이 본문은 merge(409d72e, 2026-11-05) 뒤 최종 변경에 맞게 다시 썼다. 이전 본문의 "검증" 칸은 7c7ef32 기준이었고, 고른 게이트 목록만 돌린 결과였다.
무엇을, 왜
리뷰 세 건에서 찾은 문제를 고친다.
2026-11-01 UI 디자인 감사와 2026-11-01 성숙도 리뷰
이 PR의 첫 범위다.
"결정 필요" 24건은 2026-11-03에 정해 같이 반영했다.
V3 실행기가 짝 백엔드 Envelope를 읽게 한 변경
지난 본문에서 "고치지 않은 High"로 적은 것이다.
7db32e1에서 고쳤고 e40684b로 합쳤다.
V2 HTTP 클라이언트는 지웠다(048f490). 실행 경로는 V3 실행기 하나다.
2026-11-03 성숙도 리뷰
발견 색인 95건: 리뷰 88건 + 조치 중에 찾은 merge 게이트 결함 7건(11-06, 12-09, 11-07, 11-08, 11-09, 11-10, 16-09)
지난 라운드의 High 0929/03-03도 고쳤다.
9건은 일부만 고쳤다. 그중 3건은 결정을 기다린다(아래 "위험과 영향"). 나머지는 완료 기준까지 확인했다.
발견별 상태와 커밋은 docs/reviews/2026-11-03-maturity-review/README.md 14.4절에 있다.
고른 방법과 버린 대안
2026-11-03 리뷰의 결정 6건이다. 표와 이유는 리뷰 README 14.2절에 있다.
번호
고른 것
버린 것과 이유
D1 업로드
매뉴얼에 "presigned multipart는 짝 백엔드에 없다"를 적는다. 그리고 Fileserver multipart 한 번 업로드 client를 둔다(f800549)
백엔드에 presigned를 되살리기. 백엔드 소유자의 제거 결정을 뒤집는다
D2 업무 거절
operation마다 commandEffect.refusedBeforeWrite code 목록을 둔다(1e8b3d0)
백엔드 Envelope에 단계 신호 넣기. 두 repo 계약을 바꾼다. 백엔드에 넘길 일로 남겼다
D3 시각 계약
설치된 기능의 링크·목록 영역을 가리고 찍는다
기능마다 골든 다시 찍기. 기능 수만큼 골든이 늘어난다
D4 접근성 e2e
spec이 설치된 descriptor로 응답 모양을 정하고, 경고 상자가 없다고 단언한다
기능마다 spec 고치기. 생성할 때마다 템플릿 spec을 손봐야 한다
D5 CHANGELOG
동기화 단위로 순 변경을 요약한다
커밋마다 누적 기록. 다운스트림 둘은 범위 단위로 동기화한다
D6 짝 계약 기준점
pin 파일과 백엔드 답 표 JSON을 두고 단위 테스트로 대조한다(ba2b4f4). 지금 pin은 45d2a478이다
문서에 결정일만 적기. 리뷰 중 실제로 일어난 어긋남을 못 잡는다
조치 중에 정한 것:
dev server의 contract set (16-09)
고른 것: create:feature와 기능 제거 드릴이 커밋된 public/release-manifest.json을 다시 쓴다(799ab7f).
버린 것: dev 전용 미들웨어(c15345c). capability e2e가 60번 중 7번 떨어졌다. 다시 쓰기 방식은 60번 중 0번이다.
WebKit preload 경고 (11-09)
고른 것: 테스트가 WebKit의 그 경고 문장만 정확히 무시한다. 대신 미리 받은 build script가 테스트 끝까지 실제로 실행됐는지를 세 브라우저에서 같은 방법으로 검사한다(aad005c). 제품 코드는 그대로다.
버린 것: lazy 라우트의 의존 청크 preload 끄기. 테스트에 맞추려고 모든 사용자의 첫 라우트 진입을 1~2 RTT 늦춘다.
검사가 약해지지 않았다는 근거: 정말 안 쓰는 modulepreload를 하나 넣으면, 고치기 전에는 세 엔진 모두 통과했다. 고친 뒤에는 세 엔진 모두 실패한다.
Firefox 다운로드 시간 초과 (11-10)
원인: 테스트가 그리는 중인 앱 뒤에 버튼을 붙인다. 앱 내용이 클릭 도중 12 px 길어져 클릭이 버튼에 닿지 않았다.
고른 것: 테스트가 붙이는 버튼을 앱 위 고정 층에 둔다(ee37dd8).
버린 것: 재시도, 시간 상한 늘리기. 원인을 가린다.
위험과 영향
호환을 깨는 변경 13건
커밋 제목에 !가 붙어 있다.
옮기는 법은 CHANGELOG.md 미출시 절 "먼저 할 일"에 있다.
큰 것:
V2 HTTP 클라이언트 삭제(048f490)
기능을 선언과 실행부로 나눔(298201f)
V2 API 행 삭제(12f3bb7)
예제 화면을 끌 수 있는 기능으로 옮김(b96d61d)
계약 변경 64행
CHANGELOG.md 미출시 절의 [계약] 행이다.
다운스트림(tech-log, memento)은 이 PR을 머지한 뒤 옮겨야 한다. 옮기는 작업은 하지 않았다.
결정을 기다리는 3건
13-03: 운영 의존성 high advisory 2건(zod, react-router)
zod 4.6.x는 초기 JS를 약 7 KB 늘려 예산을 넘는다.
두 갱신 모두 dependency-change-evidence.json에 owner가 아닌 reviewer가 필요하다.
09-04: 플랫폼 구성 화면(EXAMPLES_PLATFORM)을 끌 수 없다. 기능으로 옮기면 lab 측정이 443 ms로 실패한다.
03-07: 백엔드 생성기에 목록 GET이 없다. 백엔드 쪽 결정이다.
백엔드에 넘길 것
POST /v1/files가 Idempotency-Key를 읽지 않는다. 결과 불명 뒤 다시 보내면 파일이 둘 생길 수 있다.
생성기 목록 GET이 없다.
realm에 public client가 없다.
Redis 세션 모드에 로그인 엔드포인트가 없다.
Envelope에 단계 신호가 없다(D2의 버린 안).
초기 JS 여유가 1,825 B다(202,975 / 204,800 B, 파일 26 / 32). --with-create 기능 하나(약 +964 B)를 넣으면 약 860 B가 남는다.
test:feature-scaffold가 길다. FE-GATE-020은 desktop에서 1,151초 걸렸다. 이 job의 상한은 45분이다.
실제 Gitea runner의 샌드박스 조건은 모른다. desktop의 ssh 셸에서는 bwrap이 network namespace를 못 만들어 test:system의 provider 샌드박스 테스트 18건이 돌지 못했다(아래 "검증"). 러너 컨테이너가 user namespace를 막으면 FE-GATE-013이 같은 이유로 실패한다.
이 repo 밖이라 확인하지 못한 것
실제 Gitea runner
nginx
Keycloak
Redis
실제 짝 백엔드 연동
PR 크기
커밋 361개(merge 커밋 13개 포함)
파일 779개, +60,405 / −13,966줄
규칙 5.1절 상한을 크게 넘는다. 리뷰 라운드를 한 브랜치에 쌓아서다.
커밋은 논리적 변경 하나씩이다. 2026-11-03 리뷰 조치는 영역별 merge 커밋(0a00a5d~01b9def) 단위로 보면 된다.
검증
8a44226에서 merge 단계 게이트 14개를 corepack pnpm ci:gate FE-GATE-NNN으로 하나씩 돌렸다.
어디서: desktop(12코어, 31 GB), .claude/worktrees가 없는 checkout
env: workflow와 같은 CI=true, VITE_COMMIT_SHA(40자리), VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE(형식만 맞춘 가짜 digest). SOURCE_DATE_EPOCH는 ci:gate가 HEAD에서 만든다.
게이트
결과
FE-GATE-001007, 009012
모두 한 번에 통과
FE-GATE-008
통과. e2e 202건 통과(3건 skip), capability 66, storybook 1, visual 6. 고친 뒤 GATES=008만 3번 연속 통과(V3 세션)
FE-GATE-020
통과. 참조 기능·생성 기능·레시피 제거 드릴과 feature scaffold
FE-GATE-013
test:system 114건 중 96건 통과, 18건 실패. 18건 모두 bwrap이 loopback을 만들지 못한 환경 실패(RTM_NEWADDR: Operation not permitted)다. 013의 나머지 명령 7개(verify:reproducible-build, build:release-candidate, verify:local-evidence, supply-chain fixture 둘, security fixture, check:browser-security)는 같은 env로 따로 돌려 모두 통과했다
FE-GATE-013의 18건은 노트북 깨끗한 clone c7c7887(같은 env)에서 통과했다. 그 뒤 test:system 범위(scripts/, tests/system/, config/)에서 바뀐 파일은 scripts/lib/build-environment.ts와 scripts/create-feature.ts 둘이다. 8a44226에서 이 18건은 돌리지 않았다.
실행하지 않은 것:
실제 Gitea runner(러너 이미지 digest는 가짜)
8a44226에서 bwrap 샌드박스가 필요한 test:system 18건
nginx, Keycloak, Redis, 실제 짝 백엔드 연동
고친 뒤 매뉴얼만 보고 기능을 추가하는 재실험(X2). 막힘 7건이 고쳐졌는지는 각 커밋의 테스트와 생성 기능을 넣은 clone으로 확인했다
리뷰어가 볼 곳
호환을 깨는 변경:git log --oneline main..HEAD | grep '!:'로 13건을 볼 수 있다.
HTTP 쓰기 경로
V3 Envelope 판정: 7db32e1, 5d0f845
쓰기 전 거절: 1e8b3d0, 3fba68b
Fileserver 업로드: f800549, 20a5b08
짝 계약 기준점:config/contracts/backend-contract-pin.json — ba2b4f4, 5379c80
CI env에서만 나던 merge 게이트 실패
11-07: af312de
11-08: b693600
16-09: 799ab7f
브라우저 테스트 판정: 11-09 aad005c(tests/support/browser/preload-use.ts), 11-10 ee37dd8
기능 실행부 분리와 초기 JS:298201f, 1b8cb12, f887817
조치 브랜치 통합 기록: merge 커밋 12개(0a00a5d~01b9def). 합칠 때 생긴 것은 리뷰 README 14.3절에 있다.
> 이 본문은 merge(`409d72e`, 2026-11-05) 뒤 최종 변경에 맞게 다시 썼다. 이전 본문의 "검증" 칸은 `7c7ef32` 기준이었고, 고른 게이트 목록만 돌린 결과였다.
## 무엇을, 왜
리뷰 세 건에서 찾은 문제를 고친다.
- **2026-11-01 UI 디자인 감사와 2026-11-01 성숙도 리뷰**
- 이 PR의 첫 범위다.
- "결정 필요" 24건은 2026-11-03에 정해 같이 반영했다.
- **V3 실행기가 짝 백엔드 Envelope를 읽게 한 변경**
- 지난 본문에서 "고치지 않은 High"로 적은 것이다.
- `7db32e1`에서 고쳤고 `e40684b`로 합쳤다.
- V2 HTTP 클라이언트는 지웠다(`048f490`). 실행 경로는 V3 실행기 하나다.
- **2026-11-03 성숙도 리뷰**
- 발견 색인 95건: 리뷰 88건 + 조치 중에 찾은 merge 게이트 결함 7건(11-06, 12-09, 11-07, 11-08, 11-09, 11-10, 16-09)
- 지난 라운드의 High `0929/03-03`도 고쳤다.
- 9건은 일부만 고쳤다. 그중 3건은 결정을 기다린다(아래 "위험과 영향"). 나머지는 완료 기준까지 확인했다.
발견별 상태와 커밋은 `docs/reviews/2026-11-03-maturity-review/README.md` 14.4절에 있다.
## 고른 방법과 버린 대안
2026-11-03 리뷰의 결정 6건이다. 표와 이유는 리뷰 README 14.2절에 있다.
| 번호 | 고른 것 | 버린 것과 이유 |
|---|---|---|
| D1 업로드 | 매뉴얼에 "presigned multipart는 짝 백엔드에 없다"를 적는다. 그리고 Fileserver multipart 한 번 업로드 client를 둔다(`f800549`) | 백엔드에 presigned를 되살리기. 백엔드 소유자의 제거 결정을 뒤집는다 |
| D2 업무 거절 | operation마다 `commandEffect.refusedBeforeWrite` code 목록을 둔다(`1e8b3d0`) | 백엔드 Envelope에 단계 신호 넣기. 두 repo 계약을 바꾼다. 백엔드에 넘길 일로 남겼다 |
| D3 시각 계약 | 설치된 기능의 링크·목록 영역을 가리고 찍는다 | 기능마다 골든 다시 찍기. 기능 수만큼 골든이 늘어난다 |
| D4 접근성 e2e | spec이 설치된 descriptor로 응답 모양을 정하고, 경고 상자가 없다고 단언한다 | 기능마다 spec 고치기. 생성할 때마다 템플릿 spec을 손봐야 한다 |
| D5 CHANGELOG | 동기화 단위로 순 변경을 요약한다 | 커밋마다 누적 기록. 다운스트림 둘은 범위 단위로 동기화한다 |
| D6 짝 계약 기준점 | pin 파일과 백엔드 답 표 JSON을 두고 단위 테스트로 대조한다(`ba2b4f4`). 지금 pin은 `45d2a478`이다 | 문서에 결정일만 적기. 리뷰 중 실제로 일어난 어긋남을 못 잡는다 |
조치 중에 정한 것:
- **dev server의 contract set (16-09)**
- 고른 것: `create:feature`와 기능 제거 드릴이 커밋된 `public/release-manifest.json`을 다시 쓴다(`799ab7f`).
- 버린 것: dev 전용 미들웨어(`c15345c`). capability e2e가 60번 중 7번 떨어졌다. 다시 쓰기 방식은 60번 중 0번이다.
- **WebKit preload 경고 (11-09)**
- 고른 것: 테스트가 WebKit의 그 경고 문장만 정확히 무시한다. 대신 미리 받은 build script가 테스트 끝까지 실제로 실행됐는지를 세 브라우저에서 같은 방법으로 검사한다(`aad005c`). 제품 코드는 그대로다.
- 버린 것: lazy 라우트의 의존 청크 preload 끄기. 테스트에 맞추려고 모든 사용자의 첫 라우트 진입을 1~2 RTT 늦춘다.
- 검사가 약해지지 않았다는 근거: 정말 안 쓰는 modulepreload를 하나 넣으면, 고치기 전에는 세 엔진 모두 통과했다. 고친 뒤에는 세 엔진 모두 실패한다.
- **Firefox 다운로드 시간 초과 (11-10)**
- 원인: 테스트가 그리는 중인 앱 뒤에 버튼을 붙인다. 앱 내용이 클릭 도중 12 px 길어져 클릭이 버튼에 닿지 않았다.
- 고른 것: 테스트가 붙이는 버튼을 앱 위 고정 층에 둔다(`ee37dd8`).
- 버린 것: 재시도, 시간 상한 늘리기. 원인을 가린다.
## 위험과 영향
- **호환을 깨는 변경 13건**
- 커밋 제목에 `!`가 붙어 있다.
- 옮기는 법은 `CHANGELOG.md` 미출시 절 "먼저 할 일"에 있다.
- 큰 것:
- V2 HTTP 클라이언트 삭제(`048f490`)
- 기능을 선언과 실행부로 나눔(`298201f`)
- V2 API 행 삭제(`12f3bb7`)
- 예제 화면을 끌 수 있는 기능으로 옮김(`b96d61d`)
- **계약 변경 64행**
- `CHANGELOG.md` 미출시 절의 [계약] 행이다.
- 다운스트림(tech-log, memento)은 이 PR을 머지한 뒤 옮겨야 한다. 옮기는 작업은 하지 않았다.
- **결정을 기다리는 3건**
- 13-03: 운영 의존성 high advisory 2건(zod, react-router)
- zod 4.6.x는 초기 JS를 약 7 KB 늘려 예산을 넘는다.
- 두 갱신 모두 `dependency-change-evidence.json`에 owner가 아닌 reviewer가 필요하다.
- 09-04: 플랫폼 구성 화면(`EXAMPLES_PLATFORM`)을 끌 수 없다. 기능으로 옮기면 lab 측정이 443 ms로 실패한다.
- 03-07: 백엔드 생성기에 목록 GET이 없다. 백엔드 쪽 결정이다.
- **백엔드에 넘길 것**
- `POST /v1/files`가 `Idempotency-Key`를 읽지 않는다. 결과 불명 뒤 다시 보내면 파일이 둘 생길 수 있다.
- 생성기 목록 GET이 없다.
- realm에 public client가 없다.
- Redis 세션 모드에 로그인 엔드포인트가 없다.
- Envelope에 단계 신호가 없다(D2의 버린 안).
- **초기 JS 여유가 1,825 B다**(202,975 / 204,800 B, 파일 26 / 32). `--with-create` 기능 하나(약 +964 B)를 넣으면 약 860 B가 남는다.
- **`test:feature-scaffold`가 길다.** FE-GATE-020은 desktop에서 1,151초 걸렸다. 이 job의 상한은 45분이다.
- **실제 Gitea runner의 샌드박스 조건은 모른다.** desktop의 ssh 셸에서는 bwrap이 network namespace를 못 만들어 `test:system`의 provider 샌드박스 테스트 18건이 돌지 못했다(아래 "검증"). 러너 컨테이너가 user namespace를 막으면 FE-GATE-013이 같은 이유로 실패한다.
- **이 repo 밖이라 확인하지 못한 것**
- 실제 Gitea runner
- nginx
- Keycloak
- Redis
- 실제 짝 백엔드 연동
- **PR 크기**
- 커밋 361개(merge 커밋 13개 포함)
- 파일 779개, +60,405 / −13,966줄
- 규칙 5.1절 상한을 크게 넘는다. 리뷰 라운드를 한 브랜치에 쌓아서다.
- 커밋은 논리적 변경 하나씩이다. 2026-11-03 리뷰 조치는 영역별 merge 커밋(`0a00a5d`~`01b9def`) 단위로 보면 된다.
## 검증
`8a44226`에서 merge 단계 게이트 14개를 `corepack pnpm ci:gate FE-GATE-NNN`으로 하나씩 돌렸다.
- 어디서: desktop(12코어, 31 GB), `.claude/worktrees`가 없는 checkout
- env: workflow와 같은 `CI=true`, `VITE_COMMIT_SHA`(40자리), `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`(형식만 맞춘 가짜 digest). `SOURCE_DATE_EPOCH`는 `ci:gate`가 HEAD에서 만든다.
| 게이트 | 결과 |
|---|---|
| FE-GATE-001~007, 009~012 | 모두 한 번에 통과 |
| FE-GATE-008 | 통과. e2e 202건 통과(3건 skip), capability 66, storybook 1, visual 6. 고친 뒤 `GATES=008`만 3번 연속 통과(V3 세션) |
| FE-GATE-020 | 통과. 참조 기능·생성 기능·레시피 제거 드릴과 feature scaffold |
| FE-GATE-013 | `test:system` 114건 중 96건 통과, 18건 실패. 18건 모두 bwrap이 loopback을 만들지 못한 환경 실패(`RTM_NEWADDR: Operation not permitted`)다. 013의 나머지 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, supply-chain fixture 둘, security fixture, `check:browser-security`)는 같은 env로 따로 돌려 모두 통과했다 |
FE-GATE-013의 18건은 노트북 깨끗한 clone `c7c7887`(같은 env)에서 통과했다. 그 뒤 `test:system` 범위(`scripts/`, `tests/system/`, `config/`)에서 바뀐 파일은 `scripts/lib/build-environment.ts`와 `scripts/create-feature.ts` 둘이다. **`8a44226`에서 이 18건은 돌리지 않았다.**
**실행하지 않은 것:**
- 실제 Gitea runner(러너 이미지 digest는 가짜)
- `8a44226`에서 bwrap 샌드박스가 필요한 `test:system` 18건
- nginx, Keycloak, Redis, 실제 짝 백엔드 연동
- 고친 뒤 매뉴얼만 보고 기능을 추가하는 재실험(X2). 막힘 7건이 고쳐졌는지는 각 커밋의 테스트와 생성 기능을 넣은 clone으로 확인했다
## 리뷰어가 볼 곳
- **호환을 깨는 변경:** `git log --oneline main..HEAD | grep '!:'`로 13건을 볼 수 있다.
- **HTTP 쓰기 경로**
- V3 Envelope 판정: `7db32e1`, `5d0f845`
- 쓰기 전 거절: `1e8b3d0`, `3fba68b`
- Fileserver 업로드: `f800549`, `20a5b08`
- **짝 계약 기준점:** `config/contracts/backend-contract-pin.json` — `ba2b4f4`, `5379c80`
- **CI env에서만 나던 merge 게이트 실패**
- 11-07: `af312de`
- 11-08: `b693600`
- 16-09: `799ab7f`
- **브라우저 테스트 판정:** 11-09 `aad005c`(`tests/support/browser/preload-use.ts`), 11-10 `ee37dd8`
- **기능 실행부 분리와 초기 JS:** `298201f`, `1b8cb12`, `f887817`
- **조치 브랜치 통합 기록:** merge 커밋 12개(`0a00a5d`~`01b9def`). 합칠 때 생긴 것은 리뷰 README 14.3절에 있다.
## 관련
- `docs/reviews/2026-11-03-maturity-review/README.md`
- 13절: 리뷰 뒤 추가 발견
- 14절: 조치, 결정, 발견별 상태, 검증, 매뉴얼 재실험, 남은 문제
- `docs/reviews/2026-11-01-maturity-review/README.md` 13·14절
- `docs/reviews/2026-11-01-ui-design-audit.md`
- `CHANGELOG.md` 미출시 절
- `docs/manual/README.md`
- 짝 백엔드: `clean-architecture-backend-template` `45d2a478`(pin)
impeccable이 읽을 제품 정보(사용자, 목적, 제약, 원칙)가 없었다.
화면 품질을 실제 브라우저에서 잰 기록도 없었다.
PRODUCT.md에는 사용자 답으로 확인한 제품 사실만 적었다. 감사 문서는
6개 화면을 라이트·다크, 1280·375·320 폭에서 잰 발견 8건(UI-01~08)을
가이드 36.3 양식으로 적었다. DESIGN.md는 만들지 않았다. 토큰 값을
문서 머리에 복사하는 형식이라 tokens/*.css와 갈라진 복사본이 생긴다.
위험: 문서만 추가한다. 동작 변경은 없다.
검증: verify:documentation PASS_SCOPED.
라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로
WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져
그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다.
라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가
4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스
토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다.
안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다.
위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신).
검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고,
바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다
(tests/unit/oklch-contrast.test.ts).
라이트 테마에서 현재 메뉴 배경이 파랑이 아니라 분홍으로 그려졌다.
color-mix(in oklch, action 14%, panel)에서 panel이 oklch(1 0 0)으로
색상각 0을 명시해, 보간된 색상각이 255에서 345로 끌려갔다.
15곳의 혼합을 모두 in oklab으로 바꿨다. oklab에는 보간할 색상각이
없다. 흰색을 oklch(1 0 none)으로 바꾸는 방법은 버렸다. 앞으로 생길
무채색 토큰마다 같은 규칙을 기억해야 하기 때문이다.
check:design-system이 oklch·lch·hsl·hwb 혼합을 실패로 처리한다.
위험: 섞인 색이 미세하게 달라진다. 시각 골든을 갱신했다.
검증: 바꾸기 전 검사가 15곳을 보고했고, 바꾼 뒤 통과했다.
계약에 있는 컴포넌트 토큰 4개를 읽는 스타일이 없었다. 기본 버튼은
bg-action을 직접 썼고, 현재 메뉴는 --navigation-active-background의
계산식을 다시 적었다. 그래서 서비스가 이 토큰으로 브랜드를 바꿔도
화면이 바뀌지 않았다.
기본 버튼과 현재 메뉴가 토큰을 읽게 했다. 변형 버튼은 뒤에 오는 같은
우선순위 규칙이라 그대로 덮어쓴다. check:design-system이 계약의
컴포넌트 토큰을 읽는 스타일이 하나도 없으면 실패한다.
위험: 기본 버튼 배경 지정 방식이 utility에서 토큰으로 바뀐다.
보이는 색은 같다.
검증: 바꾸기 전 검사가 토큰 4개를 보고했고, 바꾼 뒤 통과했다.
max-width 8.5rem과 7rem 때문에 모든 언어에서 선택값이 잘렸다
("Light then", "Englisl", "라이트 테ㅁ"). 커밋된 시각 골든에도 잘린
머리글이 들어 있어, 시각 테스트가 결함을 정답으로 지키고 있었다.
고정 폭을 지웠다. 좁은 화면은 기존 메뉴 서랍 배치가 그대로 맡는다.
새 i18n e2e 테스트가 ko-KR, en-US, en-XA에서 선택 상자 폭을 브라우저가
옵션에 필요한 폭과 비교한다.
위험: 중간 폭에서 머리글이 넓어진다. responsive·app-shell·theme·compact
테스트가 통과했다.
검증: 새 테스트가 고치기 전 실패했고, 고친 뒤 chromium·firefox·webkit
모두 통과했다.
토큰이 Inter로 시작했지만 Inter를 불러오는 코드가 없었다. Inter가
없는 기기는 자기 글꼴로 그렸고, Inter에는 한글이 없어 한국어는 처음부터
Inter로 그려지지 않았다.
토큰을 시스템 UI 글꼴과 플랫폼별 한국어 글꼴 목록으로 바꿨다(사용자
결정). 한글 웹폰트 배포는 버렸다. 전송량과 글꼴 파일 관리가 생기고,
중립 템플릿에서는 서비스가 브랜드 글꼴로 바꾸면 되기 때문이다.
check:design-system이 첫 글꼴이 기본 키워드도 아니고 @font-face로 싣지도
않으면 실패한다.
위험: OS마다 글꼴 모양이 다르다. 시각 테스트 실행 환경의 글꼴 고정은
아직 남았다(UI-05 후반).
검증: 바꾸기 전 검사가 Inter를 보고했고, 바꾼 뒤 통과했다.
예제 화면 4곳이 제목 위에 같은 "예제" 라벨을 달았다. 이미 예제 메뉴
묶음 안에 있는 화면이라 정보가 없고, 예제를 복사하면 이 구성도 따라간다.
예제 화면의 eyebrow만 지웠다. PageHeader의 eyebrow 속성은 남겼다.
접근 상태 화면과 홈은 의미 있는 라벨을 쓴다. 검사는 넣지 않았다.
지울 수 있는 예제 화면의 문구라 검사 비용이 더 크다.
위험: 없음. 예제 화면은 i18n 검사 대상이 아니다.
검증: lint, check:types:app 통과. 시각 골든에 반영했다.
표를 감싼 스크롤 영역이 키보드 포커스(tabIndex 0)를 받지만 역할과
이름이 없었다. 스크린 리더가 이름 없는 정지점으로 읽었다.
영역에 role="region"을 주고 caption을 aria-labelledby로 연결했다.
위험: 없음. 시각 변화가 없다.
검증: 이름 있는 region을 요구하는 컴포넌트 테스트가 고치기 전 실패했고,
고친 뒤 통과했다(design-system-platform.test.tsx 10/10).
감사 문서에 발견마다 어떻게 닫았는지가 없었다.
조치 결과 표를 추가했다. 넣은 검사, 커밋, UI-03 범위 확대(읽히지 않던
컴포넌트 토큰 4개), UI-05의 남은 절반(시각 테스트 글꼴 고정),
UI-07 재판정(정상 구성과 데모 틀이라 조치 안 함)을 적었다.
위험: 문서만 바뀐다.
검증: 표의 커밋 ID와 검사 이름을 브랜치 기록과 대조했다.
예전 앱 셸 골든에는 잘린 선택 상자(UI-04)와 분홍 현재 메뉴(UI-02)가
들어 있었다.
test:visual:update로 5장을 다시 찍고 눈으로 확인했다. 선택값이 다
보이고, 현재 메뉴가 파랗고, 예제 머리글의 반복 라벨이 없다.
위험: 이 Linux 호스트의 글꼴로 찍었다. 시각 테스트 실행 환경의 글꼴
고정은 UI-05의 남은 절반이다.
검증: test:visual 5건 통과.
지난 리뷰(09-29) 뒤로 무엇이 고쳐졌고 무엇이 남았는지, 그리고 이번에
사용자가 요구한 성능 실측·폴더 구조·리팩토링·기능 개발 패턴을 확인한
기록이 없었다.
지난 14개 영역에 15(성능 실측)와 16(폴더 구조·기능 개발 패턴)을 더해
영역 에이전트 16개가 병렬로 리뷰했다. README에는 사용 결정, 차단 항목,
28개 관점 판정, 결정이 필요한 것, 개선 순서, 발견 색인을 모았다.
High 4건과 P1 일부(11-01)는 오케스트레이터가 코드에서 다시 확인했다.
위험: 문서만 추가한다. 영역 문서의 기준 커밋 d99301b는 메시지를 다시
쓴 c0c5d9c와 트리가 같다(README 9절).
검증: verify:documentation PASS_SCOPED. 발견 색인은 영역 문서에서
스크립트로 뽑았다(95건, 새 발견 90건).
PRODUCT.md가 "예제 기능과 라우트는 지울 수 있고, 예제 화면에만 있는
디자인은 남지 않는다"고 적었다. 실제 제거 드릴(test:sample-removal)은
참조 기능만 지운다. 예제 라우트 4개와 홈은 기본 구성이라 남는다. 이
주장을 믿고 예제 화면에 디자인을 넣으면 제품 빌드에 그대로 남는다.
PRODUCT.md를 드릴 범위대로 고쳤다. 접근성 수동 검토의 근거를 지워도
되는 SPEC.md에서 docs/accessibility/manual-checklist.md로 바꿨다.
README의 "복사 뒤 지워도 되는 파일" 표에 PRODUCT.md를 CLAUDE.md처럼
"제품 것으로 바꾼다"로 넣었다. 예제 화면을 지울 수 있게 만드는 일은
별도 선택이라 하지 않았다(0929/14-03).
위험: 문서만 바뀐다.
검증: deletable-history-documents 테스트 통과, verify:documentation
PASS_SCOPED.
문제: SW를 ACTIVE로 켜면 build-frontend 6단계의 SW Vite 빌드가 Vite
기본값대로 public/을 dist에 다시 복사한다. 4단계가 프로필로 만든
dist/config.json이 public/config.json(local, demo 인증,
http://localhost:8080/, 루트 release manifest)으로 덮어써진다. 빌드와
verify-release는 통과하고 release admission만 거절한다. 그래서 SW를 켠
제품은 local이 아닌 릴리스를 만들 수 없다. VITE_ROUTER_BASE_PATH를
쓰면 RELEASE_MANIFEST_URL도 base를 잃는다.
고른 방법: vite.service-worker.config.ts에 publicDir: false를 넣는다.
dist에는 3단계 앱 빌드가 이미 public/을 복사해 두었고, 워커 번들은
public/ 파일을 쓰지 않는다. 같은 repo의 다른 두 번째 Vite 빌드
(scripts/lib/optional-recipe-bundle.ts)도 같은 설정이다.
build-frontend.ts 6단계 주석에 이 조건을 한 줄 적었다.
버린 대안:
- build.copyPublicDir: false. 복사만 끄고 public 디렉터리는 계속
설정에 남는다. 워커 빌드는 public/을 쓸 일이 없어 publicDir: false가
의도를 바로 말한다.
- 앱 빌드 plugin의 closeBundle에서 워커를 만들기, 또는 Vite build()를
configFile: false로 부르는 스크립트. 둘 다 리뷰 5.2절의 대안이다.
two-pass 구조를 바꾸거나 파일이 늘어 이 결함에 비해 범위가 크다.
테스트: tests/unit/service-worker-build-output.test.ts는 임시 복사본에서
SW ACTIVE + APP_PROFILE=production + VITE_ROUTER_BASE_PATH=/app/로 실제
build-frontend.ts를 돌린다. 그리고 dist/config.json이
generateRuntimeConfig("production", env) 결과와 같은지 본다(리뷰의 완료
기준). 설정 객체에서 publicDir === false를 보는 테스트는 수정을 다시
적을 뿐이고, 설정이 5단계 생성물 없이는 로드되지 않아 버렸다. 빌드
1회가 약 2초라 unit 계층에 둔다(build-environment-bundle.test.ts와 같은
방식, docs/testing/taxonomy.md의 짧은 child process 규칙). 복사와 빌드는
e2e 도우미 prepareFixtureBuilds를 재사용하고, 빌드별 env 옵션만
추가했다(기존 호출은 그대로). 이 테스트로 0925/06-10(SW Vite 설정의
dist/config.json 읽기 테스트 없음)도 닫힌다.
위험·한계: 하위 경로에서 사전 캐시 URL이 base를 잃는 문제(0929/06-02)와
워커의 runtime config URL 기본값은 그대로다. 이 테스트는 /app/ 빌드의
설정 문서만 보고 워커 설치는 보지 않는다. Vite 8.1.5 동작 기준이다.
check:architecture는 pnpm 스크립트로만 돌아서 실행하지 않았다(src는
바꾸지 않았다).
검증:
- RED(수정 전): 새 테스트 실패. APP_ENV local(기대 production),
AUTH_MODE demo(기대 external), API_BASE_URL http://localhost:8080/,
RELEASE_MANIFEST_URL /release-manifest.json(기대 /app/...)
- GREEN: 새 테스트 통과(1.9초)
- 수정 전후 production + /app/ 빌드 비교: dist 파일 34개로 같음. 수정 후
RELEASE_TARGET=production check-release-admission ADMITTED, 수정 전 rc 1
- node scripts/run-vitest.ts run tests/unit(pnpm을 띄우는 2파일 제외):
164파일 2343건 통과
- tsc tsconfig.test.json, tsconfig.node.json 통과. 바꾼 4파일 eslint 통과
Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2절, 13-build-release-supply-chain.md 실험 E-B
문제: cgroup 테스트("applies effective aggregate cgroup limits ...")는
`await execution.completion` 뒤에 `showProcessArguments(child.pid)`로
supervisor의 argv를 다시 조회한다. completion은 child의 `close`에서
풀리고, 그때 Node는 이미 child를 회수했다. `/proc/<pid>/cmdline`도
`ps -p`도 실패해서 이 테스트는 부하와 관계없이 항상
`ps failed: `로 끝난다. 바로 위 주석은 "아래는 실행 기록을 읽는다"고
적어서 코드와 반대로 말했다. 완료 전의 live 조회(`:793`)도 provider가
1.5초 뒤 끝나므로 부하가 있으면 같은 이유로 실패할 수 있다.
고른 방법: 이미 있는 샘플러 `recordProviderProcessTree`가 5ms마다
supervisor 자신의 argv도 읽어서, 서로 다른 값을 모두 기록한다.
완료 전 live 조회와 완료 후 조회를 이 기록으로 바꿨다. 단언은 줄이지
않았다.
- supervisor argv에 command와 credential이 없다(`:793`의 정규식 그대로).
- 기록에 `run-and-validate-provider.ts`가 있다. 기록이 비어서 위
단언이 공짜로 통과하는 경우를 막는다.
- 실행 중 `process.title`로 argv를 바꿔도 값마다 남기므로, 순간 한
번을 본 live 조회보다 넓게 본다.
버린 대안:
- 완료 후 조회 줄을 지운다: supervisor argv 검사가 사라진다.
- 완료 전 스냅샷을 한 번 더 찍는다: `:793`과 같은 방식이라 부하에서
provider 종료와 경쟁한다.
- `ps` 실패를 무시한다: 결함을 숨기고 검사가 공짜로 통과한다.
위험·한계: 샘플링 간격(5ms)보다 짧게 바뀌었다 돌아오는 argv는 놓칠 수
있다. 다른 프로세스 기록과 같은 한계다. 이 테스트는 base fixture가
`corepack pnpm build:release-candidate`를 부르므로 worktree에서
실행하지 않았다. `-t 'aggregate cgroup'` 반복 실행과 `test:system` 전체
통과는 메인 checkout에서 확인해야 한다.
검증:
- RED: 게이트 로그 test_system.log(d99301b, 메인 checkout 실행)에서 이
테스트가 `Error: ps failed: `로 `:810:7`에서 실패. 2 failed /
110 passed. d99301b..402e1db 사이 scripts·tests/system 변경 없음.
- 메커니즘: 테스트 파일에서 `readProcessArguments`·`showProcessArguments`·
`recordProviderProcessTree` 원문을 잘라 타입만 지우고, 수명이 짧은
child에 돌렸다(scratchpad/fix-11-01/recorder-check.mjs).
- 수정 전 20회: close 뒤 조회 실패 20, supervisor argv 기록 0,
실행 중 title 유출 기록 0
- 수정 후 20회(loadavg 1.6): 조회 실패 20, 기록 20, 유출 기록 20
- 수정 후 30회, busy loop 20개(loadavg 17.9): 기록 30, 유출 기록 30
- `npx tsc --project tsconfig.test.json --noEmit`, `tsconfig.node.json`
통과. `npx eslint tests/system/ci-runner/ci-artifact-contract.test.ts`
통과.
Fixes: 5cc41467ae ("refactor: 프론트 템플릿 리펙토링")
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-01
문제: 13-04(839205c)가 `verify-exact-promotion-bundle.ts`에
`--archived` 모드를 넣으면서 성공 출력이
`Exact promotion bundle verification (<freshness>): PASS`로 바뀌었다.
"passes the downstream CLI for a real finalized exact-five" 테스트는
옛 문구 `Exact promotion bundle verification: PASS`를 기대해서 항상
실패하고, FE-GATE-013(`test:system`)이 코드와 무관하게 빨갛다.
고른 방법: 기대 문구를 `... (current): PASS` 전체로 바꿨다. 이 테스트는
`--archived` 없이 CLI를 부른다. `(current)`는 "기본 모드는 지금 시각
기준으로 freshness를 판정한다"는 주장의 일부다. repo에서 CLI의 기본
모드를 확인하는 테스트는 이것 하나다.
버린 대안: `/verification .*: PASS/`처럼 PASS만 본다. 문구 변경에는
강하지만 기본 모드가 `archived`(기록된 승격 시각 기준, 더 느슨한 판정)로
바뀌어도 통과한다. 출력 문구가 다시 바뀌면 이 테스트가 같이 바뀌어야
하는 편이 낫다고 판단했다.
위험·한계: 이 테스트는 base fixture가
`corepack pnpm build:release-candidate`를 부르므로 worktree에서
실행하지 않았다. 메인 checkout의 `test:system`에서 확인해야 한다.
검증:
- RED: 게이트 로그 test_system.log(d99301b, 메인 checkout 실행)에서
`:1259:27` 실패. Expected `Exact promotion bundle verification: PASS`,
Received `Exact promotion bundle verification (current): PASS`.
d99301b..402e1db 사이 scripts·tests/system 변경 없음.
- 새 기대 문구가 그 Received 줄과 글자 그대로 같다
(`grep -F` 1건 일치).
- `npx tsc --project tsconfig.test.json --noEmit` 통과.
`npx eslint tests/system/ci-runner/ci-artifact-contract.test.ts` 통과.
Fixes: 839205c134 ("feat(release): re-verify a promoted release in archived mode (13-04)")
Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-01
조립 루트의 attachCredentials가 operation의 인증 프로필을 보지 않고
세션 상태만 본다. 그래서 auth: "none" operation(ANONYMOUS 프로필)이
로그아웃이면 UNAUTHENTICATED, 로그인이면 세션 헤더가 붙어
CREDENTIAL_HEADER_NOT_ALLOWED로 거절되고, 외부 owner가 없으면
CREDENTIAL_OWNER_UNAVAILABLE로 끝난다. 어느 상태에서도 fetch가 0회다.
scope 확인 바로 다음에 INSTALLED_REST_AUTH_PROFILES에서
operation.authProfileId의 transport를 읽고, ANONYMOUS면 세션을 보지
않고 빈 헤더로 READY를 돌려준다. executor에 넘기는 레지스트리와 같은
값을 같은 객체 안에서 읽는다. 그 밖의 프로필은 기존 경로 그대로다.
버린 대안:
- executor(http-execution-v3.ts)가 ANONYMOUS면 attachCredentials를
부르지 않게 하기. adapter 공개 동작이 바뀐다. 지금 executor는 익명
프로필에도 협력자를 부르고 헤더를 내면 거절하며, 이 동작을 고정한
계약 테스트가 있다. 세션을 아는 쪽은 조립 루트라서 판단도 거기 둔다.
- 리뷰 R1(attachCredentials를 createCredentialAttacher로 꺼내기).
구조 변경이라 이번 범위를 넘는다. 09-02에서 함께 다룬다. 새 테스트가
실제 createRuntimeAdapters를 거치므로 그때도 그대로 쓸 수 있다.
- 새 케이스를 tests/unit/runtime-adapters.test.ts에 넣기. vi.mock은
파일 단위라 설치된 계약 묶음을 바꾸면 그 파일의 기존 테스트에도
번진다. 그래서 runtime-adapters-auth-profile.test.ts를 따로 만들었다.
위험·한계:
- 로그인 상태의 익명 호출에 토큰이 붙지 않고 owner에게도 가지 않는다.
ANONYMOUS 프로필이 자격증명 헤더를 하나도 허용하지 않으니 의도한
결과다. 인증 통합이 실패한 상태에서도 공개 읽기는 나간다.
- scope fence는 익명 분기보다 먼저 본다. 모르는 프로필 id는 executor가
attachCredentials 전에 UNKNOWN_AUTH_PROFILE로 막는다.
- 브라우저 화면은 보지 않았다. test:sample-removal도 돌리지 않았다.
새 테스트는 템플릿 소유 fixture와 src/contracts의 프로필만 쓴다.
- tech-log 제품 쪽 우회는 다음 동기화 때 지운다.
검증:
- RED(수정 전): 새 테스트 11건 중 5건 실패. ANONYMOUS 4개 상태가
expected 'UNAUTHENTICATED' to be 'SUCCESS'(demo 로그아웃),
expected 'AUTH_INTEGRATION_FAILURE' to be 'SUCCESS'(demo 로그인,
외부 owner 로그인, owner 없음)로 실패. owner의 attachCredential이
1회 불림. 인증 필요 프로필의 UNAUTHENTICATED, CREDENTIAL_OWNER_
UNAVAILABLE 2건, fence 중 ABORTED_BY_SCOPE, 로그인 후 bearer 전송,
익명 요청의 SCOPE_FENCED 6건은 수정 전후 모두 통과.
- GREEN: 새 테스트 11/11 통과.
- 회귀: runtime-adapters, http-execution-v3(unit·integration),
auth-recovery, legacy-http-credential-authority, tests/features,
tests/component, 영역 R1 목록 71 files / 485 tests 통과.
- tsc(tsconfig.app.json, tsconfig.test.json) 오류 0. 바꾼 두 파일
eslint 통과. check:architecture(pnpm 대신 exec 대행) 통과,
376 modules.
Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-01
문제: .ui-field__input 테두리는 계약 토큰 --field-border 대신
color-mix(in oklab, var(--color-content-muted) 55%, var(--color-panel))
를 직접 쓴다. 제품이 --field-border로 입력란 테두리를 바꿔도 화면이
그대로다. 이 식은 패널 대비 라이트 2.53:1, 다크 2.98:1이라 WCAG
1.4.11이 입력란 경계에 요구하는 3:1보다 낮다. check:design-system은
var(--field-border-invalid) 글자를 --field-border의 독자로 세어 이것을
놓쳤다(검사 수정은 다음 커밋).
고른 방법: 테두리가 var(--field-border)를 읽게 한다. 토큰값은 계약
그대로 --color-border-strong이다.
버린 대안: 토큰값을 지금 계산식으로 바꾸기. 화면은 안 바뀌지만 3:1
미달을 토큰에 굳히고, 다크 테마에서도 계약의 border-strong과 따로
노는 색이 남는다.
위험·한계: 입력란 테두리가 두 테마 모두 진해진다(화면 변경). 시각
골든은 이 커밋에서 갱신하지 않았다. 대비는 계산값이고 브라우저 실측은
하지 않았다.
검증: scripts/lib/oklch-contrast.ts로 --field-border 대비를 계산했다.
- light: panel 6.52, surface 6.24, surface-muted 5.47, elevated 6.52
- dark: panel 4.19, surface 4.54, surface-muted 3.74, elevated 3.90
- 바꾸기 전 식(oklab로 직접 섞은 값): light 2.53, dark 2.98(panel 대비)
node scripts/check-design-system.ts PASS.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01
문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다.
"var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가
0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다.
그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰
사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가
없었다(12-02).
고른 방법:
- 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다.
입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와
순서는 그대로다.
- 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야
한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙
대로 대소문자를 구분한다.
- 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe
B5 우회, B12 오탐).
- oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS
키워드는 대소문자를 구분하지 않는다.
- ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다.
버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별
검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고,
순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의
--fixture 모드와 산출물 스키마는 바꾸지 않았다.
위험·한계:
- 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로
본다. 지금 CSS에는 없다.
- 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의,
outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg,
알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지
않는다.
- 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로
"기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다.
검증:
- RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts
11개 중 5개 실패. "does not count a longer token that starts with the
same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다.
나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석
안 독자.
- 고친 검사를 앞 커밋 전 CSS(402e1db)에 돌리면 "component token
--field-border is defined but no style reads it"으로 실패했다.
- GREEN: 같은 파일 11/11 통과. tests/unit 166파일 2364개 통과.
- 변이: 대비 기준 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건
통과로 바꾸면 규칙마다 실패 테스트가 하나 이상 깨졌다(7/11 실패).
- check:design-system PASS, --fixture는 기대대로 실패. tsc(app, node,
test) 통과, 바꾼 파일 eslint 통과, verify-documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01, 12-02
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).
고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.
버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.
위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
(CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
(reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
"처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.
검증
- RED(수정 전): reference-production-vertical "keeps the key when the
resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
(IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
check:ci 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문제: SSE 어댑터는 fetch 거절과 열린 스트림의 reader 거절을 모두
OFFLINE(retryable)으로 보고한다. reconnect coordinator는 transport가
OFFLINE을 보고하면 requireOnline()으로 "새 online 이벤트"를 요구했다.
서버만 내려가거나 프록시가 연결을 끊으면 브라우저 navigator.onLine은
true 그대로라 online 이벤트가 오지 않는다. run이 재시도도 종료도 없이
RUNNING으로 멈췄다(리뷰 재현: 20분 동안 fetch 1회, 결과 없음).
고른 방법: 수정안 b. coordinator의 attempt 실패 경로와 classifyClosed
경로에서 transport OFFLINE 뒤의 requireOnline() 두 줄을 지운다. 이제
transport OFFLINE은 다른 retryable 실패처럼 backoff로 재시도하고, 시도
상한이나 elapsed 상한에 닿으면 마지막 실패로 끝난다. online 대기는
환경 신호(observeOnline(false))가 offline을 알렸을 때만 한다.
- 리뷰의 MU1은 "&& !online" 조건을 붙이는 방식이었다. 두 지점에
닿을 때 online은 항상 true다. 그 사이에 offline이 오면 wentOffline
분기가 먼저 받고, observeOnline(false)가 이미 requireOnline()을
부른다. 그래서 조건을 붙이는 것과 줄을 지우는 것은 동작이 같고,
지우는 쪽이 짧다.
- 규칙은 RealtimeReconnectEnvironment 주석과 설계 5.3절에 적었다.
버린 대안: 수정안 c(SSE가 네트워크 거절을 PROVIDER_UNAVAILABLE로
보고). SSE 한 곳의 어휘만 바뀌고 coordinator의 함정은 남는다. 조합
코드가 classifyClosed에서 OFFLINE을 돌려주거나 다른 transport가
OFFLINE을 보고하면 같은 방식으로 멈춘다. OFFLINE을 보고 화면에
"오프라인"을 띄우는 소비자의 분류도 바뀐다. b는 모든 transport가
지나는 한 곳에서 고친다. (d) online 대기에 상한 시간을 두는 방식은
상수와 상태가 늘어서 버렸다.
위험·한계:
- 환경 offline 이벤트보다 transport 실패를 먼저 보면, 첫 backoff
타이머가 잡힌다. offline 이벤트가 오면 그 sleep을 끊고 online을
기다린다(새 테스트 "after"가 고정). offline 이벤트가 타이머보다
늦게 오면 헛시도가 한두 번 생길 수 있다. 시도 상한 안이다.
- lie-fi(브라우저는 online, 실제 네트워크 없음)에서는 이제 상한까지
재시도한 뒤 OFFLINE으로 끝난다. 설계 5.3의 "budget 소진 뒤
fallback"과 같다.
- 0929/04-02(열린 SSE 세션 bridge 부재)는 그대로다. 테스트 안의
sseAttempt는 설계 6.3이 조합 코드에 맡긴 최소 bridge다.
- 설계 문서의 reconnect-coordinator.ts 줄 번호를 새 위치로 고쳤다.
- 레시피 번들(realtime): 40,886 -> 40,863 / 40,900 gzip B. 예산은
바꾸지 않았다.
검증:
- RED(수정 전): `node scripts/run-vitest.ts run
tests/unit/realtime/realtime-reconnect-coordinator.test.ts`
-> X1·X2 2건 실패 "expected "vi.fn()" to be called 3 times, but
got 1 times". 실제 offline 대기 테스트 2건(before/after)은 통과.
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/`
-> 14파일 225건 통과(기존 221 + 새 4).
- 변이: 수정 위에 MU2(SSE 거절 -> PROVIDER_UNAVAILABLE)를 넣으면 X1·X2
2건 실패.
- `node scripts/run-vitest.ts run tests/unit` -> 165파일 2357건 통과.
- `npx tsc --project tsconfig.app.json --noEmit`,
`npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 ts 2개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS.
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- `node scripts/check-optional-recipes.ts` -> PASS, realtime 40863/40900.
- 미실행: check:architecture(pnpm을 띄운다). depcruise 직접 실행은
0 modules로 끝나 의미가 없다. import는 바꾸지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 2절, 6.1절
리뷰 README에 개선 순서 1을 어떻게 닫았는지가 없었다. 11-01은 고친 뒤
다른 단언에서 간헐 실패가 드러났다.
13절에 발견별 상태, 커밋, 막는 테스트를 적었다. 11-01은 부분 충족으로
두고, 되돌린 시도 세 가지와 다음 방향(표본 대신 실행 증거 파일)을
13.1절에 남겼다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
위험: 문서만 바뀐다.
검증: verify:documentation PASS_SCOPED. cgroup 테스트 10회 중 6회 통과
(부하 약 3)를 직접 측정했다.
문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서
responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를
display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과
정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이"
조건을 어긴다.
고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상
테마 선택·세션 상태(탐색 아래)를 넣는다.
- 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect,
SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다
기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다.
- 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지
않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다).
- 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다.
그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다.
- 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에
"홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다.
- 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신
보여 준다는 주석을 달았다.
버린 대안:
- 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고
320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다.
- 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은
항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이
이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다.
- 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존
접근성 이름과 테스트가 깨진다.
위험·한계:
- 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는
한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌
dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는
strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로
좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다.
- 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을
스크롤해야 보인다.
- 좁은 화면 서랍 화면이 바뀐다. 시각 골든
app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다.
- 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은
pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와
gzipSync로 직접 쟀다.
- 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다.
검증:
- RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전
chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' })
.getByRole('combobox', { name: '색상 테마' }): element(s) not found.
- GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에
닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과
브랜드가 보인다.
- 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route
(세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의
Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는
reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다.
- 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함).
- node scripts/run-vitest.ts run tests/component: 211/211 통과.
- tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system
PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS.
- Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로
돌렸다(빌드는 node scripts/build-frontend.ts).
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01
문제: tests/system의 cgroup 테스트는 provider 실행 중 /proc을 5 ms마다
표본으로 읽어 어떤 프로세스가 어떤 argv로 돌았는지 판정한다.
systemd-run --scope는 scope로 옮긴 뒤 같은 PID에서 sh 게이트와 scope
wrapper로 exec하고, 갓 fork된 자식은 exec 전까지 부모 argv를 보인다.
표본은 PID마다 처음 본 argv만 남겨 이 짧은 단계를 자주 놓친다. 운영
코드에는 테스트가 결정적으로 읽을 실행 증거가 없다.
고른 방법: scripts/lib/provider-process-trace.ts를 추가한다.
PROVIDER_PROCESS_TRACE_PATH가 있을 때만 각 단계가 JSON 한 줄을
덧붙인다.
- 자기 기록: supervisor와 scope wrapper가 /proc/self/cmdline과
/proc/self/cgroup을 남긴다(커널이 본 값).
- 자식 기록: supervisor가 systemd-run, guardian client가 guardian,
wrapper가 bwrap을 spawn에 넘긴 argv 배열 그대로 남긴다. spawn과 기록이
같은 배열을 쓴다.
- 필드는 role, pid, ppid, argv, (자기 기록만) cgroup. 환경변수는 담지
않는다. credential과 provider 명령이 지나가는 곳이기 때문이다.
- systemd-run 환경은 허용 목록으로 다시 만들어지므로
providerProcessTraceEnvironment()로 기록 경로만 넘긴다. bwrap은
--clearenv라 sandbox 안의 provider는 경로를 받지 않는다. guardian은
빈 환경을 그대로 두고 client가 spawn 지점에서 기록한다.
테스트용 opt-in으로 두고 운영 감사 증거로 쓰지 않는다. 운영에서 켜면
argv가 두 번째로 남는 곳이 생긴다. 나중에 credential이나 provider
명령이 argv에 들어가는 회귀가 생기면, 지금은 /proc에 잠깐 보이는 값이
파일로 남아 CI 산출물이 될 수 있다. 감사 증거로 쓰려면 봉인 보고서와
같은 경로 안전·크기 상한·스키마·보존 정책이 필요하고 이번 범위가
아니다. CI 워크플로는 이 변수를 설정하지 않는다.
버린 대안:
- /proc 표본 보강(부모와 같은 argv 무시, PID별 argv 이력 보존): 리뷰
README 13.1에서 시도하고 되돌렸다. 이력 보존은 prlimit -> sh로 바뀌는
PID 이력에 provider 명령이 섞여 "인프라 argv에 명령 없음" 단언의
뜻이 바뀐다.
- spawn 직후 /proc/<pid>/cmdline 읽기: libuv는 exec 뒤에 반환하지만
systemd-run은 곧 wrapper로 다시 exec하므로 경쟁이 남는다.
- guardian 자기 기록: guardian이 빈 환경으로 뜨는 것이 보장이라 기록
경로를 넘기지 않는다.
위험·한계:
- 기록은 각 단계가 스스로 남긴다. 새 spawn 지점이 기록을 빠뜨리면
테스트에서 보이지 않는다. 모듈 주석에 적었다.
- 기록 실패는 run 결과를 바꾸지 않고 stderr에 한 줄 남긴다. wrapper의
stderr는 provider 출력으로 버려지므로 빠진 줄은 기록을 읽는 쪽에서
드러난다.
- 변수가 없으면 spawn 인자와 환경은 이전과 같다.
검증:
- node scripts/run-vitest.ts run tests/unit/provider-process-trace.test.ts
2건 통과. 자식 기록에 env 필드를 넣는 변이를 넣으면 실패한다.
- 관련 테스트 6파일 44건 통과(provider-process-trace, task3-selective-
integration, provider-output-limiter, security-provider-evidence,
provider-guardian-transaction, provider-process-group).
- pnpm 없는 하네스(운영 encoder로 systemd-run -> sh -> wrapper -> bwrap
-> prlimit -> provider 실행)에서 실행 기록 20회 중 20회 완전.
- tsc(tsconfig.node.json, tsconfig.test.json), eslint 통과.
문제: "applies effective aggregate cgroup limits ..." 테스트는
recordProviderProcessTree로 /proc을 5 ms마다 읽고 PID마다 처음 본
argv만 남긴다. systemd-run이 같은 PID에서 wrapper로 exec하고, 갓 fork된
자식이 exec 전까지 부모 argv를 보여서 "systemd-run 1개", "guardian 1개"
단언이 간헐적으로 실패한다(리뷰 README 13.1: 부하 약 3에서 10회 중
4회).
고른 방법: 표본을 지우고 앞 커밋의 실행 기록을 읽는다. 기록 파일은
workspace 밖 임시 폴더에 둔다. sandbox가 workspace를 ro-bind하므로
그 안에 두면 provider가 읽을 수 있다. 단언 대응:
- 직접 자식 systemd-run 1회: systemd-run 기록 1개, ppid가 supervisor,
argv[0]이 /usr/bin/systemd-run
- guardian 1회: guardian 기록 1개, ppid가 supervisor
- scope wrapper 1회: wrapper 기록 1개, pid가 systemd-run과 같고 cgroup이
`0::<ControlGroup>`과 정확히 같다
- sandbox 관찰: bwrap 기록 1개, ppid가 wrapper, argv에 /usr/bin/prlimit
- 인프라 argv에 명령 없음: 모든 기록 argv에 command가 없다. 추가로
providerScript 경로도 없다
- provider 1회: bwrap 실행 1회 + provider가 자기 /proc/self/cgroup에
/ca-provider-vulnerability-가 없으면 exit 8(run 실패)
- credential 없음: 기록 파일 원문과 모든 argv에 없다. stdout/stderr와
unit 메타데이터 단언은 그대로
- 종료 뒤 기록된 PID가 모두 없고 cgroup 디렉터리가 없다(그대로)
버린 대안: provider만 host 표본으로 계속 보는 혼합안. provider PID도
bwrap -> prlimit -> sh -> node로 바뀌어 같은 경쟁이 남는다.
위험·한계:
- provider의 scope 소속은 host 관찰이 아니라 provider 자신의 확인(exit
code)으로 본다. bwrap의 소속은 관찰된 wrapper cgroup에서 fork 상속으로
판단한다.
- 기록에 남지 않은 spawn은 보이지 않는다(앞 커밋 한계와 같다).
검증:
- 이 테스트는 createProviderFixture에서 corepack pnpm
build:release-candidate를 부른다. 작업 규칙상 worktree에서 pnpm을
띄우지 않으므로 실제 테스트의 RED/GREEN은 실행하지 않았다.
- 대신 pnpm 없는 하네스로 같은 실행 체인(운영 encoder, systemd-run ->
sh -> wrapper -> bwrap -> prlimit -> provider, guardian 대역 포함)을
돌렸다. 옛 표본 판정: 10회 중 4회 실패(systemd-run=0, wrapper=2).
실행 기록 판정: 20회 중 20회 통과. provider 자기 확인은 scope 안에서
통과, host에서 exit 8.
- tsc(tsconfig.test.json), eslint 통과.
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR
Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지
않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는
글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel
diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다.
고른 방법 (리뷰 4.1절 c′, 사용자 결정):
- tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리
(truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다.
playwright.visual.config.ts가 use.launchOptions.env로 그 파일을
FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI
workflow는 바꾸지 않았다.
- 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault,
autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와
sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고).
- visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를
chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고
CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다.
다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지
않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로
감싼다. test:visual:update도 같은 검사를 먼저 거친다.
버린 대안:
- fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고,
Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는
Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다.
그래서 탐침도 앱 페이지 안에 넣는다.
- document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다.
- /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와
Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다.
리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다.
- 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각.
위험·한계:
- 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면
이름 검사는 통과하고 pixel diff로 실패할 수 있다.
- generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation
Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트
(예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는
visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다.
- 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도
보인다. 탐침 4종이 바뀌면 검사가 잡는다.
- Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다.
- 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를
넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다.
- 골든은 다시 찍지 않았다.
검증 (같은 dist, flock, `npx playwright test --config
playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만
vite preview로 바꾼 로컬 사본으로 실행):
- 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu):
5 failed, toHaveScreenshot diff(46,356 px, 4%)
- 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께
latin=DejaVu Sans, korean=WenQuanYi Zen Hei
- RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run.
같은 설치 안내 + "The font probe page did not render"
- GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5)
- 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy,
sub-pixel-rgb 제외): 6 passed
- 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이
5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed
- tsc(app·node·test), eslint, check-test-evidence --source-only PASS,
verify-documentation-readiness PASS_SCOPED, vitest supply-chain과
tests/architecture 53 passed
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절
문제
guardian 테스트는 자식을 띄우자마자 절대 마감(Date.now() + 350)이 든
가드를 보낸다. 그래서 lease가 프로세스 기동 시간까지 낸다. 1코어에서
기동이 350ms를 넘으면 guardian이 가드를 마감 지남으로 거부하고, 테스트는
5초 뒤 "deadline guardian READY timed out"으로 실패한다(수정 전 1코어
재현 9회 중 4회). 같은 구조가 2~3초 lease를 쓰는 테스트 5곳에 있다. near-timeout
테스트는 READY 뒤 1초를 고정으로 자서, 기동이 길면 publish·commit에 남는
시간이 줄어든다. 자식 기동을 기다리는 poll 세 개(waitForFile,
waitForNewDirectChild, waitForStoppedProcess)는 1초 마감을 쓴다. 파일
머리의 watchdog 설명("1초 요구를 넣지 않는다")과 어긋난다.
고른 방법
- spawnGuardian이 실제 guardian을 import하는 래퍼로 띄운다. import가
끝나면(bootstrap과 stdin reader 등록까지 끝난 시점) 래퍼가 여분 pipe
(fd 7)에 1바이트를 쓰고 닫는다. 새 sendGuard는 이 신호를 받은 뒤에
마감을 계산해 가드를 보낸다. 가드를 보내는 6곳이 모두 sendGuard를 쓴다.
guardian 코드와 프로토콜, 350ms·2s·3s lease 값은 그대로다.
- near-timeout 테스트는 startProviderGuardian 호출 직전 시각에서 1초 뒤에
깬다. 클라이언트가 spawn 뒤에 마감을 찍으므로 마감은 그 시각 + 2초
이후다. 기동이 길어도 publish·commit에 1초가 남는다.
- 1초 poll 세 개는 같은 파일의 watchdog(5초)을 쓴다. 자식 기동에는 기다릴
이벤트가 없어 poll이 남는다.
- 같은 종류 guardian 두 개 테스트는 패자가 클라이언트의 고정 5초 READY
제한(RESPONSE_TIMEOUT_MS)으로만 거부된다. 테스트가 줄일 수 없는 고정
대기라 파일의 PROCESS_HEAVY_TIMEOUT_MS를 붙이고 이유를 주석에 적었다.
버린 대안
- lease를 늘리기: 기동 시간에 상한이 없어 같은 문제가 더 드물게 남는다.
350ms 테스트는 만료를 기다리는 시간도 길어진다.
- marker 파일 + poll로 준비 신호: 파일 시스템 poll에 다시 마감이 필요하다.
pipe는 이벤트로 끝나고 provider-evidence 목록 단언에 끼어들지 않는다.
- guardian 프로세스에 가짜 시계 주입: 자식 프로세스라 테스트용 훅을 운영
스크립트에 넣어야 한다.
위험·한계
- spawnGuardian 경로의 guardian은 main 모듈이 아니라 래퍼가 import한
모듈로 돈다. guardian은 argv·import.meta를 읽지 않는다. 래퍼는 신호를
보낸 뒤 fd 7을 닫으므로 가드를 받는 시점의 상속 fd(0~6)는 운영과 같다.
클라이언트 경로 테스트는 그대로 실제 스크립트를 직접 띄운다.
- 가드를 보내기 전 기동 대기는 watchdog 5초가 상한이다. 남은 실제 시계
구간은 가드 처리(decode, link, fsync, READY)뿐이다.
- 따로 남는 결함(이 커밋 범위 밖): guardian은 가드를 거부하거나 link가
실패하면 failClosed가 진단을 쓰지만, stdin 읽기가 걸려 있는 동안
종료하지 않는다. 탐침: 만료된 가드를 받고 1,008ms에 진단을 쓴 뒤 stdin을
닫은 4,014ms에야 126으로 끝났다. 그래서 클라이언트에서는 거부가 즉시
오지 않고 5초 뒤 "READY timed out"이 된다(leaseMs 1과 동시 guardian 탐침
5,018~5,053ms). 위 PROCESS_HEAVY_TIMEOUT_MS는 이 결함이 고쳐지면 뺄 수
있다.
검증
- RED(수정 전, taskset -c 0, --maxWorkers=4): component·features·
integration·platform/cardinality 3회 중 2회, 같은 묶음 + 바쁜 이웃 1개
3회 중 2회 "expires an uncommitted lease … deadline guardian READY timed
out"(5,035~5,052ms).
- GREEN(세 커밋을 합친 상태, taskset -c 0 + 같은 코어의 바쁜 이웃,
--maxWorkers=4): 대상 6개 파일 6회, 위 넓은 묶음 5회(이웃 1개) 모두
통과. 이웃 2개로 3회 돌렸을 때 이 파일은 모두 통과했다(실패 1건은
http-execution-v3-live-authority, 0929/10-03).
- 기본 코어: tests/unit·component·integration 212파일 2,734개 통과
(pnpm을 띄우는 security-followup-archive, fixture-node-modules,
lab-performance 제외). tsc -p tsconfig.test.json, 바꾼 파일 eslint
통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md
문제
extreme-scale-registry.test.ts는 머지 게이트(FE-GATE-005 coverage, pr
scale tier)에서 돈다. 그런데 절대 시간 예산(100만 조회 1,500ms, 100k
조합·멤버십 3,000ms)을 단언한다. 1코어에서는 코드와 무관하게 떨어진다
(수정 전 9회 중 5회, 1,509~1,826ms). run-scale-profile.ts와
ungated-tests.json은 pr tier를 "CPU와 무관하다"고 설명하는데 이 파일만
어긋났다. 같은 이유로 진짜 회귀를 잡는지도 기계 속도에 달려 있었다.
고른 방법
- 조합: 이미 있던 10k -> 100k 증가 비율(30 미만)만 남긴다.
- 조회: 같은 100k 키로 만든 일반 객체 조회와 비교해 3배 미만인지 본다.
조회 횟수는 1,000,000 -> 200,000(양쪽 합 400,000).
- 멤버십: 10k와 100k 선택·해석 비용을 repo의 assertLinearOrBetter(지수
1.5 이하)로 본다.
- 측정: 비교하는 두 쪽을 번갈아 재고, 10k 쪽은 10번 반복해 일의 양을
맞추고, 각자 가장 빠른 회차를 쓴다. 공유 코어에서 10ms 측정은 한
scheduler slice 안에 끝나고 100ms 측정은 다른 프로세스 뒤에서 기다려
성장이 실제보다 가팔라 보인다(일의 양을 맞추기 전 조합 비율 61 관측).
가장 빠른 회차는 check:scale:baseline이 성장을 minMs로 읽는 것과 같다.
절대 시간은 기준 CPU에서만 비교하는 check:scale:baseline 몫으로 둔다.
버린 대안
- 예산을 올리기: 더 느린 러너에서 같은 문제가 다시 생긴다.
- 절대 예산을 nightly 전용 파일로 떼기: tier 설정·ungated 목록·문서를
함께 고쳐야 하고, 머지 게이트 쪽에는 결국 이번 비교가 필요하다.
- 조회를 10k/100k 성장으로 보기: 감싸기(proxy)처럼 크기와 무관한 느려짐을
못 잡는다. 선형 탐색은 어느 쪽이든 시간 초과로 드러난다.
위험·한계
- 비교도 실제 시계로 잰다. 바쁜 이웃 3개를 둔 1코어에서 관측한 최댓값은
조합 비율 17(한도 30), 조회 비율 1.04(한도 3), 멤버십 지수 1.21(한도
1.5)이다. 여유는 한도의 약 1.2~3배다.
- 크기와 무관한 작은 상수 배 느려짐(get trap이 있는 proxy 정도)은 조회
비교가 잡지 못한다. 수정 전 절대 예산도 이 기계에서 잡지 못했다.
검증
- RED(수정 전, taskset -c 0): 대상 파일만 3회 중 1회, component·features·
integration·platform/cardinality 3회 중 1회, 바쁜 이웃 1개를 더하면
3회 중 3회 "expected 1509.6… to be less than 1500"
(extreme-scale-registry.test.ts:78).
- 변이(기본 코어): 조합에 100번째마다 Object.keys -> "expected 145.5 to be
less than 30". 조회에 20회 hasOwn get trap -> "expected 14.46 to be less
than 3". 해석을 includes로 -> "super-linear growth: exponent 1.98".
- GREEN(taskset -c 0 + 같은 코어의 바쁜 이웃, --maxWorkers=4): 대상 6개
파일 6회, component·features·integration·platform/cardinality 5회 모두
통과. 이 파일만 바쁜 이웃 3개 옆에서 6회, coverage를 켜고 3회 통과.
- 실행 시간: 기본 코어에서 파일 1.76s -> 1.37s.
- 기본 코어: tests/features·platform·architecture·contract·runtime-schema
60파일 403개 통과. tsc -p tsconfig.test.json, eslint 통과.
Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
문제
lazy route 화면을 findBy*·waitFor 기본값(1초)으로 기다리는 테스트가 1코어
부하에서 코드와 무관하게 떨어진다. 수정 전 재현에서
runtime-application.test.tsx:65 "Unable to find role=heading name=Clean
Architecture Frontend"와 reference-production-vertical.test.tsx:103
"Unable to find role=button name=로그인 시작"이 났다. 두 DOM 모두
route-loading(aria-busy) 상태였다. 지난 리뷰는 router.test.tsx:244-250도
같은 이유로 실패했다고 적었다. React 19는 Suspense를 풀 때마다 실제 300ms
타이머(FALLBACK_THROTTLE_MS)를 기다린다. context route 표와 lazy 페이지를
거치는 화면은 렌더링 전에 1초 중 600ms를 쓴다. 이 사정을 아는 파일만
호출마다 { timeout: 5000 }을 붙이거나(7개 파일 13곳) 파일 단위로
configure를 바꿨다(reference-page). 새 테스트 작성자는 이 규칙을 알 방법이
없다.
고른 방법
tests/setup.ts에서 configure({ asyncUtilTimeout: 5_000 })를 한 번 정하고,
같은 값을 반복하던 호출·파일 단위 override를 지웠다. findBy*·waitFor는
DOM 변화가 오면 바로 끝나므로 기한은 멈춤을 알리는 용도뿐이다. 10초 테스트
제한의 절반이라 진짜 멈춤은 여전히 Testing Library의 DOM 덤프와 함께
실패한다. 기한을 늘리는 방식이라 고른 이유를 setup에 주석으로 남겼다.
버린 대안
- 가짜 시계: Testing Library는 Jest의 가짜 타이머만 알아본다
(jestFakeTimersAreEnabled가 jest 전역을 본다). Vitest 가짜 타이머에서
waitFor는 자기 타이머가 멈춰 끝나지 않는다. MSW와 user-event도 실제
시계로 돈다.
- route chunk를 테스트에서 미리 import하기: chunk를 받아도 React의 300ms
reveal 타이머와 렌더링 비용은 그대로 기한 안에 남는다. 테스트가 route
모듈 목록을 따로 알아야 한다.
- 실패한 파일에만 timeout 붙이기: 지금 상태와 같다. 다음 lazy 화면
테스트에서 같은 실패가 반복된다.
위험·한계
- 기다리다 실패하는 테스트는 실패까지 1초가 아니라 5초 걸린다. 부재를
findBy·waitFor의 실패로 확인하는 테스트는 없다(grep으로 확인).
- 가짜 타이머를 쓰는 테스트의 waitFor는 이 값과 무관하다(가짜 시간).
검증
- RED(수정 전, taskset -c 0 + 같은 코어의 바쁜 이웃 1개, --maxWorkers=4,
component·features·integration·platform/cardinality): 3회 중 1회 위 두
테스트 실패.
- GREEN(같은 조건): 대상 6개 파일 6회, 넓은 묶음 5회 모두 통과. 바쁜
이웃 2개로 3회 돌렸을 때도 이 커밋이 다루는 테스트는 모두 통과했다.
넓은 묶음 한 번의 시간은 RED 91~111s(실패가 몰린 209s 회차 제외)
-> GREEN 86~88s다.
- 기본 코어: tests/unit·component·integration 212파일 2,734개, features·
platform·architecture·contract·runtime-schema 60파일 403개 통과.
tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
FE-GATE-012(build, check-bundle, check-app-build-input-bundle,
check-optional-recipes)는 release 단계에만 있어 tag push나 수동 release
실행에서만 돈다. 초기 JS를 예산보다 크게 만드는 PR도 merge 게이트를
통과하고, 몇 PR 뒤 release가 실패한다. 어느 PR이 얼마나 늘렸는지는 그때
이력을 거꾸로 따라가 찾아야 한다.
FE-GATE-012를 merge stage와 merge_gate job으로 옮긴다. release_gate는
merge_gate를 needs로 두므로 tag 실행에서도 그대로 돈다. promotion 공식
(MERGE_READY)과 CI 계약 검사의 job 소유 표를 같이 바꾸고, workflow는
생성기(node scripts/generate-ci-workflow.ts)로 다시 만든다.
버린 대안:
- check-bundle만 FE-GATE-011(build)에 붙인다(리뷰의 최소안). 같은 검사가
두 게이트에 갈라지고, release에 남은 FE-GATE-012와 중복해서 돈다.
- FE-GATE-012를 merge와 release 둘 다에 둔다. 계약이 게이트당 job 하나를
강제한다(multiply owned gate).
- lab 게이트(FE-GATE-026)도 merge로 옮긴다. PR마다 브라우저 설치와 5회
측정이 붙고, 부하에 따라 판정이 뒤집힌 기록(0929/11-04)이 있다. release에
남긴다.
위험·한계:
- merge 실행이 build 1회와 공급망 생성, 번들 계산만큼 길어진다.
- 실제 CI 러너에서는 돌려 보지 않았다(Actions 꺼짐).
검증:
- node scripts/check-ci-contract.ts: 27 gates PASS
- node scripts/generate-ci-workflow.ts --check: PASS
- node scripts/generate-artifact-schemas.ts --check: PASS
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
tests/unit/promotion-readiness.test.ts: 423 통과(workflow 스냅샷 1건 갱신)
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 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절
문제
guardian은 fd 0을 fs.createReadStream으로 읽는다. 이 스트림은 libuv
스레드 풀의 스레드 하나를 read(2)에 세워 둔다. process.exit()는 종료
전에 스레드 풀을 join하므로, 그 read가 돌아올 때까지(부모가 stdin을
닫을 때까지) 끝나지 않는다. 그래서 가드를 거부하거나 link가 실패하면
failClosed가 진단을 바로 쓰고도 프로세스는 남는다. 클라이언트는 stdin을
연 채 READY를 기다리므로 거부가 즉시 오지 않고 고정 5초 뒤 "READY timed
out"으로 끝난다. 같은 종류 guardian 두 개 테스트의 패자가 이 경로다.
탐침: 같은 종료 코드를 fs 스트림은 stdin을 닫은 2,008ms에, net 소켓은
228ms에 냈다(200ms 뒤 exit 호출).
고른 방법
- liveness 입력을 process.stdin으로 바꾼다. pipe면 Node가 이벤트 루프로
읽는 net.Socket을 만든다. 스레드 풀 read가 없어 exit가 바로 끝난다.
data/end/error 처리, removeAllListeners·destroy, closeSync(0)는 그대로다
(libuv는 fd 0~2를 destroy에서 닫지 않는다).
- 동시 guardian 테스트에 붙였던 PROCESS_HEAVY_TIMEOUT_MS와 그 주석을
뺀다. 패자가 link 실패 즉시 끝나 테스트가 5.14초에서 0.16~0.54초가 됐다.
버린 대안
- provider-scope-wrapper.ts처럼 new Socket({ fd: 0 }): fd 0이 pipe가
아니면 생성자가 throw한다. guardian은 그 시점에 이미 private alias를
묶었고 failClosed는 liveness가 있어야 돈다. process.stdin은 pipe에서는
같은 Socket이고, 그 밖의 fd에서는 throw 대신 end/error로 기존 실패
경로(125)를 탄다.
- 실패 때 SIGKILL로 자신을 죽이기: 종료 코드 124~126 계약이 사라진다.
위험·한계
- pipe인 fd 0에 O_NONBLOCK이 걸린다. 읽기 끝은 guardian만 가진다
(클라이언트는 stdio "pipe"로 띄운다).
- lease 마감 경로는 원래 SIGKILL을 쓰므로 바뀌지 않는다.
검증
- RED(수정 전): 새 테스트 "exits on a rejected guard while the parent
still holds its input open"이 "rejected-guard guardian exit timed out"
(5,122ms)으로 실패. 다른 nonce의 가드를 보내 시계와 무관하게 거부시킨다.
- GREEN: tests/integration/provider-guardian-transaction.test.ts 22/22
통과, 3회 반복 통과(새 테스트 65~333ms). tests/unit/task3-selective-
integration 7/7. tsc(tsconfig.node, tsconfig.test) 통과, 바꾼 파일
eslint 통과.
- 미실행: tests/system/ci-runner/ci-artifact-contract.test.ts의 provider
체인 테스트. fixture가 corepack pnpm으로 빌드해서 이 worktree에서는
돌리지 않았다.
Refs: commit c862004 위험·한계의 "따로 남는 결함"
문제
49d8675는 디자인 규칙 4개를 순수 함수로 옮기고 함수마다 단위 테스트를
붙였다. 규칙 함수의 판정을 깨면 규칙마다 테스트가 실패한다(이번에 다시
확인: 대비 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건 통과 → 11개 중
7개 실패). 그러나 scripts/check-design-system.ts가 그 함수를 부르는
부분은 아무것도 지키지 않는다. 스크립트에서 규칙 호출을 지우고 포커스
색을 옛 값 oklch(0.72 0.16 225), 첫 글꼴을 Inter로 되돌려도
check-design-system은 PASS, 관련 단위 테스트 17개도 통과했다. 리뷰가
적은 "규칙을 모두 꺼도 모든 게이트가 통과한다"가 이 경로로 남아 있었다.
고른 방법
- 기존 규칙 테스트 파일에 테스트 하나를 더한다. 토큰 CSS와 styles/**를
임시 폴더에 복사하고 규칙마다 위반 하나를 넣는다(옛 포커스 색, Inter
첫 글꼴, var(--drawer-width) 제거, in oklch 혼합 probe.css). 그 폴더를
cwd로 실제 스크립트를 돌리고, 산출물 JSON의 failures에 네 규칙의
메시지가 모두 있고 다른 실패는 없는지 본다.
- 스크립트·게이트·산출물 스키마는 바꾸지 않는다. 스크립트가 이미 cwd
기준 경로만 읽어서 임시 폴더로 충분하다. ci-workflow-generation 테스트가
check-ci-contract.ts를 같은 방식으로 돌린다.
버린 대안
- 리뷰가 제안한 --root 인자와 tests/fixtures/design-system/forbidden-css:
49d8675가 이미 버렸다. cwd 복사가 스크립트 변경 없이 같은 것을 증명한다.
- --fixture 모드가 CSS fixture도 읽게 하기: gates.json 기대값과 CI 계약
기준선을 함께 바꿔야 한다.
위험·한계
- 실제 CSS 문자열(--color-focus 정의, --font-sans, var(--drawer-width))을
찾아 바꾼다. 찾지 못하면 어느 문자열인지 적고 실패한다(조용히 통과하지
않는다).
- 성공 메시지와 산출물이 어떤 규칙이 돌았는지 적지 않는 점(12-02 근거의
산출물 부분)은 스키마 변경이라 그대로 둔다.
- 테스트 하나가 node 프로세스를 띄운다(약 0.2초).
검증
- RED: 스크립트에서 hueMixFailures 호출과 규칙 4개 failures.push를
지우면 새 테스트가 "expected +0 to be 1"로 실패. firstFontFamilyFailures
한 줄만 지워도 '--font-sans starts with "Inter"' 메시지가 없어 실패.
- GREEN: tests/unit/design-system-rules.test.ts 12/12, oklch-contrast·
design-system-contract 포함 18/18 통과. node scripts/check-design-system.ts
PASS. tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-02
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.
고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
<값>; contrast needs an opaque oklch(L C H), hue in degrees with or
without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.
위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.
검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
"names the value it cannot compute …" 메시지 불일치, "-apple-system"
expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
/ 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
문제
package.json에 어디서도 부르지 않는 script 4개가 있다.
- scan:security:fixture: FE-GATE-013은 이것 대신 check:security:fixtures를
돈다. supply-chain.test.ts는 "게이트에 없어야 한다"고 단언하는데 script는
남아 있다. 게이트 밖 script 검사는 check|verify|test|drill|review만 봐서
scan:을 놓쳤다.
- build:profile: 이름과 달리 generate-runtime-config.ts만 돈다.
- generate:contract-set: 참조 0건.
- build:app-only: vite build와 매니페스트만 만든다. build-frontend.ts의
계약 세트·런타임 설정·Service Worker 단계가 빠진 dist가 나온다. 참조는
product-index-entrypoints 테스트의 진입점 목록 하나다.
참조 확인(새 기준 298201f, docs/reviews 제외): package.json 정의와 위 두
테스트 말고는 config/ci/gates.json, 생성 workflow, scripts, docs 어디에도
없다. 아래 세 script가 부르던 파일(generate-runtime-config.ts,
generate-contract-set.ts, generate-build-manifest.ts)은 build-frontend.ts가
그대로 부른다.
고른 방법
- 네 script를 지우고 진입점 목록에서 build:app-only를 뺀다.
- VERIFICATION_SCRIPT에 scan을 더한다. 게이트가 닿지 않는 scan:* script는
ungated-scripts.json 항목 없이는 check:ci에서 실패한다. 지금 남은
scan:security는 build:release-candidate를 거쳐 게이트가 닿는다.
- docs/operations/ci-quality-gates.md의 접두어 목록에 scan:*을 더한다.
버린 대안
- build:app-only를 build:vite-only로 이름만 바꾸기: 남길 사용처를 찾지
못했다.
- 접두어 대신 "게이트 밖 모든 script는 예외 목록에": dev·storybook·
update:*까지 목록에 올라가 목록이 커진다(리뷰 대안 비교와 같다).
- check:feature-index 정리(리뷰 개선 (4)): 지우기와 이유 문구 고치기 중
하나를 고르는 일이라 이번에 하지 않았다.
위험·한계
- 개인 습관으로 이 script를 쓰던 사람은 build-frontend.ts나 node
scripts/...를 직접 불러야 한다.
- 게이트 명령은 바뀌지 않아 CI 계약 기준선은 그대로다.
검증
- RED: 새 테스트 "rejects a scan script that no gate reaches"가 실패
(expected [ …(2) ] to deep equally contain '…: scan:orphan'). 정규식만
넓히면 저장소 검사 "reaches every verification script …"가
scan:security:fixture 한 건으로 실패.
- GREEN: ungated-scripts·product-index-entrypoints·supply-chain·
ci-workflow-generation 4파일 457/457 통과. check:ci의 세 단계를 pnpm
없이 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS(27 gates), generate-ci-workflow --check PASS.
tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-05
문제: 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
문제: Web Storage 어댑터의 실패 원인은 QUOTA_EXCEEDED,
SIZE_LIMIT_EXCEEDED, UNAVAILABLE, VALUE_REJECTED 넷이다. 진단 이벤트
storage.operation.failed는 error_kind에 quota면 STORAGE_QUOTA_EXCEEDED,
나머지는 모두 STORAGE_UNAVAILABLE을 넣고 원인을 버린다. 그래서 운영자는
"브라우저 저장소를 못 쓴다"와 "저장된 값이 깨져서 버렸다"를 같은
이벤트로 본다. 호출자에게 주는 실패 code에는 원인이 이미 들어 있다.
고른 방법: recordStorageFailure의 context에 reason: cause를 더한다.
reason은 진단 계약의 허용 칸(taxonomy)이고 원인 값은 어댑터의 닫힌
유니온이라 cardinality가 늘지 않는다. projectDiagnosticRecord에 넣어
칸이 그대로 남는 것을 확인했다.
버린 대안: error_kind를 원인별로 나누는 것. error_kind는 createFailure의
error kind taxonomy와 맞춰져 있어, 값을 늘리면 그 taxonomy를 바꿔야
한다. 이미 있는 reason 칸에 싣는 쪽이 추가만으로 끝난다.
위험·한계: 진단 이벤트에 칸이 하나 는다(추가만). 수집기가 reason을
바깥으로 내보내는지는 영역 03 소관이라 보지 않았다.
검증:
- RED: storage-registry의 quota, discard 3종(malformed, invalid
envelope, oversized), oversize write 테스트 5개가 실패.
예: "expected vi.fn() to be called with arguments" 차이
`- "reason": "VALUE_REJECTED"`.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, runtime-adapters, diagnostics,
release-mismatch-recovery 4파일 68/68 통과. tsc app·test 통과,
eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한
주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus·
pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다.
optional-runtime-host.ts도 같은 말을 한다. 실제로는
- telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다
(telemetry-collector.ts onPageExit).
- 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를
단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외).
- lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는
없다.
또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache
복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가
살아남았다.
고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에
구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다.
tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation,
visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt,
dispose 뒤 0개를 확인한다.
버린 대안:
- (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을
만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야
해 이번 범위를 넘는다.
- (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에
비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다.
위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다).
src 동작은 바뀌지 않는다.
검증:
- RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide,
browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인.
- RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를
모두 잡는다. K3(generation += 1 제거) → "expected {...} to match
object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) →
"expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0",
dirty 검사 제거 → preventDefault "to not be called".
- 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters
3파일 30/30 통과. tsc app·test 통과, eslint 통과,
check-adapter-inventory PASS.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
문제: kernel 주석이 근거를 다른 파일의 줄 번호로만 준다. 줄이 밀려
참조 20개 중 19개가 엉뚱한 코드를 가리킨다. 예를 들어
indexeddb-transaction.ts의 "runtime은 지운 행 수로 예산을 잰다"는
indexeddb-runtime.ts:2384를 가리키는데 그 줄은 cursor 삭제 onerror다.
네 벌의 transaction 상태 기계를 가리키는 참조 넷은 kernel 이전 코드라
이미 없다(네 어댑터 모두 지금은 runIndexedDbTransaction을 쓴다).
고른 방법: 리뷰 권고대로 줄 번호 대신 심볼 이름을 쓴다.
- purgeEligibleRecords, scanBatch, monotonicClock, runCheckpointTransaction,
bindScope, 체크포인트 store의 translate, BT-UP-03,
restrictedBrowserDataProperties, browser-data-boundary 예외 목록,
REQUIRED_ABORT_CONSUMERS.
- 없어진 코드를 가리키던 역사 설명은 "IDB-X-02 이전에는 네 벌이
달랐다", "runtime의 kernel 이전 fail/requestFailed 의미"처럼 ID와
과거형으로 줄였다. "runtime이 지금 inline으로 한다"처럼 더는 사실이
아닌 문장은 지웠다.
- 유일하게 맞던 abortable-operation.ts:11도 같은 규칙으로 줄 번호만
뺐다(심볼 AbortTerminalReason이 이미 문장에 있다).
버린 대안: 줄 번호를 지금 위치로 다시 맞추기. 다음 수정에서 또 밀린다.
위험·한계: 주석만 바뀐다. 코드·번들 크기(주석은 minify에서 빠짐)는
그대로다. 심볼 이름도 이름이 바뀌면 낡지만 grep으로 바로 찾을 수 있다.
검증:
- RED(문서·코드 대조): platform/·browser-file-storage/의
`grep -rnE '\.(ts|json|md|mjs):[0-9]+'` 20건을 스크립트로 열어 대조.
19건이 다른 코드(예: check-adapter-inventory.ts:63-83은 INVENTORY 중복
행 검사, eslint.config.ts:519-530은 블록 끝 "},"), 1건만 맞음.
- GREEN: 같은 grep 0건. 새로 적은 심볼은 모두 해당 파일에 있는 것을
확인했다.
- 회귀: indexeddb-transaction, indexeddb-connection, browser-lifecycle
3파일 66/66 통과. tsc app 통과, eslint 통과, check-adapter-inventory
145 files PASS.
Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.
고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.
버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.
위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
as unfinished"가 `- "moreObjectsAvailable": true`
`+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
check-optional-recipes PASS.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.
고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
(REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
읽었는지 아닌지를 구분하지 못했다.
버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
/REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
depcruise로 볼 수 없다.
위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
(라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
참조 기능 id 하나로만 풀린다.
검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
external-contract-runtime "rejects a fixture copied into a product
feature" -> "Expected contract composition to fail."
reference-fixture-provenance "rejects a second fixture contribution"
-> "expected undefined to be 'reference-feature: only one
TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features
tests/platform tests/component tests/contract tests/runtime-schema
tests/integration (pnpm·corepack을 띄우는 fixture-node-modules,
security-followup-archive, deployment-admission, lab-performance 제외)
267 files / 3107 tests 중 3106 통과. 실패 1건은
provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로
scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0.
- 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep).
- 미실행: test:sample-removal, check:architecture(pnpm 필요).
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.
고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
(V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.
버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.
위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
파일을 돌려야 걸린다.
검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
("responseSchema": "ReferenceResourcePayload" vs "...V2").
L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
"cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
조립기와 선언 검증의 쓰기 API 규칙 5개는 지워도 관련 테스트가 모두
통과한다(리뷰 변이 MX1·MX2·MX5·MX6·MX9).
- MX1 읽기 operation의 command descriptor 금지
(external-contract-runtime.ts). 실행기는 쓰기 여부를 메서드가 아니라
commandEffect !== null로 정하므로 GET이 쓰기로 처리되는 것을 막는
유일한 경계다.
- MX9 KEYED 쓰기의 복구 descriptor 필수
- MX6 NEVER 재시도와 재시도 예산 1 이상의 모순 거부
- MX5 V2 KEYED_COMMAND의 idempotencyKeyPolicy REQUIRED 정합
(api-operations.ts)
- MX2 mapper 레지스트리 키 = mapperId (boundary-mapper.ts)
조립기는 여러 번 다시 쓰인 파일이라 규칙 줄이 빠져도 CI가 모른다.
고른 방법
규칙마다 그 규칙만 어긴 행 하나로 실패 사례를 둔다. 오류 메시지는 기능
작성자가 쓰기 API 규칙을 배우는 통로라 reason 문자열을 그대로 단언한다.
정상 대조군은 기존 사례(TEST_CONTRACT_CONTRIBUTION 조립, command()
정의, 키가 맞는 mapper 등록)를 쓰거나 같은 테스트 안에 둔다. 코드 변경은
없다.
버린 대안
- 메시지 대신 ContractContributionError 종류만 단언: 다른 규칙이 먼저
실패해도 통과해서 변이를 놓칠 수 있다.
위험·한계
- 메시지 문구를 바꾸면 테스트도 바꿔야 한다. 의도한 결합이다.
- MX6은 실행기(http-retry-lifecycle)가 한 번 더 막는다. 이 테스트는
조립 단계의 안내 메시지를 지킨다.
검증
- RED: 변이 5개를 하나씩 넣고 바꾼 3파일을 돌렸다. 이 커밋 전 테스트로는
5개 모두 살아남음(26/26 통과). 새 테스트로는 5개 모두 죽음, 각 변이마다
해당 사례 1건만 실패(30/31).
- GREEN: 변이 없이 31/31 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의
MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고
부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는
{ ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름
MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을
요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper,
참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거
조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수
없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다.
eslint 설정에 폐기 검사가 없다.
고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로)
- boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry,
mappingSuccess, mappingFailure와 바인딩 mapSuccess가
BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도
옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서
런타임과 공개 시그니처는 바뀌지 않는다.
- D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은
BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가
필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는
같은 type의 alias" 문장도 고쳤다.
- 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어
@typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core
no-restricted-imports의 patterns.importNames로 boundary-mapper의
MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다.
층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로
restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은
그 앞에 둔 공통 블록이 받는다.
버린 대안
- 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2)
후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상
공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0,
lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다.
- typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint
설정(속도·설정 범위)이 필요하다.
- 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유
문자열로 넓어져 계약이 약해진다.
위험·한계
- 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭).
리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야
충족된다. 제거 시점은 릴리스 결정으로 남긴다.
- 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint
오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데,
반환 타입은 같은 모양이라 영향 없음).
- adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다.
같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다.
검증
- RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors
("'MappingResult' import from '../../contracts/boundary-mapper.ts' is
restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure
같은 꼴).
- GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일)
--max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep).
- 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit
tests/features tests/platform tests/component tests/contract
tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외)
273 files / 3136 tests 중 3135 통과. 실패 1건은
provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이
변경과 무관한 scripts/lib 프로세스 테스트).
check-registries PASS, verify-documentation-readiness PASS_SCOPED,
check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로
사실상 미검증.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.
고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
(contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
registry-contract-extension(additive)을 더하고 artifact id 목록에도
넣었다.
버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
breaking에 남겼다.
위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
(field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
계속 breaking으로 남는다.
검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
(null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
nullable-field-cleared actual breaking, registry-contract-extension
actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
check-registries "11 registries PASS"(남은 breaking은
REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
exit=126 환경 문제로 이 변경과 무관하게 실패).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
문제
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
문제
기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면
classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를
돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract
runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를
버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고
답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을
NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다.
고른 방법
- HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은
닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다.
문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고,
finish()가 관측 기록에 싣는다.
- 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다
(reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다.
- 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지
않았다.
버린 대안
- 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기:
terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제
응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단
조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중
차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌
타입 필드가 의도가 더 잘 보인다.
- 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이
분류기 결함 때문인지 구분할 수단이 계속 없다.
위험·한계
- classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만
내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서
뺐다.
- 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개).
- VD-07 5-1에 reason 전달 규칙을 적었다.
검증
- RED(수정 전): tests/integration/http-execution-v3-observability.test.ts
"keeps MAYBE_APPLIED and records a failed problem classifier in
diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제
undefined.
- GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면
이 테스트가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/integration tests/features/reference-feature
tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 스크립트 필요).
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문제
전송 전 실패가 네 곳에서 원인 없는 위반 FINAL_REQUEST_INVARIANT_FAILED
하나로 바뀐다. 입력 검증 실패, 요청 조립 실패 10종(PATH_PLACEHOLDER_MISSING
등), 최종 불변식 실패 12종, 미설치 계약이다. 바인딩은 이 위반과
MISSING_IDEMPOTENCY_KEY·UNEXPECTED_IDEMPOTENCY_KEY를 모두 VALIDATION_REJECTED로
바꿔 "서버가 입력값을 받아들이지 않았습니다"를 띄운다. 그래서 경로
placeholder 오타나 mutation 정책과 계약의 불일치 같은 개발자 연결 실수가
사용자 입력 문제처럼 보이고, 진단에는 원인이 없다. 미설치 계약은 실행기를
거치지 않아 진단이 0건이다. 또 마감이 시도별 budget 읽기와 최종 불변식
검사 사이에 끝나면 DEADLINE_EXPIRED도 같은 위반이 되어, 시간 초과가 "입력
거절"로 보인다(P-03-05).
고른 방법
- HttpContractViolation에 선택 필드 reason(닫힌 집합
HttpRequestRejectionReason)을 더한다. 실행기의 세 거절 지점이
refusedRequest(reason)로 위반을 만들고, finish()가 그 reason을 관측의
diagnosticReason으로 옮긴다. projector는 03-05에서 만든 경로대로
diagnostics에만 reason을 싣는다. telemetry는 error_kind 그대로다.
- 최종 불변식의 DEADLINE_EXPIRED는 budget 읽기 분기와 똑같이
TRANSPORT_FAILURE/TIMEOUT으로 끝낸다(P-03-05).
- 바인딩은 사용자가 입력을 바꿔 고칠 수 있는 거절(INPUT_INVALID,
PATH_VALUE_INVALID, QUERY_TOO_LARGE, URL_TOO_LARGE, REQUEST_BODY_TOO_LARGE)과
reason 없는 거절만 VALIDATION_REJECTED로 둔다. 나머지 reason과 멱등 키
위반은 UNKNOWN_CLIENT_FAILURE(문의 행동, "요청을 처리할 수 없습니다.")로
낸다. V2 client가 미등록 operation을 같은 종류로 내는 것과 맞췄다.
- 미설치 계약 분기는 같은 projector로 관측 1건(reason
CONTRACT_NOT_INSTALLED)을 직접 남긴다.
버린 대안
- 새 FailureKind 추가: 오류 레지스트리·i18n 카탈로그·화면 분기를 다 바꿔야
한다. 이미 있는 UNKNOWN_CLIENT_FAILURE가 "클라이언트 결함, 문의"라는 같은
뜻이고 V2에서 같은 상황에 쓰고 있다.
- 리뷰 예시대로 MAPPING_CONTRACT_VIOLATION으로 내기: 문구가 "서버 응답을 화면
데이터로 바꾸지 못했습니다"라 응답이 없는 전송 전 실패와 맞지 않는다.
- 사용자 입력 쪽을 reason별 Record로 망라하기: 컴파일 시 분류를 강제하지만
20여 줄이 는다. 새 reason은 기본으로 클라이언트 결함이 되는 쪽이 안전하므로
입력 쪽 5개만 Set으로 적었다.
- terminalReason에 원인을 싣기(리뷰 문구): 03-05와 같은 이유로 버렸다.
위험·한계
- 동작 변경: 멱등 키 위반과 연결 실수가 VALIDATION_REJECTED에서
UNKNOWN_CLIENT_FAILURE로 바뀐다. 폼은 필드 오류 대신 "unavailable" 상태
안내를 띄운다. 기존 계약 테스트의 기대값을 이에 맞게 바꿨다.
- 입력 검증 실패(INPUT_INVALID)는 리뷰 문구("입력 크기 초과만")와 달리
VALIDATION_REJECTED로 남겼다. 입력 validator의 거절은 사용자 입력 문제다.
- reason 없는 FINAL_REQUEST_INVARIANT_FAILED(다른 실행기 구현)는 기존대로
VALIDATION_REJECTED다.
- AppFailure.code는 지금처럼 위반 종류다. 원인 코드는 진단에만 있다.
- 공개 타입은 추가만 했다(위반 선택 필드 1개, 진단 reason 집합 확장).
- validator가 throw하는 경우(VALIDATOR_RUNTIME_FAILURE → SCHEMA_MISMATCH,
"서버 응답 데이터가…" 문구)는 이번 범위가 아니라 그대로다.
- 미설치 계약 거절도 다른 CONTRACT_VIOLATION처럼 api.request.failed
telemetry 1건을 낸다(VD-07 규칙 5).
- 화면: 정상 상태는 그대로이고 위 실패에서만 문구가 바뀐다. 시각 골든은
다시 찍지 않았다.
검증
- RED(수정 전):
- http-execution-v3-observability "names a refused request's assembly
cause in diagnostics only (03-02)": violation.reason 없음.
- 같은 파일 "ends a deadline that expires at the final invariant check as
a timeout (P-03-05)": TRANSPORT_FAILURE 기대, 실제 CONTRACT_VIOLATION.
- feature-http-binding 계약 테스트 5건: PATH_PLACEHOLDER_MISSING,
CONTRACT_NOT_INSTALLED, HEADER_NOT_ALLOWED, MISSING_IDEMPOTENCY_KEY,
UNEXPECTED_IDEMPOTENCY_KEY가 VALIDATION_REJECTED로 나옴.
- runtime-adapters-auth-profile "is refused without a fetch and leaves one
diagnostic naming the cause": reason 없음, 진단 0건.
- GREEN: 세 파일 38/38 통과.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
13개 제외) 227 files 중 226 통과, 2354/2355. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 HTTP와 무관하다. 제외했던 http-scenario-evidence는
pnpm을 띄우지 않아 따로 돌렸고 14/14 통과.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 스크립트 필요), 번들 크기 측정.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.
고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
cache.operation.failed(operation: unregistered-query-namespace) 진단을
남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.
버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.
위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
BoundQuery.invalidation, 상수 1개).
검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
bound query whose namespace no registered topic reaches (03-01)" 실패.
"expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 이 변경과 무관하다.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
gzipSync로 쟀다. 298201f 202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적
202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다.
- 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은
0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts,
presentation -> contracts뿐이다.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문제
라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지
않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약
(config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는
`/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로
PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과
검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다.
고른 방법
- cache-policy.json에 표면 두 개를 더한다.
- appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은
Cache-Control, content-type, 보안 헤더를 요구한다.
- serviceWorker: `/service-worker.js`, no-cache, JS MIME.
`requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드
(ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은
checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다.
- live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨
fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다.
appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를
가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를
모두 FAIL로 잡는다.
- release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를
적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라
404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을
적었다.
버린 대안
- createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약·
테스트가 모두 바뀐다(리뷰 대안 비교에서 기각).
- 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만
읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다.
- 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지
않았다.
위험·한계
- nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다.
호스트가 실제로 무엇을 주는지는 live probe가 확인한다.
- 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로
실패한다(의도).
- 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
5 failed. "expected undefined to match object { cacheControl:
'no-cache', …}"(정책에 appRoute·serviceWorker 없음),
"probeLiveRelease is not a function"
- GREEN: 같은 파일 22 passed. fallback 없는 호스트에서
["appRoute http-status", "appRoute entry-script"]가 실패로 나온다
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts:
483 passed
- build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3,
결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED, check-ci-contract PASS
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04
문제
.env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고
적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를
검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고,
build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를
스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID
변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세
줄이고 고치는 방법이 없다.
고른 방법
- check-release-admission.ts가 `--config <고친 사본> --original <배포된
원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고,
원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도
바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다.
`--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지
않는다).
- 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다.
그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다.
- FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서
rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고,
release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치
설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드
없이 바꾼다"로 좁혔다.
- pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다.
버린 대안
- `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼
빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로
더 좁다.
- release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더
늘고, 여전히 BUILD_ID만 본다.
- 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어
스위치의 목적이 사라진다(리뷰 대안 비교).
위험·한계
- 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도
"바뀜"으로 거절한다(닫힌 쪽으로 실패).
- 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release
기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
새 6건 실패. 모두 "release admission refused: dist/config.json is
unreadable"(--config를 무시하고 dist를 읽음)
- GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음,
SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경·
--original 누락은 exit 1
- runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed
- 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성),
`-- --config dist/config.json --original public/config.json` ADMITTED
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05
문제
docs/operations/performance-evidence.md는 다운스트림이 첫 기능 전에 예산을
정할 때 보는 유일한 자료다. 그런데 2026-09-25 측정을 그대로 적고 있다.
기준선 196,573 B(예산의 96%, 여유 약 8,200 B), "`index` 93.5 KB,
`preload-helper` 28.5 KB(zod 포함)", "dynamic import chunk는 lazy다".
verify:documentation은 수치를 보지 않아 통과한다.
문서와 코드 대조 (RED 대신)
- 298201f 빌드(build-frontend.ts, classifyViteJavascript + gzipSync 기본
수준, check:bundle과 같은 계산): 초기 JS 16개 파일 202,509 B
(VITE_BUILD_ID=local-build), 202,522 B(gitea-123456-1). 여유 약 2,280 B
- `index` 864 B, `preload-helper` 675 B. 문서의 청크 이름별 크기가 모두
틀렸다
- 분류기(scripts/lib/classify-vite-bundle.ts)는 entry가 직접 dynamic
import하는 boot·render-boot-failure도 초기로 센다. 문서 문장과 반대다
고른 방법
- 표를 현재 측정으로 바꾸고 측정 커밋(298201f)과 빌드 ID 조건을 적는다.
- 청크 이름 대신 출처별(react-dom·react-router·zod·@tanstack·react·
템플릿 src) 크기를 적는다. sourcemap 빌드에서 minify 바이트를 원래 모듈에
나눠 붙이고 묶음마다 gzip했다. rolldown이 공용 청크에 모듈 하나의 이름을
붙여서 청크 이름으로 판단하면 엉뚱한 곳을 줄이게 된다는 설명을 둔다.
- 15-01 뒤 기능 하나의 증가량(참조 모양 +650~750 B, 298201f 커밋 측정)과
그 상한 테스트를 적는다. 다운스트림이 "몇 개 더 들어가나"를 바로 본다.
- 분류 규칙 문장을 분류기와 맞춘다.
버린 대안
- check:bundle이 bundle.json에 출처별 합계를 남기게 자동화: 빌드마다
sourcemap 빌드가 한 번 더 필요하다. 리뷰도 "가능하면"으로 적었고, 문서
수치를 맞추는 이번 범위를 넘는다.
위험·한계
- 15-01 커밋 본문의 202,361 B와 이번 측정이 148 B 다르다. 같은 커밋의 빌드
차이(빌드 정보·ID)로 보이나 원인은 확인하지 않았다.
- 출처별 표는 sourcemap 빌드(VITE_BUILD_ID=gitea-123456-1)에서 쟀다.
sourceMappingURL 주석은 빼고 셌다.
- production 프로필 빌드와 pnpm 경로의 check:bundle(generate-supply-chain이
pnpm list를 부른다)은 돌리지 않았다.
검증
- verify-documentation-readiness: PASS_SCOPED
- 다른 문서에 옛 수치(196,573, 96%, 8,200) 없음(git grep)
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-02
문제
리뷰 라운드마다 발견 ID를 `NN-MM`으로 새로 매긴다. CHANGELOG의
`(14-02)`는 0925 라운드의 "CI 계약 고정"인데, 0929 라운드의 14-02는
"README 업데이트 절차"이고 이번 라운드에도 14-02가 있다. CHANGELOG는
복사한 프로젝트가 변경 근거를 찾는 유일한 링크라 ID가 어느 라운드인지
모르면 다른 결함을 읽게 된다. 리뷰 가이드에 ID 네임스페이스 규칙이 없다.
고른 방법
- CHANGELOG 0.2.0 절의 ID 98개에 `0925/`를 붙였다(`F-N`은 0925
FOLLOW-UP의 ID라 같이 붙였다). 기계적 치환이다: 괄호 안의
`NN-MM`·`F-N`만, 범위(`01-01~01-11`)는 앞에만, 날짜는 건드리지 않는다.
0.1.0 절의 `R-x.y`는 다른 체계라 그대로 둔다.
- CHANGELOG 머리말에 `MMDD/NN-MM` 규칙과 F-N의 뜻을 적었다.
- 리뷰 가이드 36.3 "ID·제목"에 같은 규칙을 넣었다. 라운드 안에서는
`NN-MM`, 밖에서 가리킬 때는 `MMDD/NN-MM`. 기존 코드 주석 약 339곳은
고치지 않고 새로 쓰는 것부터 붙인다(리뷰의 최소 개선 방향 ③).
- tests/unit/changelog-review-ids.test.ts가 CHANGELOG 괄호 안의 라운드
없는 ID를 막는다. 리뷰가 적은 grep 검증을 test:unit 게이트로 옮긴 것이다.
버린 대안
- CHANGELOG 표에 라운드 열 추가: "그 밖의 수정" 목록에는 표가 없어 규칙이
둘이 된다. ID 자체에 붙이는 쪽이 코드 주석·커밋 제목과 같은 형식이다.
- 접두어를 `YYYYMMDD/`로: 이미 브랜치의 커밋과 리뷰 README가
`0929/03-01` 형식을 쓴다. 해가 바뀌어 월일이 겹치면 그때 연도를 붙인다.
위험·한계
- 기존 주석과 0.2.0 커밋 제목은 라운드 없는 ID로 남는다(혼재 기간).
- 테스트는 괄호 안 쉼표 구분 토큰만 본다. 괄호 밖 본문에 쓴 ID는 잡지
않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
실패 "expected [ '03-03', '03-01', '08-03', …(95) ] to deeply equal []"
- GREEN: 같은 테스트 통과. 리뷰의 검증 명령
`grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md` → 0
- eslint, tsc(test), verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS(새 테스트 파일이 test:unit 게이트에 들어감)
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-02
문제
verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에
"FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를
적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을
더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면,
개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을
안다.
고른 방법
- 검사 네 개(route scope, runtime variables, review report digest,
diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로
정한다. 판정 조건은 그대로다.
- 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로
빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지.
- 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은
그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다.
버린 대안
- route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도
같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다.
위험·한계
- diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지
않는다. 산출물 JSON의 results에 그대로 있다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가
"Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name
route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다
- GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락,
route+변수 누락)
- 실제 repo에서 verify-documentation-readiness PASS_SCOPED
- eslint, tsc(node, test), check-ci-contract PASS
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06
문제
`npx vitest run tests/unit/ci-workflow-generation.test.ts`는 79건이
"CI runner npm scope environment invalid"로 실패한다(415건 중). npx와
npm을 거친 IDE 실행기는 npm_config_prefix·_userconfig·_globalconfig를
넣는다. CI 게이트 preflight(withCiGatePreflight)는 실제 runner에서 이
변수들을 거절하는데(옳은 동작), 테스트가 그 preflight를 프로세스 안에서
부르거나 자식으로 띄우면서 실행기의 process.env를 그대로 물려받는다.
scripts/run-vitest.ts만 그중 일부를 지워서 pnpm 경로만 통과한다. 원인은
timeout이 아니라 이 환경변수다.
고른 방법
- vitest.config.ts가 NODE_ENV를 고정하는 자리에서 npm scope 변수를 지운다.
config는 worker를 띄우기 전에 메인 프로세스에서 평가되므로 worker와 그
자식 프로세스 모두 깨끗한 환경으로 시작한다. 어느 실행기로 돌리든,
어느 테스트 파일이든 한 곳에서 막는다.
- 지울 이름은 preflight가 쓰는 것과 같은 판정
(package-script-graph.ts의 isNpmScopeEnvironmentName, 기존 private 함수를
export)으로 고른다. 목록이 둘로 갈라지지 않는다.
- ci-workflow-generation.test.ts에 "테스트 프로세스에 npm scope 변수가
없다"는 테스트를 더했다.
버린 대안
- 해당 테스트 파일의 beforeEach/afterEach에서 지우고 되돌리기(리뷰의 최소
방향 1): 같은 preflight를 띄우는 다른 파일이 생기면 다시 깨진다.
- 실행 함수가 환경을 인자로 받게 하기: 자식 프로세스는 여전히 process.env를
물려받아 실패한다.
- run-vitest.ts의 하드코딩 목록 정리: 이번 수정으로 필요 없어지지만, product
index 생성 자식에도 쓰이고 동작이 같아 건드리지 않았다.
위험·한계
- 실제 게이트 실행기의 npm scope 거절은 그대로다. 테스트 안에서 일부러 변수를
넣는 기존 테스트 3건도 그대로 통과한다.
- tests/unit 밖(component, integration 등)은 npx로 돌려 보지 않았다.
검증
- RED: npx vitest run tests/unit/ci-workflow-generation.test.ts -t
"npm-launched runner" 실패 "expected [ 'npm_config_userconfig', …(2) ] to
deeply equal []". 수정 전 같은 파일 79 failed / 336 passed
- GREEN: npx vitest run tests/unit/ci-workflow-generation.test.ts
416 passed
- npx vitest run tests/unit: 171파일 2,401 passed
- tsc(node, test), eslint 바뀐 파일 통과
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-05
문제
fix/ui-design-audit-2026-11-01 브랜치에는 다운스트림(tech-log, memento)이
따라 고쳐야 하는 변경이 쌓였는데 CHANGELOG에 한 줄도 없다. 특히
298201f(15-01)는 FeatureModule 모양을 바꾸는 BREAKING 변경이라, 커밋
본문의 BREAKING CHANGE 꼬리말만으로는 기존 기능을 어떤 순서로 옮겨야
하는지 알 수 없다. 영역 14는 check:design-system 규칙 추가가 CHANGELOG에
없다고 지적했고, 영역 07 수정(증거 형식, 분류 판정, TEMPLATE_FIXTURE
거부, 폐기 별칭 lint)도 [계약] 행이 필요하다고 각 커밋이 적었다.
고른 방법
- 기존 형식(버전 절 → 보안·계약 표 → 그 밖의 수정 → 알려진 제한)을 따라
"미출시 — 브랜치 fix/ui-design-audit-2026-11-01" 절을 0.2.0 위에 둔다.
버전 번호는 정하지 않았다. 리뷰 ID는 1101/14-02 규칙대로 라운드를
붙였다.
- 15-01은 "먼저 할 일" 절로 따로 뺐다. 298201f 본문과
src/features/reference-feature/의 실제 모양(feature-module.ts,
feature-runtime.ts, context-routes.ts, contracts/reference-api-contract.ts,
installed-contract-contributions.ts, feature-module.ts 타입)을 근거로 아홉
단계를 적었다.
- [계약] 표에 15-01, FE-GATE-012 merge 이동, 0929/03-01·09-01·0929/04-01·
0929/06-01(High), check:design-system 규칙 4개, 시각 테스트 fonts.conf와
runner 글꼴 패키지, 0929/07-01·0929/07-02·07-04·07-01, 05-01, 12-05,
13-04를 넣었다. 경로는 각 커밋의 변경 파일과 대조했다.
- 커밋 해시는 브랜치에 있는 해시다. 영역 07 등 합쳐진 수정은 브랜치의
cherry-pick 해시(5e6be9a 등)를 쓴다.
버린 대안
- 0.3.0 같은 버전 절을 미리 만들기: 버전 번호는 이번 작업에서 정하지
않는다.
- 15-01 이행 순서를 starter-experience.md만 가리키기: 그 문서는 새 기능
추가 순서라, 이미 있는 기능을 옮기는 단계(runtimes 삭제, features.load
호출, fake의 load)가 없다.
위험·한계
- 이 worktree에 없는 커밋(5e6be9a까지 브랜치에 합쳐진 것)은 커밋 본문과
변경 파일 목록으로만 확인했다. 이후 합쳐지는 수정은 이 절에 없다.
- 13-04·13-05·15-02·14-02·14-06·15-05 행의 해시는 이 worktree의 해시라
브랜치에 옮길 때 바뀔 수 있다.
- registry-baseline의 source 경로, feature-shape-growth 기준선, 08-01 서랍
시각 골든은 알려진 제한에 적기만 했다.
검증
- node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
tests/unit/deletable-history-documents.test.ts: 2 passed
- grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md → 0, 새 절 본문의 라운드
없는 ID 0
- verify-documentation-readiness PASS_SCOPED
문제: reconnect coordinator, live/poll handoff, SSE onOpen·onEvent,
WS onSubscribed·onEvent는 받은 RealtimeResult를 2단계로 동결된
객체만 받는다. 타입은 Readonly일 뿐이라 같은 모양의 평범한 객체도
컴파일된다. 그런데 동결된 결과를 만드는 realtimeSuccess /
realtimeFailure는 result.ts에만 있고 배럴에 없다. 조합 코드는 배럴만
import할 수 있으므로 결과를 손으로 만들게 되고, 그러면 첫 실패나 첫
종료에서 PROTOCOL_MISMATCH·MAPPING_CONTRACT_VIOLATION으로 재시도
없이 끝난다. 이 규칙은 주석에도 없었고, reconnect 경계의 동결 검사
3곳을 지워도(MU4) 테스트가 모두 통과했다.
고른 방법: 리뷰 6.2절의 (b). 배럴 src/adapters/realtime/index.ts에서
두 함수를 export하고(추가만, 기존 시그니처 변화 없음), 엄격한 경계의
타입 주석(RealtimeReconnectOutcome, RealtimeReconnectSession,
confirmTransportBarrier, handoff apply·establishAuthoritativeCheckpoint,
SSE onOpen·onEvent, WS onEvent·onSubscribed)과 생성 함수 주석에 규칙을
적었다. 동결 규칙 자체와 DEFAULT_RETRYABLE 기본값은 그대로다.
버린 대안:
- (c) 엄격한 경계도 stream coordinator처럼 한 번 복사하기. 규칙이
하나가 되지만 "검증한 실패 객체를 그대로 돌려준다"(toBe) 계약을
깬다.
- (d) 생성 함수를 application port(shared.ts)에 두기. feature 코드도
쓸 수 있게 되지만 application 계층에 런타임 헬퍼가 는다. handoff
apply를 feature가 구현한다고 정해지면 그때 옮긴다.
- 런타임 오류 이름을 따로 두기(예: RESULT_NOT_FROZEN). failure kind
어휘가 바뀌는 계약 변경이라 이번 범위 밖이다.
위험·한계:
- 동결하지 않은 결과는 여전히 컴파일된다. 타입으로 막으려면 brand가
필요하고, 그건 공개 타입을 깨는 변경이다. 주석과 테스트로만 알린다.
- realtime 레시피 번들 40,863 -> 40,879 / 40,900 gzip B(+16 B, 여유
21 B). 예산은 그대로다.
검증:
- RED: 새 테스트 "retries a failure built with the barrel's
realtimeFailure"가 수정 전 `TypeError: realtimeFailure is not a
function`으로 실패(1 failed | 43 passed).
- 새 테스트 4건(시도의 평범한 실패, 동결된 실패 안의 평범한 error,
classifyClosed의 평범한 성공 -> PROTOCOL_MISMATCH, 재시도 없음)과
handoff apply의 평범한 성공 -> MAPPING_CONTRACT_VIOLATION 1건.
- MU4(reconnect 동결 검사 3곳 제거)를 다시 넣으면 새 테스트 3건이
실패한다(수정 전에는 생존).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/` ->
14파일 230건 통과.
- `npx tsc --project tsconfig.app.json --noEmit`,
`npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 파일 8개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
`node scripts/check-adapter-inventory.ts` -> PASS,
`node scripts/check-optional-recipes.ts` -> PASS(realtime 40879/40900).
Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-01, 6.2절
문제: 설계 13.1은 IDLE_TIMEOUT을 "heartbeat/byte deadline 초과 ->
close + bounded reconnect" 한 뜻으로만 적는다. 코드는 같은 kind를
내부 task 마감에도 쓴다. stream coordinator는 effect·recovery·close
drain 마감을 IDLE_TIMEOUT/APPLY·RECOVER·CLOSE(retryable false)로,
handoff coordinator는 quiescence·checkpoint·close 마감을
IDLE_TIMEOUT/RECOVER·CLOSE(기본값 retryable)로 보고한다. 13.1만 보고
조합 코드를 쓰면 내부 마감도 재연결 대상으로 읽는다.
RED(문서-코드 대조): 13.1 행은 transport 뜻 하나. 코드에서
IDLE_TIMEOUT을 만드는 곳은 transport 3곳(SSE RECEIVE, WS RECEIVE·
SUBSCRIBE)과 내부 task 7곳(stream-coordinator.ts 3곳,
live-poll-handoff-coordinator.ts 4곳). stream coordinator close()
주석은 "IDLE_TIMEOUT이면 아직 DRAINING"을 공개 계약으로 적는다.
고른 방법: 리뷰의 (b). 13.1 IDLE_TIMEOUT 행을 코드에 맞춰 두 뜻,
operation으로 구분하는 법, 각 경우의 recovery, 관측에서 구분되지
않는다는 한계를 적는다. 코드는 바꾸지 않는다.
버린 대안: (a) stream coordinator의 마감을 APPLY_FAILED·
PROVIDER_UNAVAILABLE로 바꾸기. 리뷰는 코드 3곳으로 봤지만 같은 관례가
handoff coordinator 4곳에도 있고, stream coordinator close()의
IDLE_TIMEOUT은 주석에 적힌 공개 계약이다. 바꾸려면 두 coordinator의
마감 어휘를 함께 정해야 하므로 별도 결정으로 남긴다.
위험·한계:
- 리뷰 완료 기준 중 "effect 마감과 전송 idle을 관측에서 구분"은
충족하지 못했다. reconnect 관측(RUN_ENDED)에 operation이 없다.
(a) 또는 관측에 operation 추가가 필요하다.
- handoff 마감 결과가 retryable true(kind 기본값)이고 stream
coordinator는 false인 차이는 문서에 적기만 했다.
검증:
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- 코드 변경 없음. 테스트 미실행(해당 없음).
Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02, 6.3절
문제: Web Push 정상 클릭은 registry path를 origin 기준으로 풀었다
(`new URL(path, origin)`). 거절된 클릭은 이미 앱 루트(=
registration.scope = router base path)를 쓴다(06-09). 그래서
VITE_ROUTER_BASE_PATH=/app/ 배포에서 열린 창이 없으면 정상 클릭이
https://host/inbox, 즉 앱 밖을 열었다. registry에 /app/inbox를 넣으면
openWindow는 맞지만 같은 값이 handoff path로 페이지에 가서 router
basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수
없었다.
고른 방법: registry path를 "base path를 뺀 앱 기준 경로"로 정하고,
클릭 어댑터가 앱 루트의 pathname(끝 / 제외)을 앞에 붙여 openWindow
대상을 만든다. handoff path는 registry 값 그대로 둔다. same-origin·
userinfo·hash 검사(safeTarget)는 그대로 거친다. 규칙은
WebPushNotificationDefinition.path 주석, appRootUrl 주석, 설계 8.5절에
적었다. 앱 루트가 origin 루트(기본값)면 결과가 전과 같다.
버린 대안: 리뷰가 적은 `new URL(path.slice(1), appRootUrl)`. 앱 루트가
/로 끝나지 않으면(`https://host/app`) 마지막 segment가 사라지고,
`/a:b` 같은 경로는 `a:b`가 scheme으로 읽혀 거절된다. pathname을 앞에
붙이면 두 경우 모두 의도대로 된다.
위험·한계:
- realtime 레시피 번들(web-push 포함) 40,879 -> 40,897 / 40,900 gzip
B(+18 B, 여유 3 B). 예산은 그대로다. 다음 realtime·web-push 변경은
예산 인상과 함께 와야 한다.
- 페이지가 handoff path를 basename 기준으로 쓰는지는 제품 코드 몫이라
확인하지 않았다(템플릿에는 handoff 소비자가 없다).
- 실제 브라우저·푸시 서비스에서는 실행하지 않았다.
검증:
- RED: 새 테스트 "opens an accepted click's route under the base
path"가 수정 전 openWindow 인자 `https://app.example.test/inbox`
(기대 `https://app.example.test/app/inbox`)로 실패(1 failed | 19
passed).
- GREEN: 같은 테스트가 통과하고, 열린 창에는 handoff path `/inbox`가
간다. `node scripts/run-vitest.ts run tests/unit/web-push
tests/unit/sub-path-deployment.test.ts
tests/unit/service-worker-web-push-remediation.test.ts` -> 8파일
82건 통과(web-push-worker-runtime 20건 포함).
- `npx tsc` app·test·service-worker -> 오류 0.
- `npx eslint <바꾼 ts 3개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
`node scripts/check-optional-recipes.ts` -> PASS(realtime
40897/40900), `node scripts/verify-documentation-readiness.ts` ->
PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-01
문제: 운영 문서(browser-file-storage-recovery.md 8절)는 "활성화는
페이지의 requestActivation()으로만 일어나므로 새 worker 활성화를
멈추려고 따로 할 일은 없다"고 적는다. 브라우저는 scope의 탭이 모두
닫히면 waiting 워커를 스스로 활성화한다. 운영자가 이 문장을 믿고
결함 있는 waiting 워커를 두면, 탭을 닫았다 연 사용자부터 그 워커를
쓰고 대응(REMOVE_REGISTRATION)이 늦어진다.
RED(문서-코드 대조): install은 skipWaiting()을 부르지 않는다
(service-worker-entry.ts). requestActivation()은 src에서 정의
(service-worker-page-controller.ts, contracts/service-worker.ts)만 있고
부르는 곳이 없다. 저장소 e2e 주석(service-worker-update.spec.ts)과
리뷰 실험 8(chromium·webkit)은 탭을 모두 닫으면 B가 활성화되고
reload만으로는 waiting에 남는 것을 보였다. 같은 저장소의
release-cache-rollback.md는 이미 "every tab of the scope closes or a
page calls requestActivation()"으로 맞게 적는다.
고른 방법: 문장을 두 활성화 경로(requestActivation 성공, scope의 탭이
모두 닫힘)와 reload만으로는 활성화되지 않는다는 점, 템플릿의 기본
경로, 결함 있는 waiting 워커에 대한 조치(다음 release로 교체 또는
REMOVE_REGISTRATION)로 고친다. 코드는 바꾸지 않는다.
버린 대안: 없음. 리뷰가 문서 정정 하나만 제시했다.
위험·한계: 이번에 브라우저 실험을 다시 하지 않았다. 근거는 표준 SW
수명주기, 저장소 e2e 주석, 리뷰 실험 8이다. firefox는 Playwright에서
페이지가 제어되지 않아 확인 범위 밖이다.
검증:
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- `grep -rln requestActivation src tests` -> src는 정의 2파일뿐.
Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-02, 7.2절
문제: SW 자산 생성기(scripts/generate-service-worker-assets.ts)가 사전
캐시 URL을 `/${relative}`로 만들어 VITE_ROUTER_BASE_PATH를 무시했다.
워커는 root-relative URL을 scope 기준으로 풀지만 base가 사라지므로
/app/ 배포에서 install이 /assets/...를 요청해 404를 받고, 워커가
설치되지 않았다. 같은 빌드의 SW 설정도 runtime config URL 기본값을
"/config.json"으로 고정해, 페이지가 쓰는 /app/config.json을 워커가
network-only로 알아보지 못했다. 앱 빌드·runtime config·06-08
fallback은 이미 base를 따르는데 이 두 곳만 빠져 있었다.
고른 방법: 리뷰가 적은 최소 방향. collectStaticAssets에 basePath
인자(기본 "/")를 더하고, 생성기 main과 SW Vite 설정이 페이지와 같은
getBuildConfig(src/contracts/env.ts)로 base와 runtime config URL을
계산한다. 결과 URL은 그대로 root-relative라 isCanonicalStaticAssetUrl
검사를 통과한다. base가 "/"이면 manifest와 digest가 전과 같다.
버린 대안: 워커가 manifest URL을 scope 상대로 풀게 바꾸기. 계약 차이는
없지만 워커 코드와 manifest 계약(root-relative)을 함께 바꿔야 해서
생성기 수정보다 크다.
위험·한계:
- base마다 manifest digest가 달라진다(의도된 결과).
- VITE_RUNTIME_CONFIG_URL이 빈 문자열이면 이제 base 기본값을 쓴다.
페이지(getBuildConfig)와 같은 규칙이다.
- 리뷰 완료 기준의 "e2e 도우미를 base 옵션으로 돌린 첫 설치가
RELOAD_TO_ENABLE"은 하지 않았다. e2e 도우미에 base 옵션과 /app/
서빙이 필요하고, 실제 브라우저 install은 이번에 확인하지 않았다.
검증:
- RED: collectStaticAssets 단위 테스트(basePath "/app/")가 수정 전
`/assets/index-abcdefgh.js`를 받아 실패(1 failed | 9 passed).
service-worker-build-output.test.ts의 새 테스트(SW ACTIVE·
production·/app/ 실제 빌드)가 생성기만 되돌리면 URL 목록에서,
SW 설정만 되돌리면 `Received: "/config.json"`으로 각각 실패.
- GREEN: 두 테스트 통과. `node scripts/run-vitest.ts run
tests/unit/service-worker tests/unit/sub-path-deployment.test.ts
tests/unit/hosting-probe.test.ts tests/unit/web-push` -> 12파일
171건 통과(빌드 테스트는 flock 안에서).
- `npx tsc` node·test·app·service-worker -> 오류 0.
- `npx eslint <바꾼 파일 4개> --max-warnings=0` -> 통과.
- `node scripts/check-adapter-inventory.ts` -> PASS.
- 미실행: SW e2e(Playwright).
Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-02, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
문제: SW e2e 도우미(prepareServiceWorkerBuilds)는 사본의
`const SERVICE_WORKER: InstalledServiceWorkerSelection | null = null;`
줄을 글자 그대로 찾아 ACTIVE로 바꿨다. 이미 SW를 켠 제품 트리에는 이
줄이 없어서 beforeAll이 throw하고 update·recovery spec이 모두 멈춘다.
이 spec이 실제로 필요한 곳이 바로 SW를 켠 제품이다. setup이 실패하면
spec이 root를 받지 못해 /tmp/ca-sw-builds-* 사본도 남았다.
service-worker-build-output.test.ts도 같은 치환을 했다.
고른 방법: selectActiveServiceWorker(root)를 도우미에 두고, SERVICE_WORKER
선언 전체를 값과 무관하게(정규식, 정확히 1개) ACTIVE_SELECTION으로
바꾼다. 두 픽스처가 이 함수를 쓴다. recovery spec이 ACTIVE_SELECTION을
다시 찾는 방식은 그대로 동작한다. setup 실패 때는 fixture-builds.ts처럼
사본을 지우고 다시 throw한다.
버린 대안: 리뷰가 함께 적은 "install spec 기대값을 dist/assets 전체 대신
생성된 service-worker-assets.ts 목록과 비교". ACTIVE 트리에서도 두 값이
같아 이번 결함과 무관하다. 제품이 사전 캐시 대상을 바꿀 때(0929/06-03)
다시 본다.
위험·한계:
- 선택 선언의 값에 `;`가 들어가면 정규식이 짧게 끊겨 "정확히 1개"
검사나 이후 타입 검사에서 실패한다(조용히 틀리지는 않는다).
- e2e는 chromium만 돌렸다. webkit·firefox는 미실행.
검증:
- RED: 작업 트리 선택을 ACTIVE로 바꾸고 SW e2e 2 spec(chromium,
webServer 없는 임시 설정)을 돌림 -> `Expected exactly one "const
SERVICE_WORKER: ... = null;"`로 2 failed, 4 did not run, 사본 2개
잔류.
- GREEN: 같은 ACTIVE 트리에서 6 passed. 선택을 null로 되돌린 템플릿
트리에서도 6 passed. 잔류 사본 0.
- 새 단위 테스트(null·ACTIVE·REMOVE_REGISTRATION 선택 -> ACTIVE) 포함
`node scripts/run-vitest.ts run
tests/unit/service-worker-build-output.test.ts` -> 5 passed(ACTIVE
트리와 null 트리 모두).
- `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 파일 2개> --max-warnings=0` -> 통과.
Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-04, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
문제: 라우터는 context마다 gateway 하나를 그 루트 경로에 붙이고 기능
라우트를 그 안에서만 렌더한다. 레지스트리와 탐색 메뉴는 경로와 상관없이
모든 기능 라우트를 싣는다. 그래서 루트 `shop/*` context의 `/catalog`
라우트는 메뉴 링크로 나오고 그 URL은 NOT_FOUND가 된다. 같은 루트를 쓰는
context가 둘이면 id가 늦은 쪽 전체가 닿지 않는다. 어떤 게이트도 경로와
루트를 비교하지 않았다.
고른 방법: `defineDeployableAppModule`이 context별 기능 계약 라우트를
React Router `matchRoutes`로 전체 context 루트에 맞춰 보고, 그 라우트를
받는 context가 소유 context가 아니면 라우트 id·경로·기능 id·context
id·루트를 담아 throw한다. 앱 모듈은 부트 정적 그래프에서 평가되므로
부트 실패 화면과 라우터를 거치는 모든 테스트에서 드러난다. 라우터와 같은
매칭 규칙을 쓰므로 루트 밖 경로, `/`, 루트 없는 context, 같은 루트, 더
구체적인 다른 루트에 먹히는 경로를 한 검사로 잡는다. 중첩 루트 자체는
허용한다(`tests/component/context-route-gateway.test.tsx`가 쓰는 모양).
starter-experience.md 기능 추가 4단계에 규칙을 적었다.
버린 대안:
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다.
- `defineBoundedContextModule`에서 검사: 다른 context의 루트를 모른다.
같은 루트·중첩 루트를 앱 단위에서 따로 또 봐야 해서 검사가 두 곳이 된다.
- 루트 문자열 접두어 비교: `:param`·splat 규칙을 다시 구현하게 된다.
위험·한계:
- 리뷰 09-06의 (3) "context 라우트 핸들의 route id가 레지스트리에 있는가"는
넣지 않았다. 핸들은 `context-routes.ts`를 읽어야 보이는데 이 파일은 늦게
읽어야 한다. 헬퍼 제공과 적재 시 검사 중 고르는 설계 선택이라 남긴다.
그 실패의 진단 누락은 09-09에서 다룬다.
- 플랫폼 라우트와 기능 라우트의 경로 충돌은 검사하지 않는다.
- 초기 JS +239 B gzip(202,509 → 202,748 B, 여유 2,291 → 2,052 B).
같은 worktree에서 `vite build` 두 번으로 쟀다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 7건 중 거절 5건이
"expected [Function] to throw an error"로 실패(수정 전, 298201f 기준).
- GREEN: 같은 파일 7건 통과.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
94 files / 588 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
1,929 tests 통과. tsc app·test·node 통과. 바꾼 파일 eslint 통과.
check-architecture.ts(pnpm exec를 node_modules/.bin으로 넘기는 shim)
통과.
문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는
`onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는
buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중
throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이
없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의
route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자
신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다.
고른 방법:
- `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에
넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존
ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작).
- incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두
경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다).
- gateway가 두 경계에 `reportRenderFailure` 호출과
`<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는
`component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에
context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다.
- 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를
탄다. route id는 URL의 등록 라우트, 없으면 context id다.
버린 대안:
- 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계
두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시
(`data-boundary`, testid)가 바뀐다.
- gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기:
두 경계가 같은 id를 공유해 사건 구분이 흐려진다.
- `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과
레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다.
위험·한계:
- `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로
buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식
(useRouteError + 마운트 시 보고)이 필요해 남겼다.
- 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다
한 번 보고한다.
- 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의
지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다.
- 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B).
검증:
- RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context
경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이
모두 `Unable to find an element with the text: /^지원 참조:
build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다.
- GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한
incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.
check-architecture(shim), check-adapter-inventory, check-diagnostics,
check-registries 통과.
문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱
조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다.
참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로
레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서
rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다.
고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와
함께 한 오류로 던진다. 예: "REST security profiles are incoherent for
CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER."
operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부
두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를
넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는
테스트·로그 검색은 계속 맞는다.
버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상
깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시
봐야 한다.
위험·한계:
- 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을
별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리
기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와
사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은
사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그
작업에 남는다.
- 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가
초기 청크에 있어 오류 문장이 그대로 실린다.
검증:
- RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가
"expected [Function] to throw error matching /incoherent.*
CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are
incoherent.'"로 실패.
- GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우).
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration
(프로세스를 띄우는 3개 제외) 131건, tests/{contract,features,
runtime-schema,component,architecture,platform} 626건 통과. tsc app·test
통과. 바꾼 파일 eslint 통과.
문제: 선택 파일은 "Adding an entry here is what installs a capability"라고
적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다.
realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지
않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그
선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다.
고른 방법:
- `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime,
webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아
throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지
않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다.
- 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는
composition에 런타임을 먼저 연결해야 한다"로 고쳤다.
버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은
여전히 아무 신호도 받지 못한다.
위험·한계:
- 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야
한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다.
- health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만,
런타임을 연결할 때 쓸 자리라 남겼다.
- 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다.
- 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B).
검증:
- RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별
하나)이 "expected [Function] to throw an error"로 실패.
- GREEN: 같은 파일 9건 통과.
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration
(프로세스를 띄우는 3개 제외) 131건, tests/{component,platform,
architecture,features,contract} 570건 통과. 그중
app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고,
heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일
eslint 통과.
문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.
고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.
버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
실패를 다시 만들어 이 값을 읽지 않는다.
위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
(4b0e44a9)대로 55,800으로 올렸다.
- 포트 반환 타입이 넓어졌으므로 CHANGELOG [계약] 한 줄이 필요하다.
이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 4건 실패.
발급·PUT이 `429 Retry-After: 5`일 때 "expected 0 to be greater than
or equal to 5000"(첫 sleep 0ms). maxRetryAfterMs 1000을 넘을 때
재시도해서 ok:true. resumable-upload-http-control-plane.test.ts 새
1건 실패: 브리지 결과에 retryAfterMs 5000이 없다.
- GREEN: 두 파일 33건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·
upload-cancellation·json-schema 단위 21파일 322건 통과. tsc app·
test·node·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
(exec 전용 shim, pnpm 미사용) 통과, check-adapter-inventory 통과,
check-optional-recipes(source) PASS file-transfer 55725/55800.
Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
문제: resolve()는 통과한 probe 기록(passedProbes)을 slot을 기다리기
전에만 본다. 같은 asset·preset을 동시에 5번 resolve하면 probe가 5번
돈다. probe마다 preset의 encoded 예산까지 no-store로 내려받고
decode하며, 같은 이미지가 probe slot을 차지해 다른 이미지의 probe가
밀린다.
고른 방법: asset·preset별로 "진행 중인 probe 단계"(slot 대기, probe,
통과 기록)를 promise 하나로 둔다. 뒤에 온 호출은 그 단계가 끝나기를
자기 signal로 기다린 뒤 기록된 통과를 재사용한다. probe 자체를
공유하지 않으므로 호출마다 abort가 독립이다. 앞선 probe가 실패하면
기다린 호출이 직접 probe한다(실패는 재사용하지 않는다는 기존 규칙).
X5(동시 5회, maxConcurrentProbes 2)에서 probe가 1회다.
버린 대안:
- 리뷰가 제안한 slot 획득 뒤 재확인. 넣어 보니 X5에서 probe가 3회로
완료 기준(2회 이하)을 못 맞춘다. slot은 원시 probe가 끝날 때
넘겨지는데(TR-RR-07), 통과 기록은 그보다 몇 microtask 뒤에 남는다.
다음 대기자가 기록 전에 깨어난다.
- 진행 중 probe의 결과를 공유(single-flight). 호출자마다 signal이
달라 참조 수를 세야 한다.
- slot 해제를 통과 기록 뒤로 미룬다. 해제 지점이 원시 probe 정착과
wrapper 종료 두 곳으로 갈라진다.
위험·한계:
- 대기 뒤 재사용할 때 만료를 따로 다시 보지 않는다. 통과를 기록한
호출이 기록 직전에 만료를 봤고, 대기자는 같은 task 안에서 이어서
실행된다. 시작할 때의 만료 검사(기존)는 그대로다.
- 앞선 probe가 실패하면 기다리던 호출들이 각자 probe한다(slot 수로
묶임). 실패가 반복되는 이미지는 지금과 같은 수의 probe가 돈다.
- probe 블록을 try/finally로 감싸면서 들여쓰기가 바뀌었다. 로직
변경은 `git show -w`로 보면 짧다.
- file-transfer 레시피 번들이 55,725 → 55,856 gzip bytes가 되어 예산
55,800을 넘었다. 다음 백 단위로 올리는 기존 규칙대로 55,900으로
올렸다.
검증:
- RED(수정 전 코드에 새 테스트): "probes once and lets the other calls
reuse the pass"가 "expected vi.fn() to be called 1 times, but got 5
times"로 실패. 재확인 안(버린 대안)에서는 2회 기대에 3회로 실패.
나머지 새 테스트 2건(앞선 probe 실패 시 대기자가 직접 probe, 대기
중 abort가 진행 중 probe를 끊지 않음)은 새 분기를 고정한다.
- GREEN: image-cdn 단위 3파일 37건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·json-schema
단위 20파일 323건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint
통과. check-optional-recipes(source) file-transfer 55856/55900.
Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
문제: 이미 stage된 release를 다시 stage하면 후보를 재검증한다.
재검증 함수 verifyReleaseCandidate는 활성화와 같이 쓰는 함수라 실패
Result의 operation을 CACHE_ACTIVATE로 만든다. 활성화 경로는
rebaseFailure로 바꾸지만 stage의 재사용 경로는 그대로 돌려준다.
Cache API가 재검증 중 일시 오류를 내면 stage 결과와 관측이 모두
CACHE_ACTIVATE가 된다. 운영자는 "활성화 실패"로 읽고, error.operation
으로 분기하는 호출자는 잘못된 경로를 탄다.
고른 방법: stage 재사용 경로도 활성화 경로처럼
rebaseFailure(..., "CACHE_STAGE")로 돌려준다. 한 줄이다.
버린 대안: verifyReleaseCandidate가 operation을 인자로 받게 하는 안.
호출부 세 곳(stage, activate, inspect)을 모두 바꾸고, inspect는 실패를
밖으로 내지 않아 이득이 없다. 리뷰가 함께 적은
readAndValidateResponse의 CACHE_STAGE 고정은 두 소비 경로가 이미
rebase하거나 결과를 내보내지 않아 겉으로 드러나는 결함이 없으므로
건드리지 않았다.
위험·한계: 동작(실패를 성공으로 바꾸지 않음, 후보를 지우지 않음)은
그대로다. 바뀌는 것은 실패의 operation 값뿐이다. service-worker-pwa
레시피 번들 9,662 → 9,665 / 10,000 gzip bytes.
검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 1건이
operation "CACHE_ACTIVATE"(기대 "CACHE_STAGE")로 실패.
- GREEN: public-response-cache 단위 3파일 37건 통과.
- 회귀: tsc app·test·service-worker 통과. 바꾼 파일 eslint 통과.
check-optional-recipes(source) PASS.
Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이
INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random
실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그
함수가 reason을 고정한다. bootstrap은 이 reason을 그대로
cache.operation.failed 진단에 싣는다. 난수 실패나 topic version
불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다.
고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는
이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사
실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason
값은 만들지 않는다. 호출자에게 돌려주는 결과
{ok:false, reason:"INVALID_EVENT"}는 그대로다.
위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는
대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가
없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는
수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해
이 worktree에서 돌리지 않았다.
검증:
- RED(수정 전): cross-tab-invalidation.test.ts 새 1건이
"expected [ 'INVALID_ENVELOPE' ] to deeply equal
[ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패.
- GREEN: 같은 파일 통과.
- 회귀: cross-tab-invalidation·tanstack-cache-coordinator·
runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일
eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
문제: runtime은 object URL lease registry 하나를 preview와 download에
같이 넘긴다. 두 쪽의 dispose()가 모두 registry 전체의 dispose()를
불러, 누가 만든 lease인지 구분하지 않고 전부 revoke한다.
runtime.previews.dispose()를 부르면 30초 grace 중인 download blob
URL까지 바로 revoke된다(E-9). 브라우저가 아직 blob을 읽기 전이면 그
download가 실패할 수 있다. 반대로 download의 dispose()는 다른 화면의
preview URL을 끊는다. registry 주석은 이 dispose를 "route teardown"
에서 쓰라고 읽혔다.
고른 방법(리뷰 5.2절의 (나)): 한도는 같이 쓰고 해제 권한만 나눈다.
registry에 scope()를 두어 소비자마다 자기가 만든 lease 집합을
들고, scope의 dispose()는 그것만 release한다. preview와 download
adapter는 각자 scope로 lease를 만든다. registry 전체 dispose()는
runtime.dispose()만 부른다. 포트 시그니처는 그대로이고,
TransientPreviewPort.dispose()에 효과 범위를 주석으로 적었다. 설계
문서 3.5절에 해제 권한과 route 정리 방법을 적고, 바뀐 줄 번호를
맞췄다.
버린 대안:
- 포트 주석만 고친다(가). 함정이 코드에 그대로 남는다.
- 소비자마다 registry를 나눈다(다). 해제 범위는 맞지만 탭 전체의
합계 바이트 상한이 두 곳으로 갈라진다.
- TransientPreviewPort에서 dispose()를 뺀다(라). 공개 포트 변경이라
이번 범위(포트는 추가만)를 넘는다. (나)와 함께 할 수 있어 남겨 둔다.
위험·한계:
- previews.dispose() 뒤 그 runtime의 preview가 계속 UNAVAILABLE인
것(영향 ②)과, previews.dispose()가 다른 화면의 preview lease까지
푸는 것(영향 ①, 같은 소비자 안)은 그대로다. 문서에 route 정리는
lease마다 release()로 하라고 적었다. 완전히 막으려면 (라)가 필요하다.
- scope가 들고 있는 release 함수 집합만큼 메모리가 조금 는다. lease
release 때 집합에서 빠지므로 lease 수 상한(기본 16)을 넘지 않는다.
- file-transfer 레시피 번들이 55,856 → 55,937 gzip bytes가 되어 예산
55,900을 넘었다. 다음 백 단위 규칙대로 56,000으로 올렸다.
검증:
- RED(수정 전): browser-file-runtime.test.ts 새 1건 "expected
[ 'blob:runtime-download' ] to deeply equal []"(previews.dispose()가
download URL을 revoke). browser-file-download.test.ts 새 1건
"expected [ 'blob:shared-1', 'blob:shared-2' ] to deeply equal
[ 'blob:shared-2' ]"(download dispose()가 다른 소비자의 lease를
revoke).
- GREEN: browser-file 단위 5파일 64건 통과. runtime dispose가 모든
lease를 즉시 revoke하는 기존 테스트도 통과.
- 회귀: browser-file·presigned·json-schema 단위 10파일 168건 통과.
tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
(exec 전용 shim) 통과, check-adapter-inventory 통과,
verify-documentation-readiness PASS_SCOPED,
check-optional-recipes(source) file-transfer 55937/56000.
Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
문제: active pointer를 읽을 때 rollback 목록 길이를 현재
retainedPreviousReleaseCount와 비교한다. 3에서 1로 줄이는 정상 설정
변경이나 pointer JSON 손상 뒤에는 읽기가 CORRUPT_DATA가 되고, 조회·
활성화·정리·inspect가 모두 여기서 멈춘다. control cache를 지우는 API가
없어 사용자가 사이트 데이터를 지우기 전까지 오프라인 캐시가 꺼진 채로
남고, cleanup이 막혀 배포마다 release cache가 쌓인다. 이번 라운드에도
Node와 실제 Cache API 3엔진에서 재현됐다.
고른 방법(지난 리뷰 4.1절의 (나)+(다)):
- (다) isActivePointer는 목록 길이를 현재 값이 아니라 정책이 허용하는
최댓값(5, MAX_RETAINED_PREVIOUS_RELEASE_COUNT)과만 비교한다. 정책
검증과 같은 상수를 쓴다. 다음 activation이 이미 하던 slice로 목록을
현재 값으로 자른다.
- (나) activateRelease는 이전 pointer 읽기가 CORRUPT_DATA면 없는
것으로 보고, 전체 재검증을 통과한 후보로 rollback 목록 없이
덮어쓴다. 일시 오류(UNAVAILABLE 등)는 지금처럼 활성화를 멈춘다.
버린 대안:
- 현상 유지 + "사이트 데이터 삭제" 안내. 운영자가 원인을 알 수 없고
캐시가 계속 쌓인다.
- control을 지우는 admin API. 포트가 늘고 호출자가 언제 불러야 하는지
알아야 한다.
- (다)만 적용. 정책 변경은 풀리지만 JSON 손상은 풀리지 않는다.
위험·한계:
- 지키던 성질은 그대로다. 검증한 후보만 활성화하고(재검증은 pointer
읽기 전에 끝난다), 조회는 manifest digest가 맞는 바이트만 돌려준다.
읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다.
손상 pointer 상태의 조회와 cleanup은 다음 activation까지 여전히
CORRUPT_DATA다.
- 덮어쓰면 손상 pointer의 rollback 목록을 잃는다. 원래 읽을 수 없던
값이다. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다.
그 탭의 조회는 네트워크로 떨어진다. Service Worker drain(VD-15)을
구현하면 이 규칙을 다시 본다(지난 리뷰 4.1절 7).
- 리뷰가 "가능하면"으로 적은 3엔진 browser spec(E-2)은 추가하지
않았다. 단위 테스트(MemoryCacheStorage)로만 확인했다.
- service-worker-pwa 레시피 번들 9,665 → 9,716 / 10,000 gzip bytes.
검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 2건 실패.
retained 3 → 1 뒤 조회가 { ok: false }(기대 ok:true), 잘린 pointer
뒤 다음 배포의 activate가 { ok: false }.
- GREEN: 같은 파일 8건 통과. 일시 오류 가드 테스트 1건을 함께 넣었다.
activate가 모든 pointer 실패를 무시하도록 바꾼 변이를 이 테스트가
잡는다(1건 실패 확인 뒤 되돌림).
- 회귀: public-response-cache 단위 3파일 40건 통과. tsc app·test·
service-worker·recipes 통과. 바꾼 파일 eslint 통과.
verify-documentation-readiness PASS_SCOPED. check-optional-recipes
(source) PASS.
Refs: docs/reviews/2026-09-29-maturity-review/02-adapters-browser-files-cache.md
문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고
적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표
밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고
retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른
행동을 가리킨다.
- ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true.
표대로면 RESELECT다.
- ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE.
다시 부르면 성공한다.
- ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새
session으로 성공한다.
- ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다.
- ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY):
RESUME. 서버가 같은 값을 다시 준다.
고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에
둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의
NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE.
나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나
REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는
번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다.
포트 표 주석과 설계 문서 표에 이 규칙을 적었다.
버린 대안:
- 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE
경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금
STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다.
- 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기
실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못
보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다.
- 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난
리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다.
위험·한계:
- ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object
store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로
고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다.
리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건
("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime
호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다.
그래서 이 발견은 부분 충족이다.
- 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나
(resumable-upload-runtime-contract.test.ts "rejects a part capability
that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다.
다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이
필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지
않았다.
- 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류
값을 주입했다.
- file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산
56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다.
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패.
① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대
RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대
NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다.
- GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면
retryable:false" 단언을 더했고 통과한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼
파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
check-architecture(exec 전용 shim) 통과. check-optional-recipes
(source) file-transfer 56031/56100.
Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
문제: "정확하지 않은 이벤트 계약을 거부한다" 테스트는 공용 fixture의
events가 빈 배열이라 첫 줄 `if (events.length === 0) return;`에서 끝난다.
단언이 하나도 실행되지 않는다. 그래서 composeContractContributions의
이벤트 snapshot(M17)이나 assertEventContract 호출(M18)을 빼도 관련
테스트가 모두 통과한다. 템플릿 안에는 이벤트를 기여하는 계약이 없어서
이 경로를 지키는 테스트가 따로 없다.
고른 방법:
- tests/helpers/external-contract-fixture.ts에 TEST_EVENT_CONTRACT를
추가한다. 공용 TEST_CONTRACT_CONTRIBUTION의 events는 그대로 비워 둔다.
이 fixture를 쓰는 다른 테스트 20여 파일의 전제를 바꾸지 않기 위해서다.
- 빈 배열이면 return하던 테스트를 지우고 "event contracts" 묶음을 둔다.
정상 행이 snapshot으로 설치되는지(같은 내용, 다른 객체, frozen) 먼저
확인해서 아래 거부 경우가 다른 이유로 throw하는 것이 아님을 보인다.
거부 경우는 HTTP 쪽 hostileRows처럼 모양(추가 필드, 다른 prototype,
accessor)과 내용(빈 eventType, 공백, C1 제어문자, 160바이트 초과,
validator 없음, 빈 schemaId), 중복 eventType이다.
ContractContributionError로 던지는지까지 본다.
버린 대안: tests/setup.ts에 전역 expect.hasAssertions()를 두는 방법.
같은 종류의 빈 테스트를 모두 막지만 모든 vitest 프로젝트의 테스트 계약을
바꾸고, 리뷰는 빠른 계층 8개 폴더에서만 확인했다. 이 발견의 범위를
넘는다.
위험·한계: 템플릿 안에서 eventByType을 읽는 코드는 여전히 없다. 이
테스트는 composition 단계의 검증만 고정한다.
검증:
- RED(변경 전 테스트 파일과 새 파일을 함께, 변이 적용):
M17(snapshotEventContract가 입력을 그대로 반환) — 옛 파일 16개 통과,
새 파일 4개 실패("installs a well-formed event contract as its own
snapshot", extra own field, custom prototype, accessor eventType).
M18(assertEventContract 호출 제거) — 옛 파일 16개 통과, 새 파일 6개
실패(빈·공백·제어문자·160바이트 초과 eventType, validator 2종).
- GREEN: node scripts/run-vitest.ts run
tests/unit/contract-registry-immutability.test.ts — 26 passed.
- related tests/helpers/external-contract-fixture.ts
src/contracts/external-contract-runtime.ts — 97파일 796 passed.
- tsc -p tsconfig.test.json, eslint(바꾼 2파일) 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-01
문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나
`it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다.
`context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고,
로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다.
check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(`
글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다.
고른 방법:
- vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다.
- scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에
state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다.
-t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다.
게이트는 실행을 좁히지 않는다.
- reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의
reporters를 대체하므로 config에 두면 package script에서 빠진다.
run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다.
호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다.
버린 대안:
- 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가
skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼
적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog,
로컬 단일 파일)은 아예 보지 못한다.
- tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이
돌지 않아 잡지 못한다.
- eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고
`context.skip()`을 못 잡는다.
위험·한계:
- run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지
않는다. allowOnly는 config라서 그때도 적용된다.
- 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다.
Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가
나온다.
- 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다.
- check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만
이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은
Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에
"quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도
quarantine이 필요해지면 허용 목록을 따로 둬야 한다.
- 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다.
검증:
- RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을
CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1
skipped | 1 todo"). only+CI=true만 exit 1.
- 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find
module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패.
- GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s)
did not run" 목록, only는 "Unexpected .only modifier". junit reporter를
준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트
11 passed.
- 빠른 계층 전체(unit·component·integration·contract·runtime-schema·
platform·architecture·features·release·scripts·recipes, pnpm 설치를
하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed,
1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트
inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록
출력은 없었다.
- tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일),
check-ci-contract, generate-ci-workflow --check,
verify-documentation-readiness(PASS_SCOPED) 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04
문제: 시각 회귀 허용치가 maxDiffPixelRatio 0.002(이미지의 0.2%)라서
긴 화면일수록 허용 픽셀이 커진다. 넓은 셸 1440×900은 2,592 px를
허용한다. 그래서 UI-04 수정을 되돌린 회귀(선택 상자 값 잘림, 1,145 px)가
통과한다. 골든이 코드와 조금씩 달라져도 실패하지 않아 어느 골든이 낡았는지
알 수 없다. VD-08 8항은 작은 rasterization 차이만 허용한다고 적는다.
고른 방법: maxDiffPixels 50. 11-02로 글꼴과 래스터 설정을 고정한 뒤
같은 호스트에서 깨끗한 빌드를 다시 찍으면 0 px 차이다(아래 검증). 50은
흩어진 anti-aliasing만 덮고, 지금까지 잰 가장 작은 실제 변화(낡은
compact 골든 175 px)보다 작다. tests/unit/visual-regression-tolerance.test.ts가
비율 허용치가 다시 들어오거나 절대값이 175 이상이 되면 실패한다.
버린 대안:
- 0 px: 이 호스트에서는 흔들리지 않았지만 다른 Linux 러너의 래스터는
재 보지 못했다(U-1). 50은 실제 회귀를 놓치지 않는 범위의 여유다.
- 위험 영역만 따로 찍어 비율의 분모를 줄이기: 골든이 늘어난다.
- 현상 유지: 회귀를 놓친다.
위험·한계:
- 커밋된 골든 2장이 새 허용치에서 실패한다. 깨끗한 빌드 기준으로 넓은
셸 614 px, compact 6,955 px 다르다. compact는 이 변경 전 0.2%에서도
이미 실패한다(08-01의 서랍 변경). 골든은 다시 찍지 않았다. 오케스트레이터가
마지막에 한 번 찍는다. 나머지 3장은 0 px로 통과한다.
- 다른 호스트의 래스터 차이는 재 보지 못했다. 수십 px 넘게 나오면 그
측정값으로 허용치를 정한다(리뷰 재검토 조건).
검증 (pnpm을 부르지 않으려고 build-frontend.ts로 빌드하고 webServer만
vite preview로 바꾼 로컬 설정 사본으로 실행, flock, 비교 대상은 깨끗한
빌드로 새로 찍은 scratch 골든. 저장소 골든은 건드리지 않았다):
- 깨끗한 빌드 vs scratch 골든, 허용치 0, --repeat-each=3: 16 passed.
- RED: UI-04 변이(f1b9d3c의 shell.css 변경을 git apply -R)를 넣은 빌드,
0.2% 비율: 6 passed. 허용치 0: 넓은 셸만 "1145 pixels are different".
- GREEN: 같은 변이, maxDiffPixels 50: 넓은 셸 실패(1,145 px), 나머지 통과.
변이를 되돌리고 다시 빌드, --repeat-each=2: 11 passed.
- 새 단위 테스트는 수정 전 "expected 0.002 to be undefined"로 실패,
수정 뒤 2 passed. supply-chain·deletable-history-documents·
test-evidence-source-rules와 함께 37 passed.
- tsc(node·test), eslint, check-test-evidence --source-only PASS,
verify-documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-03
문제: "Escape 뒤 포커스가 trigger로 돌아온다" 단언은 trigger를 클릭한
채로 Escape를 누른다. Popover는 열 때 포커스를 내용으로 옮기지 않으므로
포커스는 처음부터 끝까지 trigger에 있다. overlays.tsx의 Escape 처리에서
`triggerRef.current?.focus()`를 지워도(M15) 관련 테스트가 모두 통과한다.
내용 안의 버튼으로 Tab한 뒤 Escape를 누르는 키보드 사용자는 포커스를
잃어도 아무 테스트가 모른다(WCAG 2.4.3).
고른 방법: 열고 나서 Tab으로 내용 안의 "내부 작업" 버튼에 포커스를
옮기고, 그 버튼에 포커스가 있는지 먼저 단언한다. 그 뒤 Escape와 trigger
포커스 단언은 그대로 둔다. 리뷰 최소 개선안 그대로다.
위험·한계: 바깥 클릭으로 닫을 때의 포커스 반환(closeOutside)은 이
테스트가 보지 않는다. 이번 발견 범위 밖이다.
검증:
- RED(M15 적용): 변경 전 테스트 파일은 통과, 새 테스트는
"expect(element).toHaveFocus()" 실패(design-system-platform.test.tsx
trigger 단언).
- GREEN: 원본 overlays.tsx로 되돌리고 related overlays.tsx --run —
23파일 152 passed.
- eslint(바꾼 파일), tsc -p tsconfig.test.json 통과.
Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-02
문제: 테스트 전략 문서 13.4절은 "필수 baseline"으로 각 page template,
모든 primitive group, invalid form, 열린 dialog·drawer·menu,
pseudo-locale·RTL 등을 적는다. 실제 기준선은
tests/visual/platform.visual.spec.ts의 5장이다. invalid form, 열린
dialog·menu, RTL, page template별 기준선은 없다. check-test-evidence는
기준선이 4장 이상인지만 본다. 다운스트림이 이 목록을 보고 보호되지 않는
화면을 보호된다고 믿을 수 있다.
고른 방법: 리뷰 최소 개선안대로 목록을 "현재 기준선 5장"과 "제품이 늘릴
후보"로 나눈다. 5장마다 경로, viewport·테마·locale, 덮는 상태를 적고,
VD-08 5항의 최초 기준선 4장에 플랫폼 개요가 더해진 범위라고 밝힌다.
검사가 장 수만 본다는 것도 적는다. VD-08은 "최초 기준선은 … 포함한다"는
결정 기록이라 고치지 않았다(5장과 모순되지 않는다).
버린 대안: 기준선을 문서 목록만큼 늘리기. 골든이 늘고 11-03의 골든
재촬영과 겹친다. 리뷰도 기준선 확장은 11-02·11-03 뒤로 미뤘다.
위험·한계: check-test-evidence가 각 화면의 존재를 검사하게 바꾸지는
않았다. 문서만 고친다.
검증(문서와 코드 대조, RED 대신):
- 수정 전: 13.4절 목록 8항목 중 invalid form, open dialog/menu, RTL,
page template은 platform.visual.spec.ts의 5개 toHaveScreenshot과
__snapshots__ PNG 5장 어디에도 없다.
- 수정 뒤: 문서의 5장 이름이 __snapshots__ 파일 이름(-chromium-visual-linux
앞부분)과 일치. state 기준선이 401·403·404를 담는 것은
src/presentation/examples/state-gallery-page.tsx의 AuthRequired·
Forbidden·NotFound 표면으로 확인.
- verify-documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-04
문제: config/scale/feature-shape-growth.json에 측정 시각만 있고 어느
코드를 쟀는지가 없다. 기준선이 지금 코드와 맞는지, 다음 측정과 비교할 수
있는지 알 수 없다. 실제로 기준선은 2026-09-27 측정이고, 그 뒤 15-01이
초기 청크 구조를 바꿨다(ceilings.json도 "baseline predates 15-01"이라고
적고 있었다). 기준선 0개 초기 JS 200,001 B, 기능당 2,907 B는 지금 코드와
다르다.
고른 방법:
- 측정 스크립트가 시작할 때 `git rev-parse HEAD`와 추적 파일 변경 목록
(`git status --porcelain --untracked-files=no`)을 읽어 결과의
`source: { commit, modifiedPaths }`에 싣는다. 변경 목록이 비면 커밋만으로
재현된다는 뜻이다. 측정 중 트리가 바뀔 수 있어 시작할 때 읽는다.
- 기준선을 현재 코드로 다시 잰다(--sizes=0,25,100 --repeats=2 --write).
- ceilings.json의 수치를 새 기준선에 맞춘다. 초기 JS 여유는 리뷰 개선안대로
"예산 − 기준선 ÷ 기능당 증가"로 적는다(2,291 B ÷ 약 610 B ≈ 3개).
- 단위 테스트가 기준선에 40자 commit과 modifiedPaths 배열이 있는지 본다.
버린 대안:
- 기준선 커밋이 현재 이력의 조상인지 테스트로 확인: 이력 없이 3-way로
이식하는 다운스트림(tech-log)에서는 템플릿 커밋이 없어 항상 실패한다.
- dirty 트리면 --write를 거절: 이 커밋처럼 측정 스크립트와 기준선을 한
커밋에 넣을 수 없게 된다. 대신 변경 경로를 그대로 기록한다.
위험·한계:
- 기록된 커밋은 2be973a(이 브랜치의 직전 커밋)이고 modifiedPaths는 측정
스크립트와 그 테스트 2개다. 측정 대상(src, vite 설정)은 그 커밋과 같다.
이 브랜치를 rebase하면 기록된 SHA가 이력에서 사라진다. 그때는 다시 재야
한다.
- 시간 값은 호스트 부하(loadavg 27~29)에 따라 흔들린다. 바이트와
instantiation 수만 비교 대상이다.
- 15-01 커밋 본문의 202,361 B와 이번 0개 측정 202,509 B는 148 B 다르다.
원인은 확인하지 않았다. ceilings.json은 기준선 수치 하나로 통일했다.
검증:
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
-t 'commits a baseline' — "expected undefined to deeply equal { commit:
StringMatching…" 실패.
- 측정(flock): 0개 202,509 B·720,060 inst, 25개 218,010 B, 100개
263,119 B·12,399,171 inst, 반복 2회 바이트·inst 동일. 기능당 초기 JS
약 610 B, lazy 약 8.3 KB·8파일, inst 약 117k, tsc 메모리 약 36 MB,
route 4개.
- 재현: 같은 트리에서 --sizes=0,25 --repeats=1을 다시 돌려 0개 202,509 B,
25개 218,010 B로 같음.
- GREEN: feature-shape-growth.test.ts 5 passed(빌드 측정 테스트 포함).
- tsc(node·test), eslint(바꾼 2파일), verify-documentation-readiness
PASS_SCOPED.
Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-05
SW e2e는 템플릿의 `= null;` 줄만 바꿔 worker를 켰다. 제품이 이미 ACTIVE로
켠 트리에서는 2건이 실패하고 4건이 실행되지 않았다. 사전 캐시 목록도
템플릿 기준으로 고정돼 있어 해시 파일을 더하면 2건이 실패했다.
선택을 지금 값과 상관없이 고치되, 이미 ACTIVE면 제품의 handler를 그대로
두는 `turnOnServiceWorker` 하나로 모았다. 빌드가 만든 사전 캐시 목록을
`precached`로 돌려주고 spec이 그 목록과 비교한다. 같은 문제를 고친
0929/06-04(`96a4f68`)의 `selectActiveServiceWorker`는 ACTIVE 선택을
템플릿 값으로 덮어써 제품 handler가 빠지므로 이 함수로 바꿨고, 실패한
준비 단계에서 임시 복사본을 지우는 처리는 유지했다(두 브랜치 병합 때
오케스트레이터가 충돌을 풀었다).
위험: 테스트 도우미만 바뀐다. 0929/06-04 단위 테스트의 기대값이 "ACTIVE
선택도 템플릿 값으로 덮어쓴다"에서 "ACTIVE 선택은 그대로 둔다"로 바뀐다.
검증: ACTIVE 선택과 해시 파일 추가 트리 모두 6 passed(에이전트).
병합 뒤 service-worker-build-output 단위 테스트 5/5, SW e2e chromium·webkit
12/12, tsc(test), eslint 통과.
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로
썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로
튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다.
이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈)
navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고
권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2).
고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1
(B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만
하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지
번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다.
버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런
라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에
더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라
React 19의 useEffectEvent보다 의도가 덜 드러난다.
위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가
준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적
확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다.
검증:
- RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가
<main id="main-content">에 있었고 route.changed가 필터 테스트 1→3,
링크 테스트 1→2로 늘었다.
- GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과.
tsc(app, test) 통과, eslint(바꾼 파일) 통과,
verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로
되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두
h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다
제목 크기를 따로 만들게 된다.
고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem)
·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰
(--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤
base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면
h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰
값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로
골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에
흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이
바로 실패하고, 결과는 아래 e2e가 지킨다.
위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은
오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게
보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다.
검증:
- RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패
(h2 16px, h3 16px: "Expected: > 16, Received: 16").
- GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n·
ui-gallery·app-shell·responsive·theme·design-system-interactions·
compact-smoke + typography chromium/chromium-compact 32/32 통과(별도
playwright 설정, vite preview, pnpm 없이 빌드).
- check-design-system PASS(48 tokens). 시각 회귀는 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04
문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로
한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트
200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어
기본 원칙과 맞지 않고 모든 파생 서비스가 받는다.
고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap:
break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도
적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content
계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며
라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드
토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다.
위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은
오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의
줄바꿈은 눈으로 확인하지 않았다.
검증:
- RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패
(wordBreak "normal", overflowWrap "normal").
- GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과.
accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell·
responsive·theme·compact-smoke·platform-overview chromium/compact
34/34 통과. check-design-system PASS. 시각 회귀는 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.
고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.
위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).
검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
[ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
eslint 통과. e2e accessibility·typography·reference-form·reference-save
chromium 27/27.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제
화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다.
en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US"
아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2).
고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을
준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다.
버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다.
예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다.
위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는
문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서
영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어
본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다.
예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다.
검증:
- RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패
(Platform composition: lang Expected "ko-KR", Received "").
- GREEN: i18n·accessibility·ui-gallery·platform-overview e2e
chromium·firefox·webkit 69/69 통과. tests/component 220/220,
check-i18n PASS, tsc app 통과, eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07
문제: 접근성 기본 장치 일부를 지키는 테스트가 없었다. 리뷰 변이 중
M3(건너뛰기 링크 대상을 #content로), M4(LoadingSurface의 aria-live
제거), M5(상태 화면 제목을 <p>로), M6(사이드바 aria-label 제거)가
component 211개를 모두 통과했다. e2e의 axe는 WCAG 태그만 돌려
best-practice인 skip-link 규칙이 빠지고, 건너뛰기 링크를 누르는 e2e도
없었다.
고른 방법: 리뷰의 최소 개선 방향 그대로 단언을 더했다.
- app-shell.test.tsx: 건너뛰기 링크 href가 main의 id와 같고, 이름 있는
complementary 안에 주요 탐색이 있다.
- async-surface.test.tsx: LoadingSurface가 aria-busy와 aria-live="polite"를
가진다.
- accessibility.spec.ts: 건너뛰기 링크 Enter 뒤 포커스가 main 안에 있다.
- M5는 08-05 커밋의 제목 수준 테스트가 이미 잡는다.
버린 대안: axe에 best-practice 태그를 켜기 — 이번 범위 밖의 위반까지
한꺼번에 게이트가 된다.
위험·한계: 사이드바 이름 "사이드바"는 위치를 말하는 이름이라 리뷰가
관찰로 남겼다. 테스트는 지금 이름을 고정하므로 이름을 바꾸면 테스트도
같이 바꾼다. M3 변이 빌드에서 e2e는 공용 실행 잠금이 길게 잡혀
돌리지 못했다(component 테스트가 M3를 잡는다).
검증(테스트만 추가라 RED는 변이로 확인):
- M3: app-shell landmarks 테스트 실패(1 failed | 221 passed)
- M4: loading surface 테스트 실패(1 failed | 221 passed)
- M5(state-surfaces.tsx 제목을 <p>로): 08-05 테스트 2건 실패
- M6: app-shell landmarks 테스트 실패(1 failed | 221 passed)
- 변이 없음: tests/component 222/222, 새 e2e chromium·firefox·webkit 3/3.
tsc test 통과, eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-09
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.
고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.
위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).
검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
reference-page 3. 예: "Unable to find an element with the text: 지원
참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
59 files 336 tests 통과. e2e reference-save·reference-form·
reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
check-i18n, check-design-system 통과.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
두 수정이 따로 고쳐져 합쳐지면서 레지스트리 검사가 실패했다. 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
테스트 통과.
미출시 절은 13·14·15 묶음을 합칠 때 썼다. 그 뒤 합친 01·02·03·04·06·08·
09·10·11·16 영역 수정이 빠져 있었고, 13-04 행은 worktree 커밋 해시를
가리켰다.
[계약] 행 9개(업로드 Retry-After와 recovery, realtime 배럴 함수, base path,
조립 거절 2종, 전송 전 거절 분류, CI의 skip·todo 실패, 시각 허용치 50 px,
file-transfer 레시피 예산 인상)와 그 밖의 수정 5줄을 더했다. 13-04 해시를
브랜치 커밋으로 고쳤다.
위험: 문서만 바뀐다. file-transfer 예산 인상은 소유자 검토 대상으로 적었다.
검증: 표와 목록의 커밋 해시를 `git log`와 대조했다.
입력란 테두리 토큰(12-01), 좁은 화면 서랍(08-01), 제목 단계 크기(08-04),
한국어 단어 단위 줄바꿈(08-06)이 화면을 바꿨다. 허용치를 절대 50 px로
줄인 뒤(11-03) 기존 골든 5장이 모두 달랐다.
fonts.conf로 글꼴을 고정한 상태(11-02)에서 test:visual:update로 다시 찍고
눈으로 확인했다. 서랍에 브랜드·테마 선택·세션 상태가 보이고, 상태 화면
제목이 굵어지고, 한국어가 단어 사이에서만 줄바꿈된다.
위험: 이 호스트의 Noto·Noto CJK·Liberation 패키지 버전으로 찍었다.
검증: test:visual 6 passed(글꼴 검사 포함).
문제: 1101/07-04 이후 조립 단계는 reference feature 밖의 TEMPLATE_FIXTURE
기여를 거부한다. 규모 측정 생성기는 reference feature를 그대로 복사하므로
+25/+100 측정이 ContractContributionError로 멈췄고, 기준선 source가 작업
트리 SHA(2be973a)로 남아 있었다.
방법: renameReferenceFeature가 복사본의 source를 EXTERNAL_PACKAGE
(@feature-shape/<id>)로 바꾸고, 같은 패키지를 contracts.contractPackages에도
선언한다. 제품 기능이 실제로 거치는 경로와 같다. 조립 검사에 측정용 예외를
두는 안은 버렸다. 측정이 제품과 다른 경로를 재게 된다.
위험: reference feature의 source 블록 형태가 바뀌면 정규식이 맞지 않는다.
그때는 조립이 같은 오류로 실패하므로 조용히 틀린 값을 기록하지 않는다.
검증: node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100
--repeats=2 --write 성공(초기 JS +0: 203,816 B, +25: 219,508 B,
+100: 264,841 B), tests/unit/feature-shape-growth.test.ts 6/6 통과.
문제: 샘플 제거 드릴(test:sample-removal)이 reference feature를 지우면
설치된 기능이 0개가 된다. 15-01 이후 그 상태에서 기능 기여 타입이 never가
되어 installed-feature-adapters.ts와 테스트 2개가 타입 검사에서 실패했다.
features.load는 기능 테스트로만 검증되고 있어서, 기능 테스트가 같이
지워지면 create-application.ts 커버리지가 90% 아래로 떨어졌다. 드릴 사본에
README.md·CHANGELOG.md가 없어 문서 테스트 2개도 실패했다.
방법: never일 때도 통과하는 넓은 타입으로 받아서 읽는다(as 단언 없이 대입).
features.load는 가짜 로더로 플랫폼 테스트를 추가했다(한 번만 적재, 남의
input 거부, 실패 후 재시도). 문서 테스트 2개는 드릴 제외 목록에 넣었다.
드릴 사본에 문서를 복사하는 안은 버렸다. 기능 제거와 무관한 파일이 사본
목록에 들어간다.
위험: 넓힌 타입은 기여 타입이 바뀌어도 featureId 검사 부분은 잡지 못한다.
그 검사는 실행 시 TypeError로 남아 있다.
검증: tsc -p tsconfig.test.json 통과, check:types 통과, 관련 단위 테스트
20/20 통과. 드릴은 고치기 전 실행에서 coverage PASS를 확인했고 타입 오류
2건이 남아 있었다. 그 2건을 고친 뒤 드릴 전체는 다시 돌리지 않았다.
문제: 리뷰 README 13절은 개선 순서 1까지만 적혀 있었다. 밤사이 고친
ID와 커밋, 건너뛴 항목과 이유, 새로 찾은 결함, 예산 여유가 에이전트
보고에만 있었다. CHANGELOG 알려진 제한에는 이미 해결된 두 줄(규모
기준선이 15-01 전 측정, 좁은 화면 골든 미갱신)이 남아 있었고, 규모 근거
문장이 옛 수치를 적고 있었다.
방법: README 13.3~13.8에 개선 순서 2, 영역별 고친 ID와 커밋, 결정이
필요한 건너뛴 항목 20줄, 새 발견(여러 페이지 OPFS purge), 예산 여유,
마지막 게이트를 더했다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
CHANGELOG는 해결된 두 줄을 지우고 OPFS purge 제한을 더했다.
feature-shape-ceilings.json의 Initial/Lazy JavaScript 수치를 9333595
측정에 맞췄다.
위험: 13.6의 OPFS purge 결함은 코드로만 확인했다(E2). 실행 재현은 없다.
검증: changelog-review-ids, feature-shape-growth, documentation-readiness,
deletable-history-documents 11/11 통과. verify:documentation PASS_SCOPED.
문제: 13.5절의 건너뛴 20건과 5절의 확장 지점 범위가 결정을 기다리고
있었다. 결정이 없어서 0929/08-02·08-03, 13-01 같은 항목이 계속 미뤄졌다.
방법: 사용자가 결정을 오케스트레이터에게 맡겼다. 14절에 항목마다 결정,
이유, 버린 대안을 적었다. 레지스트리 기준선 재승인도 이 위임으로 한다는
것을 함께 적었다. 처리 결과는 구현을 합친 뒤 14.2절에 적는다.
위험: 08-03(raw mutation 제거)과 0929/05-03(recipe port 통합)은 다운스트림
코드를 깨는 공개 계약 변경이다. CHANGELOG에 이행 방법을 함께 적어야 한다.
검증: 문서만 바꿨다. 결정 근거는 각 영역 문서의 최소 개선 방향·대안 비교와
지난밤 에이전트 보고에서 가져왔다.
문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를
남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서
toUploadAction 한 곳에서 가를 수 없었다.
고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의
uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을
안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로
만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역
(toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개
타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는
곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다.
PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새
capability를 받는다(지난 수정의 보존 조건).
버린 대안:
- 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야
한다.
- code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다.
PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다.
- 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라
[계약]이다. 같은 일을 기존 값으로 할 수 있다.
- 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개
BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고,
WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시
만들면 말없이 표시가 사라진다.
- control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히
RESUME을 낸다.
위험·한계:
- BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림
화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다.
- control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지
않는다. 재인증 전에는 결과가 같기 때문이다.
- 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다.
- 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다.
- file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100).
검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중
BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403
1건은 수정 전에도 RESUME으로 통과(보존 조건 고정).
- GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다.
- 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새
테스트, 기존 01-05 표 테스트)이 실패한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼
파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
check-optional-recipes(source) file-transfer 56053/56100.
- 미실행: check:architecture(pnpm 필요).
Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로
싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고,
헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는
보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만
넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조"
줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를
싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다.
고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미
했다.
- V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드
sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를
싣는다. observation의 correlationId와 같은 값이다.
- 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다.
- 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩.
버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는
metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가
이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다.
위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을
조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안
컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로
두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은
이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼).
검증:
- RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS
200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수
없습니다."는 보이지만 "Unable to find an element with the text: 지원
참조: 29d7f444-…"로 실패.
- GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id).
tests/features·unit·integration·component 242 files 2975 tests,
tests/contract·runtime-schema·architecture 13 files 109 tests 통과.
tsc app·test, eslint(바꾼 파일), verify-documentation-readiness,
check-adapter-inventory, check-registries 통과.
Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.
고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
온 이전 응답은 버려진 client에 쓰인다. 이 동작을
server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.
위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.
검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
"error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
통과(옮긴 테스트 포함). tests/unit·component·features·contract·
runtime-schema·architecture·scripts·integration(security-followup-
archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
(바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
raw 호출이 있어 harness와 함께 동기화해야 한다.
BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03
문제: stream coordinator는 effect 마감 초과를 IDLE_TIMEOUT/APPLY로,
recovery 마감 초과를 IDLE_TIMEOUT/RECOVER로, close drain 초과를
IDLE_TIMEOUT/CLOSE로 보고한다. 설계 13.1에서 IDLE_TIMEOUT은 전송
idle(heartbeat/byte deadline -> close + bounded reconnect)이다. reconnect
관측(RUN_ENDED failureKind)에는 operation이 없어서 운영에서 "서버가
조용해짐"과 "우리 effect가 멈춤"을 failureKind로 나눌 수 없다.
5b3f5b0은 13.1에 두 뜻을 적기만 했다(리뷰의 (b)).
고른 방법: 리뷰의 (a). kind만 바꾸고 retryable:false, DRAINING 유지,
resume token 폐기는 그대로 둔다.
- effect 마감: APPLY_FAILED/APPLY. 13.1의 "feature effect 실패"이고,
WebSocket 연결도 자기 apply 마감을 APPLY_FAILED로 보고한다.
- recovery 마감: PROVIDER_UNAVAILABLE/RECOVER. recovery source가 제때
답하지 않은 것이다. recovery가 throw한 경우와 같은 kind다.
- close drain 마감: PROVIDER_UNAVAILABLE/CLOSE. reconnect coordinator가
drain 상한 초과를 PROVIDER_UNAVAILABLE로 보고하는 것과 맞춘다.
- 관측 reason도 같은 kind로 바꾼다.
- 13.1 표는 IDLE_TIMEOUT 행에서 stream coordinator 설명을 빼고,
APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 마감 경우를 적는다.
VD-28의 같은 설명도 고친다.
이 템플릿으로 운영 중인 제품이 아직 없어서 관측 값을 바꾸는 비용이
지금 가장 작다.
버린 대안: (b) 문서만 고친다. 5b3f5b0이 한 것이고, 관측에서는 여전히
구분되지 않는다. close 마감에 CLOSED를 쓰는 것도 버렸다. 아직
DRAINING인데 "닫힘"으로 읽힌다.
위험·한계:
- 공개로 관측되는 값이 바뀐다. stream coordinator 결과의 kind와
RealtimeObservation.reason에서 IDLE_TIMEOUT을 보던 조합 코드는
APPLY_FAILED/PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 그런
소비자는 없다.
- live-poll handoff coordinator의 quiescence·checkpoint·close 마감은
여전히 IDLE_TIMEOUT이다. 결정 범위(stream coordinator)를 지켰다.
13.1 IDLE_TIMEOUT 행에 handoff 마감만 남겨 적었다.
- realtime 레시피 번들 gzip이 40,897 B에서 40,902 B로 늘어 예산
40,900 B를 2 B 넘는다. "PROVIDER_UNAVAILABLE"이 "IDLE_TIMEOUT"보다
8자 길어 3곳에서 원본이 24 B 늘었다. 예산은 올리지 않았다.
check-optional-recipes가 REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED로
실패한다.
검증:
- RED: 기대값을 먼저 바꾸고 stream-coordinator.test.ts 실행 ->
7 failed | 31 passed. 예: expected kind APPLY_FAILED, received
IDLE_TIMEOUT.
- GREEN: tests/unit/realtime 14 files, 230 passed.
- tsc (tsconfig.app.json, tsconfig.test.json) 통과. 바꾼 두 파일 eslint
통과. verify-documentation-readiness PASS_SCOPED.
- check-optional-recipes: realtime 40902 > 40900 실패(위험 참고).
Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.
고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
(tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(de48db2)의 "청크 누락이 아닌 적재 실패" 경로로
context 경계에 가서 `ui.render.failed` 진단을 남긴다. 테스트로 확인했다.
- 라우트는 계속 늦게 읽는다. context를 정의할 때는 loadRoutes를 부르지
않는다.
- 7139c7c의 `contractRoutePaths`를 bounded-context-module.ts로 옮겨
앱 모듈과 같이 쓴다. "계약 라우트"의 정의가 한 곳에 남는다.
- starter-experience.md 기능 추가 3단계에 규칙을 적었다.
버린 대안:
- 헬퍼로 제공: 그 헬퍼를 쓰는 context만 지킨다. 안 쓰면 그만이다.
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 handle을 모른다.
위험·한계:
- 생성된 index는 기능별 라우트를 합쳐서 돌려주므로, 어느 기능의
`context-routes.ts`가 잘못된 handle을 냈는지는 알 수 없다. 메시지는
그 context의 기능 id 전부를 적는다. 기능이 하나인 context(지금
reference)는 정확하다.
- 최상위 라우트만 본다. 지금 context 라우트는 평평하다. children을 쓰는
context가 생기면 재귀가 필요하다.
- `defineBoundedContextModule`을 거치지 않고 손으로 만든 context 객체는
검사되지 않는다. 그 경우는 기존처럼 렌더 때 context 경계가 잡는다.
- 등록 라우트가 없는 URL에서 난 적재 실패는 진단 route_id가 NOT_FOUND다.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아 gateway의
`?? routeModule.id` 대체가 쓰이지 않는다. 09-09의 동작이고 고치지 않았다.
- 초기 JS gzip +141 B(203,818 -> 203,959 B, 여유 982 -> 841 B).
같은 worktree에서 `vite build` 두 번으로 쟀다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 새 3건 중 거절
2건이 "promise resolved ... instead of rejecting"으로 실패(10건 중 2
실패). tests/component/context-boundary-diagnostics.test.tsx 새 1건이
route_id "FIXTURE_ITEMSS"(렌더 때 경계)로 실패.
- GREEN: 두 파일 10건, 4건 통과.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
296 files 중 3,383 통과, 1건 실패. 실패는 telemetry-storm.test.ts의
10초 timeout(부하 34)이고 단독 재실행에서 4건 통과했다.
check-registries, check-adapter-inventory 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과.
verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-06
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.
고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.
버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.
위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
`tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
(+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
샘플 키에 기대지 않는다.
검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
feature-module.test.ts(26,60): error TS2345: Argument of type
'{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.
고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
`aria-description`, `aria-roledescription`, `aria-valuetext`,
`aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
`src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
"I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
`english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
(`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
`reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
`reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
된다.
버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).
위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
`eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).
검증:
- RED(수정 전):
- E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
user-facing locale literal in .../reference-resource-status-page.tsx",
exit 1
- E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
- `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
english-accessible-name.tsx, english-jsx-text.tsx", exit 2
- 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
- E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
- E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
- `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
"I18n allowed fixture was rejected", exit 2
- ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
`verify-documentation-readiness.ts` PASS_SCOPED
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
문제
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
문제
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
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
문제
registry-baseline.json의 FE-REG-API·FE-REG-SCHEMA source가 15-01(298201f,
기능 실행부 분리) 뒤에도 src/features/installed-feature-contracts.ts를
가리킨다. 두 레지스트리는 지금 src/features/loaded-feature-runtimes.ts에
있다. 기준선 diff는 contract와 rows만 비교하고 source는 보지 않아서 아무
검사도 이를 잡지 못했다. 또 0929/07-03(FE-REG-ROUTE contract 변경)과
1101/16-03(FE-REG-API authProfileId 3건)이 증거와 diff로만 남아 있다.
고른 방법
- 기준선을 한 번 재승인했다. update:registry-baseline의 node 하위 명령을
직접 실행했다(pnpm은 쓰지 않음):
node scripts/generate-product-feature-index.ts
node scripts/check-registries.ts --no-baseline \
--artifact artifacts/quality/registry-current-snapshot.json
REGISTRY_BASELINE_OWNER=DongHyeonka REGISTRY_BASELINE_REASON=...
node scripts/update-registry-baseline.ts
owner는 DongHyeonka, reason은 "2026-11-03 사용자가 결정을 위임함:
0929/07-03, 1101/16-03, 15-01 source 경로. 승인 뒤 쌓인
0925/08-13·1101/05-01(증거로 유지), VITE_BUILD_ID 기본값·
service-worker.start.failed 행(증거 불필요)도 함께 흡수"다. 사용자가 이
결정을 오케스트레이터에게 위임했고, 재승인은 A8만 한다.
- 새 기준선은 지금 스냅샷이라 source 경로가 실제 파일로 바뀌었다. 같은
재승인이 이전 승인(2026-09-25) 뒤 쌓인 변경을 모두 흡수한다:
FE-REG-ROUTE allowedValues 축소와 fieldPatterns 추가(0929/07-03),
authProfileId 3건(1101/16-03), REFERENCE_RESOURCE_DETAIL.path(0925/08-13),
CACHE_INVALIDATION_PULSE backend·valueCodec과 STORAGE backend 허용값
external(1101/05-01), VITE_BUILD_ID defaultValue(13-15),
service-worker.start.failed 텔레메트리 행(0925/06-05).
- update:registry-baseline이 0929/07-01 (3)대로 증거 5건을 지웠다(위
08-13 1건, 05-01 2건, 07-03 2건). 증거 파일은 빈 목록이다. 지운 행은
git 이력에 있다.
- 재발 방지 테스트: 기준선의 source가 governance path와 다르면
registry-governance.test.ts가 레지스트리 id를 나열하며 실패한다.
버린 대안
- source만 손으로 고치기: 승인 digest가 깨진다. 재승인 없이 기준선을
바꾸는 길을 만든다.
- 07-03·16-03 커밋마다 재승인: 지시는 한 번의 재승인이다. 그 사이 각
커밋은 증거(07-03)나 behavior-change(16-03)로 게이트를 통과했다.
- 기준선 diff가 source도 비교하게 하기: 파일을 옮기는 것은 공개 계약
변경이 아닌데 breaking 분류가 필요해진다. 테스트로 재승인만 요구한다.
위험·한계
- 레지스트리 파일을 옮기면 이제 테스트가 재승인을 요구한다. 재승인은 그
시점까지의 변경을 모두 흡수하므로, 옮기기 전에 남은 breaking 변경이
있으면 그 커밋 본문에 적어야 한다.
- 다운스트림은 이 기준선을 템플릿 이력으로 받는다. 자기 기준선을 다시
찍는 절차는 0929/07-04 범위다.
검증
- RED(재승인 전): 새 테스트 "names each registry's governed source in the
approved baseline"가 "expected [ 'FE-REG-API', 'FE-REG-SCHEMA' ] to deeply
equal []"로 실패.
- GREEN: 같은 테스트 통과. check-registries "11 registries PASS;
compatibility=none". 승인 digest 3c3702b55ad8849f399833206ea4515808eda6ab6d1fd5c49e90f8579e644170.
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,367건 통과(pnpm·프로세스를 띄우는 6개 제외), 그중 제외했던
deployment-admission은 따로 22/22. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc test rc=0, 바꾼 테스트
eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
문제
staging·production 프로필은 `https://api.example.com/`,
`https://telemetry.example.com/v1/events`를 싣고 텔레메트리를 켠다.
공개 대상 승인(FE-GATE-027)은 https와 비공개 호스트만 보므로 프로필을
고치지 않은 production 빌드가 `production ADMITTED`로 통과한다. 모든 API
호출이 실패하고 이벤트는 프로젝트가 소유하지 않은 도메인으로 간다.
CI 계약은 immutable_build의 env를 APP_PROFILE·RELEASE_TARGET로 고정해
RUNTIME_*를 넘길 수 없는데, README 변수 표는 이를 적지 않고 운영 예시는
`api.example.com`을 그대로 쓴다.
고른 방법
- publicEndpointViolations에 예약 이름 거절을 더한다. RFC 2606·6761의
`example.com`·`example.net`·`example.org`와 그 하위, `.example`,
`.invalid`, `.test`. 비공개 호스트와 겹치면 비공개 사유 하나만 낸다.
- README 운영 예시의 URL을 `<your-api-origin>/` 같은 빈칸으로 바꾼다.
- README 변수 표와 본문에 CI에서 endpoint를 바꾸는 방법은 프로필 파일을
커밋하는 것 하나라고 적는다.
- 테스트 fixture의 공개 endpoint를 예약되지 않은 이름으로 바꾸고, 프로필을
고치지 않은 빌드는 두 위반, endpoint를 준 빌드는 승인되는 것을 고정한다.
버린 대안
- 프로필 기본값을 비워 스키마가 빌드를 막게 하기: 더 확실하지만 프로필이
예시로 읽히지 않고 네 프로필을 같이 바꿔야 한다. 리뷰 대안 비교에서 승인
규칙 한 곳이 더 작다고 봤다.
- 리뷰 13-02 (3)의 괄호("13-01 배포 슬롯에 RUNTIME_* 허용 목록")는 하지
않았다. RUNTIME_*는 빌드 때 쓰이는 값이고, 슬롯은 승격 뒤 배포 job이라
거기서 넘겨도 이미 만든 후보에 닿지 않는다.
위험·한계
- 템플릿을 그대로 쓰는 프로젝트(이 repo 포함)가 APP_PROFILE=production으로
immutable_build를 돌리면 FE-GATE-027이 새로 실패한다(의도).
- `*.test` 같은 이름을 실제 운영 endpoint로 쓰는 프로젝트는 없다고 본다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
2 failed / 22 passed. "refuses names reserved for examples and tests"
(`expected [] to deeply equal [...]`), "refuses a public build from the
unedited profile on both endpoints"(`staging: expected [] to deeply equal
[ 'API_BASE_URL', 'TELEMETRY_ENDPOINT' ]`)
- GREEN: 같은 파일 24 passed. feature-override-diagnostics,
documentation-readiness 포함 29 passed
- 실험 E-A 재실행: APP_PROFILE=production VITE_BUILD_ID=rel-prod-a
RELEASE_ID=rel-a 빌드 뒤 RELEASE_TARGET=production 승인 rc=1,
API_BASE_URL·TELEMETRY_ENDPOINT 두 위반으로 거절
- tsc(app, test) 0, eslint 바뀐 파일 0, verify-documentation-readiness
PASS_SCOPED
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-02
문제
새 워커와 자기 해제 워커는 페이지 없이 클라이언트를 복구하는 유일한
경로다. edge가 루트 `.js`를 길게 캐시하면 그 TTL 동안 롤백과 비상 해제가
늦어진다. 0929/06-05는 SW 선택이 ACTIVE·REMOVE_REGISTRATION인 구성에서
cache policy에 `service-worker.js`(no-cache, JS MIME) 항목과 live probe
확인을 요구했다.
이미 된 것(629c8f0, 1101/13-04)
- config/hosting/cache-policy.json의 `serviceWorker` 표면: path
`/service-worker.js`, `no-cache`, `text/javascript`·
`application/javascript`, `requiredWhen: "service-worker-shipped"`
- verify-hosting-headers.ts는 shipsServiceWorker(ACTIVE,
REMOVE_REGISTRATION)일 때만 이 표면을 요구하고, live 모드에서는
probeLiveRelease가 그 경로를 요청해 같은 헤더 검사를 거친다
- 그 커밋은 SW null 트리에서만 돌려 "serviceWorker 헤더 검사는 건너뜀"으로
기록했다. 워커를 켠 구성에서 이 검사가 실제로 실패하는지는 아무도
확인하지 않았다.
고른 방법
남은 부분은 완료 기준의 증명이다. service-worker-build-output.test.ts가
이미 만드는 SW ACTIVE 빌드(임시 복사본, 추가 빌드 없음)에서
verify-hosting-headers.ts를 fixture 모드로 돌린다.
- 선언대로의 fixture: 실패 0, UNVERIFIED(rc=3)
- `serviceWorker` Cache-Control을 `public, max-age=31536000, immutable`로
바꾼 fixture: `serviceWorker cache-control` 하나로 FAIL(rc=1)
버린 대안
- 헤더 검사 루프를 함수로 빼서 단위 테스트: 스크립트 구조를 바꾸고도
INSTALLED_RUNTIME_CAPABILITIES를 거치는 실제 경로는 증명하지 못한다.
- 산출물 스키마가 워커를 싣는 빌드에 serviceWorker 헤더 결과를 요구:
정책 파일의 항목은 hosting-probe.test.ts가 이미 고정한다. 같은 것을
두 곳에서 지키게 된다.
위험·한계
- REMOVE_REGISTRATION 빌드는 따로 돌리지 않았다. 표면 요구 조건은
ACTIVE와 같은 shipsServiceWorker 한 함수이고, 그 함수의 두 모드는
hosting-probe.test.ts가 확인한다.
- 실제 CDN·호스트 응답은 확인하지 않았다(live 모드 미실행).
검증
- RED(629c8f0 이전 상태 재현: cache-policy.json에서 serviceWorker 항목을
지움): node scripts/run-vitest.ts run
tests/unit/service-worker-build-output.test.ts → 1 failed / 6 passed,
"expected [] to deeply equal [ 'serviceWorker cache-control' ]"
- GREEN(항목 복원): 같은 파일과 hosting-probe.test.ts 29 passed
- tsc(test) 0, eslint 바뀐 파일 0
Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-05
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
문제
제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF
쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면
runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts,
release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이
파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다
fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄).
고른 방법 (리뷰 09 4.2의 (B))
- FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의
FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은
declaration merging으로 capability를 더한다.
- 제품 소유 파일 둘을 빈 구현으로 둔다.
- src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필
id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유
product-composition-contract.ts에 둔다.
- src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정
zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에
있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수
없어서 파일을 하나로 합치지 못했다.
- 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품
제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가
CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용
목록이 정한다.
- 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다.
- 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가
두었던 전방 참조 stub이 필요 없다.
- 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에
담으면 browser-data-boundary/no-capability-alias가 막는다.
- http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다).
제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다.
버린 대안
- (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다.
- (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증
정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
- 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품
capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다.
위험·한계
- memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23,
CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히
rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다.
픽스처는 x-csrf-token으로 표현했다.
- 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다.
그 행을 요구하는 검사는 없다.
- tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드
(create-runtime-composition.ts)는 이 확장 지점 밖이다.
- 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을
끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은
이중 방어로 둔다.
- V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만
쓰는 리더다.
- 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800).
검증
- RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품
제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가
먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과.
- GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts
9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기·
쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01
tests/unit/runtime-adapters-auth-profile.test.ts 12/12.
- 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과.
integration·component 47 files 386 tests 통과(pnpm을 띄우는
security-followup-archive 제외). tsc app·test·node·recipes·web-worker·
service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS
(compatibility=breaking은 기존 route·storage 행). verify:documentation
PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신
exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON
schema는 baseline과 같다.
문제: 09-02 순서 테스트는 16-03 이름 변경 전 기준에서 작성돼 폐기 별칭
REFERENCE_EXTERNAL_BEARER를 썼다. 두 변경을 합친 뒤 테스트가 별칭에 기대게 됐다.
방법: 테스트의 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 별칭은 한 릴리스 뒤
지워지므로 새 테스트가 별칭을 쓰면 그때 같이 깨진다.
검증: tests/unit/runtime-adapters-credential-order.test.ts 통과, eslint 통과.
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).
방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.
위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).
검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
문제: 샘플 제거 절차(scripts/test-sample-removal.ts)의 SAMPLE_EXTRAS가
플랫폼 검사도 함께 지운다. HTTP 실패 시나리오 카탈로그(57개)와 tests/mocks,
test:http-scenario-evidence(FE-GATE-007), 기능 API 타입 음성 fixture 8개와
check:types:fixture:* 8개(FE-GATE-003)가 참조 기능 계약을 import해서
샘플 소유로 묶여 있었다. 드릴은 플랫폼 경로 4개만 확인하므로 통과하고,
제품은 가드레일이 줄었다는 것을 모른다.
방법: 카탈로그와 handler를 tests/helpers/external-contract-fixture.ts의
테스트 계약(TEST_LIST/DETAIL, 명령)으로 옮겼다. 바이트 상한·명령 여부·성공
status는 계약에서 읽는다. 명령은 효과를 분류하는 패키지처럼
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT를 더해 기존 기대값(401/403/429·422·
409 CONFLICT는 NOT_APPLIED, 409 IN_FLIGHT·404·503은 MAYBE_APPLIED)을
그대로 지킨다. TEST_CREATE_HTTP_CONTRACT의 분류기는 실행기 테스트가
"분류기 없음"을 확인하는 데 쓰므로 바꾸지 않았다. 문제 스키마에 선택
code만 더했다.
타입 fixture는 fixture tsconfig만 컴파일하는 fixture-feature-contract.ts의
테스트 기능(operation ID를 literal로 좁힌 테스트 계약, "fixture-feature"
입력 등록)을 쓴다. 등록 augmentation이 app·test 프로그램에 들어가지 않는다.
참조 기능 전용 handler(성공 응답만 쓰였다)는 tests/features/reference-feature
로 옮겼다. test-evidence.json의 owner는 platform이다. SAMPLE_EXTRAS에서
이 경로·스크립트를 빼고, 드릴의 플랫폼 보존 확인 목록에 16개 경로를 더했다.
샘플이 증거 정책을 갖지 않으므로 "등록 안 됨" 오류 검사는 지웠다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
검사는 계속 사라진다.
위험: fixture 스크립트 이름(check:types:fixture:reference-operation)과
파일 이름은 그대로라 이름이 내용(TEST_GET_ENTITY)과 다르다. CI 스크립트·
gates·워크플로 스냅샷을 함께 바꿔야 해서 미뤘다. 드릴의 제외 목록에 있는
tests/unit/http-scenario-evidence.test.ts는 그대로 뒀다.
test:sample-removal 자체는 pnpm이 필요해 돌리지 않았다.
검증: RED는 기준 복사본에 드릴의 삭제 목록을 적용했다. 카탈로그 테스트·
tests/mocks·타입 fixture 16파일이 지워지고 CI 스크립트 9개가 빠지는데 보존
확인은 4/4로 통과한다. GREEN은 같은 적용 뒤 보존 확인 16/16, 잔여 이름은
드릴이 빼는 removal-fixture.test.ts 하나, 타입 fixture 8개가 기존과 같은
진단(TS2345·2741·2353·2322·2345·2322·2322·2339) 1건씩으로 실패, 카탈로그
57/57 실행·check-test-evidence --scenario-only PASS, tests/component와
카탈로그 36파일 226개 통과, tsc -p tsconfig.test.json 통과. worktree에서는
테스트 계약 사용 파일·참조 기능·카탈로그 59파일 535개, scale session 2파일
통과, 음성 fixture의 양성 대조 컴파일 통과, tsc test·node 통과,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
문제: OPFS `enforcePolicies`의 LOGOUT·ACCOUNT_DELETION purge가
journal 목록을 두 페이지 이상 읽으면, 객체를 모두 지워도
`moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다.
페이지를 넘길 때 `moreObjectsAvailable = page.value.moreAvailable`가
true를 넣고, 마지막 페이지의 `||=`가 그 값을 그대로 둔다. 호출자는
다시 불러야 끝나고, 그 사이 chunk 바이트가 기기에 남는다.
고른 방법: 페이지 넘김 대입을 지운다. 대신 "다음 페이지를 읽기 전에
멈췄다"(객체 한도나 시간 예산 소진)는 루프 머리에서 true로 적는다.
`while` 조건을 루프 안 첫 검사로 옮긴 것이다. 0929/05-02(`85d8b59`)의
"건너뛴 객체가 있으면 true" 규칙은 그대로다. 그 값을 지우는 대입이
없다(마지막 페이지는 `||=`, PRESSURE 대입은 sweep하지 않는 purge).
버린 대안: 건너뜀 표시를 별도 변수로 나누기. 페이지 넘김 true가
남는 한 마지막 페이지에서 여전히 섞여 고쳐지지 않는다.
위험·한계:
- 동봉 IndexedDB journal은 페이지 한도를 "남은 객체 한도"로 받아 꽉 찬
페이지를 돌려주므로, 한 번의 호출에서 두 번째 페이지가 생기지 않는다.
결함은 port가 허용하는 짧은 페이지를 돌려주는 journal에서 드러난다.
테스트도 그 journal(페이지 1개씩)로 재현했다.
- 동작 차이 하나: 앞선 시간 검사를 통과한 직후 첫 페이지를 읽기 전에
시간이 다 되면, 전에는 `moreObjectsAvailable: false`로 sweep을
시도했고 이제는 true로 보고하고 sweep하지 않는다. 아무 객체도 읽지
않았으니 이쪽이 사실에 맞다.
- offline-indexeddb 레시피 gzip: 36,896 → 36,889 B (한도 36,900).
검증:
- RED: 새 테스트 "finishes a purge that walked more than one journal
page"가 수정 전 `moreObjectsAvailable: true`, `chunkSweep` 없음으로
실패했다.
- GREEN: `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts`
103건 통과. `tsc` app·test·web-worker 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 13.6절
문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.
고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
`STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
- 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
(0929 05-03)와 같은 조건이다.
- 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
- 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
손상 행도 지워진다. scope binding 행은 남긴다.
- 보고: `partitionDeleted: true`, `corruptObjects`,
`moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.
위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
`corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
report에는 `corruptTransactions`(필수)와 `corruptObjects`·
`partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
`STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
`listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
`CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
177 files 2,523건 통과, `tests/contract` 41건 통과.
`tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
`check:architecture`(pnpm 필요), Playwright OPFS spec.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와
같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`,
`FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`,
`PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929
05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이
복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는
runtime에 없는 resume·quarantine을 전제했다.
고른 방법 (리뷰의 (c)):
- runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고
`src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe
port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`,
`DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는
`DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src
port가 그대로 받는다).
- fake는 src port를 `implements`한다.
- 파일 picker·content·preview·download fake와 storage durability fake:
결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다.
`PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다.
- `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는
scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은
reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다).
LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다.
- 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는
`IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대
CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다.
recipe 전용 `StructuredOfflineStore`의 fake로는 남는다.
- recipe 전용 port 두 곳:
- `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection`
모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다.
- `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로
나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로
계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를
import하지 않게 하려는 것이다.
- 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를
더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을
정의하면 실패한다(다시 내보내기는 허용).
- runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는
이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께
지우고, recipe barrel에서 두 export 줄을 먼저 뺀다.
버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복
유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지).
위험·한계:
- recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다
(조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore`
생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입
4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다.
- `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가
아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다.
- `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다.
barrel 줄 제거와 경로 추가는 코드로만 확인했다.
검증:
- RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다.
`expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes
tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node
통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요),
`verify-documentation-readiness` PASS_SCOPED.
`check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산
초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다.
이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖).
BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS·
storage durability·public cache 타입 중 src/application/ports와 이름이
같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를
구현하고 BrowserDataResult를 돌려준다(`result.failure.code` →
`result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy,
maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은
`FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity`
·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03
문제
primitive가 종류별 파일 5개(core·forms·overlays·navigation·feedback)에
모여 있다. 번들러는 export가 아니라 모듈 단위로 청크를
나눈다. 그래서 셸이 쓰는 Button·Drawer·Select와 같은 파일에 있는
Tooltip·Menu·Card 같은 갤러리 전용 primitive도 셸과 같은 청크로 간다.
다음 커밋(side effect 없음 선언)이 효과를 내려면 먼저 파일이 나뉘어야
한다.
고른 방법
- primitives/ 아래를 컴포넌트마다 파일 하나로 나눈다(32개). 본문은 원래
줄을 그대로 옮기고 import만 새로 쓴다. ToastProvider·useToast는 한
파일, 내부 타입 FieldCopy는 field.tsx에서 내보낸다.
- PaginationLandmarkContext는 pagination-landmark.ts로 따로 둔다.
page-templates.tsx(StatusPage, 초기 청크)가 이것만 읽는데, Pagination과
같은 파일이면 Pagination 코드가 초기 청크로 간다.
- design-system/index.ts의 export 이름은 그대로다(값 71개, 타입 36개를
전후 비교). components/ui/*.ts 재수출, page-templates.tsx,
common-patterns.tsx는 새 경로를 가리킨다. .dependency-cruiser.json의
page-templates 예외는 출발 파일 기준이라 그대로 맞다.
버린 대안
- 셸이 쓰는 것과 나머지 두 파일로 나누기: 제품 셸이 Tooltip 하나를
쓰면 나머지가 다시 초기 청크로 간다.
위험·한계
- 이 커밋만으로는 번들이 바뀌지 않는다. 배럴이 다시 내보내는 모듈은
side effect가 있다고 보고 모두 초기 청크에 남는다(초기 JS 16개 청크,
203,818 → 203,824 B). 다음 커밋이 같이 있어야 효과가 난다.
- primitives/ 안의 파일 경로를 직접 import하던 다운스트림 코드는 경로를
바꿔야 한다. 공개 경계(index.ts)는 그대로다.
검증
- 원래 5개 파일의 import 아래 본문 줄이 새 파일에 빠짐없이 한 번씩
있다(줄 다중집합 비교).
- tsc(app·node·test) 통과, 바꾼 파일 eslint 통과.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- 빌드(flock): 초기 JS 16개 청크 203,824 B, ui-tooltip 등 갤러리 클래스는
여전히 초기 청크에 있다(예상대로).
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
문제
셸은 design-system/index.ts에서 Button·Drawer·Select를 import한다. 번들러는
배럴이 다시 내보내는 모듈을 side effect가 있다고 보고 모두 실행 순서대로
싣는다. 그래서 갤러리와 예제 화면만 쓰는 Tooltip·Menu·Toast·Tabs·Card·
Alert 등이 초기 청크(design-system-*.js)에 있다. 초기 JS는 203,818 B로
예산 204,800 B에서 982 B 남았다. 파일을 나눈 앞 커밋만으로는 바뀌지
않는다.
고른 방법
- vite.config.ts의 treeshake.moduleSideEffects 규칙으로
src/presentation/design-system/ 아래 .ts·.tsx를 side effect 없음으로
선언한다. 이 파일들은 컴포넌트·아이콘·토큰 목록 선언만 한다. CSS
import는 bootstrap/main.tsx 한 곳뿐이고 이 범위 밖이다.
- 결정: 바이트를 줄인다. 예산이 걸린 지표는 바이트이고, 늘어나는 청크는
진입 청크의 preload 목록(__vitePreload)으로 병렬로 받으므로 HTTP/2에서
왕복이 늘지 않는다. 재검토 조건(HTTP/1.1 호스팅이면 청크 수가 비용)을
설정 주석에 적었다.
- 새 테스트 tests/unit/design-system-initial-chunk.test.ts
- 실제 vite build를 돌려 초기 청크에 lazy 화면 전용 클래스 13개가
없는지 본다. 셸의 ui-drawer가 있는지를 같이 봐서 빈 결과로 통과하지
않게 한다.
- design-system 파일에 효과만을 위한 import(import "x")가 없는지 본다.
선언 아래에서는 그런 import가 모듈과 함께 사라지기 때문이다.
- build-environment-bundle 테스트(13-06)는 design-system-* 청크 이름을
찾았다. 그 청크가 없어져서, Button 코드(ui-button--pending)가 든 청크가
build id를 바꿔도 같은지로 바꾼다. 두 build id로 빌드해 보면 바뀌는
파일은 boot·index·render-boot-failure 셋뿐이다.
버린 대안
- 파일 분리만: 실측 효과 없음(203,824 B, 16개).
- manualChunks로 청크 이름을 고정: 제품이 primitive를 쓸 때마다 다시
맞춰야 한다.
- 청크 수 줄이기: 15-01 청크 그룹과 같이 봤다. rolldown의 $initial 태그는
main.tsx가 앱을 동적으로 import해서(09-03) 아무것도 잡지 않았다(25개,
+16 B). 모듈 그래프로 boot 정적 closure를 만들면 배럴을 따라 갤러리
primitive까지 잡혀 다시 초기 청크로 간다. 바이트 손해 없이 줄일 방법을
찾지 못해 늘어난 수를 둔다.
위험·한계
- 초기 청크가 16개에서 25개로 는다(결정 당시 추정 21개보다 많다. 앞
커밋의 파일 분리로 button·field·select가 따로 나온다). 전체(초기+lazy)
gzip은 232,231 → 236,253 B로 4,022 B 는다. 첫 화면만 보는 사용자는
2,718 B 덜 받고, 모든 화면을 도는 사용자는 청크 경계 비용만큼 더 받는다.
- 새 파일에 모듈 최상위 효과(전역 등록 등)를 넣으면 이 선언이 그 효과를
지울 수 있다. 효과만을 위한 import는 테스트가 막지만, 최상위 문장은
막지 않는다. 설정 주석에 적었다.
- lazy 청크 예산(청크당 122,880 B)에는 영향이 없다. 가장 큰 lazy 청크는
8,431 B다.
- 화면 변화 없음: 같은 코드를 다른 청크에서 받는다.
검증
- RED(앞 커밋 상태): 새 테스트가 실패. 초기 청크에 ui-alert·ui-badge·
ui-card·ui-data-table·ui-menu·ui-progress·ui-radio-group·ui-switch·
ui-tabs·ui-toast·ui-tooltip 11개가 있었다.
- GREEN: design-system-initial-chunk·build-environment-bundle·
design-system-contract·product-index-entrypoints·bundle-classification·
sub-path-deployment·product-feature-selection-build 통과.
- 빌드(flock, build-frontend.ts): 초기 JS gzip 203,818 → 201,100 B
(-2,718 B, 예산 여유 982 → 3,700 B), 초기 청크 16 → 25개, lazy 청크
17 → 20개.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- Chromium e2e(vite preview, 위 빌드): ui-gallery·design-system-
interactions·app-shell·accessibility·platform-overview·reference-form·
reference-route·reference-save·theme·typography·responsive·compact-
smoke·i18n·scroll-restoration 55/55 통과.
- tsc(app·node·test), 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
문제
첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반
키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴
패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수
없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니
제품은 템플릿 소유 스크립트를 고치게 된다.
고른 방법
- token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를
둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다.
- firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로
실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다.
- 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다.
- docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다.
- 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을
적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이
커밋은 (4)만 한다.
버린 대안
- 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러
설정까지 봐야 해서 규칙이 커진다.
- 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다.
위험·한계
- 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과
문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다.
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은
tests/unit/design-system-rules.test.ts뿐이다.
- 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다.
검증
- RED: 새 테스트 "passes a family the product declares it loads, and only
that one"이 실패(expected [ Array(1) ] to deeply equal []).
- GREEN: design-system-rules·oklch-contrast·design-system-contract
22/22 통과.
- 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로
시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새
메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS.
- tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness
PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
문제
config/ci/ungated-scripts.json의 check:feature-index 이유는 "--check는
로컬 사본이 오래됐다는 것만 알려 줄 수 있다"이다. 쓸모없다는 말로 읽혀
리뷰가 지울 후보로 올렸다. 실제로는 scripts/verify-extreme-scale.ts가
EXTREME_SCALE_GATES 첫 단계로 이 script를 부른다.
고른 방법
- 지우지 않는다. 이유 문구를 "로컬에서 생성 인덱스가 오래됐는지 확인,
verify:extreme-scale(scripts/verify-extreme-scale.ts)의 첫 단계. 게이트는
인덱스를 먼저 다시 만들어서 얻는 것이 없다"로 고친다.
- ungated-scripts 테스트가 EXTREME_SCALE_GATES에 이 script가 있고 이유가
verify:extreme-scale을 적는지 확인한다. verify:extreme-scale이 이
script를 그만 부르면 실패해서 다시 지울 후보가 된다.
- 12-05의 나머지(script 4개 삭제, scan: 접두어 검사)는 98b9682가 했다.
버린 대안
- check:feature-index 삭제: verify-extreme-scale.ts의 단계 목록과
tests/scripts/verify-extreme-scale.test.ts를 같이 고쳐야 하고, 로컬에서
생성 인덱스가 오래됐는지 볼 방법이 없어진다.
위험·한계
- 게이트 명령은 바뀌지 않는다. CI 계약 기준선은 그대로다.
검증
- RED: 새 테스트 "names verify:extreme-scale as the user of
check:feature-index"가 실패(expected 'The generated indexes
(src/.generated…' to contain 'verify:extreme-scale').
- GREEN: ungated-scripts·ungated-tests·verify-extreme-scale 31/31 통과.
- check:ci 세 단계를 pnpm 없이 직접 실행: generate-artifact-schemas --check
PASS, check-ci-contract.ts PASS(27 gates), generate-ci-workflow --check
PASS. 바꾼 테스트 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-05
문제: ff33d58이 tests/fixtures/typecheck/invalid-message-params.ts 주석에
샘플 기능 테스트 경로를 적었다. 샘플 제거 드릴의 잔여물 검사가 이 문자열을
샘플이 남은 흔적으로 보고 test:sample-removal이 실패했다.
방법: 주석에서 경로를 빼고 "샘플 기능의 자기 테스트"로 적었다. 잔여물 검사
정규식을 넓히거나 이 파일을 예외로 두는 방법은 버렸다. 검사가 약해진다.
검증: 같은 정규식으로 파일을 검사해 0건. test:sample-removal은 다음 게이트
실행에서 다시 돌린다.
문제: 경로 정본은 계약의 `routes[*].path`인데, 샘플 페이지가 같은 경로를
문자열로 8곳에 다시 적는다(목록 2, 상세 1, 폼 3, 상태 1, 실패 행동 1).
route 입력은 `routeInput.search as ReferenceListFilters`와
`String(route.params.resourceId)`로 cast한다. 계약에서 경로만 바꾸면 tsc는
통과하고 링크는 NOT_FOUND로 간다. 문서(routing-pages-and-patterns 4.2절,
10절 4단계)는 codec 기반 builder와 cast 금지를 권하는데, 샘플이 반대
패턴을 보여 주고 복사되는 기능이 그 습관을 가져간다.
고른 방법: 이미 있는 URL builder를 쓴다.
- `buildRouteUrl(routeId, input, featureCodecs)`(`src/presentation/routes/
route-codecs.ts`)가 route ID로 계약 `path`를 찾고, 라우터가 parse에 쓰는
같은 codec으로 직렬화한다. canonical redirect도 이 함수를 쓴다.
`src/platform`에는 URL builder가 없다. 그래서 플랫폼에 새 공개 헬퍼를
더하지 않았다.
- 기능 쪽 helper는 `presentation/reference-routes.ts`에 둔다.
- `referenceRouteUrl(routeId, input)`: `buildRouteUrl`에 이 기능의
codec을 넘기는 한 줄 래퍼다. routeId는 이 기능 계약의 키로 좁힌다.
- `useReferenceListFilters()`, `useReferenceResourceId()`: 라우터가 이미
통과시킨 route 입력을 같은 codec으로 다시 parse해서 codec의 출력
타입을 얻는다. cast가 없다. 목록 필터는 `useMemo`로 묶어 route 입력이
그대로면 같은 객체를 준다.
- `REFERENCE_FEATURE_ROUTE_CODECS`를 `reference-feature-runtime.ts`에서
새 `presentation/reference-route-codecs.ts`로 옮겼다.
- runtime 파일이 페이지를 lazy import하므로, 페이지 쪽이 runtime 파일에서
codec을 가져오면 순환 의존이 된다.
- codec 표를 helper 파일에 같이 두지 않은 이유: 그러면
`context-routes.ts`가 router의 builder·hook까지 끌어와 초기 JS가
585 B 늘었다(204,809 B로 예산 204,800 B 초과). 분리하면 475 B다.
- `context-routes.ts`와 `reference-contract.test.ts`는 새 위치에서
가져온다.
- 페이지 8곳을 route ID 호출로 바꿨다. 기능 presentation에 `"/examples/`
문자열이 0건, route 입력 cast가 0건이다. 남은 `"/examples/` 4건은 계약의
`path`(정본)다.
- 기능 README에 helper 위치와 쓰는 법을 적었다.
버린 대안:
- 리뷰 (b)처럼 기능 안에 경로 치환·직렬화를 새로 쓰는 헬퍼: 라우터와 같은
일을 두 번 구현한다. 플랫폼 builder가 이미 route ID와 기능 codec을 받는다.
- 리뷰 (c)처럼 `buildRouteUrl`의 input 타입을 route ID별로 좁히기: 플랫폼은
기능 codec 타입을 모른다(15-01 이후 codec은 지연 적재). 라우터 API
변경이라 이 발견 범위를 넘는다.
- 플랫폼 `useRouteInput`을 제네릭으로 바꿔 타입 단언하기: 런타임 검사 없는
단언이라 cast를 다른 이름으로 옮길 뿐이다.
위험·한계:
- 목록 링크가 이제 정식 URL(`/examples/reference-resources?limit=20`)을
가리킨다. 전에는 `?limit` 없는 주소로 갔다가 라우터가 같은 URL로
replace했다. 도착 URL과 history 항목 수는 같다. 폼의 "목록을 새로
불러와 확인" 링크 href 기대값을 이 값으로 바꿨다.
- `buildRouteUrl`은 codec이 거절하는 입력에 예외를 던진다. 백엔드가
공백만 있는 id를 주면(DTO는 `min(1)`, route codec은 trim 후 `min(1)`)
목록 렌더가 기능 오류 경계로 간다. 전에는 링크가 잘못된 주소 화면으로
갔다. DTO와 route codec의 id 규칙 차이는 이 변경 전부터 있다.
- route 입력을 한 번 더 parse한다. 값이 작아 비용은 무시할 만하다.
- 초기 JS gzip이 204,224 B에서 204,699 B로 475 B 늘었다(예산 204,800 B,
여유 576 B → 101 B). 새 코드가 초기 청크에 들어간 것이 아니다.
`route-codecs.ts`는 원래 초기 청크에 있었다. 페이지가 이 모듈을 import하자
rolldown이 `boot` 청크에 있던 것을 공유 청크(`route-input`)로 옮기고,
`route-input`과 `server-state-scope-provider`를 두 청크로 나눴다. 늘어난
양은 청크 분리 비용이다. 예산 값은 바꾸지 않았다.
- 페이지 테스트의 진입 URL 문자열은 그대로 뒀다. 테스트가 경로를 적는
것은 이 발견의 완료 기준 밖이다.
- 상태 페이지의 `(state as ReferenceSupportState)`는 history state 처리라
route 입력 cast가 아니다. 그대로 뒀다.
검증:
- RED(수정 전): 새 `tests/features/reference-feature/
reference-route-links.test.tsx`는 계약의 네 경로를 모두 옮긴(vi.mock)
상태로 목록→상세→목록→폼→목록, 목록→지원 페이지→목록을 걷는다.
2개 모두 실패했다. 상세 링크가 `href=".../items/reference-1"`(기대
`.../entries/reference-1`), 지원 페이지 대신 NOT_FOUND가 나왔다.
- GREEN(수정 후): 같은 테스트 2개 통과. `tests/features/reference-feature`
18 files 89 tests 통과(href 기대값 1곳 변경 뒤).
- 회귀: tests/features, tests/component, tests/architecture, tests/scale,
관련 unit 3개, generator 테스트 81 files 464 tests 통과. 첫 실행에서는
부하(평균 23~35)로 타임아웃 2건(app-build-input,
global-local-independence)이 났고, 단독 재실행과 최종 재실행에서 통과했다.
- 초기 JS gzip(`scripts/build-frontend.ts` 후 check-bundle과 같은 분류로
측정): 수정 전 204,224 B, 수정 후 204,699 B.
- `tsc` app·test·node 통과. 바꾼 파일 `eslint --max-warnings=0` 통과.
- `check-architecture.ts`(pnpm 대신 exec 전용 shim): 381 modules,
순환·위반 없음, rc=0. `verify-documentation-readiness` PASS_SCOPED,
`check-i18n` PASS.
- 페이지 테스트 harness(`renderReference`, `inputWith`)는 새 테스트와
함께 쓰도록 `reference-page-harness.tsx`로 옮겼다. 내용은 그대로다.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-04
문제
- zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의
reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은
복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을
structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다.
- RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도
검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이
타입·이름·조립 결과 어디에도 남지 않는다.
고른 방법 (C: 공유 어댑터 + 생략 표시)
- zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과
tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은
참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code
문자열). tests/helpers도 이제 성공 값을 복사한다.
- unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에
둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다.
zod가 필요 없어서 검증기 프로토콜 옆에 뒀다.
- composeContractContributions가 이 표시가 붙은 검증기를
unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로
내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두
본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다.
- 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약"
표를 둔다. 목록이 비면 그리지 않는다.
버린 대안
- (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다.
- (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의
자체 검증기까지 막아 §4 설계와 충돌한다.
위험·한계
- 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을
통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을
만들어 그 길로 생략한 것만 드러낸다.
- 공개 계약 추가: RuntimeValidator에 선택 필드 2개,
ComposedContractContributions에 필드 1개, 새 export zodValidator·
unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다.
ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야
한다(repo 안에는 없다).
- 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다.
플랫폼 개요 청크 4,625 → 4,750 B.
- 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는
돌리지 않았다.
- tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는
그대로 둔다(16-01이 그 파일을 넓힌다).
검증
- RED(수정 전): zod-validator.test.ts "Cannot find module
'../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와
starter-platform-overview-page.test.tsx "unvalidatedPayload is not a
function". 3파일 모두 실패.
- GREEN: 같은 3파일 33건 통과.
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는
security-followup-archive 제외), tests/architecture 7파일 33건 통과.
tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
eslint 0. check-registries PASS(compatibility=none), verify-documentation
PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신
exec stub) 383 모듈 PASS.
- 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능
폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용.
src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립·
플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).
방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.
위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
않았다.
검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
문제
FE-REG-QUERY-INVALIDATION은 무효화 그래프를 행 하나(invalidation-graph)로
투영하고 topics·namespaces·edges를 breakingFields로 둔다. 분류기는 배열에서
빠진 원소가 없으면 field-changed로 보고 breakingFields로 등급을 정한다. 그래서
topic 하나, namespace 하나, edge 하나를 더하기만 해도 breaking 3건이 되고
기준선 재승인이나 breaking 증거가 필요하다. 서버 상태를 쓰는 기능은 모두
topic을 달기 때문에 기능을 하나 추가할 때마다 사람이 재승인해야 한다(1101
리뷰 16 영역 2.1절: P-07-02가 남았고 범위가 더 넓다).
고른 방법 (오케스트레이터 결정 1)
- governance의 snapshotProjection.canonicalArrayKeyFields에 있는 필드는
키로 식별되는 원소 집합이다. 이 필드에서 원소가 빠지지 않았으면
set-items-added(additive)로 분류한다. 다른 레지스트리의 "행 추가"와 같은
성격이다. 이전 집합의 원소를 읽던 소비자는 모두 그대로 찾는다. 무효화가
늘어날 뿐이다.
- 원소를 빼거나 바꾸면 지금처럼 allowed-value-removed(breaking)다. 이 분기는
새 분기보다 먼저 판정된다.
- 0929/07-02(82c9e59)의 의도와 맞는지 확인했다. 그 커밋은 "이전에 유효하던
값이 모두 유효하게 남는 변경"(null 전환, allowedValues 확장)을 breaking에서
뺐고, 새·빠진·좁아진 제한은 breaking으로 남겼다. 이번 변경도 같은 기준이다.
1101/07-02(3c31576)는 V2/V3 parity 테스트라 레지스트리 분류와 겹치지 않는다.
버린 대안
- registryId(FE-REG-QUERY-INVALIDATION)를 분류기에 적기: 분류 규칙이
governance 밖에 숨는다.
- governance에 새 필드(예: additiveSetFields)를 두거나 breakingFields에서
세 필드를 빼기: $contract가 바뀌어 기준선 재승인이 필요하다. 빼기만 하면
behavior-change가 되어 결정(additive)과도 다르다.
- 뼈대·기능에서 topic을 빼기: 실제 기능에서 같은 문제가 다시 난다.
- 기능마다 재승인: 사람 승인이 기능 추가 비용이 된다.
위험·한계
- 게이트 판정이 바뀐다. 다운스트림에서 snapshotProjection을 쓰는
레지스트리는 키 집합에 원소를 더해도 breaking 증거를 요구하지 않는다.
다운스트림이 이런 추가에 적어 둔 breaking 증거 행은 이제 맞는 변경이 없어
0929/07-01 규칙대로 stale로 실패한다. update:registry-baseline으로 지운다.
- governance의 breakingFields에 topics·namespaces·edges가 남아 있지만 이
세 필드에서는 더 이상 판정을 바꾸지 않는다(빼기·바꾸기는 그 전에
breaking이다). 지우면 $contract 변경이라 기준선 재승인과 함께 할 일이다.
- 투영된 키 집합의 순서만 바뀐 경우도 additive로 분류된다.
check-registries가 키 순서로 정렬해 투영하므로 실제로는 생기지 않는다.
- 키 경로가 점을 포함한 필드(a.b)는 행 최상위 필드 이름과 맞지 않아 지금처럼
breakingFields로 판정한다.
검증
- RED(수정 전): registry-compatibility.test.ts "grades a topic, namespace
and edge added to the graph as additive" 실패. 커밋된 기준선에 topic·
namespace·edge를 하나씩 더한 스냅샷이 [edges, breaking], [namespaces,
breaking], [topics, breaking]로 분류됐다. 빼기·바꾸기 4건은 통과(breaking).
- GREEN: 같은 파일 23건 통과. registry-governance(무효화 원소 변조 4건이
여전히 breaking)·second-api-feature-registries 포함 33건 통과.
check-registry-compatibility-fixtures 11 PASS. check-registries "11
registries PASS; compatibility=none".
- 회귀: tests/unit 178파일 중 177 통과. 실패 1건
feature-shape-growth(초기 JS 증가 1036 > 1024 B)는 이 변경을 빼고 돌려도
실패한다(1042 B, 기준 커밋의 기존 상태). tsc node·test rc=0, 바꾼 파일
eslint rc=0.
- 미실행: check:architecture(pnpm 필요).
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 2.1, 16-01
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md 07-02
문제
- starter-experience.md "Adding a feature"의 폴더 밖 수정 표가 실제와 다르다.
라우트마다 필요한 수동 a11y 기록이 없고, 어느 검사가 실패하는지도 적지
않는다.
- 이 주장을 지키는 second-api-feature-registries 테스트는 무효화 topic이
없는 기능만 넣는다. 그래서 topic 추가가 기준선 재승인을 요구하던 결함을
보지 못했다.
- http-operation-v2-v3-parity 테스트는 스키마 ID "NoRequest"를 "입력 없음"
표시로 고정해 쓴다. 스키마 ID는 전역이라 두 번째 기능은 다른 이름(예:
OrderNoRequest)을 써야 한다. 그러면 이 테스트가 그 기능의 path·request
스키마를 둘 다 입력으로 세어 실패한다(16-02 작업자 발견).
고른 방법
- 표를 지금 코드 기준으로 다시 썼다. 열은 파일 / 언제 / 없으면 무엇이
실패하나. 리뷰 실험 E의 ①~⑨ 중 이번 라운드 앞 커밋이 없앤 것은 뺐다:
governance allowlist(0929/07-03), 기준선 재승인(앞 커밋, 결정 1), README·
체크리스트 route ID 목록(14-05), 인증 프로필 이름(16-03, EXTERNAL_BEARER
재사용), MSW 카탈로그와 무관한 테스트 3개(16-02). runtime-adapters.ts는
product-composition.ts로 바뀌었다(09-02).
- 남은 것: context 선언, 라우트별 a11y 기록, 경로 파라미터가
:resourceId가 아니거나 빈 배열 응답으로 그려지지 않는 페이지의 e2e a11y
spec, 제품 capability·인증 프로필·설정 키(제품 소유 파일 2개), 선택인
FEATURE_OVERRIDES, 계약 패키지를 npm 의존성으로 들일 때의 의존성 검토
증거. 계약 출처(EXTERNAL_PACKAGE)는 기능 계약의 contractPackages에
선언하므로 폴더 밖 수정이 아니다.
- 표 아래에 레지스트리 추가는 기준선을 바꾸지 않는다는 것, 전역 ID에 기능
접두어를 붙인다는 것, 기능의 MSW 시나리오는 createHttpScenarioHandler로
만든다는 것을 적었다.
- second-api 기능에 무효화 topic·namespace·edge·topicVersion을 더하고,
무효화 그래프 변경 3건이 additive인지 단언한다. 라우트는 0929/07-03이
이미 넣었으므로(SECOND_ITEM_LIST) 더하지 않았다.
- second-api의 통과 codec은 검증을 생략하므로 1101/07-03의
unvalidatedPayload로 만든다.
- parity 테스트는 V2 행에서 입력이 있는 쪽을 읽는다. path 스키마는
pathParameterNames가 있을 때, request 스키마는 requestSource가 "none"이
아닐 때 입력이다. 둘 다 없으면 행의 requestSchema(그 기능의 빈 입력
스키마)를 기대한다.
버린 대안
- 표만 고치기(리뷰 대안 a): 테스트가 계속 좁은 모양만 증명한다.
- 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾸기: FE-REG-API 행의
requestSchema·pathSchema가 바뀌어 기준선 재승인이 필요하고 범위 밖이다.
- parity 테스트에서 이름 끝이 NoRequest인 스키마를 빈 입력으로 보기: 이름
관례에 기대는 규칙이라 다른 이름을 쓰면 다시 깨진다.
- second-api 기능에 V3 기여를 넣어 parity를 그 사본에서 돌리기:
1101/07-02(3c31576)가 같은 이유로 버렸다(사본에서는 check:registries만
돈다).
위험·한계
- e2e a11y spec 행은 코드(:resourceId만 치환, 모든 API에 [] 응답)를 읽고
적었다. 다른 파라미터를 가진 라우트로 test:a11y를 실제로 돌려 보지는
않았다.
- 의존성 행은 직접 production 의존성을 더하면 generate:supply-chain이
"high-risk dependency missing review"로 실패한다는 코드를 읽고 적었다.
실행하지 않았다.
- 초기 JS 예산은 표에 넣지 않았다. 기능 하나가 초기 JS를 늘리지만 예산은
기능이 고칠 파일이 아니다. 이번에 측정하지 않았다.
- 표의 완전성은 테스트가 지키지 않는다. 생성 명령(U7)의 게이트 실행이
이 표를 실행으로 확인할 자리다.
검증
- RED: 넓힌 second-api 테스트를 결정 1 전 분류기(HEAD~1의
registry-compatibility.ts)로 돌리면 실패한다. check-registries stderr
"breaking change missing evidence:
FE-REG-QUERY-INVALIDATION:invalidation-graph:{edges,namespaces,topics}:field-changed".
parity 테스트는 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾼
변이(커밋 안 함)에서 "LIST_REFERENCE_RESOURCES: V2 declares both a path
and a request schema" 실패.
- GREEN: second-api 1/1, 같은 변이에서 parity 2/2, 변이 없이 2/2 통과.
V3 inputValidator schemaId를 바꾼 변이는 여전히 inputSchema 차이로
실패한다.
- 회귀: tests/unit 178파일 중 177 통과. 실패 1건 feature-shape-growth(초기
JS 증가 1 KiB 초과)는 기준 커밋에서도 실패한다. tsc app·test rc=0, 바꾼
테스트 eslint rc=0, verify-documentation-readiness PASS_SCOPED,
check-registries PASS(compatibility=none).
- 미실행: check:architecture(pnpm 필요), test:a11y, test:sample-removal.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-01, 8.1, 8.2
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.
고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
(`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
(`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
`src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
`AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
(context-route-gateway, context-boundary-diagnostics)에 `features: []`를
넣었다.
버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
지금처럼 플랫폼이 이긴다.
위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
`AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(7139c7c
한계). 루트 `*` context에서 `APP_HOME`이 아닌 id로 `/`를 선언하면 플랫폼
홈에 가려진다.
- 초기 JS gzip +349 B(204,586 -> 204,935 B). 예산 204,800 B를 135 B
넘는다(이전 여유 214 B). boot 청크 +228(라우터·앱 모듈),
installed-feature-contracts 청크 +121. 같은 worktree에서 HEAD 파일로
`vite build`를 한 번 더 해서 청크별로 비교했다. 예산은 고치지 않았다.
검증:
- RED: tests/component/context-layouts.test.tsx는 파일 적재에서
"Duplicate route registry key: APP_HOME"으로 실패.
tests/architecture/context-route-roots.test.ts 15건 중 3건 실패(APP_HOME
루트 예외 "not under the route root", 대체 함수가 없어 2건).
tests/scripts/generate-product-feature-index.test.ts 새 1건이 HEAD 생성기로
"expected ... to contain 'loadLayout: async () => (await import…'"로 실패.
- GREEN: 세 파일 37건 통과(생성기 15, 루트 16, context-layouts 6).
- 변이: 라우터가 `loadLayout`을 무시하면 context-layouts 6건 중 5건 실패.
topics 레이아웃을 다른 컴포넌트로 바꾸면 "keeps one layout instance" 실패.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
300 files, 3,451건 통과. check-registries, check-adapter-inventory,
verify-documentation-readiness(PASS_SCOPED) 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. 생성기 --check 통과.
- check:architecture는 pnpm이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-03, 4.3
문제
- 93180f6(합친 커밋 d3ddc89)이 초기 JS를 늘렸다. 기능 모양 측정
(scripts/scale/measure-feature-shape-growth.ts) 기준으로 기능 0개가
202,376 → 202,526 B(+150)로, 기능 1개 추가분이 960 → 1,029 B로 늘었다.
tests/unit/feature-shape-growth.test.ts의 1 KiB 상한을 넘는다.
- 원인은 두 가지다.
- 부팅 때 도는 composeContractContributions가 검증기마다 생략 표시를
읽고 목록을 만들었다(feature-platform 청크 +164 B). 이 목록을 쓰는
곳은 플랫폼 개요 화면(lazy 라우트)뿐이다.
- 공유 zod-validator.ts가 기능이 두 개가 되면 lazy 청크 하나로 따로
나왔다. 모든 context-routes·feature-runtime import의 preload 목록에
파일 이름이 하나 늘어 boot·feature-declarations 청크가 각각 약 25 B
커졌다.
고른 방법
- 목록 계산을 src/contracts/unvalidated-payload.ts의
listUnvalidatedPayloads(composed)로 옮긴다. 플랫폼 개요 화면만 이것을
import한다. 결정의 뜻(생략한 operation이 조립 결과에서 목록으로
나온다)은 그대로다. 계산 시점만 화면이 열릴 때로 미룬다.
ComposedContractContributions.unvalidatedPayloads 필드는 뺀다.
- unvalidatedPayload 팩토리도 같은 모듈로 옮긴다.
- 조립기의 표시 검사도 뺀다. 이유가 빈 생략은 unvalidatedPayload가 만들
때 거부한다(TypeError). 손으로 붙인 표시는 값이 "NONE"이 아니거나 이유가
없어도 목록에 나온다(화면에는 "이유 없음"). 그래서 생략이 숨지 않는다.
external-contract-runtime.ts에는 RuntimeValidator의 선택 타입 필드
2개만 남는다.
- vite.config.ts에서 zod-validator.ts를 schema-registry.ts와 같은 lazy
청크로 묶는다. 어댑터를 import하는 곳은 이미 schema-registry 청크를
preload한다. includeDependenciesRecursively: false라서 다른 모듈은
끌려오지 않고, 두 모듈 모두 부팅 그래프 밖이다.
버린 대안
- 조립기에 "NONE + 이유" 검사만 남기기: feature-platform 청크 +57 B gzip.
검사를 팩토리와 목록으로 옮기면 0 B다. 손으로 붙인 잘못된 표시를
부팅 때 거부하지 못하지만, 목록에는 나온다.
- zodValidator를 schema-registry.ts 안에 정의: 빌드 설정 없이 같은 결과가
나오지만 결정한 위치(src/contracts/zod-validator.ts)와 다르고, 다음 단계의
기능 생성 명령이 그 경로를 쓴다.
- 어댑터를 zod.ts에 두기: zod 입구는 초기 청크라 기능 0개 초기 JS가 는다.
위험·한계
- 조립 결과 타입에서 unvalidatedPayloads 필드가 빠진다. 93180f6 뒤 이
필드를 쓴 코드는 listUnvalidatedPayloads로 바꿔야 한다. repo 안에서는
화면과 테스트만 썼다.
- 손으로 만든 잘못된 표시(예: validation: "PARTIAL")는 더 이상 조립에서
거부되지 않는다. 목록에만 나온다. 테스트 2건을 이 동작으로 바꿨다.
- 청크 묶음은 빌드 설정에 두 파일 경로를 적는다. 파일 이름을 바꾸면
정규식도 함께 바꿔야 한다. 놓치면 바이트만 늘고 동작은 같다.
- 플랫폼 개요 화면을 열면 schema-registry 청크에 어댑터(351 B raw)가 같이
온다.
검증
- 기능 모양 측정(0개 / 1개 추가분, gzip B):
- ee81c44(07-03 전): 202,376 / 960
- d3ddc89(07-03 합친 뒤): 202,526 / 1,029
- 목록만 부팅 밖으로: 202,407 / 1,035
- 청크 묶음 추가: 202,424 / 983
- 조립기 검사 제거(이 커밋): 202,371 / 958
- feature-shape-growth.test.ts 6건 통과.
- 07-03 테스트 3파일 33건 통과(zod-validator, external-contract-runtime,
starter-platform-overview-page).
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
270파일 3,203건, tests/integration 12파일 158건(pnpm을 띄우는
security-followup-archive 제외), tests/architecture 7파일 33건 통과.
- tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
eslint 0. 아키텍처 그래프 검사(pnpm 대신 exec stub) 413 모듈 PASS.
check-registries PASS(compatibility=none).
- 본 빌드 초기 JS gzip 202,371 B(26파일). raw 644,782 B로 ee81c44 측정과
같다.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03
문제
짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드
docs/web/http-contract.md §1). V2 Envelope 스키마
(src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과
다르게 읽는다.
- 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가
data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은
그대로 통과한다.
- meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴
응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패
Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다.
error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는
이미 키가 없어도 받는다.
고른 방법
- data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을
채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은
길을 탄다. 정규화가 wire 스키마 한 곳에 있다.
- meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는
경우를 처리한다.
버린 대안
- client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와
클라이언트 두 곳이 같은 규칙을 나눠 갖는다.
- 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지
않는 모양이다. 최상위 strict는 그대로 둔다.
위험·한계
- meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와
AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다).
- V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2
경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지
않았다.
검증
- RED: tests/integration/http-client.test.ts "envelope keys the paired
backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는
403이 code HTTP_FAILURE.
- GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics·
http-execution-contract·auth-recovery·legacy-http-credential-authority,
tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼
파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
문제
짝 백엔드는 KEYED 요청을 실행하기 전에 두 가지를 거절한다(백엔드
docs/web/http-contract.md §2).
- 422 IDEMPOTENT_REQUEST_MISMATCH: 같은 키에 다른 본문. 클라이언트 버그.
- 400 IDEMPOTENCY_KEY_INVALID(details.reason MISSING·MALFORMED): 키 누락·
형식 오류.
둘 다 이 요청은 적용되지 않았고, 그대로 다시 보내면 같은 답이 온다.
- V2(client.ts)는 이 실패에 effect를 붙이지 않는다. mutation 코디네이터는
effect가 없으면 MAYBE_APPLIED로 보고(application-query.ts
mutationFailureWithEffect) 키를 붙든다. 400은 결과 불명 화면으로 가고,
같은 입력을 다시 저장하면 같은 키로 같은 400·422를 계속 받는다. 진단
이벤트(http.request.completed)에는 원인이 없다.
- V3 참조 기능은 분류기가 400·422를 이미 NOT_APPLIED로 본다. 다만
mapProblem이 400을 다루지 않아 code가 CONTRACT_PROBLEM으로 바뀌고
서버의 IDEMPOTENCY_KEY_INVALID가 사라진다.
고른 방법
- V2: 문서에 적힌 status와 code가 둘 다 맞을 때만 effect NOT_APPLIED를
붙인다(IDEMPOTENCY_REFUSALS 표). 같은 표가 진단 reason을 준다.
- 422 → reason IDEMPOTENT_REQUEST_MISMATCH
- 400 → reason IDEMPOTENCY_KEY_RULE_MISMATCH. 프론트는 보내기 전에
isValidIdempotencyKey로 키를 검사한다. 서버의 400은 두 키 규칙이
어긋났다는 뜻이라 그 이름으로 남긴다. 보내기 전 거절(VALIDATION_
REJECTED, httpStatus 없음)은 표에 걸리지 않는다.
reason은 diagnostics에만 넣는다. telemetry 속성은 그대로다(VD-07).
- V3 참조 mapProblem: 400 + IDEMPOTENCY_KEY_INVALID만 UNKNOWN_CLIENT_
FAILURE와 서버 code로 둔다. 다른 400은 기존 fallback 그대로다.
- kind는 바꾸지 않았다(422 VALIDATION_REJECTED, 400 UNKNOWN_CLIENT_
FAILURE). 둘 다 retryable:false이고 V2 재시도 대상이 아니다.
- 키 문법은 백엔드 IdempotencyKeyHeader([\x21-\x7E]{1,256}, trim 없음)와
같다. 1자 키를 받는 행을 더해 경계를 고정했다.
버린 대안
- code만 보고 판정: 다른 status에 같은 code가 오면 NOT_APPLIED를 잘못
붙인다. NOT_APPLIED는 다음 저장이 새 키를 쓰게 하는 판정이라 문서의
짝(status+code)만 믿는다.
- 422 mismatch를 UNKNOWN_CLIENT_FAILURE로 바꾸기: 화면 문구가 바뀐다.
요구는 재전송 금지·결과 불명 화면 금지·원인 code 보존이라 kind는 두었다.
- 서버 code를 진단 reason에 그대로 넣기: 서버 code는 무제한이라 진단
cardinality 규칙(taxonomy)을 깬다. 표에 있는 두 값만 넣는다.
위험·한계
- 422 mismatch를 NOT_APPLIED로 보면 다음 저장이 새 키를 쓴다. 같은 키의
앞선 요청이 적용됐을 수 있지만, 프론트는 canonical 입력이 같을 때만 키를
재사용하므로 mismatch는 지문 규칙이 어긋난 버그다. 결정(15절)대로 이번
요청은 적용되지 않았다고 본다.
- 422 화면 문구는 "입력값을 다시 확인해 주세요."다. 사용자가 고칠 입력이
아니지만 다시 저장하면 새 키로 나간다.
- V3 실행기의 진단은 problem code를 모른다(Problem 타입은 계약 패키지
소유). V3에서 원인은 AppFailure.code·httpStatus로만 보인다.
검증
- RED: tests/integration/http-diagnostics.test.ts 새 2행 실패(effect
undefined, reason 없음). tests/features/reference-feature/reference-http-
problem-mapping.test.ts 400 IDEMPOTENCY_KEY_INVALID 행 실패(code
CONTRACT_PROBLEM). 422 mismatch 매핑, 분류기 2행, 1자 키 행은 처음부터
통과(이미 맞는 동작을 고정).
- GREEN: 위 파일과 tests/features/reference-feature, tests/integration/
http-client·http-execution-contract·auth-recovery·legacy-http-credential-
authority, tests/contract/reusable-capability/feature-http-binding 24 files
207 tests 통과. tests/unit/legacy-and-optional-network-remediation 6/6.
tsc app·test 통과, 바꾼 파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
한 번 더 받는다.
고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
긴 Retry-After를 다 기다리게 하지 않는다.
버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
Retry-After를 지키는 것이다.
위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).
검증
- RED: 4행 실패.
- tests/features/reference-feature/reference-production-vertical.test.tsx
처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
- tests/component/application-mutation-admission.test.tsx 재전송이
retryAfterMs 300을 기다리지 않음
- tests/features/reference-feature/reference-http-problem-mapping.test.ts
retryAfterMs 없음
- tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
capability, tests/integration/http-client·http-diagnostics, tests/unit/
http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
문제
짝 백엔드는 쿠키 세션의 CSRF를 Spring CookieCsrfTokenRepository로
검사하고, 기본 헤더 이름은 X-XSRF-TOKEN이다(백엔드 SecurityConfig.java,
docs/registries/env-keys.yaml APP_SESSION_CSRF_HEADER_NAME). 프론트의 닫힌
자격증명 헤더 목록(VD-23, rest-profiles.ts CREDENTIAL_HEADER_NAMES)에는
x-csrf-token만 있다. 제품 인증 프로필이 x-xsrf-token을 allowed·required에
적으면 프로필 레지스트리 설치가 모듈 로드 때 throw한다. 그래서 memento가
템플릿 파일을 고쳤고, 09-02(da1e128)의 제품 제공자 테스트 fixture는
x-csrf-token으로 우회해 적었다.
고른 방법
- 목록이 닫힌 이유(VD-23 5-1): 자격증명 제공자가 transport 소유 헤더
(accept, content-type, idempotency-key)나 금지 헤더를 넣지 못하게 하고,
프로필이 정확한 allowed·required 집합을 갖게 하려는 것이다. x-xsrf-token은
그 어느 쪽도 아닌 proof 헤더라 목록에 더해도 이 이유를 깨지 않는다.
- 목록에 x-xsrf-token 하나를 더한다. 실제로 보낼 수 있는지는 여전히
프로필의 allowed 집합이 정한다. 템플릿 기본 프로필(EXTERNAL_BEARER,
ANONYMOUS)은 바뀌지 않는다.
- 09-02 fixture의 memento BFF 쓰기 프로필과 제공자를 x-xsrf-token으로
바꿔 우회를 없앤다. 이 fixture가 RED 테스트다.
버린 대안
- 헤더 이름을 프로필이 자유롭게 정하게 열기: 닫힌 목록이 막는 shadowing·
금지 헤더 위험이 돌아온다.
- 백엔드가 X-CSRF-TOKEN을 받게 설정: 백엔드 기본값을 바꾸는 일이고 이
repo 범위 밖이다. 백엔드 repo는 고치지 않는다.
위험·한계
- RestCsrfProfile.headerName 타입("x-csrf-token" | null)은 그대로다. CSRF
프로필은 템플릿 상수(REST_CSRF_PROFILES)뿐이고 제품이 더할 확장 지점이
없다. 제품 쿠키 프로필은 인증 프로필의 헤더 집합으로 표현한다.
- V2 legacy 허용 목록(client.ts LEGACY_ALLOWED_CREDENTIAL_HEADERS)은
"기존 동작 그대로"가 목적이라 바꾸지 않았다.
- 외부 세션 어댑터(external-session-adapter.ts)도 같은 목록을 읽으므로
이제 x-xsrf-token을 받는다. 보낼지는 V3 프로필 검사가 정한다.
검증
- RED: tests/unit/product-composition-fixture.test.ts를 x-xsrf-token으로
바꾸자 파일 전체 실패("REST auth profile allowedCredentialHeaders is not
an exact set", 모듈 로드).
- GREEN: 같은 파일과 tests/unit/runtime-adapters-auth-profile·runtime-
adapters-credential-order·contract-snapshot-bypass, tests/integration/
legacy-http-credential-authority 5 files 44 tests 통과. tsc app·test
통과, 바꾼 파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
문제
docs/architecture/backend-api-and-server-state-contract.md 4.1절(JSON
envelope)과 6절(Command와 idempotency)이 백엔드 계약을 직접 다시 적었다.
짝 백엔드가 바뀐 뒤 둘이 어긋난다.
- 4.1절 예시는 meta id를 늘 싣고 null 생략 규칙이 없다.
- 6절은 같은 키·다른 본문을 409 IDEMPOTENCY_KEY_REUSED로 적는다. 백엔드는
422 IDEMPOTENT_REQUEST_MISMATCH다. 처리 중 409의 retryable·Retry-After,
400 IDEMPOTENCY_KEY_INVALID도 없다.
- 4.2절 409 행이 "idempotency fingerprint" 충돌을 409로 적는다.
백엔드 http-contract.md 5절은 이 두 절이 자기 문서를 가리켜야 한다고
적는다.
고른 방법
- 4.1절·6절의 표와 예시를 지우고 백엔드 문서 링크(1절, 2절·4절)와 기준
버전(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03)만 적는다. 백엔드
변경은 아직 커밋이 없어 SHA 대신 결정 날짜를 적고, 커밋이 생기면 SHA로
바꾸라고 적었다.
- 프론트가 그 계약을 읽는 코드 위치만 남긴다. 표를 복사하지 않는다.
- 4.2절 409 행에서 멱등성 충돌을 빼고 6절을 가리킨다.
버린 대안
- 프론트 문서의 표를 백엔드 값으로 고쳐 두기: 다음 백엔드 변경에서 다시
어긋난다.
위험·한계
- 링크는 두 repo가 같은 상위 폴더에 나란히 있을 때만 열린다
(../../../clean-architecture-backend-template/...). verify:documentation은
repo 밖 링크를 검사하지 않는다.
- 6절에서 지운 권장 IdempotencyRecord와 불변조건은 짝 백엔드가 구현과
문서로 소유한다. 다른 백엔드를 붙이는 제품은 백엔드 문서를 기준으로 삼는다.
- 4.2절의 422 행(field validation)은 그대로다. 짝 백엔드는 필드 검증
실패를 400 VALIDATION_FAILED로 보낸다(백엔드 http-contract.md 4절). 이
차이는 이 변경 범위 밖이다.
검증
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED.
Refs: clean-architecture-backend-template docs/web/http-contract.md 5절, docs/reviews/2026-11-01-maturity-review/README.md 14.3
문제: 7450e1f(16-01)의 fixture 기능은 unvalidatedPayload를
external-contract-runtime.ts에서 가져왔다. 그 뒤 8b7c6eb(07-03 후속)가 이
함수를 부팅 경로 밖 src/contracts/unvalidated-payload.ts로 옮겼다. 두 변경을
합치니 복사본에서 계약 모듈이 import 오류로 적재되지 않고, check-registries가
레지스트리 6개를 "missing registry source"로 보고했다.
방법: fixture 문자열의 import 경로를 새 모듈로 바꿨다.
위험: check-registries는 적재 오류를 삼키고 "missing registry source"만
남긴다. 원인 import를 말하지 않아 이번 원인도 임시 출력으로 찾았다. 별도
개선 후보로 남긴다.
검증: tests/unit/second-api-feature-registries.test.ts 통과.
문제: check-registries는 레지스트리 source 모듈의 import 오류를 삼키고
"missing registry source <path>"만 남겼다. 파일은 있는데 그 안의 import가
깨진 경우에도 파일이 없는 것처럼 보였다. 6ea9e4a의 원인(옮긴 export를 예전
경로에서 가져온 fixture)도 이 메시지만으로는 찾을 수 없어 임시 출력을 넣어
찾았다.
방법: source 경로가 있는데 적재가 실패하면 오류 메시지 첫 줄을 실패 문장
뒤에 붙인다. 파일이 없을 때의 문장은 그대로다(release-artifacts·json-schema
테스트가 그 문장을 쓴다). 스택 전체를 붙이는 방법은 버렸다. 산출물 JSON의
failures가 커지고 경로가 실행 환경마다 달라진다.
위험: 다운스트림이 이 실패 문장을 정확히 비교하면 달라진다. 파일이 없는
경우의 문장은 바뀌지 않았다.
검증: tests/unit/registry-governance.test.ts에 "있지만 import가 깨진 source"
테스트를 더했다. 수정 전 실패(1 failed), 수정 뒤 10건 통과. check-registries
PASS, eslint, tsc(node) 통과.
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.
고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).
버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
(type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
않는다. 짝 백엔드 wire를 읽는 곳은 V2다.
위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.
검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
"reads the field details as validation issues" 실패(kind
UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
component·features·platform 283 files 중 282 통과, 3394 tests 통과.
실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).
고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.
근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
끌어낸 것이다.
버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
남아 같은 입력을 다시 저장하면 같은 키가 나간다.
위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.
검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
"saves the corrected value after a server 422 field error"는 수정 전에도
통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
tests/unit·contract·runtime-schema·integration·component·features·platform
3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
통과.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
문제
- 기능 생성 명령(U7)은 계약 패키지 인자가 없으면 자리표시자 신원으로
기능을 만든다. 이 신원은 형식 검사(external-contract-runtime.ts의
패키지 신원 검사)를 모두 통과한다. 계약 집합 검사도 같은 목록을 자기
자신과 비교한다. 그래서 자리표시자를 그대로 둔 빌드가 staging·
production 승인까지 통과한다.
고른 방법 (오케스트레이터 결정 2)
- 자리표시자를 src/contracts/deployment-admission.ts에 상수로 둔다.
digest는 sha256: 뒤에 0 64개, version 0.0.0, revision 0000000이다.
생성 명령이 이 상수를 import해 쓰므로 코드에서 자리표시자임이 보인다.
- findAdmissionViolations에 세 번째 인자로 빌드가 컴파일한 계약 패키지
목록을 받는다. 대상이 PUBLIC(staging, production)이면 digest가
자리표시자인 패키지마다 contractPackages.<packageId> 위반을 낸다.
BUILD_ID·RELEASE_ID의 PLACEHOLDER_IDENTIFIERS 검사와 같은 꼴이다.
- check-release-admission.ts는 EXPECTED_CONTRACT_SET_PACKAGES를 넘긴다.
이미 COMPILED_PRODUCT_FEATURE_IDS를 같은 방식으로 읽는다.
- 배포된 config.json의 수정본 검사(--config, 1101/13-05)는 패키지를
보지 않는다. 수정본은 비상 스위치만 바꿀 수 있고, 패키지는 빌드 필드라
빌드 승인 때 이미 검사했다.
- APP_PROFILE 테스트의 production 행은 컴파일된 계약 집합에 자리표시자가
있으면 거절(그 이유로만)을, 없으면 승인을 기대한다. 생성 명령으로
기능을 하나 만들면 저장소 자체 빌드가 production 승인을 받지 못하는
것이 의도한 동작이기 때문이다.
- 버린 대안: 계약 형식 검사에서 거절하기. 그러면 생성한 기능이 로컬에서
부팅·테스트되지 않는다. dist/release-manifest.json을 읽어 비교하기.
릴리스 일관성 검사가 이미 manifest와 컴파일된 목록이 같은지 보므로
같은 값을 한 번 더 읽고, 이 스크립트를 실행하는 테스트마다 manifest를
써야 한다.
위험·한계
- digest만 본다. version이나 revision만 자리표시자이고 digest는 진짜인
신원은 거절하지 않는다. 결정이 digest 하나를 자리표시자로 정했다.
- local·development 대상은 거절하지 않는다. 의도한 동작이다.
- 새 코드는 앱 번들에 들어가지 않는다(빌드 후 dist에서 거절 문구와
상수 이름 grep 0건). 앱은 이 모듈에서 isLoopbackHostname만 쓴다.
검증
- RED: 상수만 넣고 거절 전 코드로 새 테스트를 돌리면 실패한다.
"staging: expected [] to deeply equal [ Array(1) ]"
- RED(수정본·APP_PROFILE): 생성 명령으로 기능 하나를 만든 상태에서
두 테스트가 "contractPackages.@org-contracts/order: pins the
placeholder identity ..."로 실패했다.
- GREEN: tests/unit/deployment-admission.test.ts 25/25,
feature-override-diagnostics.test.ts(스크립트 실행) 통과. 생성한 기능이
있을 때와 없을 때 모두 통과. 생성한 기능이 있을 때 production 대상
스크립트 실행은 rc=1과 위 위반 한 줄을 낸다.
- npx tsc app·node·test rc=0, 바꾼 3파일 eslint rc=0.
문제
- 새 기능은 참조 기능을 복사해 이름을 바꾸는 방법뿐이다. 리뷰 16 실험 E
에서 이 방법은 12번 막혔다. 접두어 없는 전역 ID(NoRequest, qinv topic,
navigationOrder)는 치환으로 바뀌지 않고, 토큰 경계 없는 치환은
preference·supportReference를 깨뜨린다. 제품이 참조 기능을 지우면 복사할
원본도 없다.
고른 방법 (결정 D1·D2, 오케스트레이터 결정 2·4)
- scripts/create-feature.ts: pnpm create:feature <id> [--context <ctx>]
[--package @scope/name@x.y.z --digest sha256:… --revision <hex>].
템플릿을 이 파일 안에 두고 참조 기능을 import하지 않는다(D1).
- 뼈대: 파라미터 없는 목록 라우트 1, GET 1(SAFE, EXTERNAL_BEARER),
쿼리 1, topic 1, CollectionPage 1, ko-KR·en-US 문구. domain/ 없음.
검증은 공유 zodValidator, 링크는 route ID와 buildRouteUrl
(<base>-routes.ts). 빈 배열 응답은 공유 빈 상태로 그린다.
- 전역 ID는 모두 기능 접두어를 단다(D2): 스키마·mapper·operation·
contribution·policy·diagnostics·chunk·route·namespace·definitionId·
문구 키·telemetry kind·owner. topic은 qinv. + 무작위 26자(Crockford
base32)이고 설치된 topic과 겹치면 거부한다. navigationOrder는 설치된
최댓값 + 10.
- 패키지 인자가 없으면 결정 2의 자리표시자 상수를 import해 쓰고 경고를
출력한다. 인자가 있으면 external-contract-runtime의 신원 검사
(composeContractContributions)로 형식을 확인한다.
- 거부: kebab이 아닌 id, 기존 기능·context id(디렉터리 이름 포함),
같은 접두어를 쓰는 기존 기능, 이미 있는 <base>-context(--context 안내),
같은 라우트 루트·route ID·경로·chunk·문구 키.
- 폴더 밖은 새 context 선언과 pending a11y 기록만 쓴다. 기존 파일은
덮어쓰지 않고(wx), 쓰기나 직후 생성기 실행이 실패하면 만든 것을 지운다.
- 출력: 만든 파일, a11y 서명(FE-GATE-028), 돌릴 게이트 목록, 기준선
재승인이 필요 없다는 안내, 자리표시자 교체 방법.
- 테스트: tests/unit/create-feature.test.ts(렌더 결과만: 접두어, 샘플
토큰 없음, topic 형식·중복, 순서, 거부, 덮어쓰기·되돌리기).
생성된 기능의 테스트는 input 단위 테스트와 런타임 조립·라우터를 거치는
페이지 테스트다. MSW는 createHttpScenarioHandler(설치 계약)를 쓴다.
- 느린 드릴 test:feature-scaffold: removal-fixture로 만든 복사본(README·
CHANGELOG·docs 포함)에 기능을 만들고 커밋한 뒤 types, lint,
architecture, registries, i18n, design-system, diagnostics,
documentation, unit, component, integration, features, coverage,
check:ci, build를 돌린다. FE-GATE-020에 넣고 gates.json, 계약 기준선,
ci-workflow-generation 테스트의 개수를 맞췄다(workflow는 그대로).
- 결정 4: test:sample-removal이 기능 0개 검사 뒤 같은 복사본에서
create:feature로 기능을 만들고 같은 게이트를 scaffold- 이름으로 다시
돌린다.
- tests/release 고정 manifest가 계약 집합을 빈 배열로 고정해, EXTERNAL_
PACKAGE를 쓰는 첫 기능에서 7건이 release-mismatch로 깨졌다. 16-02가
tests/runtime-schema에 한 것처럼 설치된 집합에서 만든다.
- 버린 대안: 참조 기능 복사+토큰 치환(D1에 어긋나고 전역 ID를 놓친다),
topic을 뼈대에서 빼기(실제 기능이 같은 문제를 다시 만난다), 생성
테스트가 tests/mocks의 bootstrap·server를 쓰기(부팅 문서는 테스트 안의
fetcher가 주고, MSW는 setupServer와 http-scenarios만 쓴다).
위험·한계
- 생성기 파일이 1,408줄이다. 대부분 템플릿 문자열이다.
- context-module.ts는 생성기가 글로 읽는 선언이라 실행되지 않는다(참조
context와 같다). 나머지 생성 모듈은 생성된 테스트가 모두 실행한다
(함수 100%, 문장 100%, 페이지 분기 1개 미실행).
- --context reference-context로 참조 context에 넣으면 참조 기능의
installed-context-routing 테스트(라우트 4개 정확히 일치)가 깨진다.
드릴은 새 context를 쓴다.
- test:feature-scaffold, test:sample-removal, check:architecture는
pnpm이 필요해 worktree에서 돌리지 않았다.
- tests/unit/feature-shape-growth.test.ts는 기준 커밋에서도 1 KiB를 넘어
실패한다(이번 측정 1035·1068). 기능이 하나 더 있으면 통과한다.
검증
- RED: 생성한 기능을 넣고 돌리면 tests/release 7건 실패("expected
{ state: 'release-mismatch' } to match { state: 'booted' }"),
ci-workflow-generation 1건 실패(98 vs 99). 접두어 테스트는 템플릿의
스키마 ID를 "NoRequest"로 바꾼 변이에서 실패한다.
- GREEN(worktree에 order-feature 생성): tsc app·test·node rc=0, 전체
eslint rc=0, check-registries "11 registries PASS; compatibility=
additive"(기준선 재승인 없음), verify-documentation-readiness
PASS_SCOPED, check-i18n PASS, check-design-system·check-diagnostics·
check-adapter-inventory PASS, check-ci-contract·workflow·artifact
schema PASS, 생성 테스트 7/7, run-vitest tests/unit·component·features
238파일 통과, integration·contract·runtime-schema·platform·architecture·
release·scripts 59파일 통과(pnpm을 띄우는 2파일 제외).
- --context reference-context와 --package 변형도 tsc·registries·생성
테스트 통과. 참조 기능을 지운 복사본에서 생성 → tsc app·test, i18n,
생성 테스트·release·router 테스트 통과(결정 4 모의).
- 생성물을 지운 뒤 같은 검사 통과(feature-shape-growth 기존 실패 1건
제외), git status 깨끗.
문제: 레시피 번들 예산을 수정마다 100 B씩 올려 왔다. 한도가 늘 직전
측정값이라 예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못했다. 이번 수정
묶음 뒤 offline-indexeddb(37,327 > 36,900)와 realtime(40,902 > 40,900)이
넘었고, file-transfer는 여유가 47 B였다. remediation ledger는 예전 값
56,100을 적지 않아 check:remediation-ledger가 실패하고 있었다.
방법: 리뷰 결정(README 14절 0929/05-04)대로, 측정값 + 3%를 100 B 단위로
올린 값으로 한 번 정한다. 그 뒤 3% 안의 증가는 예산을 고치지 않고, 넘는
증가는 커밋 본문에 이유를 쓰고 같은 규칙으로 다시 정한다.
- file-transfer 56,053 → 57,800, offline-indexeddb 37,327 → 38,500,
realtime 40,902 → 42,200, service-worker-pwa 9,716 → 10,100
- 규칙·이유·측정 표는 optional-adapter-recipes.md의 예산 절에 둔다.
JSON은 주석을 받지 않아서다.
- realtime 문서 두 곳은 숫자 대신 정본 위치를 가리킨다. VD-10은 결정
기록이라 그대로 둔다.
버린 대안: 수정마다 100 B 인상(지금 방식), 레시피 예산에서 kernel 제외
(kernel 증가를 놓친다).
위험: 3% 여유 안에서는 회귀가 조용히 쌓인다. 예산 값을 표와 JSON 두
곳에 적으므로, 다음 인상 때 표도 같이 고쳐야 한다(ledger는
check:remediation-ledger가 file-transfer 값을 대조한다).
검증: check:optional-recipes:source PASS(4 budgets), verify:documentation
PASS_SCOPED, check:remediation-ledger의 예산 실패 사라짐(TR-02~04 기존
3건은 그대로, 게이트 밖).
문제: 855d22a가 ko-KR 샘플 문구를 한국어로 바꿔 목록 h1이 "참조 기능"이
됐다. reference-route.spec.ts는 h1이 route 제목("Reference feature")과
같다고 기대해 세 엔진 모두 실패했다. 화면은 정상이었다(같은 실행의
스크린샷에 h1, 인증됨, 모의 행이 모두 보인다). 그 수정 때 e2e를 돌리지
않아 놓쳤다.
방법: reference-form.spec.ts처럼 h1 문구를 직접 적는다. route 제목은
아직 catalog 밖 영어라(08-06 몫) h1과 같지 않다.
버린 대안: catalog에서 문구를 import — 다른 e2e와 방식이 갈린다.
검증: playwright test tests/e2e/reference-route.spec.ts — chromium·
firefox·webkit 3 passed. 전체 test:e2e는 이 한 건 외 184 passed.
문제: src/platform·src/apps·src/contexts의 구조·소유·예산·실행·
텔레메트리 규칙과 코드 주석 "Spec §N"의 근거가 2026-09-23 설계서
하나에만 있다. 그 설계서는 docs/reviews/ 안의 계획 묶음에 들어 있어
README가 복사 뒤 지워도 된다고 한 범위 안이다. 현재 계약 목록
(docs/README.md §1)에는 src/platform을 다루는 문서가 없다.
고른 방법: 설계서를 docs/architecture/scale-architecture.md로 복사한다
(git mv가 아니라 복사라 이력 묶음은 그대로 남는다). 본문 §1~§55는
영어 원문 그대로 두고 절 번호를 바꾸지 않는다. 맨 위에 상태 머리말을
붙인다: 현재 계약인 범위, 출처(커밋 6f6c48e와 원래 경로, git show로
보는 법), 코드와 달라진 곳을 절 끝 "> 2026-11-03 현재:"로 적는 규칙.
절 상태 표는 현재 계약(코드 참조) 41, 현재 계약 10, 기록만 4
(§40·§51·§53·§54), 미확인 0이다. 코드와 다른 18개 절에 차이를 한두
줄로 적었다(예: §4 최상위 domain/ 없음, §11 TrafficBudget에 deadline
없음, §40 부팅 게이트 없음, §47 CI는 pr 단계만). docs/README.md §1의
세부 규칙 목록에 새 문서를 더한다.
버린 대안: 필요한 절만 새로 쓰기. 68곳 넘는 주석의 절 번호 대응표가
필요해지고 원문과 갈라진다. 이력을 지우지 말라고 정책을 바꾸기
(리뷰 5.1절 (c)). 동기화 비용과 문서 섞임이 그대로 남는다.
위험·한계: 절 대조는 각 절을 가리키는 모듈의 타입·머리 주석·테스트
이름을 읽는 수준이다. 동작을 실행해 확인하지 않았다. 원문의 "Status:
Design approved…"와 예정 경로 줄은 머리말로 바꿨다. 예정 경로가 없는
파일을 가리켜 verify:documentation의 경로 검사에 걸리기 때문이다.
이 커밋만으로는 코드 주석이 아직 이름 없는 "Spec §N"이다. 다음
커밋이 바꾼다.
검증:
- 본문 비교: 원문 §1 이후와 새 문서 §1 이후의 diff에서 지운 줄 0,
"> 2026-11-03 현재" 메모 외에 더한 줄 0
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
(처음 "src/domain"을 백틱으로 적어 FAIL, 문구를 고쳐 PASS)
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
tests/unit/deletable-history-documents.test.ts: 15 passed
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.
고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
"§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
.dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.
위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.
검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
.dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
문제
- 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와
폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미,
결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패
메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다.
리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다.
- create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일
(a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다.
고른 방법
- docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과
안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일,
reference/ 4개(create-feature, global-ids, patterns, errors).
- 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다
정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을
적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트
밖 라우트는 이제 앱 모듈이 적재 때 거부한다).
- 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로
바꿨다.
- 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY,
게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿
docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은
design-docs의 conventions/feature-design-principles.md를 번호로만
가리킨다.
- 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지
않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는
것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만
더한다.
- 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조
페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다.
- 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고
지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기
(입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기
(메시지로 문서를 검색할 수 없다).
위험·한계
- docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는
verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래
.md만 검사하므로 reference/도 따로 링크해야 한다.
- 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절
번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다.
- 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만
둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능
테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다.
- "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시
돌리지 않았다.
검증
- docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고
node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서
모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다.
- 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두
말하며 FAIL_UNVERIFIED.
- 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고,
42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩
코드에서 확인했다.
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
tests/unit/deletable-history-documents.test.ts
tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.
문제: docs/manual/을 더했지만 입구 문서(README.md, docs/README.md)가
링크하지 않아 찾을 수 없고, verify:documentation도 매뉴얼을 검사하지
않았다.
방법: docs/README.md 1절의 세부 규칙 목록에 manual/과 manual/reference/를
링크한다. 1절에서 링크한 문서는 verify:documentation(FE-GATE-017)이 경로·
script·게이트 ID 실재를 검사한다. 루트 README의 Documentation 절에는
create:feature에서 시작하는 안내 한 줄을 둔다.
버린 대안: 입구 문서 표에 매뉴얼을 더하기 — 표는 계약을 정하는 문서
목록이고 매뉴얼은 그 계약을 쓰는 절차라 세부 목록에 둔다.
검증: verify-documentation-readiness PASS_SCOPED. documentReferences에
매뉴얼 8개 파일이 모두 들어가고 빠진 경로·script·게이트 ID 0.
문서 관련 단위 테스트 3파일 17건 통과.
문제: 2026-11-03 결정(리뷰 README 14절)에 따라 만든 커밋 40여 개가
CHANGELOG 미출시 절과 리뷰 README에 없었다. 다운스트림은 CHANGELOG의
[계약]·BREAKING 행으로 가져갈 수정을 고른다. CHANGELOG 11행은 0.2.0
해시가 main에서 다를 수 있다고 적었지만 52개 모두 main에서 닿는다.
방법:
- CHANGELOG 보안·계약 표에 BREAKING 2건(1101/08-03, 0929/05-03)과
[계약] 28건을 더했다. file-transfer 예산 행은 새 예산 규칙 행으로 바꿨다.
- 백엔드 리뷰에서 온 ID는 "백엔드 리뷰 1101/02-01"로 적어 이 repo의 같은
번호와 섞이지 않게 했다.
- 알려진 제한에서 풀린 것(registry-baseline source, OPFS 여러 페이지
purge)을 지우고 남은 위험을 더했다.
- 11행 해시 문장을 사실대로 고치고, docs/reviews/를 지운 복사본은 원본
repo에서 ID를 찾는다고 적었다.
- 리뷰 README에 14.2 결과, 14.3 새로 찾은 것, 14.4 남은 문제를 더했다.
위험: 행 수가 많아 다운스트림이 놓칠 수 있다. BREAKING은 표시 열 맨
앞에 둔다.
검증: tests/unit/changelog-review-ids.test.ts 통과(라운드 없는 ID 0).
표의 각 행 열 수를 확인했다(기존 이스케이프 행 1개 제외).
문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.
| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |
고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
(tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
src/contracts/api-operations.ts:9,25-27,112-125,142-190,
src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
(boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
src/adapters/http/request-builder.ts:129-135(V2만 읽음),
src/contracts/external-contract-runtime.ts:33,
src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
(src/adapters/http/feature-http-binding.ts:272-273,
src/adapters/http/http-execution-v3.ts:248-254,653-655,
src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
(src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
(실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
(http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
(src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
(src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
(http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
(reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.
남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).
검증:
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
request:start는 msw 타입에서 확인
문제: 결정 반영 묶음을 다 합친 뒤의 게이트 결과, 매뉴얼만으로 기능을
추가한 재실험 결과, 그 과정에서 찾은 결함이 리뷰 README와 CHANGELOG에
없었다.
방법:
- 리뷰 README 14.3에 세 가지를 더했다.
- create:feature와 참조 기능(V3 실행기)이 짝 백엔드 Envelope 응답을
읽지 못한다(High, P1, 결정 필요라 남김).
- 매뉴얼 재실험 결과: 막힘 5건, 예고된 실패 1건. 막힘은 매뉴얼에 메웠다.
- webkit old-tab-chunk-recovery 간헐 실패.
- 14.5에 7c7ef32 최종 게이트 표를 둔다.
- CHANGELOG 알려진 제한에 Envelope 제한과 webkit 간헐 실패를 더했다.
버린 대안: Envelope 제한을 이번에 고치기. V3 실행기에 Envelope 읽기를
넣을지, 백엔드가 problem+json을 보낼지는 두 repo에 걸친 결정이다.
게다가 백엔드 repo는 사람만 커밋한다.
위험: Envelope 제한이 풀리기 전에는 생성한 기능을 짝 백엔드에 바로 붙일
수 없다. 매뉴얼 01-3단계가 이를 적는다.
검증: tests/unit/changelog-review-ids.test.ts 통과. webkit 반복 실행
10/10 통과(load 16).
문제: `src/presentation/examples/ui-gallery-page.tsx`는 component 커버리지가
0%였다. e2e(`tests/e2e/ui-gallery.spec.ts`, 폼 검증과 모달 포커스 2건)와
시각 회귀만 이 화면을 봤다. 화면이 primitive에 연결한 규칙(공백 이름 거절,
알림 줄 문구, 알림 숨김·다시 표시, 모달 확인만 알림 줄을 바꿈, 메뉴의 toast)은
게이트 안 단위 실행에서 아무도 확인하지 않았다.
고른 방법: `tests/component/starter-ui-gallery-page.test.tsx` 9건. 화면을
LocaleProvider만으로 그리고 사용자 동작(user-event)으로 확인한다. 섹션 5개와
토큰 7개 렌더, 버튼 3개의 알림 문구, 빈 이름·공백 이름 거절과 trim한 이름
수락, controlled 입력 6종, 알림 숨김·복원, 모달의 취소·닫기·확인, 메뉴 두
항목, 수동 탭 활성화, tooltip 설명. 파일 이름은 starter 화면 테스트 규칙
(`docs/architecture/starter-experience.md`, `starter-*.test.tsx`)을 따라
화면을 지울 때 같이 지운다.
버린 대안: 스냅샷 테스트. 문구가 바뀔 때마다 깨지고 동작은 확인하지 않는다.
앱 라우터(`/examples/ui`)로 띄우기. 라우팅은 router 테스트가 보고, 이
화면은 provider가 locale 하나만 필요하다.
화면 코드는 고치지 않았다.
위험·한계: primitive 자체 동작(포커스 트랩, Esc, 화살표 이동)은 각 primitive
테스트와 e2e가 보고 여기서는 다시 세지 않는다. jsdom이라 실제 레이아웃과
`showModal()`의 top layer는 확인하지 않는다(e2e 몫).
검증:
- 커버리지(`node scripts/run-vitest.ts run tests/component --coverage
--coverage.include=src/presentation/examples/ui-gallery-page.tsx`):
전 lines 0/38, functions 0/19, branches 0/8
후 lines 38/38, functions 19/19, branches 8/8 (100%)
- 일부러 화면을 깨 봄(되돌림): fieldError의 trim 제거, 알림 onDismiss 무효화,
메뉴 "상태 확인" onSelect 무효화 → 9건 중 3건 실패
- tests/component 전체 38파일 253건 통과
- `npx eslint` 새 파일, `npx tsc --project tsconfig.test.json --noEmit` 통과
문제: `check:remediation-ledger`가 3건 실패한다.
TR-02: tests/unit/presigned-transfer.test.ts does not mention TR-02
TR-03: tests/unit/image-cdn-runtime.test.ts does not mention X-AUDIT-01 or X-AUDIT-02
TR-04: tests/unit/resumable-upload-runtime.test.ts does not mention TR-04
원인은 ID 표시가 지워진 것이 아니다. 2026-09-18 테스트 분할(`5cc41467`,
`ec7f20e2`)이 세 테스트를 표시째 다른 파일로 옮겼고, 원장과 dispositions
JSON은 옛 파일을 가리킨 채 남았다. 지금 위치:
TR-02 → tests/unit/presigned-transfer-delivery.test.ts:220
TR-03 이미지 probe → tests/unit/image-cdn-browser-probe.test.ts:579 (X-AUDIT-02)
TR-04 → tests/unit/resumable-upload-runtime-teardown.test.ts:80
분할 전 파일(`5cc41467^`)에 같은 주석과 테스트가 있었음을 확인했다.
고른 방법: 원장 행이 테스트가 실제로 있는 파일을 가리키게 한다.
`docs/operations/adapter-remediation-dispositions.json`의 evidence 3곳과
`docs/operations/adapter-remediation-ledger.md`의 같은 행 3개를 고치고,
머리말의 "옮긴 suite" 메모에 이번 분할을 더했다. 앞 절의 실행 명령은 그
실행이 쓴 파일 그대로 둔다(그 시점 기록).
버린 대안: 옛 파일에 TR-02·TR-04·X-AUDIT ID를 적기. 그 파일에는 해당
테스트가 없어서, 검사기가 막으려는 "관계없는 suite를 가리켜 증거처럼
보이기"를 그대로 만든다. 검사기와 markers 규칙은 바꾸지 않았다.
위험·한계: 테스트를 다시 쪼개거나 옮기면 같은 식으로 깨진다. 이 검사는
게이트 밖이라 그때도 아무도 모른다. `config/ci/ungated-scripts.json`의
이 검사 사유("Later fixes removed those markers … reports stale claims")는
이제 사실과 다르지만 이 커밋 범위 밖이라 고치지 않았다.
검증:
- RED(`ec7435c`): `node scripts/check-remediation-ledger.ts` 3건 실패, exit 1
- GREEN: "25 dispositions joined …; 0 open; evidence paths verified", exit 0
- 증거 suite 5개 77건 통과(`node scripts/run-vitest.ts run` 해당 파일)
- `verify-documentation-readiness.ts` PASS_SCOPED, `check-ci-contract.ts` PASS,
`check-adapter-inventory.ts` PASS, `tests/unit/ungated-scripts.test.ts` 10건 통과
문제: config/ci/ungated-scripts.json은 check:remediation-ledger를 게이트
밖에 두는 이유로 "표시가 지워져 지금 커밋에서 낡은 주장을 보고한다"를
적는다. 1335087 뒤로 이 검사는 통과하고, 실패 원인도 표시 삭제가 아니라
테스트 분할로 파일이 옮겨 간 것이었다.
고른 방법: 게이트 밖에 두고 이유만 사실대로 고친다. 지금 통과한다는 것,
게이트에 넣지 않는 실제 이유(제품이 선택 레시피 file-transfer를 빼거나
테스트 분할로 표시한 테스트가 옮겨 가면 실패한다), 언제 손으로 돌리는지를
적는다.
버린 대안: FE-GATE-010에 넣기. 1초 안에 끝나고 이번 같은 분할을 바로
잡았겠지만, 이 검사는 file-transfer 레시피 예산을 읽어 그 레시피를 뺀
제품의 merge를 막는다. 선택 레시피를 빼는 것은 템플릿이 허용한 경로다.
위험·한계: 다음 테스트 분할 때 원장이 다시 낡아도 게이트는 모른다.
이 검사는 작업 이력 원장이라 그 비용을 받아들인다.
검증: node scripts/check-remediation-ledger.ts 통과(25 dispositions,
0 open), tests/unit/ungated-scripts.test.ts 10건 통과
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.
고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
프레임을 확인한다. outputValidator는 data(키가 없으면 null),
problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
<base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
답한다.
버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.
위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
check:registries, check:diagnostics, check:i18n, check:ci 통과.
test:unit 2,604, test:component 244, test:integration 200 통과.
tests/features·tests/contract 124건 통과.
test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
Envelope로 답하는 목록 화면 테스트 3건 포함).
test:sample-removal 23개 검사 통과.
check:bundle 통과(203,321 / 204,800 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
문제
V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400
IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로
남긴다(93782b0). V3 실행기의 진단에는 백엔드 code가 없다(리뷰 README
14.4). Problem 타입이 계약 패키지 소유라 실행기가 code를 몰랐기 때문이다.
7db32e1 뒤로 responseEnvelope: "ENVELOPE_V1" operation의 실행기는
Envelope error.code를 읽는다.
고른 방법
- Envelope operation의 실패에서 backend-envelope.ts의
idempotencyRefusalReason(code, status)를 불러 V2와 같은 두 값을
HttpDiagnosticReason으로 싣는다. projector(runtime-adapters.ts)는 이미
diagnosticReason을 reason으로 옮기므로 bootstrap은 바꾸지 않았다.
- 표의 reason 타입을 IdempotencyRefusalReason으로 좁혀 두 값이 닫힌
목록임을 타입으로 둔다.
버린 대안
- 백엔드 code를 reason에 그대로 넣기: reason은 이 repo가 소유한 닫힌
목록(taxonomy)이고, 서버 code를 그대로 넣지 않는다는 93782b0 결정과
어긋난다. V2도 넣지 않는다.
- 새 진단 키(problem_code) 추가: src/contracts/diagnostics.ts 허용 목록과
bootstrap projector를 함께 바꿔야 하고 cardinality 등급을 새로 정해야
한다. 이 변경 범위를 넘는다.
위험·한계
- 그 밖의 백엔드 code는 진단에 없다. 실패의 AppFailure.code에만 있다.
- DTO 모드 operation(참조 기능)의 진단에는 여전히 code가 없다.
- classifyProblem이 던져 CLASSIFIER_FAILED가 되는 경우는 Envelope 판정이
있으면 분류기를 부르지 않으므로 둘이 겹치지 않는다.
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts의 "V3 Envelope
diagnostics name what V2 names" 4행 중 2행 실패(422·400에서 V3 reason
undefined). 409 두 행은 처음부터 통과(reason 없음 고정).
- GREEN: 같은 파일 29건 통과. 같은 응답의 V2 진단 기록과 V3 진단 기록의
reason을 비교한다.
- check:types, lint, check:architecture, check:diagnostics 통과.
test:unit 2,604, test:integration 204, test:component 244,
tests/features·tests/contract 124건 통과.
- check:bundle 통과(203,352 / 204,800 B, 7db32e1 대비 +31 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
문제
매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은
짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진
제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1"
operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503
흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다.
고른 방법
- 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드
problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정
표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의
처리 칸은 14.6을 가리킨다.
- 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고,
Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem
details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다.
- 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름.
- CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언,
V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다.
- 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는
범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다.
- 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을
backend-envelope.ts로 고쳤다.
버린 대안
- 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다.
위험·한계
- 문서의 게이트 결과는 이 커밋 직전 트리(bd83b49, scaffold·sample-removal은
7db32e1)에서 잰 값이다.
- 백엔드 링크는 두 repo가 나란히 있을 때만 열린다(기존과 같다).
검증
- verify:documentation PASS_SCOPED.
- 게이트 수치는 README 14.6 결과 표에 실행한 커밋과 함께 적었다.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
문제
"검증 거절은 적용 안 됨" 판정(64e98ee)의 근거가 추론이었다. 백엔드
http-contract.md 4절은 VALIDATION_FAILED의 출처를 적지만 "상태를 바꾸지
않는다"는 문장이 없다. 그 밖의 400·409·422 code는 어느 단계에서 나오는지
적힌 곳이 없었다. 계약 4.1·6절은 백엔드 커밋이 없어 기준을 결정일로 적었다.
고른 방법
- 백엔드 5786126c 코드에서 400·409·422를 내는 곳을 모두 찾고, code마다
단계(쓰기 전 / 쓰기 뒤 가능)와 프론트 결과(NOT_APPLIED / MAYBE_APPLIED),
백엔드 파일:줄을 6.1절 표에 적었다. 같은 code가 쓰기 전과 뒤에서 모두
나오면 쓰기 뒤 가능으로 둔다. 프론트는 code만으로 둘을 가르지 못한다.
- 4.1·6절 기준을 결정일에서 백엔드 SHA 5786126c로 바꿨다.
- 표와 지금 프론트 판정이 다른 곳을 같은 절에 적었다. client.ts는 다른
작업이 고치고 있어 이 변경에서 건드리지 않았다.
찾은 것
- 쓰기 전: VALIDATION_FAILED(출처 5곳 모두 바인딩·검증 단계, CVE handler는
지금 요청 경로 출처 없음), IDEMPOTENCY_KEY_INVALID, IDEMPOTENT_REQUEST_
MISMATCH. IDEMPOTENT_IN_FLIGHT도 이번 요청은 쓰기 전이지만 앞선 요청이
적용될 수 있어 MAYBE_APPLIED다.
- 쓰기 뒤 가능: BAD_PARAMETER(모든 층의 IllegalArgumentException),
MAPPING_FAILED(멱등성 응답 직렬화는 action이 끝난 뒤), DB_* 409 8종,
LOCK_ACQUISITION_TIMEOUT, 참조 도메인 400·409 6종, 선택 모듈 11종.
fileserver INTEGRITY_MISMATCH·MALWARE_DETECTED(422)는 레코드를 REJECTED로
쓴 뒤 던진다.
- 프론트와 다른 곳: 필드 목록 없는 400 VALIDATION_FAILED는 표로 NOT_APPLIED인데
V2는 effect가 없다. V2는 422 전체를 NOT_APPLIED로 보지만 fileserver 422는
MAYBE_APPLIED다. V3 참조 분류기는 400·422 전체를 NOT_APPLIED로 본다(참조
fixture용, 짝 백엔드에는 맞지 않는다).
버린 대안
- 백엔드 문서 표를 프론트 문서에 복사: 단계 정보는 백엔드 문서에 없다.
복사할 것이 아니라 프론트가 코드에서 읽은 판정이라 SHA와 파일:줄로 적었다.
- 프론트에 백엔드 소스를 읽는 검사 추가: 두 repo가 나란히 있어야만 돈다.
표를 SHA에 묶고, SHA를 올릴 때 표를 다시 확인하라고 적었다.
위험·한계
- "쓰기 전"은 지금 코드에서 handler에 닿는 출처를 센 결과다. 백엔드가
application bean에 @Validated를 달거나 JPA entity에 Bean Validation 제약을
넣으면 필드 목록 있는 VALIDATION_FAILED가 use case 안에서도 나온다. 백엔드에
이것을 막는 검사는 없다.
- 줄 번호는 5786126c 기준이다. 백엔드가 바뀌면 어긋난다.
검증
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- 표의 파일:줄은 백엔드 5786126c에서 grep·sed로 다시 열어 확인했다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.4
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.
고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.
버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
(check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
목록은 테스트에 SHA와 함께 적었다.
위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
청크에 있다.
검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
"Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
문제: 손상 때문에 끝나지 못한 LOGOUT·ACCOUNT_DELETION purge의 partition
삭제는 두 단계다. 디렉터리를 origin lease 안에서 지우고, 이어서 journal
row를 lease 밖에서 지운다. origin lease는 put의 BEGIN~FINISH만 막는다.
그래서 다른 탭에서 journal `begin`을 끝낸 put이 두 단계 사이에 BEGIN을
하면 새 디렉터리에 파일을 쓰고, 두 번째 단계가 그 put의 row를 지운다.
put은 다음 journal 단계에서 `CONFLICT`로 실패하지만 파일을 치울 주체가
없다.
- markFilesReady 전에 row가 지워지면: 보상이 manifest·staging을 지우고
chunk가 남는다.
- commitPut 전에 지워지면: 보상이 없어 manifest·FILES_READY staging
receipt·chunk가 남는다. staging receipt가 chunk를 GC·sweep에서 지키고
row가 없어 reconcile도 보지 않으므로 영원히 남는다. 다음 LOGOUT purge는
`chunkSweep: COMPLETED`를 보고하면서 이 bytes를 남긴다.
- commit 뒤 complete 전에 지워지면: put은 성공하지만 object는 없고
manifest·chunk가 남는다.
삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우(72edb55가 가정한
경우)는 수정 전에도 put이 `CONFLICT`로 실패하고 bytes가 남지 않았다.
고른 방법: partition 단위 Web Lock
(`<mutationLockName>:partition:<a>:<ns>:<p>`)을 둔다. 모든 put·delete는
`withTransactionLock` 안에서 journal `begin`부터 끝날 때까지 shared로
쥐고, partition 삭제는 디렉터리·journal 두 단계를 exclusive로 쥔 채 한다.
mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 진행 중이던 put은 끝난
뒤 삭제가 지우고, 삭제가 lock을 요청한 뒤 온 put은 삭제 뒤에 돈다.
lock 순서는 partition lock → origin lease 하나뿐이라 교착이 없다
(per-transaction lock은 `ifAvailable`이라 기다리지 않는다). 기다리는
동안 purge `signal`을 abort하면 `ABORTED`를 반환한다.
버린 대안:
- commitPut `CONFLICT`면 보상: commitPut 전 경우만 고치고 chunk와
commit 뒤 경우가 남는다. 또 port가 "CONFLICT = 아무것도 commit 안 됨"을
약속하지 않아 동봉 구현에 기대는 숨은 결합이 생긴다.
- commit까지 origin lease 쥐기: lease는 worker 안에 있고 journal은 page
쪽이다. 두 번째 단계(row 삭제)가 lease를 쓰지 않아 commitPut 전 경우가
그대로다.
- row를 먼저 지우고 디렉터리를 나중에: 그 사이 begin한 put이 디렉터리
단계 전에 FINISH하면 파일 없는 COMMITTED row가 생긴다. 중간 실패 뒤
재호출로 이어서 끝나는 성질도 잃는다.
- 디렉터리 → row → 디렉터리: 같은 이유로 파일 없는 commit이 생긴다.
위험·한계:
- 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle
bound(05-07)까지 삭제를 붙잡는다. 수정 전에도 그 put은 origin lease를
쥐고 있어 디렉터리 단계가 같은 시간을 기다렸다.
- reconcile은 partition lock을 쥐지 않는다. reconcile은 파일을 새로 쓰지
않으므로(검증·정리·finalize만) 삭제와 겹쳐도 bytes를 남기지 않는다고
보았고, 이 경우는 테스트하지 않았다.
- put·delete마다 Web Lock 요청이 하나 늘어난다.
- offline-indexeddb 레시피 gzip 37,327 → 37,423 B(한도 38,500).
- 공개 타입·배럴 변경 없음.
검증:
- RED(수정 전, put 결과 단언을 넣기 전): 새 it.each 5건 중 3건 실패.
디렉터리를 put BEGIN 전에 지운 경우만 실패했다.
markFilesReady 앞: chunk 1개 남음. commitPut 앞: staging receipt·chunk·
manifest 남음. complete 앞: chunk·manifest 남음.
삭제 전체가 FINISH~commit 사이인 2건은 통과(put CONFLICT, bytes 0).
"put은 삭제 앞에 끝난다" 단언을 더한 뒤 수정 전 코드: 5건 모두 실패.
- GREEN: 5건 + abort 테스트 1건 통과. 같은 5건 10회 반복 10/10.
- `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
tests/recipes` 136건 통과.
- tsc app·test·web-worker·recipes 통과. 바꾼 파일 eslint 통과.
`check-adapter-inventory` PASS, `check-optional-recipes`(source) PASS,
`verify-documentation-readiness` PASS_SCOPED.
- 미실행: `check:browser-file-storage-boundaries`·`check:architecture`
(pnpm 필요), Playwright OPFS spec(webServer가 pnpm).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다.
live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로
보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte
deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가
조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다.
- switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER
- activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER
- checkpoint 마감: IDLE_TIMEOUT/RECOVER
- close drain 마감: IDLE_TIMEOUT/CLOSE
고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고
operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다.
- quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의
apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다.
APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은
분기를 `quiescenceFailure` 하나로 합쳤다.
- checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가
throw할 때와 같은 kind다.
- close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect
coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두
분기를 하나로 합쳤다.
- 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지
않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과
retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의
RECEIVE·SUBSCRIBE(전송 idle)뿐이다.
버린 대안:
- retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는
어휘다. 재시도 판단 변경은 따로 정한다.
- close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가
settle하지 않았는데 "닫힘"으로 읽힌다.
위험·한계:
- 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을
보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo
안에 소비자는 없다(AVAILABLE_NOT_COMPOSED).
- handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다.
- 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는
true다. 13.1 표에 둘 다 적었다.
- realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200).
검증:
- RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로
넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9
passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll
quiescence, activateProbe quiescence, checkpoint).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files,
231 passed.
- tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과,
`check-optional-recipes`(source) PASS, `verify-documentation-readiness`
PASS_SCOPED, `check-adapter-inventory` PASS.
- 미실행: `check:architecture`(pnpm 필요).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4
문제
09-02(da1e128) 뒤에도 tech-log가 하는 일 두 가지는 템플릿 파일을 고쳐야
한다(리뷰 1101 README 14.4 "09-02 이식").
- 제품 설정 키의 FE-REG-ENV 행: tech-log는 템플릿 src/contracts/env.ts의
ENV_REGISTRY에 TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE 행을 직접
넣었다(tech-log env.ts:63-70).
- 부트 전 BFF 세션 owner: 세션이 httpOnly 쿠키라 owner가 백엔드에 묻는다.
tech-log는 템플릿 create-runtime-composition.ts에서 AUTH_MODE external이고
Studio가 HTTP일 때 createRuntimeAdapters 전에 host 전역
__CA_FRONTEND_AUTH_OWNER__에 owner를 넣는다(:2, :36-52,
bff-session-owner.ts:188-194). composeProduct는 http가 생긴 뒤에 불리고
http는 세션이 필요해서 이 일을 받을 수 없다.
고른 방법
- product-contracts.ts에 PRODUCT_ENV_REGISTRY를 빈 값으로 둔다. env.ts는
PRODUCT_REST_AUTH_PROFILES·PRODUCT_RUNTIME_CONFIG_FIELDS와 같은 모양으로
그 행을 ENV_REGISTRY에 합친다. 템플릿 키와 이름이 겹치면 모듈 로드 때
throw한다. check:registries와 vite.config.ts가 같은 객체를 읽으므로 제품
행도 같은 필드 검사를 받는다. 행을 더하기만 하면 additive라 기준선을
고치지 않는다(실험: 제품 행 2개 → compatibility=additive PASS, 허용 밖
classification → 실패).
- product-composition.ts에 composeProductSessionOwner(context)를 둔다.
템플릿은 null을 돌려준다. 조립 루트가 세션을 고르기 전에, AUTH_MODE가
external일 때만 부른다. 제품 owner가 host 전역보다 먼저다. null이면
지금처럼 host 전역, 없으면 unavailable이다. demo 모드는 묻지 않는다.
context는 config와 fetcher뿐이다(http 전이라 capability가 없다).
버린 대안
- owner를 composeProduct 반환값에 넣기: http가 세션을 쓰므로 순서가 꼬인다.
- 제품이 host 전역에 계속 넣게 두고 문서화: 부트 전 훅이 템플릿 파일
(create-runtime-composition.ts)에 남는다.
- FE-REG-ENV 행을 PRODUCT_RUNTIME_CONFIG_FIELDS에서 자동으로 만들기: zod
필드로는 classification·required를 알 수 없다.
- 행 타입·도우미를 product-contracts.ts가 env.ts에서 import: 순환 의존
(no-circular-dependencies)이다. 타입 검사는 env.ts의 대입에서 한다.
위험·한계
- product-composition.ts에 export가 하나 늘었다. 이 파일을 이미 복사한
제품은 composeProductSessionOwner를 더해야 한다. da1e128은 아직 main에
없고 두 다운스트림 모두 받지 않았다.
- 제품 행을 as const 없이 쓰면 phase가 string으로 넓어져 tsc 오류가
env.ts:78(템플릿 파일)에서 난다. 메시지에 키 이름은 나온다. product-
contracts.ts 주석에 as const를 적었다.
- 제품 설정 키에 FE-REG-ENV 행이 있는지 요구하는 검사는 여전히 없다.
템플릿 키도 RELEASE_ID·BUILD_ID는 행이 없어서 이 변경에서 넣지 않았다.
- 제품 owner가 throw하면 createRuntimeAdapters가 실패해 부트 실패
화면이 된다. composeProduct와 같다.
- tech-log의 owner는 subject를 null로 돌려준다(템플릿 동작대로 매 변경
fence). 이 변경과 무관하다.
검증
- RED: tests/unit/product-composition-fixture.test.ts 13건 중 3건 실패.
FE-REG-ENV 행 없음, external 모드 세션이 authenticated가 아니라
integration-failed, env 이름 충돌을 거절하지 않음.
- GREEN: 같은 파일 13/13, runtime-adapters-credential-order 7/7(mock에
composeProductSessionOwner: () => null 추가).
- fixture는 vi.mock 대상이 제품 소유 두 파일(머리 주석 "Product-owned.")과
설치 기능 seam 두 개뿐이고, tech-log가 고친 템플릿 파일 4개(env.ts,
create-runtime-composition.ts, runtime-config-schema.ts,
runtime-adapters.ts)는 대상이 아님을 이 파일의 소스를 읽어 확인한다.
- 회귀: tests/unit·contract·runtime-schema·integration 198 files 2861
tests 통과(heavy lock 아래).
- tsc app·node·test 통과, 바꾼 파일 eslint 통과, check:registries PASS
(compatibility=none, 재승인 불필요), verify:documentation PASS_SCOPED,
check:adapter-inventory PASS.
- 초기 JS gzip 202,770 → 202,931 B(+161, 예산 204,800). 같은 방법(dist
manifest의 초기 파일 26개, gzipSync 기본 레벨)으로 전·후를 쟀다.
- 미실행: check:architecture(pnpm 필요), test:component, e2e.
문제: config.json V2 스키마의 키 중 RELEASE_ID와 BUILD_ID에는
FE-REG-ENV(ENV_REGISTRY) 행이 없다. 이를 잡는 검사도 없다. 그래서
제품이 PRODUCT_RUNTIME_CONFIG_FIELDS에만 키를 더하고 PRODUCT_ENV_REGISTRY
행을 빠뜨려도 check:registries가 그 키를 보지 못한다. ece944d를 검토하다
찾았다.
고른 방법:
- tests/unit/env-registry-coverage.test.ts를 더한다. runtimeConfigV2
ArtifactSchema의 모든 최상위 키에 phase "runtime" 행이 있어야 한다.
제품 필드는 withProductFields로 같은 shape에 들어가므로 같이 검사된다.
- RELEASE_ID, BUILD_ID 행을 public-metadata, 선택, 기본값 null로 더한다.
빌드가 config.json에 쓰는 릴리스 신원이고, VITE_BUILD_ID와 같은 분류다.
버린 대안: check-registries.ts에서 검사하기. 그 검사기는
registry-governance.json에 적힌 레지스트리 export를 같은 규칙으로 읽는
일반 검사기다. 스키마와 레지스트리를 맞대는 규칙을 넣으면 FE-REG-ENV
하나만을 위한 분기가 생긴다. 테스트 하나로 같은 실패를 낸다.
위험·한계: V1 전용 키(API_CONTRACT_VERSION)는 검사하지 않는다. 그 행은
FE-REG-ENV 변경 증거로 지워졌고, V1 reader는 지울 예정이다. 행을 더한
것은 additive라 기준선을 고치지 않는다.
검증:
- RED: 새 테스트가 ["RELEASE_ID", "BUILD_ID"]를 보고하며 실패
- GREEN: 통과. env 관련 unit 4파일 43건 통과
- node scripts/check-registries.ts: 11 registries PASS, additive
- tsc app·test, eslint 통과
문제
계약 문서 6.1절(ed0e4b1, 백엔드 5786126c 코드 기준)은 400·409·422 code마다
쓰기 전 거절인지를 정했다. 쓰기 전이라 적용 안 됨인 것은 400
VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID,
422 IDEMPOTENT_REQUEST_MISMATCH뿐이고, 표에 없는 400·409·422는 쓰기 뒤에도
나올 수 있어 결과 불명이다. 지금 판정은 이 표와 세 곳이 다르다.
- V2: 필드 목록 없는 400 VALIDATION_FAILED({cause}, details 없음,
{field, code})에 effect가 없다. 결과 불명으로 붙들려 다시 저장할 수 없다.
- V2: 422는 code와 상관없이 적용 안 됨이다. fileserver의 422
INTEGRITY_MISMATCH·MALWARE_DETECTED는 레코드를 쓴 뒤 던진다.
- V3 Envelope operation(7db32e1): 위 V2 규칙을 같이 쓰고, 표 밖 400·409·422는
classifyProblem에 맡긴다. 400·422를 모두 적용 안 됨으로 보는 분류기면
BAD_PARAMETER·도메인 400이 틀린다.
고른 방법
- backend-envelope.ts에 표 REFUSED_BEFORE_WRITE(code → status, 진단
reason)를 하나 두고 V2 client.ts, V3 실행기가 envelopeFailureEffect로
같이 읽는다. 표에 있으면 NOT_APPLIED, 그 밖의 400·409·422와 503
IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED, 나머지 status는 undefined
(V2는 effect 없음, V3는 classifyProblem)다. 진단 reason도 같은 표에서
읽는다.
- kind와 validationIssues 판정(isFieldValidationFailure)은 그대로 둔다.
필드 목록 없는 400 VALIDATION_FAILED는 UNKNOWN_CLIENT_FAILURE, 422는
VALIDATION_REJECTED다. 적용 여부만 바뀐다.
- V3 Envelope operation에서는 400·409·422를 표가 정하고 classifyProblem이
바꾸지 못한다.
버린 대안
- V2와 V3에 표를 따로 두기: 7db32e1 전처럼 두 벌이 갈라진다.
- 표 밖 400·409·422를 classifyProblem에 맡기기: 6.1절이 표 밖은
MAYBE_APPLIED로 정했고, 적용 안 됨을 잘못 내면 다음 저장이 새 키를 써
같은 작업이 두 번 적용된다. 잘못된 MAYBE_APPLIED는 결과 불명 화면만 남긴다.
- 422 전부를 필드 검증(적용 안 됨)으로 남기기: 짝 백엔드는 필드 검증을
400으로 보내고, fileserver 422는 쓴 뒤 던진다.
- V3 참조 기능 분류기 고치기: 참조 기능은 Envelope operation이 아니고
fixture가 problem details라 이 표의 대상이 아니다. 고치지 않았다.
위험·한계
- 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에
폼에서 다시 저장할 수 없다(결과 불명). 프론트 계약 문서 4.2절의 "422
field validation" 행과 어긋난다. 그 문서는 이 커밋에서 고치지 않았다.
- 표는 백엔드 5786126c 기준이다. 백엔드가 쓰기 전 거절 code를 새로 만들면
6.1절과 이 표를 함께 고쳐야 한다. 두 repo를 비교하는 검사는 없다.
- 6.1절의 남은 위험: 백엔드가 use case 안에서 VALIDATION_FAILED를 내게 되면
적용 안 됨 판정이 틀린다.
검증
- RED: 바뀐 행 8건 실패. tests/integration/http-client.test.ts 필드 목록
없는 400 VALIDATION_FAILED 3모양의 effect, http-diagnostics.test.ts의
"unrelated 422"(effect NOT_APPLIED), http-execution-v3-envelope.test.ts의
고정 판정 2건(VALIDATION_FAILED 3모양 NOT_APPLIED, BAD_PARAMETER·도메인
409·fileserver 422 MAYBE_APPLIED), form-foundation.test.tsx 2건({cause}
실패 뒤 다시 저장, 422 뒤 저장 버튼 꺼짐).
- GREEN: 위 4개 파일 128건 통과. V2와 V3에 같은 응답 11가지를 보내 판정을
비교하는 행이 모두 같다.
- check:types, lint, check:architecture, check:diagnostics, check:ci,
check:registries, check:adapter-inventory 통과. test:unit 2,604,
test:integration 209, test:component 245, tests/features·tests/contract
124건 통과. check:bundle 203,354 / 204,800 B.
Refs: docs/architecture/backend-api-and-server-state-contract.md 6.1 (ed0e4b1),
docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).
고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
`loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
`loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.
버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.
위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
`AppShell`만 돈다.
검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
("expected to have a length of 1 but got +0"). AppShell skip link href를
`#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
PASS_SCOPED.
문제: 라우터는 `AppShell` 아래 플랫폼 라우트를 모든 context보다 먼저 붙인다.
그래서 기능 라우트를 플랫폼 라우트도 받으면 오류 없이 플랫폼 화면이 나온다.
React Router `matchRoutes`로 라우터와 같은 구조를 만들어 확인했다.
- 같은 경로: context `examples/*`의 `/examples/ui`는 `EXAMPLES_UI`가 받는다.
레이아웃 아래에서도 순위가 같으면 앞에 있는 `AppShell`이 이긴다.
- `APP_HOME`이 아닌 id로 선언한 `/`는 플랫폼 홈이 받는다(ca16187 한계).
- 레이아웃 없는 `*` 루트 context는 모든 URL을 NOT_FOUND splat에 뺏긴다.
splat끼리 순위가 같고 플랫폼 쪽이 먼저다. 7139c7c의 루트 검사는 context
루트끼리만 비교해 이 셋을 통과시킨다.
고른 방법: 라우트 조립 런타임, 곧 `defineDeployableAppModule`의 09-06 검사
(`assertFeatureRoutesReachOwningContext`)에 한 단계를 더한다. 기능 라우트
경로마다 `[대체되지 않은 플랫폼 라우트..., context가 붙는 자리]`로
`matchRoutes`를 돌려, 그 context가 받지 않으면 route id, 경로, 기능, context,
가로챈 플랫폼 라우트를 담아 TypeError로 실패한다. context가 붙는 자리는
라우터와 같다. 레이아웃이 없으면 루트이고, 있으면 그 라우트의 경로다. 기능이
대신한 `APP_HOME`은 플랫폼 쪽에서 빼고, `APP_HOME` 라우트 자체는 지금처럼
건너뛴다.
- 앱 모듈을 평가할 때 실패하므로 부트와 앱 모듈을 불러오는 모든 테스트가
막힌다(fail-closed). 기존 09-06 검사와 같은 자리이고, 라우트 정의는 이미
초기 그래프에 있다.
버린 대안:
- 라우터(`createRegisteredRoutes`)에서 검사: 라우터 표 자체로 보니 순위가
정확하다. 하지만 `AppRouter`가 마운트될 때에야 실패하고, 앱 모듈을 fixture로
바꿔 끼우는 테스트를 따로 만들어야 한다.
- 아키텍처 테스트: 템플릿에 설치된 기능만 보고, 다운스트림이 기능을 더한
빌드는 실행 때 지켜지지 않는다.
- 레지스트리 검사(`check:registries`) 또는 생성기: 생성기는 정규식으로
리터럴만 읽어 라우트 경로를 모른다.
- 경로 문자열 비교: `*` 루트와 파라미터 모양이 같은 경로를 놓친다.
위험·한계:
- 라우터 순서를 이 함수가 따라 한다. `app-router.tsx`가 플랫폼 라우트를
context 뒤로 옮기면 이 검사도 같이 바꿔야 한다. 주석에 적었다.
- 일부만 겹치는 경우(`/examples/:slug`의 `ui` 값)는 막지 않는다. 그 기능
라우트는 다른 값으로는 닿는다.
- 기능끼리 같은 경로는 이 커밋 범위가 아니다.
검증:
- RED: tests/architecture/context-route-roots.test.ts 새 5건 중 거절 4건이
"expected [Function] to throw an error"로 실패(21건 중 4 실패).
- GREEN: 21건 통과. 메시지 예: "Route EXAMPLES_UI_COPY (/examples/ui) of
feature examples-feature in context examples is answered by platform route
EXAMPLES_UI (/examples/ui). A feature replaces a platform route only by
declaring its id (APP_HOME)."
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files 중 3,569 통과, 1 실패. 실패는 telemetry-storm.test.ts 10초
timeout(부하 44)이고 단독 재실행에서 4건 통과했다.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. check-registries 통과.
verify-documentation-readiness PASS_SCOPED.
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
`NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
`route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
`invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
붙어서 지금은 닿지 않는 값이다.
이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.
고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.
버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
`route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.
위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
`route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
않았다.
검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
`"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
`"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
(`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
문제: 7d85589는 플랫폼 라우트가 가리는 기능 라우트를 막지만, 기능 라우트
둘이 같은 경로를 쓰는 경우는 막지 않는다. 라우터는 순위가 같은 경로를
선언 순서로 고르므로 뒤의 라우트는 그려지지 않는다. 메뉴와 레지스트리에는
그 라우트가 나온다. 파라미터 이름(`:orderId`와 `:itemId`)은 순위를
바꾸지 않으므로 이름만 다른 경로도 같은 경로다. R-B가 남긴 것으로 보고했다.
고른 방법: 같은 함수(assertFeatureRoutesReachOwningContext)에서 플랫폼
검사를 통과한 라우트마다 파라미터 이름을 지운 경로 모양을 기록하고, 이미
있으면 두 라우트와 기능 이름을 담아 throw한다. 앱 모듈을 평가할 때
실패하므로 09-06·09-03 검사와 같이 fail-closed다. APP_HOME 대체는 이
함수의 앞쪽 continue로 빠지고, 두 기능이 같은 플랫폼 라우트를 가져가는
경우는 기존 검사(withoutTakenOverPlatformRoutes)가 막는다.
버린 대안: 레지스트리 검사(check:routes)에서 경로 중복 보기. 그 검사는
route ID 중복만 보고, 라우터가 실제로 어떤 순위로 고르는지는 모른다.
위험·한계: 일부만 겹치는 경로(`/a/new`와 `/a/:id`)는 라우터가 정적 경로를
먼저 고르므로 막지 않는다. 그 경우는 accepts 테스트로 고정했다. splat(`*`)
기능 라우트끼리의 겹침은 모양 비교로만 본다.
검증:
- RED: 새 테스트 2건 중 "같은 경로 거절"이 실패(22/23 통과)
- GREEN: tests/architecture와 라우트 component 테스트 75건 통과
- tests/unit·component·integration·features 253파일 3,153건 통과
- tsc app·test, eslint 통과
문제
3261208이 V2·V3의 거절 판정을 계약 문서 6.1절 표로 바꿨다. 매뉴얼 02
4절은 아직 "422 전부와 필드 목록 400은 적용 안 됨, 그 밖은
classifyProblem"으로 적고, 리뷰 README 14.6 판정 표, 14.4의 검증 거절 줄,
CHANGELOG의 7db32e1 행도 같은 옛 규칙을 적는다.
고른 방법
- 매뉴얼 02 4절: 표의 세 code(적용 안 됨)와 그 밖의 400·409·422(결과 불명),
근거가 계약 문서 6.1절이라는 것, 쓰기 전 거절 code를 새로 만들 때 두 곳을
함께 고친다는 것.
- 매뉴얼 01 3단계: 실행기가 정하는 status 범위를 400·409·422와 503으로 적었다.
- 리뷰 README 14.6: 판정 표를 새 표로 바꾸고 처음 규칙을 한 줄로 남겼다.
"6.1 표 반영" 단락에 바뀐 것, 버린 대안, 위험, RED·GREEN, 게이트를 적었다.
14.4 줄에 바뀐 판정을 덧붙였다.
- CHANGELOG: [계약] 행 하나를 더하고 02e35d2·7db32e1 행이 그 행을 가리키게
했다.
위험·한계
- 계약 문서 6.1절은 오케스트레이터 브랜치(ed0e4b1)에만 있다. 이 브랜치의
매뉴얼은 그 절을 가리키지만, 합치기 전에는 그 절이 없다.
- 프론트 계약 문서 4.2절 "422 field validation" 행은 고치지 않았다.
검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
문제
webkit에서 old-tab-chunk-recovery.spec.ts가 가끔 실패한다. WebKit은 문서의
load 이벤트 3초 뒤에 한 번, 아직 쓰지 않은 link preload마다 경고를 남기고
strict console 검사가 그 경고를 실패로 본다.
- A 탭에서 B를 배포하고 플랫폼 화면을 누르면, Vite preload helper가 페이지
청크와 그 청크가 import하는 badge·card·schema-registry·server-state를 같이
preload한다. 페이지 청크가 404라 import가 실패하고, 같이 받은 청크는 끝까지
쓰이지 않는다. 복구가 release manifest를 읽는 동안 A 문서가 load+3초를
넘기면 경고 4줄이 나온다. B 탭의 UI 화면에서도 같은 일이 생긴다
(text-field).
- 그 청크들은 플랫폼 화면이 실제로 import한다(.vite/manifest.json). 앱이
쓰지 않는 청크를 preload하는 것이 아니다. 경고는 테스트가 일부러 지운
청크의 결과다.
- 08-08과의 관계: 원인이 아니다. 08-08 전(e1a4580) 빌드에서도 플랫폼 화면은
lazy 청크 schema-registry·server-state를 같이 preload한다. 08-08은 목록에
badge·card를 더했을 뿐이고, 목록이 비어 있지 않으면 같은 경고가 나온다.
- 간헐인 이유: 클릭이 load+3초 전에 일어나고 문서가 load+3초 뒤까지 남을
때만 경고가 나온다. 부하가 높을수록 자주 맞는다.
고른 방법
- 이 spec의 허용 목록에 WebKit 경고 문구 하나를 더한다. WebKit에서만, 빠진
두 페이지가 import하는 청크 이름만 허용한다. 이름은 고정하지 않고 각
빌드의 .vite/manifest.json에서 정적 import를 따라가 구한다(A의 플랫폼
화면, B의 UI 화면). 다른 청크의 같은 경고와 다른 브라우저는 그대로 실패한다.
버린 대안
- preload를 끄거나 줄이기(build.modulePreload): 모든 lazy 화면에서 페이지
청크를 받은 뒤 import를 다시 받는 왕복이 하나 는다. 테스트 경고 하나 때문에
세 브라우저의 화면 전환을 느리게 할 이유가 없다.
- B 배포 전에 3초 넘게 기다리기: "오래 열린 탭"에는 맞지만 WebKit 내부 상수
(3초)에 묶인 고정 대기이고, 경고를 설명하지 않고 피한다.
- strict-browser-test.ts 전역 허용: 다른 spec의 진짜 unused preload까지 덮는다.
위험·한계
- 허용 범위는 manifest에서 구한 청크 목록이다. 실제 preload 목록은 Vite가
만드는 __vite__mapDeps이고, 둘이 갈라지면 경고가 다시 실패로 나온다(덮이지
않는 쪽으로 틀린다).
- WebKit 문구가 바뀌면 다시 실패한다.
검증
- RED(ec7435c, webkit, flock, workers 1)
- 그대로 30회: 2회 실패(경고 4줄, badge·card·schema-registry·server-state),
loadavg 14.8~17.
- 시점 고정 재현(scratch spec, 원본 수정 없음): 복구의 manifest 응답을
3.5초 늦추면 3/3 실패(같은 4줄). UI 오류 뒤 3.5초 기다리면 2/2 실패
(text-field 1줄).
- GREEN
- 시점 고정 재현 두 가지를 고친 spec으로: 6/6 통과.
- 그대로 30회: workers 1에서 30/30 통과(loadavg 3.9~8.4), workers 3에서
30/30 통과(loadavg 9.0~18.0, 평균 14).
- chromium·firefox: 각 3회 통과. 시점 고정 재현도 두 엔진에서 경고 없이
통과한다(이 경고는 WebKit만 낸다).
- webkit e2e 전체(preview 빌드, 11 workers): 63/63 통과(loadavg 5.2~19.9).
- npx tsc --project tsconfig.test.json --noEmit, npx eslint (바꾼 파일) 통과.
문제
08-08은 초기 JS 바이트를 줄이는 대신 초기 파일을 16개에서 25개(entry
포함 26개)로 늘렸고, "HTTP/1.1 호스팅이면 다시 본다"를 남겼다. vite
preview도 HTTP/1.1이다. 비용을 잰 적이 없어 위험이 열려 있었다.
고른 방법
- 지금 빌드와 묶은 빌드 두 가지를 쟀다. (가) 08-08이 나눈 초기 primitive
청크 4개(field·button·select·page-templates)를 하나로. (나) 묶을 수 있는
초기 청크 14개를 하나로(entry·preload-helper·boot, 부트 실패 화면 closure,
15-01 그룹은 뺐다). 같은 커밋을 임시 복사본에서 그룹 하나만 더해 빌드했다.
- 측정: vite preview(HTTP/1.1, gzip), Chromium CDP 네트워크 에뮬레이션
(DevTools Fast 3G·Fast 4G 값), 새 context·캐시 없음, 첫 화면 =
boot 셸이 사라지고 route h1이 들어온 시각. 세 빌드를 번갈아 7번씩, 중앙값.
HTTP/2(node:http2, 자체 서명 인증서, gzip)도 같은 방법으로 쟀다.
- 결과(Fast 3G / Fast 4G 중앙값)
- 지금 26개 202,782 B: 5,887 / 1,874 ms
- (가) 23개 201,818 B: 5,426 / 1,764 ms
- (나) 13개 198,673 B: 4,930 / 1,535 ms
- HTTP/2: 지금 4,793 / 1,444, (가) 4,769 / 1,440, (나) 4,708 / 1,422 ms
- 판단: 묶지 않는다. 측정값과 판단을 performance-evidence.md에 적고,
vite.config.ts의 "재검토" 주석이 그 절을 가리키게 한다.
- (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로
고를 방법이 없었다. boot 정적 closure는 design-system 배럴을 지나 갤러리
전용 primitive까지 잡는다. rolldown `$initial` 태그는 entry가 앱을 dynamic
import로 읽어서(09-03) 아무것도 잡지 않는다. boot.tsx를 entry로 더하면
manifest 분류가 lazy 화면까지 초기로 센다(28개, 216,820 B, 예산 초과).
- 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 맞춰야 하고, 낡아도
실패하는 검사가 없다. 08-08이 같은 이유로 manualChunks 이름 고정을 버렸다.
- 템플릿은 HTTP/2 이상 서빙을 전제로 본다. HTTP/1.1로만 서빙하는 제품은
(나) 같은 그룹을 넣고 셸을 바꿀 때마다 다시 잰다고 문서에 적었다.
버린 대안
- (나)를 고정 목록으로 넣기: HTTP/1.1에서 Fast 3G 0.96초 빠르지만 숨은
결합이다(위).
- (가)만 넣기: 0.46초. 같은 이유.
위험·한계
- HTTP/1.1로 서빙하는 다운스트림은 첫 화면이 Fast 3G에서 약 1초 늦다.
이 커밋은 그 비용을 없애지 않고 숫자와 전제를 적는다. 호스팅 HTTP 버전을
검사하는 게이트는 없다(FE-GATE-019 probe 밖).
- 측정은 이 머신의 loopback과 CDP 에뮬레이션이다. 연결 수립(TCP·TLS) 비용은
CDP 지연에 들어가지 않는다. loadavg는 HTTP/1.1 측정 6~20, HTTP/2 측정
3~6이라 두 표끼리는 비교하지 않는다. 각 표 안은 번갈아 재서 비교할 수 있다.
검증
- 빌드 바이트: classify-vite-bundle + gzipSync(check:bundle과 같은 계산).
지금 빌드는 기준 202,770 B(local-build)와 맞다.
- 측정 스크립트와 로그는 커밋하지 않았다(worktree의 .tmp/ra/, 일회성).
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED.
- npx eslint vite.config.ts, npx tsc --project tsconfig.node.json --noEmit 통과.
문제: 3f9c087은 초기 청크를 묶지 않는 근거로 "템플릿은 HTTP/2 이상으로
서빙한다"를 정했다. 그런데 이 전제는 작업 기록인 performance-evidence.md
에만 있다. 호스팅을 정하는 사람이 읽는 현재 계약 문서(static-delivery.md)
에는 서빙 프로토콜 이야기가 없다.
고른 방법: static-delivery.md 끝에 한 단락을 더한다. HTTP/2 이상으로
서빙한다는 것, HTTP/1.1에서 늦어지는 정도(Fast 3G 약 1초), HTTP/2에서의
차이(100 ms 미만), HTTP/1.1만 되는 제품이 할 일을 적고 측정 기록으로
링크한다.
버린 대안: README의 배포 절에 적기. README는 배포 변수와 명령을 다루고,
호스트 동작은 static-delivery.md가 다룬다.
위험·한계: 수치는 2026-11-03 한 번의 측정이다. 셸이 바뀌면 달라진다.
검증: node scripts/verify-documentation-readiness.ts PASS_SCOPED
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다. 3261208 뒤로 프론트는
422 중 IDEMPOTENT_REQUEST_MISMATCH만 적용 안 됨으로 보고, 짝 백엔드는 필드
검증을 400 VALIDATION_FAILED로 보낸다. 같은 문서의 6.1절 표와 4.2절이 서로
다른 말을 한다.
고른 방법
- 400 행에 짝 백엔드 필드 검증이 400 VALIDATION_FAILED라는 것을 더하고
적용 여부는 6.1절을 가리킨다.
- 422 행을 짝 백엔드 기준으로 바꿨다. 기본 배포는 IDEMPOTENT_REQUEST_MISMATCH만,
fileserver는 쓰기 뒤에도 나오는 code를 422로 보낸다. 폼 필드 오류는
details.issues[]가 있으면 여전히 읽는다.
- 리뷰 README 14.6의 위험 줄을 고친 상태로 바꿨다.
버린 대안
- 422 행을 그대로 두고 6.1절만 믿기: 같은 문서 안에서 두 절이 어긋난다.
위험·한계
- 422로 필드 검증을 보내는 다른 백엔드를 쓰는 프로젝트는 422 뒤에 폼에서
다시 저장할 수 없다. 문서는 그 동작을 적을 뿐 바꾸지 않는다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.6
문제
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으로 실행한다.
문제
기능 하나가 같은 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에
넘긴다.
문제
048f490(V2 클라이언트 삭제)과 12f3bb7(V2 API 행 삭제)은 공개 이름을 깨는
변경인데 CHANGELOG 미출시 절에 행이 없고, "먼저 할 일" 절의 기능 모양 옮기기
순서가 아직 apiContract(V2 API 필드 네 개)를 만들라고 적는다. 리뷰 README
14.6의 "V2와 남은 차이"도 V2가 있는 것으로 적는다.
고른 방법
- CHANGELOG: [계약] BREAKING 행 둘(지운 이름, 옮기는 법, memento-web 영향)을
더하고, "먼저 할 일" 1·3번을 schemas 하나로 고쳤다.
- 리뷰 README 14.7: 사용자 지시, 지우기 전·후 도식, 두 커밋이 지운 것과 바꾼
것, 레지스트리 재승인 digest, 초기 JS 변화, 사라진 V2 전용 동작, 남긴
BoundedPollOperationContract, 다운스트림 영향. 14.6의 차이 절에 지금은 없다고
적었다.
위험·한계
- 다운스트림 동기화 방법은 CHANGELOG의 문장뿐이다. memento-web을 직접 옮겨
보지는 않았다.
검증
- verify:documentation PASS_SCOPED.
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기
요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을
가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD
밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤
V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키
전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을
POST에 붙여도 조립이 통과한다.
고른 방법
assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아,
쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에
x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아
거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와
같다).
버린 대안
- 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필
(MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다.
- 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자
요청 시점까지 미룬다.
위험·한계
- 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한
실패다(CHANGELOG [보안]).
- 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시
실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회).
검증
- RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie
profile requires no CSRF header" 실패(조립이 통과).
- GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는
조립된다.
- check:types, lint, check:architecture, check:registries, test:unit 2,568,
test:integration 117, test:component 245 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로
끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본
(2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response
status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는
network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과
어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝
백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로
나중에 다시 보낸다"로 정한다(http-contract.md §2).
고른 방법
- backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE.
- Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면
AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget·
MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을
다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고
키를 지킨다.
버린 대안
- V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이
응답 없는 실패 뒤 재시도를 금지한다.
- 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자
재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시
보내지 않았다.
위험·한계
- retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다.
- Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다.
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on
the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고
PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과.
- GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다.
- check:types, lint, check:architecture, test:unit 2,568, test:integration 117,
test:component 245, tests/features 99 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가
사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성
검사도 같이 사라졌다.
고른 방법
14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep
design) 8절이다.
- 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은
문장은 리뷰 대상으로 남긴다.
- KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만
되살렸다(c05f41a).
- 보안 프로필 검사: 쿠키 인증 쓰기의 CSRF 요구만 보안 불변식이라 되살렸다
(365d8c3).
CHANGELOG에 [보안] 행과 [계약] 행을 더했다.
검증
- verify:documentation PASS_SCOPED, tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
문제
2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에
나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED
재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두
브랜치를 합친 상태를 리뷰 기준으로 골랐다.
고른 방법
새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는
건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다.
- 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가
없어진 이쪽을 택했다.
- 6절: 거절 판정 위치는 backend-envelope.ts 표다.
- 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다.
위험·한계
- 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는
사용자가 정한다.
검증
- check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다.
문제
V2 HTTP 경로를 지운 뒤(048f490, 12f3bb7) 사용자가 "V2에만 있던 동작이
없어져도 되는가"를 묻고, 프론트 전체를 다시 리뷰하라고 했다. 기준은
docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md다.
고른 방법
- 두 작업 브랜치를 합친 e40684b를 기준 커밋으로 고정했다(사용자 선택).
- 지난 리뷰의 16개 영역을 그대로 나눠, 격리 worktree 에이전트가 병렬로
읽고 변이·실험을 했다. 무거운 실행은 공유 잠금으로 한 번에 하나씩
돌렸다.
- High 제안 6건과 상향 제안 1건을 코드에서 다시 확인했다. 제거 드릴
5개, feature-scaffold, lab 게이트는 직접 돌렸다.
- README에 범위(36.1), 28개 관점 판정(36.2), 최종 요약(36.5), 발견
색인을 적었다. 영역 문서의 발견 96건 중 같은 결함 8건을 대표 항목에
합쳐 색인은 88건이다.
- 버린 대안: 두 브랜치를 따로 리뷰하기. 병합 뒤 상태(문서 충돌을 푼
6.1절, 두 쪽 변경이 겹친 번들 크기)를 보지 못한다.
위험·한계
- High는 3건이다: 03-01(=08-01), 01-01, 0929/03-03(Medium에서 상향).
03-01은 이 작성자가 3261208에서 만든 판정 표가 원인이다. 14-02와
04-01도 작성자의 문장·판정이 틀렸다(README 10.5).
- V2 판정을 다시 보니 V2가 하던 일이 셋보다 많았다. 레지스트리의 wire
칸 감시(07-01), traceId 채우기(03-06), 테스트 3건(10-04), 조회
SAFE·IDEMPOTENT 제한(03-03)이 같이 사라졌다(README 3절).
- 영역이 High로 제안한 02-06·12-01·15-01은 Medium·P1로 낮췄다.
지난 라운드의 같은 모양(1101/11-01, 1101/15-01)과 등급을 맞췄다.
P1이라 첫 조치 묶음에 그대로 있다(README 2.3).
- 짝 백엔드가 리뷰 도중 7ef8d0b4에서 bbe944bd로 바뀌었다. 새 code
IDEMPOTENCY_COMPLETION_UNKNOWN 하나만 대조했다(README 10.6).
- CI 러너, 짝 백엔드 실연동, d99301b와의 lab A/B는 직접 확인하지
않았다(README 7절).
- 리뷰 중 코드는 고치지 않았다.
검증
- e40684b 게이트: check:architecture, check:types, lint, test:unit
2,580, test:component 263, test:integration 117, test:contract 23,
test:runtime-schema 56, verify:documentation, check:adapter-inventory,
check:ci, check:registries, check:i18n, check:design-system,
check:diagnostics, check:bundle(201,848 / 204,800 B) 통과.
- test:sample-removal(23 checks), test:feature-scaffold(16 checks) 통과.
- test:browser-file-storage-removal, test:realtime-removal,
test:optional-recipe-removal 실패. 세 드릴 모두 fixture에 README.md·
CHANGELOG.md가 없어 문서 테스트 2파일만 떨어진다(02-06).
- test:performance 실패: 상호작용 중앙값 227 ms > 200 ms(15-01).
- 이 문서를 넣은 뒤 verify:documentation PASS_SCOPED,
documentation-readiness·changelog-review-ids 테스트 15건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md
문제
리뷰 README 10.1절의 게이트 목록은 merge stage 전체가 아니었다.
coverage 증거 검사, storybook, a11y, browser-capabilities, CI env 값의
e2e가 빠졌다. 리뷰를 맡긴 세션이 병합의 한쪽 부모 8c39e77에서
`ci:gate FE-GATE-NNN` 14개를 돌려, 실제 러너에서 항상 실패하는 merge
게이트 두 개를 찾았다.
고른 방법
- 11-06: tests/e2e/compact-smoke.spec.ts:18이 build id를 "local-build"로
고정하고, workflow는 VITE_BUILD_ID를 gitea-<run>-<attempt>로 준다.
FE-GATE-008이 CI에서 항상 실패한다.
- 12-09: scripts/lib/ci-artifact-validator.ts:79-91의 .strict() schema가
istanbul-lib-coverage 3.2.2 summary의 branchesTrue를 거절한다.
FE-GATE-005가 테스트가 모두 통과해도 실패한다.
- 두 결함의 코드를 e40684b에서 다시 읽고, README 13절에 36.3 양식으로
적었다. 사용 결정, P1 표, 개선 순서 2, 관점 21, 색인(90건), 미검증,
오케스트레이터 실수(10.5)에 반영했다. 등급은 02-06과 같은 기준으로
Medium·P1이다.
- 셋째 결함(FE-GATE-020)은 02-06과 같아 따로 세지 않았다.
worktree 안 checkout·inotify 부족은 환경 조건이라 결함으로 세지
않았다.
위험·한계
- e40684b에서 ci:gate를 실행하지 않았다. 재현은 8c39e77 깨끗한
복제본에서 다른 세션이 했다. CI=true와 러너 이미지 조건은 아무도
재현하지 않았다.
- 코드는 고치지 않았다.
검증
- verify:documentation PASS_SCOPED.
- documentation-readiness·changelog-review-ids 테스트 15건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절
문제: verifyReleaseCandidate는 cache.match()가 던질 때만 UNKNOWN으로
본다. 본문 stream 읽기가 끊기면 readAndValidateResponse가
UNAVAILABLE(retry=true)이나 NOT_READABLE을 돌려주는데, 판정이 ABORTED
밖의 실패를 모두 REPAIRABLE로 바꾼다. 그래서 같은 I/O 오류가 조회에서는
UNAVAILABLE/RETRY, 활성화에서는 INTEGRITY_FAILED/REHYDRATE가 된다. stage
재사용 경로는 후보를 고치려고 모든 asset을 네트워크로 다시 받는다.
같은 파일의 타입 주석은 "unreadable candidate"를 UNKNOWN이라고 적는다.
고른 방법: 저장된 바이트·헤더에 대한 판정인 INTEGRITY_FAILED·
CORRUPT_DATA·POLICY_REJECTED·LIMIT_EXCEEDED만 REPAIRABLE로 두고, 나머지
(UNAVAILABLE·NOT_READABLE·ABORTED 등)는 UNKNOWN으로 둔다. 활성화와
stage 재사용은 이미 UNKNOWN을 자기 operation으로 rebase해 돌려준다.
리뷰가 적은 최소 개선 방향 그대로다. 거꾸로 "실패 code 목록을 UNKNOWN
쪽에 적는" 방식은 새 code가 생기면 손상으로 떨어지므로 버렸다.
위험·한계: stage 재사용 경로는 본문을 읽지 못하면 이제 repair 대신
실패를 돌려준다. 손상이 아닌 것을 손상으로 고치지 않는다는 STO-RR-04와
같은 방향이다. inspect()가 판정 불가를 verified:false로 합치는 것
(0929/02-02)은 그대로다. service-worker-pwa 번들 9,716 → 9,733 /
10,100 gzip B.
검증:
- RED: public-response-cache-repair.test.ts 새 테스트가 활성화
INTEGRITY_FAILED/REHYDRATE(기대 UNAVAILABLE/RETRY)로 실패.
- GREEN: 같은 파일 10건 통과. 바이트가 다르면 여전히 INTEGRITY_FAILED
인지 보는 테스트를 같이 넣었다. cache 단위 3파일 + tests/recipes
62건 통과. check:types 통과. check:optional-recipes:source PASS.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-02
문제
조립 루트는 응답이 있는 UNAUTHENTICATED면 프로필을 보지 않고
authSession.onUnauthenticated()를 불렀다. ANONYMOUS 요청은 세션을 묻지 않고
헤더 없이 나가는데도, 그 401이 로그인한 사용자를 로그아웃시키고 scope fence가
서버 상태 캐시를 모두 비웠다. 제품 credentialProviders가 자격 증명을 낸
요청의 401도 템플릿 세션을 로그아웃시켰다.
고른 방법
attachCredentials와 같은 순서로 401의 주인을 가른다(reportServerUnauthenticated).
- ANONYMOUS 프로필: 아무에게도 알리지 않는다.
- 제품 provider 프로필: 세션은 그대로 두고, ProductComposition의 선택 hook
onCredentialRejected({operationId, authProfileId})를 부른다. BFF 제품은
거기서 자기 owner에게 알린다. hook의 throw는 결과를 바꾸지 않는다.
- 나머지(템플릿 세션이 낸 자격 증명): 지금처럼 onUnauthenticated().
버린 대안: ANONYMOUS만 빼기(2줄)는 provider 경로의 과잉 로그아웃이 남는다.
owner가 401을 직접 판단하게 하면 owner 계약이 바뀌고 모든 owner가 판단
로직을 쓴다.
위험·한계
- 제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이
hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02
5절에 적었다.
- 401 도착과 계정 전환이 겹치는 경쟁은 여전히 확인하지 않았다.
검증
- RED: 새 테스트 3건(ANONYMOUS 401 demo·external, provider 401)이 수정 전
실패했다. bearer 대조군은 수정 전후 모두 통과.
- node scripts/run-vitest.ts run runtime-adapters-{auth-profile,credential-order},
runtime-adapters, product-composition-fixture, reference-runtime-composition
→ 5 files / 62 tests 통과. check:types 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-01
문제
validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는
Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty·
__proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다.
그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다.
고른 방법
같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼
Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은
타입 선언과 다른 표의 관용이 갈려 버렸다.
위험·한계
짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다.
검증
- RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과.
- form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03
문제: inspect()는 active pointer 읽기가 실패하면 그 실패를 그대로
돌려준다. 손상 pointer(CORRUPT_DATA)는 조회·cleanup을 막고 다음
activation이 rollback 없이 덮어쓰는 상태인데, 그 상태를 진단할 유일한
관리 API도 같이 멈춘다. 운영자는 어떤 후보가 남았는지, 다음 activation이
무엇을 덮어쓰고 그 뒤 cleanup이 무엇을 지울지 모른 채 배포한다.
PublicCacheInspection에는 pointer 상태를 담을 칸이 없다.
고른 방법: PublicCacheInspection에 activePointer("NONE" | "READABLE" |
"UNREADABLE")를 둔다. pointer 읽기가 CORRUPT_DATA면 UNREADABLE로 적고
activeReleaseRegistryId는 null로 둔 채 후보 목록을 끝까지 채운다. 일시
오류(UNAVAILABLE 등)는 지금처럼 실패로 돌려준다. activation이 이미 쓰는
"CORRUPT_DATA만 손상으로 본다" 규칙과 같다. recipe fake도 같은 칸을
채운다. 리뷰가 함께 적은 inspect 전용 operation 이름은 공유 operation
union을 바꾸는 일이라 이번에 하지 않았다.
위험·한계: 공개 포트 타입에 필수 칸이 하나 는다. 결과를 읽는 쪽은
그대로지만 이 포트를 직접 구현한 쪽은 칸을 채워야 한다([계약]).
repo 안 소비자는 없다. inspect의 signal·판정 불가(0929/02-02)는
그대로다. service-worker-pwa 번들 9,733 → 9,758 / 10,100 gzip B.
검증:
- RED: public-response-cache-repair.test.ts 새 테스트가 activePointer
없음으로 실패.
- GREEN: 같은 파일 11건 통과(손상 중 inspect ok, UNREADABLE, 후보
r1·r2 verified, 일시 오류는 UNAVAILABLE). cache 단위 3파일 +
tests/recipes 63건 통과. check:types, 바꾼 파일 eslint,
check:optional-recipes:source PASS, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-05
문제: vault inspect()는 이전 receipt를 무효화한 뒤 파일을 읽으며 두 번
await한다. 그 뒤 #disposed는 다시 보지만 ref가 아직 있는지는 보지 않고
receipt를 발급한다. 그 사이 release(ref)가 record와 receipt를 지우면,
inspect는 사라진 ref에 ok와 receipt를 돌려주고 receipt 기록이 놓은 File을
runtime dispose까지 붙잡는다(activeReferenceCount 0,
activeVerificationCount 1). 지금은 resolveVerifiedFile의 records.has 검사가
preview를 막지만, 그 검사를 지운 변이(L11)를 잡는 테스트가 없었다.
고른 방법: #disposed 재확인 바로 뒤에서 record가 없으면
NOT_FOUND/RESELECT로 끝낸다. resolveFile이 ref를 못 찾을 때와 같은
결과라 호출자가 이미 처리하는 분기다. 리뷰의 최소 개선 방향 그대로다.
위험·한계: 같은 ref에 inspect 두 개가 겹치면 receipt가 둘 생기는 것은
이 변경 범위 밖이다(두 receipt 모두 release·dispose가 지운다). 이 수정
뒤에는 놓은 ref에 receipt가 남는 경로가 없어서, L11 검사는 다시 두 번째
방어선이 된다. 새 테스트는 이 커밋의 검사를 지우면 실패한다.
file-transfer 번들 56,053 → 56,068 / 57,800 gzip B.
검증:
- RED: browser-file-content.test.ts 새 테스트가 inspect ok(기대
NOT_FOUND)로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 85건 통과.
check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-04
문제
tests/visual/fonts.conf는 Noto Sans·Noto Sans CJK·Liberation Mono가
있는 OS 글꼴 디렉터리만 읽는다. 생성 workflow의 브라우저 설치 단계는
`playwright install --with-deps` 한 줄이고, Playwright 의존 패키지에는
이 글꼴이 없다. 그래서 빈 러너에서는 FE-GATE-008이 코드와 무관하게
`visual-fonts` 단계에서 실패한다(1101/11-02의 남은 절반).
고른 방법
- 생성기(scripts/generate-ci-workflow.ts)의 browser-install 단계가
`--with-deps` 뒤에 글꼴 패키지 4개를 apt-get으로 설치한다.
`--with-deps`가 이미 패키지 목록을 갱신했으므로 update를 다시 하지
않는다. root가 아닌 러너에서만 sudo를 붙인다.
- 패키지 목록을 scripts/lib/visual-test-fonts.ts 한 곳에 두고 생성기와
tests/visual/fonts.setup.ts의 설치 안내가 같이 읽는다.
- 글꼴이 필요한 것은 FE-GATE-008뿐이지만 브라우저 단계 두 곳 모두에
넣었다. 게이트 ID로 갈라 쓰면 생성기가 게이트 목록에 묶인다.
- 버린 대안: job container 고정(러너의 컨테이너 지원 미확인),
ci:gate가 패키지 설치(개발자 PC에서도 sudo 요구).
위험·한계
- 실제 러너나 깨끗한 Ubuntu 24.04 컨테이너에서 이 단계를 돌리지
않았다. 패키지 이름과 디렉터리는 이 호스트(Ubuntu)와 fonts.conf로만
확인했다.
- CJK 패키지 때문에 브라우저 job 설치 시간이 수십 MB만큼 는다.
- gates.json은 바꾸지 않았다(단계 종류는 그대로 browser-install).
검증
- ci-workflow-generation 새 테스트: 생성기 수정 전 실패, 수정 뒤 통과.
파일 전체 424건 통과(스냅샷 1건 갱신).
- generate:ci-workflow로 workflow 재생성. check:ci PASS.
- lint, check:types:node, check:types:test, verify:documentation PASS.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-02
문제
같은 모양 검사가 파라미터 이름만 지운 문자열로 비교했다. React Router는
대소문자를 무시하고 끝 슬래시를 같은 경로로 본다. 그래서 /shop/items/:itemId와
/shop/Items/:id, /shop/items와 /shop/items/가 조립을 통과했고 라우터는 그중
하나만 그렸다. 메뉴·레지스트리에는 둘 다 나왔다.
고른 방법
모양 키를 만들 때 소문자로 바꾸고 끝 슬래시를 지운다. 라우트 경로 문법을
소문자·끝 슬래시 없음으로 제한하는 검사는 기존 라우트에 새 규칙을 거는
것이라 버렸다.
위험·한계
라우터가 caseSensitive를 켜면 이 검사가 과하게 거절한다. src에 caseSensitive
사용은 없다.
검증
- RED: context-route-roots.test.ts의 새 두 행이 수정 전 실패.
- tests/architecture, router, context-layouts → 9 files / 64 tests 통과.
/a/new와 /a/:id 허용 행은 그대로 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-04
문제
src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데,
같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도
쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를
찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고
말하는 채로 조용히 설치됐다.
고른 방법
- 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경).
런타임 상태 NOT_INSTALLED는 그대로 둔다.
- 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고
실패한다.
- 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는
폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로
실패해 새 이름을 알려 준다.
README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다.
위험·한계
다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다.
파일 이름만 바꾸면 된다.
검증
- RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이
수정 전 실패.
- generate-product-feature-index.test.ts 17건 통과. generate:feature-index
통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과.
BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상
인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09
문제
V2에서 옮긴 두 조립 검사가 한 사례씩만 테스트된다. 쿠키 쓰기 CSRF
검사는 POST와 x-xsrf-token 한 쌍만 본다. 그래서 `!isRead`를
`method === "POST"`로 좁히거나, CSRF 헤더 이름 대신 "필수 헤더가 하나라도
있으면"으로 바꾸거나, x-csrf-token 허용을 지워도 테스트가 통과한다.
realtime snapshot 바인딩(GET + SAFE·IDEMPOTENT)은 거절 사례가 없어
method 조건이나 retrySemantics 조건을 지워도 통과한다.
고른 방법
- rest-profile-contract: POST·PUT·PATCH·DELETE마다 CSRF 없는 쿠키 프로필과
x-tenant-context만 요구하는 쿠키 프로필을 거절하고, x-csrf-token과
x-xsrf-token을 각각 받는지 본다. GET·HEAD 쿠키 읽기는 CSRF 없이 된다.
- realtime-stream-registry: 6 method × 4 retrySemantics 표를 CURSOR와
SNAPSHOT_ONLY 두 복구 모드로 돈다. 받는 조합은 GET×SAFE, GET×IDEMPOTENT
뿐이다. 행은 조립한 descriptor를 projectApiOperationRows로 뽑은 것에서
method와 retrySemantics만 바꾼다. 투영 칸 이름이 바뀌어도 이 표가 같이
깨진다. FE-REG-API 행이 없는 id도 거절한다.
버린 대안
- 손으로 쓴 행(fixture.ts)을 그대로 쓰기: 투영과 realtime 검사가 따로
바뀌는 것을 못 잡는다.
위험·한계
- 검사 코드는 바꾸지 않았다. 테스트만 더했다.
- resumable upload 제어 요청의 쿠키 POST는 descriptor 밖이라 이 검사
범위가 아니다(영역 01).
검증
- 변이 7종을 하나씩 넣고 두 테스트 파일을 돌렸다. 모두 실패한다:
M2(POST만), M3(아무 필수 헤더), H19(x-csrf-token 허용 삭제),
M9(method 조건 삭제), M9b(method·retry 조건 삭제), S2(retry 조건 삭제),
H21-PUT(GET 또는 PUT 허용).
- 변이 없이 두 파일 47건 통과. check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-02
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-03, 10-04
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-03
문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.
고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).
위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.
검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
문제: 2026-11-03 리뷰 변이 중 아래 5개가 관련 unit 파일을 모두
통과했다. 규칙을 고치는 사람은 테스트가 통과해도 손상·로그아웃 보호가
남았는지 알 수 없다.
- L6 cleanupOwned()가 읽을 수 없는 pointer를 "pointer 없음"으로 보고
지금 서비스 중인 release까지 지운다.
- L7 stage가 손상된 marker를 고치지 않고 실패한다. REHYDRATE 안내가
기대는 회복 경로다.
- L4 preview가 파일 resolve 뒤 #disposed를 다시 보지 않는다.
- L5 vault resolveFile이 load 뒤 #disposed를 다시 보지 않는다.
- L1 vault dispose()가 File 참조 Map을 비우지 않는다.
L4·L5는 lease registry가 dispose 뒤에도 lease를 내주기 때문에 소비자
쪽 검사가 유일한 방어선이다.
고른 방법: 규칙마다 실패하는 테스트 하나를 더한다. 리뷰가 L5에
제안한 readRange()는 slice 읽기 뒤에 #disposed를 한 번 더 보므로 L5를
잡지 못한다. 그래서 resolve 직후 소스를 돌려주는 openSource()로
고정했다.
위험·한계: 테스트만 바꾼다. 동작 변경 없음.
검증: 5개 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes,
cache 단위 3파일 + tests/recipes를 돌렸다. L1·L4·L5·L6·L7 모두 새
테스트 하나씩이 실패했고(되돌린 뒤 통과), 원래 코드에서 두 파일 34건
통과. check:types:test, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-03
문제: 문서와 주석이 적은 규칙 세 개를 바꿔도 영역 단위 테스트가 모두
통과한다. 리뷰 변이 N2(part 단계가 503의 Retry-After를 읽지 않음),
N10(abort 재시도마다 ABORT 멱등 키를 바꿈, 세 라운드째 생존),
N17(control plane이 헤더 없는 429를 retryable:true로 냄)이 살아남았다.
고친 방법: 규칙마다 실패하는 테스트를 더한다.
- part 단계 Retry-After 묶음에 503을 더한다. 실제 presigned provider·
vault·실행기로 발급과 PUT 두 단계를 본다.
- abort가 한 호출 안에서 재시도하고 다음 abort() 호출에서 다시 보낼 때
세 요청의 idempotencyKey가 모두 같은지 본다. 같은 파일의
createSession·part·complete 키 테스트와 같은 방식이다.
- fetch transport가 헤더 없는 429와 상한 밖 429를 retryable:false,
retryAfterMs 없음으로 내는지 본다.
위험·한계: 테스트만 더했다. 동작은 바뀌지 않는다.
검증:
- 영역 단위 테스트(resumable-upload, presigned-transfer, image-cdn,
upload-cancellation) 15파일 272건 통과
- 변이를 하나씩 넣고 돌렸다: N2 4건 실패, N10 1건 실패, N17 2건 실패.
변이는 원본으로 되돌렸다
- check:types, eslint(바꾼 두 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-03
문제
GET에 `retrySemantics: "KEYED"`(commandRecovery 없음)나 `"NEVER"`를
적어도 계약 조립이 통과하고 FE-REG-API 행에 그 값이 남는다. KEYED 복구
descriptor 검사가 쓰기 분기 안에만 있기 때문이다. 실행기는 이 GET을
쓰기로 보지 않아 재시도 없는 읽기로 돌린다. 매뉴얼은 "읽기(GET)는 늘
SAFE"라 적는다. V2 `defineRestOperation`은 조회에 SAFE·IDEMPOTENT만
허용했는데 V2 삭제 때 이 규칙이 V3로 옮겨지지 않았다(실험 R1).
고른 방법
assertHttpContract의 읽기 분기에서 GET·HEAD의 retrySemantics가 SAFE나
IDEMPOTENT가 아니면 method와 값을 담아 거절한다. realtime snapshot 바인딩이
요구하는 짝(GET + SAFE·IDEMPOTENT)과 같은 어휘다. 매뉴얼 02 3절 "틀리면"에
거절 문구를 더했다.
버린 대안
- 레지스트리 governance의 allowedValues로 막기: method별 허용값을 표현할
칸이 없고, 조립(부팅 경로)이 아니라 check:registries에서만 걸린다.
위험·한계
- GET·HEAD를 KEYED나 NEVER로 적은 다운스트림 descriptor는 부팅에서 계약
조립 실패가 된다. 템플릿 안에는 그런 descriptor가 없다(grep).
- 쓰기의 SAFE 금지(03-03)는 이 커밋 범위가 아니다.
검증
- RED: tests/unit/external-contract-runtime.test.ts의 GET·HEAD × KEYED·NEVER
4건이 실패(조립 통과)했다.
- GREEN: `run-vitest related src/contracts/external-contract-runtime.ts`
105파일 950건 통과. check:types, eslint, check:registries,
verify:documentation 통과.
BREAKING CHANGE: GET·HEAD operation의 retrySemantics가 KEYED나 NEVER이면
계약 조립이 CONTRACT_CONTRIBUTION_INVALID로 실패한다. SAFE(재시도 허용)나
IDEMPOTENT로 바꾼다. 재시도를 막으려면 frontend.retryBudget을 0으로 둔다.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2,
protocol, semantics, replayPolicy, retry, transportMaxAttempts,
authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다.
assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와
대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET
descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다.
poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P).
고른 방법
- coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다.
실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다
(http-execution-v3.ts retryCeiling). 그래서 생성 때
retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청
한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다.
- 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT,
retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는
maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다.
- V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립
(composeContractContributions)이 GET·HEAD에서 이미 거절한다.
- 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는
retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은
객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기
옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가
재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이
없다.
위험·한계
- 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다.
- 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에
넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고
적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다.
- 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용
operation을 따로 등록해야 한다.
검증
- 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과.
- 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError,
retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서
poll 3회 = 요청 3회.
- 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사
삭제) 모두 검출.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: BoundedPollOperationContract를 지운다.
createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의
둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다.
조립된 행(composeContractContributions(...).httpByOperationId.get(id))을
넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다.
execute 안에서는 같은 descriptor를 실행기에 넘긴다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01
문제: part 단계(BFF 발급, object store PUT)가 상한(maxRetryAfterMs, 기본
30초)보다 긴 Retry-After로 429·503을 받으면 runtime은 기다리지 않고
멈춘다. 그런데 앱에 주는 실패는 retryable:true다. 포트 표대로면 "자동
재시도해도 된다"는 뜻이라, 서버가 45초 기다리라고 한 요청을 앱이 바로
다시 보낸다. 같은 429에 control plane 전송은 retryable:false를 준다.
control plane도 전송 상한이 정책 상한보다 크면 retryable:true가 된다.
고친 방법: provider 실패를 앱 실패로 바꾸는 한 곳(stripProviderFailure)이
정책 상한을 받아, 지우는 retryAfterMs가 상한을 넘었으면 retryable을
false로 만든다. control plane 전송이 이미 쓰는 규칙이다. 한 곳에서 하므로
두 단계와 두 factory 상한 조합이 모두 같은 답을 낸다. 포트 주석과 설계
문서(presigned-transfer-and-image-cdn.md 7절)에 같은 규칙을 적었다.
버린 대안: 현상 유지 + 포트 주의 한 줄은 앱이 기다릴 값을 모르므로 지킬
수 없다. 앱 실패에 retryAfterMs를 싣는 안은 공유 타입 BrowserDataFailure를
바꿔 다른 포트까지 퍼진다. 상한 밖 값도 기다리는 안은 한 호출이 끝없이
늘어지지 않는다는 상한의 목적을 깬다(리뷰 5절 D2).
위험·한계: upload()·abort()의 실패 값이 바뀐다. 상한 밖 Retry-After는
RESUME에 retryable:false가 되어, 자동 재시도하던 다운스트림은 사람이
누르는 재시도로 넘어간다. 상한 안 대기, PUT 403 재발급, 발급 401/403
NONE은 바뀌지 않는다(기존 테스트 그대로 통과). 헤더 없는 part 단계 429가
backoff로 재시도하는 차이는 이 변경 범위 밖이다.
검증:
- 고치기 전: 새 단언 5건 실패(part 단계 4건, 전송 상한 60초 조합 1건)
- 고친 뒤: 영역 단위 테스트 15파일 274건 통과
- check:types, eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-02
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.
고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.
위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.
검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
문제
FE-GATE-005의 증거 검사(scripts/lib/ci-artifact-validator.ts)는
coverage-summary.json 항목마다 lines·statements·functions·branches만
허용하는 .strict() schema를 쓴다. istanbul-lib-coverage 3.2.2는 빈
summary에 branchesTrue를 항상 넣으므로 total에 그 키가 있다. 그래서
테스트가 모두 통과해도 증거 단계에서 게이트가 실패한다. 같은 파일을
읽는 risk-coverage 게이트는 이 키를 허용해 두 검사기가 갈라져 있었다.
고른 방법
- 키 목록을 scripts/lib/coverage-summary-metrics.ts 한 곳에 두고 두
검사기가 같이 쓴다. 평가하는 네 지표와, 보고기가 더할 수 있는 선택
지표(branchesTrue)를 나눴다. 선택 지표도 counter 형식(pct 정확성
포함)은 그대로 검사한다.
- 버린 대안: validator schema에만 branchesTrue를 더하기. 지금 고장의
원인(두 목록)이 그대로 남는다. 상수를 risk-coverage.ts에서
export하기. validator가 @babel/eslint-parser까지 읽게 된다.
위험·한계
- 다른 미지의 키는 여전히 거절한다(의도). 보고기를 올리면 새 키가 생길
수 있다.
- ci:gate FE-GATE-005 전체는 이 커밋에서 돌리지 않았다.
검증
- RED: 새 tests/unit/coverage-summary-artifact.test.ts 3건 중 2건 실패
(Unrecognized key: "branchesTrue").
- 수정 뒤 coverage-summary-artifact·risk-coverage·risk-coverage-files
44건 통과. check:types 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 12-09
문제: 초기 JS가 예산을 넘으면 check:bundle은
"Bundle budget or manifest integrity failed: " 한 줄만 쓰고 콜론 뒤가
비어 있었다. 측정값과 한도는 artifacts/performance/bundle.json에만 있어
예산 실패인지 manifest 무결성 실패인지, 몇 바이트 넘었는지 알 수 없었다.
또 초기 JS 파일 수에는 상한이 없어 08-08처럼 파일을 16개에서 25개로
늘리는 변경도 모든 게이트를 통과했다. 템플릿은 HTTP/2를 전제로 초기
청크를 나눠 두었는데, 파일 수를 늘리는 결정이 어디에도 드러나지 않았다.
고른 방법: 예산 실패와 무결성 실패를 다른 문장으로 쓴다. 예산 실패는
넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다
(describeBundleBudgetFailures). config/performance/budgets.json에
initialJsFiles(지금 25)를 두고 check:bundle이 entry를 포함한 초기 파일
수를 센다. bundle.json 스키마는 측정값·한도·결과와 자가 검사 fixture를
하나씩 더 가진다. 두 변경은 같은 함수와 스키마를 고치므로 한 커밋에
넣었다.
버린 대안: 파일 수를 문서에만 적기. 08-08이 그 상태에서 파일을 늘렸다.
위험·한계: 초기 파일을 하나라도 늘리는 변경은 이제 budgets.json을 같이
고쳐야 통과한다. 그것이 목적이다. HTTP/2 확인 자체는 이 커밋에 없다
(13-02에서 probe에 넣는다).
검증: tests/unit/check-bundle-output.test.ts가 손으로 만든 빌드 출력에
check-bundle.ts를 돌려 통과·초기 바이트 초과·lazy 초과·파일 수 초과·
무결성 실패의 출력을 본다(고치기 전 4건 실패). bundle-artifact-contract,
performance-budgets 통과. 실제 빌드에서 check:bundle PASS(25 / 25 files).
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-03, 15-05
문제
조립 루트 주석과 생성 뼈대 주석은 "기능은 needs에 적은 capability만 받는다"고
했지만, invokeContribution은 context 전체를 넘겼다. needs: ["telemetry"] 기여가
["telemetry","http"]를 받았다(E6). 제품 capability도 모든 기능에 갔다. 타입이
막고 있어 cast가 있어야 생기지만, 그러면 needs가 실제 의존을 다 말하지 않는다.
고른 방법
invokeContribution이 needs의 키만 골라 새 frozen 객체로 넘긴다. 주석을 "타입만
그렇다"로 고치는 대안은 생성 뼈대 주석(scripts/create-feature.ts)까지 모든
기능에 퍼진 설명을 바꿔야 해서 버렸다. 이제 두 주석이 실행과 맞는다.
위험·한계
needs에 적지 않은 capability를 cast로 쓰던 다운스트림 기능은 그 값이
undefined가 된다. repo 안에는 그런 기능이 없다.
검증
- RED: feature-adapter-composition.test.ts에 E6 행(받은 키가 ["telemetry"])을
더했고 수정 전 실패.
- tests/contract/reusable-capability, tests/features, runtime-adapters 계열,
product-composition-fixture → 27 files / 178 tests 통과.
- check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-08
문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).
고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).
위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
(before/after 테스트 그대로 통과).
검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
문제: useSessionAction이 recover()의 결과를 버린다. owner가
"no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와
셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가
지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면
코드를 읽고 추론해야 했다.
고른 방법: 두 가지를 함께 한다.
- SessionState·SessionGateway.recover·ExternalSessionOwner에 전이
계약을 적는다. restored면 authenticated, no-session이면
unauthenticated(또는 integration-failed), reject면 상태 유지.
- SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데
owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에
unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을
보인다.
버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만
보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독
알림을 새로 만들어야 해서 scope fence와 얽힌다.
위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다.
application·scope fence는 owner의 상태를 그대로 본다.
검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패
확인), router·app-shell·route-status-surfaces·auth-session-adapter
테스트 통과, check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11
문제
tests/e2e/compact-smoke.spec.ts가 html의 data-build-id를 "local-build"로
고정해 비교한다. workflow는 전체 env에 VITE_BUILD_ID=gitea-<run>-<attempt>를
넣고, preview 서버가 그 env로 빌드한다. 그래서 실제 CI에서 FE-GATE-008이
코드와 무관하게 항상 실패한다.
고른 방법
- 기대값을 이 프로세스의 VITE_BUILD_ID에서 읽고, 비었으면 "local-build"를
쓴다. playwright webServer가 같은 env로 빌드하고,
scripts/generate-runtime-config.ts가 같은 규칙(값 || "local-build")으로
BUILD_ID를 정한다.
- 버린 대안: build id가 비어 있지 않은지만 보기. 빌드에 준 값이 화면까지
오는지(release manifest·runtime config 일치)를 더는 확인하지 못한다.
vite loadEnv로 .env 파일까지 읽기. build id는 .env가 아니라 프로세스
env에서만 온다(generate-runtime-config.ts, generate-build-manifest.ts).
위험·한계
- CI=true와 러너 이미지 조건, ci:gate FE-GATE-008 전체는 돌리지 않았다.
검증
- RED: VITE_BUILD_ID=gitea-1-1로 chromium-compact 1건 실패
(data-build-id "local-build" 기대).
- 수정 뒤 VITE_BUILD_ID=gitea-1-1, 기본값 두 경우 모두 1 passed.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 11-06
문제: build id는 부트 실패 화면이 보여 주므로 render-boot-failure 청크에
들어간다. react-dom과 scheduler(약 56 KB gzip)가 같은 청크에 있어서
build id만 다른 두 빌드에서 boot·index·render-boot-failure 세 파일의
이름이 바뀌었다. 합계 99,785 B로 초기 JS의 49.4%다. 해시 자산은 1년
immutable로 캐시되는데, 재방문 사용자는 코드가 같아도 release마다 이만큼
다시 받았다. 1101 O1이 같은 것을 재고 채택을 권했지만 결정 기록이 없었다.
고른 방법: codeSplitting.groups에 react-dom·scheduler 그룹을 더한다
(includeDependenciesRecursively: false라 라이브러리 모듈만 묶는다).
같은 비교에서 바뀐 초기 JS가 44,297 B(22.0%)로 준다. 초기 JS는
201,857 → 201,552 B, 초기 파일 수는 25개 그대로다(react-dom 진입
모듈 1.3 KB 청크가 합쳐졌다).
버린 대안: build id를 JS에 넣지 않고 release-manifest.json에서만 읽기.
boot까지 바뀌지 않아 더 줄지만, 부트 실패 화면이 build id를 보여 주는
계약을 바꿔야 한다.
위험·한계: boot(39 KB)는 build id로 설정을 대조하므로 계속 바뀐다.
그룹 정규식은 pnpm의 node_modules 배치를 가정한다. 배치가 바뀌어 그룹이
비면 새 테스트가 실패한다.
검증: tests/unit/build-environment-bundle.test.ts가 build id만 다른 두
빌드에서 react-dom이 든 청크의 이름이 같고 그 청크가
render-boot-failure가 아님을 본다(고치기 전 실패). 부트 실패 화면
e2e(tests/e2e/boot-module-failure.spec.ts, chromium) 통과.
feature-shape-growth·design-system-initial-chunk·bundle-classification
통과. 두 빌드 비교는 docs/operations/performance-evidence.md에 기록했다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-06
문제
test:sample-removal -- --feature=<id>는 참조 기능이 아닌 기능에
ciScripts: []를 쓴다. pruneRemovalFixtureCiContract가 그 빈 집합으로
기준선 사유를 "removal fixture pruned "(끝 공백)로 만들고, 바로 뒤
기준선 검사가 "leading/trailing whitespace is forbidden"으로 거부한다.
그래서 create:feature로 만든 모든 기능의 제거 드릴이 3초 만에 무관한
오류로 끝나고 게이트 검사는 하나도 돌지 않는다.
고른 방법
- 지운 스크립트가 없으면 사유를 "removal fixture pruned no CI scripts"로
쓴다.
- 이 길을 merge 게이트가 돌게 하는 것(test:feature-scaffold가 생성
기능에 --feature 드릴을 한 번 돌림)은 같은 발견의 둘째 절반이라
드릴 범위를 고치는 다음 커밋에서 한다.
위험·한계
- 이 커밋만으로는 제품 기능 제거 드릴 전체를 실행해 보지 않았다.
검증
- RED: 새 테스트 "re-baselines a removal that prunes no CI script" 실패
(reason 'removal fixture pruned ').
- 수정 뒤 tests/unit/removal-fixture.test.ts 9건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
문제
Envelope 실패 판정 표(backend-envelope.ts)와 실행기의 실패 Envelope
처리는 커버리지가 100%인데 경계 다섯 곳이 테스트에 걸리지 않는다. 표의
code를 다른 status로 보내는 행, 표 밖 422, 게이트웨이 408·425, 응답
한도보다 크고 64 KiB보다 작은 실패 본문, JSON이 아닌 실패 본문이 없다.
그래서 변이 H14(=M6, status 대조 제거)·H45(표 밖 422를 분류기로)·H15
(408·425 제거)·H23(실패 한도를 64 KiB 고정)·H10b(실패 media type 검사
제거)가 살아남았다. 처리 중 409를 자동 재전송하게 바꾼 변이 M7도
살아남았다. Envelope 표 테스트는 재시도 예산이 0이라 재전송을 볼 수
없었다. 같은 문서의 이월 항목 둘도 그대로다. 결과 불명 동안 입력
identity를 잡는 네 줄(M1, 0929/03-06)과 반사 correlation 문법 검사(M3,
1101/03-06)를 지워도 테스트가 통과한다.
고른 방법
- tests/unit/backend-envelope.test.ts: envelopeFailureEffect·
idempotencyRefusalReason·envelopeFailureReading을 status × code 표로
직접 부른다.
- envelope 통합 테스트: LENIENT 묶음에 422 INTEGRITY_MISMATCH 한 행,
한도를 넘는 실패 Envelope와 text/plain 실패 본문(네이티브 Response),
retryBudget 1인 KEYED가 409 IDEMPOTENT_IN_FLIGHT에 한 번만 보내는 행.
- 결과 불명 입력이 두 칸짜리 identity 레지스트리에서 밀려나지 않는지,
문법 밖 반사 id가 보낸 id로 바뀌는지를 각각 한 건씩 더한다.
위험·한계
테스트만 더했다. 동작은 바꾸지 않았다.
검증
- 변이 8종(H14·H45·H15·H23·H10b·M7·M1·M3)을 하나씩 넣고 관련 테스트를
돌렸다. 모두 새 테스트에서 실패하고, 되돌리면 통과한다.
- check:types, lint 통과. 바뀐 4파일 83건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-02
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-08
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.
고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).
위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
둬야 한다(리뷰 재검토 조건).
검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
6파일 76건 통과.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
문제
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절
문제
scripts/scale/run-scale-profile.ts는 단계 출력을
artifacts/scale/<tier>/<step>.log에 쓴다. 이 로그와
verify:extreme-scale·phase5 로그 63개가 git에 추적되고, .gitignore는
artifacts의 json·xml·txt·sarif만 무시한다. 그래서 merge 게이트
check:scale:pr(FE-GATE-005)를 로컬에서 한 번 돌리면 추적 로그 3개가
바뀌고 새 로그 1개가 생겨 작업 트리가 더러워진다. 커밋된 판은 다른
기계의 경로와 ANSI 색 코드를 담고, 읽는 코드·테스트·설정은 없다.
고른 방법
- .gitignore에 artifacts/**/*.log를 넣고 63개 추적을 끊는다. scale
로그(12-08) 35개만이 아니라 같은 원인의 extreme-scale·phase5 로그도
같이 뺀다(0929/11-09 남은 항목).
- 기준 측정은 이미 config/scale/benchmark-baseline.json 같은 정해진
JSON이 맡는다. 로그를 증거로 쓰는 곳은 없다(git grep).
위험·한계
- 동기화 때 다운스트림에서 이 파일들이 지워진다. 두 다운스트림은 이미
지웠다(지난 리뷰 기록).
검증
- check:scale:pr PASSED 뒤 git status에 로그 변경이 없다.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-08
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 0929/11-09
문제: react-router 7.18.1의 exports는 모든 조건에서
dist/development/*를 가리킨다. 그 파일은 ENABLE_DEV_WARNINGS = true라
운영 번들의 초기 청크에 라우터 개발 경고 문구("You rendered descendant
…")가 들어 있었다. 운영 콘솔에 개발 경고가 뜨고, 초기 JS가 약 600 B 크다.
고른 방법: vite build일 때만 react-router-dom이 import하는 두 진입점
(react-router, react-router/dom)을 같은 패키지의 dist/production 파일로
alias한다. 경로는 react-router-dom에서 react-router를 resolve한 개발
진입점 옆에서 찾고, 파일이 없으면 빌드를 멈춘다. 개발 서버와 테스트는
개발 빌드를 그대로 써서 경고를 받는다.
버린 대안: 고정 경로 alias(리뷰 실험). 업그레이드로 배치가 바뀌면
조용히 깨진다. react-router에 production 조건을 요청하기는 시점을 정할
수 없어 이 alias를 지울 조건으로만 적었다.
위험·한계: exports 밖 경로를 쓴다. 업그레이드 때 배치가 바뀌면 빌드가
실패한다(조용히 개발 빌드로 돌아가지 않는다). Firefox·WebKit e2e는
돌리지 않았다.
검증: tests/unit/build-environment-bundle.test.ts가 빌드한 JS에 개발
경고 문구가 없음을 본다(고치기 전 chunk-KS7C4IRE 1개에서 실패).
같은 빌드(local-build) 초기 JS 201,552 → 200,939 B(−613 B), 파일 25개.
라우터를 쓰는 e2e 5개 spec 14건(app-shell, reference-route,
reference-save, scroll-restoration, platform-overview, chromium) 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-07
문제
설계 정본 8.3은 SAFE를 "GET/HEAD; 보낸 뒤 network 실패에도 재시도 허용"
으로 정한다. 실행기는 그 규칙대로 SAFE면 보낸 뒤 응답을 잃어도 다시
보낸다(http-retry-lifecycle.ts canRetryTransport). 그런데 조립 검사는
쓰기가 SAFE인지 보지 않는다. 생성된 뼈대 descriptor가 GET·SAFE·
retryBudget 2이고, 매뉴얼은 쓰기를 더할 때 이 파일을 고쳐 쓰라고 한다.
retrySemantics를 바꾸지 않으면 POST가 조립을 통과하고, 응답을 잃은 생성
요청이 최대 두 번 더 나간다(리뷰 실험 X-E: fetch 2회, 결과 SUCCESS).
V2에도 이 규칙은 없었다.
고른 방법
assertHttpContract의 쓰기 가지(GET·HEAD 밖)에서 retrySemantics가 SAFE면
operation·method와 고를 값(IDEMPOTENT·KEYED·NEVER), 매뉴얼 절을 담아
거절한다. 매뉴얼 02 3절 "틀리면"에 같은 문장을 더했다.
버린 대안
실행기에서 쓰기의 SAFE를 NEVER처럼 다루기: 잘못 적은 계약이 조용히
다른 뜻으로 돈다. 조립 때 알리는 쪽이 고칠 곳을 바로 보여 준다.
위험·한계
쓰기를 SAFE로 적은 다운스트림은 부팅에서 실패한다. 의도한 실패다.
실행기를 조립 없이 직접 부르는 테스트 경로는 이 검사를 거치지 않는다.
검증
- RED: tests/unit/external-contract-runtime.test.ts의 POST·PUT·PATCH·DELETE
× SAFE 4건 실패(조립 통과).
- GREEN: 같은 파일 23건 통과. GET·SAFE와 PUT·IDEMPOTENT는 그대로 조립된다.
- tests/unit·integration·contract·features·runtime-schema 214파일 2,904건
통과. check:types:app·test, eslint, verify:documentation 통과.
BREAKING CHANGE: POST·PUT·PATCH·DELETE operation에 retrySemantics "SAFE"를
쓰면 composeContractContributions가 거절한다. 서버 보장에 맞춰 IDEMPOTENT,
KEYED(commandRecovery 필요) 또는 NEVER(retryBudget 0)로 바꾼다.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-03
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.
고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
결과는 surface hashedAsset.<ext>, header content-type이다.
verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
(c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
— 검출이 없다(리뷰 5.2).
위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.
검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
문제
SW runbook(browser-file-storage-recovery.md 8절)은
"verify:hosting-headers는 파일이 있는지만 보고 이 헤더는 보지 않는다"고
적는다. 지금은 워커를 싣는 빌드에서 serviceWorker surface가 필수이고
Cache-Control이 no-cache가 아니면 FAIL이다(cache-policy.json
serviceWorker, verify-hosting-headers.ts). release-cache-rollback.md는
맞게 적어 두 운영 문서가 반대로 말한다.
고른 방법
- 그 문장을 live 모드가 /service-worker.js의 no-cache를 확인한다로
고친다. fixture 모드가 UNVERIFIED라는 것과, 하위 경로 base는 probe가
아직 받지 않아 손으로 확인해야 한다는 것을 함께 적는다.
위험·한계
- 하위 경로 문장은 0929/13-06이 고쳐지면 지워야 한다.
검증
- 문서와 코드(cache-policy.json, verify-hosting-headers.ts,
hosting-probe.ts classifyLiveHostingBaseUrl)를 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-01
문제
캐시를 지우는 곳은 activate 하나다(현재 + 마커가 가장 높은 직전 1개).
템플릿은 requestActivation()을 부르지 않으므로 활성화는 그 scope의
탭이 모두 닫혀야 일어난다. 그 사이 release마다 새 후보가 waiting
워커를 밀어내지만 밀려난 캐시는 남는다(리뷰 실험 L2: A 활성 + 탭
유지에서 B, C를 받으면 소유 캐시 3개, 활성화 뒤 2개). 운영 문서는
"현재 + 직전 1개"만 말해 waiting 기간의 캐시 수가 보이지 않는다.
고른 방법
- 리뷰 5.1 판단대로 (a) 문서만 고친다. SW runbook 8절에 쌓이는 규칙,
예, 크기 상한, 쿼터에 닿았을 때의 결과, 줄이는 방법
(requestActivation 화면)과 install이 지우지 않는 이유를 적는다.
release-cache-rollback.md SW 1단계에 한 문장과 링크를 둔다.
- 버린 대안: (b) install 성공 뒤 "무마커 + 이번 후보 아님 + 활성 캐시
아님"을 지우기. install하는 워커는 활성 캐시 이름을 모르고, 마커
쓰기에 실패한 활성 캐시는 후보와 구별되지 않는다. (c) 이번 후보를 뺀
무마커 캐시를 모두 지우기. 그 활성 캐시를 지워 직전 캐시 보존 성질을
깬다.
위험·한계
- 쌓이는 동작 자체는 그대로다. 사전 캐시가 1 MiB를 넘고 release가 잦아
지면 (b)를 다시 본다(리뷰 재검토 조건).
- 브라우저 종료로 활성화되는지는 확인하지 않았다.
검증
- 문서와 코드(service-worker-lifecycle.ts onActivate,
service-worker-static-assets.ts QUOTA_EXCEEDED, service-worker.ts
assetSetBytes)를 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-04
문제
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
문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.
고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.
버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.
위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.
검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
문제
설정 키 금지 조각 검사(assertSafeConfigNames: TOKEN, COOKIE, SECRET 등)는
부팅 때 한 곳에서만 돈다. ece944d가 연 제품 키 경로로 PRODUCT_COOKIE_NOTICE
같은 키를 zod 필드·FE-REG-ENV 행·config/runtime 값으로 더하면
generateRuntimeConfig, 범위 테스트, check:registries가 모두 통과한다. 그
config.json으로 배포하면 모든 사용자가 부팅 실패 화면을 보고, 오류 코드
CONFIG_SECRET_NAME_REJECTED에는 키 이름이 없다(실험 E-4).
고른 방법
env-registry-coverage에 사례 하나를 더한다. V2 스키마가 읽는 키와
FE-REG-ENV 런타임 행 키 전부로, 값은 스키마 기본값(CAPABILITY_OVERRIDES의
중첩 키 포함)으로 문서를 만들어 assertSafeConfigNames에 넣는다. 실패
메시지가 키 이름을 말한다. 규칙은 매뉴얼 03 C절의 product-contracts.ts
항목에 적었다.
버린 대안
- product-contracts.ts 주석에 규칙 적기: 이 파일은 제품 소유이고 템플릿이
복사 뒤에 고치지 않는다고 약속한 파일이다. 동기화 때 충돌을 만든다.
- generate-runtime-config에서도 검사: 스키마가 strict라 제품 키는 스키마
필드여야 들어가고, 그 키는 이 테스트가 먼저 잡는다. 같은 검사를 한 곳
더 두지 않았다.
위험·한계
- 부팅 오류 CONFIG_SECRET_NAME_REJECTED에 거절한 키 이름을 싣는 것은 하지
않았다(src/bootstrap/load-runtime-config.ts, 다른 작업 범위).
- 제품 record 필드의 임의 중첩 키(값으로만 생기는 키)는 기본값에 없으면
이 테스트가 보지 못한다. 부팅 검사가 여전히 막는다.
검증
- E-4 재실행: PRODUCT_COOKIE_NOTICE를 제품 zod 필드와 행으로 더하면 이
사례가 "Forbidden client configuration key: PRODUCT_COOKIE_NOTICE"로
실패한다. 되돌리면 4건 통과.
- eslint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-04
문제: 앱·Service Worker·선택 레시피 번들의 청크 설정이 Vite 8에서
@deprecated인 build.rollupOptions 별칭에 있었다(0929/13-07, 세 라운드
남음). 별칭이 지워지는 Vite 버전으로 올리면 청크 그룹과 treeshake 설정이
조용히 빠질 수 있다.
고른 방법: 세 곳의 키 이름만 rolldownOptions로 바꾼다. 내용은 그대로다.
위험·한계: 없음에 가깝다. 같은 설정의 정식 이름이다.
검증: 바꾸기 전후 빌드의 dist/assets 파일 이름이 모두 같다(해시가 같아
출력이 같다). service-worker-build-output 7건 통과,
check:optional-recipes PASS(레시피 예산 4개 그대로).
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-07
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.
고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.
위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).
검증
- verify:documentation PASS_SCOPED. documentation-readiness·
changelog-review-ids 테스트 15건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.
고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.
위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.
검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.
고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.
위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
적는 중복은 문서 규칙으로만 막는다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.
고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
frontend-application-foundation, 계약 주석.
위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
옮겨야 node 검사가 통과한다.
검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제
Envelope 판정 표가 정하는 5xx는 503 IDEMPOTENCY_UNAVAILABLE 하나다. 짝
백엔드 http-contract.md가 직접 정한 다른 답 셋은 기능의 classifyProblem이
정한다.
- §2 500 IDEMPOTENCY_RECOVERY_REQUIRED: 이전 시도의 효과를 증명할 수 없다.
- §2 503 IDEMPOTENCY_COMPLETION_UNKNOWN(백엔드 bbe944bd): 작업은 돌았고
결과 기록이 실패했다. 같은 키로 나중에, 새 키 금지.
- §4 503 REQUEST_TIMEOUT: 비동기 요청이 시간을 넘겼고 처리가 계속될 수 있다.
분류기가 5xx를 NOT_APPLIED로 보면 셋 다 SERVER_FAILURE/NOT_APPLIED가 되고,
retryBudget이 있으면 실행기가 다시 보낸다. 폼은 "다시 시도"를 새 키로
연다(리뷰 실험 X-F). 백엔드가 "새 키 금지"라고 한 요청이다.
고른 방법
backend-envelope.ts에 MAYBE_APPLIED_ANSWERS(code → status)를 두고 IU와
같은 줄에 셋을 더했다. status와 code가 함께 맞을 때만 MAYBE_APPLIED다.
MAYBE_APPLIED는 retryHint를 끄므로 자동 재전송이 없고, 코디네이터가 키를
붙들어 결과 불명 화면의 재전송이 같은 키로 나간다. 자동 같은 키 재전송은
지금처럼 KEYED의 503 IU뿐이다.
버린 대안
RECOVERY_REQUIRED에 "재전송 불가" 표시를 실어 화면 버튼을 숨기기(리뷰 최소
개선의 뒷부분): 완료 기준 밖이고 바인딩·코디네이터·화면을 함께 바꾼다.
같은 키 재전송은 백엔드가 다시 실행하지 않고 같은 500이나 재생으로 답한다.
남은 문제로 보고한다.
위험·한계
500 DB_COMPLETION_UNKNOWN(백엔드 error-codes.yaml, http-contract.md 밖)은
넣지 않았다. 계속 분류기가 정한다.
검증
- RED: backend-envelope 단위 3건, envelope 통합 4건(LENIENT 분류기 세 code의
effect, retryBudget 2에서 fetch 1회·같은 키) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,121건 통과. check:types:app·test, eslint, verify:documentation 통과.
- 매뉴얼 02 4절, 계약 문서 6.1절, descriptor 주석에 네 답을 적었다.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-04
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
문제
heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지
않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은
유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7).
훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신,
isReconnectAttemptResetEligible)을 같이 읽어야 안다.
고른 방법
- 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에
같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을
만들라고 적는다. 동작은 바꾸지 않는다.
위험·한계
- 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다.
검증
- 바꾼 파일 eslint 통과. 주석만 바꿨다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04
문제
tests/unit/task3-selective-integration.test.ts의 EOF 테스트는
provider-scope-wrapper.ts를 새 Node로 띄우고, 준비 신호 없이 75 ms를 잔
뒤 stdin을 닫고 1초 안에 끝나기를 기다린다. 75 ms 안에 자식이 기동을
끝내지 못하면 Node 기동과 TS 모듈 import가 그 1초에 들어간다. 그래서
부하가 걸린 호스트에서 "provider scope EOF close timed out"으로 merge
게이트가 코드와 무관하게 떨어진다.
고른 방법
- guardian 테스트(c862004)와 같은 방식: 자식을 loader로 띄우고, loader가
바뀌지 않은 wrapper를 import한 뒤 여분 pipe(fd 3)에 1바이트를 쓴다.
테스트는 그 신호를 받은 뒤에 stdin을 닫는다. import가 끝나면 wrapper는
liveness 채널을 열고 EOF 처리기를 붙인 상태다.
- 한도는 1초 대신 같은 계열의 watchdog 5초로 둔다. 이 한도는 멈춤만
판정한다. wrapper에 EOF 마감 같은 프로토콜 요구는 없다.
- 버린 대안: 한도만 5초로 올리기. 기동 시간이 계속 한도 안에 든다.
PROVIDER_PROCESS_TRACE_PATH 기록을 준비 신호로 쓰기. 파일 poll에 다시
마감이 필요하다.
위험·한계
- wrapper는 main 모듈이 아니라 loader가 import한 모듈로 돈다. wrapper는
argv[2..]만 읽고 import.meta를 쓰지 않는다. 여분 fd 3은 신호 뒤 닫힌다.
- 파일 위치(tests/unit vs taxonomy의 tests/integration)는 1101/10-05와
같이 정할 일이라 옮기지 않았다.
검증
- RED: 자식만 기동에 1.5초를 쓰게 하는 --import 훅(scratchpad
slow-start.mjs)으로 수정 전 테스트가 "provider scope EOF close timed
out"으로 실패했다. 수정 뒤 같은 조건에서 통과(1.6초).
- 한 코어에 바쁜 이웃 14개(taskset) 5회 모두 통과.
- 변이: wrapper의 liveness.once("end", …)를 지우면 테스트가 실패한다
(code 0 ≠ 125). 되돌렸다.
- 파일 전체 7건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-01
문제
자기 해제 service-worker.js는 REMOVE_REGISTRATION release만 낸다
(build-frontend.ts). 다음 단계 release에는 워커 파일이 없어 update
검사가 404로 실패한다. PURGE_OWNED_RESOURCES는 부팅한 페이지만 다시
unregister하고, null은 아무것도 하지 않는다. 1단계 기간에 오지 않은
사용자에게 부팅을 막는 워커나 옛 워커가 남는다(리뷰 1103 실험 L3).
운영 문서는 세 단계 순서만 적고 각 단계 유지 기간이 없다.
고른 방법
- 0929/06-06의 최소 방향 중 문서 한 줄을 고른다. SW runbook 8절과
release-cache-rollback.md 4단계에 "1단계를 최대 미방문 기간 이상 유지,
그 뒤 남은 사용자가 보이면 1단계를 다시 배포"를 적는다.
- 버린 대안: 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을
맞추기. 빌드·hosting 검사·e2e를 함께 바꿔야 해서 이월 항목의 작은
수정 범위를 넘는다.
위험·한계
- 동작은 그대로다. 유지 기간을 지키는지는 운영자 몫이다.
검증
- 문서와 코드(build-frontend.ts, service-worker-page-controller.ts
PURGE_OWNED_RESOURCES 분기, service-worker-removal.ts)를 대조했다.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-06
문제
WebSocket 연결은 구독마다 1초 창에 maxEventsPerSecond(256, server가
알린 값과 작은 쪽)를 넘는 event가 오면 EVENT_RATE_EXCEEDED recovery를
요청하고 QUEUE_OVERFLOW로 닫는다. 이를 확인하는 테스트가 없어 검사를
꺼도 모든 테스트가 통과한다(리뷰 변이 R7, 두 라운드째). 설계 11절
상한표에도 행이 없다.
고른 방법
- 상한을 2로 낮춘 연결에서 2개 → 1초 뒤 2개(열림 유지) → 1개 더(닫힘,
EVENT_RATE_EXCEEDED)를 보내는 테스트 1건을 더한다. 창 초기화와 상한
값 출처까지 한 테스트가 본다.
- 설계 11절 상한표에 행 하나를 더한다.
위험·한계
- 동작은 바꾸지 않았다. 실제 서버 부하로는 확인하지 않았다.
검증
- 새 테스트 통과(websocket-connection 24건).
- 변이 3건 모두 검출: 상한 검사 끄기(R7), 1초 창 초기화 삭제, 협상된
상한 대신 256 고정.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 1101/04-03
문제
tests/browser-capabilities/indexeddb-runtime.spec.ts의 차단 업그레이드
테스트는 v2 runtime을 blockedTimeoutMs 500으로 시작한 뒤
expect.poll(lifecycleStatus)로 BLOCKED 상태를 기다린다. 이 상태는
500 ms 뒤 CLOSED/NOT_OPENED로 바뀌고, 폴링 한 번은 page.evaluate
왕복이다. 그래서 바쁜 호스트에서는 첫 관찰 전에 창이 닫혀 FE-GATE-008이
코드와 무관하게 떨어진다(리뷰 전체 실행에서 chromium·webkit 실패).
고른 방법
- 전이 상태 폴링을 지우고, 바로 뒤 settleLifecycleRuntime 결과
(opened.error.code BLOCKED, recovery RELOAD_OTHER_CONTEXTS, status
CLOSED/NOT_OPENED)로 차단을 판정한다. 전이 상태 BLOCKED는 제어한
scheduler로 tests/unit/indexeddb-runtime.test.ts가 이미 고정한다.
- 버린 대안: blockedTimeoutMs를 늘리기. 창이 넓어질 뿐 경쟁이 남는다.
runtime이 상태 변화를 기록하게 하기. 운영 코드에 테스트용 기록이
생긴다.
위험·한계
- 실제 브라우저에서 getStatus()가 BLOCKED를 돌려주는 순간은 이 spec이
더는 보지 않는다(단위 테스트가 본다).
검증
- RED: 창을 20 ms로 줄이면 수정 전 테스트가 chromium·webkit에서
CLOSED/NOT_OPENED를 받아 실패했다(리뷰 실패와 같은 모양). 수정 뒤 같은
20 ms에서 세 엔진 통과. 값은 500으로 되돌렸다.
- test:browser-capabilities 전체 63 passed(load 15~20). 5회 반복은 하지
않았다.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-05
문제: withTransactionLock은 partition lock을 signal 없이 요청한다
(withPartitionLock("shared", operation, undefined, run)). put·remove의
request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면
시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만
걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은
partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면,
삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기).
05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다.
고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고,
withPartitionLock은 kernel createAbortableOperation으로 caller signal과
mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller
abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의
acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를
지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다).
lock 전 abort는 journal begin 전이라 보상할 것이 없다.
버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이
남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다.
위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다.
다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고
호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort
경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb
번들 37,521 → 37,555 / 38,500 gzip B.
검증:
- RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에
끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지
않아 10초 timeout.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건
통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source
PASS, verify:documentation 통과.
- browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진
27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러
5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02
문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫
복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이
섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가
비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md,
static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고
현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발).
(3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서
픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드
(약 201 KB)가 아니라 약 264 KB였다.
고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가
기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의
비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰
값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript
한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계
1%, 파일 수 정확히, 기능·context 비용 10%). 기록은
`measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다.
문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고
돈다.
버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서
숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가
필요하다).
위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는
변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다.
`298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은
측정 기록으로 남겼다.
검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2%
바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개,
기능 +765 B, context +214 B. feature-shape-growth 7건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).
고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
소유 src/features/product-capabilities.ts의
PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
(validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
(선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.
위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.
검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
runtime-composition-service-worker-telemetry, product-features,
product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
문제
catalog의 service-worker-pwa trigger는 "a measured offline-shell
requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이
있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는
navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며,
설계는 cached index.html fallback을 금지한다(closed deep design 18.8).
catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게
알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례).
고른 방법
- 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인
셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품
capability"를 적는다. failureKinds의 offline-fallback을
offline-navigation-network-error로 바꾼다.
- 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시
증명할 e2e 단언과 성질, 동기화 충돌)를 적는다.
- 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가
금지한 동작이고 재검토 조건(제품 요구)이 아직 없다.
위험·한계
- catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다.
검증
- json-schema 테스트 6건 통과, check:remediation-ledger·
check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.
고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
(409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
<FEATURE>_INVALID 예와 거부 문구를 적었다.
버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).
위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.
검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
계속 검출.
- check:types, lint, check:registries, check:architecture,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
문제
참조 기능의 FE-REG-SCHEMA 행은 응답 스키마를 STRIP_UNKNOWN, 요청 스키마를
REJECT_UNKNOWN이라 적는다. 실제 정책은 zod .strip()·.strict()가 정하고,
unknownFieldPolicy·direction을 읽는 실행 코드는 없다. 응답 DTO를 .strict()로
바꿔도 check:registries와 관련 테스트가 모두 통과한다(실험 X8). 그러면
백엔드가 응답에 필드 하나를 더할 때마다 그 API가 SCHEMA_MISMATCH로
실패하는데, 스냅샷과 docs/contracts/compatibility.md는 여전히 additive라
말한다.
고른 방법
설치된 기능의 HTTP descriptor마다 입력·출력 검증기를 FE-REG-SCHEMA 행과
대조하는 테스트를 더한다.
- direction: 입력 검증기 행은 REQUEST, 출력 검증기 행은 RESPONSE.
- unknownFieldPolicy: 아무 스키마도 선언하지 않는 키 하나를 가진 객체와,
그 객체 하나를 담은 배열을 검증기에 넣는다. 그 객체 위치의
unrecognized_keys면 REJECT_UNKNOWN, 객체 안을 봤는데 그 issue가 없으면
STRIP_UNKNOWN이다. 정책을 적은 행만 본다.
loaded-feature-runtimes를 읽으므로 다운스트림이 더한 기능도 같은 검사를
받는다. create:feature 뼈대(NoRequest strict, 목록 응답 strip)도 맞는다.
버린 대안
- 메타데이터에서 두 칸을 지우기: 읽는 곳이 없어 가장 단순하지만 호환
문서의 근거가 사라지고 기준선 재승인이 필요하다. 메타데이터 생성은
다른 작업(16-04~06) 범위다.
- 스키마마다 유효한 예시 값을 두고 모르는 키를 더하기: 기능마다 예시를
손으로 써야 해 다운스트림 기능을 자동으로 덮지 못한다.
위험·한계
- 탐침은 payload의 첫 객체 단계(객체, 또는 배열의 항목)만 본다. 그 아래
중첩 객체의 정책은 보지 않는다.
- problem 검증기는 FE-REG-SCHEMA 행이 없어 대상이 아니다.
검증
- 변이: 응답 DTO .strip()→.strict()(X8), 생성 명령 .strict()→.strip(),
응답 행 direction을 REQUEST로 바꾸면 각각 실패한다. 되돌리면 2건 통과. 설치된 기능이 없으면(샘플 제거 뒤) 두 건 모두 빈 채로 통과한다.
- eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-03
문제
기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은
"missing registry source src/features/loaded-feature-runtimes.ts: Installed
contract contribution is not composable" 두 줄, "FE-REG-API is not an
object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA",
"breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은
ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다.
끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을
제안한다(실험 E-9).
고른 방법
- source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께
적는다.
- 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사
("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교
(removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지
않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다.
- errors.md 레지스트리 표에 이 메시지 행을 더했다.
버린 대안
- 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와
CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다.
위험·한계
- source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도
"missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서
지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다.
- FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다.
검증
- RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가
다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를
던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고
cascade 3줄이 더 나와 실패했다.
- GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록
operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason:
reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId
NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다.
- check:registries:fixture·check:routes:fixture·baseline-fixture가 기대
진단으로 실패한다. eslint, check:types:node, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06
문제
zod-is-reached-through-contracts-zod 규칙의 to.path가 ^zod$다. src 파일이
"zod/v4"를 import하면 check:architecture가 rc=0으로 통과한다(실험 Z1). 그
모듈은 src/contracts/zod.ts의 jitless 설정보다 먼저 스키마를 만들 수 있고,
그러면 운영 CSP가 zod의 Function 탐침을 부팅마다 보고한다(F-7).
고른 방법
to.path를 ^zod(/|$)로 넓힌다. 그래프 fixture에 "zod/v4"를 import하는 파일과
그것이 거절되는지 보는 회귀 검사를 더했다. layers.md 규칙 표도 고쳤다.
버린 대안
- eslint no-restricted-imports에 zod 패턴 추가: 같은 규칙을 두 도구에
둔다. 경계 규칙은 dependency-cruiser가 정본이다.
위험·한계
- src 안에 zod 하위 경로 import는 지금 없다(grep). 다운스트림이 쓰고
있으면 check:architecture가 실패한다. src/contracts/zod.ts의 z로 바꾼다.
검증
- 수정 뒤: 참조 기능 스키마 파일 import를 "zod/v4"로 바꾸면
"Architecture violation [zod-is-reached-through-contracts-zod]: ... ->
zod/v4"로 실패, "zod"도 실패.
- 규칙을 ^zod$로 되돌리면 새 회귀 검사 "zod subpath import outside
src/contracts/zod.ts is rejected"가 실패한다.
- check:architecture(29 regression checks PASS), check:types, eslint,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-06
문제
- AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason
kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과
action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry)
설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05).
- CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지
않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만
있다(1101/07-07).
- 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에
없다.
고른 방법
주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다
재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고,
화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지
않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행.
버린 대안
- retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는
비용에 비해 얻는 것이 작다.
위험·한계
- 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금
상태다.
검증
- grep: src/presentation·bootstrap·features·application에서
AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요
화면뿐.
- eslint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는
logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된
ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은
남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE
DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도
지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고
수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고,
그 경보가 진짜 손상을 가린다.
고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지
않는다. 대신
- journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키
범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음).
- reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸
없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다.
- runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면
없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다.
버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 —
그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번).
위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage
.unattributedRows, OpfsReconciliationReport
.unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면
지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이
SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의
partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다.
offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B.
검증:
- RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음,
opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions
없음으로 실패.
- GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다.
키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면
DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host +
tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일
eslint, check:optional-recipes:source PASS, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03
문제
워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번
리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect:
"error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의
CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8).
고른 방법
- service-worker-runtime.test.ts에 테스트 3건을 더한다.
- install이 자산마다 cache no-store, credentials omit, redirect error로
요청한다(M1).
- 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은
client의 drain 응답은 세지 않는다(M3, M9).
- active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8).
- 동작은 바꾸지 않는다.
위험·한계
- N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를
흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다.
검증
- service-worker-runtime 64건 통과.
- 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고
되돌렸다.
- 바꾼 파일 eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04
문제: OPFS worker runtime을 메모리에서 돌리는 MemoryDirectory·MemoryFile이
tests/unit/opfs-worker-runtime.test.ts 안에만 있다. 05-04를 고치려면
recipe fake와 runtime에 같은 시나리오를 돌리는 parity 테스트가
tests/recipes에 필요한데, 그 테스트는 이 파일 시스템을 쓸 수 없다.
unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로
parity 테스트를 unit 쪽에 둘 수도 없다.
고른 방법: 그 블록(MemoryNode·MemoryFile·MemoryDirectory·fileHandle·
notFound)을 그대로 tests/helpers/memory-opfs.ts로 옮기고 export한다.
memory-indexeddb.ts와 같은 자리다. 코드는 바꾸지 않았다. helper는 src를
import하지 않아 browser-file-storage 제거 드릴에서도 남아도 된다.
위험·한계: 동작 변경 없음.
검증: opfs-worker-runtime.test.ts 82건 통과. check:types:test, 바꾼 파일
eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04
문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만
후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬
프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback
API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인
(FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는
config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만
비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip
바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지
않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다.
고른 방법:
- 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치
두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나
읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수
(scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다.
- 받은 index.html의 entry script를 후보 index.html의 것과 비교한다.
- cache-policy.json에 transport.alpnProtocols(["h2"])와
hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS
handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의
Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로
붙어서 프로토콜은 따로 확인해야 한다.
- nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와
release-cache-rollback.md에 두 전제와 실패 조건을 적었다.
두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다.
버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이
생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기
(아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면
제품이 끌 수 있다).
위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그
제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와
Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약
규칙은 다음 커밋(제품 overlay)에 있다.
검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상
스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry →
FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을
더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험:
http2.createSecureServer → "h2", https.createServer → "http/1.1",
인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID.
verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02
문제
참조 폼 페이지는 저장 중과 결과 불명 동안 저장 버튼에 disabled를 준다.
포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 body로 내려놓는다. 폼은 필드
오류일 때만 포커스를 옮겼으므로, 키보드로 저장했다가 결과 불명(500)이나 429를
받으면 세 엔진 모두 포커스가 body로 떨어졌다. 복구 버튼은 폼 위 feedback
자리에 있어 셸 머리말부터 다시 지나야 닿았다.
고른 방법
- useAppForm이 feedbackId를 내고, 필드 오류·성공이 아닌 결과(결과 불명,
재인증, 권한 없음, 다시 시도, 사용 불가, 충돌)로 끝나면 렌더 뒤 그 요소에
포커스를 준다. FormPage(StandardPage)는 feedbackId를 받으면 feedback 자리를
id + tabIndex=-1인 포커스 대상으로 만든다. 페이지마다 포커스 코드를 복사하지
않게 하려고 hook과 템플릿에 두었다.
- 참조 폼의 저장 버튼은 저장 중에 disabled 대신 Button의 pending(aria-busy)을
쓴다. 중복 제출은 지금처럼 폼(submitForm)과 onSubmit 가드가 막는다. 결과
불명 동안에는 여전히 꺼진다(08-01 범위). 그때는 위의 포커스 이동이 받는다.
- 첫 행동 버튼 대신 feedback 자리 전체를 포커스한 이유: 실패 종류마다 버튼
구성이 다르고, Tab 한 번에 첫 복구 버튼에 닿는다.
매뉴얼 02 6절 FormPage에 feedbackId와 pending을 적었다.
위험·한계
- 스크린 리더가 포커스된 feedback 자리를 어떻게 읽는지는 확인하지 않았다.
- 파생 폼 페이지는 feedbackId를 넘겨야 이 동작을 얻는다.
- "deduplicates create" 테스트의 저장 중 단언을 disabled에서 aria-busy와
포커스 유지로 바꿨다. 한 번만 호출되는 단언은 그대로다.
검증
- RED: reference-page.test.tsx 새 2행(결과 불명, 429)이 수정 전 실패. e2e
reference-save.spec.ts 새 2건이 수정 전 소스에서 chromium·firefox·webkit
6건 모두 실패(feedback 자리 focused 아님).
- 수정 후 reference-save·reference-form e2e 3엔진 45건 통과(heavy lock,
CHOKIDAR_USEPOLLING=1). tests/component·tests/features 60 files / 368
tests 통과. check:types, eslint, check:design-system, check:i18n,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-02
문제: 프론트 업로드 레시피(PRESIGNED_MULTIPART_V1, 브라우저가 object
store에 직접 PUT)를 받는 서버가 짝 백엔드 템플릿에 없다. 짝 백엔드는
2026-09-25에 presigned·direct multipart 코드를 지웠고, 파일은 자기
Fileserver가 직접 받는다(POST /v1/files, POST /v1/files:raw, tus). 그런데
서버 handoff 문서는 아직 "서버 구현 대기", "이후 서버 template에서 구현"
이라고 적고, docs/manual에는 업로드 언급이 없다. 팀은 조립 단계에서야
짝이 아님을 안다.
고친 방법(리뷰 D1 (다)):
- server-file-capability-infrastructure.md 상태 줄을 "짝 백엔드 템플릿은
구현하지 않음(2026-09-25 제거)"으로, 대상을 "제품 backend가 직접 구현"
으로 고치고 짝 아님 안내를 머리에 둔다.
- presigned-transfer-and-image-cdn.md 머리에 같은 안내를 둔다. presigned
다운로드와 private Image CDN descriptor 발급 서버도 짝 백엔드에 없다.
- 레시피 카탈로그 file-transfer의 fallback에 짝 백엔드 경로(Fileserver
POST /v1/files)를 적는다.
- docs/manual/02-decision-tables.md에 7절 "파일 업로드"를 더한다. 두 경로
비교와 고르는 기준이다. 매뉴얼 README의 목차 줄도 고친다.
위험·한계: 문서만 바꾼다. 짝 백엔드로 파일을 올리는 프론트 client는 이
커밋에 없다(다음 커밋, D1 (나-1)). 백엔드 매뉴얼에 같은 안내를 적는 일은
백엔드 repo 몫이라 하지 않았다.
검증:
- verify:documentation PASS_SCOPED
- check:optional-recipes:source PASS (file-transfer 56,084/57,800)
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.
고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.
버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.
위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
"적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.
검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
문제: (1) 배포 슬롯 계약은 단계 종류만 제한하고 "마지막이 deploy 하나"만
강제했다. checkout → setup-node → frozen-install → deploy(script)처럼
후보 archive를 받지 않고 다시 빌드하는 슬롯도 check:ci를 통과했고,
생성된 job 이름은 그대로 deploy-promoted-release였다(리뷰 실험 E-3).
(2) 생성기는 슬롯의 환경 바인딩을 job 수준 env:로 썼다. 그래서
secrets.* 배포 자격 증명이 checkout, setup-node, frozen-install과
제3자 download action에도 보였다.
고른 방법: (1) deploy 단계에 script가 있으면 promoted-release 전송 하나만
download하고, 그 경로의 release-candidate.tar.gz를 extract하고,
CANDIDATE_ARCHIVE_SHA256을 immutable_build의 digest로 바인딩해야 한다.
extract는 verify-ci-candidate-archive.ts가 digest로 확인한다. 빈 슬롯은
그대로 허용한다. (2) 배포 슬롯의 secrets.* 바인딩은 deploy 단계의 env:로만
렌더링한다. vars.*와 후보 digest는 job 수준에 남는다(extract가 digest를
쓴다).
버린 대안: 슬롯 단계를 템플릿이 통째로 고정하기. 다음 커밋의 제품
overlay가 채우는 모양을 고정하고, gates.json으로 채우는 길은 이 규칙으로
막는다.
위험·한계: 슬롯이 받은 파일을 deploy 스크립트가 실제로 올리는지는 계약이
볼 수 없다. 그것은 FE-GATE-019의 config.json·entry 대조(앞 커밋)가 결과로
본다. 템플릿 슬롯은 비어 있어 생성 workflow 바이트는 바뀌지 않는다.
검증: ci-workflow-generation.test.ts에 후보 없이 deploy하는 슬롯과
digest 없이 extract하는 슬롯의 거절, secret이 deploy 단계 env에만 한 번
나오는 것을 더했다(고치기 전 3건 실패). 425건 통과. check:ci PASS,
CI workflow bytes PASS.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-05
문제: recipe fake MemoryDurableObjectStore의 reconcile은 멈춘 put 행을
모두 rollback으로 센다. runtime은 FILES_READY 행을 다시 검증한 뒤
commit하고 finalize한다(runbook, 설계 문서의 roll-forward). recipe 테스트
주석은 "Like the runtime, reconcile rolls a stopped put back"이라고 적는다.
이 fake로 쓴 다운스트림 테스트는 "멈춘 업로드는 reconcile 뒤 사라진다"를
통과하지만 실제로는 객체가 다시 생긴다. fake의 LOGOUT·ACCOUNT_DELETION도
멈춘 행을 보지 않아 05-01을 fake 테스트로 찾을 수 없었다.
고른 방법: fake가 멈춘 단계를 기억한다. FILES_READY까지 간 행은 commit될
객체를 함께 둔다. reconcile은 그 행을 runtime과 같은 generation 검사로
commit하고(committedTransactions), PREPARING 행은 rollback한다.
LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지우고, 그런 행이 있었으면 runtime처럼
chunkSweep 대신 partitionDeleted를 보고한다. 같은 네 시나리오(두 단계 ×
reconcile 전 계정 삭제 여부)를 메모리 OPFS·IndexedDB 위의 실제 runtime과
fake에 돌려 결과가 같은지 보는 parity 테스트를 tests/recipes에 더했다.
unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로
parity 테스트는 recipe 쪽에 두었다(앞 커밋이 메모리 OPFS를 helper로
옮긴 이유).
위험·한계: 이 fake를 쓰는 다운스트림 테스트 중 FILES_READY 멈춤 뒤
rollback을 기대하던 것은 기대값이 바뀐다. 기존 recipe 테스트는 같은
흐름을 유지하려고 PREPARING 멈춤으로 바꿨다. fake는 runtime의 재검증
실패(digest 불일치) 경로는 흉내 내지 않는다.
검증:
- RED: parity 테스트 4건 중 3건 실패(fake가 FILES_READY를 rollback,
계정 삭제가 partitionDeleted 없이 COMPLETED). runtime 쪽 기대값은
처음부터 통과.
- GREEN: tests/recipes 24건 통과. check:types, 바꾼 파일 eslint,
check:optional-recipes:source PASS.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04
문제
짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 meta.page(number·size·
total·sort)에 싣는다(http-contract.md §1). 프론트 Envelope 읽기는 meta에서
id 셋만 남기고 data만 꺼낸다. 그래서 목록 기능은 첫 페이지(기본 20개)만 받고
전체 수를 모른다. 생성된 목록 화면의 "총 N개 항목"은 배열 길이라 페이지
크기를 전체 수처럼 보인다(리뷰 실험 X-G). 우회하려면 responseEnvelope를 빼야
하고, 그러면 Envelope 실패 판정을 함께 잃는다.
고른 방법
- backend-envelope.ts: meta에 page 스키마(정수, number·total 0 이상,
size 1~100, sort 문자열 또는 null). 범위 밖이면 page만 버리고 응답은 읽는다.
readSuccessEnvelope가 data와 함께 page를 돌려준다.
- 실행기의 SUCCESS 결과에 선택 칸 page. outputValidator는 지금처럼 data만
본다.
- 바인딩: mapSuccess(value, context)의 두 번째 인자 FeatureHttpSuccessContext
{ page? }. 한 인자짜리 기존 mapSuccess는 그대로 맞는다.
- 배럴에서 EnvelopePage·FeatureHttpSuccessContext 타입을 낸다.
- 계약 문서 4.1절에 meta.page 경로와 "bulk results는 지원하지 않는다", 7절에
"짝 백엔드는 offset meta.page"를 적었다.
버린 대안
- outputValidator에 { data, page }를 넘기기: 기존 기능 스키마가 모두 깨진다.
- 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다.
- page가 범위 밖이면 응답 전체를 거절: meta의 모르는 키는 무시한다는 백엔드
§1 규칙과 어긋난다.
위험·한계
- 생성기(create-feature.ts)의 목록 화면은 아직 배열 길이를 보인다. 생성기
담당 작업이 page.total을 쓰도록 이어 받는다.
- bulk는 지원하지 않고 문서로만 알린다.
검증
- RED: envelope 통합 3건 실패(mapSuccess가 page를 받지 못함, 정렬 없는
page 2건).
- GREEN: 같은 파일 51건 통과. 범위 밖 page 3건(size 500, number -1, total
1.5)은 page 없이 SUCCESS. tests/unit·integration·component·features·
contract·runtime-schema 253파일 3,209건 통과.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-02
문제: composeProductSessionOwner는 config와 raw fetcher만 받는다. owner는
http보다 먼저 만들어져 세션 조회·토큰 호출을 직접 해야 하는데, 응답하지
않는 호출 하나가 세션을 recovery-pending에 영원히 둔다. 픽스처의 쿠키
owner 스케치가 바로 그렇게 쓴다. 로그인 리다이렉트에 필요한 페이지
(location·history)와 sessionStorage도 bootstrap lint가 전역 접근을 막아
제품 파일에서 얻을 길이 없다.
고른 방법: ProductSessionOwnerContext에 넷을 더한다.
- fetch: 헤더와 본문 전체에 마감 하나(REQUEST_TIMEOUT_MS가 상한, 호출이
줄일 수만 있다). 본문은 64 KiB까지 메모리로 읽어 새 Response로 준다.
redirect는 항상 error. fetcher가 signal을 무시해도 경합으로 끝난다.
- readCookie: composeProduct와 같은 host cookie 읽기.
- page: href·replaceUrl·assign. host에 없으면 throw로 닫힌다.
replaceUrl은 라우터의 history state를 그대로 둔다.
- redirectStorage: host sessionStorage. 토큰이 아니라 리다이렉트 한 번
동안의 상태만 둔다고 계약에 적었다.
조립은 새 파일 product-session-owner-context.ts에 두고
runtime-adapters.ts는 호출 한 곳만 바꿨다. fetch 구현
(session-owner-fetch.ts)은 처음 쓸 때 동적 import로 읽는다. 초기 번들
여유가 3 KB 남짓이라 demo 모드나 owner 없는 제품이 이 코드를 내려받지
않게 했다.
버린 대안:
- platform 커널 createAbortableOperation 사용. 커널이 boot가 이미 읽는
배럴과 같은 청크로 묶여 지연 청크로 빼도 초기 번들에 남았다(빌드로
확인). 그래서 read-bounded-boot-json.ts와 같은 마감 방식을 쓴다.
- 마감만 주고 본문은 owner가 읽게 두기. 본문이 멈추면 다시 무한 대기다.
위험·한계: fetch는 필수 필드라 ProductSessionOwnerContext를 직접 만드는
제품 테스트는 컴파일이 깨진다. 기존 fetcher는 그대로 둔다. 지연 청크
적재 시간은 마감에 들어가지 않는다(라우트 청크와 같다).
검증: tests/unit/product-session-owner-context.test.ts 12건(구현 전 모듈
없음으로 실패 확인), product-composition-fixture·runtime-adapters 테스트
통과, check:types, eslint 통과. build + check:bundle: initial JS
202,242 / 204,800 B gzip(09-11 포함, 기준 201,848), 지연 청크
session-owner-fetch 0.81 kB gzip.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제: AUTH_MODE external은 제품이 owner 8개 메서드를 직접 써야 하는데,
짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 owner가 src·recipes
어디에도 없다. 쿠키 owner 모양은 테스트 파일 안 스케치뿐이다. 그래서
제품마다 첫 연동 전에 토큰 획득·갱신·subject·상태 전이·401 처리를
처음부터 쓴다.
짝 백엔드(bbe944bd)에서 확인한 계약:
- jwt 모드(기본): OAuth2 resource server. iss = APP_SECURITY_JWT_ISSUER
(local http://localhost:8081/realms/ca-skeleton), aud 필수. CSRF·세션
없음. 그러나 realm에는 서비스용 confidential client(ca-skeleton-api,
standard flow 꺼짐)만 있고 브라우저용 public client가 없다.
- redis-session 모드: CA_SESSION httpOnly 쿠키, CookieCsrfTokenRepository
(XSRF-TOKEN 쿠키, X-XSRF-TOKEN 헤더, plain handler). 로그인·로그아웃·
세션 조회·CSRF 발급 엔드포인트는 운영 코드에 없다(테스트 픽스처만).
고른 방법: recipes/session-owners/에 둘을 둔다. 제품은 src/bootstrap/로
복사해 composeProductSessionOwner에서 돌려준다.
- oidc-pkce-session-owner.ts: authorization code + PKCE S256, WebCrypto와
context fetch만 쓴다(라이브러리 없음). 토큰은 메모리에만, sessionStorage
에는 10분짜리 거래(verifier·state·nonce·returnTo)만 두고 콜백이 먼저
지운다. 콜백 URL에서 code를 네트워크 호출 전에 지운다. state·RFC 9207
iss·nonce·aud·azp·exp·sub를 검사하고, 갱신 때 sub가 바뀌면 로그아웃.
bearer는 apiOrigins에만 보낸다. 만료 30초 전 갱신은 한 번만 하고 상태
알림이 없다. 401이면 refresh token으로 한 번 복구하고, 그 토큰도 401이면
로그아웃. 설정이 틀리면 integration-failed로 닫는다.
- cookie-session-owner.ts: 세션 조회·로그아웃 URL과 로그인 시작을 기본값
없이 받는다(백엔드에 없는 엔드포인트를 지어내지 않는다). 200+subject →
authenticated, 401 → unauthenticated, 그 밖은 reject(상태 유지).
SESSION_COOKIE_READ/WRITE 프로필과 XSRF-TOKEN → x-xsrf-token provider.
쿠키가 없으면 쓰기는 UNAVAILABLE로 아무것도 보내지 않는다.
- 두 owner 모두 SessionState·recover 전이 계약을 따른다.
- PRODUCTION_IMPORTS_RECIPE 검사를 recipes/session-owners에도 건다.
recipe는 복사하지 import하지 않는다(초기 번들 밖).
버린 대안: src에 기본 owner 내장(IdP 결합이 템플릿 본체에 들어간다),
OIDC 라이브러리 의존(fetch·WebCrypto로 충분), 매뉴얼만(같은 실수 반복).
위험·한계: 실제 Keycloak·Redis session 백엔드에 붙여 보지 않았다. ID
token 서명은 검사하지 않는다(토큰 엔드포인트 직접 응답, OIDC Core
3.1.3.7 (6)); access token 서명은 백엔드가 본다. 새로고침하면 메모리
토큰이 사라져 다시 로그인한다(Keycloak SSO면 비밀번호 없이 돌아온다).
쿠키 모드는 페이지와 API가 같은 host여야 XSRF-TOKEN을 읽는다.
검증: tests/recipes 3파일 52건(구현 전 모듈 없음으로 실패 확인).
변이 15개(state·origin·401 한 번·nonce·iss·URL 정리·갱신 sub·TTL,
CSRF 헤더·401·로그아웃 실패·notify·단일 조회·subject 상한·credentials)
모두 실패로 잡힘. runtime 조립 테스트 4건이 실제 createRuntimeAdapters로
EXTERNAL_BEARER bearer, 401 뒤 갱신, 쿠키 쓰기의 x-xsrf-token을 확인.
check:optional-recipe-fixtures(regex 변경 없이는 실패 확인),
check:optional-recipes:source, check:types, eslint 통과. 두 recipe의
minify+gzip 크기 3.8 kB, 1.1 kB.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유
config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도
"deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이
바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고,
다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다.
고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈
파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다.
- deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지
슬롯(promoted-release download, digest로 확인하는 extract, deploy)은
템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을
그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay
양쪽에서 슬롯을 채우면 거절한다.
- mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의
product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE
id·명령·산출물·readiness 공식은 건드리지 못한다.
loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약
기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는
거절하고, 제품 gate script는 ungated 검사에서 gated로 센다.
버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할
명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이
산출물 전달이 검증되지 않았다).
위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식
밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성
workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면
재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다.
검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯
채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job
렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를
채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성
YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿
변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다.
ci-workflow-generation 425건, check:ci PASS.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제
AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2
client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서
traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘
undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를
싣는다(http-contract.md §1).
고른 방법
- readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미
meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다.
- 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에
싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 →
보낸 id)는 그대로다.
- 계약 문서 5절의 correlation 문단에 한 줄 더했다.
버린 대안
traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이
필요하고, 백엔드가 이미 주는 지원용 id를 버린다.
위험·한계
- Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패,
Envelope 없는 operation은 traceId가 없다.
- 텔레메트리에는 싣지 않는다(요청 단위 값).
- 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다.
검증
- RED: envelope 통합 1건 실패(404 실패의 traceId 없음).
- GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit·
integration·component·features·contract·runtime-schema 253파일 중 252파일
통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은
이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과
무관하다.
- check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.
고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).
위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.
검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제: browser-files runtime은 세션을 모르고, 닫는 수단은
runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state
scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일
runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지
않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번
불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서
연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중
download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이
메모리와 다운로드 폴더에 남을 수 있다).
고른 방법(리뷰 5.3절 (다) + 레시피 예제):
- ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant:
label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline
lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가
돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가
있으면 template participant와 같이 READY로 가지 않는다(FAILED).
composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이
자리를 미리 만들고 나중에 채운다.
- recipes/frontend-capabilities/browser-file-session-capability.ts:
기능에는 runtime 대신 current() getter를 주고, participant가 dispose한
뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다.
- 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새
레시피 파일도 같이 지운다.
버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수
없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독
위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를
제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 —
adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다.
위험·한계:
- 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로
컴파일된다, [계약]).
- 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을
들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음
세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는
없다).
- app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다.
- 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다).
- scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도
고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다.
검증:
- RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환
뒤에도 이전 runtime의 readRange가 ok로 실패.
- GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange
UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대
runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope-
participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행).
- 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락)
모두 새 테스트가 잡았다.
- runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과.
check:types, 바꾼 파일 eslint, check:architecture, verify:documentation
통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.
고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
"effect_certainty는 필요해지면 더한다" 문장은 지웠다.
버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
섞인다. 비율은 effect_certainty로 센다.
위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
맞춰야 한다.
검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
tests/unit·integration·component·features·contract·runtime-schema·platform
282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
문제: putIdleTimeoutMs < mutationLockWaitTimeoutMs는 05-07이 기대는
관계다(멈춘 put이 idle 상한에서 origin lock을 놓아야 줄 선 writer가
대기 상한 전에 돈다). 이 관계가 opfs-policy.ts 주석에만 있고, 정책
검사는 각 값의 범위만 본다. 두 값을 뒤집은 정책은 조용히 통과하고,
멈춘 put 하나가 다른 탭의 모든 쓰기를 BLOCKED로 끝낸다.
고른 방법: assertOpfsRuntimePolicy가 putIdleTimeoutMs >=
mutationLockWaitTimeoutMs를 TypeError로 거절한다. 다른 정책 오류와
같은 자리·같은 방식이다. 기본값(2분 < 10분)과 repo 안의 모든 정책은
이미 관계를 지킨다.
위험·한계: 이 관계를 어긴 정책을 쓰던 다운스트림은 조립 때 실패한다.
의도한 동작이다.
검증:
- RED: opfs-worker-runtime.test.ts 새 2건(같음, 김)이 throw 없음으로 실패.
- GREEN: OPFS 단위 3파일 + tests/recipes + tests/contract 174건 통과.
check:types, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-09
문제
test:sample-removal은 참조 기능을 지운 복사본에서 test:unit을 돈다. 그때
product-extension-typecheck 픽스처 기능이 유일한 기능이 되는데, 메시지
catalog가 비어 있어(messages: {}) 메시지 키 타입이 무너져 tsc app이 presentation
파일 수십 곳에서 실패했다. 템플릿 결함이 아니라 픽스처 기능의 모양 문제다.
고른 방법
픽스처 기능에 두 locale의 메시지를 준다. two-feature-install-typecheck 픽스처와
같은 모양이다.
위험·한계
없다고 보는 이유: 테스트 픽스처 문자열만 바뀐다.
검증
- product-extension-typecheck.test.ts 통과(전체 repo).
- test:sample-removal 재실행 결과는 브랜치 보고에 적는다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제
V2를 지울 때(048f490) 같이 지운 테스트 둘이 V3 동작도 지키고 있었다.
- 운영 설정 MAX_RETRY_ATTEMPTS가 실행기에 닿는지. V3는
runtime-adapters.ts에서 넘긴다. 값을 상수 2로 바꾼 변이 H53이 15파일
143건을 통과했다. 장애 때 재시도를 끄는 손잡이가 조용히 사라질 수 있다
(REQUEST_TIMEOUT_MS는 실제로 한 번 그렇게 버려졌다).
- 호출자·scope signal에 단 abort listener를 지우는지. 호출자 쪽 제거를 지운
H56은 머지 게이트 테스트를 모두 통과했고, scope 쪽(H57)은 nightly
tier의 long-session 테스트 하나만 잡았다.
고른 방법
- tests/features/reference-feature/reference-runtime-composition.test.ts:
실제 createRuntimeAdapters에 MAX_RETRY_ATTEMPTS 0·1을 주고, 재시도
예산 2인 참조 목록 조회가 503에 1회·2회 나가는지 센다(Math.random 0으로
backoff 대기 없음). 설치된 기능의 HTTP가 있어야 조립 루트 경로를 탈 수
있어 참조 기능 테스트에 두었다. test:reference-feature는 머지 게이트다.
- tests/unit/http-execution-v3.test.ts: 응답으로 끝날 때와 호출자 abort로
끝날 때, 호출자·scope signal에 더한 abort listener가 같은 함수로 모두
지워지는지 센다.
위험·한계
- ①은 참조 기능에 기댄다. 샘플을 지운 제품에서는 이 테스트도 같이
빠진다. 조립 루트를 기능 없이 부를 수단이 없어서다.
- 10-04 ③(realtime snapshot의 GET 조건)은 다른 작업 몫이다.
검증
- 변이 H53·H56·H57을 하나씩 넣으면 새 테스트가 실패하고, 되돌리면 통과한다.
- 두 파일 76건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-04
문제: 2026-11-01 05-06에서 남은 두 분기를 테스트가 잡지 못한다. 이번
리뷰에서도 두 변이가 Web Storage 관련 테스트 3파일 49건을 통과했다.
- W4: quota 판정 목록에서 Firefox의 NS_ERROR_DOM_QUOTA_REACHED를 빼도
테스트가 통과한다. 빠지면 Firefox의 quota 실패가 memory fallback 없이
STORAGE_UNAVAILABLE이 된다.
- W8: 만료 비교 `<=`를 `<`로 바꿔도 통과한다. 만료 시각과 같은 순간에
값을 돌려준다.
고른 방법: 각 분기에 실패하는 테스트 하나씩. 저장소 test double에
Firefox 이름으로 던지는 모드를 더했고, 만료 경계는 expiresAt 100·101을
now 100에서 읽는다.
위험·한계: 테스트만 바꾼다. codec을 직접 부르는 테스트는 여전히 없다.
검증: W4·W8 변이를 하나씩 넣고 storage-registry·runtime-adapters·
browser-storage-policy 테스트를 돌렸다. 둘 다 새 테스트가 실패했고,
원래 코드에서 storage-registry 26건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 1101/05-06
문제: FILE_BYTE_SOURCE로 이어 올리면 runtime이 서버가 이미 받은 part까지
SHA-256으로 다시 검증한다. 검증(verifyUploadPartBytes)이 수락 확인보다
앞에 있기 때문이다. 8 part 중 6개가 수락된 뒤 이어 올리면 part 해시가
16번 돈다. RANGE_READER 경로는 같은 상황에서 10번이다(manifest 8 + 보낼
part 2).
고친 방법: 스트림 경로에서 수락된 part는 검증 전에 건너뛴다. 보내지 않는
part의 바이트는 검증할 필요가 없다. 파일이 checkpoint와 같은지는 그 앞의
manifest 계산이 이미 확인한다(다른 파일이면 STALE_RESULT). part의
offset·길이 확인은 그대로 모든 part에 한다.
위험·한계: 스트림은 여전히 처음부터 끝까지 읽는다. 읽기를 건너뛰는 것은
스트림 모양상 할 수 없다.
검증:
- 새 테스트(8 part 중 6개 수락 뒤 FILE 재개, part 크기 digest 수): 고치기
전 16, 고친 뒤 10
- 영역 단위 테스트 15파일 275건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 1101/01-02
문제: 이번 리뷰에서도 아래 browser-files 변이가 관련 unit 파일을 모두
통과했다.
- M10(0929/02-05): bounded download의 catch에서 lease?.release()를 지운다.
handoff가 던지면 만든 blob URL이 runtime dispose까지 남는다.
- N27(1101/02-04 ③): 같은 파일을 다시 inspect할 때 이전 receipt를
무효화하지 않는다. 다른 정책으로 검사한 옛 receipt로 preview가 열린다.
- N29(1101/02-04 ①): object URL lease의 합계 바이트 상한을 지운다. 기존
테스트는 개수 상한이 먼저 막아 바이트 상한을 보지 못했다.
- N30(1101/02-04 ⑥): browser-managed handoff의 fragment 거절을 지운다.
고른 방법: 규칙마다 실패하는 테스트 하나. N29는 개수 여유가 있을 때도
바이트가 막는 경우를 기존 상한 테스트 끝에 더했고, N30은 target 규칙
표에 fragment href 한 줄을 더했다.
위험·한계: 테스트만 바꾼다. 1101/02-04의 나머지(N26·N26b는 다음 커밋,
N38 host storageArea, N39 조회 keys() 재확인)는 이 커밋에 없다.
검증: 네 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes를
돌렸다. 모두 새 테스트(또는 늘린 행)가 실패했고 되돌린 뒤 통과. 원래
코드에서 두 파일 47건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-05, 1101/02-04
문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status
QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이
그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true,
RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은
상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다.
고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와
상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음
upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙
줄에 재조정 경우를 더했다.
위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다
status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은
한계다.
검증:
- 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와
같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음,
다음 호출이 정리
- 영역 단위 테스트 15파일 276건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02
문제: 1101/02-04의 두 변이가 이번에도 cache 단위 테스트를 모두
통과했다. N26b는 Cache-Control: no-cache 거절, N26은 Set-Cookie 응답
거절을 지운다. 둘 다 빠지면 사용자별이거나 재검증이 필요한 응답이 익명
공용 캐시에 들어간다. 기존 표는 no-store·pragma·www-authenticate만 따로
보았다.
고른 방법: 응답 검증 표("keeps response validation failure codes")에 두
행을 더한다. 각 행은 규칙 하나만 어긴다.
위험·한계: 테스트만 바꾼다.
검증: 두 변이를 하나씩 넣고 cache 단위 3파일 + tests/recipes를 돌렸다.
둘 다 이 테스트가 실패했고 되돌린 뒤 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
문제
FE-GATE-020의 제거 드릴은 정해진 목록만 fixture에 복사하고, 그 목록에
README.md·CHANGELOG.md·docs/가 없다. 그런데 fixture에서 도는 test:all에는
그 문서를 읽는 테스트 두 개(documentation-readiness,
changelog-review-ids)가 들어 있다. sample-removal 드릴만 두 테스트를
지웠고, browser-file-storage·realtime·optional-recipe 드릴은 제거 대상과
무관하게 `test` 검사에서 ENOENT로 항상 실패했다. 세 드릴의 실패는 merge
게이트를 빨갛게 하고 release 단계도 막는다.
고른 방법
- scripts/lib/removal-fixture.ts에 문서 목록
(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과 그 문서를 읽는 테스트 목록
(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 한 번만 둔다. prepareRemovalFixture는
문서를 복사하지 않은 fixture에서 그 테스트를 지운다. 문서를 복사하는
드릴(test:feature-scaffold)에서는 그대로 돈다.
- sample-removal 드릴의 자체 제외 두 줄을 지운다.
- 버린 대안: 모든 드릴이 문서까지 복사. capability 드릴은 문서가
설명하는 runtime을 지우므로, 문서 테스트가 지운 경로를 실패로 본다.
드릴마다 문서 예외가 필요해진다. 드릴마다 제외를 복사. 지금 고장의
원인(갈라진 목록)을 되풀이한다.
- 단위 테스트가 목록을 고정한다: 문서 없이 복사하면 제외, 문서를
복사하면 제외 없음, 제외 대상이 실제로 문서를 읽음, 다섯 드릴이 모두
prepareRemovalFixture를 쓰고 자체 제외 목록을 두지 않음.
위험·한계
- 저장소 루트 문서를 읽는 테스트가 더 생기면 이 목록에 더해야 한다.
더하지 않으면 capability 드릴이 다시 ENOENT로 실패한다(조용히 통과하지는
않는다).
- 세 드릴의 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- RED: 새 테스트 "is the only exclusion list"가 수정 전 sample 드릴의 자체
목록 때문에 실패.
- tests/unit/removal-fixture.test.ts 12건 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06
문제: 조회는 cache 이름 목록을 pointer보다 먼저 읽는다. 그 사이 다른
탭의 activation이 pointer를 새 캐시로 옮기면 목록에 그 캐시가 없다.
코드는 목록을 한 번 더 읽고서야 STORAGE_EVICTED를 낸다
(1101/02-04 ⑤, N39). 이 재확인을 지워도 테스트가 모두 통과했다. 빠지면
방금 배포한 release의 첫 조회가 "지워졌다"로 끝나고 REHYDRATE로 간다.
고른 방법: 첫 keys()만 배포 전 목록을 돌려주는 저장소로 r2 활성화 뒤
조회한다. adapter는 만들 때 keys를 잡아 두므로 저장소 하위 클래스로
한 번만 낡은 답을 준다.
위험·한계: 테스트만 바꾼다. 1101/02-04의 N38(host storageArea 비교)은
pulse wire 값을 만드는 하네스가 필요해 이번에 하지 않았다.
검증: N39 변이를 넣으면 이 테스트가 STORAGE_EVICTED로 실패하고(cache
단위 3파일 + tests/recipes 71건 중 1건), 되돌리면 같은 파일 14건 통과.
check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.
고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
verify:documentation, check:i18n, check:design-system을 돈다
(FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
(c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.
위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
documentation-readiness 14건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제: client-cache-and-storage.md의 cross-context 조립 설명이
runtime-adapters.ts·server-state-scope-runtime.ts·tanstack-cache-
coordinator.ts의 줄 번호를 가리키는데, 네 곳 모두 다른 코드로 밀렸다
(0929/02-04). 문서 줄 번호를 보는 검사는 없어서 다음 변경에도 또 밀린다.
browser-file-and-origin-storage.md의 participant 등록 예 줄 번호는 앞
커밋(02-01)이 이미 고쳤다.
고른 방법: 줄 번호 대신 함수·호출 이름을 적는다(1101/05-05와 같은
방식). 리뷰가 맞다고 확인한 다른 줄 번호는 그대로 둔다.
위험·한계: 문서만 바꾼다. 다른 문서의 줄 번호 참조는 건드리지 않았다.
검증: verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-04
문제
짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 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
문제
tests/system/ci-runner/ci-artifact-contract.test.ts는 provider 묶음에 30초
예산(PROCESS_HEAVY_TIMEOUT_MS)을 두고 "10s default is sized for pure-JS
unit tests"라고 적는다. 그런데 같은 describe의 테스트 선언 8개(케이스
10개)는 여전히 10초다. 그래서 바쁜 호스트에서 "kills descendants … timeout
termination"이 10,116 ms로 시간 초과해 FE-GATE-013이 가끔 빨개진다. 또 기반
fixture(build:release-candidate)를 처음 createProviderFixture()를 부른 테스트
안에서 만들어서, -t로 하나만 골라 돌리면 그 테스트가 빌드를 떠안아 항상
실패한다.
고른 방법
- describe 옵션으로 묶음 전체에 PROCESS_HEAVY_TIMEOUT_MS를 주고, 테스트마다
적은 10_000·15_000·20_000·30_000을 지운다. 40_000을 준 tar 폭탄 테스트
하나는 그대로 둔다.
- 기반 fixture는 describe의 beforeAll에서 만든다. 상한은 빌드의 spawn
상한(120초)에 복사·압축 여유를 더한 180초다.
- 버린 대안: 전역 testTimeout 올리기. 파일 주석이 이미 버렸다(진짜 멈춘
테스트를 숨긴다). 테스트마다 상수로 바꾸기. 상수를 안 쓰는 테스트가 다시
생길 수 있다.
위험·한계
- 실제로 멈춘 provider 테스트는 실패까지 최대 30초 걸린다.
- runProviderSupervisor의 spawn 상한(기본 8초)은 바꾸지 않았다. 부하에서
systemd user manager가 느리면 "provider unit remained loaded"로 따로
실패할 수 있다(이번 실행에서 load 24일 때 한 번 봄, 운영 코드의 상한).
- loadavg 20 이상에서 test:system 전체 5회 반복은 하지 않았다.
검증
- -t "kills descendants|hides repository metadata"로 골라 돌렸을 때 두
kills descendants 테스트가 통과(3.0 s, 2.9 s). 기반 빌드는 beforeAll이
떠안았다.
- eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-03
문제
매뉴얼 01은 "필요하면 mapProblem을 둔다(예: 409, 422를 업무 실패로)"라고만
적는다. Envelope operation에서 mapProblem은 kind·code·필드 오류만 바꾸고
적용 여부는 바꾸지 못한다. 이 안내만 따르면 필드 오류는 보이지만 저장
버튼은 꺼진 채로 남는다(리뷰 08-01 P1의 mapProblem 행). 1e8b3d0이 더한
refusedBeforeWrite는 매뉴얼 02 4절에만 있다.
고른 방법
Envelope 실패 흐름 목록과 "정할 것"의 mapProblem 줄에 한 문장씩 더해
refusedBeforeWrite와 02 결정표 4절을 가리킨다. 5xx 판정 문장도 지금 표에
맞췄다.
위험·한계
문서만 바꿨다.
검증
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
문제
scripts/run-and-validate-provider.ts는 작업 폴더에 .git이 있으면 그 자리에
--tmpfs를 건다. git worktree나 서브모듈 checkout에서는 .git이 디렉터리가
아니라 "gitdir:" 한 줄짜리 파일이라 bubblewrap이 "Can't mkdir …/.git: Not a
directory"로 끝난다. 그래서 worktree에서 test:system을 돌리면 사전 점검은
PASS인데 provider 테스트 16개가 샌드박스 회귀처럼 실패한다. 또 provider 기반
fixture는 현재 폴더를 통째로 복사해, checkout 안의 .claude/worktrees/*나
.tmp/* 같은 다른 checkout·드릴 fixture와 그 node_modules까지
/tmp/ci-provider-upload-*에 복사했다(시간 초과, ENOTEMPTY).
고른 방법
- .git이 디렉터리면 지금처럼 tmpfs로 가린다. 디렉터리가 아니면 /dev/null을
--ro-bind로 겹친다. bubblewrap은 bind를 nodev로 걸어서 provider는 그 줄을
읽지도 그 경로에 쓰지도 못한다. 파일이 가리키는 실제 git 디렉터리는 작업
폴더 밖이라 원래 샌드박스에 들어오지 않는다.
- 리뷰 최소 개선 (1)(사전 점검이 worktree를 거부) 대신 (2)를 골랐다. 이
repo의 리뷰·수정 절차가 영역마다 worktree를 쓰므로, worktree에서
샌드박스 경계 테스트를 돌릴 수 있어야 한다. 비용도 몇 줄로 비슷하다.
- 기반 fixture 복사에서 .claude, .worktrees, .tmp, graphify-out을 뺀다. 모두
추적하지 않는 폴더라 후보의 추적 파일 목록에는 영향이 없다.
- 새 system 테스트 2건이 .git이 디렉터리일 때와 파일일 때 provider가 그
내용을 보지도 바꾸지도 못함을 확인한다.
- 버린 대안: --dev-bind /dev/null. 읽으면 빈 내용이지만 쓰기를 받는다.
--remount-ro를 더하면 nodev가 다시 걸려 --ro-bind와 같아진다. 빈 일반 파일을
호스트에 만들어 bind. 임시 파일의 수명·정리 경로가 하나 는다.
위험·한계
- .git 파일 자리에서 provider는 빈 파일이 아니라 열 수 없는 문자 장치를
본다(EACCES). 작업 폴더를 훑는 provider가 그 오류를 실패로 다루면 거기서
드러난다.
- 마스크를 지우는 변이 확인은 부하(load 24) 때문에 systemd unit 수거가 늦어
결론을 내지 못했다(두 경우 모두 "provider unit remained loaded").
검증
- RED: worktree에서 test:system 16 failed / 96 passed(모두 provider 묶음,
같은 bwrap 오류). 새 테스트는 수정 전 "file" 경우만 실패.
- 수정 뒤 새 테스트 2건 통과(-t "hides repository metadata").
- eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-04
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드
레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를
지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다.
src 전체에 multipart 요청을 만드는 코드가 없다.
고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에
createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다.
- 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한
번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼
인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지
않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기
전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼
하나에 바로 쓴다.
- 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이
정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다.
redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한
deadline 하나, 호출자 abort(커널 createAbortableOperation).
- 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의
state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH,
APPLIED_CONFIRMED.
- 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을
그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous,
AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은
MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가
모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver
code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패·
시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본
30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙).
- Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다.
위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격
증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안
import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http
파일은 index.ts의 export 한 묶음뿐이다.
버린 대안:
- backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를
browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고,
커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다.
file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned
레시피와 무관한데 그 제거 드릴에 함께 지워진다.
- browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다.
- V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과
동시에 크게 고쳐야 한다.
- FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint),
기능은 Blob을 갖지 않는다.
조립: 제품이 product-composition.ts에서 client 재료
(FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가
createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지
않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피
fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을
더했다(번호는 끝에 141로 붙였다).
위험·한계:
- 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus
client는 없다.
- 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다
(NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개
생길 수 있다. 매뉴얼에 적었다.
- 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드
bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류).
- 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는
MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다.
- 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로,
템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential
provider를 써야 한다.
검증:
- tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문,
Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖
Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort,
자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData
파서로 다시 읽어 확인했다.
- 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락,
201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다.
- check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory,
verify:documentation, check:registries, check:ci 통과
- check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물
어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS
(file-transfer 56,082 / 57,800)
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
문제
tests/fixtures/architecture/forbidden/**에는 fixture 전용 ESLint 블록이
붙어 있었다. 모든 계층의 금지 import와 fetch·localStorage·sessionStorage
금지를 합친 것이다. check-architecture.ts는 fixture마다 ESLint 종료 코드가
0이 아니면 거부됐다고 셌다. 그래서 운영 src/presentation/** 블록에서 계층
import 금지와 fetch 금지를 지워도(변이 M2) check:architecture는 "9 forbidden
rejected"로 통과했다. 전역 fetch·localStorage 금지는 이 ESLint 블록 말고 지키는
검사가 없다.
고른 방법
- 새 scripts/lib/architecture-lint-fixtures.ts가 fixture마다 그것이 대표하는
운영 경로(lintAs, 예: src/presentation/__architecture_fixture__/…)와 거부해야
하는 규칙(rejectedBy)을 적는다. ESLint API lintText(code, { filePath })로
그 경로의 운영 설정을 그대로 적용한다. 금지 fixture는 그 규칙이 보고해야
통과하고, 허용 fixture는 계층 규칙(no-restricted-imports·globals)이 아무것도
보고하지 않아야 통과한다. 목록에 없는 fixture 파일도 실패로 센다.
- domain fixture는 domain 코드가 실제로 사는 src/features/*/domain 블록으로
검사한다(최상위 src/domain 폴더는 없다).
- fixture 전용 ESLint 블록을 지운다. check-architecture.ts에서 쓰이지 않게 된
pnpm 하위 프로세스 실행과 npm_execpath 요구를 지운다.
- 버린 대안: 금지 fixture 삭제. import 방향은 그래프가 지키지만 전역 금지의
검출이 0이 된다. 종료 코드만 보고 운영 경로로 옮기기. 다른 규칙(화면 문구
등)이 걸려도 거부로 센다.
위험·한계
- 계층 규칙 이름이 바뀌면 fixture 표의 rejectedBy도 같이 고쳐야 한다(고치지
않으면 실패로 드러난다).
- 출력 문구가 "3 allowed PASS, 9 forbidden rejected by the production rule for
their layer"로 바뀐다. 이 문구를 읽는 스크립트는 없다.
검증
- RED: 수정 전 변이 M2(운영 presentation 블록의 계층 import 금지와 fetch 금지
삭제)에서 check:architecture exit 0, "9 forbidden rejected".
- 수정 뒤 같은 변이에서 check:architecture exit 1, presentation fixture 5개가
"was accepted"로 실패. 되돌린 뒤 exit 0.
- 새 tests/unit/architecture-lint-fixtures.test.ts 3건(운영 설정 통과,
overrideConfig로 규칙을 끄면 실패, 목록 밖 fixture 실패) 통과.
architecture-report 3건 통과. check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-04
문제
verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서
`corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의
명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장
docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께
지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도
알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger
사유는 "It passes at this commit"이라는 시점 문장을 담았다.
고른 방법
- 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서
명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash,
sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고,
--flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로
경로로 보지 않는다.
- 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick
경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이
있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not
verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다.
보고서 schema에 그 칸을 더했다.
- 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고,
ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을
고쳤다.
- 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고
오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛
경로를 적어 예외가 늘어난다.
위험·한계
- 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다.
- 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이
있는 개발 환경에서만 된다.
- 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다.
검증
- RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소
없음 보고) 실패.
- 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가
"names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation
PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified).
check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel
(src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만
적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After,
JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent
factory까지 10개 파일이 있다. 편입 기준("must never own")은
indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지
문서로는 알 수 없다.
고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유
메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를
가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음).
위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을
넣을지를 기계가 보지 않는 것은 그대로다.
검증: check:architecture, verify:documentation 통과. bootstrap 밖에서
lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-08
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).
고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.
위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.
검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
문제
create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고
적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다.
그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가
88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서
생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이
실제로 그렇게 생겼다). 또 제품 기능 제거 드릴
(test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유
결함(16-02)이 드러나지 않았다.
고른 방법
- 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json
merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은
run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다.
- 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다:
브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix
browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한
provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다),
제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는
스크립트를 제외 목록에 두면 실패한다.
- 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로
다시 지운다(16-02 둘째 절반).
- 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다.
- 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본
에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십
분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을
고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다.
그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다.
위험·한계
- 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번).
FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다.
tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다.
- 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기).
검증
- RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what
test:feature-scaffold runs"가 수정 전 실패.
- 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성
fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부,
드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과.
verify:documentation PASS_SCOPED, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
문제
decideRouteAccess의 recovery-pending 분기(wait-for-session)를 어떤 테스트도
보지 않았다. 지난 리뷰 변이 L02(wait-for-session을 show-sign-in으로)가 18파일
105개 테스트를 통과했다. 그러면 세션을 복구하는 중인 사용자가 들어갈 수 있는
페이지에서 로그인 화면으로 튕긴다.
고른 방법
- tests/unit/navigation-policy.test.ts에 보호 라우트 하나로 recovery-pending은
wait-for-session, authenticated는 허용임을 단언한다.
위험·한계
- 화면(route-status-surfaces) 수준의 대기 표시는 따로 고정하지 않았다.
검증
- 새 테스트 통과. 변이 L02를 넣으면 새 테스트만 실패한다(되돌림).
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 1101/10-03
문제
tests/component/boot-unexpected-failure.test.tsx는 vi.stubGlobal로
reportError를 바꾸고 되돌리지 않는다. 설정에 unstubGlobals가 없어서 그 stub이
같은 파일의 다음 테스트에 남는다.
고른 방법
- 이 파일에 afterEach(vi.unstubAllGlobals)를 둔다. 전역 설정
(unstubGlobals: true)은 다른 파일의 동작까지 바꾸므로 고르지 않았다.
검증
- 파일 2건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md (2절 boot-unexpected-failure stubGlobal)
문제
tests/unit/runbook-drill.test.ts의 "상수 판정 금지" 검사는 옛 모양
(assertion(..., true), Asserted: true)만 찾는다. drill은 이제
verdict()로 "PASS"/"FAIL" 문자열을 쓴다. 지난 리뷰 변이(:238의
verdict(await builtAssetsPresent(...))를 상수 "PASS"로)가 이 검사를
통과했다.
고른 방법
- assertion(..., "PASS"), *Asserted / *AsExpected: "PASS", verdict(true)
모양을 더 찾는다. 옛 정규식 셋은 그대로 둔다.
위험·한계
- 문자열을 변수에 담아 넘기는 우회는 이 정적 검사가 못 본다. 그 경우는
동작 테스트(FE-RB-002 등)가 본다.
검증
- 검사 통과. 리뷰의 변이를 다시 넣으면 이 검사가 실패한다(되돌림).
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 0929/11-08
문제
tests/browser-capabilities/resumable-upload.spec.ts가 CORS 응답의 origin을
"http://127.0.0.1:4174"로 따로 적는다. playwright.capabilities.config.ts의
baseURL과 지금은 같아서 동작하지만, 설정의 포트를 바꾸면 이 spec만 CORS로
조용히 깨진다.
고른 방법
- 설정 파일을 import해 use.baseURL의 origin을 쓴다. test.info()는 route
처리기 안에서 부를 수 있는지가 Playwright 내부 맥락에 달려 고르지 않았다.
검증
- check:types(tsconfig.test.json) 통과, eslint 통과. 브라우저 실행 결과는
이 커밋 메시지에 적지 않았다(공유 잠금 대기).
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md (2절 FOLLOW-UP resumable-upload 포트)
문제
capability 제거 드릴의 fixture도 test:unit을 돈다. 앞 커밋들이 더한 가드
테스트 두 개가 그 안에서 실패했다.
- removal-fixture.test.ts: 문서 테스트 파일과 드릴 스크립트를 이름으로 읽는데,
fixture는 문서 테스트를 지우고(02-06) 드릴은 자기 스크립트를 지운다.
browser-file-storage·realtime 드릴이 이 두 건으로 `test` 검사에서 실패했다.
- feature-scaffold-drill: 제거 드릴이 자기 capability 명령을 계약에서 빼면,
scaffold 드릴 제외 목록의 그 스크립트가 "merge 단계에 없음"으로 실패한다.
고른 방법
- 문서 테스트는 "문서가 있는 곳에만 있다"를 단언한다(저장소: 둘 다 있음,
capability fixture: 둘 다 없음).
- 드릴 목록은 scripts/test-*.ts 중 removal-fixture.ts를 import하는 파일로 찾고,
sample·scaffold 드릴이 그 안에 있는지 확인한다.
- 제외 목록이 낡았다는 판정은 계약에 있으나 merge 단계 밖인 명령에만 한다.
계약에서 아예 빠진 명령(제거 드릴이 정리한 capability)은 낡은 것이 아니다.
위험·한계
- 계약에서 지운 스크립트의 제외 항목이 저장소에 남아도 이 검사는 알리지
않는다. 남아도 아무 명령을 숨기지 않는다.
검증
- 수정 전 snapshot(0edc3fc)에서 test:browser-file-storage-removal,
test:realtime-removal 모두 이 두 테스트로 exit 1(ENOENT).
- 수정 뒤 removal-fixture·feature-scaffold-drill 18건 통과, eslint·tsc 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
문제
c4d5870 뒤 test:sample-removal이 문서를 복사하고 verify:documentation과 문서
테스트를 돌린다. 실제 드릴 실행(snapshot 0edc3fc)에서 두 가지로 실패했다.
- 드릴은 fixture에서만 tests/unit/ci-workflow-generation.test.ts와
tests/unit/removal-fixture.test.ts를 지운다(전체 저장소를 고정하는 테스트라).
docs/operations/adapter-remediation-ledger.md가 그 두 파일을 백틱 경로로 적어,
fixture의 문서 검사와 문서 테스트 7건이 실패했다. 샘플을 지운 실제 프로젝트는
그 테스트를 지우지 않으므로 이 실패는 fixture에만 있다.
- 잔여 검사가 tests/unit/documentation-readiness.test.ts의 정규식
REFERENCE_RESOURCE_[A-Z]+를 샘플 흔적으로 잡았다. 그 파일은 예전에는 fixture
에서 지워져 검사되지 않았다.
고른 방법
- 원장(기록 문서)의 그 세 곳을 백틱 없는 경로로 바꾼다. 드릴의 fixture 전용
삭제 목록 옆에 "현재 계약 문서는 이 파일들을 백틱 경로로 적지 않는다"를
적었다.
- 정규식을 [A-Z]+_RESOURCE_[A-Z]+로 쓴다. 라우트 ID를 지우는 용도는 같다.
- 버린 대안: 문서 검사에 fixture 전용 예외 경로를 넘기는 환경 변수. 운영
스크립트에 테스트용 입력이 생긴다. fixture 전용 삭제를 그만두기.
ci-workflow-generation 스냅샷은 줄어든 CI 계약과 맞지 않는다.
위험·한계
- 앞으로 현재 계약 문서가 그 두 테스트를 백틱으로 적으면 sample 드릴이 다시
문서 검사에서 실패한다. 실패 메시지가 파일과 경로를 적는다.
검증
- 수정 전 snapshot 0edc3fc의 test:sample-removal exit 1: documentation,
unit-integration, coverage, fixture-id-residue와 scaffold- 세 검사가 이 두
원인으로 실패. lint·check:i18n·check:design-system 등 나머지는 통과.
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지운 복사본(sim-sample-docs.sh)에서
verify:documentation PASS_SCOPED. 저장소에서 documentation-readiness 19건
통과, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
fix/r1103-session의 session-owners-runtime 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)은 템플릿 테스트가 제품 설정
키의 기본값을 받도록 testRuntimeConfig로 설정을 만들게 했고, 복사본에
제품 키를 넣은 뒤 tsc test 프로그램을 도는 테스트를 더했다. 두 브랜치를
합치자 그 테스트가 session-owners-runtime.test.ts:161에서 TS2322로
실패한다.
고른 방법
- 이 테스트도 tests/helpers/runtime-config.ts의 testRuntimeConfig로
설정을 만든다. 다른 템플릿 테스트와 같은 방식이다.
위험·한계
- 동작 변경은 없다. 테스트 입력 모양만 바뀐다.
검증
- tests/unit/product-extension-typecheck.test.ts 통과.
- tests/recipes/session-owners-runtime.test.ts 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02 09-03
문제
fix/r1103-storage가 더한 browser-file-session-capability·
runtime-adapters-product-scope-participants 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)의 제품 확장 타입 검사
테스트가 이 두 파일에서 TS2322로 실패한다(9b9d62a와 같은 원인).
고른 방법
- 두 테스트도 testRuntimeConfig로 설정을 만든다.
위험·한계
- 동작 변경은 없다.
검증
- tests/unit/product-extension-typecheck.test.ts, 두 테스트, test:recipes,
lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제: README 빌드 변수 표는 VITE_BUILD_ID 기본값을 local-build로만
적었다. staging·production 빌드는 이 값이 없으면 멈추는데
(scripts/generate-runtime-config.ts, src/contracts/env.ts 주석), 그 조건이
표에 없었다(0929/13-09, 세 라운드 남음).
고른 방법: 표의 기본값 칸에 local·development는 local-build, staging·
production은 없으면 빌드 실패라고 적는다.
위험·한계: 문서만 바꾼다.
검증: verify:documentation PASS_SCOPED(이 표를 읽는 검사 포함).
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-09
문제
test:sample-removal은 참조 기능을 지울 때 그 전용 script
test:reference-feature도 package.json에서 지운다. 샘플을 지운 프로젝트도
같다. 그런데 docs/testing/taxonomy.md와 원장 두 행이 그 script를 백틱·명령
형태로 적어, 문서 검사가 "names package scripts that do not exist:
test:reference-feature"로 실패했다(b6bfc9b snapshot의 드릴 실행).
고른 방법
- 참조 기능 경로와 같은 규칙(patterns.md 첫머리): 참조 기능이 가진 script는
백틱이나 `corepack pnpm` 없이 적고 "참조 기능과 함께 지워진다"를 붙인다.
위험·한계
- 템플릿에서도 문서 검사가 이 script 이름의 존재를 보지 않는다.
검증
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지우고 test:reference-feature를
package.json에서 뺀 복사본(sim-sample-docs.sh)에서 verify:documentation
PASS_SCOPED. 저장소에서도 PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
e1b4e28 뒤 test:feature-scaffold는 merge 단계 명령을 모두 돈다. 실제 실행
(snapshot b6bfc9b, CI env 없음)에서 검사 75개 중 FE-GATE-013의 두 개만
실패했다. build:release-candidate가 build의 commitSha를 source.revision으로
기록하는데, VITE_COMMIT_SHA가 없으면 commitSha가 "local"이라 schema(40·64자리
16진수)가 거부한다. verify:local-evidence는 그 결과를 읽어 따라 실패했다.
CI workflow는 VITE_COMMIT_SHA를 전체 env로 주므로 CI에서는 나지 않는다.
고른 방법
- VITE_COMMIT_SHA가 비었을 때만 드릴이 fixture의 봉인 commit(git rev-parse
HEAD)을 넣는다. CI 값은 그대로 둔다. test:system의 provider fixture도 같은
방법으로 commit을 준다.
- 버린 대안: build:release-candidate·verify:local-evidence를 제외 목록에
넣기. 생성 기능 파일이 후보의 추적 파일 목록과 공급망 증거에 들어가는지를
보지 못한다.
위험·한계
- 로컬 실행에서 빌드 산출물의 commitSha가 "local" 대신 fixture commit이 된다.
fixture 안에서만이다.
검증
- 수정 전 드릴 실행: create-feature, merge 명령 73개(음성 fixture 포함),
feature-removal 통과. 실패는 위 두 개뿐(866초, load 10~25).
- 수정 뒤 eslint·tsc 통과, feature-scaffold-drill 6건 통과. 드릴 재실행 결과는
이 커밋 메시지에 적지 않았다(공유 잠금).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
문제: pnpm 11은 설치 정책을 pnpm-workspace.yaml에서 읽는다(13-09가
.npmrc에서 옮겼다). engineStrict·saveExact가 빠지거나 minimumReleaseAge를
기본값(1440분)보다 짧게 줄여도 실패하는 검사가 없었다(0929/13-08, 세
라운드 남음). 지원하지 않는 Node로 설치되거나, 새 의존성이 ^ 범위로
저장되거나, 방금 나온 버전이 설치될 수 있다.
고른 방법: unit 테스트가 pnpm-workspace.yaml의 engineStrict: true,
saveExact: true를 확인하고, minimumReleaseAge를 적었다면 1440 이상인지
본다. minimumReleaseAgeExclude 항목은 정확한 버전만 허용한다.
버린 대안: `pnpm config get`을 부르는 테스트. 자식 프로세스 비용이 들고
같은 파일을 읽는다.
위험·한계: 파일 텍스트를 정규식으로 읽는다. 키를 다른 YAML 형식(인라인
맵 등)으로 바꾸면 테스트가 실패하므로 놓치는 쪽으로는 틀리지 않는다.
검증: 2건 통과. saveExact: false와 minimumReleaseAge: 60으로 바꾸면
실패하고 되돌리면 통과한다.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-08
문제
fix/r1103-contracts는 fix/r1103-http가 아직 없을 때
CommandEffectDescriptor에 없는 refusedBeforeWrite를 구조 캐스트로
읽었다. 두 브랜치를 합치자 그 칸이 타입에 생겼다. 또 행 투영 테스트가
Envelope가 아닌 operation에 refusedBeforeWrite를 적는데, http 쪽 조립
검사(1103/03-01)는 그것을 거절해 테스트가 ContractContributionError로
실패한다.
고른 방법
- api-operations.ts는 effect.refusedBeforeWrite를 타입으로 읽는다.
- 테스트의 create descriptor에 responseEnvelope ENVELOPE_V1을 주고,
code를 업무 거절 모양(TEST_ENTITY_INVALID 등)으로 바꾼다.
위험·한계
- 행 모양은 그대로다. 기준선 영향 없음.
검증
- tests/unit/api-operation-rows.test.ts 12건, test:unit 2,790건,
check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
fix/r1103-transfer의 Fileserver 업로드 client는 실패 kind를 공유 Envelope
판정(envelopeFailureReading)에서 받고 413·415만 VALIDATION_REJECTED로
바꾼다. fix/r1103-http(1103/08-05)는 필드 목록 없는 422를
UNKNOWN_CLIENT_FAILURE로 읽게 했다. 두 브랜치를 합치자 Fileserver의
422(digest·서명·검사기 거절, 예: MALWARE_DETECTED)가 입력 거절이 아니게
되어 통합 테스트 2건이 실패한다.
고른 방법
- Fileserver 계약에서 422는 파일 자체의 거절이다(백엔드
docs/fileserver/http-contract.md 상태 표). 사용자가 파일을 바꿔야 하는
413·415와 같이 VALIDATION_REJECTED로 둔다.
- 422 IDEMPOTENT_REQUEST_MISMATCH(같은 키, 다른 본문)는 파일 문제가
아니므로 08-05의 공통 판정(UNKNOWN_CLIENT_FAILURE)을 따른다. 테스트
기대값도 그렇게 바꿨다.
- 버린 대안: 공통 판정을 422 전체 입력 거절로 되돌리기. 08-05가 고친
결함(같은 키 불일치를 입력 오류로 보임)이 다시 생긴다.
위험·한계
- 422 code 목록을 파일 거절로 고정하지 않고 "불일치가 아니면 파일 거절"로
본다. 백엔드가 파일 업로드에 다른 뜻의 422를 더하면 다시 본다.
검증
- test:integration 189건(fileserver-upload 48건 포함), check:types,
lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, 08-presentation.md 08-05
문제
fb20699의 새 테스트는 보호 라우트 하나를 찾아 단언하고, 없으면 실패한다.
참조 기능을 지운 제거 fixture에는 보호 라우트가 없어서, test:sample-removal
(snapshot fd11d08)의 test:all과 test:coverage가 이 테스트 하나로 실패했다.
고른 방법
- 같은 파일의 "every non-public route" 반복 안에서 recovery-pending과
authenticated를 함께 단언한다. 라우트가 있는 템플릿에서는 같은 변이를 잡고,
보호 라우트가 없는 구성에서는 다른 단언처럼 대상이 없다.
검증
- 파일 4건 통과. 변이 L02(wait-for-session → show-sign-in)를 넣으면 그 반복
테스트가 실패한다(되돌림). eslint 통과.
- snapshot fd11d08의 test:sample-removal: 이 테스트 말고 실패한 검사가
없었다(documentation·lint·i18n·design-system 포함).
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 1101/10-03
문제
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
문제
docs/README.md는 목표 설계 문서의 기능이 지금 동작하는지 문서 안의
상태 값으로 확인하라고 한다. 그런데 2026-11-03에 지운 V2 구성요소가
여전히 COMPOSED다(VD-23 머리, VD-24 머리, api-contract-schema-mapper
원장 세 행). VD-23은 "401 recovery는 replay-safe operation만 한 번
수행한다"를 적는데, 정본 8.4(FRT-D016)와 코드는 숨은 refresh-and-replay를
하지 않는다. 코드 주석 다섯 곳이 이 VD-23을 근거로 가리킨다. 지금 실행
규칙인 6.1절(쓰기 전 거절 표)은 "backend implementation pending"인 목표
설계 문서에 있어 verify:documentation 검사 밖이다.
고른 방법
- VD-23: 정본 우선 안내를 붙이고, V2 baseline을 REMOVED(048f490·12f3bb7)로,
V3 contract executor를 COMPOSED로 적는다. 401 문장을 정본 8.4 문장으로
바꾸고, 2절 defineRestOperation 앞에 삭제 안내를 둔다.
- VD-24 머리와 api-contract-schema-mapper 원장의 V2 행을 REMOVED로, shared
executor 행을 V3 실행기 설명으로 바꾼다.
- backend-api-and-server-state-contract.md 상태 줄에 4.1·6·6.1절은 지금
실행 규칙이라고 적고, docs/README.md 1절에서 그 절을 링크한다. 그 결과
이 문서도 경로 검사를 받으므로, 백엔드 repo 경로 7곳에
clean-architecture-backend-template/ 접두어를 붙였다.
- 버린 대안: 6.1절을 docs/contracts/로 옮기기. 백엔드 pin·답 표 JSON·
backend-envelope.ts 주석이 이 절을 가리켜 같이 고쳐야 할 곳이 늘어난다.
위험·한계
- 원장 행의 나머지 문장과 VD-23 본문에는 V2 시기 서술이 남아 있다.
상태 값과 401 규칙만 맞췄고, 남은 서술은 "V2 기록"이라고 표시했다.
검증
- git grep "401 recovery는 auth-required" -- docs/architecture: 0건.
- verify:documentation PASS_SCOPED, documentation-readiness·
changelog-review-ids 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-03, 03-adapters-http-state.md 03-06
문제
starter-experience.md의 제품 소유 파일 표는 제품 런타임 설정 키의
FE-REG-ENV 행에 대해 "nothing requires the row"라고 적는다.
tests/unit/env-registry-coverage.test.ts(d0414c8)는 키마다 행을 요구하고,
fix/r1103-contracts(13-04)는 그 행의 required·defaultValue까지 스키마와
대조하게 했다. 매뉴얼 03 C절은 이 표를 정본으로 가리킨다.
고른 방법
- 그 셀을 "check:registries가 칸을 보고, env-registry-coverage 테스트
(test:unit)가 키마다 행과 required·defaultValue를 요구한다"로 바꾼다.
- 같은 표의 사라진 오류 문구(14-05 ①)는 fix/r1103-app(09-07)이 이미
고쳤다.
위험·한계
- 없음. 문서 한 셀이다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-05
문제: pnpm audit(2026-11-04) 결과 advisory 44건(critical 1, high 16)이
있었고, 템플릿 자신의 취약점 정책(high 이상 차단, 예외 0건)을 어겼다.
대부분 개발 의존성이다: storybook 10.5.4(critical, dev 서버 코드 주입),
vite 8.1.5, vitest 4.1.10, 그리고 jsdom 경유 undici 7.28.0,
brace-expansion 5.0.8, nanoid 3.3.16, source-map-js 1.2.1.
고른 방법: 고친 버전이 있는 가장 가까운 줄로 올린다. vite 8.1.6(같은
8.1 줄), vitest·@vitest/coverage-v8 4.1.12(같은 4.1 줄), storybook
3종 10.6.5. 전이 의존성은 `pnpm update --depth Infinity`로 선언된 범위
안에서만 올렸다(undici 7.30.1, brace-expansion 5.0.12, nanoid 3.3.20,
source-map-js 1.2.2, postcss 8.5.23). 의존성 기준선을
update:dependency-baseline으로 다시 승인했다.
버린 대안: 운영 의존성 zod 4.6.7·react-router-dom 7.18.5도 함께 올리기.
직접 운영 의존성 변경은 dependency-change-evidence.json에 owner와 다른
reviewer가 필요해 기준선 생성이 거절했다(add:zod@4.6.7,
add:react-router-dom@7.18.5). 또 zod 4.6.7은 초기 JS를 약 7 KB 늘려
예산(204,800 B)을 넘긴다(측정 208,444 B). 그래서 이 커밋에 넣지 않고
다음 커밋에서 남은 위반으로 기록한다.
위험·한계: 남은 high 2건은 운영 의존성(zod GHSA-mrhx-c7xc-m3w5,
react-router GHSA-qwww-vcr4-c8h2)이다. 남은 moderate 2건(minimatch,
glob)은 고친 버전이 선언된 major 범위 밖이라 올리지 않았다. 의존성 수
561 → 562.
검증: pnpm audit → high 2(운영), moderate 2, critical 0. 이 상태에서
test:component 263, test:integration 117, build:storybook 성공,
check:bundle PASS(200,939 B, 25개), feature-shape-growth·supply-chain·
build-environment-bundle 39건 통과. 운영 의존성까지 올린 상태의
test:unit은 2,611건 통과였다(전체 test:unit은 브랜치 끝에서 다시 돌린다).
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제: 의존성 취약점 판정은 운영 승격의 외부 provider에만 있었다. 로컬
supply chain은 스캔하지 않고 provider: UNCONFIGURED를 썼다. 그래서
lockfile이 템플릿 자신의 정책(high 이상 차단, 예외 0건)을 어겨도 merge·
release 단계에서는 아무 신호가 없었고, provider가 없는 복사본은 끝까지
몰랐다. 갱신 자동화도 없었다(짝 백엔드에는 renovate.json이 있다).
고른 방법:
- scan:dependency-advisories(scripts/scan-dependency-advisories.ts)가
pnpm audit --json에 config/security/vulnerability-policy.json과
예외 파일을 적용한다. 판정은 승격이 쓰는 validateVulnerabilityReport를
그대로 쓴다. 결과는 PASS / POLICY_VIOLATION(승격에서 막힐 항목 목록) /
UNVERIFIED(레지스트리에 닿지 못함)이고, 운영·개발 의존성별 개수와 함께
gate 로그와 artifacts/security/dependency-advisories.json에 남는다.
- FE-GATE-027(release-admission, release 단계, 후보 빌드 직후)이 이 명령을
두 번째로 돈다. 명령은 항상 exit 0이다.
- renovate.json을 둔다(보안 업데이트만, 사람이 리뷰·merge).
- 남은 운영 의존성 위반 2건과 올리지 않은 이유, 다시 볼 날짜
(2026-12-04)를 ci-quality-gates.md에 적는다.
버린 대안: merge 차단 audit(코드가 안 바뀌어도 advisory DB 변경으로
merge가 깨진다), 로컬 스캐너를 provider로 내장(서명 주체 분리라는 원래
목적이 사라진다), 새 evidence 산출물·스키마 등록(계약 변경이 커진다.
gate 로그가 이미 release 단계 산출물이다).
위험·한계: 비차단이라 신호를 읽는 사람이 있어야 한다. 네트워크가 없는
runner에서는 UNVERIFIED로 남는다. Renovate runner는 붙어 있지 않아
renovate.json은 아직 동작하지 않는다. 남은 zod·react-router high 2건은
dependency-change-evidence의 reviewer(owner와 다른 사람)와 zod의 번들
예산 결정이 있어야 고칠 수 있다. 계약 기준선(contract-baseline.json)을
명령 100개·참조 104개로 다시 기록했다.
검증: dependency-advisories.test.ts 5건(정책 위반 판정, PASS, 유효한
예외, 보고서 없음 → UNVERIFIED, FE-GATE-027 배선과 exit 0). 상태 판정을
PASS로 고정하는 변이를 넣으면 실패한다. 실제 실행: POLICY_VIOLATION
(운영 high 2, 개발 moderate 2), exit 0. 죽은 프록시로 돌리면 UNVERIFIED,
exit 0. check:ci PASS, CI workflow bytes PASS, ci-workflow-generation·
product-ci-overlay·ungated-scripts·removal-fixture·supply-chain 489건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제
responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을
손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를
거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의
선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로
깨진다(리뷰 E-1).
고른 방법
계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이
없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서
그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다.
거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와
check:registries가 실패한다.
버린 대안
- responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor
약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입
변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다.
- 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다.
위험·한계
- 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트
(백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다.
- 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는
테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다.
검증
- RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과.
- tests/unit·integration·contract·component·features·runtime-schema·platform·
architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).
고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
이유), hover 프리페치(키보드·직접 진입에 효과 작음).
위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.
검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
feature-runtime·reference-schemas는 제목 뒤에 받는다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.
고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
접근성 spec 생성(파일·실행 시간 증가).
위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
"passed"로 적힌다.
검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.
고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
실패를 낸다.
- 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
빠진다.
- 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
골든을 제품 소유로 선언(동기화마다 PNG 충돌).
위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
보기" 버튼만 남는다.
검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
가림 규칙에 걸리지 않음).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
문제
BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시
적는 자유 값이다. operationId에 오타가 있어도 check:types와
check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와
다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을
처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이
같은 재기술을 적었다.
고른 방법
src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다.
descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은
이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를
넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다.
버린 대안
- BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트
약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다.
- 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌
위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지
않으므로 미뤘다.
- 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한
descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다.
위험·한계
- 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에
적었다.
- 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연
청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다).
검증
- RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패.
GREEN 뒤 통과.
- tests/features/reference-feature, tests/component/application-query.test.tsx
125건 통과.
- check:types, check:architecture, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05
문제
QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다.
bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능
작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로
적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②).
고른 방법
세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는
채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다.
매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title·
navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다.
버린 대안
- 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과
다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다.
- 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의
operation ID를 싣는다. 같은 값을 두 번 싣는다.
위험·한계
- 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면
FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와
test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은
파일이라 이번에는 문서로만 적었다.
검증
- RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner·
operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과.
- tests/features/reference-feature, tests/unit/create-feature.test.ts,
scope-fence 129건 통과. check:types(app·node·test), lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
문제
fix/r1103-gates(12-05)의 테스트는 옆 checkout을 흉내 낸 stub(백엔드
문서 1개)을 두고 verify:documentation 전체가 통과하기를 기대한다. 다른
브랜치를 합치자 실제 문서(매뉴얼 02·04, 백엔드 계약 문서)가 stub에 없는
백엔드 경로를 가리켜, 테스트가 status 1로 실패한다. 결함은 문서가 아니라
테스트 범위에 있다. 그 경로 14개는 실제 옆 checkout에 모두 있다.
고른 방법
- "있는 경로" 경우에서 전체 status 대신, 테스트가 고친 문서
(CI_DOC)에 빠진 경로가 없는지만 본다(stderr와 보고서 missingPaths).
- 버린 대안: stub에 실제 문서가 가리키는 백엔드 경로를 모두 만든다.
문서가 바뀔 때마다 테스트도 같이 바뀌어야 한다.
위험·한계
- 다른 문서의 짝 저장소 경로가 틀리면 이 테스트로는 잡지 않는다. 실제
옆 checkout이 있는 개발 환경의 verify:documentation이 잡는다.
검증
- tests/unit/documentation-readiness.test.ts 19건 통과.
- 실제 백엔드 checkout에서 문서가 가리키는 경로 14개 존재 확인.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
직전 커밋(짝 저장소 참조 테스트 범위 축소)이 보고서의 missingPaths를
읽지만, 테스트가 JSON을 읽을 때 쓰는 타입에 그 칸이 없어 check:types가
TS2339로 실패한다. vitest는 타입을 보지 않아 테스트는 통과했다.
고른 방법
- 보고서 타입에 missingPaths?: string[]를 더한다.
검증
- check:types 통과, documentation-readiness 테스트 19건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
fix/r1103-release(15-05)는 초기 JS 파일 수 상한을 그 브랜치의 개수(25)로
두었다. fix/r1103-examples(15-01)는 플랫폼 구성 화면이 실행부 레지스트리
조립 모듈을 동적으로 받게 했다. 그 결과 그 모듈과 초기 그래프가 함께 쓰는
installed-product-manifest(198 B gzip)가 따로 떨어져 초기 파일이 하나
늘었다. 두 브랜치를 합친 빌드는 26개이고 check:bundle이
"initial JavaScript files 26 > budget 25"로 실패한다.
고른 방법
- 상한을 26으로 올린다. performance-evidence.md의 규칙대로 초기 파일을
늘린 이유를 같은 변경에 적는다. 이 파일은 15-01(lab 게이트 회복)의
결과이고, 템플릿은 HTTP/2 서빙을 전제로 한다(13-02).
- 버린 대안: manualChunks로 그 모듈을 초기 청크에 묶기. 198 B 하나 때문에
청크 그룹 규칙이 하나 늘고, 셸을 바꿀 때마다 다시 재야 한다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다.
검증
- check:bundle PASS(26/26 파일).
- performance-budgets·bundle-artifact-contract 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05 15-01
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).
고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
실패 본문 행을 더한다.
버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
"빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
"...-vertical-slice"). 그대로 둔다.
위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
(REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
잡힌다.
검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
create-feature 테스트 통과. check:types, lint, verify:documentation 통과.
BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).
고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.
버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
가정 하나를 지키려고 정상 입력을 막는다.
위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
적었다. 이 경로의 드릴은 돌리지 않았다(추론).
검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
상태에서 tests/features 124건 통과, tests/component·architecture와
create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
문제
짝 백엔드에 쓰기를 붙일 때 기능 작성자가 정하는 값 넷(호출 문맥 intent,
retryBudget, classifyStatus, operationIdentityField)을 매뉴얼이 정해 주지
않는다. 02 3절은 "retryBudget 안에서 같은 키로 재전송"과 "참조 기능은 0"을
함께 적어 부딪히고, 401·403·429를 짝 백엔드가 쓰기 전에 거절하는지는 어느
문서에도 없다. 실험에서 실행기 코드를 읽고 값을 정했다(리뷰 B1~B4). 또 백엔드
생성 create가 NOT_IDEMPOTENT라는 사실과 프론트 retrySemantics의 관계가 적혀
있지 않다(03-07).
고른 방법
- 02 3절에 "짝 백엔드의 생성 기능에 붙일 때" 표를 둔다. 백엔드 create를
그대로 두면 NEVER, IdempotencyExecutor 뒤로 옮기면 KEYED. 두 경우의
retrySemantics, retryBudget(0 / 1과 실제 상한 계산), commandRecovery와
operationIdentityField의 뜻(실행기는 읽지 않음), intent 전달,
classifyStatus(401 보안 필터, 403 @RequiresPermission 프록시, 429
rate-limit interceptor preHandle — 백엔드 코드에서 확인),
refusedBeforeWrite, acceptedStatuses, 결과 불명 화면, 생성 테스트를 적는다.
- 01 4단계에 쓰기 메서드의 호출 문맥(intent), 8단계에 NEVER는 다시 보내기
버튼이 없다는 것과 생성 예제 위치를 적는다.
- 표의 값은 create:feature --with-create(--keyed)가 만드는 값과 같다.
버린 대안
- classifyStatus를 "백엔드 확인 전에는 생략"으로 두기(리뷰 권고 (1)의 잠정안):
백엔드 코드를 확인해 생성 create에서는 셋 다 use case 전이라 NOT_APPLIED로
적었다. use case가 AuthorizationPort를 쓰기 뒤에 부르면 지우라고 조건을
붙였다.
위험·한계
- classifyStatus 판정은 백엔드 c508b1ba의 생성 템플릿과 web 어댑터 기준이다.
백엔드가 바뀌면 다시 본다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-07
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
문제
--with-create(NEVER)와 --with-create --keyed(KEYED)가 만드는 코드는 단위
테스트가 텍스트로만 본다. FE-GATE-020의 두 드릴(test:feature-scaffold,
test:sample-removal)은 기본 기능 하나만 만들어 게이트를 돈다. 그래서 쓰기
slice의 타입·lint·테스트·빌드가 머지 게이트에서 깨져도 모른다(16 5.3절의
"생성 결과를 매번 게이트로 돌린다"는 전제).
고른 방법
- scripts/test-feature-scaffold.ts: 기본 기능(scaffold-feature) 옆에
scaffold-write-feature를 --with-create --keyed로 하나 더 만들고, 둘 다
만들어졌을 때 같은 게이트를 한 번 돈다. 바꾼 것은 WRITE_FEATURE_ID 상수,
create-feature-write 검사 한 개, 게이트 조건(created && createdWrite), 머리
주석이다.
- scripts/test-sample-removal.ts: 참조 기능을 지운 복사본의 create:feature
인자에 --with-create 한 개를 더했다. 쓰기 slice도 샘플에 기대지 않는다는
증거다.
- 세 변형(기본, NEVER, KEYED)이 모두 드릴의 게이트를 지난다.
- reference/create-feature.md의 드릴 설명을 맞췄다.
버린 대안
- 드릴 기능 하나를 --with-create로 바꾸기: 기본 변형이 게이트에서 빠진다.
위험·한계
- test:feature-scaffold는 기능 하나만큼(create:feature 한 번과 그 기능의
테스트) 길어진다. 게이트는 한 번만 돈다.
- 다른 작업(게이트 담당)이 같은 두 파일의 명령 목록을 고칠 수 있다. 내 수정은
위 줄로 좁혔다.
검증
- flock 아래 CHOKIDAR_USEPOLLING=1 corepack pnpm test:feature-scaffold:
rc=0, "feature scaffold: PASS (17 checks)" (생성 2 + 게이트 15), 162초.
- 같은 조건 corepack pnpm test:sample-removal: rc=0, "reference-feature
removal: PASS (23 checks, no fixture IDs)". 참조 기능을 지운 복사본에서
--with-create 기능을 만든 뒤 scaffold-* 게이트 9개가 모두 통과했다. 첫
실행은 tests/unit/create-feature.test.ts에 샘플 ID 문자열이 있어
fixture-id-residue로 실패했고, 그 테스트를 앞 커밋에서 고친 뒤 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
09-06의 완료 기준은 짝 백엔드 wire의 KEYED 생성, 400 필드 오류와 함께 409
IDEMPOTENT_IN_FLIGHT를 실행하는 기능 예제다. --with-create --keyed가 만드는
gateway 테스트는 503 IDEMPOTENCY_UNAVAILABLE 재전송만 보고 409 처리 중은 보지
않는다.
고른 방법
KEYED 생성 gateway 테스트에 409 IDEMPOTENT_IN_FLIGHT 사례를 더한다. 결과는
MAYBE_APPLIED이고 code가 그대로이며, 실행기는 스스로 다시 보내지 않는다(같은
키 재전송은 폼이 한다, http-contract.md §2). NEVER 생성은 키가 없어 이 답을
받지 않으므로 더하지 않는다.
위험·한계
- Retry-After 대기는 뮤테이션 조정자 쪽이라 이 gateway 테스트는 보지 않는다.
검증
- keyx-feature --with-create --keyed를 만들어 gateway 테스트 13건 통과, eslint
통과. 생성 기능은 지웠다. tests/unit/create-feature.test.ts 43건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
문제
fix/r1103-release(15-02)는 초기 JS 기준선을 feature-shape-ceilings.json의
initialJavascript 한 곳에 두고, test:unit이 빌드와 대조하게 했다. 열 개
조치 브랜치를 합친 빌드는 그 브랜치 하나로 잰 기록(200,939 B, 25개)과
다르다(15-01이 떨어뜨린 파일 하나, 세션·업로드·생성기 변경). 그래서
feature-shape-growth 테스트가 "initialJavascript is stale"로 실패한다.
고른 방법
- 기록 절차(performance-evidence.md)대로
measure-feature-shape-growth.ts --initial-baseline --write로 다시 쓴다.
- 결과: 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B.
예산 204,800 B에 여유 1,873 B다.
위험·한계
- 여유가 작다. --with-create 기능 하나(+약 964 B)를 넣으면 약 900 B가
남는다.
검증
- tests/unit/feature-shape-growth.test.ts 통과(heavy lock,
CHOKIDAR_USEPOLLING=1).
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02 15-04
문제
.gitea/workflows/quality-gates.yml은 workflow 전체 env에
VITE_BUILD_ID=gitea-<run>-<attempt>와 VITE_COMMIT_SHA를 넣는다. Vite는 이
값을 import.meta.env로 번들에 넣는다. 그래서 CI와 같은 env로 돌리면:
- vitest: 앱을 local-build fixture release로 조립하는 테스트가
CONFIG_BUILD_MISMATCH로 실패한다(runtime-application,
boot-unexpected-failure, runtime-composition-service-worker-telemetry,
reference-production-vertical, 생성 기능 페이지 테스트). FE-GATE-005·006·
007과 제거 드릴(FE-GATE-020)이 떨어진다.
- capability e2e: dev server는 public/config.json(BUILD_ID local-build)을
내주는데 번들은 gitea-1-1이라, 페이지마다 rolling-release 불일치로 한 번
다시 불러오고 그다음 실패 화면이 된다. page.evaluate가 "Execution context
was destroyed"로 30건 실패한다(FE-GATE-008).
깨끗한 clone에서 merge 단계 14개를 CI env로 돌려(리뷰 조치 X4) 찾았다.
로컬에서는 이 값이 없어서 늘 통과한다. 1103/11-06과 같은 원인이다.
고른 방법
- vitest.config.ts가 npm scope 변수를 지우는 것과 같은 자리에서
VITE_BUILD_ID·VITE_COMMIT_SHA를 지운다. 테스트는 로컬 빌드 식별값으로
시작한다.
- dev server를 띄우는 Playwright 설정(capabilities, dev)은 webServer env로
VITE_BUILD_ID=local-build, VITE_COMMIT_SHA=local을 준다. 그 dev server가
내주는 config.json과 같은 값이다.
- build·preview를 쓰는 e2e·visual은 바꾸지 않았다. 빌드가 같은 값으로
config.json을 만들므로 맞는다.
- 버린 대안: 테스트마다 기대값을 env에서 읽기(11-06 방식). 같은 모양의
fixture가 여러 파일에 있고, 다음 테스트가 또 같은 실수를 한다.
위험·한계
- vitest 안에서 CI 빌드 식별값을 읽는 것을 검사하려는 테스트는 값을 직접
넣어야 한다(지금은 없다).
- CI=true와 러너 이미지 조건은 재현하지 않았다.
검증
- VITE_BUILD_ID=gitea-1-1, VITE_COMMIT_SHA=<HEAD>로: test:unit 2,878,
test:component 270, test:integration 189, test:reference-feature 97,
test:recipes 77 통과. browser-files capability spec chromium 3건 통과
(수정 전 3건 실패, env 없으면 통과).
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-06
문제
ac52a93이 backend-api-and-server-state-contract.md를 docs/README.md 1절에서
링크해 이 문서도 경로 검사를 받는다. 이 문서는 참조 기능 파일 둘을 백틱
경로로 적는다. static-delivery.md는 config/scale/feature-shape-ceilings.json
(15-02, 샘플 제거 때 함께 지워짐)을 백틱 경로로 적는다. 그래서 참조 기능을
지운 제거 fixture에서 verify:documentation이 "names paths that do not exist"로
실패하고, 그 fixture의 documentation-readiness 테스트 36건이 떨어진다
(FE-GATE-020). 14-04가 정한 규칙(지울 수 있는 샘플 경로는 백틱 없이)을
어겼다.
고른 방법
- 세 경로를 백틱 없이 적고, static-delivery에는 샘플과 함께 지워진다고
적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture 확인은 X4 재실행에서 한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 14-03
문제
미출시 절은 fix/ui-design-audit-2026-11-01 한 브랜치의 누적 기록이었다.
- 같은 묶음에 들어온 그 브랜치 뒤 16커밋(ece944dd0414c87d855897c8cb1917fa8d127f45238a09c90e5b7b3e 등)과 2026-11-03 조치 11개 브랜치가 없다.
- V2를 고친 행과 V2를 지운 행이 함께 있고, 알려진 제한 13줄 중 대부분이
이미 고쳐졌다.
- BREAKING 이행 안내가 "memento-web이 V2 API 행을 쓴다"고 적었다. memento-web의
apiOperations는 비어 있고, 실제 작업은 descriptor 29개의 FE-REG-API 행,
스키마 행 43개, zod가 아닌 검증기다. tech-log의 직접 조립 경로는 안내가
없었다.
- 0.2.0의 17d617a 행이 설정 스키마 분류기를 "레지스트리 호환성 분류기"라고
부르고, 그 커밋이 고치지 않은 scripts/check-registries.ts를 적는다.
고른 방법
- 결정 D5 (b): 752a61f → fix/maturity-review-2026-11-03 범위를 한 동기화
단위로 보고 최종 상태만 적는다. 머리에 범위·세 갈래·읽는 법, 이어서
"먼저 할 일 (BREAKING)"을 옮기기 전 / 옮기는 법 / 옮긴 뒤 확인 순서로,
그 뒤 영역별 [보안]·[계약] 표, 그 밖의 수정, f887817에서 사실인 알려진
제한을 둔다. 뒤 커밋이 바꾼 중간 상태 행(V2 Envelope·V2 거절·V2/V3 대조,
REST 보안 프로필 메시지, 초기 청크 16→25개 등)은 최종 행에 합치거나 지웠다.
- 14-02: 두 다운스트림(memento d3810a0, tech-log 7a4e201a)을 읽고 단계마다
실제 모양을 적었다. memento: PRODUCT_LOCAL_CONTRACT 출처, ownsShell·APP_HOME
다리, SW ACTIVE 선택, 손으로 쓴 검증기. tech-log: NOT_INSTALLED 직접 조립과
기능 모듈로 바꾸는 길(fixture-layout-product 모양).
- 리뷰 P-07-07은 경로를 scripts/lib/registry-compatibility.ts로 바꾸라고
했지만, 17d617a가 고친 것은 src/contracts/compatibility.ts(FE-GATE-014)다.
경로를 바꾸면 틀린다. 그래서 이름을 "설정 스키마 호환성 분류기"로,
둘째 경로를 scripts/check-compatibility.ts로 고쳤다.
- 머리 규칙에 미출시 절이 동기화 단위 순 요약이라는 줄을 더했다.
- 버린 대안: 브랜치별 누적 기록을 유지하고 빠진 행만 더하기(14-01 (a)).
다운스트림이 서로 뒤집는 행을 직접 걸러야 한다. 커밋 trailer 검사
(14-01 (c))는 이번에 넣지 않았다.
위험·한계
- 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento 숫자는
정적 집계다. 알려진 제한에 적었다.
- 끝 커밋은 f887817 기준이다. 이 브랜치를 합친 뒤 끝이 바뀌어도 해시 규칙
(범위 안)은 그대로다.
- 짝 백엔드가 pin c508b1ba 뒤로 바뀐 것(HEAD 45d2a478, §2 두 행 설명)을
알려진 제한에 적었다. pin은 올리지 않았다.
검증
- 미출시 절의 이 repo 해시 148개: 모두 f887817에서 닿고 752a61f에서 닿지
않는다(merge-base --is-ancestor 스크립트). 나머지는 기준점 2개와 다른
repo 커밋 4개.
- vitest changelog-review-ids, documentation-readiness 20건 통과.
- verify:documentation PASS_SCOPED, check:types, lint 통과.
- 인증 프로필 오타 변이(참조 기능): check:registries가 reason과 함께 실패,
check:types·check:architecture·verify:documentation 통과를 확인했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-02
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-07
문제
리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다.
- 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가
"실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다.
실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다.
- 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가
실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만
실패하고 check:types·check:architecture·verify:documentation은 통과한다.
- 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400
VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는
Envelope operation에서 결과 불명이다.
- starter-experience.md: "`NoRequest` already belongs to the sample". src에
NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다.
다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app).
고른 방법
문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지
않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로
적는다. 매뉴얼에 그 테스트를 가리켰다.
위험·한계
- 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는
돌리지 않았다.
검증
- 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0,
check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림.
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08
문제
- "CI and evidence"의 로컬 merge 게이트 반복문이 13개이고 FE-GATE-012가 없다.
f41e3d5가 번들 예산 게이트를 merge 단계로 옮겨 gates.json의 merge 단계는
14개다. "Updating a copied project"가 이 반복문을 가리키므로, 동기화한
제품은 번들 예산을 건너뛴다.
- 배포 슬롯을 채우는 곳이 config/ci/product-gates.json으로 바뀌었고(12-07),
FE-GATE-019는 HTTP/2·entry 압축이 없는 호스트도 실패시킨다(13-02).
README는 둘 다 말하지 않는다.
- CHANGELOG 미출시 절이 동기화 단위 순 요약이 됐는데(14-01 D5 (b)), 업데이트
절은 그 절을 어떻게 받는지 말하지 않는다.
고른 방법
문장 셋만 고친다. 반복문에 012를 넣고 개수를 14로, 제품 merge 검사
(PRODUCT-GATE-NNN)는 workflow의 product_merge_gate job이 돈다고 적었다.
업데이트 절에는 미출시 절을 범위째 받고 "먼저 할 일"부터 하라는 한 문장을
더했다. cherry-pick 절차는 그대로 둔다(한 수정을 받을 때는 여전히 맞다).
위험·한계
- README의 다른 절(0929/14-02의 범위 동기화 절차 전체)은 다시 쓰지 않았다.
검증
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
- config/ci/gates.json merge 단계 gateIds 14개와 반복문을 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제
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
문제
af312de(vitest와 dev server Playwright가 CI의 VITE_BUILD_ID·VITE_COMMIT_SHA를
물려받지 않는다)는 CHANGELOG 재작성(44aa44d) 뒤에 들어왔다. 미출시 절
머리의 끝 커밋 설명도 그 뒤의 변경을 말하지 않는다.
고른 방법
- 게이트·드릴 행에 1103/11-07 행을 더한다. 리뷰 README 13절에 발견으로
적는다.
- 머리에 f887817 뒤로 검증 수정과 pin 갱신이 더해졌다고 적는다.
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제
깨끗한 clone의 FE-GATE-008에서 test:storybook이 "Axe is already running"으로
떨어졌고, 이 worktree에서도 두 번에 한 번 떨어진다. @storybook/addon-a11y
10.6.5(13-03이 올린 판)는 story를 그린 뒤 afterEach에서 axe를 스스로 돌린다
(globals.a11y.manual이 true가 아니면). spec의 AxeBuilder.analyze()는 그 페이지의
같은 axe 인스턴스를 쓰므로, 두 실행이 겹치면 두 번째가 거절된다.
고른 방법
- spec이 story를 `globals=a11y.manual:!true`로 연다. 애드온은 자동 검사를
건너뛰고, 접근성 판정은 지금처럼 spec의 AxeBuilder가 한다.
- 버린 대안: 애드온 실행이 끝나길 axe 내부 상태로 기다리기. 공개 API가
아니고, 애드온 실행이 시작되기 전에 확인하면 여전히 겹친다.
- 버린 대안: preview 전체에서 애드온 자동 검사 끄기. workshop에서 쓰는
사람이 패널 결과를 잃는다.
위험·한계
- 이 spec만 바꿨다. 다른 storybook spec이 생기면 같은 URL을 쓴다.
검증
- test:storybook 5회 연속 통과(heavy lock). 수정 전 2회 중 1회 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
fix/r1103-release(15-02)가 performance-evidence.md에 기준선 기록 파일
(config/scale/feature-shape-ceilings.json)과 측정 테스트
(tests/unit/feature-shape-growth.test.ts)를 백틱 경로로 적었다. 둘 다 참조
기능을 복사해 재므로 test:sample-removal이 함께 지운다. 그래서 제거
fixture에서 verify:documentation이 실패하고 documentation-readiness
테스트 36건이 떨어진다(깨끗한 clone FE-GATE-020). 14-04 규칙(지울 수 있는
샘플 경로는 백틱 없이)과 2f2426a와 같은 결함이다.
고른 방법
- 두 경로를 백틱 없이 적고, 샘플과 함께 지워진다고 적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture는 X4 재실행에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 15-performance.md 15-02
문제
홈 화면과 플랫폼 구성 화면은 build id와 release id를 글자로 그린다. CI는
workflow 전체에 VITE_BUILD_ID·VITE_COMMIT_SHA·RELEASE_ID를 준다. 그래서
test:visual(FE-GATE-008)의 build가 골든과 다른 글자를 그려, 셸 넓은 화면·
좁은 서랍·플랫폼 구성 3장이 1,109~1,545 px 달라 항상 실패한다. 깨끗한
clone에 CI env를 준 merge 단계 재실행에서 찾았다(af312de와 같은 원인,
1103/11-07).
고른 방법
- playwright.visual.config.ts webServer env로 로컬 식별값(local-build,
local, local-release)을 준다. 골든은 템플릿의 모양 계약이고 그 값으로
찍었다.
- 버린 대안: 식별값 글자를 화면마다 가리기. 가릴 곳이 화면마다 늘고,
식별값을 그리는 새 화면이 생길 때마다 다시 빠진다.
위험·한계
- 시각 테스트의 build는 CI 식별값을 쓰지 않는다. 식별값 표시 자체는
e2e(compact smoke, 11-06)가 CI 값으로 본다.
검증
- VITE_BUILD_ID=gitea-1-1·VITE_COMMIT_SHA·RELEASE_ID를 주고 test:visual 6/6,
env 없이 6/6 통과. 수정 전 CI env에서 3건 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제
test:sample-removal의 잔여 검사(REFERENCE_RESOURCE|reference-feature|
reference-resource)가 샘플을 지운 fixture에서 두 파일을 잡아 FE-GATE-020이
실패한다. tests/unit/hosting-probe.test.ts는 비상 스위치 예시로
FEATURE_OVERRIDES에 "reference-feature"를 쓰고(13-01), platform-examples-
context의 머리 주석은 참조 context 경로를 적는다(09-04).
고른 방법
- 테스트 값을 "platform-examples-feature"로 바꾸고, 주석은 샘플 이름 없이
적는다. 동작은 바뀌지 않는다.
검증
- tests/unit/hosting-probe.test.ts 37건, lint 통과. 제거 드릴은 X4 재실행에서
확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.
고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
`/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.
위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).
검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02)는 복사본에 제품
파일과 기능 하나를 넣고 tsc 세 프로그램을 돈다. 세 가지가 제품과
제거 드릴에서 깨진다(리뷰 조치 X2 #1, #7).
- 탐침 ID가 notice-feature·notice-context다. 매뉴얼 예시가 모두 "공지"라
제품이 같은 ID를 쓰면 FE-GATE-005가 원인을 말하지 않는 TS 오류 약
20줄로 실패한다.
- product-capabilities.ts가 템플릿의 빈 선언 그대로여야 한다고 단언하고
그 선언을 바꿔 쓴다. 자기 capability를 적은 제품에서 실패한다.
- 복사 대상을 모두 복사한다. test:optional-recipe-removal의 fixture에는
recipes/가 없어 ENOENT로 떨어진다.
고른 방법
- 탐침 이름을 typecheck-probe-*(capability typecheckProbeSettings, 설정 키
TYPECHECK_PROBE_PAGE_SIZE)로 바꾸고, 그 기능 폴더가 이미 있으면 이름을
말하며 실패한다.
- capability 타입은 제품 파일 끝에 같은 이름 interface로 덧붙인다.
TypeScript가 합치므로 제품의 선언이 남는다.
- 없는 복사 대상은 건너뛴다.
위험·한계
- product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔
쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 복사본에서
타입 오류가 날 수 있다.
검증
- 테스트 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02, README.md 14.6 X2
문제
config/scale/feature-shape-ceilings.json의 initialJavascript는 지금 설치된
기능으로 만든 빌드를 기록하고, test:unit이 빌드와 대조한다(1103/15-02).
제품이 기능을 더하면 기록을 다시 써야 FE-GATE-005가 통과한다. 그러면
`test:sample-removal -- --feature=<id>`가 그 기능을 지운 fixture에서 반대
이유("record 27, build 26")로 실패한다. 두 게이트를 함께 통과시킬 방법이
없다(리뷰 조치 X2 #2).
고른 방법
- 드릴이 레지스트리 기준선을 다시 찍는 것과 같은 자리에서
measure-feature-shape-growth.ts --initial-baseline --write를 fixture에서
돌린다. 제품이 기능을 지운 뒤 할 일을 드릴이 그대로 한다.
- 샘플 제거는 측정 스크립트를 함께 지우므로 그때는 건너뛴다.
위험·한계
- 측정이 빌드를 하므로 기능 제거 드릴이 1~2분 길어진다.
검증
- eslint 통과. 기능 제거 드릴은 X4 재실행(test:feature-scaffold 안의
feature-removal)에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, README.md 14.6 X2 #2
문제
initialJsFiles 상한이 템플릿 그대로의 수(26)와 같다(1b8cb12). 기능의 지연
페이지가 셸과 같은 구성요소(Button, SearchField)를 쓰면 그 구성요소가 공유
청크로 떨어져 초기 파일이 하나 는다. 매뉴얼의 검색 폼 예제를 따른 기능
하나로 FE-GATE-012가 "27 > budget 26"으로 실패했다(리뷰 조치 X2 #4).
고른 방법
- 상한을 32(지금 26 + 6)로 둔다. 템플릿은 HTTP/2 서빙을 요구하고
(1103/13-02, FE-GATE-019), 그때 파일 하나의 비용은 거의 없다(15 영역
측정). 상한은 청크가 통째로 쪼개지는 회귀를 막는 용도다.
- performance-evidence.md에 이유와, 넘었을 때 먼저 청크 그룹을 볼 것을
적는다.
- 버린 대안: 상한을 지금 수로 두고 제품마다 올리기. 템플릿 소유 파일을
기능마다 고치게 된다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다. 여유는 1,873 B다.
검증
- performance-budgets·bundle-artifact-contract 테스트 14건,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05, README.md 14.6 X2 #4
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)에서 안내가 틀리거나 빠진
곳이 나왔다.
- 생성 명령 출력과 매뉴얼 01이 초기 JS 기록(config/scale/feature-shape-
ceilings.json)을 말하지 않는다. 출력은 "baseline does not change"만 적는다.
- 01·create-feature.md가 "드릴은 check:bundle을 돌리지 않는다"고 적는다.
12-02 뒤로 드릴은 merge 단계 명령으로 check:bundle을 돈다.
- 로컬에서 FE-GATE-013은 VITE_COMMIT_SHA가 40자리 커밋이어야 한다. 실패한
게이트의 로그 위치가 어디에도 없다.
- 01 6단계가 "생성된 판은 파라미터가 없다"고 적지만 --with-create 상세
라우트는 codec을 넘긴다. global-ids.md의 API 경로 예가 옛 생성 경로다.
고른 방법
- 생성 명령 Next에 3번(기록 다시 쓰기)과 로그 위치·FE-GATE-013 조건을
더한다. 매뉴얼 01 "merge 전에 돌릴 것"에 같은 내용과 파일 수 상한을
적는다. 나머지 문장을 지금 동작에 맞춘다.
검증
- tests/unit/create-feature.test.ts 43건, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #2#5#6
문제
src/adapters/http/fileserver-upload.ts(1103/01-01)가 입력 타입으로
application/ports/browser-file-storage의 FileByteSource를 import한다.
test:browser-file-storage-removal(FE-GATE-020)은 그 선택 런타임과 포트를
지우고 남은 코드가 import하지 않는지 본다. 그래서 "Removed browser
file/storage runtime is still imported by: src/adapters/http/
fileserver-upload.ts"로 항상 실패한다(리뷰 조치 X2 #7).
고른 방법
- client 안에 같은 모양의 FileserverByteSource(byteLength, stream이
Result<Uint8Array, { code }>를 낸다)를 두고 배럴로 낸다. client가 쓰는
것은 이 셋뿐이다. 제품은 FileContentPort.openSource가 준 FileByteSource를
그대로 넘긴다(구조 타입).
- 버린 대안: 드릴이 이 client도 함께 지우기. http 배럴이 export하므로 배럴도
고쳐야 하고, 파일 runtime을 쓰지 않는 제품도 업로드 client를 잃는다.
위험·한계
- FileByteSource 모양이 바뀌면 두 타입이 어긋날 수 있다. 통합 테스트가
FileByteSource 값을 client에 넘기므로 check:types가 그 어긋남을 잡는다.
검증
- check:types(테스트의 FileByteSource → client 호환), lint,
check:architecture, test:integration 통과. 드릴은 이 커밋 뒤 재실행한다.
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, README.md 14.6 X2 #7
문제
c15345c가 vite.config.ts에서 scripts/lib/dev-release-manifest.ts를
import한다. 초기 JS를 재는 measure-feature-shape-growth.ts와
product-feature-selection-build 테스트는 빌드할 복사본에 정해진 파일만
복사하는데(BUILD_INPUTS), 그 목록에 새 파일이 없다. 그래서 복사본의 vite
build가 "Could not resolve './scripts/lib/dev-release-manifest.ts'"로 실패해
test:unit 두 파일과 세 capability 제거 드릴이 떨어졌다. c15345c 뒤에
test:unit 전체를 돌리지 않아 놓쳤다.
고른 방법
- 두 BUILD_INPUTS에 그 파일을 더한다.
- 두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 이 수정의 범위 밖으로
둔다(남은 문제).
검증
- test:unit 193파일 2,880건 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)의 막힘 7건과 깨끗한 clone
검증에서 고친 것이 미출시 절에 없다.
고른 방법
- 그 밖의 수정에 한 행으로 적는다(dev release manifest 1103/16-09, 기능 제거
드릴의 초기 JS 재기록 15-02, 파일 상한 32 15-05, 업로드 client 포트
분리 01-01, 타입 검사 탐침 09-02, 시각·storybook 11-07).
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6
문제
dev-release-manifest 테스트의 둘째 경우가 생성 결과를 커밋된 자리표시자와
통째로 비교한다. 템플릿 기능만 있으면 같지만, 기능을 더한 제품이나 생성
기능을 넣은 제거 드릴 fixture에서는 contract set이 달라 실패한다. 깨끗한
clone의 FE-GATE-020(test:sample-removal 안의 test:unit)에서 떨어졌다. 이
리뷰가 여러 번 고친 "템플릿 그대로일 때만 맞는 테스트"와 같은 결함을 새로
만들었다.
고른 방법
- 둘째 경우는 contract set을 뺀 나머지 칸이 자리표시자와 같고, contract
set이 설치된 기능의 buildContractSet()과 같은지 본다.
검증
- 테스트 2건, eslint, check:types 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
c15345c의 플러그인은 apply: "serve"라 Vitest가 Vite를 띄울 때도 돌아,
test:unit마다 자식 프로세스로 manifest를 쓴다. 출력 위치
src/.generated/dev-release-manifest.json에는 자리표시자의 routeChunks(샘플
경로)가 들어 있다. test:sample-removal의 잔여 검사는 src/를 훑으므로
FE-GATE-020이 "fixture-id-residue: src/.generated/dev-release-manifest.json"으로
실패한다.
고른 방법
- 출력을 빌드의 contract set 생성물 옆 .generated/frontend-runtime/로 옮긴다
(무시 대상).
- apply가 serve이면서 VITEST가 없을 때만 돈다. 테스트는 서버에서
manifest를 받지 않는다.
검증
- browser-files capability spec(dev server) chromium 3건 통과, 생성물이 새
위치에 생긴다.
- test:unit 2,880건 통과, 실행 뒤 src/.generated에 manifest가 없다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
test:feature-scaffold(12-02)는 기능 둘을 생성한 fixture에서 merge 단계
명령을 돈다. 15-02의 test:unit은 초기 JS 기록
(config/scale/feature-shape-ceilings.json)을 빌드와 대조한다. 두 브랜치를
합치자 드릴 안의 test:unit·test:coverage가 "initialJavascript is stale"로
실패해 FE-GATE-020이 떨어진다. 제품은 생성 명령 Next: 3번대로 기록을 다시
쓰지만 드릴은 그 단계를 하지 않았다.
고른 방법
- 생성이 성공하면 fixture를 봉인하기 전에 measure-feature-shape-growth.ts
--initial-baseline --write를 돌린다. 측정 스크립트가 없으면(샘플이 없으면)
건너뛴다. 결과는 별도 검사(initial-javascript-record)로 보고한다.
위험·한계
- 드릴이 빌드 한 번만큼 길어진다.
검증
- check:types, eslint 통과. FE-GATE-020은 깨끗한 clone에서 다시 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02, 15-performance.md 15-02
문제
깨끗한 clone의 FE-GATE-008에서 dev server를 쓰는 capability e2e가
"requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 1~4건씩
떨어졌다(세 번 중 세 번, 부하 9~30). 플러그인(db5728b)이 dev server 시작
때 .generated/frontend-runtime/에 manifest를 쓰는데, polling 감시
(CHOKIDAR_USEPOLLING=1)가 그 새 파일을 서버가 뜬 뒤에 보고 부팅 중인 페이지를
다시 불러오면 진행 중인 manifest 요청이 끊긴다고 본다. 플러그인을 넣기 전
같은 부하의 회차들은 66건 모두 통과했다.
고른 방법
- 자식 프로세스가 manifest를 stdout으로 내고, 플러그인은 그 문자열을
메모리에 두고 낸다. 파일을 쓰지 않으므로 감시가 볼 것이 없다.
devReleaseManifest(source)가 문자열을 돌려준다.
위험·한계
- 원인을 감시 이벤트로 직접 관측하지는 않았다(추론). 수정 뒤 재실행으로
확인한다.
검증
- tests/unit/dev-release-manifest.test.ts 2건, check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 X4
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
미출시 절은 "corepack pnpm dev가 설치된 기능의 contract set으로 release
manifest를 낸다"고 적는다. 그 미들웨어는 799ab7f에서 지웠고, 지금은
create:feature와 기능 제거 드릴이 public/release-manifest.json을 다시 쓴다.
고른 방법
- 행을 지금 동작([계약]: 다시 쓰는 명령, 커밋할 것, 낡으면 실패하는 테스트)과
dev server 감시 제외로 고친다.
검증
- changelog-review-ids·documentation-readiness 테스트 20건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 16-09
문제
리뷰 README에 조치 결과가 없다. 사용자가 "나머지 전부 진행하세요"라고
했고, 이 세션이 발견 90건과 0929/03-03을 고치고 통합했다.
고른 방법
- 13절에 조치 중 찾은 발견 둘(11-07 CI 빌드 식별값 누출, 16-09 dev
manifest 고정 contract set)을 36.3 양식으로 더하고 색인을 92건으로 고친다.
- 14절을 새로 둔다: 방법(수정 브랜치 11개, wave 1~3), 결정 D1~D6, 통합에서
생긴 것, 발견별 상태(일부 9건과 결정 대기 3건), 깨끗한 clone의 merge 단계
14개 회차별 결과(X4), 매뉴얼 재실험 막힘 7건과 처리(X2), 남은 문제.
위험·한계
- X2(매뉴얼만 보는 재실험)는 고친 뒤 다시 돌리지 않았다. 고친 것은 생성
기능을 넣은 clone 확인과 X4로 확인했다.
- 실제 Gitea 러너, 짝 백엔드·nginx·Keycloak·Redis 연동은 확인하지 않았다.
검증
- 최종 커밋 799ab7f, 깨끗한 clone, CI env: FE-GATE-001~013·020 통과
(FE-GATE-008은 첫 실행 Firefox 다운로드 시간 초과 1건, 재실행 2회 통과).
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 14절
문제
workflow는 모든 job에 CI=true와 CI 빌드 식별값을 준다. 메인 세션이 깨끗한
clone에서 그 env 그대로(CI=true 포함) merge 단계 14개를 돌리자 FE-GATE-005·
008·020이 실패했다.
- vitest 안의 fixture 빌드(tests/e2e/support/fixture-builds.ts →
build-frontend.ts)가 CI=true를 물려받아 release 빌드처럼 검사된다.
af312de가 vitest에서 VITE_COMMIT_SHA를 지워 "missing required CI build
environment: VITE_COMMIT_SHA"로 멈춘다(service-worker-build-output 7건이
돌지 않음, 제거 드릴 안에서도 같다).
- 시각 골든 build(9bddfa5)가 VITE_COMMIT_SHA="local"을 받는데 CI=true가
40·64자리 hex를 요구해 webServer가 뜨지 않는다.
내 X4가 CI=true 없이 돌아 놓쳤다. 1103/11-07과 같은 원인이다.
고른 방법
- scripts/lib/build-environment.ts에 둘을 둔다.
- localBuildEnvironment(env): spawn하는 로컬 빌드용. CI와 CI 빌드 식별값을
뺀 사본. fixture-builds.ts, service-worker-builds.ts가 쓴다.
- LOCAL_BUILD_IDENTITY: Playwright web server용. Playwright가 env를
process.env 위에 합치므로 CI를 지우지 않고 ""로 덮는다(검사는
CI === "true"일 때만). visual·capabilities·dev 설정이 쓴다.
- assertCiBuildEnvironment의 CI=true 검사는 그대로다. job 자신의 release
빌드(build:release-candidate 등)는 계속 검사된다.
- 버린 대안: 로컬 빌드에 유효한 가짜 커밋 id(0×40)를 주기. CI=true 검사의
다른 칸(CI_RUNNER_IMAGE, SOURCE_DATE_EPOCH)도 함께 맞춰야 하고, 로컬
빌드가 release 빌드인 척한다.
위험·한계
- 로컬 빌드 안에서 CI를 읽어 동작을 바꾸는 코드가 있으면 그 빌드는 이제
CI가 아닌 쪽으로 돈다(지금은 build-environment 검사뿐이다).
검증
- tests/unit/local-build-environment.test.ts 3건: 구현 전 2건 실패(RED),
CI job 자체 검사는 유지.
- CI=true·VITE_COMMIT_SHA·VITE_BUILD_ID=gitea-41-1·RELEASE_ID·
CI_RUNNER_IMAGE·SOURCE_DATE_EPOCH로: service-worker-build-output 7건,
test:visual 6/6, test:unit 2,883, test:component 270, test:integration 189
통과. 수정 전 service-worker-build-output은 7건 미실행.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
README의 로컬 merge 게이트 반복문과 매뉴얼 01, 생성 명령 출력은 CI=true와
CI 빌드 식별값 없이 돌리는 법만 적는다. 그렇게 통과해도 workflow(CI=true)에서
떨어지는 결함 두 건(1103/11-07, 11-08)이 이 차이로 숨었다.
고른 방법
- README 반복문 아래에 workflow와 같은 env 블록(CI=true, VITE_COMMIT_SHA,
VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest)과 깨끗한 clone에서 돌리라는
말을 더한다. 테스트가 만드는 로컬 빌드는 이 값과 무관하게 로컬 빌드로
돈다는 것도 적는다.
- 매뉴얼 01 "merge 전에 돌릴 것"과 생성 명령 Next 2번이 그 블록을
가리킨다.
검증
- verify:documentation PASS_SCOPED, tests/unit/create-feature.test.ts 43건.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제: b693600(1103/11-08)이 fixture 빌드·시각 골든 build·dev server를
CI=true와 CI 식별값에서 떼어 놓았는데 CHANGELOG에는 11-07의 vitest·dev
server 조치만 있었다.
방법: 게이트·드릴 행의 11-07 문장 뒤에 11-08을 이어 적었다. 새 행을 만들지
않은 것은 같은 원인(CI env가 로컬 빌드로 샌다)의 두 번째 조치라서다.
검증: tests/unit/changelog-review-ids.test.ts 통과,
verify:documentation PASS_SCOPED(짝 백엔드 checkout 없음).
문제: 14.5절 X4의 1~7회차와 799ab7f 결과는 CI=true와 CI_RUNNER_IMAGE
없이 돌린 것이라, 메인 세션이 c7c7887에서 workflow env로 찾은
FE-GATE-005·008·020 실패(11-08)를 놓쳤다. 리뷰 기록에 그 사실과 새 발견이
없었다.
방법:
- 13절에 11-08(Medium·P1, 고침 b693600, 안내 cd7e784)을 더하고 색인·
14.4 행·발견 수(93건)를 맞췄다.
- 14.5절에 앞 회차가 CI=true 없이 돌았다고 적고, 8회차(cd7e784, CI=true와
CI_RUNNER_IMAGE digest)와 최종 행을 더했다. 표 중간의 빈 줄로 7회차와
최종 행이 표 밖으로 빠져 있던 것도 고쳤다.
- 14.7절에 FE-GATE-008을 한 번에 통과시키지 못하게 하는 두 flake(Firefox
다운로드 시간 초과, webkit preload 경고)와 원인 조사 결과를 적었다.
Blob URL을 일찍 회수하는 경쟁을 의심해 A/B로 쟀으나 둘 다 60/60이라
테스트는 고치지 않았다.
위험·한계: 실제 Gitea 러너가 아니라 로컬에서 workflow env를 준 실행이고
CI_RUNNER_IMAGE는 가짜 digest다. 두 flake의 원인은 찾지 못했다.
검증: 깨끗한 clone(cd7e784)에서 14개 ci:gate. 001~007·009~013·020은 한
번에, 008은 세 번째 실행에서 통과. verify:documentation PASS_SCOPED.
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).
고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
"preload한 script가 실제로 실행됐는가"를 본다.
- 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
MutationObserver로 적고, 끝에 남은 link도 더한다.
- page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
문장 하나를 앞에 붙인다.
- test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
"참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
- script가 아닌 preload는 `preloadunverifiable:<as>:`.
- Service Worker가 문서를 제어할 때 만든 preload는
`preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
release manifest의 sha256 대조가 깨진다.
- route.fetch가 세 번 실패해 표시 없이 넘어간 script는
`preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
- boot-module-failure: 깨진 build의 boot 정적 closure.
- old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
허용이 WebKit 경고 문구로만 있었다.
- service-worker-update: worker 제어 중 preload만.
- production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
fulfillBuildScript를 쓴다.
버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.
위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
service-worker-update만 허용).
검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
- 변이 test는 세 엔진 모두 Expected
["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
- 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
…/reference-schemas-DICBcHlO.js was preloaded using link preload but not
used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
- 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
- 새 fixture: 3/3 실패,
"preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
- 이전 fixture: webkit 실패.
- 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
(probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
문제: aad005cb(1103/11-09)이 strict fixture의 WebKit preload 경고 처리와
새 preload 사용 검사를 바꿨는데 CHANGELOG에 없었다. 다운스트림은 build
script를 직접 fulfill하는 test에 `fulfillBuildScript`를 써야 한다.
방법: 게이트·드릴 행의 11-08 문장 뒤에 이어 적었다. FE-GATE-008이 가끔
떨어지던 게이트 문제라 같은 행에 둔다.
검증: desktop에서 tests/unit/changelog-review-ids.test.ts(아래 README
커밋과 함께).
문제: 메인 세션이 desktop(부하 0.68)에서 8a3b16a의 FE-GATE-008 webkit
실패(i18n.spec.ts:60)를 찾았다. 14.7절은 같은 경고(production-csp.spec.ts:52)를
부하 탓 flake로 적어 두었는데 틀렸다.
방법:
- 13절에 11-09(Medium·P1, 관점 10·21, 고침 aad005cb)를 더했다. 근거는 실패
trace의 시각, 재현 3/10·0/10·2/2, 이전 fixture가 정말 안 쓴 preload를
놓친 probe다.
- 색인·발견 수(94건)·14.4 행을 맞췄다.
- 14.7절의 webkit flake 줄을 지우고 정정을 적었다. FE-GATE-008이 한 번에
통과하지 않을 수 있는 이유는 이제 Firefox 다운로드 건 하나다.
검증: desktop에서 changelog-review-ids test와 verify:documentation.
문제: FE-GATE-008의 test:browser-capabilities가 firefox에서 가끔 30초 시간
초과로 떨어졌다. browser-files.spec.ts의 두 test가 번갈아 걸렸다. 하나는
"filechooser"를, 다른 하나는 "download"를 기다리다 끝났다. desktop에서
firefox capability suite를 30회씩 돌리면 두 test 60건 중 3건이 떨어졌다(두
번 모두). 부하와는 상관없었다(1.05에서도 남). 리뷰 14.7절은 이것을 "알려진
flake"로 두었다(1103/11-10).
원인: 두 test는 `goto("/")` 직후 label·input·button을 `<body>` 끝, 앱 root
뒤에 붙이고 그 button을 누른다. 그때 앱은 아직 그리는 중이다. 실패한 6건의
event 기록(진단 branch, 커밋 안 함)은 모두 같았다.
- pointerdown·mousedown은 button("Choose test file"/"Download generated").
- 30~45 ms 뒤 pointerup·mouseup은 홈 화면 내용("프로젝트 시작점…").
- click은 둘의 공통 조상(앱 root)이라 button의 handler가 돌지 않았다
(`__browserFileResult` 없음). 그래서 picker도 download도 없었다.
- 위치까지 적은 3건에서 그 사이 scrollY는 24로 같았다. body 높이는 744에서 756으로, button top은
696에서 708로 둘 다 12 px 늘었다. 앱 내용이 클릭 도중 12 px 자랐고,
viewport 아래 끝의 button 중앙 좌표가 button 밖이 됐다. 통과한 run은
pointerdown 때 이미 756이었다.
고른 방법: 두 test가 붙이는 control을 `position: fixed` 층(왼쪽 위, 가장
높은 z-index)에 둔다. 앱의 흐름 밖이라 앱이 늦게 그려도 button이 움직이지
않는다. 제품 코드는 바꾸지 않는다.
버린 대안:
- 앱이 다 그려질 때까지 기다린다. "다 그려짐"을 정할 신호가 없다. 늦게 오는
글꼴이나 내용이 생기면 다시 깨진다.
- `dispatchEvent("click")`이나 `force` click. 신뢰된 사용자 입력이 아니어서
firefox가 file picker를 열지 않는다. test가 증명하려는 것을 지운다.
- 재시도·timeout 늘리기·worker 줄이기. 금지된 우회이고 원인이 남는다.
위험·한계: 고정 층이 앱 header 왼쪽 위를 덮는다. 두 test는 앱 UI를 누르지
않는다. 다른 capability spec은 body에 control을 붙이지 않는다(grep).
검증 (desktop):
- RED(커밋 안 한 재현): mousedown 때 앱 root에 400 px를 더하고 layout을
다시 계산한다(앱이 늦게 그리는 것과 같은 일). 수정 전 spec은 세 엔진 두
test 6/6 실패(filechooser·download 대기 시간 초과).
- GREEN: 같은 재현에서 수정 뒤 6/6 통과.
- 실제 조건 firefox capability suite ×30: 수정 전 두 번 다 3 failed /
657 passed, 수정 뒤 660 passed.
문제: ee37dd86(1103/11-10)이 firefox에서 FE-GATE-008을 가끔 떨어뜨리던
capability test의 구조를 고쳤는데 CHANGELOG에 없었다.
방법: 게이트·드릴 행의 11-09 문장 뒤에 이어 적었다.
검증: desktop에서 changelog-review-ids test(README 커밋과 함께).
문제: 메인 세션이 desktop(ee7e195, 부하 0.96)에서 FE-GATE-008의 firefox
capability 실패를 다시 찾았다. 14.7절은 같은 실패(browser-files 다운로드
test)를 부하 탓 flake로 적어 두었는데 틀렸다.
방법:
- 13절에 11-10(Medium·P1, 관점 10·21, 고침 ee37dd86)을 더했다. 근거는
진단 event 기록 6건(mouseup이 홈 화면 내용), 위치 기록 3건(scrollY
그대로, body·button 12 px 아래로), ×30 재현 3/60 두 번이다.
- 색인·발견 수(95건)·14.4 행을 맞췄다.
- 14.7절의 Firefox 줄을 지우고 정정을 적었다. "FE-GATE-008이 한 번에
통과하지 않을 수 있다"는 줄도 지웠다.
검증: desktop에서 changelog-review-ids test와 verify:documentation(scoped).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
리뷰 세 건에서 찾은 문제를 고친다.
7db32e1에서 고쳤고e40684b로 합쳤다.048f490). 실행 경로는 V3 실행기 하나다.0929/03-03도 고쳤다.발견별 상태와 커밋은
docs/reviews/2026-11-03-maturity-review/README.md14.4절에 있다.고른 방법과 버린 대안
2026-11-03 리뷰의 결정 6건이다. 표와 이유는 리뷰 README 14.2절에 있다.
f800549)commandEffect.refusedBeforeWritecode 목록을 둔다(1e8b3d0)ba2b4f4). 지금 pin은45d2a478이다조치 중에 정한 것:
create:feature와 기능 제거 드릴이 커밋된public/release-manifest.json을 다시 쓴다(799ab7f).c15345c). capability e2e가 60번 중 7번 떨어졌다. 다시 쓰기 방식은 60번 중 0번이다.aad005c). 제품 코드는 그대로다.ee37dd8).위험과 영향
!가 붙어 있다.CHANGELOG.md미출시 절 "먼저 할 일"에 있다.048f490)298201f)12f3bb7)b96d61d)CHANGELOG.md미출시 절의 [계약] 행이다.dependency-change-evidence.json에 owner가 아닌 reviewer가 필요하다.EXAMPLES_PLATFORM)을 끌 수 없다. 기능으로 옮기면 lab 측정이 443 ms로 실패한다.POST /v1/files가Idempotency-Key를 읽지 않는다. 결과 불명 뒤 다시 보내면 파일이 둘 생길 수 있다.--with-create기능 하나(약 +964 B)를 넣으면 약 860 B가 남는다.test:feature-scaffold가 길다. FE-GATE-020은 desktop에서 1,151초 걸렸다. 이 job의 상한은 45분이다.test:system의 provider 샌드박스 테스트 18건이 돌지 못했다(아래 "검증"). 러너 컨테이너가 user namespace를 막으면 FE-GATE-013이 같은 이유로 실패한다.0a00a5d~01b9def) 단위로 보면 된다.검증
8a44226에서 merge 단계 게이트 14개를corepack pnpm ci:gate FE-GATE-NNN으로 하나씩 돌렸다..claude/worktrees가 없는 checkoutCI=true,VITE_COMMIT_SHA(40자리),VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGE(형식만 맞춘 가짜 digest).SOURCE_DATE_EPOCH는ci:gate가 HEAD에서 만든다.007, 009012GATES=008만 3번 연속 통과(V3 세션)test:system114건 중 96건 통과, 18건 실패. 18건 모두 bwrap이 loopback을 만들지 못한 환경 실패(RTM_NEWADDR: Operation not permitted)다. 013의 나머지 명령 7개(verify:reproducible-build,build:release-candidate,verify:local-evidence, supply-chain fixture 둘, security fixture,check:browser-security)는 같은 env로 따로 돌려 모두 통과했다FE-GATE-013의 18건은 노트북 깨끗한 clone
c7c7887(같은 env)에서 통과했다. 그 뒤test:system범위(scripts/,tests/system/,config/)에서 바뀐 파일은scripts/lib/build-environment.ts와scripts/create-feature.ts둘이다.8a44226에서 이 18건은 돌리지 않았다.실행하지 않은 것:
8a44226에서 bwrap 샌드박스가 필요한test:system18건리뷰어가 볼 곳
git log --oneline main..HEAD | grep '!:'로 13건을 볼 수 있다.7db32e1,5d0f8451e8b3d0,3fba68bf800549,20a5b08config/contracts/backend-contract-pin.json—ba2b4f4,5379c80af312deb693600799ab7faad005c(tests/support/browser/preload-use.ts), 11-10ee37dd8298201f,1b8cb12,f8878170a00a5d~01b9def). 합칠 때 생긴 것은 리뷰 README 14.3절에 있다.관련
docs/reviews/2026-11-03-maturity-review/README.mddocs/reviews/2026-11-01-maturity-review/README.md13·14절docs/reviews/2026-11-01-ui-design-audit.mdCHANGELOG.md미출시 절docs/manual/README.mdclean-architecture-backend-template45d2a478(pin)max-width 8.5rem과 7rem 때문에 모든 언어에서 선택값이 잘렸다 ("Light then", "Englisl", "라이트 테ㅁ"). 커밋된 시각 골든에도 잘린 머리글이 들어 있어, 시각 테스트가 결함을 정답으로 지키고 있었다. 고정 폭을 지웠다. 좁은 화면은 기존 메뉴 서랍 배치가 그대로 맡는다. 새 i18n e2e 테스트가 ko-KR, en-US, en-XA에서 선택 상자 폭을 브라우저가 옵션에 필요한 폭과 비교한다. 위험: 중간 폭에서 머리글이 넓어진다. responsive·app-shell·theme·compact 테스트가 통과했다. 검증: 새 테스트가 고치기 전 실패했고, 고친 뒤 chromium·firefox·webkit 모두 통과했다.문제: cgroup 테스트("applies effective aggregate cgroup limits ...")는 `await execution.completion` 뒤에 `showProcessArguments(child.pid)`로 supervisor의 argv를 다시 조회한다. completion은 child의 `close`에서 풀리고, 그때 Node는 이미 child를 회수했다. `/proc/<pid>/cmdline`도 `ps -p`도 실패해서 이 테스트는 부하와 관계없이 항상 `ps failed: `로 끝난다. 바로 위 주석은 "아래는 실행 기록을 읽는다"고 적어서 코드와 반대로 말했다. 완료 전의 live 조회(`:793`)도 provider가 1.5초 뒤 끝나므로 부하가 있으면 같은 이유로 실패할 수 있다. 고른 방법: 이미 있는 샘플러 `recordProviderProcessTree`가 5ms마다 supervisor 자신의 argv도 읽어서, 서로 다른 값을 모두 기록한다. 완료 전 live 조회와 완료 후 조회를 이 기록으로 바꿨다. 단언은 줄이지 않았다. - supervisor argv에 command와 credential이 없다(`:793`의 정규식 그대로). - 기록에 `run-and-validate-provider.ts`가 있다. 기록이 비어서 위 단언이 공짜로 통과하는 경우를 막는다. - 실행 중 `process.title`로 argv를 바꿔도 값마다 남기므로, 순간 한 번을 본 live 조회보다 넓게 본다. 버린 대안: - 완료 후 조회 줄을 지운다: supervisor argv 검사가 사라진다. - 완료 전 스냅샷을 한 번 더 찍는다: `:793`과 같은 방식이라 부하에서 provider 종료와 경쟁한다. - `ps` 실패를 무시한다: 결함을 숨기고 검사가 공짜로 통과한다. 위험·한계: 샘플링 간격(5ms)보다 짧게 바뀌었다 돌아오는 argv는 놓칠 수 있다. 다른 프로세스 기록과 같은 한계다. 이 테스트는 base fixture가 `corepack pnpm build:release-candidate`를 부르므로 worktree에서 실행하지 않았다. `-t 'aggregate cgroup'` 반복 실행과 `test:system` 전체 통과는 메인 checkout에서 확인해야 한다. 검증: - RED: 게이트 로그 test_system.log(d99301b, 메인 checkout 실행)에서 이 테스트가 `Error: ps failed: `로 `:810:7`에서 실패. 2 failed / 110 passed. d99301b..402e1db 사이 scripts·tests/system 변경 없음. - 메커니즘: 테스트 파일에서 `readProcessArguments`·`showProcessArguments`· `recordProviderProcessTree` 원문을 잘라 타입만 지우고, 수명이 짧은 child에 돌렸다(scratchpad/fix-11-01/recorder-check.mjs). - 수정 전 20회: close 뒤 조회 실패 20, supervisor argv 기록 0, 실행 중 title 유출 기록 0 - 수정 후 20회(loadavg 1.6): 조회 실패 20, 기록 20, 유출 기록 20 - 수정 후 30회, busy loop 20개(loadavg 17.9): 기록 30, 유출 기록 30 - `npx tsc --project tsconfig.test.json --noEmit`, `tsconfig.node.json` 통과. `npx eslint tests/system/ci-runner/ci-artifact-contract.test.ts` 통과. Fixes:5cc41467ae("refactor: 프론트 템플릿 리펙토링") Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-01문제: UI-03 규칙은 source.includes(`var(${token}`)로 독자를 찾는다. "var(--field-border"가 var(--field-border-invalid) 안에도 있어서, 독자가 0곳이던 --field-border를 통과시켰다. 주석 안의 var(--x)도 독자로 셌다. 그리고 이번 브랜치의 디자인 규칙 4개(포커스 대비, oklab 혼합, 토큰 사용, 첫 글꼴)는 스크립트 본문에 바로 있어서, 규칙을 꺼도 잡는 테스트가 없었다(12-02). 고른 방법: - 규칙 4개를 scripts/lib/design-system-rules.ts의 순수 함수로 옮긴다. 입력은 CSS 글자와 토큰 맵이고 출력은 실패 메시지다. 메시지 문구와 순서는 그대로다. - 토큰 독자는 var(--name) 또는 var(--name, ...)처럼 이름 전체가 맞아야 한다. "var"는 대소문자를 무시하고, 사용자 정의 속성 이름은 CSS 규칙 대로 대소문자를 구분한다. - 토큰 사용 규칙과 oklab 혼합 규칙은 CSS 주석을 지우고 본다(리뷰 probe B5 우회, B12 오탐). - oklab 혼합 규칙은 대소문자를 무시한다(B1 `in OKLCH` 우회). CSS 키워드는 대소문자를 구분하지 않는다. - ui-design-audit.md의 UI-03 행에 다섯 번째 토큰을 적는다. 버린 대안: 12-02가 제안한 --root 인자와 CSS 음성 fixture 폴더. 규칙별 검출을 증명하려면 어차피 실패 메시지를 단언하는 테스트가 필요하고, 순수 함수 단위 테스트가 fixture 파일 없이 같은 것을 증명한다. 게이트의 --fixture 모드와 산출물 스키마는 바꾸지 않았다. 위험·한계: - 주석 제거는 정규식이라 따옴표 문자열 안의 "/*"를 주석 시작으로 본다. 지금 CSS에는 없다. - 12-03의 나머지 우회(그라디언트, TSX 인라인, base.css 재정의, outline-offset 0, feature CSS)와 12-04의 오탐(-apple-system, deg, 알파, color-mix 표면)은 그대로다. 포커스·글꼴 규칙은 주석을 지우지 않는다. - 게이트의 check:design-system:fixture는 여전히 TSX fixture 두 개만으로 "기대 실패"를 채운다. CSS 규칙 회귀는 test:unit이 잡는다. 검증: - RED(규칙을 동작 그대로 옮긴 상태): tests/unit/design-system-rules.test.ts 11개 중 5개 실패. "does not count a longer token that starts with the same name"이 "expected [] to deeply equal [ Array(1) ]"로 실패했다. 나머지 4개는 대문자 OKLCH, 주석 안 혼합, VAR( --x , ...) 형태, 주석 안 독자. - 고친 검사를 앞 커밋 전 CSS(402e1db)에 돌리면 "component token --field-border is defined but no style reads it"으로 실패했다. - GREEN: 같은 파일 11/11 통과. tests/unit 166파일 2364개 통과. - 변이: 대비 기준 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건 통과로 바꾸면 규칙마다 실패 테스트가 하나 이상 깨졌다(7/11 실패). - check:design-system PASS, --fixture는 기대대로 실패. tsc(app, node, test) 통과, 바꾼 파일 eslint 통과, verify-documentation PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01, 12-02문제 참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다 (reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은 멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은 409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고 conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을 지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시 열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번 생긴다(키 [K, K, K']). 고른 방법 분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code (CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT" 하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의 409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고 있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다. 시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과 "충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다. 버린 대안 - IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속 NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면 같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다. - 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도 APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가 틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조 변경이다. 이번 범위를 넘어 뺐다. - 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED 목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이 응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선 요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을 만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다. 위험·한계 - 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state- contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만 적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로 고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝 백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드 템플릿 소유자. - problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라 Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory). 참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면 referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만 code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다. - 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다 (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이 이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다. "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다. - 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드 확인). 동기화 때 같은 수정이 필요하다. - 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와 run-http-scenario-evidence.ts 출력 문구를 맞췄다. - 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로 두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다. 검증 - RED(수정 전): reference-production-vertical "keeps the key when the resend meets the first attempt still in flight" 실패, 키 [K, K, K']. 분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'" (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음). 카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치. - GREEN: 같은 세 파일 23/23 통과. - 회귀: run-vitest tests/features tests/component tests/contract tests/integration tests/unit(pnpm을 띄우는 security-followup-archive 제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED. - 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을 읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다. check:ci 미실행. Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서 responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를 display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과 정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이" 조건을 어긴다. 고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상 테마 선택·세션 상태(탐색 아래)를 넣는다. - 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect, SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다 기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다. - 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지 않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다). - 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다. 그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다. - 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에 "홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다. - 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신 보여 준다는 주석을 달았다. 버린 대안: - 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고 320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다. - 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은 항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이 이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다. - 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존 접근성 이름과 테스트가 깨진다. 위험·한계: - 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는 한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌 dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는 strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로 좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다. - 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을 스크롤해야 보인다. - 좁은 화면 서랍 화면이 바뀐다. 시각 골든 app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다. - 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은 pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와 gzipSync로 직접 쟀다. - 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다. 검증: - RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전 chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' }) .getByRole('combobox', { name: '색상 테마' }): element(s) not found. - GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에 닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과 브랜드가 보인다. - 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route (세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의 Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는 reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다. - 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함). - node scripts/run-vitest.ts run tests/component: 211/211 통과. - tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS. - Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로 돌렸다(빌드는 node scripts/build-frontend.ts). Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01문제 guardian 테스트는 자식을 띄우자마자 절대 마감(Date.now() + 350)이 든 가드를 보낸다. 그래서 lease가 프로세스 기동 시간까지 낸다. 1코어에서 기동이 350ms를 넘으면 guardian이 가드를 마감 지남으로 거부하고, 테스트는 5초 뒤 "deadline guardian READY timed out"으로 실패한다(수정 전 1코어 재현 9회 중 4회). 같은 구조가 2~3초 lease를 쓰는 테스트 5곳에 있다. near-timeout 테스트는 READY 뒤 1초를 고정으로 자서, 기동이 길면 publish·commit에 남는 시간이 줄어든다. 자식 기동을 기다리는 poll 세 개(waitForFile, waitForNewDirectChild, waitForStoppedProcess)는 1초 마감을 쓴다. 파일 머리의 watchdog 설명("1초 요구를 넣지 않는다")과 어긋난다. 고른 방법 - spawnGuardian이 실제 guardian을 import하는 래퍼로 띄운다. import가 끝나면(bootstrap과 stdin reader 등록까지 끝난 시점) 래퍼가 여분 pipe (fd 7)에 1바이트를 쓰고 닫는다. 새 sendGuard는 이 신호를 받은 뒤에 마감을 계산해 가드를 보낸다. 가드를 보내는 6곳이 모두 sendGuard를 쓴다. guardian 코드와 프로토콜, 350ms·2s·3s lease 값은 그대로다. - near-timeout 테스트는 startProviderGuardian 호출 직전 시각에서 1초 뒤에 깬다. 클라이언트가 spawn 뒤에 마감을 찍으므로 마감은 그 시각 + 2초 이후다. 기동이 길어도 publish·commit에 1초가 남는다. - 1초 poll 세 개는 같은 파일의 watchdog(5초)을 쓴다. 자식 기동에는 기다릴 이벤트가 없어 poll이 남는다. - 같은 종류 guardian 두 개 테스트는 패자가 클라이언트의 고정 5초 READY 제한(RESPONSE_TIMEOUT_MS)으로만 거부된다. 테스트가 줄일 수 없는 고정 대기라 파일의 PROCESS_HEAVY_TIMEOUT_MS를 붙이고 이유를 주석에 적었다. 버린 대안 - lease를 늘리기: 기동 시간에 상한이 없어 같은 문제가 더 드물게 남는다. 350ms 테스트는 만료를 기다리는 시간도 길어진다. - marker 파일 + poll로 준비 신호: 파일 시스템 poll에 다시 마감이 필요하다. pipe는 이벤트로 끝나고 provider-evidence 목록 단언에 끼어들지 않는다. - guardian 프로세스에 가짜 시계 주입: 자식 프로세스라 테스트용 훅을 운영 스크립트에 넣어야 한다. 위험·한계 - spawnGuardian 경로의 guardian은 main 모듈이 아니라 래퍼가 import한 모듈로 돈다. guardian은 argv·import.meta를 읽지 않는다. 래퍼는 신호를 보낸 뒤 fd 7을 닫으므로 가드를 받는 시점의 상속 fd(0~6)는 운영과 같다. 클라이언트 경로 테스트는 그대로 실제 스크립트를 직접 띄운다. - 가드를 보내기 전 기동 대기는 watchdog 5초가 상한이다. 남은 실제 시계 구간은 가드 처리(decode, link, fsync, READY)뿐이다. - 따로 남는 결함(이 커밋 범위 밖): guardian은 가드를 거부하거나 link가 실패하면 failClosed가 진단을 쓰지만, stdin 읽기가 걸려 있는 동안 종료하지 않는다. 탐침: 만료된 가드를 받고 1,008ms에 진단을 쓴 뒤 stdin을 닫은 4,014ms에야 126으로 끝났다. 그래서 클라이언트에서는 거부가 즉시 오지 않고 5초 뒤 "READY timed out"이 된다(leaseMs 1과 동시 guardian 탐침 5,018~5,053ms). 위 PROCESS_HEAVY_TIMEOUT_MS는 이 결함이 고쳐지면 뺄 수 있다. 검증 - RED(수정 전, taskset -c 0, --maxWorkers=4): component·features· integration·platform/cardinality 3회 중 2회, 같은 묶음 + 바쁜 이웃 1개 3회 중 2회 "expires an uncommitted lease … deadline guardian READY timed out"(5,035~5,052ms). - GREEN(세 커밋을 합친 상태, taskset -c 0 + 같은 코어의 바쁜 이웃, --maxWorkers=4): 대상 6개 파일 6회, 위 넓은 묶음 5회(이웃 1개) 모두 통과. 이웃 2개로 3회 돌렸을 때 이 파일은 모두 통과했다(실패 1건은 http-execution-v3-live-authority, 0929/10-03). - 기본 코어: tests/unit·component·integration 212파일 2,734개 통과 (pnpm을 띄우는 security-followup-archive, fixture-node-modules, lab-performance 제외). tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md문제 lazy route 화면을 findBy*·waitFor 기본값(1초)으로 기다리는 테스트가 1코어 부하에서 코드와 무관하게 떨어진다. 수정 전 재현에서 runtime-application.test.tsx:65 "Unable to find role=heading name=Clean Architecture Frontend"와 reference-production-vertical.test.tsx:103 "Unable to find role=button name=로그인 시작"이 났다. 두 DOM 모두 route-loading(aria-busy) 상태였다. 지난 리뷰는 router.test.tsx:244-250도 같은 이유로 실패했다고 적었다. React 19는 Suspense를 풀 때마다 실제 300ms 타이머(FALLBACK_THROTTLE_MS)를 기다린다. context route 표와 lazy 페이지를 거치는 화면은 렌더링 전에 1초 중 600ms를 쓴다. 이 사정을 아는 파일만 호출마다 { timeout: 5000 }을 붙이거나(7개 파일 13곳) 파일 단위로 configure를 바꿨다(reference-page). 새 테스트 작성자는 이 규칙을 알 방법이 없다. 고른 방법 tests/setup.ts에서 configure({ asyncUtilTimeout: 5_000 })를 한 번 정하고, 같은 값을 반복하던 호출·파일 단위 override를 지웠다. findBy*·waitFor는 DOM 변화가 오면 바로 끝나므로 기한은 멈춤을 알리는 용도뿐이다. 10초 테스트 제한의 절반이라 진짜 멈춤은 여전히 Testing Library의 DOM 덤프와 함께 실패한다. 기한을 늘리는 방식이라 고른 이유를 setup에 주석으로 남겼다. 버린 대안 - 가짜 시계: Testing Library는 Jest의 가짜 타이머만 알아본다 (jestFakeTimersAreEnabled가 jest 전역을 본다). Vitest 가짜 타이머에서 waitFor는 자기 타이머가 멈춰 끝나지 않는다. MSW와 user-event도 실제 시계로 돈다. - route chunk를 테스트에서 미리 import하기: chunk를 받아도 React의 300ms reveal 타이머와 렌더링 비용은 그대로 기한 안에 남는다. 테스트가 route 모듈 목록을 따로 알아야 한다. - 실패한 파일에만 timeout 붙이기: 지금 상태와 같다. 다음 lazy 화면 테스트에서 같은 실패가 반복된다. 위험·한계 - 기다리다 실패하는 테스트는 실패까지 1초가 아니라 5초 걸린다. 부재를 findBy·waitFor의 실패로 확인하는 테스트는 없다(grep으로 확인). - 가짜 타이머를 쓰는 테스트의 waitFor는 이 값과 무관하다(가짜 시간). 검증 - RED(수정 전, taskset -c 0 + 같은 코어의 바쁜 이웃 1개, --maxWorkers=4, component·features·integration·platform/cardinality): 3회 중 1회 위 두 테스트 실패. - GREEN(같은 조건): 대상 6개 파일 6회, 넓은 묶음 5회 모두 통과. 바쁜 이웃 2개로 3회 돌렸을 때도 이 커밋이 다루는 테스트는 모두 통과했다. 넓은 묶음 한 번의 시간은 RED 91~111s(실패가 몰린 209s 회차 제외) -> GREEN 86~88s다. - 기본 코어: tests/unit·component·integration 212파일 2,734개, features· platform·architecture·contract·runtime-schema 60파일 403개 통과. tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md문제 guardian은 fd 0을 fs.createReadStream으로 읽는다. 이 스트림은 libuv 스레드 풀의 스레드 하나를 read(2)에 세워 둔다. process.exit()는 종료 전에 스레드 풀을 join하므로, 그 read가 돌아올 때까지(부모가 stdin을 닫을 때까지) 끝나지 않는다. 그래서 가드를 거부하거나 link가 실패하면 failClosed가 진단을 바로 쓰고도 프로세스는 남는다. 클라이언트는 stdin을 연 채 READY를 기다리므로 거부가 즉시 오지 않고 고정 5초 뒤 "READY timed out"으로 끝난다. 같은 종류 guardian 두 개 테스트의 패자가 이 경로다. 탐침: 같은 종료 코드를 fs 스트림은 stdin을 닫은 2,008ms에, net 소켓은 228ms에 냈다(200ms 뒤 exit 호출). 고른 방법 - liveness 입력을 process.stdin으로 바꾼다. pipe면 Node가 이벤트 루프로 읽는 net.Socket을 만든다. 스레드 풀 read가 없어 exit가 바로 끝난다. data/end/error 처리, removeAllListeners·destroy, closeSync(0)는 그대로다 (libuv는 fd 0~2를 destroy에서 닫지 않는다). - 동시 guardian 테스트에 붙였던 PROCESS_HEAVY_TIMEOUT_MS와 그 주석을 뺀다. 패자가 link 실패 즉시 끝나 테스트가 5.14초에서 0.16~0.54초가 됐다. 버린 대안 - provider-scope-wrapper.ts처럼 new Socket({ fd: 0 }): fd 0이 pipe가 아니면 생성자가 throw한다. guardian은 그 시점에 이미 private alias를 묶었고 failClosed는 liveness가 있어야 돈다. process.stdin은 pipe에서는 같은 Socket이고, 그 밖의 fd에서는 throw 대신 end/error로 기존 실패 경로(125)를 탄다. - 실패 때 SIGKILL로 자신을 죽이기: 종료 코드 124~126 계약이 사라진다. 위험·한계 - pipe인 fd 0에 O_NONBLOCK이 걸린다. 읽기 끝은 guardian만 가진다 (클라이언트는 stdio "pipe"로 띄운다). - lease 마감 경로는 원래 SIGKILL을 쓰므로 바뀌지 않는다. 검증 - RED(수정 전): 새 테스트 "exits on a rejected guard while the parent still holds its input open"이 "rejected-guard guardian exit timed out" (5,122ms)으로 실패. 다른 nonce의 가드를 보내 시계와 무관하게 거부시킨다. - GREEN: tests/integration/provider-guardian-transaction.test.ts 22/22 통과, 3회 반복 통과(새 테스트 65~333ms). tests/unit/task3-selective- integration 7/7. tsc(tsconfig.node, tsconfig.test) 통과, 바꾼 파일 eslint 통과. - 미실행: tests/system/ci-runner/ci-artifact-contract.test.ts의 provider 체인 테스트. fixture가 corepack pnpm으로 빌드해서 이 worktree에서는 돌리지 않았다. Refs: commitc862004위험·한계의 "따로 남는 결함"문제 디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는 색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로 센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는 시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은 "--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이 무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만 있다. 고른 방법 - parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다. - oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가 그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is <값>; contrast needs an opaque oklch(L C H), hue in degrees with or without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다. - 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다. - docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식, 검사 위치를 표 하나로 적는다. 버린 대안 - color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지 규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로 해결 형식을 알린다(리뷰 대안 비교와 같다). - 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에 새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할 곳이 없어 실패한다"로 적었다. - rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다. 위험·한계 - 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다. - 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다. - 화면 변화 없음. CSS를 바꾸지 않았다. 검증 - RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개 실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [], "names the value it cannot compute …" 메시지 불일치, "-apple-system" expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected null. - GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트 probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를 oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0 / 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS. - tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify- documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04문제: 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문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한 주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus· pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다. optional-runtime-host.ts도 같은 말을 한다. 실제로는 - telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다 (telemetry-collector.ts onPageExit). - 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를 단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외). - lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는 없다. 또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache 복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가 살아남았다. 고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에 구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다. tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation, visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt, dispose 뒤 0개를 확인한다. 버린 대안: - (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을 만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야 해 이번 범위를 넘는다. - (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에 비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다. 위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다). src 동작은 바뀌지 않는다. 검증: - RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide, browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인. - RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를 모두 잡는다. K3(generation += 1 제거) → "expected {...} to match object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) → "expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0", dirty 검사 제거 → preventDefault "to not be called". - 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters 3파일 30/30 통과. tsc app·test 통과, eslint 통과, check-adapter-inventory PASS. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다. chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable && !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안 ACCOUNT_DELETION purge를 부르면 {removedObjects: 0, moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와 chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once every object is removed"라고 약속하고 runbook도 COMPLETED를 완료 조건으로 적는다. 고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로 두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다 (chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에 맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음 페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고, PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의 moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다. 버린 대안: - skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0 그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고 번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다. - 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다. 위험·한계: - offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B. 예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04). - 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막 페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다 지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적 방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만 확인했고 실행하지 않았다. 동작 변경이라 범위 밖. - 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다. 검증: - RED: opfs-worker-runtime "reports a purge that skipped a changing object as unfinished"가 `- "moreObjectsAvailable": true` `+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸 chunkSweep 존재). - GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1, chunkSweep COMPLETED, partition 파일 0개로 끝난다. - 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal, indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker· recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED, check-optional-recipes PASS. Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md문제 HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로 실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의 apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는 parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서 V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가 통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서 실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다. 고른 방법 (리뷰 5.1절의 B, 1단계) - 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와 V2만 있는 API가 각각 실패한다. - 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3 commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로), 요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id (V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator), 응답 스키마 id(V2 responseSchema ↔ V3 outputValidator). - V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와 대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을 정하라고 알린다. 지금 설치된 operation에는 없다. - RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는 게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다. 버린 대안 - V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고 V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조 변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은 defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은 생겼다. - "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서 이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합 비교가 한쪽만 빈 경우를 잡는다. - 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기: fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이 parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다. 위험·한계 - 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지 않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다. 주석에 비교하지 않는다고 적었다. - 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔ zod DTO 차이는 여전히 대조하지 않는다. - 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이 파일을 돌려야 걸린다. 검증 - RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다. L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를 ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패 ("responseSchema": "ReferenceResourcePayload" vs "...V2"). L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트 "cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY"). - GREEN: 변이 없이 2/2 통과. - 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과 함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐). Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md문제 MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의 MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고 부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는 { ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름 MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을 요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper, 참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거 조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수 없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다. eslint 설정에 폐기 검사가 없다. 고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로) - boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry, mappingSuccess, mappingFailure와 바인딩 mapSuccess가 BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도 옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서 런타임과 공개 시그니처는 바뀌지 않는다. - D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은 BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가 필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는 같은 type의 alias" 문장도 고쳤다. - 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어 @typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core no-restricted-imports의 patterns.importNames로 boundary-mapper의 MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다. 층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로 restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은 그 앞에 둔 공통 블록이 받는다. 버린 대안 - 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2) 후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상 공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0, lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다. - typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint 설정(속도·설정 범위)이 필요하다. - 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유 문자열로 넓어져 계약이 약해진다. 위험·한계 - 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭). 리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야 충족된다. 제거 시점은 릴리스 결정으로 남긴다. - 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint 오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데, 반환 타입은 같은 모양이라 영향 없음). - adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다. 같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다. 검증 - RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors ("'MappingResult' import from '../../contracts/boundary-mapper.ts' is restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure 같은 꼴). - GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일) --max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep). - 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit tests/features tests/platform tests/component tests/contract tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외) 273 files / 3136 tests 중 3135 통과. 실패 1건은 provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이 변경과 무관한 scripts/lib 프로세스 테스트). check-registries PASS, verify-documentation-readiness PASS_SCOPED, check-adapter-inventory PASS. - 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로 사실상 미검증. Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md문제 레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS 타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로 판정한다. null과 문자열은 타입이 달라서, governance가 string|null로 선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도 breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도 어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에 "마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID defaultValue null -> "local-build"에 "the value itself did not change"라고 적은 breaking 증거를 남겼다. 고른 방법 (리뷰 최소 개선 B) - 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입 (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라 field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나 선언 밖 값이면 지금처럼 field-type-changed(breaking)다. - contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두 포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나, 새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지 contract 변경도 그대로 breaking이다. - 선언 타입 판정은 check-registries.ts에 있던 runtimeType· matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다. - semantic-diff.json fixture에 nullable-field-cleared(behavior-change), registry-contract-extension(additive)을 더하고 artifact id 목록에도 넣었다. 버린 대안 - 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는 길을 더 넓힌다(0929/07-04). - nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른 레지스트리 영향을 다시 봐야 하는 넓은 변경이다. - 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰 기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로 breaking에 남겼다. 위험·한계 - fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능 꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다. paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다. - 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서 behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행 (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는 0929/07-01 범위라 이번에는 지우지 않았다. - 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이 바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번 라운드는 CHANGELOG 미출시 절이 없어 적지 않았다). - fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아 계속 breaking으로 남는다. 검증 - RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패 (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의 kind, allowlist 확장 breaking). check-registry-compatibility-fixtures: nullable-field-cleared actual breaking, registry-contract-extension actual breaking. - GREEN: registry-compatibility·registry-governance·release-artifacts· second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS. check-registries "11 registries PASS"(남은 breaking은 REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음). ci-artifact-contract "semantic validator" 사례 통과. - 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0. - 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian exit=126 환경 문제로 이 변경과 무관하게 실패). Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md문제 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문제 전송 전 실패가 네 곳에서 원인 없는 위반 FINAL_REQUEST_INVARIANT_FAILED 하나로 바뀐다. 입력 검증 실패, 요청 조립 실패 10종(PATH_PLACEHOLDER_MISSING 등), 최종 불변식 실패 12종, 미설치 계약이다. 바인딩은 이 위반과 MISSING_IDEMPOTENCY_KEY·UNEXPECTED_IDEMPOTENCY_KEY를 모두 VALIDATION_REJECTED로 바꿔 "서버가 입력값을 받아들이지 않았습니다"를 띄운다. 그래서 경로 placeholder 오타나 mutation 정책과 계약의 불일치 같은 개발자 연결 실수가 사용자 입력 문제처럼 보이고, 진단에는 원인이 없다. 미설치 계약은 실행기를 거치지 않아 진단이 0건이다. 또 마감이 시도별 budget 읽기와 최종 불변식 검사 사이에 끝나면 DEADLINE_EXPIRED도 같은 위반이 되어, 시간 초과가 "입력 거절"로 보인다(P-03-05). 고른 방법 - HttpContractViolation에 선택 필드 reason(닫힌 집합 HttpRequestRejectionReason)을 더한다. 실행기의 세 거절 지점이 refusedRequest(reason)로 위반을 만들고, finish()가 그 reason을 관측의 diagnosticReason으로 옮긴다. projector는 03-05에서 만든 경로대로 diagnostics에만 reason을 싣는다. telemetry는 error_kind 그대로다. - 최종 불변식의 DEADLINE_EXPIRED는 budget 읽기 분기와 똑같이 TRANSPORT_FAILURE/TIMEOUT으로 끝낸다(P-03-05). - 바인딩은 사용자가 입력을 바꿔 고칠 수 있는 거절(INPUT_INVALID, PATH_VALUE_INVALID, QUERY_TOO_LARGE, URL_TOO_LARGE, REQUEST_BODY_TOO_LARGE)과 reason 없는 거절만 VALIDATION_REJECTED로 둔다. 나머지 reason과 멱등 키 위반은 UNKNOWN_CLIENT_FAILURE(문의 행동, "요청을 처리할 수 없습니다.")로 낸다. V2 client가 미등록 operation을 같은 종류로 내는 것과 맞췄다. - 미설치 계약 분기는 같은 projector로 관측 1건(reason CONTRACT_NOT_INSTALLED)을 직접 남긴다. 버린 대안 - 새 FailureKind 추가: 오류 레지스트리·i18n 카탈로그·화면 분기를 다 바꿔야 한다. 이미 있는 UNKNOWN_CLIENT_FAILURE가 "클라이언트 결함, 문의"라는 같은 뜻이고 V2에서 같은 상황에 쓰고 있다. - 리뷰 예시대로 MAPPING_CONTRACT_VIOLATION으로 내기: 문구가 "서버 응답을 화면 데이터로 바꾸지 못했습니다"라 응답이 없는 전송 전 실패와 맞지 않는다. - 사용자 입력 쪽을 reason별 Record로 망라하기: 컴파일 시 분류를 강제하지만 20여 줄이 는다. 새 reason은 기본으로 클라이언트 결함이 되는 쪽이 안전하므로 입력 쪽 5개만 Set으로 적었다. - terminalReason에 원인을 싣기(리뷰 문구): 03-05와 같은 이유로 버렸다. 위험·한계 - 동작 변경: 멱등 키 위반과 연결 실수가 VALIDATION_REJECTED에서 UNKNOWN_CLIENT_FAILURE로 바뀐다. 폼은 필드 오류 대신 "unavailable" 상태 안내를 띄운다. 기존 계약 테스트의 기대값을 이에 맞게 바꿨다. - 입력 검증 실패(INPUT_INVALID)는 리뷰 문구("입력 크기 초과만")와 달리 VALIDATION_REJECTED로 남겼다. 입력 validator의 거절은 사용자 입력 문제다. - reason 없는 FINAL_REQUEST_INVARIANT_FAILED(다른 실행기 구현)는 기존대로 VALIDATION_REJECTED다. - AppFailure.code는 지금처럼 위반 종류다. 원인 코드는 진단에만 있다. - 공개 타입은 추가만 했다(위반 선택 필드 1개, 진단 reason 집합 확장). - validator가 throw하는 경우(VALIDATOR_RUNTIME_FAILURE → SCHEMA_MISMATCH, "서버 응답 데이터가…" 문구)는 이번 범위가 아니라 그대로다. - 미설치 계약 거절도 다른 CONTRACT_VIOLATION처럼 api.request.failed telemetry 1건을 낸다(VD-07 규칙 5). - 화면: 정상 상태는 그대로이고 위 실패에서만 문구가 바뀐다. 시각 골든은 다시 찍지 않았다. 검증 - RED(수정 전): - http-execution-v3-observability "names a refused request's assembly cause in diagnostics only (03-02)": violation.reason 없음. - 같은 파일 "ends a deadline that expires at the final invariant check as a timeout (P-03-05)": TRANSPORT_FAILURE 기대, 실제 CONTRACT_VIOLATION. - feature-http-binding 계약 테스트 5건: PATH_PLACEHOLDER_MISSING, CONTRACT_NOT_INSTALLED, HEADER_NOT_ALLOWED, MISSING_IDEMPOTENCY_KEY, UNEXPECTED_IDEMPOTENCY_KEY가 VALIDATION_REJECTED로 나옴. - runtime-adapters-auth-profile "is refused without a fetch and leaves one diagnostic naming the cause": reason 없음, 진단 0건. - GREEN: 세 파일 38/38 통과. - 회귀: run-vitest tests/unit tests/integration tests/component tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일 13개 제외) 227 files 중 226 통과, 2354/2355. 실패 1건은 provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의 다른 실행 때문)로 HTTP와 무관하다. 제외했던 http-scenario-evidence는 pnpm을 띄우지 않아 따로 돌렸고 14/14 통과. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED. - 미실행: check:architecture(pnpm 스크립트 필요), 번들 크기 측정. Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md문제 QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무 숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지 보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로, namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는 저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query namespace는 registry reference"라고 적지만(client-cache-and-storage.md), 참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다. 고른 방법 - 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added" 이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를 읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번 cache.operation.failed(operation: unregistered-query-namespace) 진단을 남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고 있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다. - 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을 더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수 QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은 상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면 coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state 청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17). - 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의 QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록 객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다. 버린 대안 - 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를 깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개 포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다. - useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드 추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는 못 본다. - 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack 알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을 채운다. - 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을 넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다. 위험·한계 - 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다. - "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan namespace로 거절하므로 여기까지 오지 않는다. - 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다. - useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의 런타임 테스트는 없다. - 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation, BoundQuery.invalidation, 상수 1개). 검증 - RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a bound query whose namespace no registered topic reaches (03-01)" 실패. "expected vi.fn() to be called 2 times, but got 0 times". - GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files / 89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을 넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다. - 회귀: run-vitest tests/unit tests/integration tests/component tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일 12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은 provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의 다른 실행 때문)로 이 변경과 무관하다. tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED. - 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를 gzipSync로 쟀다.298201f202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적 202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다. - 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은 0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts, presentation -> contracts뿐이다. Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md문제 라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지 않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약 (config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는 `/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로 PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과 검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다. 고른 방법 - cache-policy.json에 표면 두 개를 더한다. - appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은 Cache-Control, content-type, 보안 헤더를 요구한다. - serviceWorker: `/service-worker.js`, no-cache, JS MIME. `requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드 (ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은 checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다. - live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨 fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다. appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를 가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를 모두 FAIL로 잡는다. - release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를 적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라 404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을 적었다. 버린 대안 - createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약· 테스트가 모두 바뀐다(리뷰 대안 비교에서 기각). - 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만 읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다. - 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지 않았다. 위험·한계 - nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다. 호스트가 실제로 무엇을 주는지는 live probe가 확인한다. - 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로 실패한다(의도). - 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts 5 failed. "expected undefined to match object { cacheControl: 'no-cache', …}"(정책에 appRoute·serviceWorker 없음), "probeLiveRelease is not a function" - GREEN: 같은 파일 22 passed. fallback 없는 호스트에서 ["appRoute http-status", "appRoute entry-script"]가 실패로 나온다 - node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts: 483 passed - build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3, 결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀 - tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness PASS_SCOPED, check-ci-contract PASS Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04문제 리뷰 라운드마다 발견 ID를 `NN-MM`으로 새로 매긴다. CHANGELOG의 `(14-02)`는 0925 라운드의 "CI 계약 고정"인데, 0929 라운드의 14-02는 "README 업데이트 절차"이고 이번 라운드에도 14-02가 있다. CHANGELOG는 복사한 프로젝트가 변경 근거를 찾는 유일한 링크라 ID가 어느 라운드인지 모르면 다른 결함을 읽게 된다. 리뷰 가이드에 ID 네임스페이스 규칙이 없다. 고른 방법 - CHANGELOG 0.2.0 절의 ID 98개에 `0925/`를 붙였다(`F-N`은 0925 FOLLOW-UP의 ID라 같이 붙였다). 기계적 치환이다: 괄호 안의 `NN-MM`·`F-N`만, 범위(`01-01~01-11`)는 앞에만, 날짜는 건드리지 않는다. 0.1.0 절의 `R-x.y`는 다른 체계라 그대로 둔다. - CHANGELOG 머리말에 `MMDD/NN-MM` 규칙과 F-N의 뜻을 적었다. - 리뷰 가이드 36.3 "ID·제목"에 같은 규칙을 넣었다. 라운드 안에서는 `NN-MM`, 밖에서 가리킬 때는 `MMDD/NN-MM`. 기존 코드 주석 약 339곳은 고치지 않고 새로 쓰는 것부터 붙인다(리뷰의 최소 개선 방향 ③). - tests/unit/changelog-review-ids.test.ts가 CHANGELOG 괄호 안의 라운드 없는 ID를 막는다. 리뷰가 적은 grep 검증을 test:unit 게이트로 옮긴 것이다. 버린 대안 - CHANGELOG 표에 라운드 열 추가: "그 밖의 수정" 목록에는 표가 없어 규칙이 둘이 된다. ID 자체에 붙이는 쪽이 코드 주석·커밋 제목과 같은 형식이다. - 접두어를 `YYYYMMDD/`로: 이미 브랜치의 커밋과 리뷰 README가 `0929/03-01` 형식을 쓴다. 해가 바뀌어 월일이 겹치면 그때 연도를 붙인다. 위험·한계 - 기존 주석과 0.2.0 커밋 제목은 라운드 없는 ID로 남는다(혼재 기간). - 테스트는 괄호 안 쉼표 구분 토큰만 본다. 괄호 밖 본문에 쓴 ID는 잡지 않는다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts 실패 "expected [ '03-03', '03-01', '08-03', …(95) ] to deeply equal []" - GREEN: 같은 테스트 통과. 리뷰의 검증 명령 `grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md` → 0 - eslint, tsc(test), verify-documentation-readiness PASS_SCOPED, check-ci-contract PASS(새 테스트 파일이 test:unit 게이트에 들어감) Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-02문제: SW 자산 생성기(scripts/generate-service-worker-assets.ts)가 사전 캐시 URL을 `/${relative}`로 만들어 VITE_ROUTER_BASE_PATH를 무시했다. 워커는 root-relative URL을 scope 기준으로 풀지만 base가 사라지므로 /app/ 배포에서 install이 /assets/...를 요청해 404를 받고, 워커가 설치되지 않았다. 같은 빌드의 SW 설정도 runtime config URL 기본값을 "/config.json"으로 고정해, 페이지가 쓰는 /app/config.json을 워커가 network-only로 알아보지 못했다. 앱 빌드·runtime config·06-08 fallback은 이미 base를 따르는데 이 두 곳만 빠져 있었다. 고른 방법: 리뷰가 적은 최소 방향. collectStaticAssets에 basePath 인자(기본 "/")를 더하고, 생성기 main과 SW Vite 설정이 페이지와 같은 getBuildConfig(src/contracts/env.ts)로 base와 runtime config URL을 계산한다. 결과 URL은 그대로 root-relative라 isCanonicalStaticAssetUrl 검사를 통과한다. base가 "/"이면 manifest와 digest가 전과 같다. 버린 대안: 워커가 manifest URL을 scope 상대로 풀게 바꾸기. 계약 차이는 없지만 워커 코드와 manifest 계약(root-relative)을 함께 바꿔야 해서 생성기 수정보다 크다. 위험·한계: - base마다 manifest digest가 달라진다(의도된 결과). - VITE_RUNTIME_CONFIG_URL이 빈 문자열이면 이제 base 기본값을 쓴다. 페이지(getBuildConfig)와 같은 규칙이다. - 리뷰 완료 기준의 "e2e 도우미를 base 옵션으로 돌린 첫 설치가 RELOAD_TO_ENABLE"은 하지 않았다. e2e 도우미에 base 옵션과 /app/ 서빙이 필요하고, 실제 브라우저 install은 이번에 확인하지 않았다. 검증: - RED: collectStaticAssets 단위 테스트(basePath "/app/")가 수정 전 `/assets/index-abcdefgh.js`를 받아 실패(1 failed | 9 passed). service-worker-build-output.test.ts의 새 테스트(SW ACTIVE· production·/app/ 실제 빌드)가 생성기만 되돌리면 URL 목록에서, SW 설정만 되돌리면 `Received: "/config.json"`으로 각각 실패. - GREEN: 두 테스트 통과. `node scripts/run-vitest.ts run tests/unit/service-worker tests/unit/sub-path-deployment.test.ts tests/unit/hosting-probe.test.ts tests/unit/web-push` -> 12파일 171건 통과(빌드 테스트는 flock 안에서). - `npx tsc` node·test·app·service-worker -> 오류 0. - `npx eslint <바꾼 파일 4개> --max-warnings=0` -> 통과. - `node scripts/check-adapter-inventory.ts` -> PASS. - 미실행: SW e2e(Playwright). Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-02, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는 `onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는 buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중 throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이 없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의 route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자 신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다. 고른 방법: - `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에 넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존 ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작). - incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두 경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다). - gateway가 두 경계에 `reportRenderFailure` 호출과 `<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는 `component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에 context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다. - 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를 탄다. route id는 URL의 등록 라우트, 없으면 context id다. 버린 대안: - 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계 두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시 (`data-boundary`, testid)가 바뀐다. - gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기: 두 경계가 같은 id를 공유해 사건 구분이 흐려진다. - `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과 레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다. 위험·한계: - `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로 buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식 (useRouteError + 마운트 시 보고)이 필요해 남겼다. - 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다 한 번 보고한다. - 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의 지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다. - 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B). 검증: - RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context 경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이 모두 `Unable to find an element with the text: /^지원 참조: build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다. - GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한 incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가. - 회귀: tests/{architecture,platform,component,features,scripts,contract} 95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files / 1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과. check-architecture(shim), check-adapter-inventory, check-diagnostics, check-registries 통과.문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱 조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다. 참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로 레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서 rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다. 고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와 함께 한 오류로 던진다. 예: "REST security profiles are incoherent for CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER." operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부 두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를 넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는 테스트·로그 검색은 계속 맞는다. 버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상 깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시 봐야 한다. 위험·한계: - 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을 별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리 기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와 사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은 사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그 작업에 남는다. - 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가 초기 청크에 있어 오류 문장이 그대로 실린다. 검증: - RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가 "expected [Function] to throw error matching /incoherent.* CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are incoherent.'"로 실패. - GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우). - 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration (프로세스를 띄우는 3개 제외) 131건, tests/{contract,features, runtime-schema,component,architecture,platform} 626건 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.문제: 선택 파일은 "Adding an entry here is what installs a capability"라고 적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다. realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지 않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그 선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다. 고른 방법: - `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime, webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아 throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지 않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다. - 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는 composition에 런타임을 먼저 연결해야 한다"로 고쳤다. 버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은 여전히 아무 신호도 받지 못한다. 위험·한계: - 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야 한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다. - health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만, 런타임을 연결할 때 쓸 자리라 남겼다. - 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다. - 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B). 검증: - RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별 하나)이 "expected [Function] to throw an error"로 실패. - GREEN: 같은 파일 9건 통과. - 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration (프로세스를 띄우는 3개 제외) 131건, tests/{component,platform, architecture,features,contract} 570건 통과. 그중 app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고, heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이 INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random 실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그 함수가 reason을 고정한다. bootstrap은 이 reason을 그대로 cache.operation.failed 진단에 싣는다. 난수 실패나 topic version 불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다. 고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는 이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사 실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason 값은 만들지 않는다. 호출자에게 돌려주는 결과 {ok:false, reason:"INVALID_EVENT"}는 그대로다. 위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는 대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가 없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는 수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해 이 worktree에서 돌리지 않았다. 검증: - RED(수정 전): cross-tab-invalidation.test.ts 새 1건이 "expected [ 'INVALID_ENVELOPE' ] to deeply equal [ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패. - GREEN: 같은 파일 통과. - 회귀: cross-tab-invalidation·tanstack-cache-coordinator· runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md문제: active pointer를 읽을 때 rollback 목록 길이를 현재 retainedPreviousReleaseCount와 비교한다. 3에서 1로 줄이는 정상 설정 변경이나 pointer JSON 손상 뒤에는 읽기가 CORRUPT_DATA가 되고, 조회· 활성화·정리·inspect가 모두 여기서 멈춘다. control cache를 지우는 API가 없어 사용자가 사이트 데이터를 지우기 전까지 오프라인 캐시가 꺼진 채로 남고, cleanup이 막혀 배포마다 release cache가 쌓인다. 이번 라운드에도 Node와 실제 Cache API 3엔진에서 재현됐다. 고른 방법(지난 리뷰 4.1절의 (나)+(다)): - (다) isActivePointer는 목록 길이를 현재 값이 아니라 정책이 허용하는 최댓값(5, MAX_RETAINED_PREVIOUS_RELEASE_COUNT)과만 비교한다. 정책 검증과 같은 상수를 쓴다. 다음 activation이 이미 하던 slice로 목록을 현재 값으로 자른다. - (나) activateRelease는 이전 pointer 읽기가 CORRUPT_DATA면 없는 것으로 보고, 전체 재검증을 통과한 후보로 rollback 목록 없이 덮어쓴다. 일시 오류(UNAVAILABLE 등)는 지금처럼 활성화를 멈춘다. 버린 대안: - 현상 유지 + "사이트 데이터 삭제" 안내. 운영자가 원인을 알 수 없고 캐시가 계속 쌓인다. - control을 지우는 admin API. 포트가 늘고 호출자가 언제 불러야 하는지 알아야 한다. - (다)만 적용. 정책 변경은 풀리지만 JSON 손상은 풀리지 않는다. 위험·한계: - 지키던 성질은 그대로다. 검증한 후보만 활성화하고(재검증은 pointer 읽기 전에 끝난다), 조회는 manifest digest가 맞는 바이트만 돌려준다. 읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다. 손상 pointer 상태의 조회와 cleanup은 다음 activation까지 여전히 CORRUPT_DATA다. - 덮어쓰면 손상 pointer의 rollback 목록을 잃는다. 원래 읽을 수 없던 값이다. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다. 그 탭의 조회는 네트워크로 떨어진다. Service Worker drain(VD-15)을 구현하면 이 규칙을 다시 본다(지난 리뷰 4.1절 7). - 리뷰가 "가능하면"으로 적은 3엔진 browser spec(E-2)은 추가하지 않았다. 단위 테스트(MemoryCacheStorage)로만 확인했다. - service-worker-pwa 레시피 번들 9,665 → 9,716 / 10,000 gzip bytes. 검증: - RED(수정 전): public-response-cache-repair.test.ts 새 2건 실패. retained 3 → 1 뒤 조회가 { ok: false }(기대 ok:true), 잘린 pointer 뒤 다음 배포의 activate가 { ok: false }. - GREEN: 같은 파일 8건 통과. 일시 오류 가드 테스트 1건을 함께 넣었다. activate가 모든 pointer 실패를 무시하도록 바꾼 변이를 이 테스트가 잡는다(1건 실패 확인 뒤 되돌림). - 회귀: public-response-cache 단위 3파일 40건 통과. tsc app·test· service-worker·recipes 통과. 바꾼 파일 eslint 통과. verify-documentation-readiness PASS_SCOPED. check-optional-recipes (source) PASS. Refs: docs/reviews/2026-09-29-maturity-review/02-adapters-browser-files-cache.md문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고 적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표 밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고 retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른 행동을 가리킨다. - ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true. 표대로면 RESELECT다. - ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE. 다시 부르면 성공한다. - ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새 session으로 성공한다. - ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다. - ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY): RESUME. 서버가 같은 값을 다시 준다. 고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에 둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의 NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE. 나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나 REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는 번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다. 포트 표 주석과 설계 문서 표에 이 규칙을 적었다. 버린 대안: - 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE 경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금 STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다. - 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기 실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못 보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다. - 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난 리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다. 위험·한계: - ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로 고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다. 리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건 ("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime 호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다. 그래서 이 발견은 부분 충족이다. - 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나 (resumable-upload-runtime-contract.test.ts "rejects a part capability that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다. 다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다. - 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류 값을 주입했다. - file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산 56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다. 검증: - RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패. ① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대 RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대 NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다. - GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면 retryable:false" 단언을 더했고 통과한다. - 회귀: resumable-upload·presigned·upload-cancellation·browser-file· image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. verify-documentation-readiness PASS_SCOPED. check-architecture(exec 전용 shim) 통과. check-optional-recipes (source) file-transfer 56031/56100. Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md문제: "정확하지 않은 이벤트 계약을 거부한다" 테스트는 공용 fixture의 events가 빈 배열이라 첫 줄 `if (events.length === 0) return;`에서 끝난다. 단언이 하나도 실행되지 않는다. 그래서 composeContractContributions의 이벤트 snapshot(M17)이나 assertEventContract 호출(M18)을 빼도 관련 테스트가 모두 통과한다. 템플릿 안에는 이벤트를 기여하는 계약이 없어서 이 경로를 지키는 테스트가 따로 없다. 고른 방법: - tests/helpers/external-contract-fixture.ts에 TEST_EVENT_CONTRACT를 추가한다. 공용 TEST_CONTRACT_CONTRIBUTION의 events는 그대로 비워 둔다. 이 fixture를 쓰는 다른 테스트 20여 파일의 전제를 바꾸지 않기 위해서다. - 빈 배열이면 return하던 테스트를 지우고 "event contracts" 묶음을 둔다. 정상 행이 snapshot으로 설치되는지(같은 내용, 다른 객체, frozen) 먼저 확인해서 아래 거부 경우가 다른 이유로 throw하는 것이 아님을 보인다. 거부 경우는 HTTP 쪽 hostileRows처럼 모양(추가 필드, 다른 prototype, accessor)과 내용(빈 eventType, 공백, C1 제어문자, 160바이트 초과, validator 없음, 빈 schemaId), 중복 eventType이다. ContractContributionError로 던지는지까지 본다. 버린 대안: tests/setup.ts에 전역 expect.hasAssertions()를 두는 방법. 같은 종류의 빈 테스트를 모두 막지만 모든 vitest 프로젝트의 테스트 계약을 바꾸고, 리뷰는 빠른 계층 8개 폴더에서만 확인했다. 이 발견의 범위를 넘는다. 위험·한계: 템플릿 안에서 eventByType을 읽는 코드는 여전히 없다. 이 테스트는 composition 단계의 검증만 고정한다. 검증: - RED(변경 전 테스트 파일과 새 파일을 함께, 변이 적용): M17(snapshotEventContract가 입력을 그대로 반환) — 옛 파일 16개 통과, 새 파일 4개 실패("installs a well-formed event contract as its own snapshot", extra own field, custom prototype, accessor eventType). M18(assertEventContract 호출 제거) — 옛 파일 16개 통과, 새 파일 6개 실패(빈·공백·제어문자·160바이트 초과 eventType, validator 2종). - GREEN: node scripts/run-vitest.ts run tests/unit/contract-registry-immutability.test.ts — 26 passed. - related tests/helpers/external-contract-fixture.ts src/contracts/external-contract-runtime.ts — 97파일 796 passed. - tsc -p tsconfig.test.json, eslint(바꾼 2파일) 통과. Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-01문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나 `it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다. `context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고, 로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다. check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(` 글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다. 고른 방법: - vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다. - scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에 state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다. -t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다. 게이트는 실행을 좁히지 않는다. - reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의 reporters를 대체하므로 config에 두면 package script에서 빠진다. run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다. 호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다. 버린 대안: - 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가 skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼 적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog, 로컬 단일 파일)은 아예 보지 못한다. - tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이 돌지 않아 잡지 못한다. - eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고 `context.skip()`을 못 잡는다. 위험·한계: - run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지 않는다. allowOnly는 config라서 그때도 적용된다. - 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다. Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가 나온다. - 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다. - check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만 이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은 Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에 "quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도 quarantine이 필요해지면 허용 목록을 따로 둬야 한다. - 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다. 검증: - RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을 CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1 skipped | 1 todo"). only+CI=true만 exit 1. - 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패. - GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s) did not run" 목록, only는 "Unexpected .only modifier". junit reporter를 준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트 11 passed. - 빠른 계층 전체(unit·component·integration·contract·runtime-schema· platform·architecture·features·release·scripts·recipes, pnpm 설치를 하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed, 1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트 inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록 출력은 없었다. - tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일), check-ci-contract, generate-ci-workflow --check, verify-documentation-readiness(PASS_SCOPED) 통과. Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04문제: config/scale/feature-shape-growth.json에 측정 시각만 있고 어느 코드를 쟀는지가 없다. 기준선이 지금 코드와 맞는지, 다음 측정과 비교할 수 있는지 알 수 없다. 실제로 기준선은 2026-09-27 측정이고, 그 뒤 15-01이 초기 청크 구조를 바꿨다(ceilings.json도 "baseline predates 15-01"이라고 적고 있었다). 기준선 0개 초기 JS 200,001 B, 기능당 2,907 B는 지금 코드와 다르다. 고른 방법: - 측정 스크립트가 시작할 때 `git rev-parse HEAD`와 추적 파일 변경 목록 (`git status --porcelain --untracked-files=no`)을 읽어 결과의 `source: { commit, modifiedPaths }`에 싣는다. 변경 목록이 비면 커밋만으로 재현된다는 뜻이다. 측정 중 트리가 바뀔 수 있어 시작할 때 읽는다. - 기준선을 현재 코드로 다시 잰다(--sizes=0,25,100 --repeats=2 --write). - ceilings.json의 수치를 새 기준선에 맞춘다. 초기 JS 여유는 리뷰 개선안대로 "예산 − 기준선 ÷ 기능당 증가"로 적는다(2,291 B ÷ 약 610 B ≈ 3개). - 단위 테스트가 기준선에 40자 commit과 modifiedPaths 배열이 있는지 본다. 버린 대안: - 기준선 커밋이 현재 이력의 조상인지 테스트로 확인: 이력 없이 3-way로 이식하는 다운스트림(tech-log)에서는 템플릿 커밋이 없어 항상 실패한다. - dirty 트리면 --write를 거절: 이 커밋처럼 측정 스크립트와 기준선을 한 커밋에 넣을 수 없게 된다. 대신 변경 경로를 그대로 기록한다. 위험·한계: - 기록된 커밋은 2be973a(이 브랜치의 직전 커밋)이고 modifiedPaths는 측정 스크립트와 그 테스트 2개다. 측정 대상(src, vite 설정)은 그 커밋과 같다. 이 브랜치를 rebase하면 기록된 SHA가 이력에서 사라진다. 그때는 다시 재야 한다. - 시간 값은 호스트 부하(loadavg 27~29)에 따라 흔들린다. 바이트와 instantiation 수만 비교 대상이다. - 15-01 커밋 본문의 202,361 B와 이번 0개 측정 202,509 B는 148 B 다르다. 원인은 확인하지 않았다. ceilings.json은 기준선 수치 하나로 통일했다. 검증: - RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts -t 'commits a baseline' — "expected undefined to deeply equal { commit: StringMatching…" 실패. - 측정(flock): 0개 202,509 B·720,060 inst, 25개 218,010 B, 100개 263,119 B·12,399,171 inst, 반복 2회 바이트·inst 동일. 기능당 초기 JS 약 610 B, lazy 약 8.3 KB·8파일, inst 약 117k, tsc 메모리 약 36 MB, route 4개. - 재현: 같은 트리에서 --sizes=0,25 --repeats=1을 다시 돌려 0개 202,509 B, 25개 218,010 B로 같음. - GREEN: feature-shape-growth.test.ts 5 passed(빌드 측정 테스트 포함). - tsc(node·test), eslint(바꾼 2파일), verify-documentation-readiness PASS_SCOPED. Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-05문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로 한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트 200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어 기본 원칙과 맞지 않고 모든 파생 서비스가 받는다. 고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap: break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도 적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content 계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며 라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드 토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다. 위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은 오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의 줄바꿈은 눈으로 확인하지 않았다. 검증: - RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패 (wordBreak "normal", overflowWrap "normal"). - GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과. accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell· responsive·theme·compact-smoke·platform-overview chromium/compact 34/34 통과. check-design-system PASS. 시각 회귀는 미실행. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의 FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의 indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다. 사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의 contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는 고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다. 고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다. - FormFailureStatus가 supportReference={failure.requestId}를 넘긴다. - useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재 보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는 여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번 그리지 않는다. - AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만 보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다. - 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에 넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다. 공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop). 버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에 두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03 (raw 경로 정리)과 겹친다. 위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서 남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가 x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03). 결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준 202,520 → 202,631 B(예산 204,800 B). 검증: - RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1, reference-page 3. 예: "Unable to find an element with the text: 지원 참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조: corr-save-500') not found). - GREEN: 관련 3파일 70/70, tests/component·features·architecture 59 files 336 tests 통과. e2e reference-save·reference-form· reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint, check-i18n, check-design-system 통과. Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04문제: part 발급(BFF)이 401/403으로 거절하면 upload()가 {PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다. 세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다. 그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일 전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를 남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서 toUploadAction 한 곳에서 가를 수 없었다. 고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의 uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을 안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로 만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역 (toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개 타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는 곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다. PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새 capability를 받는다(지난 수정의 보존 조건). 버린 대안: - 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야 한다. - code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다. PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다. - 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라 [계약]이다. 같은 일을 기존 값으로 할 수 있다. - 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개 BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고, WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시 만들면 말없이 표시가 사라진다. - control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히 RESUME을 낸다. 위험·한계: - BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다. - control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지 않는다. 재인증 전에는 결과가 같기 때문이다. - 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다. - 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다. - file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100). 검증: - RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중 BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403 1건은 수정 전에도 RESUME으로 통과(보존 조건 고정). - GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다. - 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새 테스트, 기존 01-05 표 테스트)이 실패한다. - 회귀: resumable-upload·presigned·upload-cancellation·browser-file· image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. verify-documentation-readiness PASS_SCOPED. check-optional-recipes(source) file-transfer 56053/56100. - 미실행: check:architecture(pnpm 필요). Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md문제: useApplicationMutation이 BoundMutation과 함께 raw LegacyMutationOptions({ execute, definitionId })도 공개 overload로 받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope 세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는 null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무 일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의 raw 사용을 막지 않는다. 고른 방법(결정대로): - 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개 시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다. - raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application- query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는 명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다. - 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw 입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면 tsconfig.test.json 검사가 TS2578로 실패한다. - raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는 세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서 ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전 QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게 온 이전 응답은 버려진 client에 쓰인다. 이 동작을 server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은 client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인). 시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider 밖에서는 훅이 막지 않는다는 위험을 적었다. - typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다. 버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이 깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 — 쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY 분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를 못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json, gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고 다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존 check:types:test 게이트가 돈다. 위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로 여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가 쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는 ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다. 검증: - RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json → "error TS2578: Unused '@ts-expect-error' directive." - GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests 통과(옮긴 테스트 포함). tests/unit·component·features·contract· runtime-schema·architecture·scripts·integration(security-followup- archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint (바꾼 파일) 통과. - 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는 제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은 raw 호출이 있어 harness와 함께 동기화해야 한다. BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId } 입력을 받지 않는다. BoundMutation(definitionId, definitionVersion, operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope, invalidate, execute(input, { signal, intent }))을 넘긴다. scope는 useServerStateScope()에서 얻는다. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만 있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서 `formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를 통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로 거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿 파일에 키 11개를 넣었다. 고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의 `{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은 `string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로 덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴 항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다. `ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서 만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다. 새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다. 버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이 교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로 맞춰야 한다. 위험·한계: - 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에 덮어쓴다. - 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는 `tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다. - ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지 않는다(VD-06 재검토 조건). - 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`): Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663 (+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로 흔들려 차이를 구분할 수 없었다. - 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는 샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는 샘플 키에 기대지 않는다. 검증: - RED: `npx tsc -p tsconfig.test.json --noEmit` feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error' feature-module.test.ts(26,60): error TS2345: Argument of type '{ count: number; }' is not assignable to parameter of type 'undefined'. - GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과. - `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로 계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다. - vitest: tests/features/reference-feature, i18n-contract, locale-platform 19 files 97 tests 통과. - 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다. Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석 한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플 화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature", `limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created", 폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다. 고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로 옮긴다(`eslint.config.ts`의 `screenTextSelectors`). - 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`, `aria-description`, `aria-roledescription`, `aria-valuetext`, `aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열 literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다. 구두점·숫자만 있는 문구는 통과한다. - 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI 폴더와 `src/features/*/presentation`. 컴포넌트 갤러리 `src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는 workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다. - 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019 선택자(raw HTML, script 생성)를 함께 싣는다. - `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다. raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다. - `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도 돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2), 새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog 문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1, "I18n contract failed:")은 그대로다. - fixture 추가: allowed `korean-comment.tsx`, forbidden `english-jsx-text.tsx`, `english-accessible-name.tsx`. - 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개 (`reference.list.title`·`filterLimit`·`filterTags`·`resources`, `reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`, `reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은 예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가 된다. 버린 대안: - (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다. - (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에 기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다. ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품, 고유명사 허용). 위험·한계: - 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체 prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로 옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터 밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다. - 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에 `eslint-disable-next-line`을 쓴다. - ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라 그대로 뒀다(라우트 제목 정리는 0929/08-06 몫). - `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조 기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가 pnpm build를 부른다). - 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다. 샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행). 검증: - RED(수정 전): - E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common user-facing locale literal in .../reference-resource-status-page.tsx", exit 1 - E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0 - `check-i18n.ts --fixture` -> "I18n fixture was not rejected: english-accessible-name.tsx, english-jsx-text.tsx", exit 2 - 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패 - GREEN(수정 후): - E1 변이: `check-i18n.ts` PASS, `eslint` exit 0 - E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1 - `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두 거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면 "I18n allowed fixture was rejected", exit 2 - ko-KR main 테스트 통과 - `npx eslint src scripts tests recipes .storybook ... --max-warnings=0` 통과, app·test·node 타입 검사 통과 - vitest: tests/unit + tests/component 209 files 2725 tests, tests/features 등 25 files 141 tests 통과 - `check-registries.ts` PASS, `check-ci-contract.ts` PASS, `verify-documentation-readiness.ts` PASS_SCOPED Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3문제 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문제 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문제 유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다. 세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유 파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이 이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류 메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다. 고른 방법 (2026-11-03 결정) - 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와 V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를 새 이름으로 옮겼다. - 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고 JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야 하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다. 그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로 해석된다. - scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는 "REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다. - 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지, src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준). 버린 대안 - 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서 바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다. - 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이 매핑을 알아야 한다. 프로필 항목 하나가 더 작다. 위험·한계 - 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지 않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다. 그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다. - 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가 보이지 않는다. CHANGELOG로 알린다. - FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라 behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번 작업 묶음 끝에서 한 번에 한다. - 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭 항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy 청크라 초기 크기에 영향이 없다. 검증 - RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected undefined to match object { transport: 'BEARER_HEADER', …(1) }", "expected [ …(9) ] to deeply equal [ Array(1) ]"). - GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS" (FE-REG-API authProfileId 3건 behavior-change). - 회귀: tests/{unit,integration,features,contract,runtime-schema} 207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외: http-scenario-evidence, ci-workflow-generation, lab-performance, fixture-node-modules, deployment-admission, security-followup-archive). tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공. - 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e. Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md문제 production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이 없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도 없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지 않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local 프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠 있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다. 고른 방법 (리뷰 대안 (c), (1)~(3)) (1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와 비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id· release-id). 후보는 검사하는 dist의 release-manifest.json이다. (2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가 `--release-root .release/promoted-release`를 받아 후보 dist를 본다. 계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든 게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다. (3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을 선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면 FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다. 프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것: checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나 (`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과 같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과 vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안 바뀐다. - ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences 103→102(update-ci-contract-baseline, owner frontend-platform). - verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다. 스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live (예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고 각각 UNVERIFIED·FAIL로 끝난다. 버린 대안 - (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상 FAIL이 된다. - (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact 전달이 검증되지 않았다. - 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면 이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다. 위험·한계 - Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와 `$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다. - 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은 fetcher를 주입한 단위 테스트로만 확인했다. - 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함) env에 보인다. 프로젝트가 고르는 값이다. - FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보 archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts 7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음). tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed ("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...", "expected -1 to be 6", deployment job 없음) - GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed (스냅샷 1개 갱신) - check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS, check-ci-contract.ts PASS, generate-ci-workflow --check PASS - 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면 "CI gate contract missing package scripts: deploy:release"로 실패. 실험 뒤 원복 - 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe, service-worker-build-output, deployment-admission, ungated-*, supply-chain, removal-fixture, task3-selective-integration, documentation-readiness, tests/release, tests/platform/release) - tsc(node, test, app) 0, eslint 바뀐 파일 0, verify-documentation-readiness PASS_SCOPED - 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm) Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01문제 제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF 쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면 runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts, release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이 파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다 fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄). 고른 방법 (리뷰 09 4.2의 (B)) - FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의 FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은 declaration merging으로 capability를 더한다. - 제품 소유 파일 둘을 빈 구현으로 둔다. - src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필 id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유 product-composition-contract.ts에 둔다. - src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정 zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에 있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수 없어서 파일을 하나로 합치지 못했다. - 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품 제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가 CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용 목록이 정한다. - 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다. - 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가 두었던 전방 참조 stub이 필요 없다. - 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에 담으면 browser-data-boundary/no-capability-alias가 막는다. - http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다). 제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다. 버린 대안 - (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다. - (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증 정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다. - 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품 capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다. 위험·한계 - memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23, CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히 rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다. 픽스처는 x-csrf-token으로 표현했다. - 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다. 그 행을 요구하는 검사는 없다. - tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드 (create-runtime-composition.ts)는 이 확장 지점 밖이다. - 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을 끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은 이중 방어로 둔다. - V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만 쓰는 리더다. - 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800). 검증 - RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품 제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가 먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과. - GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts 9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기· 쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01 tests/unit/runtime-adapters-auth-profile.test.ts 12/12. - 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과. integration·component 47 files 386 tests 통과(pnpm을 띄우는 security-followup-archive 제외). tsc app·test·node·recipes·web-worker· service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS (compatibility=breaking은 기존 route·storage 행). verify:documentation PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신 exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON schema는 baseline과 같다.문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고 소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조, 그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다. diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다. README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다. design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과 check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가 어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를 설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를 모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를 고쳐야 한다(다운스트림 동기화 충돌 지점). 고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3. - route ID 나열을 지운다. verify:documentation은 설치된 라우트마다 artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치 (ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로 starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을 가리키게 바꾼다. - docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에 적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다. 문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는 작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo 기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서 읽는다), README "Files you can delete after copying"의 이력 중 지워진 것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한 FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를 적는 문서라 뺀다. - compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에 3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트 경로를 현재 위치로 고치고 그 사실을 머리에 적는다. - diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고 ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다. - documentation-review.json에 documentReferences를 더한다. routeScope는 모양을 유지하고 기록 폴더 한 항목으로 쓴다. 버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를 고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어 주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 — artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다. 위험·한계: - 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운 링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든 경로, 심볼 이름이 맞는지는 보지 않는다. - script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로 시작하는 "`접두:이름`"만 본다. - 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재 계약 문서(README, compatibility.md, starter-experience.md, manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운 복사본은 그대로 통과한다. - 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도 본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다. - CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다. 검증: - RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패. 기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면 "failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두 통과했다. - GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED. tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에 돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다. - 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를 고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림). - 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과. deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일 eslint 통과. check-ci-contract, generate-artifact-schemas --check, generate-ci-workflow --check, check-adapter-inventory 통과. check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖, 이번 변경과 무관). - 미실행: check:architecture(pnpm 필요, worktree에서 금지).문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터 화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을 대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데, 제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다 같은 파일이 충돌한다(두 제품 기록). 방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를 더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시), chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던 방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다. 스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩 실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은 starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로 모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다. fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다. 배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가 자기 자신을 기다린다. 버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만 화면을 바꾸면 검사는 여전히 깨지거나 사라진다. 위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는 화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는 여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서 렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는 key={definition.routeId}를 지우면 여전히 실패한다(변이 확인). 검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로 바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4, platform-overview 7, app-shell·async-surface·chunk-recovery· runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만 실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서 tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼 파일 eslint 통과.문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행 하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서 - 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지 하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다. - journal DB는 authority 단위라 손상 행 하나가 모든 partition의 reconcile과 orphan GC를 멈춘다. 스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다. 고른 방법 (리뷰의 (c)): 1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지 않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은 페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고, 0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다. 2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴 object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep, `STAGING_STATE_UNREADABLE`) partition을 통째로 지운다. - 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를 통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제 (0929 05-03)와 같은 조건이다. - 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를 쥔 채 `authorities/<a>/<ns>/<p>`를 지운다. - 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는 object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다. 손상 행도 지워진다. scope binding 행은 남긴다. - 보고: `partitionDeleted: true`, `corruptObjects`, `moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에 실패해도 다시 부르면 이어서 끝난다. 버린 대안: - 현상 유지: 손상이 있으면 삭제가 영구히 실패한다. - 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다. - journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다. 기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과 runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다. 위험·한계: - 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에 `corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한 쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다). report에는 `corruptTransactions`(필수)와 `corruptObjects`· `partitionDeleted`(선택)가 생겼다. - lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은 partition put은 journal 행이 지워져 다음 journal 단계에서 실패할 것으로 보지만, 이 경합은 실행으로 확인하지 않았다. - partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다. - reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽 `STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만 partition 삭제로 빠져나간다. - offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B 초과). 예산은 올리지 않았다. - 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다. 검증: - RED (수정 전): journal 4건 실패 — `listIncomplete`· `listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가 `CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도 디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드). - GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes` 177 files 2,523건 통과, `tests/contract` 41건 통과. `tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일 eslint 통과, `check-adapter-inventory` 통과. - 미실행: `check:browser-file-storage-boundaries`(pnpm 필요), `check:architecture`(pnpm 필요), Playwright OPFS spec. Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와 같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`, `FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`, `PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929 05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이 복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는 runtime에 없는 resume·quarantine을 전제했다. 고른 방법 (리뷰의 (c)): - runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고 `src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`, `DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는 `DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src port가 그대로 받는다). - fake는 src port를 `implements`한다. - 파일 picker·content·preview·download fake와 storage durability fake: 결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다. `PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다. - `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는 scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은 reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다). LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다. - 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는 `IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대 CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다. recipe 전용 `StructuredOfflineStore`의 fake로는 남는다. - recipe 전용 port 두 곳: - `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection` 모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다. - `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로 나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로 계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를 import하지 않게 하려는 것이다. - 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를 더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을 정의하면 실패한다(다시 내보내기는 허용). - runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는 이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께 지우고, recipe barrel에서 두 export 줄을 먼저 뺀다. 버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복 유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지). 위험·한계: - recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다 (조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore` 생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입 4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다. - `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가 아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다. - `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다. barrel 줄 제거와 경로 추가는 코드로만 확인했다. 검증: - RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다. `expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개). - GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node 통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요), `verify-documentation-readiness` PASS_SCOPED. `check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산 초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다. 이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖). BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS· storage durability·public cache 타입 중 src/application/ports와 이름이 같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를 구현하고 BrowserDataResult를 돌려준다(`result.failure.code` → `result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy, maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은 `FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity` ·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다. Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03문제 셸은 design-system/index.ts에서 Button·Drawer·Select를 import한다. 번들러는 배럴이 다시 내보내는 모듈을 side effect가 있다고 보고 모두 실행 순서대로 싣는다. 그래서 갤러리와 예제 화면만 쓰는 Tooltip·Menu·Toast·Tabs·Card· Alert 등이 초기 청크(design-system-*.js)에 있다. 초기 JS는 203,818 B로 예산 204,800 B에서 982 B 남았다. 파일을 나눈 앞 커밋만으로는 바뀌지 않는다. 고른 방법 - vite.config.ts의 treeshake.moduleSideEffects 규칙으로 src/presentation/design-system/ 아래 .ts·.tsx를 side effect 없음으로 선언한다. 이 파일들은 컴포넌트·아이콘·토큰 목록 선언만 한다. CSS import는 bootstrap/main.tsx 한 곳뿐이고 이 범위 밖이다. - 결정: 바이트를 줄인다. 예산이 걸린 지표는 바이트이고, 늘어나는 청크는 진입 청크의 preload 목록(__vitePreload)으로 병렬로 받으므로 HTTP/2에서 왕복이 늘지 않는다. 재검토 조건(HTTP/1.1 호스팅이면 청크 수가 비용)을 설정 주석에 적었다. - 새 테스트 tests/unit/design-system-initial-chunk.test.ts - 실제 vite build를 돌려 초기 청크에 lazy 화면 전용 클래스 13개가 없는지 본다. 셸의 ui-drawer가 있는지를 같이 봐서 빈 결과로 통과하지 않게 한다. - design-system 파일에 효과만을 위한 import(import "x")가 없는지 본다. 선언 아래에서는 그런 import가 모듈과 함께 사라지기 때문이다. - build-environment-bundle 테스트(13-06)는 design-system-* 청크 이름을 찾았다. 그 청크가 없어져서, Button 코드(ui-button--pending)가 든 청크가 build id를 바꿔도 같은지로 바꾼다. 두 build id로 빌드해 보면 바뀌는 파일은 boot·index·render-boot-failure 셋뿐이다. 버린 대안 - 파일 분리만: 실측 효과 없음(203,824 B, 16개). - manualChunks로 청크 이름을 고정: 제품이 primitive를 쓸 때마다 다시 맞춰야 한다. - 청크 수 줄이기: 15-01 청크 그룹과 같이 봤다. rolldown의 $initial 태그는 main.tsx가 앱을 동적으로 import해서(09-03) 아무것도 잡지 않았다(25개, +16 B). 모듈 그래프로 boot 정적 closure를 만들면 배럴을 따라 갤러리 primitive까지 잡혀 다시 초기 청크로 간다. 바이트 손해 없이 줄일 방법을 찾지 못해 늘어난 수를 둔다. 위험·한계 - 초기 청크가 16개에서 25개로 는다(결정 당시 추정 21개보다 많다. 앞 커밋의 파일 분리로 button·field·select가 따로 나온다). 전체(초기+lazy) gzip은 232,231 → 236,253 B로 4,022 B 는다. 첫 화면만 보는 사용자는 2,718 B 덜 받고, 모든 화면을 도는 사용자는 청크 경계 비용만큼 더 받는다. - 새 파일에 모듈 최상위 효과(전역 등록 등)를 넣으면 이 선언이 그 효과를 지울 수 있다. 효과만을 위한 import는 테스트가 막지만, 최상위 문장은 막지 않는다. 설정 주석에 적었다. - lazy 청크 예산(청크당 122,880 B)에는 영향이 없다. 가장 큰 lazy 청크는 8,431 B다. - 화면 변화 없음: 같은 코드를 다른 청크에서 받는다. 검증 - RED(앞 커밋 상태): 새 테스트가 실패. 초기 청크에 ui-alert·ui-badge· ui-card·ui-data-table·ui-menu·ui-progress·ui-radio-group·ui-switch· ui-tabs·ui-toast·ui-tooltip 11개가 있었다. - GREEN: design-system-initial-chunk·build-environment-bundle· design-system-contract·product-index-entrypoints·bundle-classification· sub-path-deployment·product-feature-selection-build 통과. - 빌드(flock, build-frontend.ts): 초기 JS gzip 203,818 → 201,100 B (-2,718 B, 예산 여유 982 → 3,700 B), 초기 청크 16 → 25개, lazy 청크 17 → 20개. - node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과. - Chromium e2e(vite preview, 위 빌드): ui-gallery·design-system- interactions·app-shell·accessibility·platform-overview·reference-form· reference-route·reference-save·theme·typography·responsive·compact- smoke·i18n·scroll-restoration 55/55 통과. - tsc(app·node·test), 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08문제: 경로 정본은 계약의 `routes[*].path`인데, 샘플 페이지가 같은 경로를 문자열로 8곳에 다시 적는다(목록 2, 상세 1, 폼 3, 상태 1, 실패 행동 1). route 입력은 `routeInput.search as ReferenceListFilters`와 `String(route.params.resourceId)`로 cast한다. 계약에서 경로만 바꾸면 tsc는 통과하고 링크는 NOT_FOUND로 간다. 문서(routing-pages-and-patterns 4.2절, 10절 4단계)는 codec 기반 builder와 cast 금지를 권하는데, 샘플이 반대 패턴을 보여 주고 복사되는 기능이 그 습관을 가져간다. 고른 방법: 이미 있는 URL builder를 쓴다. - `buildRouteUrl(routeId, input, featureCodecs)`(`src/presentation/routes/ route-codecs.ts`)가 route ID로 계약 `path`를 찾고, 라우터가 parse에 쓰는 같은 codec으로 직렬화한다. canonical redirect도 이 함수를 쓴다. `src/platform`에는 URL builder가 없다. 그래서 플랫폼에 새 공개 헬퍼를 더하지 않았다. - 기능 쪽 helper는 `presentation/reference-routes.ts`에 둔다. - `referenceRouteUrl(routeId, input)`: `buildRouteUrl`에 이 기능의 codec을 넘기는 한 줄 래퍼다. routeId는 이 기능 계약의 키로 좁힌다. - `useReferenceListFilters()`, `useReferenceResourceId()`: 라우터가 이미 통과시킨 route 입력을 같은 codec으로 다시 parse해서 codec의 출력 타입을 얻는다. cast가 없다. 목록 필터는 `useMemo`로 묶어 route 입력이 그대로면 같은 객체를 준다. - `REFERENCE_FEATURE_ROUTE_CODECS`를 `reference-feature-runtime.ts`에서 새 `presentation/reference-route-codecs.ts`로 옮겼다. - runtime 파일이 페이지를 lazy import하므로, 페이지 쪽이 runtime 파일에서 codec을 가져오면 순환 의존이 된다. - codec 표를 helper 파일에 같이 두지 않은 이유: 그러면 `context-routes.ts`가 router의 builder·hook까지 끌어와 초기 JS가 585 B 늘었다(204,809 B로 예산 204,800 B 초과). 분리하면 475 B다. - `context-routes.ts`와 `reference-contract.test.ts`는 새 위치에서 가져온다. - 페이지 8곳을 route ID 호출로 바꿨다. 기능 presentation에 `"/examples/` 문자열이 0건, route 입력 cast가 0건이다. 남은 `"/examples/` 4건은 계약의 `path`(정본)다. - 기능 README에 helper 위치와 쓰는 법을 적었다. 버린 대안: - 리뷰 (b)처럼 기능 안에 경로 치환·직렬화를 새로 쓰는 헬퍼: 라우터와 같은 일을 두 번 구현한다. 플랫폼 builder가 이미 route ID와 기능 codec을 받는다. - 리뷰 (c)처럼 `buildRouteUrl`의 input 타입을 route ID별로 좁히기: 플랫폼은 기능 codec 타입을 모른다(15-01 이후 codec은 지연 적재). 라우터 API 변경이라 이 발견 범위를 넘는다. - 플랫폼 `useRouteInput`을 제네릭으로 바꿔 타입 단언하기: 런타임 검사 없는 단언이라 cast를 다른 이름으로 옮길 뿐이다. 위험·한계: - 목록 링크가 이제 정식 URL(`/examples/reference-resources?limit=20`)을 가리킨다. 전에는 `?limit` 없는 주소로 갔다가 라우터가 같은 URL로 replace했다. 도착 URL과 history 항목 수는 같다. 폼의 "목록을 새로 불러와 확인" 링크 href 기대값을 이 값으로 바꿨다. - `buildRouteUrl`은 codec이 거절하는 입력에 예외를 던진다. 백엔드가 공백만 있는 id를 주면(DTO는 `min(1)`, route codec은 trim 후 `min(1)`) 목록 렌더가 기능 오류 경계로 간다. 전에는 링크가 잘못된 주소 화면으로 갔다. DTO와 route codec의 id 규칙 차이는 이 변경 전부터 있다. - route 입력을 한 번 더 parse한다. 값이 작아 비용은 무시할 만하다. - 초기 JS gzip이 204,224 B에서 204,699 B로 475 B 늘었다(예산 204,800 B, 여유 576 B → 101 B). 새 코드가 초기 청크에 들어간 것이 아니다. `route-codecs.ts`는 원래 초기 청크에 있었다. 페이지가 이 모듈을 import하자 rolldown이 `boot` 청크에 있던 것을 공유 청크(`route-input`)로 옮기고, `route-input`과 `server-state-scope-provider`를 두 청크로 나눴다. 늘어난 양은 청크 분리 비용이다. 예산 값은 바꾸지 않았다. - 페이지 테스트의 진입 URL 문자열은 그대로 뒀다. 테스트가 경로를 적는 것은 이 발견의 완료 기준 밖이다. - 상태 페이지의 `(state as ReferenceSupportState)`는 history state 처리라 route 입력 cast가 아니다. 그대로 뒀다. 검증: - RED(수정 전): 새 `tests/features/reference-feature/ reference-route-links.test.tsx`는 계약의 네 경로를 모두 옮긴(vi.mock) 상태로 목록→상세→목록→폼→목록, 목록→지원 페이지→목록을 걷는다. 2개 모두 실패했다. 상세 링크가 `href=".../items/reference-1"`(기대 `.../entries/reference-1`), 지원 페이지 대신 NOT_FOUND가 나왔다. - GREEN(수정 후): 같은 테스트 2개 통과. `tests/features/reference-feature` 18 files 89 tests 통과(href 기대값 1곳 변경 뒤). - 회귀: tests/features, tests/component, tests/architecture, tests/scale, 관련 unit 3개, generator 테스트 81 files 464 tests 통과. 첫 실행에서는 부하(평균 23~35)로 타임아웃 2건(app-build-input, global-local-independence)이 났고, 단독 재실행과 최종 재실행에서 통과했다. - 초기 JS gzip(`scripts/build-frontend.ts` 후 check-bundle과 같은 분류로 측정): 수정 전 204,224 B, 수정 후 204,699 B. - `tsc` app·test·node 통과. 바꾼 파일 `eslint --max-warnings=0` 통과. - `check-architecture.ts`(pnpm 대신 exec 전용 shim): 381 modules, 순환·위반 없음, rc=0. `verify-documentation-readiness` PASS_SCOPED, `check-i18n` PASS. - 페이지 테스트 harness(`renderReference`, `inputWith`)는 새 테스트와 함께 쓰도록 `reference-page-harness.tsx`로 옮겼다. 내용은 그대로다. Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-04문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다. ① installed-context-routing은 context 목록이 정확히 ["reference-context"]이고 첫 context가 참조 context라고 단정한다. ② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을 끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다. ③ release-manifest fixture가 contractSet.packages: []로 고정이다. EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다. 또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고 시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능 테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다 (안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError). 방법: 리뷰의 (b) 최소 개선. ① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은 context에서 한다. ② REFERENCE_FEATURE_ID를 쓴다. ③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서 만든다. 하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령 여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3 descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/ http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도 descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그 확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는 계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는 operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을 말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던 응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다). 새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler( <자기 설치 계약>, { scenario: "server-terminal-503", payload })) 버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로 나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능 operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로 만든다. test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에 그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고, 테스트 전략 문서 11절에 사용법을 적었다. 위험·한계: - 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다. 실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존 제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다. - 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다. http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다. 스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이 테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별 a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가 breaking, 16-01)도 깨진다. - test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지 않았다. 검증: RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context, EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은 ① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서 참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한 테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469). 새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준 assertOperationScenario는 미등록 operation에 TypeError를 낸다. GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일 중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다. order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로 content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서 확인했다(카탈로그 수정 없음). 복사본을 지운 뒤: tests/features·component·runtime-schema·unit· integration(security-followup-archive 제외)·contract 250파일 3111개 통과, 카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS, tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED, check-ci-contract PASS, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02문제 짝 백엔드는 KEYED 요청을 실행하기 전에 두 가지를 거절한다(백엔드 docs/web/http-contract.md §2). - 422 IDEMPOTENT_REQUEST_MISMATCH: 같은 키에 다른 본문. 클라이언트 버그. - 400 IDEMPOTENCY_KEY_INVALID(details.reason MISSING·MALFORMED): 키 누락· 형식 오류. 둘 다 이 요청은 적용되지 않았고, 그대로 다시 보내면 같은 답이 온다. - V2(client.ts)는 이 실패에 effect를 붙이지 않는다. mutation 코디네이터는 effect가 없으면 MAYBE_APPLIED로 보고(application-query.ts mutationFailureWithEffect) 키를 붙든다. 400은 결과 불명 화면으로 가고, 같은 입력을 다시 저장하면 같은 키로 같은 400·422를 계속 받는다. 진단 이벤트(http.request.completed)에는 원인이 없다. - V3 참조 기능은 분류기가 400·422를 이미 NOT_APPLIED로 본다. 다만 mapProblem이 400을 다루지 않아 code가 CONTRACT_PROBLEM으로 바뀌고 서버의 IDEMPOTENCY_KEY_INVALID가 사라진다. 고른 방법 - V2: 문서에 적힌 status와 code가 둘 다 맞을 때만 effect NOT_APPLIED를 붙인다(IDEMPOTENCY_REFUSALS 표). 같은 표가 진단 reason을 준다. - 422 → reason IDEMPOTENT_REQUEST_MISMATCH - 400 → reason IDEMPOTENCY_KEY_RULE_MISMATCH. 프론트는 보내기 전에 isValidIdempotencyKey로 키를 검사한다. 서버의 400은 두 키 규칙이 어긋났다는 뜻이라 그 이름으로 남긴다. 보내기 전 거절(VALIDATION_ REJECTED, httpStatus 없음)은 표에 걸리지 않는다. reason은 diagnostics에만 넣는다. telemetry 속성은 그대로다(VD-07). - V3 참조 mapProblem: 400 + IDEMPOTENCY_KEY_INVALID만 UNKNOWN_CLIENT_ FAILURE와 서버 code로 둔다. 다른 400은 기존 fallback 그대로다. - kind는 바꾸지 않았다(422 VALIDATION_REJECTED, 400 UNKNOWN_CLIENT_ FAILURE). 둘 다 retryable:false이고 V2 재시도 대상이 아니다. - 키 문법은 백엔드 IdempotencyKeyHeader([\x21-\x7E]{1,256}, trim 없음)와 같다. 1자 키를 받는 행을 더해 경계를 고정했다. 버린 대안 - code만 보고 판정: 다른 status에 같은 code가 오면 NOT_APPLIED를 잘못 붙인다. NOT_APPLIED는 다음 저장이 새 키를 쓰게 하는 판정이라 문서의 짝(status+code)만 믿는다. - 422 mismatch를 UNKNOWN_CLIENT_FAILURE로 바꾸기: 화면 문구가 바뀐다. 요구는 재전송 금지·결과 불명 화면 금지·원인 code 보존이라 kind는 두었다. - 서버 code를 진단 reason에 그대로 넣기: 서버 code는 무제한이라 진단 cardinality 규칙(taxonomy)을 깬다. 표에 있는 두 값만 넣는다. 위험·한계 - 422 mismatch를 NOT_APPLIED로 보면 다음 저장이 새 키를 쓴다. 같은 키의 앞선 요청이 적용됐을 수 있지만, 프론트는 canonical 입력이 같을 때만 키를 재사용하므로 mismatch는 지문 규칙이 어긋난 버그다. 결정(15절)대로 이번 요청은 적용되지 않았다고 본다. - 422 화면 문구는 "입력값을 다시 확인해 주세요."다. 사용자가 고칠 입력이 아니지만 다시 저장하면 새 키로 나간다. - V3 실행기의 진단은 problem code를 모른다(Problem 타입은 계약 패키지 소유). V3에서 원인은 AppFailure.code·httpStatus로만 보인다. 검증 - RED: tests/integration/http-diagnostics.test.ts 새 2행 실패(effect undefined, reason 없음). tests/features/reference-feature/reference-http- problem-mapping.test.ts 400 IDEMPOTENCY_KEY_INVALID 행 실패(code CONTRACT_PROBLEM). 422 mismatch 매핑, 분류기 2행, 1자 키 행은 처음부터 통과(이미 맞는 동작을 고정). - GREEN: 위 파일과 tests/features/reference-feature, tests/integration/ http-client·http-execution-contract·auth-recovery·legacy-http-credential- authority, tests/contract/reusable-capability/feature-http-binding 24 files 207 tests 통과. tests/unit/legacy-and-optional-network-remediation 6/6. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15문제 짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409 IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드 docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤 재전송"이다. - 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를 붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를 고정). 이 부분은 이미 맞다. - Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만 feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의 Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시 보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를 한 번 더 받는다. 고른 방법 재전송이 그 시각 전이면 기다렸다 보낸다. - feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다. V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다). - mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는 admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다. 같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지 기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다. scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다. - 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다. 더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로, 긴 Retry-After를 다 기다리게 하지 않는다. 버린 대안 - Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시 열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다. - V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는 상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다. - 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는 동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는 Retry-After를 지키는 것이다. 위험·한계 - AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는 곳은 코디네이터뿐이다. - 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른 상태(NOT_APPLIED 등)는 그대로다. - 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면 브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다). 검증 - RED: 4행 실패. - tests/features/reference-feature/reference-production-vertical.test.tsx 처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상) - tests/component/application-mutation-admission.test.tsx 재전송이 retryAfterMs 300을 기다리지 않음 - tests/features/reference-feature/reference-http-problem-mapping.test.ts retryAfterMs 없음 - tests/integration/http-client.test.ts V2 409 retryAfterMs 없음 상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는 것을 확인했다. - GREEN: 위 행 모두 통과. tests/component·features·contract/reusable- capability, tests/integration/http-client·http-diagnostics, tests/unit/ http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15문제 짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는 위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http- contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성 이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다. 프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은 UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이 필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도 {issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다. 고른 방법 - V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로 본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로 만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를 그대로 쓴다. 새 폼 경로는 없다. - safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다. message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로 자른 뒤 projectValidationIssues에 넘긴다. - 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문 파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER, IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지). 버린 대안 - 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은 클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이 있을 때만 바꾼다. - 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와 V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용 safeValidationIssues에서만 읽는다. - V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json (type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지 않는다. 짝 백엔드 wire를 읽는 곳은 V2다. 위험·한계 - 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서 필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드 위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다. - 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이 아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼 입력이 아니라 목록 조회 파라미터다. - V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는 이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다. 검증 - RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2 클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고 Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts "reads the field details as validation issues" 실패(kind UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지 동작 고정). - GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration· component·features·platform 283 files 중 282 통과, 3394 tests 통과. 실패 1개(tests/unit/second-api-feature-registries.test.ts "passes check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다. tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS. Refs: clean-architecture-backend-template docs/web/http-contract.md 4절문제 V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400 VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation 코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면 MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_ REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을 들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form 자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다. 막는 것은 코디네이터 상태다. V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로 본다(reference-feature-contract-contribution.ts classifyProblem). 고른 방법 V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED + 배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_ REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다. 근거(백엔드 계약) - docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_ FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException), Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수 없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다. - 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서 끌어낸 것이다. 버린 대안 - 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기: 거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면 MAYBE_APPLIED" 규칙은 그대로 둔다. - 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채 남아 같은 입력을 다시 저장하면 같은 키가 나간다. 위험·한계 - application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가 있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를 EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를 쓰므로 그 경로를 타지 않는다. - 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의 400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다. - 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다. 검증 - RED: tests/component/form-foundation.test.tsx "saves the corrected value after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드 오류 뒤 저장 버튼이 disabled다. - V3: tests/features/reference-feature/reference-production-vertical.test.tsx "saves the corrected value after a server 422 field error"는 수정 전에도 통과한다(재현 안 됨, 동작 고정). - GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated 422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을 더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client. test.ts에 400 VALIDATION_FAILED effect 단언을 더했다. tests/unit·contract·runtime-schema·integration·component·features·platform 3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts, 기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint 통과. Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표문제 - 새 기능은 참조 기능을 복사해 이름을 바꾸는 방법뿐이다. 리뷰 16 실험 E 에서 이 방법은 12번 막혔다. 접두어 없는 전역 ID(NoRequest, qinv topic, navigationOrder)는 치환으로 바뀌지 않고, 토큰 경계 없는 치환은 preference·supportReference를 깨뜨린다. 제품이 참조 기능을 지우면 복사할 원본도 없다. 고른 방법 (결정 D1·D2, 오케스트레이터 결정 2·4) - scripts/create-feature.ts: pnpm create:feature <id> [--context <ctx>] [--package @scope/name@x.y.z --digest sha256:… --revision <hex>]. 템플릿을 이 파일 안에 두고 참조 기능을 import하지 않는다(D1). - 뼈대: 파라미터 없는 목록 라우트 1, GET 1(SAFE, EXTERNAL_BEARER), 쿼리 1, topic 1, CollectionPage 1, ko-KR·en-US 문구. domain/ 없음. 검증은 공유 zodValidator, 링크는 route ID와 buildRouteUrl (<base>-routes.ts). 빈 배열 응답은 공유 빈 상태로 그린다. - 전역 ID는 모두 기능 접두어를 단다(D2): 스키마·mapper·operation· contribution·policy·diagnostics·chunk·route·namespace·definitionId· 문구 키·telemetry kind·owner. topic은 qinv. + 무작위 26자(Crockford base32)이고 설치된 topic과 겹치면 거부한다. navigationOrder는 설치된 최댓값 + 10. - 패키지 인자가 없으면 결정 2의 자리표시자 상수를 import해 쓰고 경고를 출력한다. 인자가 있으면 external-contract-runtime의 신원 검사 (composeContractContributions)로 형식을 확인한다. - 거부: kebab이 아닌 id, 기존 기능·context id(디렉터리 이름 포함), 같은 접두어를 쓰는 기존 기능, 이미 있는 <base>-context(--context 안내), 같은 라우트 루트·route ID·경로·chunk·문구 키. - 폴더 밖은 새 context 선언과 pending a11y 기록만 쓴다. 기존 파일은 덮어쓰지 않고(wx), 쓰기나 직후 생성기 실행이 실패하면 만든 것을 지운다. - 출력: 만든 파일, a11y 서명(FE-GATE-028), 돌릴 게이트 목록, 기준선 재승인이 필요 없다는 안내, 자리표시자 교체 방법. - 테스트: tests/unit/create-feature.test.ts(렌더 결과만: 접두어, 샘플 토큰 없음, topic 형식·중복, 순서, 거부, 덮어쓰기·되돌리기). 생성된 기능의 테스트는 input 단위 테스트와 런타임 조립·라우터를 거치는 페이지 테스트다. MSW는 createHttpScenarioHandler(설치 계약)를 쓴다. - 느린 드릴 test:feature-scaffold: removal-fixture로 만든 복사본(README· CHANGELOG·docs 포함)에 기능을 만들고 커밋한 뒤 types, lint, architecture, registries, i18n, design-system, diagnostics, documentation, unit, component, integration, features, coverage, check:ci, build를 돌린다. FE-GATE-020에 넣고 gates.json, 계약 기준선, ci-workflow-generation 테스트의 개수를 맞췄다(workflow는 그대로). - 결정 4: test:sample-removal이 기능 0개 검사 뒤 같은 복사본에서 create:feature로 기능을 만들고 같은 게이트를 scaffold- 이름으로 다시 돌린다. - tests/release 고정 manifest가 계약 집합을 빈 배열로 고정해, EXTERNAL_ PACKAGE를 쓰는 첫 기능에서 7건이 release-mismatch로 깨졌다. 16-02가 tests/runtime-schema에 한 것처럼 설치된 집합에서 만든다. - 버린 대안: 참조 기능 복사+토큰 치환(D1에 어긋나고 전역 ID를 놓친다), topic을 뼈대에서 빼기(실제 기능이 같은 문제를 다시 만난다), 생성 테스트가 tests/mocks의 bootstrap·server를 쓰기(부팅 문서는 테스트 안의 fetcher가 주고, MSW는 setupServer와 http-scenarios만 쓴다). 위험·한계 - 생성기 파일이 1,408줄이다. 대부분 템플릿 문자열이다. - context-module.ts는 생성기가 글로 읽는 선언이라 실행되지 않는다(참조 context와 같다). 나머지 생성 모듈은 생성된 테스트가 모두 실행한다 (함수 100%, 문장 100%, 페이지 분기 1개 미실행). - --context reference-context로 참조 context에 넣으면 참조 기능의 installed-context-routing 테스트(라우트 4개 정확히 일치)가 깨진다. 드릴은 새 context를 쓴다. - test:feature-scaffold, test:sample-removal, check:architecture는 pnpm이 필요해 worktree에서 돌리지 않았다. - tests/unit/feature-shape-growth.test.ts는 기준 커밋에서도 1 KiB를 넘어 실패한다(이번 측정 1035·1068). 기능이 하나 더 있으면 통과한다. 검증 - RED: 생성한 기능을 넣고 돌리면 tests/release 7건 실패("expected { state: 'release-mismatch' } to match { state: 'booted' }"), ci-workflow-generation 1건 실패(98 vs 99). 접두어 테스트는 템플릿의 스키마 ID를 "NoRequest"로 바꾼 변이에서 실패한다. - GREEN(worktree에 order-feature 생성): tsc app·test·node rc=0, 전체 eslint rc=0, check-registries "11 registries PASS; compatibility= additive"(기준선 재승인 없음), verify-documentation-readiness PASS_SCOPED, check-i18n PASS, check-design-system·check-diagnostics· check-adapter-inventory PASS, check-ci-contract·workflow·artifact schema PASS, 생성 테스트 7/7, run-vitest tests/unit·component·features 238파일 통과, integration·contract·runtime-schema·platform·architecture· release·scripts 59파일 통과(pnpm을 띄우는 2파일 제외). - --context reference-context와 --package 변형도 tsc·registries·생성 테스트 통과. 참조 기능을 지운 복사본에서 생성 → tsc app·test, i18n, 생성 테스트·release·router 테스트 통과(결정 4 모의). - 생성물을 지운 뒤 같은 검사 통과(feature-shape-growth 기존 실패 1건 제외), git status 깨끗.문제: 855d22a가 ko-KR 샘플 문구를 한국어로 바꿔 목록 h1이 "참조 기능"이 됐다. reference-route.spec.ts는 h1이 route 제목("Reference feature")과 같다고 기대해 세 엔진 모두 실패했다. 화면은 정상이었다(같은 실행의 스크린샷에 h1, 인증됨, 모의 행이 모두 보인다). 그 수정 때 e2e를 돌리지 않아 놓쳤다. 방법: reference-form.spec.ts처럼 h1 문구를 직접 적는다. route 제목은 아직 catalog 밖 영어라(08-06 몫) h1과 같지 않다. 버린 대안: catalog에서 문구를 import — 다른 e2e와 방식이 갈린다. 검증: playwright test tests/e2e/reference-route.spec.ts — chromium· firefox·webkit 3 passed. 전체 test:e2e는 이 한 건 외 184 passed.문제: 결정 반영 묶음을 다 합친 뒤의 게이트 결과, 매뉴얼만으로 기능을 추가한 재실험 결과, 그 과정에서 찾은 결함이 리뷰 README와 CHANGELOG에 없었다. 방법: - 리뷰 README 14.3에 세 가지를 더했다. - create:feature와 참조 기능(V3 실행기)이 짝 백엔드 Envelope 응답을 읽지 못한다(High, P1, 결정 필요라 남김). - 매뉴얼 재실험 결과: 막힘 5건, 예고된 실패 1건. 막힘은 매뉴얼에 메웠다. - webkit old-tab-chunk-recovery 간헐 실패. - 14.5에7c7ef32최종 게이트 표를 둔다. - CHANGELOG 알려진 제한에 Envelope 제한과 webkit 간헐 실패를 더했다. 버린 대안: Envelope 제한을 이번에 고치기. V3 실행기에 Envelope 읽기를 넣을지, 백엔드가 problem+json을 보낼지는 두 repo에 걸친 결정이다. 게다가 백엔드 repo는 사람만 커밋한다. 위험: Envelope 제한이 풀리기 전에는 생성한 기능을 짝 백엔드에 바로 붙일 수 없다. 매뉴얼 01-3단계가 이를 적는다. 검증: tests/unit/changelog-review-ids.test.ts 통과. webkit 반복 실행 10/10 통과(load 16).문제: `check:remediation-ledger`가 3건 실패한다. TR-02: tests/unit/presigned-transfer.test.ts does not mention TR-02 TR-03: tests/unit/image-cdn-runtime.test.ts does not mention X-AUDIT-01 or X-AUDIT-02 TR-04: tests/unit/resumable-upload-runtime.test.ts does not mention TR-04 원인은 ID 표시가 지워진 것이 아니다. 2026-09-18 테스트 분할(`5cc41467`, `ec7f20e2`)이 세 테스트를 표시째 다른 파일로 옮겼고, 원장과 dispositions JSON은 옛 파일을 가리킨 채 남았다. 지금 위치: TR-02 → tests/unit/presigned-transfer-delivery.test.ts:220 TR-03 이미지 probe → tests/unit/image-cdn-browser-probe.test.ts:579 (X-AUDIT-02) TR-04 → tests/unit/resumable-upload-runtime-teardown.test.ts:80 분할 전 파일(`5cc41467^`)에 같은 주석과 테스트가 있었음을 확인했다. 고른 방법: 원장 행이 테스트가 실제로 있는 파일을 가리키게 한다. `docs/operations/adapter-remediation-dispositions.json`의 evidence 3곳과 `docs/operations/adapter-remediation-ledger.md`의 같은 행 3개를 고치고, 머리말의 "옮긴 suite" 메모에 이번 분할을 더했다. 앞 절의 실행 명령은 그 실행이 쓴 파일 그대로 둔다(그 시점 기록). 버린 대안: 옛 파일에 TR-02·TR-04·X-AUDIT ID를 적기. 그 파일에는 해당 테스트가 없어서, 검사기가 막으려는 "관계없는 suite를 가리켜 증거처럼 보이기"를 그대로 만든다. 검사기와 markers 규칙은 바꾸지 않았다. 위험·한계: 테스트를 다시 쪼개거나 옮기면 같은 식으로 깨진다. 이 검사는 게이트 밖이라 그때도 아무도 모른다. `config/ci/ungated-scripts.json`의 이 검사 사유("Later fixes removed those markers … reports stale claims")는 이제 사실과 다르지만 이 커밋 범위 밖이라 고치지 않았다. 검증: - RED(`ec7435c`): `node scripts/check-remediation-ledger.ts` 3건 실패, exit 1 - GREEN: "25 dispositions joined …; 0 open; evidence paths verified", exit 0 - 증거 suite 5개 77건 통과(`node scripts/run-vitest.ts run` 해당 파일) - `verify-documentation-readiness.ts` PASS_SCOPED, `check-ci-contract.ts` PASS, `check-adapter-inventory.ts` PASS, `tests/unit/ungated-scripts.test.ts` 10건 통과문제 create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기 (http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로, 실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는 모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는 키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝 백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는 결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만 들어갔다. 고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기 - V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를 둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과 같다. - ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤 프레임을 확인한다. outputValidator는 data(키가 없으면 null), problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은 새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은 min(64 KiB, responseByteLimit)이다. - V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을 backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께 읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨, 409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을 classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와 같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다. - create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem 스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은 <base>-http-gateway.test.ts를 생성한다. - MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로 답한다. 버린 대안 - provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다. 참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두 모양의 API를 쓸 수 없다. - (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두 Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다. - (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별· 멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다. 위험·한계 - HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는 exhaustive switch는 분기를 더해야 한다. - 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저 정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과 불명이다. - V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸 KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조 예산은 V3에만 있다. - 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는 모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는 돌리지 않았다). - 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B). 검증 - RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건 실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED, 조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작 고정). - GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code· httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로 비교한다. - check:types, lint, check:architecture, check:adapter-inventory, check:registries, check:diagnostics, check:i18n, check:ci 통과. test:unit 2,604, test:component 244, test:integration 200 통과. tests/features·tests/contract 124건 통과. test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건, Envelope로 답하는 목록 화면 테스트 3건 포함). test:sample-removal 23개 검사 통과. check:bundle 통과(203,321 / 204,800 B). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6문제 짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기 code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와 INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와 REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을 확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다. 고른 방법 - VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존 키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN → invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE → invalidValue. - 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive, positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent, future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다. - 모르는 code는 그대로 form.validation.unknown이다. - 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로 넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다. 버린 대안 - SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽 문구를 고르면 틀린 말을 할 수 있다. - 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙 (check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다. - 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다. 목록은 테스트에 SHA와 함께 적었다. 위험·한계 - 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌 방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에 제안). - 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가 배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다. - 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기 청크에 있다. 검증 - RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두 백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은 "Name: 입력값을 확인해 주세요."를 보였다. - GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과. tests/component·unit·features 237 files 2951 tests 통과. - node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts: 237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS, compatibility=none. - tsc app·test 통과, 바꾼 파일 eslint 통과. - 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고 check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로 쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다. 그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">` 하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과 starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도 실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄). 고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트 `tests/component/layout-landmarks.test.tsx`. - 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각 `loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각 `loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도 검사 대상이 된다. - 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다. 확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식 페이지가 그 안에 있음, `href="#main-content"` 링크가 있음. - fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다. 버린 대안: - context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다. 설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리 아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다. - `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를 골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다. 위험·한계: - 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이 테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로 한다. - skip link가 첫 focus 대상인지는 보지 않는다. - 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금 `AppShell`만 돈다. 검증: - RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패 ("expected to have a length of 1 but got +0"). AppShell skip link href를 `#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다. - GREEN: 4건 통과(AppShell, context site, topics, studio). - tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때 `route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다. - 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`. 레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은 `NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found 화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의 라우트 모듈이다. - 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는 `route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는 `invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인). - 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만 붙어서 지금은 닿지 않는 값이다. 이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나, 그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다. 고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록 라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값 `UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를 쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트 id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지 않았다. 버린 대안: - context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히 가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자 kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의 `route_id` 검사가 약해진다. - context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트 id와 섞인다. - `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을 바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다. 위험·한계: - 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은 결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다. - [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다. 복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다. `route_id` 이름과 허용 문법은 그대로다. - 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지 않았다. 검증: - RED: context-boundary-diagnostics "unregistered handle" 1건이 `"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이 `"route_id": "context-offline"`로 실패(8건 중 3 실패). - GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영 (`projectTelemetryEvent`)도 통과한다. - 회귀: tests/{architecture,unit,features,platform,component,contract, runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306 files, 3,572건 통과. - tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries, check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.문제 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일을 16개에서 25개(entry 포함 26개)로 늘렸고, "HTTP/1.1 호스팅이면 다시 본다"를 남겼다. vite preview도 HTTP/1.1이다. 비용을 잰 적이 없어 위험이 열려 있었다. 고른 방법 - 지금 빌드와 묶은 빌드 두 가지를 쟀다. (가) 08-08이 나눈 초기 primitive 청크 4개(field·button·select·page-templates)를 하나로. (나) 묶을 수 있는 초기 청크 14개를 하나로(entry·preload-helper·boot, 부트 실패 화면 closure, 15-01 그룹은 뺐다). 같은 커밋을 임시 복사본에서 그룹 하나만 더해 빌드했다. - 측정: vite preview(HTTP/1.1, gzip), Chromium CDP 네트워크 에뮬레이션 (DevTools Fast 3G·Fast 4G 값), 새 context·캐시 없음, 첫 화면 = boot 셸이 사라지고 route h1이 들어온 시각. 세 빌드를 번갈아 7번씩, 중앙값. HTTP/2(node:http2, 자체 서명 인증서, gzip)도 같은 방법으로 쟀다. - 결과(Fast 3G / Fast 4G 중앙값) - 지금 26개 202,782 B: 5,887 / 1,874 ms - (가) 23개 201,818 B: 5,426 / 1,764 ms - (나) 13개 198,673 B: 4,930 / 1,535 ms - HTTP/2: 지금 4,793 / 1,444, (가) 4,769 / 1,440, (나) 4,708 / 1,422 ms - 판단: 묶지 않는다. 측정값과 판단을 performance-evidence.md에 적고, vite.config.ts의 "재검토" 주석이 그 절을 가리키게 한다. - (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로 고를 방법이 없었다. boot 정적 closure는 design-system 배럴을 지나 갤러리 전용 primitive까지 잡는다. rolldown `$initial` 태그는 entry가 앱을 dynamic import로 읽어서(09-03) 아무것도 잡지 않는다. boot.tsx를 entry로 더하면 manifest 분류가 lazy 화면까지 초기로 센다(28개, 216,820 B, 예산 초과). - 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 맞춰야 하고, 낡아도 실패하는 검사가 없다. 08-08이 같은 이유로 manualChunks 이름 고정을 버렸다. - 템플릿은 HTTP/2 이상 서빙을 전제로 본다. HTTP/1.1로만 서빙하는 제품은 (나) 같은 그룹을 넣고 셸을 바꿀 때마다 다시 잰다고 문서에 적었다. 버린 대안 - (나)를 고정 목록으로 넣기: HTTP/1.1에서 Fast 3G 0.96초 빠르지만 숨은 결합이다(위). - (가)만 넣기: 0.46초. 같은 이유. 위험·한계 - HTTP/1.1로 서빙하는 다운스트림은 첫 화면이 Fast 3G에서 약 1초 늦다. 이 커밋은 그 비용을 없애지 않고 숫자와 전제를 적는다. 호스팅 HTTP 버전을 검사하는 게이트는 없다(FE-GATE-019 probe 밖). - 측정은 이 머신의 loopback과 CDP 에뮬레이션이다. 연결 수립(TCP·TLS) 비용은 CDP 지연에 들어가지 않는다. loadavg는 HTTP/1.1 측정 6~20, HTTP/2 측정 3~6이라 두 표끼리는 비교하지 않는다. 각 표 안은 번갈아 재서 비교할 수 있다. 검증 - 빌드 바이트: classify-vite-bundle + gzipSync(check:bundle과 같은 계산). 지금 빌드는 기준 202,770 B(local-build)와 맞다. - 측정 스크립트와 로그는 커밋하지 않았다(worktree의 .tmp/ra/, 일회성). - node scripts/verify-documentation-readiness.ts: PASS_SCOPED. - npx eslint vite.config.ts, npx tsc --project tsconfig.node.json --noEmit 통과.문제 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으로 실행한다.문제 조립 루트는 응답이 있는 UNAUTHENTICATED면 프로필을 보지 않고 authSession.onUnauthenticated()를 불렀다. ANONYMOUS 요청은 세션을 묻지 않고 헤더 없이 나가는데도, 그 401이 로그인한 사용자를 로그아웃시키고 scope fence가 서버 상태 캐시를 모두 비웠다. 제품 credentialProviders가 자격 증명을 낸 요청의 401도 템플릿 세션을 로그아웃시켰다. 고른 방법 attachCredentials와 같은 순서로 401의 주인을 가른다(reportServerUnauthenticated). - ANONYMOUS 프로필: 아무에게도 알리지 않는다. - 제품 provider 프로필: 세션은 그대로 두고, ProductComposition의 선택 hook onCredentialRejected({operationId, authProfileId})를 부른다. BFF 제품은 거기서 자기 owner에게 알린다. hook의 throw는 결과를 바꾸지 않는다. - 나머지(템플릿 세션이 낸 자격 증명): 지금처럼 onUnauthenticated(). 버린 대안: ANONYMOUS만 빼기(2줄)는 provider 경로의 과잉 로그아웃이 남는다. owner가 401을 직접 판단하게 하면 owner 계약이 바뀌고 모든 owner가 판단 로직을 쓴다. 위험·한계 - 제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이 hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02 5절에 적었다. - 401 도착과 계정 전환이 겹치는 경쟁은 여전히 확인하지 않았다. 검증 - RED: 새 테스트 3건(ANONYMOUS 401 demo·external, provider 401)이 수정 전 실패했다. bearer 대조군은 수정 전후 모두 통과. - node scripts/run-vitest.ts run runtime-adapters-{auth-profile,credential-order}, runtime-adapters, product-composition-fixture, reference-runtime-composition → 5 files / 62 tests 통과. check:types 통과. eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-01문제 validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는 Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty· __proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다. 그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다. 고른 방법 같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼 Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은 타입 선언과 다른 표의 관용이 갈려 버렸다. 위험·한계 짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다. 검증 - RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과. - form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03문제: inspect()는 active pointer 읽기가 실패하면 그 실패를 그대로 돌려준다. 손상 pointer(CORRUPT_DATA)는 조회·cleanup을 막고 다음 activation이 rollback 없이 덮어쓰는 상태인데, 그 상태를 진단할 유일한 관리 API도 같이 멈춘다. 운영자는 어떤 후보가 남았는지, 다음 activation이 무엇을 덮어쓰고 그 뒤 cleanup이 무엇을 지울지 모른 채 배포한다. PublicCacheInspection에는 pointer 상태를 담을 칸이 없다. 고른 방법: PublicCacheInspection에 activePointer("NONE" | "READABLE" | "UNREADABLE")를 둔다. pointer 읽기가 CORRUPT_DATA면 UNREADABLE로 적고 activeReleaseRegistryId는 null로 둔 채 후보 목록을 끝까지 채운다. 일시 오류(UNAVAILABLE 등)는 지금처럼 실패로 돌려준다. activation이 이미 쓰는 "CORRUPT_DATA만 손상으로 본다" 규칙과 같다. recipe fake도 같은 칸을 채운다. 리뷰가 함께 적은 inspect 전용 operation 이름은 공유 operation union을 바꾸는 일이라 이번에 하지 않았다. 위험·한계: 공개 포트 타입에 필수 칸이 하나 는다. 결과를 읽는 쪽은 그대로지만 이 포트를 직접 구현한 쪽은 칸을 채워야 한다([계약]). repo 안 소비자는 없다. inspect의 signal·판정 불가(0929/02-02)는 그대로다. service-worker-pwa 번들 9,733 → 9,758 / 10,100 gzip B. 검증: - RED: public-response-cache-repair.test.ts 새 테스트가 activePointer 없음으로 실패. - GREEN: 같은 파일 11건 통과(손상 중 inspect ok, UNREADABLE, 후보 r1·r2 verified, 일시 오류는 UNAVAILABLE). cache 단위 3파일 + tests/recipes 63건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-05문제 FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이 지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API registries"), frontend-application-foundation.md("composes the V2 API registries"), starter-experience.md 기능 추가 2단계("the API contract (operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는 칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다. 고른 방법 네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는 application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서 투영한다(installed-feature-runtime-registries.ts와 같다). 위험·한계 verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다. 검증 - git grep "V2 API registr|runtime schemas, mappers|runtime schemas and mappers" -- src docs/architecture → 0건. - verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10 Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05문제 ContractContributionError의 message는 "Installed contract contribution is not composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는 message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에 operation id도 프로필 id도 없었다("missing registry source …: Installed contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience 정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …" 메시지를 약속했다. 고른 방법 message에 reason을 붙인다: "Installed contract contribution is not composable: <reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을 보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를 그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다. 문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로 고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다. 위험·한계 - check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object registry, breaking change missing evidence … removed)은 그대로다(14-06 범위). - message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다. 검증 - RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN 으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패. - 같은 파일, external-contract-runtime, http-execution-v3-auth-profile, reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과. - eslint, tsc(test), verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07문제 registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은 `${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작, `//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를 dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과 `/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰 실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다. 고른 방법 - safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만 받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다. query는 그대로 남는다. - 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된 registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에 throw하는 쪽이 이르고 작다(리뷰 5.3 (a)). 위험·한계 - 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도 거절된다. registry를 쓰는 제품 코드는 아직 없다. - registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께 둬야 한다(리뷰 재검토 조건). 검증 - 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위 6파일 76건 통과. - 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02문제: react-router 7.18.1의 exports는 모든 조건에서 dist/development/*를 가리킨다. 그 파일은 ENABLE_DEV_WARNINGS = true라 운영 번들의 초기 청크에 라우터 개발 경고 문구("You rendered descendant …")가 들어 있었다. 운영 콘솔에 개발 경고가 뜨고, 초기 JS가 약 600 B 크다. 고른 방법: vite build일 때만 react-router-dom이 import하는 두 진입점 (react-router, react-router/dom)을 같은 패키지의 dist/production 파일로 alias한다. 경로는 react-router-dom에서 react-router를 resolve한 개발 진입점 옆에서 찾고, 파일이 없으면 빌드를 멈춘다. 개발 서버와 테스트는 개발 빌드를 그대로 써서 경고를 받는다. 버린 대안: 고정 경로 alias(리뷰 실험). 업그레이드로 배치가 바뀌면 조용히 깨진다. react-router에 production 조건을 요청하기는 시점을 정할 수 없어 이 alias를 지울 조건으로만 적었다. 위험·한계: exports 밖 경로를 쓴다. 업그레이드 때 배치가 바뀌면 빌드가 실패한다(조용히 개발 빌드로 돌아가지 않는다). Firefox·WebKit e2e는 돌리지 않았다. 검증: tests/unit/build-environment-bundle.test.ts가 빌드한 JS에 개발 경고 문구가 없음을 본다(고치기 전 chunk-KS7C4IRE 1개에서 실패). 같은 빌드(local-build) 초기 JS 201,552 → 200,939 B(−613 B), 파일 25개. 라우터를 쓰는 e2e 5개 spec 14건(app-shell, reference-route, reference-save, scroll-restoration, platform-overview, chromium) 통과. Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-07문제 워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값 (CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과 정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅 live probe는 index가 가리키는 entry script 하나만 요청하고 hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain, 글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는 글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다. 고른 방법 - probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다 첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다. 결과는 surface hashedAsset.<ext>, header content-type이다. verify-hosting-headers live 모드에서만 부른다. - 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와 같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가 지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset). - 운영 문서(release-cache-rollback.md)에 새 검사를 적는다. - 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸 응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다. (c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만 — 검출이 없다(리뷰 5.2). 위험·한계 - live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개). - 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이 다른 호스트는 잡지 못한다. - cache-control은 이 자산들에서 다시 보지 않는다. entry script의 hashedAsset 검사가 그대로 본다. - 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다. - 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새 함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다. 검증 - 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드: hosting-probe·service-worker-build-output 테스트 통과. - CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL. - check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03문제 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문제 Envelope 실패 해석이 422를 모두 필드 검증으로 본다 (isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는 "같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가 VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다. 사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는 지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다. 고른 방법 422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만 필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다. 400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원 참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로 NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다. 버린 대안 IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록 없는 다른 422가 계속 입력 오류로 보인다. 위험·한계 422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드 오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다. 검증 - RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH· INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구 없음) 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다 ("keeps the save off after a 422 the backend may have applied"). - check:types:app·test, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05문제: withTransactionLock은 partition lock을 signal 없이 요청한다 (withPartitionLock("shared", operation, undefined, run)). put·remove의 request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면 시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만 걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은 partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면, 삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기). 05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다. 고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고, withPartitionLock은 kernel createAbortableOperation으로 caller signal과 mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의 acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를 지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다). lock 전 abort는 journal begin 전이라 보상할 것이 없다. 버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이 남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다. 위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다. 다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고 호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort 경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb 번들 37,521 → 37,555 / 38,500 gzip B. 검증: - RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에 끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지 않아 10초 timeout. - GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건 통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS, verify:documentation 통과. - browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진 27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러 5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02문제 기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은 "missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable" 두 줄, "FE-REG-API is not an object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA", "breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은 ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다. 끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을 제안한다(실험 E-9). 고른 방법 - source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께 적는다. - 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사 ("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교 (removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지 않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다. - errors.md 레지스트리 표에 이 메시지 행을 더했다. 버린 대안 - 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와 CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다. 위험·한계 - source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도 "missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서 지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다. - FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다. 검증 - RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가 다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를 던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고 cascade 3줄이 더 나와 실패했다. - GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록 operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason: reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다. - check:registries:fixture·check:routes:fixture·baseline-fixture가 기대 진단으로 실패한다. eslint, check:types:node, check:types:test 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06문제 워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번 리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect: "error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의 CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8). 고른 방법 - service-worker-runtime.test.ts에 테스트 3건을 더한다. - install이 자산마다 cache no-store, credentials omit, redirect error로 요청한다(M1). - 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은 client의 drain 응답은 세지 않는다(M3, M9). - active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8). - 동작은 바꾸지 않는다. 위험·한계 - N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를 흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다. 검증 - service-worker-runtime 64건 통과. - 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고 되돌렸다. - 바꾼 파일 eslint, check:types:test 통과. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04문제 짝 백엔드는 페이지 목록의 전체 수·페이지 번호를 meta.page(number·size· total·sort)에 싣는다(http-contract.md §1). 프론트 Envelope 읽기는 meta에서 id 셋만 남기고 data만 꺼낸다. 그래서 목록 기능은 첫 페이지(기본 20개)만 받고 전체 수를 모른다. 생성된 목록 화면의 "총 N개 항목"은 배열 길이라 페이지 크기를 전체 수처럼 보인다(리뷰 실험 X-G). 우회하려면 responseEnvelope를 빼야 하고, 그러면 Envelope 실패 판정을 함께 잃는다. 고른 방법 - backend-envelope.ts: meta에 page 스키마(정수, number·total 0 이상, size 1~100, sort 문자열 또는 null). 범위 밖이면 page만 버리고 응답은 읽는다. readSuccessEnvelope가 data와 함께 page를 돌려준다. - 실행기의 SUCCESS 결과에 선택 칸 page. outputValidator는 지금처럼 data만 본다. - 바인딩: mapSuccess(value, context)의 두 번째 인자 FeatureHttpSuccessContext { page? }. 한 인자짜리 기존 mapSuccess는 그대로 맞는다. - 배럴에서 EnvelopePage·FeatureHttpSuccessContext 타입을 낸다. - 계약 문서 4.1절에 meta.page 경로와 "bulk results는 지원하지 않는다", 7절에 "짝 백엔드는 offset meta.page"를 적었다. 버린 대안 - outputValidator에 { data, page }를 넘기기: 기존 기능 스키마가 모두 깨진다. - 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다. - page가 범위 밖이면 응답 전체를 거절: meta의 모르는 키는 무시한다는 백엔드 §1 규칙과 어긋난다. 위험·한계 - 생성기(create-feature.ts)의 목록 화면은 아직 배열 길이를 보인다. 생성기 담당 작업이 page.total을 쓰도록 이어 받는다. - bulk는 지원하지 않고 문서로만 알린다. 검증 - RED: envelope 통합 3건 실패(mapSuccess가 page를 받지 못함, 정렬 없는 page 2건). - GREEN: 같은 파일 51건 통과. 범위 밖 page 3건(size 500, number -1, total 1.5)은 page 없이 SUCCESS. tests/unit·integration·component·features· contract·runtime-schema 253파일 3,209건 통과. - check:types, lint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-02문제 AppFailure와 createFailure는 traceId를 받는다. 이를 채우던 곳은 V2 client.ts의 Envelope meta.traceId였고, 048f490이 V2를 지운 뒤 src에서 traceId를 넘기는 곳이 없다. 빈 칸을 믿고 만든 화면·진단 코드는 늘 undefined를 받는다. 짝 백엔드는 모든 실패 Envelope의 meta에 W3C trace id를 싣는다(http-contract.md §1). 고른 방법 - readFailureEnvelope가 error와 함께 meta.traceId를 돌려준다. 값은 이미 meta 스키마의 id 문법([A-Za-z0-9._:-]{1,128})을 통과한 것이다. - 실행기가 그 값을 PROBLEM 결과의 SafeResponseMetadata.traceReference에 싣고, 바인딩이 AppFailure.traceId로 옮긴다. requestId 경로(반사 헤더 → 보낸 id)는 그대로다. - 계약 문서 5절의 correlation 문단에 한 줄 더했다. 버린 대안 traceId를 타입에서 지우기(리뷰의 다른 선택지): 다운스트림이 쓰는지 확인이 필요하고, 백엔드가 이미 주는 지원용 id를 버린다. 위험·한계 - Envelope operation의 실패 응답만 채운다. 성공 뒤 매핑 실패, 전송 실패, Envelope 없는 operation은 traceId가 없다. - 텔레메트리에는 싣지 않는다(요청 단위 값). - 같은 발견의 VD-23 401 문장은 다른 작업 몫이라 건드리지 않았다. 검증 - RED: envelope 통합 1건 실패(404 실패의 traceId 없음). - GREEN: meta.traceId가 있으면 그 값, 없으면 칸 없음. tests/unit· integration·component·features·contract·runtime-schema 253파일 중 252파일 통과. 남은 1건(provider-guardian-transaction "cleans a linked raw inode")은 이 기계의 inotify 한도(ENOSPC watch)로 단독 실행에서도 실패하며 이 변경과 무관하다. - check:types, lint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-06문제 test:sample-removal은 참조 기능을 지운 복사본에서 test:unit을 돈다. 그때 product-extension-typecheck 픽스처 기능이 유일한 기능이 되는데, 메시지 catalog가 비어 있어(messages: {}) 메시지 키 타입이 무너져 tsc app이 presentation 파일 수십 곳에서 실패했다. 템플릿 결함이 아니라 픽스처 기능의 모양 문제다. 고른 방법 픽스처 기능에 두 locale의 메시지를 준다. two-feature-install-typecheck 픽스처와 같은 모양이다. 위험·한계 없다고 보는 이유: 테스트 픽스처 문자열만 바뀐다. 검증 - product-extension-typecheck.test.ts 통과(전체 repo). - test:sample-removal 재실행 결과는 브랜치 보고에 적는다. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이 그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은 상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다. 고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와 상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음 upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙 줄에 재조정 경우를 더했다. 위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다 status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은 한계다. 검증: - 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와 같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음, 다음 호출이 정리 - 영역 단위 테스트 15파일 276건 통과 - check:types(test), eslint(바꾼 파일) 통과 Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02문제: 1101/02-04의 두 변이가 이번에도 cache 단위 테스트를 모두 통과했다. N26b는 Cache-Control: no-cache 거절, N26은 Set-Cookie 응답 거절을 지운다. 둘 다 빠지면 사용자별이거나 재검증이 필요한 응답이 익명 공용 캐시에 들어간다. 기존 표는 no-store·pragma·www-authenticate만 따로 보았다. 고른 방법: 응답 검증 표("keeps response validation failure codes")에 두 행을 더한다. 각 행은 규칙 하나만 어긴다. 위험·한계: 테스트만 바꾼다. 검증: 두 변이를 하나씩 넣고 cache 단위 3파일 + tests/recipes를 돌렸다. 둘 다 이 테스트가 실패했고 되돌린 뒤 통과. eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04문제 tests/fixtures/architecture/forbidden/**에는 fixture 전용 ESLint 블록이 붙어 있었다. 모든 계층의 금지 import와 fetch·localStorage·sessionStorage 금지를 합친 것이다. check-architecture.ts는 fixture마다 ESLint 종료 코드가 0이 아니면 거부됐다고 셌다. 그래서 운영 src/presentation/** 블록에서 계층 import 금지와 fetch 금지를 지워도(변이 M2) check:architecture는 "9 forbidden rejected"로 통과했다. 전역 fetch·localStorage 금지는 이 ESLint 블록 말고 지키는 검사가 없다. 고른 방법 - 새 scripts/lib/architecture-lint-fixtures.ts가 fixture마다 그것이 대표하는 운영 경로(lintAs, 예: src/presentation/__architecture_fixture__/…)와 거부해야 하는 규칙(rejectedBy)을 적는다. ESLint API lintText(code, { filePath })로 그 경로의 운영 설정을 그대로 적용한다. 금지 fixture는 그 규칙이 보고해야 통과하고, 허용 fixture는 계층 규칙(no-restricted-imports·globals)이 아무것도 보고하지 않아야 통과한다. 목록에 없는 fixture 파일도 실패로 센다. - domain fixture는 domain 코드가 실제로 사는 src/features/*/domain 블록으로 검사한다(최상위 src/domain 폴더는 없다). - fixture 전용 ESLint 블록을 지운다. check-architecture.ts에서 쓰이지 않게 된 pnpm 하위 프로세스 실행과 npm_execpath 요구를 지운다. - 버린 대안: 금지 fixture 삭제. import 방향은 그래프가 지키지만 전역 금지의 검출이 0이 된다. 종료 코드만 보고 운영 경로로 옮기기. 다른 규칙(화면 문구 등)이 걸려도 거부로 센다. 위험·한계 - 계층 규칙 이름이 바뀌면 fixture 표의 rejectedBy도 같이 고쳐야 한다(고치지 않으면 실패로 드러난다). - 출력 문구가 "3 allowed PASS, 9 forbidden rejected by the production rule for their layer"로 바뀐다. 이 문구를 읽는 스크립트는 없다. 검증 - RED: 수정 전 변이 M2(운영 presentation 블록의 계층 import 금지와 fetch 금지 삭제)에서 check:architecture exit 0, "9 forbidden rejected". - 수정 뒤 같은 변이에서 check:architecture exit 1, presentation fixture 5개가 "was accepted"로 실패. 되돌린 뒤 exit 0. - 새 tests/unit/architecture-lint-fixtures.test.ts 3건(운영 설정 통과, overrideConfig로 규칙을 끄면 실패, 목록 밖 fixture 실패) 통과. architecture-report 3건 통과. check:types 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-04문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel (src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만 적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After, JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent factory까지 10개 파일이 있다. 편입 기준("must never own")은 indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지 문서로는 알 수 없다. 고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유 메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를 가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음). 위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을 넣을지를 기계가 보지 않는 것은 그대로다. 검증: check:architecture, verify:documentation 통과. bootstrap 밖에서 lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다. Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-08문제 /examples/ui, /examples/states, /examples/auth(와 /examples/platform)는 플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와 FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다. 릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된 수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고 서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다. 고른 방법 - UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다. 자기 context platform-examples-context(루트 examples/*)에 산다. reference-context의 examples/reference-resources/*와 플랫폼 라우트 /examples/platform이 더 구체적이라 그 URL은 그대로 간다. - 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y 기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을 쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다. - 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context routes에서 페이지마다 lazy로 받는다. - 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는 같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰 lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지 청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를 routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약 (페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를 지키려고 이 한 화면은 남겼다. - 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을 "{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼 구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의 화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open 하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사 (product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다. - 예제 화면 component 테스트는 tests/features/platform-examples-feature/로 옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는 기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의 "플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다. - old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서 찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이 잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다. - 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의 예외에 새 폴더를 넣었다. - 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만 제품이 지우게 둠(동기화 충돌 자리가 남음). 위험·한계 - 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery, state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY· PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH, home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다. - 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다. - tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다. 예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다 (starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지 않아 이것을 보지 않는다. - 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백) 때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을 임시로 고친 상태에서 낸 것이다(커밋하지 않음). - 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도 재지 않는다. 검증 - product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드): 홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친 뒤 통과. - test:sample-removal -- --feature=platform-examples-feature(heavy lock, 16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture, registries, test:all, coverage, test-evidence, ci, home-smoke, build, route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가 측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서 측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다). - test:unit 2,587, test:component 253, tests/features·platform· architecture 383 통과. check:types, lint, check:architecture, check:i18n, check:registries(additive), verify:documentation 통과. - test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine). old-tab-chunk-recovery 포함. test:a11y 60 passed. - build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B). - lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음 d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04 BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가 플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은 src/features/platform-examples-feature/presentation/으로 갔고, PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT· PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키 home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다. 예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.문제 merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍, 플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이 찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px, 3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를 고정 글꼴 환경에서 다시 찍어야 했다. 고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기) - 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을 display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은 실패를 낸다. - 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은 ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을 고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이 빠진다. - 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능 절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성 기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력 카드·나머지 릴리스 신원은 남긴다. - 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다. - 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과) 에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다. - 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남), 골든을 제품 소유로 선언(동기화마다 PNG 충돌). 위험·한계 - 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는 component·e2e 테스트가 본다. - 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성 보기" 버튼만 남는다. 검증 heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6: - test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성). - 깨끗한 상태 6/6 통과. - create:feature probe-feature(새 context) 뒤 6/6 통과. - probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과. 생성 파일은 지웠다. - 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem. 넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다. - 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이 710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가). - eslint, check:types:test, check:test-evidence:source 통과(mask 전체 가림 규칙에 걸리지 않음). Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01문제 - 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드 new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를 만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07). - 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는 참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서 쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을 함께 옮긴다(09-06, 16 5.3절). - 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지 않는다(03-02 수정이 남긴 일). 고른 방법 - 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로 API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다. - 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈 목록은 EmptySurface로 같은 빈 상태를 그린다. - --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마 (이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity), 작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키 없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의 KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다. - 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite ["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드 보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에 거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다. - 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope, 404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 → MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키 1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)). 작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에 보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시 보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다. - 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다. - slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절 재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을 필요한 자리로 좁힌다. - X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그 모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는 단위 테스트를 더한다. 버린 대안 - 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이 새 항목을 만든다. 안전해 보이는 거짓 보장이다. - 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수 바꾸고 problem details 예제가 사라진다. - 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열 속성을 버린다. 위험·한계 - 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을 더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다. - 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선 203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라 --with-create 기능 하나를 넣으면 134 B가 남는다. - 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과 경로를 읽어 생성 테스트에 옮겼다. 검증 - RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과. - 기본·--with-create·--with-create --keyed·--context reference-context --with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint, check:registries(additive), check:i18n, check:architecture, check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능 테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만 실패(X1, 다음 커밋). - 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의 responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패. - flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create 기능 204,666 / 204,800 B PASS. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06 Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07 Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01문제 리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다. - 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가 "실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다. 실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다. - 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가 실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만 실패하고 check:types·check:architecture·verify:documentation은 통과한다. - 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400 VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는 Envelope operation에서 결과 불명이다. - starter-experience.md: "`NoRequest` already belongs to the sample". src에 NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다. 다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app). 고른 방법 문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지 않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로 적는다. 매뉴얼에 그 테스트를 가리켰다. 위험·한계 - 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는 돌리지 않았다. 검증 - 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0, check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림. - verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08문제 `create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를 선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을 그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이 집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가 CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를 보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의 test:browser-capabilities가 38건 실패하고("Execution context was destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을 더하는 재실험(리뷰 조치 X2 #3)에서 찾았다. 고른 방법 - dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를 시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려 src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고, `/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에 설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다. - 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을 import해야 하는데, Vite 설정이 그것을 불러오면 안 된다. - build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다. - 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가 contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을 다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다. 위험·한계 - dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다. - 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다). 검증 - tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로 바꾼다, 템플릿 그대로면 자리표시자와 같다). - check:types, lint, check:architecture, check:ci 통과. - 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다. Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3문제 config/scale/feature-shape-ceilings.json의 initialJavascript는 지금 설치된 기능으로 만든 빌드를 기록하고, test:unit이 빌드와 대조한다(1103/15-02). 제품이 기능을 더하면 기록을 다시 써야 FE-GATE-005가 통과한다. 그러면 `test:sample-removal -- --feature=<id>`가 그 기능을 지운 fixture에서 반대 이유("record 27, build 26")로 실패한다. 두 게이트를 함께 통과시킬 방법이 없다(리뷰 조치 X2 #2). 고른 방법 - 드릴이 레지스트리 기준선을 다시 찍는 것과 같은 자리에서 measure-feature-shape-growth.ts --initial-baseline --write를 fixture에서 돌린다. 제품이 기능을 지운 뒤 할 일을 드릴이 그대로 한다. - 샘플 제거는 측정 스크립트를 함께 지우므로 그때는 건너뛴다. 위험·한계 - 측정이 빌드를 하므로 기능 제거 드릴이 1~2분 길어진다. 검증 - eslint 통과. 기능 제거 드릴은 X4 재실행(test:feature-scaffold 안의 feature-removal)에서 확인한다. Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, README.md 14.6 X2 #2문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using link preload but not used within a few seconds from the window's load event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중 3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지 않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두 불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload 한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은 reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가 그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium· Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다 (1103/11-09). 고른 방법: - strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른 console warning·error는 그대로 실패다. - 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로 "preload한 script가 실제로 실행됐는가"를 본다. - 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터 MutationObserver로 적고, 끝에 남은 link도 더한다. - page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는 문장 하나를 앞에 붙인다. - test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로 실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다. - "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox) 받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그 문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의 "참조됨"과 달리 시각에 기대지 않는다. - 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed). - script가 아닌 preload는 `preloadunverifiable:<as>:`. - Service Worker가 문서를 제어할 때 만든 preload는 `preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서 page.route가 못 본다. context.route로 worker가 받는 것을 표시하면 release manifest의 sha256 대조가 깨진다. - route.fetch가 세 번 실패해 표시 없이 넘어간 script는 `preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히 route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit reference-form 1건). - 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다. - boot-module-failure: 깨진 build의 boot 정적 closure. - old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이 허용이 WebKit 경고 문구로만 있었다. - service-worker-update: worker 제어 중 preload만. - production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는 fulfillBuildScript를 쓴다. 버린 대안: - (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만 test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가 늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다. - 청크 단계를 줄인다. 창이 좁아질 뿐이다. - 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다. 위험·한계: - 모든 strict fixture test가 build script를 page.route로 받는다. - 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다. - fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다). - worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패, service-worker-update만 허용). 검증 (desktop, CI=true와 workflow env): - RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패. - 변이 test는 세 엔진 모두 Expected ["preloadunused:/assets/async-state-Cxfod8c-.js"], Received []. - 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource …/reference-schemas-DICBcHlO.js was preloaded using link preload but not used …"로 실패. - GREEN: 9 passed. - 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나: - 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침). - 새 fixture: 3/3 실패, "preloadunused:/assets/async-state-Cxfod8c-.js". - 부모 청크 3.5초 지연 probe: - 이전 fixture: webkit 실패. - 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다 (probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]). - 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip). - check:types:test, 바꾼 파일 eslint 통과.문제: FE-GATE-008의 test:browser-capabilities가 firefox에서 가끔 30초 시간 초과로 떨어졌다. browser-files.spec.ts의 두 test가 번갈아 걸렸다. 하나는 "filechooser"를, 다른 하나는 "download"를 기다리다 끝났다. desktop에서 firefox capability suite를 30회씩 돌리면 두 test 60건 중 3건이 떨어졌다(두 번 모두). 부하와는 상관없었다(1.05에서도 남). 리뷰 14.7절은 이것을 "알려진 flake"로 두었다(1103/11-10). 원인: 두 test는 `goto("/")` 직후 label·input·button을 `<body>` 끝, 앱 root 뒤에 붙이고 그 button을 누른다. 그때 앱은 아직 그리는 중이다. 실패한 6건의 event 기록(진단 branch, 커밋 안 함)은 모두 같았다. - pointerdown·mousedown은 button("Choose test file"/"Download generated"). - 30~45 ms 뒤 pointerup·mouseup은 홈 화면 내용("프로젝트 시작점…"). - click은 둘의 공통 조상(앱 root)이라 button의 handler가 돌지 않았다 (`__browserFileResult` 없음). 그래서 picker도 download도 없었다. - 위치까지 적은 3건에서 그 사이 scrollY는 24로 같았다. body 높이는 744에서 756으로, button top은 696에서 708로 둘 다 12 px 늘었다. 앱 내용이 클릭 도중 12 px 자랐고, viewport 아래 끝의 button 중앙 좌표가 button 밖이 됐다. 통과한 run은 pointerdown 때 이미 756이었다. 고른 방법: 두 test가 붙이는 control을 `position: fixed` 층(왼쪽 위, 가장 높은 z-index)에 둔다. 앱의 흐름 밖이라 앱이 늦게 그려도 button이 움직이지 않는다. 제품 코드는 바꾸지 않는다. 버린 대안: - 앱이 다 그려질 때까지 기다린다. "다 그려짐"을 정할 신호가 없다. 늦게 오는 글꼴이나 내용이 생기면 다시 깨진다. - `dispatchEvent("click")`이나 `force` click. 신뢰된 사용자 입력이 아니어서 firefox가 file picker를 열지 않는다. test가 증명하려는 것을 지운다. - 재시도·timeout 늘리기·worker 줄이기. 금지된 우회이고 원인이 남는다. 위험·한계: 고정 층이 앱 header 왼쪽 위를 덮는다. 두 test는 앱 UI를 누르지 않는다. 다른 capability spec은 body에 control을 붙이지 않는다(grep). 검증 (desktop): - RED(커밋 안 한 재현): mousedown 때 앱 root에 400 px를 더하고 layout을 다시 계산한다(앱이 늦게 그리는 것과 같은 일). 수정 전 spec은 세 엔진 두 test 6/6 실패(filechooser·download 대기 시간 초과). - GREEN: 같은 재현에서 수정 뒤 6/6 통과. - 실제 조건 firefox capability suite ×30: 수정 전 두 번 다 3 failed / 657 passed, 수정 뒤 660 passed.fix: UI 감사와 11-01 성숙도 리뷰의 발견과 결정 24건을 반영한다to fix: UI 감사와 11-01·11-03 성숙도 리뷰의 발견을 반영한다