docs(review): 2026-11-03 프론트 전체 성숙도 리뷰를 기록한다

문제
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
This commit is contained in:
DongHyeonka
2026-11-04 00:18:59 +09:00
parent e40684b4e1
commit 9c521ecd75
17 changed files with 6006 additions and 0 deletions
@@ -0,0 +1,262 @@
# 01 browser-transfer 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/browser-transfer/`(배럴 `index.ts`, `presigned/`, `resumable-upload/`, `image-cdn/`), 포트 `src/application/ports/browser-transfer/`
> 깊게 본 관점: 1, 5, 6, 12, 14, 17, 28
> 이번 라운드 렌즈: 오늘 바뀐 것(V2 HTTP 경로 삭제, HTTP 오류 해석 변경)과 업로드·전송 경로의 경계가 여전히 맞는가. 실패 뒤 재개와 결과 불명 처리.
> 영역 판정(35.8): presigned 실행기·vault는 **지정 범위에서 사용 가능**. resumable upload runtime은 **조건부 사용 가능**(제품이 `PRESIGNED_MULTIPART_V1` 서버를 직접 만들 때. 01-02를 알고 쓴다). 짝 백엔드와 함께 파일 업로드를 출시하는 용도는 **해당 용도의 사용 보류**(01-01). image CDN runtime은 **지정 범위에서 사용 가능**(reference runtime 범위. descriptor 발급 서버는 01-01과 같은 이유로 짝 백엔드에 없다).
ID 표기: 이번 라운드 발견은 `01-01`부터 쓴다. 지난 라운드는 `1101/01-01`(2026-11-01), 그 전 라운드는 `0929/01-01`(2026-09-29)처럼 앞에 날짜를 붙인다.
## 0. 결론
- **새 High.** 프론트 업로드 레시피가 쓰는 서버 프로토콜(`PRESIGNED_MULTIPART_V1`, 브라우저가 object store에 직접 PUT)이 짝 백엔드에 없다. 짝 백엔드는 2026-09-25에 presigned·direct multipart 코드를 지웠다. 파일은 자기 Fileserver(multipart 한 번 요청, tus)로 받는다. 프론트에는 그 Fileserver를 부를 client가 없다. 두 템플릿의 어느 문서도 이 사실을 적지 않는다. 오늘 V3 실행기만 짝 백엔드 Envelope에 맞췄고, 업로드 control plane은 여전히 DTO 그대로·status만 읽는다(01-01).
- **새 Medium.** 지난 1101/01-01 수정으로 part 단계도 `Retry-After`를 기다린다. 그런데 값이 상한(기본 30초)을 넘으면 앱에 `retryable:true`를 준다. 포트 표대로면 "자동 재시도해도 된다"는 뜻이다. 같은 429에 control plane은 `retryable:false`를 준다. 결과가 두 factory(transport, runtime 정책)의 상한 중 어느 쪽이 큰지에 따라서도 바뀐다(01-02).
- 지난 발견 9건 재판정: **고쳐짐 3건**(1101/01-01, 1101/01-04, 0929/01-01), **남음 6건**. 0929/01-02는 남았지만 영향이 줄었다. 앱이 이제 `NONE` 대신 `RESUME`, `retryable:true`를 받아 다음 호출로 회복한다.
- 변이 18건 중 13건을 테스트가 잡았다. 생존 5건 중 3건은 테스트 빈틈이다: ABORT 키 재사용(세 라운드째), control plane의 헤더 없는 429, part 단계 503의 `Retry-After`(01-03). 2건은 남은 결함을 고친 모양이라 생존이 맞다.
- 영역 단위 테스트 15파일 265건 통과(1.96초, 직전 부하 18). Playwright 영역 spec 3개는 3엔진 9/9 통과다(정상 경로만). file-transfer 레시피 번들은 56,053 / 57,800 gzip bytes다(6.3절).
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. `src/adapters/browser-transfer/` 27파일(TS 26, README 1) 12,898줄. 포트 `src/application/ports/browser-transfer/` 5파일 818줄. 단위 테스트 15파일 + fixture 3파일 11,568줄. 브라우저 spec 3파일(`tests/browser-capabilities/{resumable-upload,presigned-streaming,image-cdn}.spec.ts`) |
| 커밋·작업 상태·확인 시점 | `e40684b`(두 작업 브랜치를 합친 리뷰 기준). 격리 worktree에서 `git checkout --detach e40684b`, `corepack pnpm install --frozen-lockfile`. 지난 리뷰 기준 `d99301b` 뒤 이 영역 코드 변경은 `95e4445`(1101/01-01), `6b7b53f`(1101/01-04), `9142390`·`c5f87aa`(0929/01-01)다. 영역·포트·kernel 12파일 +311/−162. 포트 2파일이 바뀌었다(`presigned-transfer.ts`, `resumable-upload.ts`). 오늘(2026-11-03)의 V2 HTTP 삭제 커밋(`048f490`, `12f3bb7`)은 이 영역 파일을 건드리지 않았다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `RECIPE_AVAILABLE` / `AVAILABLE_NOT_COMPOSED`, `productionComposition: false`(`config/recipes/frontend-capability-recipes.json:155-199`). 공개 경계는 배럴 `src/adapters/browser-transfer/index.ts` |
| 필수 요구와 규모·운영 목표 | 사용자 목표: 짝 백엔드 템플릿(`clean-architecture-backend-template` `7ef8d0b4`, 읽기만)과 함께 서비스를 빨리 출시한다. 규모·허용 실패율은 정해져 있지 않다. 기본 정책값(`runtime-policy.ts:60-81`)을 사실상의 목표로 보았다 |
| 읽은 코드·구성 범위 | 전부: `resumable-upload-runtime.ts`, `fetch-json-transport.ts`, `runtime-policy.ts`, `upload-mutation-lock.ts`, 포트 `resumable-upload.ts`, 지난 리뷰 뒤 바뀐 부분 전부(`git diff d99301b e40684b`). 필요한 부분: `http-control-plane-adapter.ts`(1-360행), `presigned/http-common.ts`(140-279행), `image-cdn-runtime.ts`(probe 단계), `upload-response-validation.ts`(`validateSession`), `indexeddb-checkpoint-store.ts`(CAS), kernel `browser-file-storage/result.ts`(기본값·IndexedDB 예외표), `platform/retry-after.ts`. 짝 백엔드: `docs/storage-capability-boundary.md`, `docs/capability-status.md:255-275`, `docs/fileserver/http-contract.md`, `docs/web/http-contract.md` 1·2절, `CorsExposedHeaders.java` |
| 읽은 문서(주장) | `docs/architecture/presigned-transfer-and-image-cdn.md` 0·1·4절과 280-300·380-395·725-746행, `server-file-capability-infrastructure.md` 머리·860-868·1652-1666행, `backend-api-and-server-state-contract.md:28-40`, `docs/manual/`(업로드 언급 검색), 지난 리뷰 `2026-11-01-maturity-review/01-adapters-browser-transfer.md`와 README 13·14절, `2026-09-29-maturity-review/01-adapters-browser-transfer.md` 4절 |
| 수행한 테스트·실험 | ① 영역 단위 테스트 `node scripts/run-vitest.ts run tests/unit/resumable-upload tests/unit/presigned-transfer tests/unit/image-cdn tests/unit/upload-cancellation` → 15파일 265건 통과, 1.96초(직전 부하 18.0) ② 실험 X1~X5(worktree의 `tests/unit/zz-area01-experiments.test.ts`, 끝난 뒤 지움) ③ 변이 18건(`scratchpad/a01-1103/mutate.mjs`, 결과 `scratchpad/a01-1103/mutations.log`) ④ `flock heavy.lock`으로 Playwright 영역 spec 3개 × 3엔진, `check:optional-recipes:source`(6.3절) ⑤ 게이트는 오케스트레이터 실행 로그(`review-gates/summary.txt`)를 읽었다: `check:architecture`·`check:types`·`lint`·`test:unit`(2,580건)·`check:adapter-inventory` exit 0. `test:unit` 로그에서 이 영역 15파일이 통과했다 |
| 실험 조건 | 단위 harness, 가짜 BFF·object store. X1·X2는 출하 코드(presigned provider·vault·실행기, HTTP control plane adapter, fetch transport, runtime)를 그대로 조립했다. 실제 네트워크와 실제 서버는 쓰지 않았다. 짝 백엔드는 실행하지 않고 문서·코드만 읽었다 |
| 확인하지 못한 범위·이유 | 짝 백엔드 Fileserver의 실제 응답(실행 안 함), 실제 브라우저 메모리 최고점(측정 환경 없음), 두 탭 같은 uploadKey 실제 경쟁(spec이 없음), 실제 브라우저에서의 실패 뒤 재개·결과 불명 complete·`Retry-After`(브라우저 spec은 정상 경로뿐), 모바일 CPU 해시 시간(장비 없음), 다운스트림 제품의 업로드 사용 여부(제품 repo 안 봄) |
| 이전 리뷰와 비교 가능한 범위 | 지난 발견은 지금 코드 위치와 이번 실행으로 다시 판정했다. 지난 라운드의 실험 결과(X1~X6, 변이 M9~M35, 번들 55,623바이트)는 증거로 쓰지 않았다. 이번 X3은 지난 X3과 같은 절차다 |
## 2. 지난 발견 재판정
| 지난 ID | 지난 심각도 | 판정 | 근거 |
| --- | --- | --- | --- |
| 1101/01-01 part 단계(발급·PUT)가 `Retry-After`를 읽지 않는다 | Medium · P2 | **고쳐짐**(상한 밖 구간은 새 01-02) | `statusFailure`가 `Response`를 받아 429·503의 `Retry-After`를 `retryAfterMs`로 싣는다(`presigned/http-common.ts:168-212`). HTTP control plane adapter가 그 값을 runtime에 넘긴다(`http-control-plane-adapter.ts:202-215`). 테스트가 실제 provider·vault·실행기로 두 단계를 본다(`tests/unit/resumable-upload-runtime-recovery.test.ts:330-376`). 변이 N1(헤더 무시)·N3(adapter 전달 제거)·N12·N13이 모두 잡혔다 |
| 1101/01-02 `FILE_BYTE_SOURCE` 재개가 수락된 part까지 다시 해시한다 | Low · P3 | **남음** | 검증(`resumable-upload-runtime.ts:882-888`)이 수락 확인(`:889`)보다 앞이다. **X3**(8 part 중 6개 수락 뒤 재개, part 크기 SHA-256만 셈): FILE 16회, RANGE 10회. 변이 N11(순서 바꿈)은 265건 통과 — 고쳐도 깨지는 테스트가 없다 |
| 1101/01-03 메모리 상한 식의 copyFactor가 설정값이다 | Low · P3 | **남음**(정적 확인) | `partBufferCopyFactor`는 여전히 정책 필드이고 1~8을 받는다(`runtime-policy.ts:12`, `:101-107`). 하한 상수는 없다 |
| 1101/01-04 같은 이미지 동시 resolve에서 probe가 호출 수만큼 돈다 | Low · P3 | **고쳐짐** | asset·preset별 "probe 단계" promise를 두고, 뒤에 온 호출은 그 단계를 자기 signal로 기다린 뒤 통과 기록을 재사용한다(`image-cdn-runtime.ts:239-257`, `:625-638`, `:720-726`). 실패한 probe는 공유하지 않는다. 변이 N15(대기 제거)·N16(대기 뒤 재확인 제거)이 잡혔다. 남은 한계는 커밋 `6b7b53f` 본문에 적혀 있다: 앞선 probe가 실패하면 대기자가 각자 probe한다(slot 수로 묶임) |
| 0929/01-01 `upload()` 실패 recovery가 6경로에서 포트 표와 다르다 | Medium · P2 | **고쳐짐**(`upload()`). `abort()`는 0929/01-05로 남음 | `uploadActionFor`가 code도 본다(`resumable-upload-runtime.ts:1745-1764`). `NONE`·`RESELECT`는 `retryable:false`로 강제한다(`:1731-1732`). 발급 401/403은 runtime 발급 분기가 `NONE`으로 만든다(`:988-995`). 6경로 모두 테스트가 있고 변이가 잡혔다: ① N7·N8, ② X4 둘째 호출이 `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, RESUME}`, ③ N5, ④ N4, ⑤ N9, ⑥ N6. 포트 표와 문서 표도 같이 고쳤다(`resumable-upload.ts:103-124`, `presigned-transfer-and-image-cdn.md:729-746`) |
| 0929/01-02 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | Low · P3 | **남음**(영향 줄어듦) | `QUARANTINED` 분기는 여전히 삭제 실패를 그대로 돌려준다(`resumable-upload-runtime.ts:584-590`). **X4**: 첫 호출 `{UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME}` → 둘째 호출(삭제 1회 실패) `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, RESUME}`, resourceId 없음 → 셋째 호출 `{QUARANTINED, resource_01, replayed:true}`. 둘째 호출이 이제 `NONE`이 아니라 `RESUME`이라 앱이 다시 부르게 된다. 변이 N18(삭제 실패 무시)은 265건 통과 — 고쳐도 깨지는 테스트가 없다 |
| 0929/01-03 느린 업링크 설정이 runtime 정책과 실행기에 따로 있다 | Low · P3 | **남음**(정적 확인) | runtime `resumable-upload-runtime.ts:1043-1047`, 실행기 `presigned-transfer-executor.ts`의 자기 `timeoutMs`·`minTransferBytesPerSecond`. 문서는 "정책의 `minTransferBytesPerSecond`를 낮춘다"만 적는다(`presigned-transfer-and-image-cdn.md:292-298`. 지난 리뷰 뒤 이 줄은 바뀌지 않았다). 같은 모양이 `maxRetryAfterMs`에도 생겼다(01-02, X1f) |
| 0929/01-04 file-transfer 어댑터만 지우면 게이트 3개가 실패한다 | Low · P3 | **남음**(정적 확인) | `scripts/check-adapter-inventory.ts:139-144`가 이 영역 4파일을 이름으로 고정한다. `scripts/contracts/release-artifacts.ts:1147`의 메시지도 그대로다. 제거 실험은 다시 하지 않았다 |
| 0929/01-05 `abort()` 실패 recovery에는 행동 표가 없다 | Low · P3 | **남음** | 포트 표는 `upload()`에만 있다(`resumable-upload.ts:103-124`). **X5**: 닫힌 runtime에서 `upload()`는 `{UNAVAILABLE, UPLOAD_SESSION, retryable:false, NONE}`, `abort()`는 `{UNAVAILABLE, UPLOAD_ABORT, retryable:false, RESUME}`(`resumable-upload-runtime.ts:241-245`). 0929/01-01을 `upload()`에만 고쳐서 같은 상황의 두 메서드 답이 갈라졌다 |
지난 라운드 FOLLOW-UP 성격 항목:
| 항목 | 판정 | 근거 |
| --- | --- | --- |
| ABORT 멱등 키 재사용을 고정하는 테스트 없음 | 남음 → 01-03 | 변이 N10(시도마다 키 변경) 265건 통과. 세 라운드째 같다 |
| `maxPartCount` 바이트 검사가 transport에 넘길 때만 동작 | 남음 | `fetch-json-transport.ts:157-167`. 유일한 조립 예도 transport에 넘기지 않는다(`tests/browser-capabilities/resumable-upload.spec.ts:329-342`) |
| 업로드 PUT에 idle 제한 없음 | 남음(문서화된 선택) | `presigned-transfer-and-image-cdn.md:295-297` |
| probe 재사용 테스트가 공개 이미지만 씀 | 남음 | 새 동시 resolve 테스트도 `publicAsset()`만 쓴다(`tests/unit/image-cdn-runtime.test.ts:1486, 1522, 1557, 1644`) |
| `resumable-upload.spec.ts` `PAGE_ORIGIN` 포트 4174 고정 | 남음 | `:7`과 `playwright.capabilities.config.ts`의 `baseURL`·`webServer`가 따로 적혀 있다 |
| 레시피 번들 예산 여유 77바이트 | 바뀜 | 예산 규칙이 "측정값 + 3%"로 바뀌었다(0929/05-04, `313f9ba`). 지금 예산은 57,800이다(`frontend-capability-recipes.json:198`). 이번 측정은 6.3절 |
## 3. 이번 발견 (36.3)
### 01-01 파일 업로드는 두 템플릿을 짝으로 쓰면 연결되지 않는다 — 프론트 레시피의 서버 프로토콜이 짝 백엔드에 없고, 짝 백엔드 Fileserver를 부를 프론트 client도 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(두 템플릿 사이 계약 불일치. 프론트 문서의 "서버 template 구현 대기" 주장이 짝 백엔드의 제거 결정과 반대다) |
| 관련 관점 | 17, 26, 20, 5, 23 (+30.2 옵션 조합의 검증 책임) |
| 근거 | **프론트.** 업로드 runtime은 `PRESIGNED_MULTIPART_V1` 하나만 안다(`src/application/ports/browser-transfer/resumable-upload.ts:9-12`). control plane은 create·status·complete·abort JSON 4개와 part capability 발급이다(`src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts:38-42`, `:162-248`). 바이트는 브라우저가 object store에 직접 PUT한다. 서버 handoff 문서는 "상태: 설계 완료, 서버 구현 대기", "대상: 이후 서버 template 또는 제품 backend에서 구현할"이라고 적는다(`docs/architecture/server-file-capability-infrastructure.md:3-5`). tus 같은 offset protocol은 "별도 protocol/version과 wire adapter"가 필요하다고 적는다(`docs/architecture/presigned-transfer-and-image-cdn.md:193-196`). 그런 adapter는 없다. `src/` 전체에 `FormData`가 0건이다. 그래서 레시피 fallback의 "same-origin authorized server upload"(`config/recipes/frontend-capability-recipes.json:199`)를 구현한 코드도 없다. `tus-js-client`는 선택 전 설치 금지 목록에 있다(`:22`, 검사 `scripts/lib/optional-recipes.ts:192-208`). `docs/manual/`에는 업로드·presigned·resumable 언급이 0건이다. **짝 백엔드**(`7ef8d0b4`, 읽기만). "Direct/presigned transfer and multipart upload are not implemented: their unassembled code was removed"(`docs/storage-capability-boundary.md:21-23`, 표 `:8` "no direct/presigned transfer exists"). 지운 목록은 `docs/capability-status.md:265-275`(`6d27356e`, 2026-09-25)다. 파일은 Fileserver가 직접 받는다: `POST /v1/files` multipart 한 번 요청, `POST /v1/files:raw`, tus `/v1/uploads`(`docs/fileserver/http-contract.md:8-24`). 실패 본문은 Envelope다(`:72-80`). 멱등 키는 `Idempotency-Key` 헤더이고, 처리 중이면 409 `IDEMPOTENT_IN_FLIGHT` + `Retry-After: 2`다(`docs/web/http-contract.md:76-82`). **오늘 바뀐 것과의 관계.** 오늘 V3 실행기는 짝 백엔드 Envelope와 멱등 code를 `src/adapters/http/backend-envelope.ts` 한 곳에서 읽게 됐다(1101 README 14.6·14.7). 업로드 control plane은 그와 별개인 두 번째 JSON HTTP 경로다. 성공 본문은 DTO 그대로 읽고(`fetch-json-transport.ts:291-299`, `http-control-plane-adapter.ts:116`), 실패는 status만 본다(`fetch-json-transport.ts:551-593`). 멱등 키는 JSON 본문에 싣는다(`http-control-plane-adapter.ts:110`). **X2**(출하 fetch transport·HTTP control plane·runtime, 가짜 BFF): ① createSession 성공을 짝 백엔드 Envelope로 감싸면 `{CORRUPT_DATA, UPLOAD_SESSION, retryable:false, RECONCILE}` ② 같은 본문을 감싸지 않으면 status 단계까지 간다(대조군) ③ status가 409 `IDEMPOTENT_IN_FLIGHT` + `Retry-After: 2`이면 기다리지 않고 `{CONFLICT, UPLOAD_RECONCILE, retryable:false, RECONCILE}` |
| 발생 조건 | 두 템플릿으로 파일 업로드가 있는 서비스를 만든다. 같은 원인으로 presigned 다운로드와 private Image CDN descriptor도 짝 서버가 없다(정적 확인. 짝 백엔드 문서에 image CDN 언급 0건) |
| 영향 | 프론트 업로드 레시피도, 백엔드 Fileserver도 그대로는 짝이 되지 않는다. 팀은 둘 중 하나를 새로 만들어야 한다. (가) 백엔드에 `PRESIGNED_MULTIPART_V1` BFF: session·part 발급·receipt·complete·abort·멱등·quarantine. 짝 백엔드가 지운 코드 범위다. (나) 프론트에 Fileserver client: multipart 한 번 요청 또는 tus. 어느 문서도 이 사실을 알리지 않아 조립 단계에서야 드러난다. 레시피를 짝 백엔드 방식의 BFF에 그대로 붙이면 첫 응답부터 `CORRUPT_DATA`이고, 서버에는 클라이언트가 기록하지 못한 session이 남는다(X2 ①). 데이터 손상은 없다 |
| 심각도·우선순위 | High · P1 — 파일 업로드가 있는 제품 기준이다. "두 템플릿을 짝으로 써서 빨리 출시한다"는 목표에 직접 걸린다. 지난 라운드의 같은 성격 결함("생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다", 1101 README 14.3, High · P1)과 같은 급으로 맞췄다. 파일 기능이 없는 제품에는 해당이 없다 |
| 통제·증거 | 짝 백엔드와의 파일 전송 계약: M0(두 repo의 해당 경로를 확인했고 대응 서술·코드가 없다) · E1(두 repo 코드·문서) + E2(X2) |
| 확실성과 남은 가정 | 프로토콜 불일치, 프론트 문서 주장, 백엔드 제거 결정은 코드·문서로 확정했다. 다운스트림 제품(tech-log, memento)이 업로드를 쓰는지는 미확인이다. 백엔드 Fileserver가 프론트가 요구하는 성질(파일 fingerprint, part checksum, quarantine 결과)을 모두 주는지는 대조하지 않았다 |
| 결정의 근거 | [기록된 의도] 프론트는 "BFF가 control plane을 소유하고 브라우저가 data plane을 맡는다"를 골랐다(`presigned-transfer-and-image-cdn.md:44-60`, 레시피 `boundary` `frontend-capability-recipes.json:191`). 백엔드는 "Fileserver가 바이트를 직접 받는다"를 골랐고, 조립 경로 없는 presigned 코드를 지웠다(소유자 결정 D1·D-7a). [확인한 사실] 두 결정은 서로를 가리키지 않는다. [리뷰어 추론] 각자 타당한 선택이 짝 조합에서 비었다. 어느 쪽이 움직일지는 두 repo 소유자의 결정이다(5절 D1) |
| 이해 비용 | 제품 팀은 프론트 레시피, 서버 handoff 문서, 백엔드 storage-boundary, Fileserver 계약 네 곳을 읽어야 업로드가 짝이 아님을 안다 |
| 최소 개선 방향 | 1단계(문서, 바로): 두 템플릿 매뉴얼에 "파일 업로드는 짝이 아니다"와 선택지를 적는다. 프론트 handoff 문서의 상태 줄을 "짝 백엔드는 구현하지 않음(2026-09-25 제거)"으로 고친다. 2단계: 5절 D1에서 고른 안을 구현한다 |
| 대안 비교 | 5절 D1. (가) 백엔드 BFF, (나-1) 프론트 multipart 한 번 업로드 adapter, (나-2) 프론트 tus wire adapter, (다) 문서만 |
| 단순화의 보존 조건 | 어느 안이든 지금 레시피의 보안 성질(credentials omit, redirect error, no-referrer, capability 1회 사용, checkpoint allowlist)을 유지한다. adapter 사이 import 예외를 새로 만들지 않는다. 업로드 경로가 Envelope 해석을 재사용하려면 `backend-envelope.ts`를 kernel 폴더(`src/adapters/platform/`)로 옮기거나, 업로드 operation을 http adapter에 둔다 |
| 비용·부작용 | 1단계: 문서 몇 줄씩. (나-1): 수백 줄 추정, 재개 없음. (나-2): 상위 session 계약을 재사용하는 새 wire adapter, 규모 미측정. (가): 백엔드에 지운 범위의 코드를 다시 들인다 |
| 재검토 조건 | 짝 백엔드가 presigned/direct 전송을 다시 들이기로 할 때. 제품이 수 GiB 업로드와 서버 대역폭 절약을 요구할 때 (가)가 유리해진다 |
| 완료 기준 | 두 템플릿을 그대로 써서 파일 하나를 올리는 경로가 있고, 두 매뉴얼이 그 경로를 가리킨다. 1단계만 했다면 "짝 아님"이 두 매뉴얼과 프론트 handoff 문서에 있다 |
| 검증 방법 | 1단계: 매뉴얼·handoff 문서 grep. 2단계: 짝 백엔드 Fileserver를 띄우고 프론트 adapter로 업로드, 중단 뒤 재개, 결과 불명을 재현하는 통합 테스트. 짝 백엔드 실패 Envelope를 쓰는 contract fixture |
| 담당·기한·상태 | 미정(두 repo 소유자 결정) · 미정 · 신규 |
### 01-02 `Retry-After`가 상한을 넘으면 part 단계는 앱에 `retryable:true`를 준다 — 같은 429에 control plane은 `false`를 준다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(포트 표가 허락하는 자동 재시도가 서버의 대기 요청을 어긴다. 단계 사이 불일치) |
| 관련 관점 | 6, 17, 23, 19, 14 |
| 근거 | part 단계 상태표는 429를 `retryable:true`로 두고 `retryAfterMs`를 상한 없이 싣는다(`src/adapters/browser-transfer/presigned/http-common.ts:173-179`). runtime은 상한을 넘으면 재시도를 멈춘다(`canRetry`, `resumable-upload-runtime.ts:1499-1512`). 그다음 `stripProviderFailure`가 `retryAfterMs`를 지우고 `retryable:true`는 그대로 둔다(`:1676-1684`, 호출 `:997-999`, `:1071-1079`). `toUploadAction`도 그대로 둔다(`:1726-1743`). 포트 표는 "`retryable: true`면 자동 재시도해도 된다"고 적는다(`resumable-upload.ts:109-110`). control plane transport는 같은 429를 상한을 넘거나 헤더가 없으면 `retryable:false`로 만든다(`fetch-json-transport.ts:575-589`). 문서도 "없거나 상한을 넘으면 재시도하지 않는다"고 적는다(`presigned-transfer-and-image-cdn.md:392-393`). **X1**(출하 provider·vault·실행기·HTTP control plane adapter, 정책 상한 30초, 지터 최대): a) 발급 429 `Retry-After: 45` → 발급 1회, sleep 없음, `{UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME}` b) PUT 429 `Retry-After: 45` → 발급 1회·PUT 1회, 같은 결과 c) 발급 429 헤더 없음 → sleep `[250, 500, 1000]` 뒤 같은 결과 d) createSession 429 `Retry-After: 45`(transport 상한 기본 30초) → 1회, `{UNAVAILABLE, UPLOAD_SESSION, retryable:false, RESUME}` e) createSession 429 헤더 없음 → 1회, `retryable:false` f) d와 같되 transport 상한 60초 → `retryable:true`. 기존 테스트 `does not retry a $stage 429 whose Retry-After exceeds maxRetryAfterMs`(`tests/unit/resumable-upload-runtime-recovery.test.ts:355-376`)는 code·operation만 보고 `retryable`은 보지 않는다 |
| 발생 조건 | BFF 발급이나 object store가 기본 `maxRetryAfterMs`(30초)보다 긴 `Retry-After`로 429를 준다. 분 단위 rate limit 창이면 60초까지 나온다. control plane도 transport 상한이 정책 상한보다 크면 같다(X1f) |
| 영향 | 포트 표를 따르는 다운스트림은 곧바로 `upload()`를 다시 부른다. 서버가 45초 기다리라고 했는데 바로 다시 온다. 호출마다 파일 전체 해시, status, 발급 요청이 다시 돈다. 1101/01-01이 막으려던 재시도 증폭이 상한 밖 구간에 남았다. 데이터 피해와 중복 부작용은 없다 |
| 심각도·우선순위 | Medium · P2 — 1101/01-01(Medium)과 피해 형태가 같다. 고치는 비용은 몇 줄이다 |
| 통제·증거 | 상한 안 대기 M3(N1·N12·N13 검출) · 상한 밖에서 앱에 주는 신호 M0(이 경로를 확인했고 막는 장치가 없다) · E2(X1) |
| 확실성과 남은 가정 | 코드와 실험으로 확정했다. 실제 서버가 주는 `Retry-After` 분포는 미확인이다 |
| 결정의 근거 | 5절 D2. [확인한 사실] control plane은 이미 "상한 밖이면 재시도 불가"를 골랐다. [리뷰어 추론] part 단계만 다른 이유는 기록에 없다. 1101/01-01 수정이 상한 안 경로만 맞췄다 |
| 이해 비용 | 같은 429를 두 단계가 다르게 끝낸다는 사실을 알려면 상태표 두 개와 runtime 함수 세 개를 읽어야 한다. 상한 값도 두 factory(transport `maxRetryAfterMs`, 정책 `maxRetryAfterMs`)에 있다 |
| 최소 개선 방향 | 지운 `retryAfterMs`가 정책 상한을 넘었으면 앱에 줄 실패를 `retryable:false`로 만든다. control plane과 같은 규칙이다. runtime이 provider 실패를 앱 실패로 바꾸는 한 지점에서 하면 두 단계와 두 상한 조합이 모두 같아진다 |
| 대안 비교 | 5절 D2. (가) 위 최소 개선. (나) 현상 유지 + 포트 표에 주의 한 줄 — 앱은 기다릴 값을 모른다. (다) 앱 실패에 `retryAfterMs`를 싣는다 — 공유 타입 `BrowserDataFailure` 변경 |
| 단순화의 보존 조건 | 상한 안 `Retry-After` 대기(N1·N12·N13), PUT 403 재발급(N14), 발급 401/403 `NONE`(N4)을 바꾸지 않는다 |
| 비용·부작용 | 몇 줄. `upload()` 결과 값이 바뀌므로 CHANGELOG [계약] 한 줄 |
| 재검토 조건 | 포트가 앱에 대기 시간을 넘기기로 할 때 (다)를 다시 본다 |
| 완료 기준 | X1a·X1b가 `retryable:false`다. X1d·X1f는 두 상한을 어떻게 두어도 같은 답이다 |
| 검증 방법 | 기존 테스트(`:355-376`)에 `retryable:false` 단언을 더한다. transport 상한 > 정책 상한 조합 테스트를 하나 더한다 |
| 함께 볼 것 | ① cross-origin object store에서 `Retry-After`는 CORS 안전 헤더가 아니라 `Access-Control-Expose-Headers`가 필요하다. 이 사실은 코드 주석에만 있다(`http-common.ts:163-165`). 서버 handoff 문서는 receipt 헤더만 적는다(`server-file-capability-infrastructure.md:1656-1661`). 없으면 runtime이 자기 backoff로 돌아가므로 피해는 작다. 짝 백엔드는 자기 응답에 이미 expose한다(`CorsExposedHeaders.java:27-30`). ② 포트 주석은 `retryAfterMs`를 "runtime만 쓰고 앱 실패에서는 지운다"고 적는다(`resumable-upload.ts:134-137`). 하지만 앱 포트 `PresignedUploadPartPort.put`도 이 타입을 상한 없이 돌려준다(`presigned-transfer.ts:163-178`) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 01-03 `Retry-After`·멱등 키 규칙 세 개를 테스트가 고정하지 않는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(테스트 빈틈. 문서·주석의 규칙을 바꿔도 영역 265건이 통과한다) |
| 관련 관점 | 10, 6, 21 |
| 근거 | 변이 세 건이 영역 테스트 265건을 모두 통과했다. **N10**: abort 재시도마다 ABORT 멱등 키를 바꿈(`resumable-upload-runtime.ts:1210-1230`). 같은 키 재사용은 결과 불명 abort를 서버가 같은 작업으로 알아보는 근거다. 0929·1101 라운드에도 같은 변이가 살았다. **N17**: control plane의 헤더 없는 429를 `retryable:true`로 바꿈(`fetch-json-transport.ts:588`). 문서는 "없거나 상한을 넘으면 재시도하지 않는다"고 적는다(`presigned-transfer-and-image-cdn.md:392`). **N2**: part 단계가 503의 `Retry-After`를 읽지 않게 바꿈(`http-common.ts:174`). 주석은 "A 429 or 503 also carries the server's `Retry-After`"라고 적는다(`:160`) |
| 발생 조건 | 이 규칙 근처를 바꾸는 리팩토링. 01-02를 고칠 때도 이 근처를 바꾼다 |
| 영향 | 규칙이 조용히 깨질 수 있다. N10이 깨지면 서버가 ABORT 재시도를 새 작업으로 볼 수 있다. N17·N2가 깨지면 과부하 서버에 대한 대기 동작이 바뀐다 |
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 막는 장치만 없다 |
| 통제·증거 | 세 규칙 M2(구현만, 검출 없음) · E2(변이 N2·N10·N17) |
| 확실성과 남은 가정 | 변이 실행으로 확정했다 |
| 결정의 근거 | 적용 제외 — 이미 정한 규칙을 테스트로 고정하는 문제다 |
| 이해 비용 | 적용 제외 — 지역 빈틈이다 |
| 최소 개선 방향 | ① abort가 재시도할 때 두 요청의 `idempotencyKey`가 같은지 보는 테스트(같은 파일의 `resumable upload idempotency keys (01-04)` 묶음과 같은 방식, `tests/unit/resumable-upload-runtime-recovery.test.ts:378-534`) ② transport 테스트에 헤더 없는 429 → `retryable:false` ③ part 단계 503 `Retry-After` → 대기 |
| 대안 비교 | 적용 제외 — 기대 계약이 이미 정해져 있다 |
| 단순화의 보존 조건 | 적용 제외 — 테스트 추가뿐이다 |
| 비용·부작용 | 테스트 세 건 |
| 재검토 조건 | 적용 제외 — 선택 판단이 없다 |
| 완료 기준 | N2·N10·N17이 각각 한 건 이상 실패를 만든다 |
| 검증 방법 | `node scratchpad/a01-1103/mutate.mjs <worktree> <log> N2,N10,N17`을 다시 돌린다 |
| 담당·기한·상태 | 미정 · 미정 · 신규(N10은 0929 FOLLOW-UP부터 이어짐) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| **1** | 코드 성숙도 | O | M3 / M3 | E2 | checkpoint는 `ACTIVE → ABORT_PENDING → 삭제`로만, revision CAS로만 바뀐다. `upload()` 실패 번역이 `NONE`·`RESELECT`의 `retryable:false`를 한 곳에서 강제한다. N4~N9 검출 |
| 2 | 구조적 성숙도 | O | M4 | E1, 게이트 | 다른 adapter import는 kernel(`browser-file-storage/result.ts`, `platform/*`)뿐이다. 오늘 V2 삭제와 무관하다. `check:architecture` exit 0(오케스트레이터) |
| 3 | 변경 용이성 | O | M3 | E2 | 1101/01-01 수정은 포트 타입을 추가형으로만 바꿨다(`UploadProviderResult`). 정책을 낮춘 빌드의 재개 테스트가 그대로 통과한다 |
| 4 | 인지 부하 | P | M1~M2 | E1, E2 | 조립에 factory 6개가 든다. 같은 이름 `maxRetryAfterMs`가 두 factory에 있고 어느 쪽이 큰지로 결과가 바뀐다(X1f). resumable 조립 예는 Playwright spec뿐이다 |
| **5** | 위험 가시성 | P | M2 / M1~M2 | E1, E2 | 포트 표가 이제 구현과 맞다(0929/01-01). 남은 것: 서버 handoff 문서가 짝 백엔드와 반대로 주장(01-01), 상한 밖 429의 `retryable:true`(01-02), "hard ceiling"이 설정 하나로 풀림(1101/01-03) |
| **6** | 실패 성숙도 | P | M3 / M3(주 경로) | E2 | 재시도는 한 계층, 상한·지터, 두 단계 모두 상한 안 `Retry-After` 대기, PUT 403 재발급, 결과 불명 complete 재조정(N1·N12~N14 검출). 남은 것: 상한 밖 429 재시도 증폭(01-02), 0929/01-02 |
| 7 | 운영 성숙도 | O | M2 | E1 | part마다 `UPLOAD_PART` 관측 1건과 시도 수 bucket(`resumable-upload-runtime.ts:834-840`). 이번에 바뀌지 않았다. 수집·알림은 다운스트림 몫이다 |
| 8 | 디버깅 가능성 | P | M2 | E2 | `upload()`의 `NONE`+`retryable:true` 조합이 없어졌다. 남은 것: `abort()` recovery에 뜻이 없다(X5, 0929/01-05). 앱 실패에서 서버의 대기 값이 사라진다(01-02) |
| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본 `isAbortSignal` 두 벌(`checkpoint-schema.ts:195`, `http-common.ts:231`), `MEDIA_TYPE` 두 벌(`checkpoint-schema.ts:26`, `presigned-capability-http-provider.ts:50`), 손으로 적은 `RECOVERIES`(`resumable-upload-runtime.ts:119-133`). 지난 라운드와 같다 |
| 10 | 테스트 성숙도 | P | M3 / M3(대부분) | E2(265건, 변이 13/18 검출) | 새 테스트가 출하 provider·adapter로 `Retry-After`를 본다. 남은 것: N2·N10·N17 생존(01-03), 상한 밖 테스트가 `retryable`을 안 봄(01-02). 브라우저 spec은 3엔진 9/9 통과지만 spec마다 정상 경로 1건이다 |
| 11 | 데이터 성숙도 | P | M2~M4 | E2 | 계정 partition과 checkpoint key allowlist는 그대로다. 재조정 경로 삭제 실패 때 그 호출에서 resourceId를 잃는다(0929/01-02, X4) |
| **12** | 동시성 성숙도 | P | M3 / M3(탭 하나) | E2, E3(브라우저 정상 경로) | 업로드: Web Lock 직렬화, CAS, receipt 저장 직렬화, 첫 실패 때 형제 worker 중단. image probe: 같은 asset·preset 동시 resolve가 진행 중 단계를 기다린다(N15·N16 검출). 두 탭이 같은 uploadKey로 겨루는 실제 경쟁은 단위 테스트(메모리 lock)뿐이다 |
| 13 | 확장성 | P | M2 | E1 | 발급 요청이 part 수에 비례한다(`2N+4`, 바뀌지 않음). `maxPartCount` 바이트 검사는 transport에 넘길 때만 한다 |
| **14** | 성능 성숙도 | P | M3 / M2 | E2(X3), 번들 56,053/57,800 | 같은 이미지 중복 probe는 없어졌다. 남은 것: FILE 재개 재해시(1101/01-02, X3 FILE 16 vs RANGE 10), copyFactor 설정값(1101/01-03), 상한 밖 429 뒤 재해시 반복(01-02) |
| 15 | 보안 성숙도 | O | M4 | E2, E3(브라우저 정상 경로) | vault identity, `singleUse`, `credentials:"omit"`, `redirect:"error"`, `no-referrer`. 이번 변경은 이 경로를 건드리지 않았다. 브라우저 spec이 control 요청에 서명 query와 object origin이 없음을 본다 |
| 16 | 의존성 성숙도 | O | M2 | E1 | 외부 패키지가 없다. 선택 전 vendor 설치는 `check:optional-recipes`가 막는다 |
| **17** | API / Contract 성숙도 | P | M3 / M1~M3 | E1, E2 | `upload()` 행동 표가 구현과 맞다(0929/01-01). 남은 것: 짝 백엔드와의 파일 전송 계약 없음(01-01), 상한 밖 429가 표의 자동 재시도 허락과 충돌(01-02), `abort()` 표 없음(0929/01-05) |
| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 바꾼 새 빌드가 이전 checkpoint를 이어 간다. 이번에 바뀌지 않았다 |
| 19 | 설정 성숙도 | P | M2 | E1, E2 | factory 사이 값을 서로 검사하지 않는다: 업링크 속도 두 곳(0929/01-03), `maxRetryAfterMs` 두 곳(X1f), copyFactor 설정값(1101/01-03) |
| 20 | 개발자 경험 | X | M1 / M0 | E1 | 짝 백엔드로 파일 업로드를 붙이는 경로가 어느 문서에도 없다(01-01). resumable 조립 문서도 없다. image-cdn은 README가 있다 |
| 21 | Guardrail 성숙도 | P | M3 | E2 | 영역 규칙 대부분이 변이로 검출된다. 남은 것: N2·N10·N17(01-03), 게이트가 이 영역 파일 이름을 고정한다(0929/01-04) |
| 22 | 추상화 성숙도 | O | M3 | E1 | 앱 포트는 `upload()`·`abort()` 둘이다. 응답 해석은 `ResumableUploadJsonTransport` seam 뒤에 있어 제품 transport로 바꿀 수 있다(`http-control-plane-adapter.ts:44-55`) |
| 23 | 일관성 | P | M2 | E2 | 같은 429를 part 단계는 `retryable:true`, control plane은 `false`로 끝낸다(01-02). 503 `Retry-After`는 part 단계만 읽는다. 닫힌 runtime에서 `upload()`는 `NONE`, `abort()`는 `RESUME`(X5). 짝 백엔드 응답 해석이 V3 실행기에만 있다(01-01) |
| 24 | 네이밍 / 의미 성숙도 | P | M2 | E1 | 같은 이름 `maxRetryAfterMs`가 두 곳에서 다른 효과를 낸다. `abort()`가 `upload()` 표의 어휘 `RESUME`을 정해진 뜻 없이 돌려준다 |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 |
| 26 | Ownership 성숙도 | X | M1 / M0 | E1 | `PRESIGNED_MULTIPART_V1` 서버 쪽 주인이 비었다. 프론트 문서는 "이후 서버 template"이라 적고 짝 백엔드는 지웠다(01-01). object store CORS expose 책임도 handoff 문서에 없다(01-02 함께 볼 것) |
| 27 | 삭제 가능성 | P | M3 주장 / 레시피 단위 M0 | E1 | 레시피는 production 번들에 조립돼 있지 않다. 어댑터만 지우면 게이트가 실패한다(0929/01-04, 정적 확인) |
| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | 중단 뒤 재개, 결과 불명 complete 재조정, `ABORT_PENDING`, teardown 미완료 보고가 테스트된다. 남은 것: 0929/01-02(이제 `RESUME`이라 다음 호출로 회복), 상한 밖 429 뒤 즉시 재호출(01-02), ABORT 키 재사용 미고정(01-03) |
충족 O 8 · 부분 충족 P 17 · 미충족 X 2 · 미검증 ? 0 · 적용 제외 1.
## 5. 설계 선택 검토 (41절)
### D1. 파일 업로드를 짝 백엔드와 어떻게 맞출까 — 결정 필요, 1단계(문서)는 바로
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 두 템플릿으로 파일 업로드가 있는 서비스를 빨리 출시한다. 업로드는 중단 뒤 이어지고, 결과 불명 complete가 중복 자원을 만들지 않아야 한다 |
| 2. 지킬 성질 | 서버가 업로드 상태의 주인이다. 클라이언트는 같은 작업을 같은 키로 다시 보낸다. 서명 URL·토큰은 저장소와 관측에 남지 않는다 |
| 3. 현재 보장 | [확인한 사실] 프론트는 presigned multipart 쪽에서 위 성질을 구현했고 테스트한다(2절). 백엔드는 Fileserver 쪽에서 tus·multipart를 구현했다. [보장하지 않음] 두 구현은 서로 말하지 않는다(01-01) |
| 4. 대안 | (가) 백엔드에 `PRESIGNED_MULTIPART_V1` BFF를 만든다. (나-1) 프론트에 multipart 한 번 업로드 adapter(`POST /v1/files`)를 만든다. (나-2) 프론트에 tus wire adapter를 만들고 지금 상위 계약(`ResumableUploadPort`)을 그대로 쓴다. (다) 두 매뉴얼에 "짝 아님"만 적는다 |
| 5. 비교 | (가) 서버 대역폭을 쓰지 않고 프론트 코드를 그대로 쓴다. 대신 백엔드가 지운 범위(session·발급·receipt·quarantine)를 다시 들이고, object store CORS와 서명 운영이 생긴다. (나-1) 가장 작고 빠르다. 재개가 없어 큰 파일과 불안정한 망에 약하다. 바이트가 앱 서버를 지난다. (나-2) 재개를 지키고 짝 백엔드를 그대로 쓴다. tus offset 모델과 지금 part manifest 모델을 맞추는 설계가 필요하다(규모 미측정). (다) 비용이 거의 없고 함정은 없앤다. 짝으로 출시하는 경로는 여전히 없다 |
| 6. 판단 | 지금 바로 (다)를 한다. 그다음 기본 경로로는 (나-1)이 출시 속도 목표에 가장 맞다. 짝 백엔드 Fileserver가 이미 multipart 한 번 요청과 quarantine 상태를 준다. 큰 파일 재개가 제품 요구가 되면 (나-2)를 본다. (가)는 백엔드 소유자의 제거 결정(D1·D-7a)을 뒤집는 일이라 이 영역에서 권하지 않는다. 최종 선택은 두 repo 소유자 몫이다 |
| 7. 재검토 조건 | 제품이 수 GiB 업로드나 서버 대역폭 절약을 요구할 때 (가)를 다시 본다. 짝 백엔드가 tus를 기본 업로드로 정할 때 (나-2)의 우선순위를 올린다 |
### D2. `Retry-After`가 상한을 넘을 때 앱에 무엇을 알릴까 — `retryable:false`로 맞춘다
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 과부하 서버가 기다리라고 할 때, 클라이언트 전체(runtime과 다운스트림)가 그보다 일찍 다시 오지 않는다 |
| 2. 지킬 성질 | 포트 표의 "`retryable:true`면 자동 재시도해도 된다"가 서버의 대기 요청과 충돌하지 않는다. 같은 응답은 단계와 설정에 관계없이 같은 신호가 된다 |
| 3. 현재 보장 | [확인한 사실] 상한 안이면 runtime이 기다린다(두 단계, N1·N13 검출). control plane은 상한 밖·헤더 없음을 `retryable:false`로 끝낸다(`fetch-json-transport.ts:575-589`). [보장하지 않음] part 단계와 X1f 조합은 `retryable:true`이고 대기 값이 지워진다(01-02) |
| 4. 대안 | (가) 상한 밖이면 `retryable:false`. (나) 현상 유지 + 포트 문서에 주의 한 줄. (다) 앱 실패에 `retryAfterMs`를 싣는다. (라) runtime이 상한 밖 값도 기다린다 |
| 5. 비교 | (가) 몇 줄이고 control plane과 같은 규칙이다. 앱은 사람이 누르는 재시도로 넘어간다. (나) 앱은 기다릴 값을 모르므로 주의를 지킬 수 없다. (다) 앱이 정확히 기다릴 수 있다. 대신 공유 타입 `BrowserDataFailure`가 바뀌어 다른 포트까지 퍼진다. (라) 상한을 둔 이유, 즉 한 호출이 끝없이 늘어지지 않는다는 성질을 깬다 |
| 6. 판단 | (가). control plane이 이미 고른 규칙이고, 포트 표의 뜻을 지키는 가장 작은 변경이다 |
| 7. 재검토 조건 | 다운스트림이 서버 대기 값을 화면에 보여 줘야 할 때(예: "45초 뒤 다시") (다)를 다시 본다 |
### D3. 발급 401/403을 runtime의 발급 분기에서 `NONE`으로 만든다 — 유지, 포트에 한 줄 보강
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | BFF 발급 거절(세션 만료·권한 회수)과 object store PUT 거절(서명 만료)을 앱이 다르게 처리한다. 앞의 것은 재인증 전에는 다시 불러도 같고, 뒤의 것은 새 capability로 풀린다 |
| 2. 지킬 성질 | 발급 401/403은 `NONE`·`retryable:false`다. PUT 403은 `maxRetries` 안에서 재발급하고, 다 쓰면 `RESUME`이다 |
| 3. 현재 보장 | [확인한 사실] 두 거절은 상태표에서 code·단계·recovery가 같다(`http-common.ts:180-182`). 출처를 아는 곳은 runtime의 발급 분기뿐이다(`resumable-upload-runtime.ts:988-995`). 테스트가 세 경우를 실제 provider로 본다(`resumable-upload-runtime-recovery.test.ts:302-327`, N4 검출). [기록된 의도] 1101 README 14.2가 "출처 필드는 공개 타입을 바꾸고, WeakSet 표시는 숨은 결합"이라며 이 방식을 골랐다. [보장하지 않음] 이 규칙은 runtime 주석과 설계 문서(`presigned-transfer-and-image-cdn.md:737-746`)에만 있다. control plane 포트 `issuePartCapability`(`resumable-upload.ts:212-222`)에는 없다 |
| 4. 대안 | (가) 현상 유지. (나) 실패 타입에 출처 필드. (다) 상태표가 단계별로 다른 code를 낸다 |
| 5. 비교 | (가) 코드가 가장 작다. 다만 제품이 자기 control plane을 만들면 포트만 보고는 "발급 단계 `PERMISSION_DENIED`는 끝"이라는 규칙을 모른다. (나) 공유 타입이 바뀐다. (다) `PERMISSION_DENIED`의 뜻이 단계마다 달라져 다른 포트의 해석이 흔들린다 |
| 6. 판단 | 유지한다. `issuePartCapability` 포트 주석에 "`PERMISSION_DENIED`는 재시도하지 않고 `NONE`이 된다" 한 줄을 더하면, 제품 구현자가 같은 근거를 가까이서 찾는다 |
| 7. 재검토 조건 | 발급 단계에 다른 출처의 `PERMISSION_DENIED`(예: 제품 BFF의 자체 정책 거절)가 생기고, 그중 일부가 재시도로 풀릴 때 (나)를 다시 본다 |
## 6. 실험·변이 기록
### 6.1 실험 (worktree `tests/unit/zz-area01-experiments.test.ts`, 끝난 뒤 지움)
| ID | 무엇을 바꿨나 | 결과 | 쓰인 곳 |
| --- | --- | --- | --- |
| X1a | 발급 429 `Retry-After: 45`, 정책 상한 30초 | 발급 1회, sleep 없음, `{UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME}` | 01-02 |
| X1b | PUT 429 `Retry-After: 45` | 발급 1·PUT 1, sleep 없음, 같은 결과 | 01-02 |
| X1c | 발급 429 헤더 없음 ×4 | 발급 4회, sleep `[250, 500, 1000]`, 같은 결과 | 01-02 |
| X1d | createSession 429 `Retry-After: 45`, transport 상한 기본 30초 | 1회, sleep 없음, `{UNAVAILABLE, UPLOAD_SESSION, retryable:false, RESUME}` | 01-02 |
| X1e | createSession 429 헤더 없음 | 1회, `retryable:false` | 01-02 |
| X1f | X1d와 같되 transport 상한 60초 | 1회, sleep 없음, `retryable:true` | 01-02, 관점 19 |
| X2a | createSession 성공을 짝 백엔드 Envelope(`{success, data, meta}`)로 감쌈 | createSession 1회 뒤 `{CORRUPT_DATA, UPLOAD_SESSION, retryable:false, RECONCILE}` | 01-01 |
| X2b | X2a 대조군(감싸지 않음, status는 503) | create 1회 + status 4회, `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, RESUME}` | 01-01 |
| X2c | status가 409 `IDEMPOTENT_IN_FLIGHT` Envelope + `Retry-After: 2` | sleep 없음, `{CONFLICT, UPLOAD_RECONCILE, retryable:false, RECONCILE}` | 01-01 |
| X3 | 8 part 중 6개 수락 뒤 재개, part 크기 SHA-256 호출 수 | 첫 호출 15회(두 경로 같음). 재개 FILE 16회, RANGE 10회 | 1101/01-02 |
| X4 | complete 응답 유실 → 재조정 중 checkpoint 삭제 1회 실패(IndexedDB `UnknownError` 매핑 `UNAVAILABLE/REOPEN`) | `RESUME`(complete) → `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, RESUME}` → `{QUARANTINED, resource_01, replayed:true}` | 0929/01-02, 0929/01-01 ② |
| X5 | `dispose()` 뒤 `upload()`와 `abort()` | `upload()` `NONE`, `abort()` `RESUME` | 0929/01-05 |
### 6.2 변이 (`scratchpad/a01-1103/mutate.mjs`, 코드 한 곳을 바꾸고 영역 265건을 돌린 뒤 원본으로 되돌림)
| ID | 바꾼 것 | 결과 |
| --- | --- | --- |
| N1 | part 단계가 `Retry-After`를 읽지 않음(1101/01-01 되돌림) | 4 실패 — 검출 |
| N2 | part 단계가 503의 `Retry-After`를 읽지 않음 | **265 통과 — 검출 못 함**(01-03) |
| N3 | HTTP control plane adapter가 발급 `retryAfterMs`를 버림 | 1 실패 — 검출 |
| N4 | 발급 401/403 분기 제거(0929/01-01 ④ 되돌림) | 2 실패 — 검출 |
| N5 | `UPLOAD_PART`의 `NOT_FOUND` → `RECONCILE` 제거 | 1 실패 — 검출 |
| N6 | `POLICY_REJECTED` → `NONE` 제거 | 2 실패 — 검출 |
| N7 | `NOT_READABLE`/`REOPEN` → `RESELECT` 제거 | 1 실패 — 검출 |
| N8 | `NONE`·`RESELECT`의 `retryable:false` 강제 제거 | 1 실패 — 검출 |
| N9 | 닫힌 runtime `upload()`를 다시 `RESUME`으로 | 1 실패 — 검출 |
| N10 | abort 재시도마다 ABORT 멱등 키를 바꿈 | **265 통과 — 검출 못 함**(01-03, 세 라운드째) |
| N11 | 스트림 경로에서 수락 확인을 검증 앞으로(1101/01-02의 고친 모양) | 265 통과 — 리팩토링 안전성 확인 |
| N12 | `canRetry`가 상한 밖 `Retry-After`도 재시도 | 2 실패 — 검출 |
| N13 | `waitForRetry`가 `Retry-After`를 무시 | 4 실패 — 검출 |
| N14 | PUT의 `REISSUE_CAPABILITY` 거절을 재발급하지 않음 | 4 실패 — 검출 |
| N15 | 동시 resolve가 진행 중 probe 단계를 기다리지 않음(1101/01-04 되돌림) | 1 실패 — 검출 |
| N16 | 대기 뒤 통과 기록을 다시 보지 않음 | 1 실패 — 검출 |
| N17 | control plane의 헤더 없는 429를 `retryable:true`로 | **265 통과 — 검출 못 함**(01-03) |
| N18 | 재조정 `QUARANTINED`에서 삭제 실패 무시(0929/01-02의 고친 모양) | 265 통과 — 고쳐도 깨지는 테스트가 없다 |
18건 중 13건 검출. 생존 5건 중 N2·N10·N17은 빈틈이다(01-03). N11·N18은 남은 결함을 고친 모양이라 생존이 맞다.
### 6.3 무거운 실행 (`flock /tmp/claude-1000/review-2026-11-03-heavy.lock`)
| 실행 | 조건 | 결과 |
| --- | --- | --- |
| `check:optional-recipes:source` | 23:08~23:16, 시작 부하 31.5, 끝 부하 70.7 | **PASS**. `file-transfer: 56,053 / 57,800 gzip bytes`(여유 1,747). 다른 레시피: offline-indexeddb 37,423/38,500, realtime 40,857/42,200, service-worker-pwa 9,716/10,100. 1101 라운드 측정(55,623/55,700)보다 430바이트 늘었다. 01-01·01-04·0929/01-01 수정분이다 |
| Playwright 영역 spec 3개 × chromium·firefox·webkit, 1차 | 23:08~23:12, 부하 33~37 | **실행 못 함**. dev server(vite)가 `ENOSPC: System limit for number of file watchers reached`로 떴다가 죽었다. 호스트 inotify 한도(`max_user_watches` 65,536)를 다른 리뷰어의 dev server와 나눠 쓴 탓이다. 코드 결함이 아니다 |
| 같은 spec, 2차(`CHOKIDAR_USEPOLLING=1`) | 23:16 대기 시작, 23:33 끝, 끝 부하 10.6 | **9/9 통과**, 9.1초. `resumable-upload`(실제 IndexedDB·Web Locks·BroadcastChannel·fetch로 3 part 업로드, 끝난 뒤 checkpoint 없음과 partition 삭제 확인), `presigned-streaming`(capability 발급과 검증된 스트리밍 저장), `image-cdn`(공개 immutable 이미지 fetch·decode)가 세 엔진 모두 통과했다 |
브라우저 spec은 spec마다 정상 경로 1건이다. 실패 뒤 재개, 결과 불명 complete, `Retry-After`, 두 탭 경쟁은 브라우저에서 확인하지 않았다. 이 경로의 증거는 단위 harness(E2)까지다.
### 6.4 끝난 뒤 정리
worktree에서 `git checkout -- . && git clean -fd`로 실험 파일을 지웠다. 변이는 스크립트가 원본을 메모리에서 되돌렸다. 변이 실행 뒤 `git status`에는 실험 파일 하나만 보였다. 커밋하지 않았다.
@@ -0,0 +1,385 @@
# 02 browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `src/adapters/browser-files/`, `src/adapters/cache-storage/`, `src/adapters/cross-context-invalidation/`
> 깊게 본 관점: 1, 5, 6, 11, 12, 15, 24
> 이번 라운드 렌즈: 다른 탭·세션 사이의 캐시 무효화와 파일 보관이 로그아웃·계정 전환·손상 데이터에서 안전한가
> 영역 판정(35.8): cross-context-invalidation **지정 범위에서 사용 가능** · cache-storage **조건부 사용 가능** · browser-files **조건부 사용 가능**(0절)
ID 표기: 이번 라운드의 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-11-01)의 발견은 `1101/02-01`, 그 전 라운드(2026-09-29)의 발견은 `0929/02-01`처럼 앞에 날짜를 붙인다.
## 0. 결론
**렌즈에 대한 답**
- **탭 간 캐시 무효화는 로그아웃·계정 전환에서 안전하다.** wire event에는 topic·순번·식별자만 있다. 데이터와 사용자 정보가 없다(E-6의 wire 키). 세션이 바뀌면 그 탭의 transport를 닫고 새 `sourceId`로 다시 연다. 닫힌 세대는 이벤트를 받지 않는다(E-6). 다른 계정 탭이 보낸 hint는 "다시 읽어라"일 뿐이라 데이터가 섞이지 않는다. 손상된 pulse는 버린다.
- **Cache Storage는 계정과 무관하게 설계돼 있어 로그아웃에서 지울 것이 없다.** stage 요청은 `credentials: "omit"`, `mode: "same-origin"`이고 인증 헤더를 금지한다(`src/adapters/cache-storage/public-cache-response-validation.ts:223-238`, `public-cache-codec.ts:250-279`). 그래서 익명 응답만 들어간다. 손상 pointer 문제(`0929/02-01`)는 고쳐졌다. 다음 활성화가 손상 pointer를 덮어쓰고, 일시 오류에서는 덮어쓰지 않는다(F5·F6·F7 검출).
- **파일 보관(browser-files)은 runtime을 닫으면 안전하다. 그런데 로그아웃·계정 전환에 runtime을 닫는 공식 연결점이 없다(02-01, Medium).** 설계 문서는 템플릿 소유 파일 `runtime-adapters.ts`에 participant를 등록하라고 한다. 매뉴얼은 제품이 그 파일을 고치지 않는다고 한다. 제품 확장 지점(`product-composition.ts`)에는 세션 수명 신호가 없다. 연결하지 않으면 이전 사용자가 고른 File 참조, preview blob URL, 진행 중 download가 다음 세션까지 남는다.
**지난 발견 재판정**: 11건(지난 라운드 5건 + 그 전 라운드에서 남은 6건)을 다시 봤다. 고쳐짐 4건(`1101/02-01`, `1101/02-03`, `1101/02-05`, `0929/02-01`), 남음 7건이다. 고친 4건은 되돌리는 변이를 새 테스트가 모두 잡는다(F1~F7).
**이번 발견**: High 1건, Medium 1건, Low 4건.
- **High(02-06)는 렌즈 밖에서 나왔다.** 이 영역의 제거 드릴 `test:browser-file-storage-removal`이 이 커밋에서 항상 실패한다. 이 드릴은 merge 단계 게이트 FE-GATE-020의 명령이고, release 단계도 이 게이트를 기다린다(`config/ci/gates.json:2107-2125`, `:2235-2249`, `:2310-2322`). 원인은 공유 fixture가 `README.md`·`CHANGELOG.md`를 복사하지 않는데, 11-01에 생긴 문서 테스트 2파일이 그 파일을 읽는 것이다. sample-removal 드릴만 이 두 테스트를 뺐다. 오케스트레이터 게이트 목록에 이 드릴이 없어 지금까지 드러나지 않았다.
| ID | 심각도 | 한 줄 |
| --- | --- | --- |
| 02-06 | High · P1 | 제거 드릴(FE-GATE-020)이 문서 테스트 2파일 때문에 항상 실패한다 |
| 02-01 | Medium · P2 | browser-files runtime을 로그아웃·계정 전환에 맞춰 닫는 공식 연결점이 없다 |
| 02-02 | Low · P3 | 활성화 재검증이 캐시 본문 읽기의 일시 오류를 무결성 실패로 보고한다 |
| 02-03 | Low · P3 | 손상 데이터·로그아웃 경로의 보호 규칙 5개를 테스트가 잡지 못한다 |
| 02-04 | Low · P3 | `inspect()`와 `release()`가 겹치면 놓은 ref에 receipt가 발급되고 File이 남는다 |
| 02-05 | Low · P3 | pointer가 손상되면 `inspect()`가 아무 상태도 보여 주지 않고 실패한다 |
**영역 판정 (35.8)**
- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** 범위는 "같은 release 탭끼리 등록 topic을 빨리 stale 처리하는 hint"다. 다른 release 탭과는 hint를 주고받지 않는다. 설계 문서 8.2·8.3절이 그렇게 정했다. host의 `storageArea` 비교만 여전히 테스트가 없다(`1101/02-04` ②).
- cache-storage(service-worker-pwa 레시피, 미조립): **조건부 사용 가능.** 조건은 정적 release 조합에만 쓰는 것이다. Service Worker drain 조합에서는 손상 pointer를 덮어쓴 뒤 직전 release가 다음 정리에서 지워진다는 점을 먼저 검토한다(5.1절). 지난 라운드의 "정책 값을 바꾸는 배포 전 사용 보류"는 풀린다.
- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 조건은 두 가지다. 조립하는 제품이 출시 전에 runtime 수명을 세션에 묶는 방법을 정한다(02-01). download 정책의 확장자를 직접 검토한다(`1101/02-02`).
- 템플릿 CI(merge·release 단계)를 그대로 쓰는 용도: **사용 보류.** FE-GATE-020이 고쳐질 때까지 merge 게이트가 빨갛다(02-06). 고치는 비용은 몇 줄이다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 02: `src/adapters/browser-files/` 10파일 4,818줄, `src/adapters/cache-storage/` 5파일 2,320줄, `src/adapters/cross-context-invalidation/` 3파일 1,062줄. 함께 본 것: 포트 `src/application/ports/browser-file-storage/{file,shared,cache-storage-ports}.ts`, kernel `src/adapters/browser-file-storage/result.ts`, 계약 `src/contracts/cache-invalidation.ts` |
| 커밋·작업 상태·확인 시점 | `e40684b`(detached, 격리 worktree), 2026-11-03 23:00~. `corepack pnpm install --frozen-lockfile` 뒤 미커밋 변경 없음. 지난 기준 `d99301b` 뒤 이 영역을 바꾼 커밋은 `8ad11c0`(1101/02-01), `3bb1829`(1101/02-03), `5b96529`(1101/02-05), `aedd328`(0929/02-01)과 포트 파일을 건드린 `72edb55`·`68e88b0`(영역 05)이다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker, SSR 없음. cross-context는 기본 조립이다(`src/bootstrap/runtime-adapters.ts:334-379`). cache-storage는 service-worker-pwa, browser-files는 file-transfer 레시피의 `AVAILABLE_NOT_COMPOSED` runtime이다(`config/recipes/frontend-capability-recipes.json:118-152`, `:155-201`). 공개 경계는 배럴 세 개다 |
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 봤다. 사용자 목표(짝 백엔드와 빠른 출시)에 걸리는 것은 파일 기능 제품의 세션 경계(02-01)다 |
| 읽은 코드·구성 범위 | 세 폴더 전체. 포트 3파일, `result.ts`, `cache-invalidation.ts` 전체. 소비·조립: `src/adapters/query-cache/tanstack-cache-coordinator.ts` 전체, `server-state-scope-runtime.ts:1-160`, `src/bootstrap/runtime-adapters.ts:300-420`·`:600-680`, `src/bootstrap/product-composition.ts`·`product-composition-contract.ts` 전체, `src/bootstrap/runtime-application.tsx:30-58`, `src/features/feature-adapter-contribution.ts:1-120`, `src/features/installed-feature-adapters.ts:40-90`, `src/presentation/adapters/query/server-state-generation-provider.tsx`, `.dependency-cruiser.json` 규칙 |
| 읽은 설정·문서(주장) | `docs/architecture/browser-file-and-origin-storage.md:350-380`·`:460-470`·`:955-998`, `docs/architecture/client-cache-and-storage.md:60-110`·`:845-935`, `docs/manual/03-outside-feature-folder.md:100-131`, `CHANGELOG.md:56`·`:113`·`:180`, 레시피 카탈로그 file-transfer·service-worker-pwa 항목, 지난 라운드 `2026-11-01-maturity-review/02-adapters-browser-files-cache.md`와 README 13~14절 |
| 수행한 테스트·실험 | ① 게이트: 오케스트레이터 결과를 읽었다(`scratchpad/review-gates/summary.txt`). `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`·bundle 모두 exit 0. ② 영역 unit 11파일 **138건 통과, 1.45초**(부하 8.88). recipe 계약 테스트 9건 통과. ③ 변이 30건(6.2절). ④ 실험 E-1~E-7(6.1절, 임시 테스트 2파일). ⑤ `check:optional-recipes:source`(번들 측정, 6.4절). ⑥ `flock heavy.lock` 아래 영역 browser spec 3개 × 3엔진(21/21 통과)과 제거 드릴(rc=1, 02-06). 6.3절 |
| 확인하지 못한 범위·이유 | 실제 제품 화면(레시피 미조립). 운영 QueryClient까지 연결한 2탭 로그아웃 E2E(조립된 하네스가 없다. 설계 문서 `client-cache-and-storage.md:79-80`도 인정한다). Safari의 30초 grace 충분성. file·cache observer가 제품 telemetry로 가는지(조립 코드 없음). 6.5절에 정리했다 |
| 이전 리뷰와 비교 가능한 범위 | 변이 N2x·N3x·M05·M10은 지난 라운드와 같은 변형을 이 커밋에 다시 걸었다. 지난 라운드의 E-1~E-9 결과는 증거로 쓰지 않았다. 같은 시나리오를 새로 돌렸다(E-1, E-7) |
## 2. 지난 발견 재판정
| 지난 ID | 지난 심각도 | 판정 | 현재 근거 |
| --- | --- | --- | --- |
| `1101/02-01` `previews.dispose()`가 공유 lease registry 전체를 비운다 | Medium · P2 | **고쳐짐** | registry가 소비자별 `scope()`를 준다(`src/adapters/browser-files/object-url-lease.ts:192-208`). preview(`:258-262`)와 download(`download-delivery-adapter.ts:160-162`)가 각자 scope를 쓴다. registry 전체는 `runtime.dispose()`만 비운다(`create-browser-file-runtime.ts:177-188`). 포트 주석이 범위를 적는다(`src/application/ports/browser-file-storage/file.ts:166-171`). 되돌리는 변이 F1·F2를 새 테스트가 잡는다(`tests/unit/browser-file-runtime.test.ts:179`, `browser-file-download.test.ts`의 "revokes only its own leases"). 남은 점: registry는 dispose 뒤에도 lease를 내준다(E-5). 소비자 쪽 `#disposed` 검사에 기댄다(02-03, 5.2절) |
| `1101/02-02` download 정책 `safeExtension`이 금지 목록·media type을 보지 않는다 | Low · P3 | **남음** | registry는 여전히 형식만 본다(`browser-file-policy-registry.ts:446-466`, `file-policy.ts:314`, `:378-384`). 금지 목록은 사용자 이름에만 쓴다(`file-policy.ts:357-360`). 문서의 주장 줄이 467행으로 밀렸다(`browser-file-and-origin-storage.md:467`). E-7: `application/pdf` + `.exe` 정책이 생성되고 `invoice.pdf`가 `invoice.exe`로 handoff된다 |
| `1101/02-03` stage 재검증 실패가 `CACHE_ACTIVATE`로 기록된다 | Low · P3 | **고쳐짐** | 재사용 경로가 `rebaseFailure(..., "CACHE_STAGE")`로 돌려준다(`public-response-cache-adapter.ts:497`). F3를 `public-response-cache-repair.test.ts`의 "reports a failed re-verification ... as CACHE_STAGE"가 잡는다. `readAndValidateResponse`가 operation을 `CACHE_STAGE`로 고정하는 것(`public-cache-response-validation.ts:100`)은 호출부가 rebase하는 방식으로 남았다 |
| `1101/02-04` 보호 규칙 7개가 변이에서 살아남는다 | Low · P3 | **남음** | 같은 7개 변이를 다시 걸었다. 모두 생존: N29(합계 바이트 상한 `object-url-lease.ts:144-151`), N38(host `storageArea` 동일성 `browser-cross-context-host.ts:289-295`), N27(재검사 때 receipt 무효화 `browser-file-vault.ts:334`), N26b(`no-cache` 거절 `public-cache-response-validation.ts:57`), N39(조회의 `keys()` 재확인 `public-response-cache-adapter.ts:263-267`), N30(fragment 거절 `download-input-validation.ts:348`), N26(`Set-Cookie` 거절 `public-cache-response-validation.ts:61`) |
| `1101/02-05` cross-context publish 실패 reason이 하나로 뭉친다 | Low · P3 | **고쳐짐** | 난수 실패는 `SECURE_RANDOM_UNAVAILABLE`(`browser-cross-context-invalidation.ts:318`), parse 실패는 `parsed.reason`(`:337`)을 관측에 싣는다(`:368-378`). F4a·F4b를 `cross-tab-invalidation.test.ts`의 "observes why a publish failed"가 잡는다 |
| `0929/02-01` pointer를 현재 정책으로 검증해 정책 변경·손상 뒤 영구히 멈춘다 | Medium · P2 | **고쳐짐(범위 조건 있음)** | 읽을 때 rollback 길이를 정책 상한 5와 비교한다(`public-cache-codec.ts:456-461`, `public-cache-policy.ts:39`). 활성화는 `CORRUPT_DATA` pointer를 rollback 없이 덮어쓰고, 그 밖의 읽기 실패에서는 멈춘다(`public-response-cache-adapter.ts:699-714`). E-1a: retained 3→1 뒤 조회·배포·정리·inspect가 모두 성공한다. E-1b: 손상 pointer 동안 조회·정리·inspect는 `CORRUPT_DATA`다. 다음 배포가 덮어쓰고, 정리가 r1·r2를 지운다. F5(손상도 멈춤)·F6(일시 오류도 덮어씀)·F7(옛 길이 검사)을 새 테스트 3건이 잡는다. 남은 조건: 덮어쓴 뒤 직전 활성 release가 rollback 없이 지워진다(5.1절). 손상 pointer 동안 inspect가 멈춘다(02-05) |
| `0929/02-02` `inspect()`의 비용·취소·판정 불가가 포트 계약에 없다 | Low · P3 | **남음** | 포트에 signal이 없다(`cache-storage-ports.ts:84`). 호출부가 `undefined`를 넘긴다(`public-response-cache-adapter.ts:894`). 읽기 오류도 `verified:false`다(`:899`). M05 생존 |
| `0929/02-03` CHANGELOG 0.2.0 browser-files [계약] 행의 경로·대상이 틀렸다 | Low · P3 | **남음** | `CHANGELOG.md:180`의 영향 경로가 여전히 `src/adapters/browser-file-storage/`다. Cache Storage를 "browser-files recipe"로 적는다(실제는 service-worker-pwa 레시피) |
| `0929/02-04` 설계 문서 줄 번호 참조가 밀렸다 | Low · P3 | **남음(대상 바뀜)** | 지난번 지적한 browser-files 줄은 고쳐졌다(`browser-file-and-origin-storage.md:356-374`의 `:154`·`:163`·`:48-71`·`:143-151`·`:150`·`:177-188`·`:390-396`이 맞다). 새로 밀린 곳이 5곳이다. `browser-file-and-origin-storage.md:376`의 `runtime-adapters.ts:410-416`(실제 participant는 `:386-392`). `client-cache-and-storage.md:93-100`의 `runtime-adapters.ts:364-366`(실제 `:339-341`), `server-state-scope-runtime.ts:148`(실제 `:154`), `runtime-adapters.ts:359-372`(실제 `:336-372`), `tanstack-cache-coordinator.ts:276-280`(실제 dispose `:304-314`). 문서 줄 번호를 보는 검사는 여전히 없다 |
| `0929/02-05` handoff 실패 lease 반환을 테스트가 고정하지 않는다 | Low · P3 | **남음** | `download-delivery-adapter.ts:831`에서 lease를 만들고 `:858`에서 돌려준다. M10(`:858` 삭제)이 생존한다 |
| `0929/02-06` cross-context kernel 예외가 쓰임보다 넓다 | Low · P3 · 결정 필요 | **남음(결정 대기)** | 예외가 `cross-context-invalidation/index.ts` 전체를 연다(`.dependency-cruiser.json:261`, 주석 `:254`). adapter 쪽 사용은 query-cache의 `import type` 하나다(`tanstack-cache-coordinator.ts:18-21`). 2026-11-03 결정표(지난 README 14.1)에 이 ID가 없다. repo `CLAUDE.md`는 이 예외를 kernel로 열거한다. 좁힐지는 소유자가 정한다 |
## 3. 이번 발견 (36.3)
### 02-01 browser-files runtime을 로그아웃·계정 전환에 맞춰 닫는 공식 연결점이 없다 — 문서는 템플릿 파일 수정을 안내하고, 제품 확장 지점에는 세션 수명 신호가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 15, 5, 3, 17, 9 |
| 근거 | ① runtime은 세션을 모른다. 정리 수단은 `runtime.dispose()` 하나다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`, `:177-188`). `previews.dispose()`는 그 runtime의 preview를 영구히 끄므로 세션별 정리에 쓸 수 없다(`object-url-lease.ts:290-294`, `:372-376`, 포트 `file.ts:166-171`). ② 설계 문서는 "로그아웃·계정 전환에서는 runtime 전체를 dispose한다"고 한다. 방법으로 "server-state scope reset participant로 `dispose()`를 등록하고 다음 세대에서 새 runtime을 만든다"를 들고, 예로 `runtime-adapters.ts:410-416`을 가리킨다(`docs/architecture/browser-file-and-origin-storage.md:370-377`). 레시피 카탈로그도 `dispose-browser-file-runtime-on-logout-or-account-switch`를 수명 메서드로 적는다(`config/recipes/frontend-capability-recipes.json:195`). ③ participant 목록은 템플릿 소유 파일에 고정돼 있다(`src/bootstrap/runtime-adapters.ts:386-392`). 매뉴얼은 제품이 이 파일을 고치지 않는다고 한다(`docs/manual/03-outside-feature-folder.md:106`, `:131`). ④ 제품 확장 지점 `composeProduct`는 부팅 때 한 번 불린다(`runtime-adapters.ts:609-615`). 결과 capability는 앱 수명 동안 고정된다(`:625-629`). 받는 context는 `config`·`readCookie`·`fetcher`·`http`·`isScopeReady()`뿐이다(`src/bootstrap/product-composition-contract.ts:46-56`). participant 등록도, lifecycle 구독도, 세대 `signal`도 없다. scope runtime 자체는 `subscribeLifecycle`을 갖고 있다(`src/contracts/server-state-scope.ts:28-36`). ⑤ 문서대로 template 파일에 participant를 달아도, features는 부팅 때 받은 옛 runtime을 계속 들고 있다. "다음 세대의 새 runtime"을 features에 넘기는 방법은 문서에도 예제에도 없다 |
| 발생 조건 | 제품이 file-transfer 레시피를 조립한다. 문서 권고대로 runtime을 route보다 오래 사는 곳(예: `product-composition.ts`의 capability)에 만든다. 그 뒤 로그아웃하거나 같은 탭에서 다른 계정으로 로그인한다 |
| 영향 | 화면 트리는 세대가 바뀔 때 다시 마운트된다(`src/presentation/adapters/query/server-state-generation-provider.tsx:44`, `src/bootstrap/runtime-application.tsx:36-55`). 그래서 UI 상태는 사라지지만 runtime 상태는 남는다. ① vault가 이전 사용자가 고른 File과 verification receipt를 붙잡는다(기본 최대 32개·256 MiB, `browser-file-vault.ts:100-101`). 기능이 ref를 놓지 않았다면 다음 사용자의 선택이 `LIMIT_EXCEEDED`로 막힌다. ② 놓지 않은 preview blob URL이 이전 사용자의 이미지 바이트를 메모리에 둔다. ③ 진행 중이던 download가 로그아웃 뒤에도 끝까지 가서 이전 사용자의 파일을 다음 사용자 세션에서 browser download로 넘긴다. E-5는 dispose를 부르면 `ABORTED`로 멈추고 handoff가 0회임을 보였다. 부르지 않으면 멈출 장치가 없다. 반대로 template 파일을 고쳐 연결하면 템플릿을 동기화할 때마다 충돌한다. 지난 README 14.1의 09-02 결정 이유와 같은 비용이다 |
| 심각도·우선순위 | Medium · P2 — 서버 데이터가 다른 계정으로 새는 경로는 아니다. blob URL은 추측할 수 없고, ref는 UI 상태와 함께 사라진다. 하지만 공유 기기에서 이전 사용자의 파일이 메모리와 다운로드 폴더에 남을 수 있다. 파일 업로드·다운로드는 흔한 기능이라 두 템플릿으로 빨리 출시하는 제품이 그대로 밟는다. 레시피가 미조립이라 P1은 아니다. file-transfer를 조립하는 제품에는 출시 전 결정 항목이다 |
| 통제·증거 | 문서 지시 M1 · 제품 파일만으로 연결하는 경로 M0 확인(context 타입에 수단 없음) · E1(정적), E2(E-5: dispose를 부르면 진행 작업이 멈춘다) |
| 확실성과 남은 가정 | context 타입, `composeProduct` 호출 횟수, participant 위치는 코드로 확정했다. 제품이 runtime을 어디서 만들지는 모른다(repo 안 소비자 없음). 컴포넌트 수명으로 runtime을 만들면 트리 재마운트로 풀린다. 다만 feature presentation은 adapter를 import할 수 없다(`.dependency-cruiser.json`의 `feature-presentation-does-not-know-outbound-adapters`). 그래서 그 방법을 쓰려면 factory capability를 설계해야 하는데, 그 예제가 없다. 우회로가 하나 있다. 제품이 `composeProductSessionOwner`로 세션 owner를 직접 만들면(`runtime-adapters.ts:284-290`) 같은 파일 안에서 로그아웃을 알 수 있다. 하지만 host 전역 owner를 쓰는 제품은 이 길이 없다. 그리고 이 신호는 template의 scope fence 순서(FENCED → participant → READY)와 맞물리지 않는다 |
| 결정의 근거 | 5.3절. 확인한 사실: 템플릿은 수명을 조립 쪽 책임으로 둔다(runtime이 세션을 모른다). 기록된 의도: 문서의 participant 등록 안내. 리뷰어 추론: 09-02 결정(제품은 `runtime-adapters.ts`를 고치지 않는다) 뒤에 이 안내가 갱신되지 않았다 |
| 이해 비용 | 파일 기능을 붙이는 개발자는 설계 문서 5절, `runtime-adapters.ts`, `server-state-scope-runtime.ts`, `product-composition-contract.ts`, feature capability 전달 경로까지 읽어야 "제품 파일만으로는 안 된다"는 사실을 안다 |
| 최소 개선 방향 | `ProductComposition`이 `scopeParticipants`를 돌려주면 template이 participant 목록에 붙인다. 또는 `ProductCompositionContext`에 scope lifecycle 구독을 위임한다. 그리고 file-transfer 레시피에 "capability를 factory로 주고 세대마다 runtime을 새로 만든다" 예제를 둔다(자리: indexeddb 레시피와 같은 `recipes/frontend-capabilities/`). 설계 문서 370-377행을 그 방법으로 고친다 |
| 대안 비교 | (가) 현상 유지 + 문서만 고침("컴포넌트 수명으로 만든다"): 코드 0줄. 장기 runtime이 필요한 제품은 여전히 template 파일을 고친다. (나) context에 lifecycle 구독 위임: 계약 1개 추가. 순서 보장은 제품이 한다. (다) `ProductComposition.scopeParticipants`: template의 order 규칙과 "reset 실패는 READY를 막는다" 규칙을 그대로 쓴다. (라) runtime이 세대 `AbortSignal`을 받아 스스로 닫음: adapter가 세대 개념을 알게 되고 다른 opt-in runtime도 같은 방식을 따로 받아야 한다. (다) + 레시피 예제가 가장 작다 |
| 단순화의 보존 조건 | `runtime.dispose()`가 File 참조·receipt·preview·download lease·진행 중 download를 한 번에 닫는다(`browser-file-runtime.test.ts` 첫 테스트). runtime은 세션을 모른다(adapter가 auth를 import하지 않는다). reset participant 실패는 READY를 막는다 |
| 비용·부작용 | 제품 계약 표면이 하나 는다([계약] CHANGELOG 행). 레시피 예제와 테스트 1~2개 |
| 재검토 조건 | browser-files를 기본 조립으로 올리면 template이 직접 participant를 단다. 세션 수명이 필요한 opt-in runtime이 둘 이상 되면(offline-indexeddb의 계정 범위 partition 등) 한 계약으로 같이 설계한다 |
| 완료 기준 | 제품 소유 파일만 고쳐서 로그아웃·계정 전환 때 file runtime이 dispose되고, 다음 세대의 기능이 새 runtime을 받는 예제가 있다. 그 예제를 도는 테스트가 있다. 설계 문서 370-377행이 그 방법을 가리킨다 |
| 검증 방법 | 레시피 예제를 조립한 테스트에서 세션 subject를 바꾼 뒤 ① 이전 runtime의 `content.readRange`가 `UNAVAILABLE` ② 진행 중 bounded download가 `ABORTED`이고 handoff 0회 ③ 새 세대 기능의 파일 선택이 성공 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-02 활성화 재검증이 캐시 본문 읽기의 일시 오류를 무결성 실패로 보고한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 8, 23, 24 |
| 근거 | `verifyReleaseCandidate`는 `cache.match()`가 던질 때만 `UNKNOWN`으로 본다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1097-1110`). 본문 읽기 실패는 `readAndValidateResponse`가 `UNAVAILABLE`(retry=true)이나 `NOT_READABLE`로 돌려준다(`public-cache-codec.ts:566-583`). 그런데 판정은 `ABORTED`만 `UNKNOWN`으로 두고 나머지를 모두 `REPAIRABLE`로 바꾼다(`public-response-cache-adapter.ts:1119-1125`). 활성화는 `REPAIRABLE`을 `INTEGRITY_FAILED`/`REHYDRATE`로 보고한다(`:687-692`). 같은 파일의 타입 주석은 "unreadable candidate"를 `UNKNOWN`이라고 한다(`:1071`). 조회 경로는 같은 실패의 code를 그대로 쓴다(`:352-358`). E-2: 본문 stream이 `TypeError`로 끊기면 조회는 `UNAVAILABLE/retry=true/RETRY`, 활성화는 `INTEGRITY_FAILED/retry=false/REHYDRATE`, inspect는 `verified:false`다. `match()`가 던지면 활성화도 `UNAVAILABLE/retry=true`다 |
| 발생 조건 | 활성화(또는 rollback 재활성화) 중 Cache Storage 본문 읽기가 일시적으로 실패한다(디스크 I/O 오류, 브라우저 내부 오류) |
| 영향 | 배포 흐름이 "다시 시도"가 아니라 "후보가 깨졌으니 다시 받는다"로 간다. 다시 stage하면 모든 asset을 네트워크로 다시 받는다. 캐시를 지우지는 않는다(stage 재사용 경로는 기존 후보를 지우지 않는다, `:572-579`). 관측에서는 무결성 사고처럼 보인다 |
| 심각도·우선순위 | Low · P3 — 데이터는 지켜진다. 분류·진단 오류와 불필요한 재다운로드 비용만 생긴다 |
| 통제·증거 | M0(본문 읽기 오류를 따로 분류하지 않음) · E2(E-2) |
| 확실성과 남은 가정 | 코드와 E-2로 확정. 실제 브라우저에서 본문 읽기 일시 오류가 얼마나 자주 나는지는 모른다 |
| 결정의 근거 | 적용 제외 — 이미 있는 `UNKNOWN` 분류에 본문 읽기 실패를 넣으면 되는 단순 결함이다 |
| 이해 비용 | 관측만 보는 운영자는 Cache Storage를 직접 열기 전까지 원인을 잘못 짚는다 |
| 최소 개선 방향 | `:1119-1125`에서 `INTEGRITY_FAILED`·`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`만 `REPAIRABLE`로 두고, 나머지(`UNAVAILABLE`·`NOT_READABLE`·`ABORTED`)는 `UNKNOWN`으로 둔다 |
| 대안 비교 | 적용 제외 — 타입 주석(`:1071`)이 이미 정한 계약에 맞추는 단순 수정이다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄과 테스트 1개. stage 재사용 경로는 `UNKNOWN`이면 repair 대신 실패를 돌려주게 된다(`:492-498`). 그쪽 주석의 의도와 같다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-2 시나리오에서 활성화가 `UNAVAILABLE`/retry=true다 |
| 검증 방법 | E-2를 `tests/unit/public-response-cache-repair.test.ts`에 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-03 손상 데이터·로그아웃 경로의 보호 규칙 5개를 테스트가 잡지 못한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 28, 6, 15 |
| 근거 | 이번 렌즈로 고른 변이 중 아래 5개가 관련 unit 파일을 모두 통과했다(6.2절). ① L6: `cleanupOwned()`가 읽을 수 없는 pointer를 "pointer 없음"으로 보고 소유 release 캐시를 전부 지운다(`public-response-cache-adapter.ts:798-800`을 바꿈). 지금 코드는 정리를 멈추고, 문서도 그렇게 약속한다(`browser-file-and-origin-storage.md:982-983`). ② L7: stage가 손상된 marker를 고치지 않고 실패한다(`:463`의 `CORRUPT_DATA` 예외 삭제). `REHYDRATE` 안내가 기대는 실제 회복 경로다. ③ L4: preview가 파일 resolve 뒤 `#disposed`를 다시 보지 않는다(`object-url-lease.ts:318-322`). ④ L5: vault `resolveFile`이 load 뒤 `#disposed`를 다시 보지 않는다(`browser-file-vault.ts:566-568`). ⑤ L1: vault `dispose()`가 File 참조 Map을 비우지 않는다(`browser-file-vault.ts:632`). ③④는 registry가 dispose 뒤에도 lease를 내주기 때문에(E-5) 소비자 쪽 검사가 유일한 방어선이다 |
| 발생 조건 | 리팩터링이나 단순화로 해당 줄이 빠진다 |
| 영향 | ① 손상 pointer 하나로 지금 서비스 중인 release까지 지운다. 다음 조회는 `STORAGE_EVICTED`이고 rollback도 없다. ② 손상 marker가 생기면 다시 stage해도 회복되지 않는다. ③④ 로그아웃 순간 진행 중이던 preview가 dispose 뒤 lease를 만들어 blob URL이 페이지를 닫을 때까지 남는다. ⑤ 로그아웃 뒤에도 runtime 객체가 살아 있는 동안 이전 사용자의 File이 메모리에 남는다 |
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. ①·②가 우선이다(손상에서 데이터를 지키는 규칙) |
| 통제·증거 | 각 규칙 M2 구현 · 검출 M3 없음 · E3(변이 생존) |
| 확실성과 남은 가정 | 변이 결과는 확정. ⑤는 동작(`UNAVAILABLE`)은 같고 메모리 보존만 다르다 |
| 결정의 근거 | 적용 제외 — 테스트를 더하는 문제다 |
| 이해 비용 | 규칙을 고치는 사람은 테스트가 통과해도 손상·로그아웃 보호가 남았는지 알 수 없다 |
| 최소 개선 방향 | 규칙마다 실패하는 테스트 하나. ① E-1b의 손상 pointer 상태에서 `cleanupOwned()`가 `CORRUPT_DATA`이고 캐시 수가 그대로인지. ② marker JSON을 잘라 넣은 뒤 같은 manifest stage가 성공하는지. ③ `preview.create()` 직후 같은 턴에 dispose하고 `createObjectURL`이 0회인지. ④ `content.readRange()` 직후 dispose하고 `UNAVAILABLE`인지. ⑤ dispose 뒤 `activeReferenceCount === 0`인지 |
| 비용·부작용 | 테스트 5개 |
| 완료 기준 | L1·L4·L5·L6·L7이 실패한다 |
| 검증 방법 | `scratchpad/review0203-02/mutate.mjs`의 같은 변이를 다시 건다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-04 `inspect()`와 `release()`가 겹치면 놓은 ref에 receipt가 발급되고 File이 vault에 남는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 12, 1, 11, 15 |
| 근거 | `inspect()`는 이전 receipt를 무효화한 뒤(`src/adapters/browser-files/browser-file-vault.ts:334`) 파일을 읽으며 두 번 await한다(`:335`, `:347-349`). 그 뒤 `#disposed`는 다시 보지만(`:350`) ref가 아직 있는지는 보지 않고 receipt를 발급한다(`:381-392`). `release()`는 그 사이에 record와 receipt를 지운다(`:617-623`). E-4: inspect 시작 직후 release하면 inspect가 `ok`와 receipt를 돌려준다. 그때 `activeReferenceCount 0`, `activeVerificationCount 1`이다. receipt 기록은 File을 붙잡는다(`:80-85`). preview는 `resolveVerifiedFile`의 `records.has(ref)` 검사(`:605`) 덕분에 `POLICY_REJECTED`다. 그런데 이 검사를 지운 변이 L11이 생존한다 |
| 발생 조건 | 사용자가 파일을 고른 뒤 검사가 끝나기 전에 그 파일을 목록에서 빼거나, 화면을 떠나며 ref를 놓는다 |
| 영향 | 놓은 File이 runtime dispose까지 메모리에 남는다. 호출자는 사라진 ref에 대해 성공을 받는다. 지금은 preview가 막혀 노출은 없다. L11 검사가 빠지면 놓은 파일로 preview를 만들 수 있다 |
| 심각도·우선순위 | Low · P3 — 메모리 보존과 결과 의미만 틀린다. 노출은 두 번째 검사가 막는다 |
| 통제·증거 | M0(await 뒤 ref 재확인 없음) · E2(E-4) · 두 번째 방어선은 M2 구현, 검출 없음(L11 생존) |
| 확실성과 남은 가정 | 코드와 E-4로 확정 |
| 결정의 근거 | 적용 제외 — `#disposed` 재확인 옆에 ref 재확인을 더하는 단순 결함이다 |
| 이해 비용 | vault 내부를 아는 사람만 "release 뒤에도 File이 남을 수 있다"를 안다 |
| 최소 개선 방향 | `:350`의 disposed 검사 옆에서 `this.#records.has(request.ref)`가 아니면 `NOT_FOUND`/`RESELECT`로 끝낸다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄과 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-4에서 inspect가 `NOT_FOUND`이고 `activeVerificationCount`가 0이다. L11이 실패한다 |
| 검증 방법 | E-4를 `tests/unit/browser-file-content.test.ts`에 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-05 pointer가 손상되면 `inspect()`가 아무 상태도 보여 주지 않고 실패한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(진단 공백) |
| 관련 관점 | 8, 28, 5 |
| 근거 | `inspect()`는 pointer 읽기가 실패하면 그 실패를 그대로 돌려준다(`src/adapters/cache-storage/public-response-cache-adapter.ts:866-870`). 소유 캐시 수, 후보 목록, 읽을 수 없는 캐시 수를 하나도 주지 않는다. `PublicCacheInspection`에는 pointer 상태를 담을 칸이 없다(`cache-storage-ports.ts:42-51`의 `activeReleaseRegistryId: string \| null`뿐). 설계 문서는 손상 pointer가 "조회와 cleanup을 계속 막는다"고만 적는다(`browser-file-and-origin-storage.md:982-983`). E-1b: 손상 pointer 동안 inspect가 `CORRUPT_DATA/CACHE_LOOKUP`이다 |
| 발생 조건 | active pointer가 손상되거나 정책상 읽을 수 없게 된다(`0929/02-01`이 다룬 상태) |
| 영향 | 손상을 진단할 유일한 관리 API가 손상에서 멈춘다. 운영자는 어떤 release 후보가 남았는지, 다음 활성화가 무엇을 덮어쓰고 다음 정리가 무엇을 지울지 모른 채 배포한다. 오류 operation도 `CACHE_LOOKUP`이라 inspect 실패인지 조회 실패인지 구분되지 않는다 |
| 심각도·우선순위 | Low · P3 — 다음 활성화로 회복은 된다. 진단만 막힌다 |
| 통제·증거 | M0(손상 pointer를 표현할 칸 없음) · E2(E-1b) |
| 확실성과 남은 가정 | 코드와 E-1b로 확정. 제품이 inspect를 어디서 부를지는 정해지지 않았다(미조립) |
| 결정의 근거 | 적용 제외 — 결과 타입에 pointer 상태 칸 하나를 더하는 단순 결함이다. 포트 변경([계약])이지만 repo 안 소비자가 없다 |
| 이해 비용 | 운영자는 `CORRUPT_DATA` 하나만 보고 DevTools로 Cache Storage를 직접 열어야 한다 |
| 최소 개선 방향 | `PublicCacheInspection`에 `activePointer: "NONE" \| "READABLE" \| "UNREADABLE"`을 두고, 읽을 수 없어도 후보 목록을 채운다. `0929/02-02`(signal·판정 불가)를 고칠 때 같이 한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 포트 필드 1개, 테스트 1개. service-worker-pwa 번들 여유 384 B 안에서 끝나야 한다(6.4절) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-1b의 손상 상태에서 inspect가 성공하고 `activePointer: "UNREADABLE"`과 후보 r1·r2를 보고한다 |
| 검증 방법 | E-1b를 `public-response-cache-repair.test.ts`의 0929/02-01 묶음에 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 02-06 제거 드릴 `test:browser-file-storage-removal`(merge 게이트 FE-GATE-020)이 문서 테스트 2파일 때문에 항상 실패한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 27, 18, 10 |
| 근거 | ① 드릴은 공유 fixture에 정해진 목록만 복사한다(`scripts/lib/removal-fixture.ts:25-39`). 목록에 `README.md`, `CHANGELOG.md`, `docs/`가 없다. 그 fixture에서 `test:all`을 돈다(`scripts/test-browser-file-storage-runtime-removal.ts:178`). ② `tests/unit/documentation-readiness.test.ts`(1101/14-03·14-05·14-06, `f13ed7b` 등)와 `tests/unit/changelog-review-ids.test.ts`(1101/14-02, `003832b`)는 저장소 루트의 `README.md`·`CHANGELOG.md`를 읽는다. ③ sample-removal 드릴은 바로 이 이유로 두 테스트를 fixture에서 지운다(`scripts/test-sample-removal.ts:204-215`, `e4ace51`). browser-file-storage·realtime·optional-recipe 드릴에는 같은 제외가 없다(`grep` 결과: 두 테스트 이름은 `test-sample-removal.ts`에만 있다). ④ 이 드릴은 FE-GATE-020 "removability"의 명령이다(`config/ci/gates.json:531-534`, `:2107-2125`). FE-GATE-020은 merge 단계 `gateIds`와 release 단계 `needs`에 들어 있다(`:2235-2249`, `:2310-2322`). ⑤ 실행(6.3절): `corepack pnpm test:browser-file-storage-removal` → `Browser file/storage runtime removal failed: test`. junit 7개 검사 중 `test` 하나만 실패(typecheck·lint·architecture·build·optional-catalog·ci-contract 통과). `test:all` unit에서 2파일 15건 실패, 1,519건 통과. 실패 원인은 모두 `ENOENT: ... 'README.md'`, `'CHANGELOG.md'` |
| 발생 조건 | 이 커밋에서 merge·release 파이프라인을 돌린다. 템플릿을 복사한 제품이 첫 CI를 돌린다. 조건 없이 항상 난다 |
| 영향 | merge 게이트가 빨갛다. release 단계는 FE-GATE-020을 기다리므로 막힌다. 템플릿 CI를 그대로 쓰는 다운스트림은 첫 PR부터 원인이 다른 영역(문서 테스트)인 실패를 받는다. 실제 삭제 가능성(코드·타입·빌드)은 문제없는데 드릴이 거짓 실패를 내므로, 정말로 runtime이 남아 있는 회귀가 생겨도 같은 빨간색에 묻힌다 |
| 심각도·우선순위 | High · P1 — 지원하는 배포 경로(템플릿 CI의 merge·release 단계)에서 필수 게이트가 항상 실패한다. 짝 템플릿으로 빨리 출시하려는 제품이 CI를 쓰는 첫날 막힌다. 고치는 비용은 몇 줄이다 |
| 통제·증거 | 게이트 정의 M3(check:ci는 정의만 본다) · 실제 통과 M0 · E3(이 커밋에서 드릴 실행) |
| 확실성과 남은 가정 | browser-file-storage 드릴 실패는 실행으로 확정했다. realtime·optional-recipe 드릴도 같은 원인으로 실패할 것으로 보지만 돌리지 않았다(정적 근거: 두 스크립트도 `test:all`을 돌고 제외가 없다, `test-realtime-runtime-removal.ts:128`, `test-optional-recipe-removal.ts:73`). 실제 Gitea runner에서는 돌리지 않았다 |
| 결정의 근거 | 적용 제외 — 게이트가 이미 기대 계약("pass")을 정해 두었고, 제외 목록 한 곳이 갈라진 단순 결함이다. 다만 고칠 자리는 아래처럼 고른다 |
| 이해 비용 | 실패 메시지가 "removal failed: test"뿐이다. 원인을 알려면 2,000줄짜리 로그에서 ENOENT를 찾아야 하고, sample-removal 스크립트의 제외 목록을 알아야 한다 |
| 최소 개선 방향 | 제외 목록을 `scripts/lib/removal-fixture.ts`의 한 상수로 올리고 모든 드릴이 쓰게 한다(지금은 `test-sample-removal.ts`에만 있다). 또는 fixture가 두 테스트가 읽는 문서를 복사한다. 앞쪽이 작다. 같은 파일 주석(`:41-47`)이 "copy-target 목록이 갈라져 고장 났다"고 이미 적은 패턴과 같다 |
| 대안 비교 | (가) 각 드릴 스크립트에 제외를 복사: 지금 고장의 원인(갈라진 목록)을 되풀이한다. (나) 공유 상수: 한 곳. (다) fixture가 문서까지 복사: 문서 테스트가 fixture에서도 돌아 검증이 하나 는다. 대신 문서 테스트가 "지운 경로"를 실패로 볼 수 있어(14-05가 경로 실재를 검사한다) 드릴마다 문서 예외가 필요해질 수 있다 |
| 단순화의 보존 조건 | 드릴의 나머지 6개 검사와 runtime import 0 검사(`assertNoRuntimeImports`)는 그대로다. 문서 테스트는 본 저장소의 `test:unit`에서 계속 돈다 |
| 비용·부작용 | 몇 줄. 세 드릴의 junit 결과가 바뀐다 |
| 재검토 조건 | 저장소 루트 파일을 읽는 테스트가 더 생기면 제외 목록 대신 "fixture에서 도는 테스트" 쪽을 명시하는 방식(허용 목록)을 비교한다 |
| 완료 기준 | 이 커밋 기준으로 `test:browser-file-storage-removal`, `test:realtime-removal`, `test:optional-recipe-removal`이 모두 rc=0이다. 제외 목록이 한 곳에 있다 |
| 검증 방법 | 세 드릴을 실행한다. 오케스트레이터 게이트 목록(리뷰 절차 2단계)에 FE-GATE-020의 다섯 명령을 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규. 원인 위치(`scripts/lib/removal-fixture.ts`)는 영역 12(guardrail·CI) 범위와 겹친다. 같은 결함으로 한 번만 센다 |
### 3.1 발견 색인
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
| --- | --- | --- | --- | --- | --- |
| 02-06 | High | P1 | 확인된 결함 | 21, 27, 18, 10 | 제거 드릴(FE-GATE-020)이 문서 테스트 2파일 때문에 항상 실패한다 |
| 02-01 | Medium | P2 | 구조적 위험 | 15, 5, 3, 17, 9 | browser-files runtime을 세션 수명에 묶는 공식 연결점이 없다 |
| 02-02 | Low | P3 | 확인된 결함 | 6, 8, 23, 24 | 활성화가 본문 읽기 일시 오류를 무결성 실패로 보고한다 |
| 02-03 | Low | P3 | 구조적 위험(테스트 공백) | 10, 28, 6, 15 | 손상·로그아웃 보호 규칙 5개가 변이에서 살아남는다 |
| 02-04 | Low | P3 | 확인된 결함 | 12, 1, 11, 15 | inspect·release가 겹치면 놓은 ref에 receipt가 남는다 |
| 02-05 | Low | P3 | 확인된 결함 | 8, 28, 5 | 손상 pointer에서 inspect가 상태를 보여 주지 않는다 |
| `1101/02-02` | Low | P3 | 구조적 위험 | 15, 5, 21, 23 | download 정책 `safeExtension` 검사 없음(남음) |
| `1101/02-04` | Low | P3 | 구조적 위험(테스트 공백) | 10, 15, 6, 12 | 보호 규칙 7개 변이 생존(남음) |
| `0929/02-02` | Low | P3 | 구조적 위험 | 5, 14, 24, 10 | `inspect()` 비용·취소·판정 불가(남음) |
| `0929/02-03` | Low | P3 | 확인된 결함 | 17, 9 | CHANGELOG 0.2.0 행 경로(남음) |
| `0929/02-04` | Low | P3 | 확인된 결함 | 9, 21 | 설계 문서 줄 번호(남음, 대상 바뀜) |
| `0929/02-05` | Low | P3 | 구조적 위험 | 10, 6, 14 | handoff 실패 lease 반환 테스트 공백(남음) |
| `0929/02-06` | Low | P3 | 개선 제안 | 2, 21, 22, 5, 26 | kernel 예외가 쓰임보다 넓다(남음, 결정 대기) |
## 4. 28개 관점 판정 (36.2)
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| **1** | 코드 성숙도 | 적용 — 상한, "검증 뒤에만 성공", 같은 턴 abort가 규칙이다 | M2 / M2 | E2, E3 | P — 규칙은 지켜진다(F1~F7 검출). inspect·release가 겹치면 놓은 ref에 receipt가 발급된다(02-04) |
| 2 | 구조적 성숙도 | 적용 — 배럴 공개 경계와 kernel 예외 | M3 / M3 | E1(`check:architecture` rc=0, 오케스트레이터) | P — 내부 파일 import는 게이트가 막는다. cross-context 예외가 배럴 전체를 연다(`0929/02-06`) |
| 3 | 변경 용이성 | 적용 — 정책·topic 추가와 수명 연결 | M2 / M1 | E1 | P — 정책·topic은 registry에 더하면 끝난다. file runtime을 세션에 묶으려면 template 파일을 고쳐야 한다(02-01) |
| 4 | 인지 부하 | 적용 — 1.1k줄 파일 2개와 수명 규칙 | — / — | E1 | P — 큰 파일 두 개는 지난 라운드의 "유지" 판단을 그대로 둔다. 로그아웃 연결 방법을 알려면 문서·bootstrap·계약·feature 경로 네 곳을 읽어야 한다(02-01) |
| **5** | 위험 가시성 | 적용 — dispose 범위, 실패 의미, 세션 수명 | M1~M2 / M1~M2 | E1, E2 | P — preview dispose 범위가 포트 주석에 생겼다(고쳐짐). 활성화가 일시 오류를 무결성 실패로 보인다(02-02). 세션 수명 책임이 문서에만 있다(02-01) |
| **6** | 실패 성숙도 | 적용 — 손상·일시 오류·취소 구분 | M2 / M2 | E2, E3 | P — 손상 pointer는 다음 활성화로 회복하고 일시 오류는 멈춘다(F5·F6 검출). 본문 읽기 일시 오류 분류가 틀린다(02-02). handoff 실패 lease 반환이 테스트 밖이다(`0929/02-05`) |
| 7 | 운영 성숙도 | 적용 — 관측 연결 | M2 / M2 | E1 | P — cross-context 실패는 bootstrap이 `cache.operation.failed`로 남긴다(`runtime-adapters.ts:348-364`). file·cache observer는 레시피 조립 몫이라 repo에서 연결되지 않는다 |
| 8 | 디버깅 가능성 | 적용 — 관측 reason·operation | M2 / M2 | E2 | P — stage·publish reason은 고쳐졌다(F3·F4 검출). 손상 pointer 동안 inspect가 멈춘다(02-05). 활성화가 원인을 잘못 적는다(02-02) |
| 9 | 유지보수 성숙도 | 적용 — 문서·CHANGELOG 정합 | M1 / M1 | E1 | P — 설계 문서 줄 번호 5곳이 새로 밀렸다(`0929/02-04`). CHANGELOG 0.2.0 행이 그대로다(`0929/02-03`). participant 안내가 09-02 결정 뒤 갱신되지 않았다(02-01) |
| 10 | 테스트 성숙도 | 적용 — 영역 unit, browser spec, 변이 | M3 / M3 | E2(unit 138 + recipe 9 통과), E3(browser spec 21/21 3엔진, 변이 30) | P — 변이 30건: 검출 12, 생존 15, 동등 3. 고친 4건은 모두 검출된다. 생존 15건은 `1101/02-04` 7, 02-03 5, 02-04 1(L11), `0929/02-02` 1(M05), `0929/02-05` 1(M10). 제거 드릴 fixture에서 문서 테스트가 거짓 실패한다(02-06) |
| **11** | 데이터 성숙도 | 적용 — Cache Storage pointer·marker 형식, 파일 snapshot | M2 / M2 | E2(E-1) | P — 정책을 바꾼 배포 뒤에도 pointer를 읽는다(고쳐짐). 손상 pointer를 덮어쓰면 rollback 목록이 사라지고 직전 release가 다음 정리에서 지워진다(문서화, 5.1절). prefix를 바꾸면 옛 캐시가 남는다(문서화된 제한) |
| **12** | 동시성 성숙도 | 적용 — 탭 간 순서, Web Lock, async 경쟁 | M3 / M3 | E2, E3 | P — 탭 간 역순·중복·self echo는 테스트가 잡는다(L8 검출). Web Lock으로 관리 연산을 직렬화한다. inspect·release 경쟁이 남았다(02-04). 조회의 `keys()` 재확인이 테스트 밖이다(N39) |
| 13 | 확장성 | 적용 — 상한 값 | M2 / M2 | E1 | O — source 256·dedupe 1,024 LRU, release당 entry 500·128 MiB, lease 16개. 부하 목표는 없다 |
| 14 | 성능 성숙도 | 적용 — 레시피 번들, 관리 연산 비용 | M2 / M2 | E1, E3(`check:optional-recipes:source`) | P — service-worker-pwa 9,716 / 10,100 gzip B(여유 384), file-transfer 56,053 / 57,800(여유 1,747). `inspect()`·`cleanupOwned()`에 cursor·deadline이 없다(문서화, `0929/02-02`) |
| **15** | 보안 성숙도 | 적용 — 세션 경계, 익명 캐시, 파일명 | M2~M3 / M1~M3 | E1, E2, E3 | P — 익명 stage, 인증 헤더 금지, 파일명 무력화, tab hint에 데이터 없음을 확인했다. file runtime을 세션 경계에 연결할 경로가 없다(02-01). 정책 확장자 검사가 없다(`1101/02-02`). host `storageArea` 비교가 테스트 밖이다(N38) |
| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더의 외부 패키지 import 0건(grep) | — | E1 | - |
| 17 | API / Contract 성숙도 | 적용 — 포트 계약, 제품 확장 계약 | M2 / M2 | E1, E2 | P — `TransientPreviewPort.dispose()` 범위가 정의됐다(고쳐짐). 제품 확장 계약에 세션 수명 신호가 없다(02-01). `PublicCacheInspection`이 pointer 상태를 표현하지 못한다(02-05). CHANGELOG 행이 틀렸다(`0929/02-03`) |
| 18 | 배포 성숙도 | 적용 — 정책 값을 바꾼 배포, release 단계 게이트 | M2 / M2 | E2(E-1a), E3(browser spec, 제거 드릴) | P — 정책을 바꾼 배포가 더는 이후 배포를 막지 않는다(고쳐짐, 정적 release 조합 범위). release 단계가 기다리는 FE-GATE-020이 항상 빨갛다(02-06). Service Worker drain 조합은 구현되지 않아 범위 밖이다 |
| 19 | 설정 성숙도 | 적용 — 정책 조합 검증 | M3 / M3 | E2 | P — 잘못된 cache 정책 조합은 조립 때 `TypeError`다. retained 감소가 이제 허용된다(고쳐짐). 위험한 `safeExtension`이 통과한다(`1101/02-02`) |
| 20 | 개발자 경험 | > 영역 14 — 02-01의 매뉴얼·설계 문서 충돌은 영역 14와 같이 본다 | — | — | > |
| 21 | Guardrail 성숙도 | 적용 — kernel 예외, 문서 검사, 제거 드릴 | M3 / M3(정의), M0(드릴 통과) | E1(`check:architecture`, `verify:documentation` rc=0), E3(드릴 실행) | P — kernel 예외는 게이트가 강제한다. 제거 드릴 게이트가 거짓 실패로 항상 빨갛다(02-06). 문서 줄 번호와 로그아웃 연결을 보는 검사는 없다(`0929/02-04`, 02-01) |
| 22 | 추상화 성숙도 | 적용 — lease registry·scope, 네이티브 facade | — / — | E1, E2 | P — scope로 해제 권한을 나눴다(고쳐짐). registry가 dispose 뒤에도 lease를 내줘 소비자 검사에 기댄다(E-5, 02-03 ③④) |
| 23 | 일관성 | 적용 — 실패 분류 | — / — | E1, E2 | P — 같은 본문 읽기 오류가 조회 `UNAVAILABLE`, 활성화 `INTEGRITY_FAILED`다(02-02). `QUOTA_EXCEEDED`가 `READ_ONLY`(`result.ts:80-85`)와 `ONLINE_ONLY`(`public-cache-codec.ts:597-603`)로 갈린다. stage가 `read.error.code`만 남겨 recovery를 잃는다(`public-response-cache-adapter.ts:531`) |
| **24** | 네이밍 / 의미 성숙도 | 적용 — 실패 이름이 약속하는 것 | M2 / M2 | E1, E2 | P — `REHYDRATE`가 손상 pointer에서 이제 지켜진다(다시 stage·활성화로 회복). `REPAIRABLE`이 "읽지 못함"까지 담는다(02-02). `verified:false`가 판정 불가를 합친다(`0929/02-02`) |
| 25 | 조직 확장성 | 적용 제외 — 1인 관리, 팀 경계 검증 대상 없음 | — | — | - |
| 26 | Ownership 성숙도 | > 영역 12 — kernel 예외 주석에 담당은 있고 재검토 조건은 없다(`.dependency-cruiser.json:254`) | — | — | > |
| 27 | 삭제 가능성 | 적용 — 제거 드릴 `test:browser-file-storage-removal` | M3 / M3(코드), M0(게이트 통과) | E3(드릴 실행, 6.3절) | P — browser-files·cache-storage·포트를 지운 fixture에서 typecheck·lint·architecture·build·optional-catalog·ci-contract가 통과한다. 지울 수는 있다. 드릴의 `test` 단계가 문서 테스트 때문에 실패해 게이트는 빨갛다(02-06). 지난 라운드 `?`에서 처음으로 실행 증거를 얻었다 |
| 28 | 회복 가능성 | 적용 — 손상 pointer·marker 회복 | M2 / M2 | E2(E-1b), E3(변이) | P — 손상 pointer는 다음 활성화로 회복된다(고쳐짐, 지난 판정 X에서 올라감). 그 전까지 조회·정리·inspect가 멈추고(02-05), 회복하면 rollback 후보가 사라진다. 손상 marker 회복 경로가 테스트 밖이다(02-03 ②) |
집계(이 영역에서 판정한 24개): O 1(13) · P 23 · X 0 · ? 0. 적용 제외 2(16, 25) · 다른 영역 2(20, 26). 지난 라운드 대비: 28번 X → P(0929/02-01 수정), 27번 ? → P(드릴 첫 실행), 18번 P 유지(원인이 0929/02-01에서 02-06으로 바뀜), 3·12번 O → P(02-01, 02-04).
## 5. 설계 선택 검토 (41절)
### 5.1 손상된 active pointer를 다음 활성화가 rollback 목록 없이 덮어쓴다 (`0929/02-01` 수정)
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 손상됐거나 정책상 읽을 수 없는 pointer 하나가 이후 모든 배포를 막지 않아야 한다. 동시에 검증 안 된 release를 서비스하지 않아야 한다 |
| 2. 지킬 성질 | (a) 검증한 후보만 활성화 (b) 일시 읽기 오류로 pointer를 덮어쓰지 않음 (c) 읽을 수 있는 pointer가 가리키는 캐시는 지우지 않음 (d) 손상 하나가 영구 정지가 되지 않음 (e) Service Worker 조합에서 drain 전 client의 release를 지우지 않음(문서 `browser-file-and-origin-storage.md:964-968`) |
| 3. 현재 보장 | (a) 활성화가 전체를 재검증한다(`public-response-cache-adapter.ts:674-693`). (b) `CORRUPT_DATA`만 덮어쓴다(`:703-711`, F6 검출). (c) 정리가 읽을 수 없는 pointer에서 멈춘다(`:798-800`). 다만 테스트가 없다(L6 생존). (d) E-1b로 회복을 확인했다. (e) 보장하지 않는다. 덮어쓴 뒤 rollback 목록이 비어 직전 활성 release(E-1b의 r2)가 다음 정리에서 지워진다. drain controller는 구현되지 않았다(문서 `:993-998`) |
| 4. 대안 | (가) 예전 방식: 멈춤 (나) 현재: 손상만 덮어쓰고 rollback을 비움 (다) 덮어쓸 때 소유 캐시의 검증된 marker에서 `stagedAtEpochMs` 최신순으로 rollback 목록을 다시 만든다 (라) pointer 수리 전용 관리 API |
| 5. 비교 | (가) 무결성은 같고 진행성을 잃는다(지난 라운드 28번 X 판정의 원인). (나) 코드 몇 줄로 (a)~(d)를 지킨다. (e)의 위험은 정적 release 조합에서는 없다. (다) (e)를 근사로 지킨다. 대신 marker 읽기·검증 비용이 활성화에 붙고 번들이 는다(여유 384 B). (라) 포트가 늘고 호출 시점을 호출자가 알아야 한다 |
| 6. 선택 | 정적 release 조합에서는 (나)가 타당하다. 손상 pointer 동안 조회는 이미 실패하고 있어 그 사이 캐시에서 서비스되는 것이 없다. 그래서 rollback을 잃는 실제 손해가 작다 |
| 7. 재검토 조건 | Service Worker drain 조합을 조립할 때. 그때는 drain 중인 client가 쓰는 release를 pointer 밖에서 알아야 하므로, (다)와 "drain controller가 보존 집합을 넘기는 방식"을 비교한다 |
구분: 현재 동작은 E-1b와 테스트로 확인했다. 기록된 의도는 코드 주석(`:699-702`)과 설계 문서 979-985행이다. (e)와의 관계는 리뷰어 추론이다.
### 5.2 lease registry는 하나, 해제 권한은 소비자별 scope, registry 자체에는 닫힘 상태가 없다 (`1101/02-01` 수정, 02-03)
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 탭 하나가 붙잡는 blob 메모리에 상한 하나. 로그아웃에서 모든 URL을 한 번에 끊기. 한 소비자의 정리가 다른 소비자를 끊지 않기 |
| 2. 지킬 성질 | 활성 URL 수·합계 ≤ 상한. revoke는 lease마다 한 번. runtime dispose는 전부 revoke. scope dispose는 자기 것만. **runtime dispose 뒤에는 새 URL이 생기지 않음** |
| 3. 현재 보장 | 앞의 넷은 보장한다(F1·F2 검출, runtime 첫 테스트). 마지막 성질은 registry가 아니라 소비자마다 `#disposed` 검사로 지킨다(`object-url-lease.ts:290-294`, `:318-322`, `download-delivery-adapter.ts:272-277`). registry는 dispose 뒤에도 lease를 만든다(E-5). preview의 재확인은 테스트가 없다(L4 생존). 합계 상한도 테스트가 없다(N29 생존) |
| 4. 대안 | (가) 현상 유지 (나) registry에 닫힘 상태를 두고 dispose 뒤 `create()`를 거절 (다) 소비자별 registry 분리 |
| 5. 비교 | (가) 비용 0. 새 소비자가 검사를 빠뜨리면 로그아웃 뒤 URL이 남는다. (나) 몇 줄. 방어선이 한 곳에 모인다. scope도 registry 상태를 따른다. (다) 합계 상한이 두 곳으로 갈린다(지난 라운드 결론 유지) |
| 6. 선택 | 지금은 (가)를 유지하고 L4·N29 테스트를 더한다. 지금 소비자는 둘이고 둘 다 검사를 갖고 있다 |
| 7. 재검토 조건 | 세 번째 lease 소비자(예: 이미지 CDN preview)가 같은 registry를 쓰게 되면 (나)로 바꾼다 |
구분: 사실은 코드와 E-5다. "registry에 닫힘 상태를 두지 않았다"가 의도인지는 기록이 없다.
### 5.3 browser-files runtime은 세션을 모르고, 수명은 조립이 소유한다 (02-01)
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 로그아웃·계정 전환 뒤 이전 사용자의 File·preview URL·진행 중 download가 다음 세션에 남지 않아야 한다. 제품은 template 파일을 고치지 않아야 한다(09-02 결정) |
| 2. 지킬 성질 | adapter는 auth를 모른다(경계). 세대가 바뀌면 이전 runtime은 닫히고 기능은 새 runtime을 받는다. reset 실패는 READY를 막는다 |
| 3. 현재 보장 | 닫는 동작(`runtime.dispose()`)은 완전하다(E-5). 언제 닫을지를 제품이 연결할 공식 자리가 없다(`product-composition-contract.ts:46-56`). 문서는 template 파일의 participant를 가리킨다(`browser-file-and-origin-storage.md:375-377`). 트리 재마운트(`server-state-generation-provider.tsx:44`)는 컴포넌트 수명 runtime만 정리한다 |
| 4. 대안 | (가) 현상 유지 + 문서 수정(컴포넌트 수명 권장) (나) 제품 context에 lifecycle 구독 위임 (다) `ProductComposition.scopeParticipants` (라) runtime이 세대 `AbortSignal`을 받아 스스로 닫음 |
| 5. 비교 | (가) 계약 변경이 없다. 하지만 feature presentation은 adapter를 직접 만들 수 없어 factory capability가 필요하고, 그 설계를 제품마다 반복한다. (나) scope runtime의 `subscribeLifecycle`을 넘기기만 한다. 순서 보장은 제품 몫이다. (다) template의 order·실패 규칙을 그대로 쓴다. 계약 표면이 하나 는다. (라) adapter가 세대 개념을 알게 되고, browser-transfer·indexeddb도 같은 방식을 따로 받아야 한다 |
| 6. 선택 | (다) + file-transfer 레시피 예제(factory capability)를 권한다. 수명 규칙이 template 한 곳에 남고 제품은 제품 파일만 고친다 |
| 7. 재검토 조건 | browser-files를 기본 조립으로 올리면 template이 직접 participant를 단다. 세션 수명이 필요한 opt-in runtime이 둘 이상 되면 한 계약으로 같이 설계한다 |
구분: 확인한 사실은 context 타입, 호출 횟수, participant 위치다. "09-02 뒤 문서가 갱신되지 않았다"는 리뷰어 추론이다. (다)의 비용은 추정이다.
## 6. 실험·변이 기록
임시 테스트와 스크립트는 worktree 밖 `scratchpad/review0203-02/`에 두었다(`mutate.mjs`, `mutate-result.json`, `experiments/zz-review0203-cache-cx.test.ts`, `experiments/zz-review0203-files.test.ts`, `heavy-specs*.sh`, `heavy-removal.sh`와 각 로그). 실험이 끝난 뒤 worktree에서 임시 파일을 옮기고 `git status`가 깨끗함을 확인했다. 커밋하지 않았다.
### 6.1 실험
| ID | 방법 | 결과 |
| --- | --- | --- |
| E-1a | `MemoryCacheStorage`에서 retained 3 정책으로 r1~r4를 배포한 뒤, 같은 저장소에 retained 1 adapter를 만든다. 조회, inspect, r5 배포, 정리 | `{"lookup":"ok","inspect":"ok","deployR5":["ok","ok"],"cleanup":{"inspectedOwnedCaches":6,"deletedOwnedCaches":3,"retainedOwnedCaches":3}}`, 남은 캐시 control·r4·r5 |
| E-1b | retained 1로 r1·r2를 배포한 뒤 pointer JSON을 잘라 넣는다. 조회·정리·inspect, r3 배포, 정리 | 손상 중: 조회·정리·inspect 모두 `CORRUPT_DATA/retry=false/REHYDRATE`, 캐시 그대로(control·r1·r2). r3 배포 stage·활성화 `ok`. 정리 `deletedOwnedCaches 2`(r1·r2). 남은 캐시 control·r3 |
| E-2 | r1 배포 뒤 asset의 `cache.match()`가 `TypeError`로 끊기는 본문 stream을 돌려주게 한다. 조회·재활성화·inspect. 이어서 `match()`가 던지게 하고 재활성화 | 본문 오류: 조회 `UNAVAILABLE/retry=true/RETRY`, 활성화 `INTEGRITY_FAILED/retry=false/REHYDRATE`, inspect `verified:false`. `match()` 오류: 활성화 `UNAVAILABLE/retry=true/RETRY` |
| E-4 | vault에 PNG를 capture한 뒤 `inspect()`를 시작하고 같은 턴에 `release(ref)`. 받은 receipt로 preview 생성 | inspect `ok`·receipt 있음, `activeReferenceCount 0`, `activeVerificationCount 1`, `retainedByteLength 0`, preview `POLICY_REJECTED` |
| E-5 | 공유 registry로 preview·download·vault를 만든다. preview 생성, 재검사, 생성자가 멈춰 있는 bounded download를 시작하고, 같은 턴에 runtime과 같은 순서로 dispose(download → preview → registry → vault). 그 뒤 registry에 lease를 요청 | preview `UNAVAILABLE`, inspect `UNAVAILABLE`, download `ABORTED`, handoff 0회, dispose 전에 만든 URL 0개. dispose 뒤 registry `create()`는 성공(`blob:e5-1`, 활성 1) |
| E-6 | 가짜 BroadcastChannel로 탭 A, 탭 B 세대 1을 연다. A publish → B1 닫음 → B2 열림 → A publish → A 닫고 A2 열어 publish | B1은 첫 이벤트만 받는다(`a1 seq1 NEXT`). B2는 `a1 seq2 GAP`, `a2 seq1 NEXT`. 닫힌 B1 상태 `CLOSED`. wire 키는 `cacheEpoch, emittedAt, eventId, expiresAt, protocolVersion, sequence, sourceEpoch, sourceId, topic, topicVersion`뿐이다 |
| E-7 | download 정책 `{mediaType:"application/pdf", safeExtension:".exe"}`로 registry를 만들고 `invoice.pdf`를 BOUNDED_OBJECT_URL로 전달 | 정책 생성 성공, `BROWSER_HANDOFF`, handoff 파일명 `invoice.exe` |
E-6의 `GAP`은 새 세대가 이미 순번이 진행된 다른 탭 source를 처음 볼 때 생긴다. coordinator는 그때 등록 topic 전체를 무효화한다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:137-141`). 새 세대의 QueryClient는 비어 있어 비용이 작다. 결함으로 세지 않았다.
### 6.2 변이 (E-3)
관련 unit 파일만 돌렸다(browser-files 6개 + recipe 계약, cache 3개 + recipe 계약, cross-context 2개). 30건, 약 1분 30초(시작 부하 20.41). 결과: 검출 12 · 생존 15 · 동등 3.
| ID | 바꾼 규칙 | 결과 | 연결 |
| --- | --- | --- | --- |
| N29 | object URL 합계 바이트 상한 삭제(`object-url-lease.ts:144-151`) | 생존 | `1101/02-04` ① |
| N38 | host가 `storageArea`를 캡처한 localStorage와 비교하지 않음 | 생존 | `1101/02-04` ② |
| N27 | 재검사 때 이전 receipt 무효화 삭제 | 생존 | `1101/02-04` ③ |
| N26b | `Cache-Control: no-cache` 거절 삭제 | 생존 | `1101/02-04` ④ |
| N39 | 조회가 eviction 판정 전 `keys()`를 다시 읽지 않음 | 생존 | `1101/02-04` ⑤ |
| N30 | browser-managed handoff의 fragment 거절 삭제 | 생존 | `1101/02-04` ⑥ |
| N26 | `Set-Cookie` 응답 거절 삭제 | 생존 | `1101/02-04` ⑦ |
| M05 | `inspect()`의 판정 불가를 `verified:true`로 | 생존 | `0929/02-02` |
| M10 | bounded download catch의 `lease?.release()` 삭제 | 생존 | `0929/02-05` |
| F1 | preview dispose가 registry 전체를 비움(1101/02-01 되돌림) | 검출 | 고쳐짐 확인 |
| F2 | download dispose가 registry 전체를 비움 | 검출 | 고쳐짐 확인 |
| F3 | stage 재사용 실패를 rebase하지 않음(1101/02-03 되돌림) | 검출 | 고쳐짐 확인 |
| F4a | 난수 실패 reason을 `INVALID_ENVELOPE`로 | 검출 | 고쳐짐 확인 |
| F4b | parse 실패 reason을 `INVALID_ENVELOPE`로 | 검출 | 고쳐짐 확인 |
| F5 | 활성화가 손상 pointer에서도 멈춤(0929/02-01 되돌림) | 검출 | 고쳐짐 확인 |
| F6 | 활성화가 일시 읽기 오류에서도 pointer를 덮어씀 | 검출 | 고쳐짐 확인 |
| F7 | rollback 길이를 현재 `retainedPreviousReleaseCount`와 비교 | 검출 | 고쳐짐 확인 |
| F8 | runtime dispose의 `objectUrls.dispose()` 삭제 | 동등 | preview·download scope가 모든 lease를 덮는다. 안전망 줄이다 |
| L1 | vault `dispose()`가 File 참조 Map을 비우지 않음 | 생존 | 02-03 ⑤ |
| L2 | vault `release()`가 receipt를 무효화하지 않음 | 검출 | — |
| L3 | download dispose가 진행 중 작업을 닫지 않음 | 검출 | — |
| L4 | preview가 resolve 뒤 `#disposed`를 다시 보지 않음 | 생존 | 02-03 ③ |
| L5 | vault `resolveFile`이 load 뒤 `#disposed`를 다시 보지 않음 | 생존 | 02-03 ④ |
| L6 | `cleanupOwned()`가 손상 pointer를 "없음"으로 보고 정리 | 생존 | 02-03 ① |
| L7 | stage가 손상 marker를 고치지 않고 실패 | 생존 | 02-03 ② |
| L8 | cross-context self echo 검사 삭제 | 검출 | — |
| L9 | cross-context `close()`가 listener 목록을 비우지 않음 | 동등 | `closed` 검사가 전달을 막는다. 메모리만 다르다 |
| L10 | wire 계약의 `cacheEpoch` 불일치 거절 삭제 | 검출 | — |
| L11 | `resolveVerifiedFile`이 ref 존재를 보지 않음 | 생존 | 02-04 |
| L12 | `receive()`의 `closed` 검사 삭제 | 동등 | close가 broadcast listener를 먼저 떼어 늦은 메시지가 오지 않는다 |
### 6.3 browser spec과 제거 드릴 (`flock /tmp/claude-1000/review-2026-11-03-heavy.lock`)
| 실행 | 결과 |
| --- | --- |
| 영역 browser spec 1차(23:16, 부하 70.7) | 21건 모두 실패. 원인은 코드가 아니라 호스트다. dev server가 `ENOSPC: System limit for number of file watchers reached`로 죽어 모든 페이지가 `ERR_CONNECTION_REFUSED`였다(`heavy-specs.log`). 증거로 쓰지 않았다 |
| 영역 browser spec 2차(23:33, 부하 10.6, `CHOKIDAR_USEPOLLING=1`) | **21/21 통과, 15.5초**(browser-files 3, cross-context-invalidation 2, public-cache-storage 2 × chromium·firefox·webkit). 실제 Cache API·BroadcastChannel·localStorage 이벤트·Blob download 경로가 이 커밋에서 동작한다 |
| 제거 드릴 `corepack pnpm test:browser-file-storage-removal`(23:22, 부하 38, 116초) | **rc=1.** junit(`scratchpad/review0203-02/browser-file-storage-runtime-removal.xml`): typecheck·lint·architecture·build·optional-catalog·ci-contract 통과, `test` 실패(`corepack pnpm test:all exited 1`). unit 140파일 중 2파일 실패(`documentation-readiness.test.ts` 14건, `changelog-review-ids.test.ts` 1건), 1,519건 통과. 오류는 모두 `ENOENT ... 'README.md'` / `'CHANGELOG.md'`. 02-06 |
드릴 fixture는 worktree의 `.tmp/` 아래에 생겼다가 지워졌다(실행 뒤 `.tmp/`는 비어 있다). 드릴과 spec이 만든 `artifacts/tests/` 산출물은 지웠다.
### 6.4 번들 (`check:optional-recipes:source`, 미조립 레시피 gzip)
`Optional recipes: PASS`. file-transfer 56,053 / 57,800, offline-indexeddb 37,423 / 38,500, realtime 40,857 / 42,200, service-worker-pwa 9,716 / 10,100 B. 이 영역을 고치면 service-worker-pwa 여유 384 B 안에서 끝나야 한다(02-02, 02-05, `0929/02-02`). 예산을 넘으면 지난 README 14.1의 0929/05-04 결정(측정값 + 3%) 규칙을 따른다.
### 6.5 미검증
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
| --- | --- | --- |
| 운영 QueryClient까지 연결한 2탭 로그아웃·계정 전환 | 조립된 2탭 하네스가 없다. 이번에는 transport 층만 봤다(E-6) | 탭 A 로그아웃·B 로그인 → B mutation → A 상태를 보는 2탭 E2E |
| 02-01을 연결하지 않았을 때 실제 브라우저 download가 로그아웃 뒤 끝나는지 | 레시피를 조립한 화면이 없다 | 레시피 예제를 조립한 E2E |
| Safari의 30초 grace 충분성 | 실제 다운로드 완료를 보지 않는다 | WebKit 실기에서 큰 Blob download 직후 타이머 단축 |
| file·cache observer가 제품 telemetry로 이어지는지 | 조립 코드가 repo에 없다 | 레시피를 조립한 제품에서 확인 |
| `test:realtime-removal`, `test:optional-recipe-removal`도 02-06과 같은 원인으로 실패하는지 | 영역 밖이고 무거운 실행이라 돌리지 않았다(정적 근거만 있다) | 두 드릴 실행(오케스트레이터 또는 영역 12) |
| FE-GATE-020이 실제 Gitea runner에서 같은 결과인지 | runner에서 돌리지 않았다 | runner의 merge job 실행 |
@@ -0,0 +1,400 @@
# 03 HTTP·서버 상태·인증·진단 — 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/http/`, `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`. 흐름 확인용으로 `src/bootstrap/runtime-adapters.ts`, `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/contracts/external-contract-runtime.ts`, 참조 기능, `scripts/create-feature.ts`
> 깊게 본 관점: 5, 6, 8, 12, 15, 17, 22
> 이번 라운드 렌즈: (1) V3 실행기가 짝 백엔드 Envelope를 계약대로 읽는가(백엔드 `docs/web/http-contract.md` 1·2·4절, 프론트 계약 6.1절). (2) V2 클라이언트·V2 API 행 삭제로 빠진 보호가 있는가. (3) 결과 불명(`MAYBE_APPLIED`) 처리, 멱등 키 재사용, 진단 `reason`
> 영역 판정(35.8): **조건부 사용 가능.** 조회 경로, 인증 세대 fence, 자격증명 프로필, 전송 상한, KEYED 결과 불명의 키 유지는 그대로 복제해도 된다. 짝 백엔드에 쓰기 폼을 붙이는 용도는 03-01을 고치기 전까지 **보류**한다. 업무 규칙 거절이 모두 "결과 불명"이 되어 사용자가 입력을 고쳐 다시 저장할 수 없다. 키 없는 쓰기(`NEVER`)에는 결과 불명 재전송 버튼을 달지 않는다(0929/03-03). 쓰기 descriptor를 `SAFE`로 두지 않는다(03-03). 둘 다 지금은 검사가 막지 않는다.
ID 표기: `03-NN`은 이번(2026-11-03) 라운드 발견이다. 지난 라운드는 `1101/03-NN`, 그 전 라운드는 `0929/03-NN`으로 적는다.
## 0. 결론
- **Envelope 읽기는 백엔드 계약의 모양과 멱등성 응답을 대부분 맞게 읽는다.** 성공·실패 판별, null 키 생략, 처리 중 409의 같은 키 유지와 `Retry-After`, 422 본문 불일치·400 키 오류의 "적용 안 됨", 503 `IDEMPOTENCY_UNAVAILABLE`의 같은 키 자동 재전송이 코드·실험·변이로 확인된다(6절 X-H, 기존 테스트 `tests/integration/http-execution-v3-envelope.test.ts:416-680`, 변이 M5·M9·M10·M17·M18·M20·M24 검출).
- **짝 백엔드의 업무 규칙 거절이 모든 쓰기에서 "결과 불명"이 된다(03-01, High).** 표에 없는 400·409·422는 무조건 `MAYBE_APPLIED`다. 기능의 분류기는 이를 바꿀 수 없다. 짝 백엔드가 생성하는 create는 이름 규칙 위반을 쓰기 전에 `<FEATURE>_INVALID` 400으로 돌려준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를 띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 보낼 수 없다(실험 X-A·X-B).
- **목록 응답의 `meta.page`를 버린다(03-02, Medium).** 백엔드는 페이지 목록의 전체 수·페이지 번호를 `meta.page`에 싣는다. 프론트는 `data`만 꺼낸다. 생성된 목록 화면의 "총 N개 항목"은 첫 페이지 크기(기본 20)를 전체 수처럼 보인다(실험 X-G).
- **쓰기를 `SAFE`로 설치할 수 있고, 그러면 보낸 POST를 자동으로 다시 보낸다(03-03, Medium).** 설계 정본 8.3은 `SAFE`를 GET/HEAD로 정한다. 조립 검사에 그 규칙이 없다. 생성된 뼈대(`SAFE`, `retryBudget: 2`)를 고쳐 쓰기를 만들면 그대로 통과한다(실험 X-E: fetch 2회).
- **키 없는 쓰기의 결과 불명 재전송은 그대로다(0929/03-03, 심각도 상향 제안 Medium → High).** 짝 백엔드 생성 기능의 create가 `NOT_IDEMPOTENT`라 프론트 쓰기는 `NEVER`가 기본 선택이 된다. 03-01 때문에 결과 불명 화면이 자주 뜬다. 그 화면의 "같은 요청으로 다시 보내기"는 키 없이 다시 보낸다(실험 X-D).
- **V2 삭제로 빠진 보호는 이미 판정한 셋 말고는 찾지 못했다.** 셋(401 숨은 재전송 없음, KEYED 503 같은 키 재전송, 쿠키 쓰기 CSRF)은 코드·테스트·변이로 다시 확인했다(2절, 5절 C). 남은 것은 정리 누락이다. `AppFailure.traceId`를 채우는 곳이 없어졌고, VD-23에 정본과 반대인 401 재전송 문장이 남았다(03-06).
- **지난 라운드 6건 중 3건이 고쳐졌고 변이로 검출된다(1101/03-01·03-02·03-05).** 1101/03-03은 남았다. 1101/03-04는 남았고, 이제는 템플릿 표가 직접 만든다(422). 1101/03-06은 절반만 고쳐졌다. 0929 이월 6건 중 3건이 고쳐졌다(2절).
- **변이 24개 중 19개가 검출됐다.** 생존 5개 중 M8은 사실상 동등 변이다. 진짜 빈틈은 넷이다: UNKNOWN identity lease(M1, 0929/03-06), 반사 correlation 문법(M3, 1101/03-06), 거절 표의 "상태와 code를 함께 본다" 규칙(M6), 처리 중 409를 자동 재전송하지 않는 규칙(M7). 뒤의 둘은 03-08이다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 읽기만 했다 |
| 커밋·작업 상태·확인 시점 | 프론트 `e40684b`(격리 worktree `agent-aa78f6f3b8fe6593e`, detached, 미커밋 없이 시작). 백엔드 HEAD `7ef8d0b4`(프론트 계약 기준인 `5786126c`에서 리뷰 문서만 더함, `git diff --stat`). 백엔드 작업 트리에는 미커밋 변경 400여 파일이 있다. 그중 `docs/web/http-contract.md`가 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`을 새로 적는다. 판정은 백엔드 HEAD 기준으로 하고, 작업 트리 변화는 따로 표시했다(03-04). 2026-11-03 23시대 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 사용자 목표는 프론트·백엔드 템플릿을 짝으로 써서 빨리 출시하는 것 |
| 필수 요구와 규모·운영 목표 | 짝 백엔드 계약(`http-contract.md` 1·2·4절), 프론트 계약(`docs/architecture/backend-api-and-server-state-contract.md` 4·6·6.1·16.1절), 설계 정본 8절(재시도·결과 불명). 수치 운영 목표는 없다 |
| 읽은 코드·구성 범위 | 줄 단위: `backend-envelope.ts`, `http-execution-v3.ts` 전부, `feature-http-binding.ts`, `http-retry-lifecycle.ts`, `http-effect-certainty.ts`, `external-contract-runtime.ts` 155~260·370~562·725~760, `rest-profiles.ts` 195~222, `runtime-adapters.ts` 180~240·460~620, `application-query.ts` 500~835, `use-app-form.ts` 170~408, `async-surface.tsx` 128~235, `tanstack-cache-coordinator.ts` 52~150, 참조 폼 페이지·참조 계약, `scripts/create-feature.ts` 560~760, 삭제된 V2 `client.ts`(`048f490^`)·`resolveRestSecurityProfiles`·`api-operations.ts`(`12f3bb7^`). 백엔드: `http-contract.md`, `IdempotencyExecutor.java` 80~260, `ResponseMeta`·`PageMeta`·`PageParams`·`WebMvcRequestIdFilter`·`CorsSettings`, 생성기 템플릿(controller·create use case·error code·request DTO·controller test). `src/adapters/auth`·`telemetry`·`diagnostics`·`browser-rpc`는 `d99301b..e40684b` 사이 주석만 바뀌어(`git diff`) 공개 함수와 테스트 결과만 다시 봤다 |
| 수행한 테스트·실험 | 오케스트레이터 게이트(같은 커밋) 인용: `check:architecture`·`check:types`·`lint`·`check:ci`·`check:registries`·`check:diagnostics`·`check:adapter-inventory`·`verify:documentation` rc=0, unit 2,580 · component 263 · integration 117 · contract 23 · runtime-schema 56 통과, 초기 JS 201,848 / 204,800 B. 영역 테스트 75 files / 800 tests 직접 실행(20.4초, load 14~16). 실험 X-A~X-I(6.2절), 변이 24개(6.3절) |
| 확인하지 못한 범위·이유 | 7절 |
| 이전 리뷰와 비교 가능한 범위 | `d99301b..e40684b` 사이 영역·흐름 파일 28개가 바뀌었다(+951/−1,728줄, V2 6파일 삭제). 지난 실행 결과는 증거로 쓰지 않고 이번에 다시 돌렸다 |
## 2. 지난 발견 재판정
| ID | 지난 판정 | 상태 | 현재 근거 |
|---|---|---|---|
| 1101/03-01 조회 namespace를 무효화 레지스트리와 대조하지 않는다 | Medium · P2 | **고쳐짐(런타임 진단)** | 쿼리가 캐시에 추가될 때 namespace가 어느 topic에도 없으면 `unregistered-query-namespace` 진단을 namespace당 한 번 남긴다(`tanstack-cache-coordinator.ts:57-77`). `QueryDefinition`은 등록 객체를 받는 형태를 더했다(`server-state.ts:169-171`). 문자열 형태도 남아 있어 타입으로 막지는 않는다(M3 수준). 변이 M14(진단 제거)를 `tanstack-cache-coordinator.test.ts`가 잡았다 |
| 1101/03-02 전송 전 실패가 모두 "입력 거절"로 합쳐진다 | Low · P2 | **고쳐짐** | 위반에 닫힌 `reason`이 붙고(`http-execution-v3.ts:131-135`, `refusedRequest` `:1799-1812`) 진단 `reason`으로 간다(`runtime-adapters.ts:217-219`). 바인딩은 사용자가 고칠 수 있는 5종만 `VALIDATION_REJECTED`로 둔다(`feature-http-binding.ts:498-532`). 미설치 계약도 관측 1건을 남긴다(`runtime-adapters.ts:544-570`). 변이 M15(`http-execution-v3-observability.test.ts`), M16(`feature-http-binding.test.ts`), M23(`runtime-adapters-auth-profile.test.ts`) 모두 검출 |
| 1101/03-03 mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 적는다 | Low · P3 | **남음** | 참조 기능이 `"CREATE_REFERENCE_RESOURCE"`와 `true`를 다시 쓴다(`use-reference-feature.ts:56-57`). V2 행이 지워져 같은 사실을 적는 곳은 셋에서 둘(계약, mutation 정책)로 줄었다 |
| 1101/03-04 효과 판정과 화면 분류가 두 함수로 나뉜다 | Low · P3 | **남음 — 이제 템플릿 표가 직접 만든다** | Envelope operation에서 `IDEMPOTENT_REQUEST_MISMATCH` 밖의 422는 kind `VALIDATION_REJECTED`(`backend-envelope.ts:140-150`, 422면 무조건)와 effect `MAYBE_APPLIED`(`:163-174`)를 함께 받는다. 폼은 `VALIDATION_REJECTED`를 먼저 보고 결과 불명 기록을 지운다(`use-app-form.ts:204-205`). 코디네이터는 결과 불명으로 붙들어 저장 버튼이 꺼진다. 테스트가 이 상태를 기대값으로 고정한다(`tests/component/form-foundation.test.tsx:863-883` "keeps the save off after a 422"). 참조 폼 모양이면 필드 오류와 "변경 결과를 확인할 수 없습니다"가 함께 보인다. 짝 백엔드에서 422는 멱등성 불일치와 fileserver 계열뿐이라 폼에서 만날 일은 드물다. Low 유지 |
| 1101/03-05 분류기 실패 흔적이 없다 | Low · P2 | **고쳐짐** | `contractRuntimeFailure`가 진단 `reason: CLASSIFIER_FAILED`가 된다(`http-execution-v3.ts:1747-1752`). 변이 M2(catch 가지를 `NOT_APPLIED`로)를 `http-execution-v3-observability.test.ts`가 잡았다 |
| 1101/03-06 V3 시간 초과 분류와 반사 correlation 문법 검사의 테스트가 없다 | Low · P3 | **절반 고쳐짐** | 변이 M4(TIMEOUT → `NETWORK_UNREACHABLE`)는 `feature-http-binding.test.ts`가 잡았다. 변이 M3(`safeMetadata`의 문법 검사 제거, `http-execution-v3.ts:1765`)는 영역 테스트 전부를 통과했다. 서버(또는 중간 프록시)가 준 임의 문자열이 길이 제한 없이 `AppFailure.requestId`(화면 지원 참조)와 진단 `correlation_id`로 갈 수 있다. React가 이스케이프하므로 스크립트 실행은 없다 |
| 0929/03-01 "처리 중" 409 뒤 키 보호가 풀린다 | High · P1 | **고쳐짐(프론트)** | 참조 분류기는 선언한 충돌 code만 `NOT_APPLIED`로 본다(`reference-feature-contract-contribution.ts:41-63`). Envelope operation은 표가 409를 `MAYBE_APPLIED`로 고정한다(`backend-envelope.ts:168-173`). 백엔드 계약 §2가 처리 중 409를 `IDEMPOTENT_IN_FLIGHT`·`Retry-After: 2`로 정했다. 실험 X-H: fetch 1회, `MAYBE_APPLIED`, `retryAfterMs` 2,000. 변이 M5(409를 분류기에 맡김)·M24(처리 중 409를 거절 표에 넣음) 모두 `http-execution-v3-envelope.test.ts`가 잡았다 |
| 0929/03-02 `x-correlation-id` CORS 허용이 문서 통제뿐이다 | Medium · P2 | **남음(짝 백엔드는 완화)** | 짝 백엔드는 기본으로 모든 요청 헤더를 허용하고(`CorsSettings.java:47-48`, 비면 `*`) `X-Correlation-Id`를 expose한다(`http-contract.md` §3). 프론트 쪽 확인 수단은 여전히 문서(`backend-api-and-server-state-contract.md` §5)뿐이다. 런북 FE-RB-003·README·매뉴얼에 CORS·preflight가 없다(grep 0건). 백엔드가 허용 헤더를 명시 목록으로 바꾸면 다시 드러난다 |
| 0929/03-03 결과 불명 재전송이 키 없는 명령에도 열려 있다 | Medium · P2 | **남음 — 심각도 상향 제안: High · P1** | `resendUnknownEffect`는 head가 UNKNOWN이고 intent가 있는지만 본다(`application-query.ts:792-803`). 키 없는 명령도 intent는 있다. **실험 X-D: `NEVER` 쓰기가 504 뒤 재전송하자 fetch 2회, 두 요청 모두 `Idempotency-Key` 없음.** 상향 이유: 짝 백엔드 생성 기능의 create가 `NOT_IDEMPOTENT`다(백엔드 `Create__Feature__UseCase.java.tmpl:20`, `:27`). 프론트 매뉴얼은 "모르면 `NEVER`"를 권한다(`docs/manual/02-decision-tables.md` 3절). 그래서 `NEVER` 쓰기가 짝 사용의 기본 경로다. 03-01 때문에 업무 거절마다 결과 불명 화면이 뜨고, 사용자는 "같은 요청으로 다시 보내기"를 자주 보게 된다. 응답을 정말 잃은 경우에 이 버튼을 누르면 같은 항목이 두 번 생긴다. 키 없는 명령에서 이 버튼을 숨기는 장치는 훅에도 화면에도 없다(`async-surface.tsx:221-225`). 가이드 35.2의 High 예시("결과 불명 작업의 무방비 재실행")에 해당한다. 최소 개선: `resendUnknownEffect`가 `head.intent.idempotencyKey`가 없으면 `null`을 돌려준다. 훅이 재전송 가능 여부를 내고, 화면은 그때만 버튼을 그린다 |
| 0929/03-04 결과 불명 쓰기에 문의 식별자가 없다 | Medium · P2 | **고쳐짐** | 실행 결과에 `sentRequestId`가 실리고(`http-execution-v3.ts:214-223`, `:893`), 반사 헤더가 없으면 그 값을 `requestId`로 쓴다(`feature-http-binding.ts:341-358`). 폼이 결과 불명 상태의 지원 참조를 낸다(`use-app-form.ts:368-370`). 변이 M22(fallback 제거)를 `reference-production-vertical.test.tsx`가 잡았다 |
| 0929/03-05 마감이 최종 검사 직전에 끝나면 "입력 거절"이 된다 | Low · P2 | **고쳐짐** | 최종 불변식의 `DEADLINE_EXPIRED`는 `TRANSPORT_FAILURE`/`TIMEOUT`으로 끝난다(`http-execution-v3.ts:1002-1004`). `HttpRequestRejectionReason`이 이 값을 타입에서 뺀다(`:131-135`). 변이 M21을 `http-execution-v3-observability.test.ts`가 잡았다 |
| 0929/03-06 UNKNOWN 동안 identity lease를 잡는 코드의 테스트가 없다 | Low · P3 | **남음** | 코드는 `application-query.ts:661-664`에 있다. 변이 M1(네 줄 삭제)이 영역 테스트 800건을 모두 통과했다 |
**V2 삭제 때 판정한 셋(1101 README 14.7)의 재검증**
| 항목 | 다시 본 결과 | 근거 |
|---|---|---|
| 401 뒤 숨은 재전송이 없어도 된다(정본 8.4, FRT-D016) | 맞다 | 자격증명은 보내기 전에 정해진다(`http-execution-v3.ts:779-860`). 응답 401은 끝이다(`:1270-1276`). 조립 루트는 서버가 답한 401에만 세션에 알린다(`runtime-adapters.ts:591-593`). VD-23은 반대 문장을 그대로 갖고 있다(03-06) |
| KEYED 503 `IDEMPOTENCY_UNAVAILABLE`의 같은 키 재전송 복원 | 맞다 | `invitesKeyedResend`(`backend-envelope.ts:182-187`)는 Envelope·KEYED 명령에서만 켜진다(`http-execution-v3.ts:1698-1701`). 헤더는 재시도 루프 밖에서 한 번 만들어 같은 키다(`:869-893`). 예산을 다 쓰면 `MAYBE_APPLIED`로 키를 지킨다(`envelope.test.ts:661-666`). 다른 503은 재전송하지 않는다(`:668-679`). 변이 M9(첫 답 effect를 잊음, `http-execution-v3.test.ts`)·M18(예산 무시, `envelope.test.ts`) 검출. M7(처리 중 409도 자동 재전송)은 생존했다(03-08). M8(KEYED 아닌 명령도 재전송)은 생존했지만 동등에 가깝다. 백엔드는 IU를 KEYED executor에서만 내고, `NEVER`는 예산이 0이라 재전송이 일어나지 않는다 |
| 쿠키 인증 쓰기의 CSRF 헤더 요구 복원 | 맞다 | 조립 검사가 쿠키 프로필로 GET·HEAD 밖을 쓰면서 `x-csrf-token`·`x-xsrf-token`을 요구하지 않는 operation을 거절한다(`external-contract-runtime.ts:543-556`). 쿠키 프로필은 모두 `SAME_ORIGIN_COOKIE` transport여야 해서(`rest-profiles.ts:158-185`) 빠지는 경로가 없다. 변이 M12를 `rest-profile-contract.test.ts:87-96`이 잡았다 |
## 3. 이번 발견 (36.3)
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 03-01 | High | P1 | 확인된 결함 | 6, 17, 22, 20, 28, 5, 23 (+30.5) | 짝 백엔드의 업무 규칙 거절(표 밖 400·409·422)이 모든 쓰기에서 결과 불명이 되어, 폼이 거절 이유를 못 보이고 고친 값을 다시 저장하지 못한다 |
| 03-02 | Medium | P2 | 확인된 결함 | 17, 22, 20 | Envelope 읽기가 `data`만 꺼내 백엔드 목록의 `meta.page`를 버리고 bulk `results`를 거절한다 |
| 03-03 | Medium | P2 | 확인된 결함 | 6, 21, 17, 12 | 쓰기 operation을 `SAFE`로 설치할 수 있고, 그러면 보낸 뒤 응답을 잃은 POST를 자동으로 다시 보낸다 |
| 03-04 | Low | P2 | 구조적 위험 | 6, 17, 12, 9 | 백엔드의 다른 멱등성 실패(500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 작업 중인 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`)와 503 `REQUEST_TIMEOUT`이 표 밖이라 패키지 분류기 하나에 달려 있다 |
| 03-05 | Low | P3 | 개선 제안 | 8, 7 | 결과 불명으로 끝난 쓰기의 진단·텔레메트리에 effect와 원인이 없다 |
| 03-06 | Low | P3 | 확인된 결함 | 27, 9, 24 | V2 삭제 뒤 정리 누락: `AppFailure.traceId`를 채우는 곳이 없고, VD-23에 정본과 반대인 401 재전송 문장이 남았다 |
| 03-07 | Low | P3 | 개선 제안 | 20, 17 (+30.5) | 프론트 `create:feature`와 백엔드 `new-feature.sh`가 만드는 operation이 서로 맞지 않는다 |
| 03-08 | Low | P3 | 개선 제안 | 10, 6 | 거절 표의 "상태와 code를 함께 본다" 규칙과 "처리 중 409는 자동 재전송하지 않는다" 규칙을 고정하는 테스트가 없다 |
### 03-01 짝 백엔드의 업무 규칙 거절이 모든 쓰기에서 결과 불명이 되어, 폼이 거절 이유를 못 보이고 고친 값을 다시 저장하지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 17, 22, 20, 28, 5, 23 (+30.5 샘플 대표성) |
| 근거 | ① 표: Envelope operation의 400·409·422는 `REFUSED_BEFORE_WRITE`의 세 code만 `NOT_APPLIED`이고 나머지는 모두 `MAYBE_APPLIED`다(`backend-envelope.ts:97-117`, `:163-174`). ② 실행기는 표가 판정하면 기능의 `classifyProblem`을 부르지 않는다(`http-execution-v3.ts:1722-1731`). 기존 테스트가 이를 고정한다. 분류기가 `NOT_APPLIED`라고 해도 "409 domain conflict"·"400 BAD_PARAMETER"는 `MAYBE_APPLIED`다(`http-execution-v3-envelope.test.ts:541-584`). ③ 폼은 `MAYBE_APPLIED` 분기를 `CONFLICT` 분기보다 먼저 본다(`use-app-form.ts:221` vs `:229`). 결과 불명이면 다음 제출을 막는다(`:307`). 참조 폼은 저장·취소·초기화 버튼을 모두 끈다(`reference-resource-form-page.tsx:54-55`, `:63-66`, `:116-131`). ④ 결과 불명 화면이 주는 동작은 "변경됨으로 확인"과 "같은 요청으로 다시 보내기" 둘뿐이다(`async-surface.tsx:128`, `:216-225`, 문구 `catalog.ts:15-16`, `:61`). "적용되지 않음"으로 닫는 버튼은 없다. 훅에는 그 동작이 있다(`application-query.ts:741-790`의 `reconcileUnknownEffect("NOT_APPLIED")`, `use-app-form.ts:190-196`의 `settleNotApplied`). ⑤ 짝 백엔드 생성 기능의 create는 이름 규칙을 도메인이 검사한다. `build(command)`가 트랜잭션 전에 돌고(`Create__Feature__UseCase.java.tmpl:52-53`) 실패하면 `<FEATURE>_INVALID` 400이다(`__Feature__ErrorCode.java.tmpl:13`, 백엔드 생성 테스트 `__Feature__ControllerTest.java.tmpl:62-69`). 요청 DTO에 Bean Validation을 일부러 두지 않아 `VALIDATION_FAILED`가 나오지 않는다(`Create__Feature__HttpRequest.java.tmpl:3-8`). **실험 X-B(400 `WORKLOG_INVALID`)·X-A(409 `POSTER_ALREADY_EXISTS`), 분류기 `NOT_APPLIED`:** 폼 결과 `effect-unknown`, 저장 버튼 꺼짐, 폼 오류 없음. 값을 고치고 제출해도 fetch는 1회 그대로다 |
| 발생 조건 | Envelope operation(생성한 기능의 기본값)으로 쓰기를 만들고, 백엔드가 표에 없는 400·409·422를 돌려준다. 짝 백엔드의 업무 예외(`*_INVALID`, `*_ALREADY_EXISTS`, `*_CONFLICT`, `BAD_PARAMETER`)가 모두 해당한다. 백엔드 생성 기능의 create에서는 빈 이름 하나로 생긴다 |
| 영향 | 사용자는 거절 이유(이미 있음, 규칙 위반)를 보지 못하고 "변경 결과를 확인할 수 없습니다"를 본다. 입력을 고쳐 저장할 수 없다. 빠져나가려면 사실과 반대인 "변경됨으로 확인"을 누르거나 화면을 떠나야 한다. "같은 요청으로 다시 보내기"는 같은 거절을 다시 받는다. KEYED면 백엔드가 action 예외를 `EFFECT_UNKNOWN_ABANDONED`로 기록하므로(`IdempotencyExecutor.java:193-199`, HEAD) 같은 키 재전송은 다시 실행되지 않는다. 키 없는 쓰기면 0929/03-03의 재전송 버튼이 자주 노출된다. 데이터 피해는 없다(안전 쪽으로 실패) |
| 심각도·우선순위 | High · P1 — 짝 템플릿으로 쓰기 폼을 만들 때 가장 흔한 실패 경로가 막힌다. 백엔드 생성 기능과 프론트 매뉴얼을 그대로 따라도 생긴다. 출시 전에 풀어야 한다. 데이터 피해가 없어 Critical은 아니다 |
| 통제·증거 | 중복 방지(키 유지): M4 — 표가 패키지 판정을 덮어쓴다. 업무 거절을 "적용 안 됨"으로 적을 수단: M0 — operation 단위로 선언할 칸이 없고 화면에도 동작이 없다 · 증거 E2(X-A·X-B, 기존 테스트), 백엔드 쪽 E1(생성기 템플릿 코드) |
| 확실성과 남은 가정 | 프론트 동작은 확정(jsdom). 백엔드 생성 기능의 실제 HTTP 응답은 백엔드 생성 테스트 템플릿으로만 확인했고 실행하지 않았다. 참조 도메인 code(`WORKLOG_INVALID` 등)는 프론트 계약 6.1절 표의 목록을 그대로 썼다 |
| 결정의 근거 | `[기록]` `3261208`이 "표 밖 400·409·422는 `MAYBE_APPLIED`로 고정"을 골랐다. 버린 대안 (2)는 "`classifyProblem`에 맡기면 참조 분류기처럼 400·422를 모두 `NOT_APPLIED`로 보는 패키지가 새 키를 쓴다"이다(1101 README 14.6). `[사실]` 백엔드 계약 §2·§4와 프론트 6.1절은 업무 code가 쓰기 전에만 나오는지 적지 않는다. `[사실]` KEYED에서는 백엔드도 action 예외를 결과 불명으로 기록한다. 그러니 KEYED에서 `MAYBE_APPLIED`는 백엔드 판정과 같다. `[사실]` 백엔드 생성 기능 create는 `NOT_IDEMPOTENT`이고 거절이 트랜잭션 전이다. 이 엔드포인트에서는 "적용 안 됨"이 사실이다. `[추론]` 문제는 판정 자체보다, 엔드포인트별 사실을 적을 자리가 없다는 것이다. 401·403·429는 `classifyStatus`로 operation이 정할 수 있는데(`http-effect-certainty.ts:138-153`) 400·409·422는 정할 수 없다 |
| 이해 비용 | 쓰기를 추가하는 개발자는 "내 분류기가 400을 `NOT_APPLIED`로 답해도 무시된다"는 사실을 매뉴얼 02 4절의 한 문장에서만 알 수 있다. 참조 분류기(`reference-feature-contract-contribution.ts:41-63`)는 code 목록으로 `NOT_APPLIED`를 정하는 패턴을 보여 준다. Envelope operation에서 같은 패턴은 효과가 없다 |
| 최소 개선 방향 | ① operation 단위 code 목록: `commandEffect`(또는 descriptor)에 `refusedBeforeWrite: readonly string[]`를 둔다. 표 밖 400·409·422 중 이 목록에 있는 code만 `NOT_APPLIED`로 내린다. 함수가 아니라 code 목록이라 리뷰할 수 있고, 상태 범위를 통째로 `NOT_APPLIED`로 만들 수 없다. `IDEMPOTENT_IN_FLIGHT`와 `IDEMPOTENCY_*`가 목록에 있으면 조립 검사가 거절한다. ② 매뉴얼 02 4절과 생성기의 쓰기 예시에 "백엔드 생성 기능의 `<FEATURE>_INVALID`는 쓰기 전 거절"을 적는다. ③(장기) 백엔드 실패 Envelope에 단계 신호(예: `error.applied: false`)를 두는 두 repo 계약 변경을 백엔드 소유자와 정한다 |
| 대안 비교 | 5절 A. 현상 유지: 안전하지만 쓰기 폼이 막힌다. 표 밖 400을 모두 `NOT_APPLIED`: `BAD_PARAMETER`·`MAPPING_FAILED`는 쓰기 뒤에도 나온다(6.1절)라 틀린다. 분류기 판정 복원: `3261208`이 버린 길이다. 400 전체를 `NOT_APPLIED`로 보는 분류기가 키 보호를 푼다. 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로 중복 생성될 수 있다. 설계 8.9는 "no effect" 판정을 inspect로 하라고 한다. ①이 가장 좁다 |
| 단순화의 보존 조건 | 표의 세 `NOT_APPLIED` code와 처리 중 409·503 `IDEMPOTENCY_UNAVAILABLE`의 `MAYBE_APPLIED`는 어떤 선언으로도 바뀌지 않는다. 목록에 없는 code는 지금처럼 결과 불명이다 |
| 비용·부작용 | 공개 타입 칸 1개, 조립 검사 몇 줄, 판정 한 줄. 매뉴얼·생성기 갱신. 칸이 선택이라 다운스트림은 깨지지 않는다 |
| 재검토 조건 | 백엔드가 단계 신호를 내면 ①을 그 신호로 바꾼다. 백엔드에 inspect 엔드포인트가 생기면 화면의 "적용되지 않음" 확인을 inspect로 연결한다 |
| 완료 기준 | X-B에서 `WORKLOG_INVALID`를 선언한 operation은 결과 불명이 아니고, 저장 버튼이 켜져 있다. 고친 값을 저장하면 fetch 2회이고 두 번째는 새 키다. 선언하지 않은 code는 지금처럼 결과 불명이다. 처리 중 409를 목록에 넣으면 조립이 실패한다 |
| 검증 방법 | X-A·X-B를 `tests/component/form-foundation.test.tsx`의 "correcting a field after a server validation refusal" 묶음으로 옮긴다. 변이 M10(표 무시)·M5(409를 분류기로)·M24는 계속 검출돼야 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-02 Envelope 읽기가 `data`만 꺼내 백엔드 목록의 `meta.page`를 버리고 bulk `results`를 거절한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 22, 20 |
| 근거 | `meta` 스키마는 `requestId`·`traceId`·`correlationId`만 남기고 나머지를 지운다(`backend-envelope.ts:20-26`, `.strip()`). `readSuccessEnvelope`는 `data`만 돌려준다(`:68-73`). 실행기는 그 값만 `outputValidator`에 넘긴다(`http-execution-v3.ts:1435-1451`). 성공 스키마는 최상위 `.strict()`이고 `data`만 안다(`backend-envelope.ts:28-35`). 백엔드 §1은 `meta.page`(`number`·`size`·`total`·`sort`)를 페이지 목록 응답의 키로 적고, bulk 성공을 `results`로 적는다. 백엔드 목록 컨트롤러가 `meta.page`를 싣는다(`WorkLogController.java:110-113`). 기본 페이지 크기는 20이다(`PageParams.java:18`). 기존 테스트 이름이 "ignores meta keys it does not know"이고 그 예시에 `page`가 들어 있다(`http-execution-v3-envelope.test.ts:323-340`). **실험 X-G:** `meta.page.total: 137`을 보낸 성공 응답의 결과 값은 `data` 배열뿐이고, 결과 객체에 page 정보가 없다. 프론트 계약 §7은 다른 모양(본문 안의 `CursorPage`)을 요구한다. 생성된 목록 화면의 "총 {count}개 항목"은 배열 길이다(`create-feature.ts:953-955`) |
| 발생 조건 | 짝 백엔드의 페이지 목록(`PageParams`·`withPage`)에 목록 화면을 붙인다. bulk 엔드포인트를 부른다 |
| 영향 | 목록은 첫 페이지(기본 20개)만 받고 전체 수·다음 페이지 여부를 모른다. 생성된 목록 화면은 페이지 크기를 전체 수처럼 보인다. 페이지 이동 UI를 만들 수 없다. 우회하려면 `responseEnvelope`를 빼고 기능 스키마가 Envelope 전체를 읽어야 한다. 그러면 Envelope 실패 판정(03-01의 표, 필드 오류 읽기)을 함께 잃는다. bulk 성공은 `ENVELOPE_MISMATCH`가 된다(쓰기면 `MAYBE_APPLIED`) |
| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 페이지 목록은 거의 모든 제품에 있어 짝 사용의 흔한 경로다. 우회가 있지만 비싸다 |
| 통제·증거 | 계약 지원: M0(읽을 수단 없음) · E2(X-G, 기존 테스트) |
| 확실성과 남은 가정 | 확정. 백엔드 bulk 엔드포인트의 사용처는 보지 않았다 |
| 결정의 근거 | `[기록]` 1101 README 14.6은 bulk 사용처가 없다고 적었다. `meta.page`에 대한 기록은 찾지 못했다. `[추론]` 프론트 계약 §7(cursor)과 백엔드(offset `meta.page`)가 따로 설계돼 Envelope 읽기가 어느 쪽도 고르지 않았다 |
| 이해 비용 | 목록을 만드는 개발자는 전체 수가 왜 20인지 찾으려고 실행기까지 내려가야 한다 |
| 최소 개선 방향 | 성공 결과에 선택 필드 `page?: Readonly<{ number; size; total; sort? }>`를 둔다. Envelope operation이고 `meta.page`가 스키마(정수 범위, `size` 1~100)를 통과할 때만 싣는다. 바인딩은 `mapSuccess(value, { page })`처럼 두 번째 인자로 넘긴다. 프론트 계약 §7에 "짝 백엔드는 offset `meta.page`"를 적고 cursor 계약과의 관계를 정한다. bulk는 지원하지 않는다고 4.1절에 적는다 |
| 대안 비교 | 기능 스키마가 Envelope 전체를 읽기: 실패 판정을 잃는다. `outputValidator`에 `{data, page}`를 넘기기: 기존 기능 스키마가 모두 깨진다. 백엔드가 page를 `data` 안에 넣기: 백엔드 계약 변경 |
| 단순화의 보존 조건 | 바이트·구조 상한은 Envelope 전체에 걸린다. `meta`의 모르는 키는 계속 무시한다 |
| 비용·부작용 | 결과 타입 선택 필드 1개, 바인딩 인자 1개. 초기 JS 수십 바이트 |
| 재검토 조건 | 백엔드가 cursor 페이지로 바꾸면 프론트 §7 계약으로 합친다 |
| 완료 기준 | X-G에서 바인딩의 `mapSuccess`가 `total: 137`을 받는다. 생성된 목록 화면이 전체 수를 `page.total`로 보인다 |
| 검증 방법 | X-G를 `http-execution-v3-envelope.test.ts`에 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-03 쓰기 operation을 `SAFE`로 설치할 수 있고, 그러면 보낸 뒤 응답을 잃은 POST를 자동으로 다시 보낸다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(조립 검사 누락) |
| 관련 관점 | 6, 21, 17, 12 |
| 근거 | 설계 정본 8.3은 `SAFE`를 "GET/HEAD; network failure after dispatch 허용"으로 정한다. 매뉴얼은 "읽기(GET)는 늘 `SAFE`다"라고 적는다(`02-decision-tables.md` 3절). 조립 검사(`external-contract-runtime.ts:429-562`)는 `NEVER`+재시도 예산(`:557-562`)과 KEYED의 recovery(`:527-529`)만 본다. 쓰기가 `SAFE`인지 보지 않는다. 재시도 권한은 `SAFE`면 보낸 뒤에도 참이다(`http-retry-lifecycle.ts:21-30`, 사용처 `http-execution-v3.ts:1044-1060`). 생성된 뼈대 descriptor가 `SAFE`·`retryBudget: 2`다(`create-feature.ts:663`, `:684`). 쓰기를 추가할 때 이 파일을 고쳐 쓰는 것이 매뉴얼 경로다(`01-add-a-feature.md:37`). V2에도 이 규칙은 없었다(COMMAND의 `replayPolicy: SAFE` 허용, `12f3bb7^:src/contracts/api-operations.ts:191-208`). 삭제와 무관한 기존 빈틈이다. **실험 X-E:** `POST` + `commandEffect` + `SAFE` + `retryBudget: 2` 계약이 조립을 통과했다. 첫 시도가 보낸 뒤 네트워크 오류로 끝나자 같은 요청을 다시 보내 fetch 2회, 결과 `SUCCESS` |
| 발생 조건 | 개발자가 뼈대의 GET descriptor를 복사해 쓰기를 만들면서 `retrySemantics`를 바꾸지 않는다 |
| 영향 | 응답을 잃은 생성 요청이 최대 두 번 더 나간다. 서버가 멱등 처리를 하지 않으면 같은 항목이 여러 개 생긴다. 결과가 `SUCCESS`로 보여 사용자도 모른다 |
| 심각도·우선순위 | Medium · P2 — 피해는 중복 쓰기로 크다. 다만 매뉴얼이 경고하는 실수가 있어야 한다. 고치는 비용은 몇 줄이다 |
| 통제·증거 | 목표 M4(조립 거절) / 확인 M1(설계·매뉴얼 문장) · E2(X-E) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 적용 제외 — 설계 정본이 이미 정한 규칙의 검사가 빠졌다 |
| 이해 비용 | 적용 제외 — 단순 검사 누락이다 |
| 최소 개선 방향 | 조립 검사에 "`retrySemantics === "SAFE"`이면 method는 GET 또는 HEAD"를 더한다. 위반 문구에 `IDEMPOTENT`/`KEYED`/`NEVER`를 고르는 매뉴얼 절을 적는다 |
| 대안 비교 | 적용 제외 — 규칙이 정본에 고정돼 있다 |
| 단순화의 보존 조건 | GET/HEAD의 `SAFE`·`IDEMPOTENT`는 그대로다 |
| 비용·부작용 | 조립 검사 몇 줄. 이미 쓰기를 `SAFE`로 적은 다운스트림은 부팅에서 실패한다(CHANGELOG [계약] 행) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | X-E 계약이 조립에서 "SAFE는 GET·HEAD만" 이유로 거절된다 |
| 검증 방법 | `tests/unit/external-contract-runtime.test.ts`에 X-E 계약 거절 테스트 1건 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-04 백엔드의 다른 멱등성 실패와 503 `REQUEST_TIMEOUT`이 표 밖이라 패키지 분류기 하나에 달려 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 6, 17, 12, 9 |
| 근거 | 표가 정하는 5xx는 503 `IDEMPOTENCY_UNAVAILABLE` 하나다(`backend-envelope.ts:163-174`). 다음 셋은 모두 분류기가 정한다. 백엔드 HEAD §2의 500 `IDEMPOTENCY_RECOVERY_REQUIRED`("재전송도 재실행도 안전하지 않다"). §4의 503 `REQUEST_TIMEOUT`(비동기 요청 시간 초과, 처리가 계속될 수 있다). 백엔드 작업 트리(미커밋)의 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`("새 키 금지"). **실험 X-F:** 분류기가 `NOT_APPLIED`라고 하면 세 code 모두 `SERVER_FAILURE`/`NOT_APPLIED`다. 폼은 `retry-later`가 되고, "다시 시도"는 결과 불명 기록이 없으므로 새 키로 보낸다(X-A의 재전송 뒤 결과 `retry-later`도 같은 경로다). 분류기가 `MAYBE_APPLIED`라고 하면 키는 지키지만, `RECOVERY_REQUIRED`에도 "같은 요청으로 다시 보내기"가 보이고 같은 500을 다시 받는다 |
| 발생 조건 | 기능 분류기가 5xx를 `NOT_APPLIED`로 본다. 그리고 멱등성 저장소가 장애이거나, 백엔드가 비동기 요청 시간을 넘긴다 |
| 영향 | 백엔드가 "새 키 금지·재실행 금지"라고 한 요청이 새 키로 다시 실행될 수 있다. 드문 장애 경로다 |
| 심각도·우선순위 | Low · P2 — 분류기 실수와 장애가 겹쳐야 한다. 그러나 표가 "백엔드 자신의 판정"을 소유한다고 적으면서(`http-execution-v3.ts:1722-1723` 주석, 매뉴얼 02 4절) 백엔드 §2의 일부만 담는다. 표에 몇 줄을 더하면 닫힌다 |
| 통제·증거 | 표가 강제하는 범위: M4(503 `IDEMPOTENCY_UNAVAILABLE`만) / 나머지 M1(매뉴얼 "모르면 `MAYBE_APPLIED`") · E2(X-F) |
| 확실성과 남은 가정 | `COMPLETION_UNKNOWN`은 백엔드 작업 트리에만 있다. 커밋되면 프론트 6.1절의 기준 커밋도 옮겨야 한다 |
| 결정의 근거 | 적용 제외 — 표의 범위 누락이다 |
| 이해 비용 | 분류기를 쓰는 사람은 백엔드 §2 표의 어느 줄을 프론트가 이미 처리하는지 코드 주석을 읽어야 안다 |
| 최소 개선 방향 | `envelopeFailureEffect`에 500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 503 `REQUEST_TIMEOUT`, (백엔드가 커밋하면) 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`을 `MAYBE_APPLIED`로 더한다. `RECOVERY_REQUIRED`는 바인딩 결과에 "재전송 불가" 표시를 실어 화면이 재전송 버튼을 숨기게 한다 |
| 대안 비교 | 적용 제외 — 기존 표에 행을 채우는 문제다 |
| 단순화의 보존 조건 | 503 `IDEMPOTENCY_UNAVAILABLE`의 자동 재전송은 그대로다. 다른 5xx는 자동 재전송하지 않는다(`envelope.test.ts:668-679`) |
| 비용·부작용 | 표 몇 줄. 6.1절 표와 매뉴얼 02 4절 갱신 |
| 재검토 조건 | 백엔드 §2·§4 표가 바뀔 때마다(6.1절의 "기준 커밋을 올리면 같은 변경에서 다시 확인") |
| 완료 기준 | X-F의 세 code가 분류기와 관계없이 `MAYBE_APPLIED`다 |
| 검증 방법 | X-F를 `http-execution-v3-envelope.test.ts`의 표 묶음에 넣는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-05 결과 불명으로 끝난 쓰기의 진단·텔레메트리에 effect와 원인이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 8, 7 |
| 근거 | 관측 기록에는 `effect`가 있다(`http-execution-v3.ts:314`). 조립 루트 projector는 그것을 진단에도 텔레메트리에도 싣지 않는다(`runtime-adapters.ts:195-228`). 진단 허용 키에 `effect`가 없다(`diagnostics.ts:25-45`). 상태는 묶음(`4xx`)만 남는다(`diagnostics.ts:237-241`). 백엔드 code는 일부러 싣지 않는다(1101 README 14.6). 기존 테스트가 "409 `IDEMPOTENT_IN_FLIGHT`"와 "409 domain conflict" 둘 다 `reason` 없음으로 고정한다(`http-execution-v3-envelope.test.ts:590-615`) |
| 발생 조건 | 사용자가 "변경 결과를 확인할 수 없습니다"와 지원 참조를 들고 문의한다. 운영자가 결과 불명 쓰기 수를 보려 한다 |
| 영향 | 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중 409와 업무 409, IU 재전송 소진이 같은 줄이 된다. 원인은 서버 로그를 correlation id로 찾아야 안다(찾을 수는 있다). 텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다 |
| 심각도·우선순위 | Low · P3 — 서버 로그로 원인을 찾을 길이 있다. 03-01이 결과 불명을 자주 만들수록 가치가 커진다 |
| 통제·증거 | M0(기록 없음) · E2(기존 테스트), E1(projector 코드) |
| 확실성과 남은 가정 | 확정. 텔레메트리에 `effect`를 더하는 것이 VD-07 허용 라벨 규칙에 맞는지는 보지 않았다 |
| 결정의 근거 | `[기록]` 원 code를 진단에 싣지 않는 것은 cardinality 결정 대기다(14.6). `[추론]` `effect`는 값 5개로 닫혀 있어 그 결정과 무관하다 |
| 이해 비용 | 적용 제외 — 진단 필드 추가 문제다 |
| 최소 개선 방향 | 진단 허용 키에 `effect`(닫힌 5값)를 더하고 projector가 싣는다. 결과 불명의 원인을 닫힌 `reason` 셋(예: `IN_FLIGHT`, `IDEMPOTENCY_UNAVAILABLE_EXHAUSTED`, `STAGE_UNKNOWN`)으로 싣는다 |
| 대안 비교 | 원 code를 싣기: cardinality 결정이 먼저다. 현상 유지: 서버 로그에 기댄다 |
| 단순화의 보존 조건 | 텔레메트리 라벨은 닫힌 값만 쓴다. correlation id는 진단 전용이다 |
| 비용·부작용 | 허용 키 1개, projector 몇 줄, `check:diagnostics` 갱신 |
| 재검토 조건 | 진단 sink가 생기면(지금은 메모리 버퍼뿐, `runtime-adapters.ts:297`) 우선순위를 올린다 |
| 완료 기준 | 처리 중 409와 업무 409의 진단 기록이 `reason`에서 갈리고, 둘 다 `effect: MAYBE_APPLIED`를 갖는다 |
| 검증 방법 | `envelope.test.ts:590-615`의 기대값을 바꾼다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-06 V2 삭제 뒤 정리 누락: `AppFailure.traceId`를 채우는 곳이 없고, VD-23에 정본과 반대인 401 재전송 문장이 남았다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 27, 9, 24 |
| 근거 | `AppFailure`와 `createFailure`는 `traceId`를 받는다(`errors.ts:129`, `:152`, `:180`). 이를 채우던 곳은 V2 `client.ts`의 Envelope `meta.traceId`였다(`048f490^:src/adapters/http/client.ts`의 `parseResponse` 실패 반환). 지금 `src`에서 `createFailure`에 `traceId`를 넘기는 곳은 0곳이다(grep). VD-23은 "401 recovery는 auth-required이면서 replay-safe한 operation만 한 번 수행한다"를 그대로 갖고 있다(`docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md:422-423`). 정본 8.4(FRT-D016)와 반대이고, 1101 README 14.7이 "리뷰 대상"으로 남긴 문장이다. 소비자 0인 `projectCertaintyToUi`(`http-effect-certainty.ts:155-167`, 1101 R4)도 그대로다 |
| 발생 조건 | 개발자가 `AppFailure.traceId`를 화면·진단에 쓰려 한다. 401 처리를 VD-23으로 배운다 |
| 영향 | 빈 칸을 믿고 만든 코드는 항상 `undefined`를 받는다. VD-23을 읽은 사람이 숨은 재전송을 다시 넣을 수 있다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | M0 · E1(grep, 문서 대조) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 적용 제외 — 삭제의 뒷정리다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | `traceId`를 타입에서 지우거나 Envelope `meta.traceId`를 실패에 싣는다(둘 중 하나). VD-23의 401 문장을 정본 8.4로 바꾼다. `projectCertaintyToUi`를 지운다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | `requestId` 경로(반사 헤더 → 보낸 id)는 그대로다 |
| 비용·부작용 | 몇 줄. 타입에서 지우면 다운스트림이 쓰는지 확인한다(tech-log·memento grep) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `traceId`가 채워지거나 타입에 없다. VD-23에 401 재전송 문장이 없다 |
| 검증 방법 | grep, `verify:documentation` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-07 프론트 `create:feature`와 백엔드 `new-feature.sh`가 만드는 operation이 서로 맞지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 (영역 14와 겹칠 수 있다) |
| 관련 관점 | 20, 17 (+30.5) |
| 근거 | 프론트는 `GET /api/<base>-items` 목록 하나를 만든다(`create-feature.ts:258`, `:652-668`). 백엔드는 `POST /<plural>`(201, `NOT_IDEMPOTENT`)와 `GET /<plural>/{id}`를 만든다(`__Feature__Controller.java.tmpl:31-68`, `new-feature.sh`의 `path_segment`). 목록 엔드포인트가 없고 경로 접두사도 다르다 |
| 발생 조건 | 두 생성기를 같은 기능 이름으로 돌린다 |
| 영향 | 생성 직후 프론트 목록이 백엔드에서 405를 받는다(추론, 실행하지 않음). 개발자가 매 기능마다 목록 엔드포인트(백엔드)나 상세·생성 operation(프론트)을 손으로 맞춘다. 매뉴얼은 "생성된 파일을 실제 계약으로 바꾸기"라고만 적는다(`01-add-a-feature.md:37`) |
| 심각도·우선순위 | Low · P3 — 피해는 없고, 기능마다 반복되는 작업 시간이다 |
| 통제·증거 | M0 · E1 |
| 확실성과 남은 가정 | 두 생성기를 실제로 돌려 붙여 보지는 않았다 |
| 결정의 근거 | `[추론]` 두 생성기가 각 repo의 리뷰 라운드에서 따로 만들어졌다 |
| 이해 비용 | 기능 하나를 짝으로 만드는 사람이 두 repo의 생성 결과를 비교해 operation을 맞춘다 |
| 최소 개선 방향 | 두 생성기가 같은 operation 쌍(목록 GET, 생성 POST, 상세 GET)과 같은 경로 규칙을 만든다. 프론트 생성기의 쓰기 `retrySemantics`는 백엔드 생성기의 멱등성 선택(`NOT_IDEMPOTENT` → `NEVER`)과 맞춘다 |
| 대안 비교 | 매뉴얼에 맞추는 표만 둔다: 비용이 매번 남는다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 두 생성기 템플릿 수정. `test:feature-scaffold`와 백엔드 `verify-feature-scaffold.sh` 갱신 |
| 재검토 조건 | 두 템플릿 중 하나만 쓰는 사용처가 많아지면 다시 본다 |
| 완료 기준 | 같은 이름으로 두 생성기를 돌린 뒤 프론트 목록·생성·상세가 백엔드 생성 엔드포인트에 그대로 닿는다 |
| 검증 방법 | 백엔드 생성 테스트의 응답 본문으로 프론트 생성 gateway 테스트를 돌린다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-08 거절 표의 "상태와 code를 함께 본다" 규칙과 "처리 중 409는 자동 재전송하지 않는다" 규칙을 고정하는 테스트가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 10, 6 |
| 근거 | **변이 M6:** `refusedBeforeWrite`가 status를 보지 않게 해도(`backend-envelope.ts:123`) 영역 테스트 전부가 통과했다. 주석은 "Only the status and code together count"라고 적는다(`:89-90`). **변이 M7:** `invitesKeyedResend`가 409 `IDEMPOTENT_IN_FLIGHT`에도 참이 되게 해도 통과했다. Envelope 표 테스트는 `retryBudget: 0`·`maxRetryAttempts: 0`이라(`envelope.test.ts:58-67`, `:288-295`) 재전송 여부를 볼 수 없다. KEYED 재전송 묶음(`:617-680`)은 503만 본다 |
| 발생 조건 | 표·재전송 조건을 고치는 리팩터링 |
| 영향 | M6: 표의 code가 다른 status로 오면 `NOT_APPLIED`가 된다(지금 백엔드에 그런 응답은 없다). M7: 처리 중 409를 요청 안에서 2초 기다려 다시 보낸다. 같은 키라 중복은 없지만 설계 8.3·매뉴얼 02 3절과 다른 동작이 조용히 들어간다 |
| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다. 회귀를 막는 테스트가 없을 뿐이다 |
| 통제·증거 | M2(구현) / 검출 없음 · E2(M6·M7 생존) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 적용 제외 — 테스트 추가 문제다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | `envelope.test.ts`에 ① 422 `VALIDATION_FAILED`(표 code, 다른 status) → `MAYBE_APPLIED` ② `retryBudget: 1`인 KEYED가 409 IN_FLIGHT를 받으면 fetch 1회 — 테스트 2건. 0929/03-06(M1)·1101/03-06(M3)의 테스트도 같이 넣는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 2~4건 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | M1·M3·M6·M7이 검출된다 |
| 검증 방법 | `node scratchpad/r03/run-mutations.mjs M1 M3 M6 M7`(오케스트레이터 scratchpad) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 | P — 짝 백엔드 판정이 한 모듈(`backend-envelope.ts`)에 모였다. 바인딩의 `default` 가지가 새 위반 종류를 `ENVELOPE_MISMATCH`로 흡수한다(`feature-http-binding.ts:536`, 1101 R3 남음) |
| 2 | 구조적 성숙도 | 다른 영역 | — | 게이트 | > 12·16 영역. `check:architecture` PASS |
| 3 | 변경 용이성 | 적용 | M3 / M2 | E1 | P — V2 행이 지워져 쓰기 하나에 맞출 곳이 셋에서 둘이다(1101/03-03). 업무 code 판정을 바꾸려면 템플릿 파일 `backend-envelope.ts`를 고쳐야 한다(03-01) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 쓰기 실패 판정은 401·403·429 → 표 → 분류기 → 폼 분기 순서를 알아야 한다. 매뉴얼 02 4절이 설명하지만 "분류기가 무시된다"는 한 문장이다 |
| **5** | 위험 가시성 | 적용 | M3 / M2 | E2 | P — 재시도·Envelope·멱등성이 descriptor 한 곳에 보인다. 표가 분류기를 덮어쓴다는 사실(03-01)과 쓰기의 `SAFE`(03-03)는 descriptor만 보고 알 수 없다 |
| **6** | 실패 성숙도 | 적용 | M4 / M2 | E2 | P — 처리 중 409 키 유지, IU 같은 키 재전송, 결과 불명 자동 재전송 금지는 맞다. 업무 거절이 결과 불명이 된다(03-01). `SAFE` 쓰기가 보낸 뒤 재전송된다(03-03). 키 없는 재전송(0929/03-03, X-D) |
| 7 | 운영 성숙도 | 적용 | M2 / M1 | E1 | P — 텔레메트리 라벨은 닫혀 있다. 결과 불명 쓰기 수를 셀 수 없다(03-05). 진단은 메모리 버퍼뿐이다(`runtime-adapters.ts:297`) |
| **8** | 디버깅 가능성 | 적용 | M2 / M2 | E2 | P — 보낸 id fallback(0929/03-04), 전송 전 거절 `reason`(1101/03-02), 분류기 실패(1101/03-05), 멱등성 거절 `reason`이 들어왔다. 결과 불명의 원인·effect가 없다(03-05). `traceId` 빈 칸(03-06) |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P — 6.1절 표가 백엔드 SHA에 묶여 있고 재확인은 문장 규칙뿐이다. 백엔드 작업 트리의 새 code를 아직 모른다(03-04). VD-23 낡은 문장(03-06) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 영역 75 files / 800 tests, 20.4초. 변이 24개 중 19개 검출(동등 1개 빼면 23개 중 19개). 빈틈: UNKNOWN identity lease(M1), 반사 correlation 문법(M3), 표의 status 대조(M6), 처리 중 409 무재전송(M7) |
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent뿐이다 |
| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2 | P — 세대 fence, 진행 중 mutation 동안 원격 무효화 지연, 같은 입력의 같은 intent는 유지된다(변이 M19 검출). 키 없는 재전송(0929/03-03), `SAFE` 쓰기 재전송(03-03) |
| 13 | 확장성 | 다른 영역 | — | — | > 11·15 영역 |
| 14 | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — 바이트·구조 상한이 Envelope 전체에 걸리고(`http-execution-v3.ts:1347-1435`), 실패 Envelope는 64 KiB 이하다(`:1613-1621`, 변이 M11 검출). V2 삭제 뒤 초기 JS 201,848 / 204,800 B(게이트) |
| **15** | 보안 성숙도 | 적용 | M4 / M3 | E2 | O — 자격증명 헤더는 프로필이 정한다. `redirect: "error"`·`no-referrer`·`no-store`다(`http-execution-v3.ts:971-984`). 쿠키 쓰기 CSRF 요구가 복원됐다(M12 검출). 반사 correlation 값 문법 검사에 테스트가 없다(M3 생존, 1101/03-06) |
| 16 | 의존성 성숙도 | 다른 영역 | — | — | > 13 영역 |
| **17** | API / Contract | 적용 | M3 / M2 | E2 | P — 백엔드 §1 모양과 §2의 처리 중·불일치·키 오류·IU는 맞다. `meta.page`·bulk를 못 읽는다(03-02). §2·§4의 나머지 5xx가 표 밖이다(03-04). 업무 code의 단계 신호가 계약에 없다(03-01) |
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 13 영역 |
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P — `REQUEST_TIMEOUT_MS`는 상한으로만, `MAX_RETRY_ATTEMPTS`는 ceiling으로 쓴다(`runtime-adapters.ts:468-475`). 교차 origin CORS 요구는 문서뿐이다(0929/03-02) |
| 20 | 개발자 경험 | 적용 | M2 / M1 | E2 | P — 생성 기능이 Envelope를 읽어 1101 README 14.3의 막힘은 풀렸다. 업무 거절 막힘(03-01), 목록 전체 수(03-02), 짝 생성기 불일치(03-07). 전체 판정은 14 영역 |
| 21 | Guardrail 성숙도 | 적용 | M4 / M3 | E2 | P — 조립 검사가 CSRF·KEYED recovery·NEVER 예산·Envelope 값을 막는다. 쓰기의 `SAFE`는 막지 않는다(03-03). namespace는 진단으로 잡는다(1101/03-01, M14 검출) |
| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E2 | P — `FeatureHttpBinding`은 좁고, Envelope 해석은 한 모듈이다. 표가 패키지 분류기를 상태 범위째 덮어 operation이 아는 사실을 적을 자리가 없다(03-01). 효과와 화면 분류가 두 곳에서 정해진다(1101/03-04) |
| 23 | 일관성 | 적용 | M2 / M1 | E1 | P — 401·403·429는 `classifyStatus`로 operation이 `NOT_APPLIED`를 정할 수 있는데, 400·409·422는 정할 수 없다(03-01) |
| 24 | 네이밍 / 의미 | 적용 | M1 / M1 | E1 | P — "같은 요청으로 다시 보내기"가 키 없는 명령에도 동작한다(0929/03-03). `invitesKeyedResend` 주석의 "refused before the command ran"은 백엔드 HEAD 코드와 다르다(백엔드 RR-02-03. 같은 키라 결과에는 영향 없음) |
| 25 | 조직 확장성 | 다른 영역 | — | — | > 14 영역 |
| 26 | Ownership | 적용 | M1 / M1 | E1 | P — 6.1절 표는 프론트가 백엔드 코드를 읽어 만든 판정이다. 백엔드가 code를 더할 때 프론트에 알리는 경로는 백엔드 §5의 문장 하나다 |
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E2 | O — V2 클라이언트·V2 API 행을 지우고 게이트가 통과했다. 정리 누락 둘이 남았다(03-06) |
| 28 | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 결과 불명은 같은 키로 재전송되고, IU는 자동 재전송된다. 업무 거절 뒤에는 고쳐서 저장할 길이 없다(03-01). 새로고침·fence 뒤는 새 키다(런북 6.3-7에 적힌 한계) |
X(미충족)는 없다. 6·17·20·28은 03-01(High)과 0929/03-03(상향 제안)이 남아 있어 P다.
## 5. 설계 선택 검토 (41절)
`[사실]`은 코드·실행으로 확인한 것, `[기록]`은 커밋·문서에 적힌 의도, `[추론]`은 리뷰어의 해석이다.
### A. Envelope operation의 400·409·422 판정을 템플릿 표가 소유하고, 기능 분류기는 덮어쓴다 (`3261208`)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 쓰기가 실패하면 적용 여부를 정한다. 그것으로 키 유지와 화면을 정한다. `[기록]` 설계서 4.4 "frontend는 problem effect meaning을 작성하지 않는다" |
| 2. 지킬 성질 | 결과를 모르면 `NOT_APPLIED`라고 하지 않는다. 쓰기 전에 거절된 요청은 사용자가 고쳐 다시 보낼 수 있다 |
| 3. 현재 보장 | `[사실]` 세 code만 `NOT_APPLIED`, 나머지 400·409·422는 `MAYBE_APPLIED`로 고정한다. 패키지 실수가 키 보호를 풀 수 없다(M4, 변이 M10 검출). **보장하지 않음:** 쓰기 전 거절이 확실한 업무 code(백엔드 생성 기능의 `<FEATURE>_INVALID`)도 결과 불명이 되어 두 번째 성질을 어긴다(03-01) |
| 4. 대안 | (a) 현재 (b) 분류기 판정 복원 (c) operation 단위 `refusedBeforeWrite` code 목록 (d) 백엔드 단계 신호(`error.applied`) |
| 5. 비교 | (a) 안전하지만 폼이 막힌다. (b) `3261208`이 버린 길이다. 상태 범위를 통째로 `NOT_APPLIED`로 보는 분류기가 키를 푼다. (c) 리뷰할 수 있는 code 목록이다. IN_FLIGHT·IDEMPOTENCY_*는 조립이 거절해 (a)의 안전을 지킨다. 비용은 칸 1개다. (d) 가장 정확하지만 두 repo 계약을 바꿔야 한다 |
| 6. 현재 조건에서 | `[추론]` (c). 짝 백엔드는 단계 신호가 없고, 업무 code의 단계는 엔드포인트마다 다르다. 그 사실을 아는 사람은 기능 작성자뿐이다 |
| 7. 재검토 조건 | 백엔드가 (d)를 내면 (c)를 (d)로 바꾼다. (c)의 목록에 잘못 넣은 code로 중복이 관측되면 목록에 백엔드 테스트 근거를 요구한다 |
### B. 503 `IDEMPOTENCY_UNAVAILABLE`에만 KEYED 자동 재전송을 연다 (`c05f41a`)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 백엔드 §2는 이 응답 뒤 "같은 키로 나중에 다시 보낸다"를 요구한다. 정본 8.3은 KEYED 자동 재전송을 "known response status가 retry 가능하다고 명시한 경우만" 허용한다 |
| 2. 지킬 성질 | 같은 키로만 보낸다. 보낸 뒤 응답을 잃은 요청은 자동 재전송하지 않는다. 예산을 다 쓰면 키를 지킨다 |
| 3. 현재 보장 | `[사실]` Envelope + KEYED + 503 IU에서만 `keyedResend`가 켜진다(`http-execution-v3.ts:1698-1701`). 헤더를 루프 밖에서 한 번 만들어 같은 키다. 소진하면 `MAYBE_APPLIED`다. 다른 503은 재전송하지 않는다. **보장하지 않음:** 백엔드 HEAD는 complete 단계 저장소 장애도 같은 IU로 낸다(백엔드 RR-02-03). 그때 action은 이미 돌았다. 같은 키라 중복은 없지만 주석의 "refused before the command ran"은 사실이 아니다. 참조 기능처럼 `retryBudget: 0`이면 재전송이 일어나지 않는다(매뉴얼 02 3절이 그렇게 안내한다) |
| 4. 대안 | (a) 현재 (b) 자동 재전송 없이 결과 불명 화면으로(`c05f41a` 이전) (c) 409 IN_FLIGHT도 `Retry-After` 뒤 자동 재전송 |
| 5. 비교 | (a) 일시 장애를 사용자 몰래 넘긴다. 같은 키라 안전하다. (b) 사용자가 매번 버튼을 누른다. (c) 2초 대기가 요청 마감(기본 10초)을 많이 쓴다. 처리 중 요청이 길면 소용없다 |
| 6. 현재 조건에서 | `[추론]` (a) 유지. 다만 매뉴얼 02 4절의 "503 → 결과 불명 화면" 흐름도에 자동 재전송을 적고, 주석의 "실행 전" 단정을 백엔드 HEAD에 맞춰 고친다 |
| 7. 재검토 조건 | 백엔드가 `COMPLETION_UNKNOWN`을 커밋하면 IU는 정말 "실행 전"이 된다. 그때 IU를 `NOT_APPLIED`+같은 키 재전송으로 바꿀 수 있는지 다시 본다 |
### C. V2 클라이언트와 V2 API 행을 지우고 V3 하나만 남긴다 (`048f490`, `12f3bb7`)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 실행 경로 하나. 사용자 지시("레거시를 코드에 둬서 코드 크기 키우지 말고") |
| 2. 지킬 성질 | V2만 갖고 있던 보호 중 정본이 요구하는 것은 V3에 있어야 한다 |
| 3. 현재 보장 | `[사실]` 이미 판정한 셋은 2절 표대로 맞다. V2 `client.ts`·`resolveRestSecurityProfiles`·`api-operations.ts`를 다시 읽어 더 찾은 차이는 넷이다. ① provider별 `credentials` 허용 목록(`allowedCredentialsModes`)이 없어졌다. 쿠키 프로필의 `include`를 막는 곳이 없다. 그러나 프로필은 제품 소유 파일 한 곳에서만 더하고, 쿠키 쓰기는 CSRF 요구로 막힌다. 없어도 된다고 판정한다. ② V2는 잘못된 `meta` id를 버리고 응답을 읽었다. V3는 응답 전체를 거절한다. 백엔드가 id를 `[A-Za-z0-9._-]{1,128}`로 정리하므로(`WebMvcRequestIdFilter.java:68`, `:194-199`) 지금 영향은 없다. 더 엄격해진 것이라 보호 손실이 아니다. ③ V2는 실패에 `meta.traceId`를 실었다. 지금은 빈 칸이다(03-06). ④ 쓰기의 `SAFE`를 막는 규칙은 V2에도 없었다. 03-03은 삭제와 무관한 기존 빈틈이다 |
| 4. 대안 | (a) 지금 (b) V2를 `@deprecated`로 한 릴리스 유지 |
| 5. 비교 | (a) 초기 JS 1,859 B 감소, 판정 한 벌. (b) 옮길 사용자가 없다(커밋 본문) |
| 6. 현재 조건에서 | `[사실]` (a)가 맞다. 남은 일은 03-06의 정리다 |
| 7. 재검토 조건 | 다운스트림(memento-web의 V2 행) 이식 중 V2에만 있던 동작에 기댄 코드가 나오면 그 동작을 정본 기준으로 다시 판정한다 |
## 6. 실험·변이 기록
### 6.1 환경
- worktree `agent-aa78f6f3b8fe6593e`, `e40684b` detached, `corepack pnpm install --frozen-lockfile`. 미커밋 없이 시작했다.
- 영역 테스트 목록: 오케스트레이터 scratchpad `r03/area-tests.txt`(43개 경로: `tests/integration` 전체, `tests/features/reference-feature`, `tests/unit/browser-rpc`, `tests/platform/telemetry`, 영역 단위·컴포넌트 파일). M12 재실행부터 `tests/unit/rest-profile-contract.test.ts`를 더했다.
- baseline: 75 files / 800 tests 통과, 20.4초(load 14~16).
- 실험 파일 `tests/component/r03-experiments.test.tsx`(jsdom). 실제 `createContractHttpExecutor` + `createFeatureHttpBinding` + `useApplicationMutation` + `useAppForm`를 쓰고 fetch만 `vi.fn`으로 바꿨다. 10 tests 통과. 사본을 scratchpad `r03/r03-experiments.test.tsx`에 두고 worktree에서는 지웠다.
- 변이 스크립트 scratchpad `r03/run-mutations.mjs`: 원문을 메모리에 두고 한 곳 바꿈 → 영역 테스트 `--bail=1` → 원문 복원. 결과 `r03/mutation-results.txt`. 변이 동안 호스트 load가 30~67이었다(다른 리뷰어와 겹침). 시간은 비교에 쓰지 않는다.
- 끝난 뒤 `git checkout -- . && git clean -fd`로 되돌렸고 `git status --short`가 비었다. 커밋하지 않았다.
### 6.2 실험
| ID | 무엇 | 결과 |
|---|---|---|
| X-A | KEYED Envelope 쓰기 폼(분류기 `NOT_APPLIED`)이 409 `POSTER_ALREADY_EXISTS`를 받는다. 값을 고쳐 제출하고, 그다음 "Resend"(같은 키, 백엔드 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 흉내) | 첫 답 뒤 폼 `effect-unknown`, indicator `mutation-effect-unknown`, 저장 버튼 꺼짐, 폼 오류 없음. 고친 값 제출: fetch 1회 그대로. 재전송: 키 `[key-1, key-1]`, 폼 `retry-later`(분류기가 500을 `NOT_APPLIED`로 봄 → 03-04) |
| X-B | 같은 폼, 400 `WORKLOG_INVALID` | X-A와 같다 |
| X-D | (0929/03-03) `NEVER` 쓰기, 첫 답 504 HTML → 결과 불명 → "Resend" | fetch 2회, 키 `[null, null]`, 결과 `success` |
| X-E | (03-03) `POST` + `SAFE` + `retryBudget: 2` 계약을 조립하고, 첫 fetch가 보낸 뒤 TypeError로 끝난다 | 조립 통과. fetch 2회, `SUCCESS` |
| X-F | (03-04) KEYED, 분류기 `NOT_APPLIED`, `retryBudget: 2`. 500 `IDEMPOTENCY_RECOVERY_REQUIRED` / 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` / 503 `REQUEST_TIMEOUT` | 셋 모두 fetch 1회, `SERVER_FAILURE`/`NOT_APPLIED` |
| X-G | (03-02) 성공 Envelope에 `meta.page.total: 137` | 결과 값은 `data` 배열뿐. 결과 객체 키는 `kind,value,metadata,effect,sentRequestId` |
| X-H | (0929/03-01) KEYED, `retryBudget: 2`, 409 `IDEMPOTENT_IN_FLIGHT` + `Retry-After: 2` | fetch 1회, `CONFLICT`/`MAYBE_APPLIED`, `retryAfterMs` 2,000 |
| X-I | KEYED, `retryBudget: 1`, 첫 답 503 IU, 재전송 답 400 `VALIDATION_FAILED`(필드 목록) | fetch 2회, `VALIDATION_REJECTED`/`MAYBE_APPLIED`. 앞선 시도의 결과 불명을 지킨다. 폼에서는 1101/03-04 모양(필드 오류 + 저장 꺼짐)이 된다. 같은 본문이 재전송에서만 바인딩 실패할 일은 거의 없어 발견으로 세지 않았다 |
### 6.3 변이 (관점 10)
결과: 24개 중 19개 검출, 5개 생존. 생존 중 M8은 사실상 동등 변이다. 동등을 빼면 23개 중 19개 검출이다.
| 변이 | 위치 | 결과 | 해석 |
|---|---|---|---|
| M1 UNKNOWN 동안 identity lease를 잡지 않음 | `application-query.ts:661-664` | **생존** | 0929/03-06 그대로 |
| M2 `classifyProblem` throw → `NOT_APPLIED` | `http-effect-certainty.ts:115-120` | 검출(`http-execution-v3-observability.test.ts`) | 1101/03-05 고쳐짐 |
| M3 반사 correlation 문법 검사 제거 | `http-execution-v3.ts:1765` | **생존** | 1101/03-06 남은 절반 |
| M4 바인딩 TIMEOUT → `NETWORK_UNREACHABLE` | `feature-http-binding.ts` TRANSPORT_FAILURE 분기 | 검출(`feature-http-binding.test.ts`) | 1101/03-06 절반 고쳐짐 |
| M5 Envelope 409를 분류기에 맡김 | `backend-envelope.ts:168-169` | 검출(`http-execution-v3-envelope.test.ts`) | |
| M6 거절 표가 status를 보지 않음 | `backend-envelope.ts:123` | **생존** | 03-08 |
| M7 처리 중 409도 KEYED 자동 재전송 | `backend-envelope.ts:186` | **생존** | 03-08 |
| M8 KEYED 아닌 명령도 IU 재전송 | `http-execution-v3.ts:1698-1701` | 생존 | 동등에 가깝다. 백엔드는 IU를 KEYED executor에서만 낸다. `NEVER`는 예산 0이다. `IDEMPOTENT`는 되풀이해도 된다고 선언한 명령이다 |
| M9 IU 재전송이 첫 답의 effect를 잊음 | `http-execution-v3.ts:1123` | 검출(`http-execution-v3.test.ts`) | |
| M10 Envelope 표 무시(분류기가 400·409·422 판정) | `http-execution-v3.ts:1725` | 검출(`envelope.test.ts`) | 03-01의 보존 조건 |
| M11 실패 Envelope 상한 = `responseByteLimit` | `http-execution-v3.ts:1616-1621` | 검출(`http-execution-v3-live-authority.test.ts`) | |
| M12 쿠키 쓰기 CSRF 조립 검사 제거 | `external-contract-runtime.ts:547-548` | 검출(`rest-profile-contract.test.ts`, 재실행) | 첫 실행은 이 테스트가 목록에 없어 생존으로 나왔다. 목록에 넣고 다시 돌렸다 |
| M13 멱등성 거절 `reason` 제거 | `http-execution-v3.ts:1697` | 검출(`envelope.test.ts`) | |
| M14 미등록 namespace 진단 제거 | `tanstack-cache-coordinator.ts:77` | 검출(`tanstack-cache-coordinator.test.ts`) | 1101/03-01 고쳐짐 |
| M15 전송 전 거절 `reason` 제거 | `http-execution-v3.ts:1806-1808` | 검출(`http-execution-v3-observability.test.ts`) | 1101/03-02 |
| M16 연결 실수를 입력 거절로 | `feature-http-binding.ts:530-532` | 검출(`feature-http-binding.test.ts`) | 1101/03-02 |
| M17 모든 400 `VALIDATION_FAILED`를 필드 오류로 | `backend-envelope.ts:148` | 검출(`envelope.test.ts`) | |
| M18 IU 재전송이 재시도 상한 무시 | `http-execution-v3.ts:1101-1107` | 검출(`envelope.test.ts`) | |
| M19 결과 불명 재전송이 `Retry-After`를 기다리지 않음 | `application-query.ts:618-619` | 검출(`application-mutation-admission.test.tsx`) | |
| M20 Envelope 성공 frame 확인 생략 | `http-execution-v3.ts:1438` | 검출(`envelope.test.ts`) | |
| M21 최종 검사 `DEADLINE_EXPIRED` → 거절 | `http-execution-v3.ts:1002` | 검출(`http-execution-v3-observability.test.ts`) | 0929/03-05 고쳐짐 |
| M22 보낸 요청 id fallback 제거 | `feature-http-binding.ts:356` | 검출(`reference-production-vertical.test.tsx`) | 0929/03-04 고쳐짐 |
| M23 미설치 계약의 관측 제거 | `runtime-adapters.ts:555` | 검출(`runtime-adapters-auth-profile.test.ts`, 재실행) | 첫 실행의 실패 파일은 무관한 `security-followup-archive.test.ts`였다(load 40대). 재실행에서 이 변이를 보는 테스트가 실패했다 |
| M24 처리 중 409를 거절 표(`NOT_APPLIED`)에 넣음 | `backend-envelope.ts:97-117` | 검출(`envelope.test.ts`, 재실행) | 첫 실행의 첫 실패 파일은 `live-authority`였다. 재실행에서 표 테스트가 실패했다 |
## 7. 미검증 목록
| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 짝 백엔드와의 실제 통합(03-01·03-02·03-04) | 백엔드는 읽기만 했다. 실험은 백엔드 계약과 생성 테스트의 본문을 fetch mock으로 흉내 냈다 | 백엔드 생성 기능을 띄우고 빈 이름 create, 페이지 목록, IU 장애 주입 |
| 백엔드 작업 트리의 미커밋 계약 변경 | 400여 파일이 다른 세션에서 바뀌는 중이다. `http-contract.md`의 `COMPLETION_UNKNOWN`만 대조했다. `GlobalExceptionHandler`·`EnvelopeBodyAdvice`도 바뀌어 6.1절 표가 달라질 수 있다 | 백엔드 커밋 뒤 6.1절 표를 그 SHA로 다시 대조 |
| 실제 브라우저 화면(X-A·X-B·X-D) | jsdom에서만 확인했다 | Playwright 폼 시나리오 |
| 두 생성기를 붙인 실제 동작(03-07) | 두 생성기를 함께 돌리지 않았다 | 같은 이름으로 생성 후 통합 실행 |
| 다운스트림에 03-01·03-03·0929/03-03 경로가 있는가 | tech-log·memento를 읽지 않았다 | 두 제품의 descriptor `retrySemantics`·`responseEnvelope`와 재전송 버튼 grep |
| Browser RPC·auth·telemetry·diagnostics의 세부 동작 | 이번 범위에서 주석만 바뀌었다. 영역 테스트 통과만 확인했다 | 지난 라운드 변이를 다시 돌리기 |
| 여러 탭·새로고침 뒤 결과 불명 | intent가 탭 메모리에만 있다는 것은 코드로 확인했다(런북 6.3-7) | 두 컨텍스트 e2e |
| 텔레메트리에 `effect`를 더하는 것이 VD-07에 맞는가(03-05) | VD-07을 다시 읽지 않았다 | VD-07 허용 라벨 대조 |
@@ -0,0 +1,330 @@
# 04 realtime 어댑터 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/realtime/`, `src/contracts/realtime-streams.ts`, `src/application/policies/bounded-polling.ts`
> 깊게 본 관점: 6, 7, 12, 13, 14, 17
> 렌즈: ① realtime snapshot 바인딩이 V2 API 행 대신 V3 descriptor에서 뽑은 `ApiOperationRow`를 읽는다. 이전과 같은 것을 지키는가 ② `BoundedPollOperationContract`의 `contractVersion: 2`가 V2 HTTP 경로 삭제 뒤에도 뜻이 맞는가 ③ 재연결·끊김·마감 실패 분류
ID 표기: 이번 라운드 발견은 `04-01`부터 쓴다. 지난 라운드는 `1101/04-NN`, 그 전 라운드는 `0929/04-NN`이다.
**영역 판정 (35.8)**
| 범위 | 판정 | 이유 |
| --- | --- | --- |
| codec·stream coordinator·WebSocket 연결·live↔Poll handoff·reconnect coordinator | 지정 범위에서 사용 가능 | 입력 검증, 자원 상한, 순서·중복·gap, DRAINING fence가 유지된다. 지난 라운드의 결과 동결 규칙(1101/04-01)과 마감 kind(1101/04-02)가 고쳐졌고 변이로 고정된다(R4, D1~D4) |
| reconnect coordinator + SSE | 조건부 사용 가능 | 서버만 끊긴 뒤 멈추던 결함(0929/04-01)이 고쳐졌다(R1·R2 검출). 조합 코드가 SSE session bridge와 EOF 분류를 직접 정해야 한다(0929/04-02) |
| bounded polling + V3 HTTP 실행기 | 조건부 사용 가능 | 조합 코드가 poll 전용 실행기의 재시도를 0으로 묶어야 한다. 계약 선언은 이것을 검사하지 못한다(04-01) |
| 짝 백엔드 템플릿과 realtime을 그대로 연결 | 해당 용도의 사용 보류 | 백엔드는 STOMP·NDJSON을 내고 프론트는 SSE·`realtime.v1`을 기대한다. 어느 쪽에도 대응표가 없다(04-02) |
## 0. 결론
- 지난 라운드 차단 항목(0929/04-01, High)은 **고쳐졌다.** 서버만 끊기면 run이 멈추던 문제다. 막는 테스트가 있고, 수정을 되돌리는 변이(R1)와 SSE 어휘를 바꾸는 변이(R2)가 모두 잡힌다.
- 1101/04-01(결과 생성 함수 미공개)과 1101/04-02(`IDLE_TIMEOUT` 남용)는 **고쳐졌다.** handoff 마감 4곳(1101 README 14.4의 남은 문제)도 `17fa8d1`로 고쳐졌다. 1101/04-03(WebSocket 초당 이벤트 상한 테스트)은 **남았다**(R7 생존).
- 렌즈 ①: snapshot 바인딩은 **이전과 같은 것을 지킨다.** 받아들이는 조합은 `GET × SAFE|IDEMPOTENT`다. V2 규칙(`QUERY` = GET|HEAD × SAFE|IDEMPOTENT)보다 HEAD만 빠져 더 좁다(실험 S). 다만 이 검사를 막는 테스트가 없다. 검사를 통째로 지워도 테스트가 모두 통과한다(04-03).
- 렌즈 ②: `contractVersion: 2`는 **뜻을 잃었다.** 계약 필드는 지운 V2 행의 어휘이고, 무엇과도 대조하지 않는 자기 선언이다. 그래서 V3 실행기의 재시도를 보지 못한다. 실험에서 poll 3회가 실제 요청 9회가 됐다(04-01, Medium).
- 렌즈 ③: 재연결 멈춤은 풀렸고 마감 kind는 13.1과 맞다. 남은 것은 두 가지다. 서버만 끊긴 경우 SSE·polling은 `OFFLINE`, WebSocket은 `PROVIDER_UNAVAILABLE`로 끝난다(04-04). 서버가 스트림을 정상 종료(EOF)했을 때 재연결할지 정한 곳이 없다(0929/04-02).
- 사용자 목표(짝 템플릿으로 빠른 출시)에 걸리는 것: 짝 백엔드와 realtime이 바로 연결되지 않는다(04-02, Medium). 실시간이 필요한 제품은 출시 전에 어느 쪽을 새로 쓸지 정해야 한다.
- 이번 발견 6건: **Medium 2 · Low 4.** High 이상은 없다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`(`7ef8d0b4`)는 읽기만 했다 |
| 커밋·작업 상태·확인 시점 | `e40684b`(두 작업 브랜치를 합친 것). 분리 worktree에서 `git checkout --detach e40684b`, `corepack pnpm install --frozen-lockfile`. 리뷰 끝에 작업 트리를 되돌렸다. 2026-11-03 23:00~ |
| 목적과 지원 실행 구성 | 템플릿. realtime은 `RECIPE_AVAILABLE`·`AVAILABLE_NOT_COMPOSED`다. 조합 코드(bridge, 환경 신호, 닫기, poll `execute`)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개 |
| 필수 요구와 규모·운영 목표 | 합의된 SLO 없음. 설계 문서의 상한표(11절)와 실패 어휘(13.1절)를 기준으로 봤다 |
| 읽은 코드·구성 범위 | `d99301b..e40684b`에서 영역을 바꾼 커밋 전부(`4d27b20`, `3fe28de`, `1196b86`, `17fa8d1`, `12f3bb7`의 realtime·contracts 부분, 합치기 `e40684b`). 전부 읽음: `realtime-streams.ts`, `api-operations.ts`, `bounded-polling.ts`, `bounded-poll-coordinator.ts`. 필요한 부분: `reconnect-coordinator.ts`(online 대기, 재시도 분기, 결과 파서), `sse/fetch-sse-connection.ts`(거절·EOF 분류, `readSseForReconnect`), `websocket-connection.ts`(오류 분류, rate 상한, heartbeat), `stream-coordinator.ts`·`live-poll-handoff-coordinator.ts`(마감 kind), `external-contract-runtime.ts`(descriptor 검증), `http-execution-v3.ts`·`http-retry-lifecycle.ts`(재시도), `installed-feature-runtime-registries.ts`, `feature-module.ts` |
| 읽은 문서(주장) | 설계 `realtime-events-web-push-and-bounded-polling.md` 상태표·4.5·5.3·6.3·9.2·9.3·11·13.1절, `VD-28`·`VD-23` 일부, `optional-adapter-recipes.md` 1·5절, `CHANGELOG.md` 미출시 절, 지난 라운드 `2026-11-01-maturity-review/04-adapters-realtime.md`와 README 13~14절. 짝 백엔드 `src/adapter/inbound/websocket/README.md`, `src/adapter/inbound/web-advanced/README.md` |
| 수행한 테스트·실험 | 오케스트레이터 게이트 결과를 인용했다(`review-gates/summary.txt`: `check:architecture`·`check:types`·`lint`·`test:unit` 2,580건·`check:adapter-inventory` 등 모두 exit 0, `test:unit` 로그에 realtime 14파일 231건). 직접 실행: realtime 단위 테스트, 실험 S·P, 변이 16건, `check-realtime-boundaries`·fixture, `check-optional-recipes`(source). 6절에 적었다 |
| 확인하지 못한 범위·이유 | `test:realtime-removal`(heavy lock 대기열이 길어 시작하지 못함, 6.4절). 실제 브라우저·SSE/WS 서버·프록시(환경 없음). 짝 백엔드 실행(읽기만 허용). 여러 클라이언트 재연결 분포(부하 실험 없음). 브라우저에서의 파서·codec 성능. `0929/04-03`·`0929/04-04`는 코드가 그대로라 다시 실험하지 않았다 |
| 이전 리뷰와 비교 가능한 범위 | 지난 발견 8건을 지금 코드와 이번 실행으로 다시 판정했다(2절). 지난 라운드의 실험·변이 결과는 증거로 쓰지 않았다. 변이 R4·R7은 지난 MU4·MU7과 같은 자리에 다시 넣어 돌렸다 |
## 2. 지난 발견 재판정
| 지난 ID | 지난 심각도 | 지금 | 근거 |
| --- | --- | --- | --- |
| 0929/04-01 SSE 네트워크 오류가 `OFFLINE`이 되어 run이 멈춘다 | High · P1 | **고쳐짐** | `4d27b20`이 transport `OFFLINE` 뒤의 `requireOnline()` 두 줄을 지웠다. 지금 online 대기는 환경 신호가 offline일 때만 건다(`reconnect-coordinator.ts:433-462`, `:559-568`). 규칙이 타입 주석(`:112-117`)과 설계 5.3(`:779-785`)에 있다. 막는 테스트: `realtime-reconnect-coordinator.test.ts:2094`(fetch 거절), `:2135`(열린 스트림의 reader 거절), `:2192`(offline 이벤트 앞·뒤). 변이 R1(두 줄 되살림) → 2건 실패. R2(SSE 거절을 `PROVIDER_UNAVAILABLE`로) → 2건 실패. R3(online 복귀 때 elapsed 재시작 삭제) → 3건 실패. 남은 이름 문제는 04-04로 따로 적었다 |
| 0929/04-02 SSE↔reconnect 세션 bridge 부재 | Medium · P2 | **남음**(근거 추가) | 템플릿 도구는 여전히 `readSseForReconnect` 하나다(`fetch-sse-connection.ts:487-504`). 열린 세션 테스트는 생겼지만 bridge는 테스트 파일 안에 있다(`realtime-reconnect-coordinator.test.ts:1762-1803`). **이번에 확인:** 그 bridge는 SSE EOF(서버 정상 종료)를 `PROTOCOL_MISMATCH`/`RECEIVE`/`retryable:false`로 바꿔 run을 끝낸다(`:1791-1798`). 설계 6.3 상태표는 `204`만 "자동 reconnect 금지"로 정하고, `200` 뒤 EOF는 정하지 않는다(`realtime-events-…md:1039-1049`). 백엔드 배포의 정상 종료가 EOF로 온다. 조합자가 유일한 예시를 베끼면 배포 때마다 연결이 끝난다(리뷰어 추론, 실행 미확인) |
| 0929/04-03 SSE `retry:` 처리 규칙이 설계와 다르다 | Low · P3 | **남음** | `sse-parser.ts:330-341` 그대로다. `maxRetryMs`(60s)를 넘는 값을 버린다. 코드가 같아 실험은 다시 하지 않았다 |
| 0929/04-04 hidden 탭에서 heartbeat를 멈춘 조용한 WS | Low · P3 | **남음**(정적) | `heartbeatEligible`(`websocket-connection.ts:182`)에 여전히 주석이 없다. false면 heartbeat를 보내지 않는다(`:1148-1154`) |
| 0929/04-05 CHANGELOG [계약] 문장이 초기화 조건보다 넓다 | Low · P3 | **바뀜** — 닫아도 된다 | 그 문장(`CHANGELOG.md:179`)은 0.2.0 출시 절의 이력이다. 미출시 절의 새 [계약] 행(`:48`)이 지금 규칙을 정확히 적는다 |
| 1101/04-01 결과를 받는 경계마다 동결 규칙이 다르고, 생성 함수가 배럴에 없다 | Medium · P2 | **고쳐짐** | `3fe28de`. 배럴 export(`src/adapters/realtime/index.ts:38`). 엄격한 경계의 타입 주석(`reconnect-coordinator.ts:41-48`, `:94-98`, `:178`, `live-poll-handoff-coordinator.ts:100-104`, `fetch-sse-connection.ts:62-65`, `websocket-connection.ts:161-165`)과 생성 함수 주석(`result.ts:46-53`). 테스트가 배럴로 import한다(`realtime-reconnect-coordinator.test.ts:2238-2330`). 변이 R4(동결 검사 3곳 삭제) → 3건 실패. 남은 한계: 평범한 객체가 여전히 컴파일되고, 오류 이름이 `PROTOCOL_MISMATCH`다. 커밋 본문이 위험으로 적었다 |
| 1101/04-02 `IDLE_TIMEOUT`이 내부 마감에도 쓰인다 | Low · P3 | **고쳐짐** | `1196b86`(stream coordinator), `17fa8d1`(handoff 4곳). 남은 `IDLE_TIMEOUT` 생성 지점은 SSE `RECEIVE`(`fetch-sse-connection.ts:398`), WS `RECEIVE`(`websocket-connection.ts:1171`)·`SUBSCRIBE`(`:1438`)뿐이다. 13.1 표와 같다(`realtime-events-…md:1898`). 변이 D1~D4 모두 검출. 바뀐 점: handoff의 `APPLY_FAILED`는 `retryable:true`, stream coordinator의 것은 `false`다. reconnect coordinator는 `APPLY_FAILED`를 `retryable`과 상관없이 재연결하지 않는다(`reconnect-coordinator.ts:194-200`, `:1590-1597`). 4절 23번에 적었다. CHANGELOG 반영 누락은 04-05 |
| 1101/04-03 WS 구독별 초당 이벤트 상한(256) 테스트·문서 없음 | Low · P3 | **남음** | `tests/`에 `EVENT_RATE_EXCEEDED`를 확인하는 줄이 없다. 설계 11절 상한표(`:1764-1820`)에도 행이 없다. 변이 R7(검사 끄기) 생존 |
1101 README 14.7의 "남긴 것"(`BoundedPollOperationContract`는 "자체 계약이고 V2 HTTP 경로가 아니다")은 04-01에서 다시 판정했다. 실행 경로가 아니라는 말은 맞다. 그러나 필드가 가리키던 원본이 사라져 지금은 아무것도 검사하지 않는다.
## 3. 이번 발견 (36.3)
### 04-01 bounded polling 계약이 지운 V2 행 어휘로 된 자기 선언이라, V3 실행기의 재시도를 막지 못한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험. 인과는 실험으로 확인했다. 제품 조합 코드는 아직 없다 |
| 관련 관점 | 17, 6, 14, 13, 24, 5, 10, 22 |
| 근거 | ① `BoundedPollOperationContract`(`src/application/policies/bounded-polling.ts:35-48`)의 `contractVersion: 2`, `protocol: "REST"`, `semantics: "QUERY"`, `replayPolicy`, `retry: "never"`는 지운 V2 `ApiOperation` 행의 필드다(`12f3bb7^:src/contracts/api-operations.ts:13-16`, `:41-47`). `transportMaxAttempts`·`authRecoveryCount`·`maxCumulativeSleepMs`는 VD-23의 V2 실행 예산이다(`VD-23-…md:379-385`). ② `assertBoundedPollOperation`(`:119-147`)은 선언의 리터럴 값만 본다. API 행(`ApiOperationRow`)이나 descriptor의 실행 정책과 대조하지 않는다. 조정기는 선언을 받고, 실제 요청은 조합 코드의 `execute`가 한다(`bounded-poll-coordinator.ts:97-112`, `:131`, `:303`). ③ V3 실행기는 SAFE·IDEMPOTENT 요청을 `min(retryBudget, maxRetryAttempts, 2)`번 다시 보낸다(상한 `http-execution-v3.ts:894-898`, 네트워크 실패 `:1044-1056`, 재시도 가능 status `:1100-1124`, `http-retry-lifecycle.ts:4-6`, `:21-30`). `create:feature`가 만드는 GET은 `retryBudget: 2`다(`scripts/create-feature.ts:684`). 앱 실행기의 `MAX_RETRY_ATTEMPTS` 기본값도 2다(`src/contracts/env.ts:55`). ④ **실험 P**: 선언(`transportMaxAttempts: 1`, `maxCumulativeSleepMs: 0`)은 검사를 통과한다. `execute`를 V3 실행기에 연결하고 서버가 503만 주게 했다. poll 3회에 실제 요청 9회, 실행기 내부 대기 6번(125·250 ms)이 생겼다. 실행기를 `maxRetryAttempts: 0`으로 만들면 3회다. ⑤ 설계는 이것을 금지한다. "Poll-bound REST transport retry … 끈다"(`realtime-events-…md:777`), "transport retry profile … `NONE`"(`:1612-1615`), "한 attempt는 … 한 physical request"(`:1652-1655`). ⑥ 변이 P1~P4(리터럴 검사 4개 삭제)가 모두 생존한다. 테스트는 `transportMaxAttempts`와 `maxResponseBytes`만 본다(`tests/unit/realtime/bounded-polling-policy.test.ts:59-104`) |
| 발생 조건 | 조합 코드가 poll `execute`를 앱의 V3 실행기와 기본 정책 descriptor로 구현할 때. V2 클라이언트가 지워져 이것이 유일한 HTTP 경로다 |
| 영향 | 서버가 408·429·502·503·504를 낼 때 poll 한 번이 요청 3번이 된다. lease 상한(`maxAttempts` 최대 120)이면 요청 최대 360번이다. 서버가 힘들 때 부하가 커진다. 실행기 안의 재시도는 poll 관측(`ATTEMPT_FINISHED` 1건)에 보이지 않는다. 데이터 손상은 없다. lease 전체 시간 상한은 지켜진다(`awaitWithinLease`) |
| 심각도·우선순위 | Medium · P2. 설계가 금지한 동작이 가장 자연스러운 조합에서 조용히 나온다. 상한(최대 3배)이 있고 제품 조합이 아직 없어 High는 아니다 |
| 통제·증거 | 규칙 명시 M1(설계 5.3·9.2·9.3) · 선언과 실행 정책을 잇는 구현 M0 · 위반 검출 없음. 증거 E1 + E2(실험 P, 변이 P1~P4) |
| 확실성과 남은 가정 | 실험은 리뷰어가 쓴 최소 조합이다. 조합 코드가 poll 전용 실행기(`maxRetryAttempts: 0`)를 쓰면 문제가 없다. 그렇게 하라는 안내는 설계·레시피 문서 어디에도 없다(정적 확인) |
| 결정의 근거 | 확인한 사실: 1101 README 14.7은 이 계약을 "자체 계약"으로 보고 남겼다. 기록된 의도: 설계 9.2는 `operationId`가 "existing API registry의 terminal `QUERY`, `REST`, `SAFE \| IDEMPOTENT`"여야 한다고 적는다(`:1609-1611`). 이 계약은 API 행을 좁혀 옮겨 적는 자리였다. 리뷰어 추론: V2 행이 사라지자 옮겨 적을 원본이 없어졌고, 남은 리터럴은 타입만 맞으면 늘 통과한다. 41절 검토는 5.2절 |
| 이해 비용 | poll을 조립하는 사람은 V2가 없는데 `contractVersion: 2`, `protocol: "REST"`를 적어야 한다. `transportMaxAttempts: 1`을 적으면 실행기도 한 번만 보낸다고 믿기 쉽다. 실제로는 descriptor의 `retryBudget`과 실행기의 `maxRetryAttempts`를 따로 찾아 0으로 맞춰야 한다 |
| 최소 개선 방향 | 계약을 V3 행과 실행 정책에서 만든다. 예: `assertBoundedPollOperation(policy, row: ApiOperationRow, execution: HttpExecutionPolicy)`가 `row.method`(GET·HEAD), `row.retrySemantics`(SAFE·IDEMPOTENT), `execution.retryBudget === 0`, `execution.responseByteLimit`(상한 이하)를 본다. V2 리터럴 필드(`contractVersion`, `protocol`, `semantics`, `replayPolicy`, `retry`, `authRecoveryCount`)는 지운다. V3에는 401 재전송이 없다(1101 README 14.7 표) |
| 대안 비교 | 5.2절. (a) 현상 유지 (b) V3 행·정책에서 검사(제안) (c) 템플릿이 poll 전용 실행기 래퍼를 제공 (d) 문서에 "poll 실행기는 `maxRetryAttempts: 0`"만 적기 |
| 단순화의 보존 조건 | lease 상한(시도·시간·바이트), terminal state 검사, `definePollLeasePolicy` 검증, `execute`가 받는 `maxResponseBytes`를 유지한다 |
| 비용·부작용 | 공개 타입이 바뀐다(BREAKING). repo 안 소비자는 없다. 테스트 2파일을 고친다. 레시피 번들 여유는 1,343 B다(6.1절) |
| 재검토 조건 | V3 실행기가 호출마다 재시도를 끄는 입력을 받게 되면 (c)로 줄일 수 있다 |
| 완료 기준 | `retryBudget > 0`인 descriptor를 poll에 묶으면 조립 때 거절된다. 실험 P와 같은 조합에서 poll 3회가 요청 3회다 |
| 검증 방법 | 실험 P를 테스트로 옮긴다. `retryBudget` 검사를 지우는 변이가 그 테스트에서 실패하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 04-02 짝 백엔드의 실시간 출구와 프론트 realtime의 전송 규약이 맞지 않고, 어디에도 적혀 있지 않다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험(두 템플릿 사이 공백). 양쪽 코드를 읽어 확인했다. 실제 연결은 실행하지 않았다 |
| 관련 관점 | 17, 3, 20, 5, 18 (+30.6, 30.8) |
| 근거 | **프론트**: SSE는 `Accept: text/event-stream`으로 요청하고(`fetch-sse-connection.ts:196`) content type이 정확히 `text/event-stream`이어야 한다(`:572`). 이벤트는 `REALTIME_EVENT_V1` envelope(streamEpoch, sequence, eventId, scopeBinding, recoveryMode, resumeCursor)이어야 한다(설계 4.2). WebSocket은 협상된 subprotocol이 정확히 `realtime.v1`이어야 한다(`websocket-connection.ts:310`, `websocket-protocol.ts:5`). **짝 백엔드**: 실시간 출구는 STOMP-over-SockJS 채널(`/ws`, `/topic/events`, 세션당 구독 1개, `Map<String, String>` 투영)과 raw WebSocket 라이브러리 API다(`clean-architecture-backend-template/src/adapter/inbound/websocket/README.md:7-12`, `:17-31`). simple broker는 재전송·영속이 없다(같은 파일 "한계" 절). subprotocol 협상 코드는 없다(`src/adapter/inbound/websocket/src/main`에서 `setSupportedProtocols`·`Sec-WebSocket-Protocol` 0건). 스트리밍은 NDJSON·JSON text sequence writer뿐이다(`src/adapter/inbound/web-advanced/README.md:28-29`). SSE 상수(`StreamMediaType.SSE`)는 OpenAPI 생성기에서만 쓴다(`WebOpenApi32Generator.java:33`). **문서**: 프론트 repo에 STOMP·SockJS 언급이 없다. 설계 상태표는 "제품 realtime delivery: backend/provider 계약 승인 후 선택"이라고만 적는다(`realtime-events-…md:74`). `desktop-server-git/design-docs/`에도 realtime 대응 문서가 없다 |
| 발생 조건 | 짝 템플릿으로 실시간 갱신(알림, 목록 무효화)이 필요한 기능을 만들 때 |
| 영향 | 프론트 SSE·WS 어댑터는 짝 백엔드 어느 출구와도 연결되지 않는다. 백엔드 STOMP에 붙이면 subprotocol 불일치로 `PROTOCOL_MISMATCH`가 난다(리뷰어 추론, 실행 미확인). 개발자는 (a) 백엔드에 `REALTIME_EVENT_V1` SSE 또는 `realtime.v1` WS 서버를 쓰거나 (b) 프론트에 STOMP transport를 쓴다. 백엔드 STOMP는 sequence·재전송이 없어 `AUTHORITATIVE_DELTA` stream은 쓸 수 없고, `INVALIDATION_HINT` + snapshot 복구만 가능하다(설계 4.5 `:686` "backend가 replay를 제공하지 않으면") |
| 심각도·우선순위 | Medium · P2. 기본 조합에는 realtime이 없어 지금 깨진 기능은 없다. 실시간이 필요한 제품에는 출시 전에 정해야 하는 차단 항목(P1)이 된다 |
| 통제·증거 | 대응 규칙 M0(어느 문서에도 없음) · E1(두 repo 정적 확인) |
| 확실성과 남은 가정 | 백엔드는 읽기만 했다. 백엔드 서비스 코드가 raw handler로 `realtime.v1`을 구현할 수는 있다. 그 예시는 없다 |
| 결정의 근거 | 41절 적용. 고를 길이 셋이다. (a) 백엔드에 SSE writer + `REALTIME_EVENT_V1`: 프론트 어댑터를 그대로 쓰고 cursor 복구까지 간다. 백엔드에 replay 저장소가 필요하다. (b) 프론트에 STOMP transport: 백엔드는 그대로다. 프론트는 sequence 없는 hint만 받으므로 stream coordinator의 gap·cursor 기능을 못 쓴다. (c) 실시간 없이 bounded polling: 둘 다 그대로다. 04-01을 먼저 고쳐야 한다. 리뷰어는 고르지 않는다. 선택은 사용자 결정이다 |
| 이해 비용 | 채택자가 두 repo의 realtime 문서와 코드를 다 읽어야 불일치를 안다 |
| 최소 개선 방향 | `desktop-server-git/design-docs/`에 "실시간: 짝 백엔드 출구 ↔ 프론트 transport 대응표" 한 절을 둔다. 지금 바로 되는 조합(없음), 각 선택지에서 새로 쓸 것, 권장 경로를 적는다. 프론트 `optional-adapter-recipes.md` Realtime 절에서 링크한다 |
| 대안 비교 | 위 결정의 근거 (a)~(c). 문서 없이 두는 현상 유지는 채택자가 매번 같은 조사를 한다 |
| 단순화의 보존 조건 | 적용 제외 — 기존 계약을 줄이는 제안이 아니다 |
| 비용·부작용 | 문서 1절. 코드 선택은 별도 결정 |
| 재검토 조건 | 백엔드에 SSE writer가 생기거나 프론트에 STOMP transport가 생기면 표를 고친다 |
| 완료 기준 | 채택자가 두 repo를 읽지 않고 대응표 하나로 "지금 연결되는 조합"과 "새로 쓸 것"을 안다 |
| 검증 방법 | 문서 리뷰. 고른 경로가 생기면 로컬 서버 + 브라우저 실행으로 확인(설계 15.3) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 04-03 realtime snapshot 바인딩 검사는 같은 것을 지키지만, 막는 테스트가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험(테스트 공백) |
| 관련 관점 | 10, 17, 21, 3 |
| 근거 | ① 지금 검사: snapshot operation이 있고 `method === "GET"`이고 `retrySemantics`가 SAFE·IDEMPOTENT다(`src/contracts/realtime-streams.ts:457-474`). V2 때는 `contractVersion === 2`, `protocol === "REST"`, `semantics === "QUERY"`, `replayPolicy` SAFE·IDEMPOTENT였다(`12f3bb7` diff). V2 `QUERY`는 GET·HEAD에 SAFE·IDEMPOTENT만 허용했다(`12f3bb7^:src/contracts/api-operations.ts:191-201`). ② **실험 S**(V3 descriptor를 실제로 조립하고 `projectApiOperationRows`로 뽑은 행을 넣음, 3 method × 4 retrySemantics + 없는 id): 받아들이는 조합은 GET×SAFE, GET×IDEMPOTENT 둘뿐이다. V2 규칙과 비교하면 HEAD 두 조합만 새로 거절된다. HEAD는 checkpoint 본문을 줄 수 없으므로 의도와 맞다. ③ V3 조립은 GET×KEYED, GET×NEVER, HEAD, POST×SAFE도 통과시킨다(`external-contract-runtime.ts:503-528`). 그래서 이 검사가 realtime 쪽 유일한 문이다. ④ `protocol`·`contractVersion` 조건이 빠진 것은 손실이 아니다. V3 행에는 HTTP descriptor만 있고 Browser RPC는 따로 등록한다. ⑤ **변이** S1(method 조건 삭제), S2(retrySemantics 조건 삭제), S3(operation 조건 전체 삭제)이 모두 생존한다. `realtime-stream-registry.test.ts`에는 snapshot 거절 사례가 없다. fixture 행은 손으로 쓴 객체다(`tests/unit/realtime/fixture.ts:105-118`) |
| 발생 조건 | 이 검사를 고치거나 V3 행 필드 이름이 바뀌는 변경 |
| 영향 | 검사가 약해져도 CI가 모른다. 그러면 state-bearing stream이 POST나 NEVER operation을 복구용 snapshot으로 등록할 수 있다. 복구 때 쓰기를 다시 실행하게 된다 |
| 심각도·우선순위 | Low · P3. 지금 코드는 맞다(실험 S). 회귀 탐지 공백이다 |
| 통제·증거 | M2(구현) · 위반 검출 없음(S1~S3 생존) · E2(실험 S, 변이) |
| 확실성과 남은 가정 | 실험과 변이로 확인했다 |
| 결정의 근거 | 적용 제외 — 기존 검사에 테스트를 붙이는 문제다. 검사 모양 자체는 5.1절에서 봤다 |
| 이해 비용 | 이 검사를 바꾸는 사람이 테스트로 의미를 확인할 수 없다 |
| 최소 개선 방향 | `realtime-stream-registry.test.ts`에 실험 S의 표를 테스트로 옮긴다. 행은 `composeContractContributions` + `projectApiOperationRows`로 만든다. 그러면 행 projection이 바뀔 때도 함께 잡힌다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1건(표 13행) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | S1~S3이 모두 실패한다 |
| 검증 방법 | 변이 S1~S3 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 04-04 서버만 끊긴 실패의 이름이 transport마다 다르고, 13.1 표가 바뀐 재시도 규칙과 맞지 않는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(어휘 불일치) |
| 관련 관점 | 24, 23, 17, 7, 8, 9 |
| 근거 | ① 같은 "서버에 닿지 않음"을 SSE는 `OFFLINE`(fetch 거절 `fetch-sse-connection.ts:217-221`, reader 거절 `:400-405`), polling은 executor 거절을 `OFFLINE`(`bounded-poll-coordinator.ts:316-323`), WebSocket은 `PROVIDER_UNAVAILABLE`(`websocket-connection.ts:431-441`)로 부른다. ② `4d27b20` 뒤 reconnect coordinator는 transport `OFFLINE`을 backoff로 재시도한다. 예산을 다 쓰면 브라우저가 online인데도 `OFFLINE`으로 끝난다. 테스트가 이 값을 고정한다(`realtime-reconnect-coordinator.test.ts:2121-2124`, `:2176-2179`). ③ polling은 `OFFLINE`을 재시도 대상으로 보지 않는다(`bounded-poll-coordinator.ts:116-121`). executor가 한 번 던지면 lease가 바로 끝난다(`:380-393`). ④ 13.1 표의 `OFFLINE` 행은 "network hint/attempt failure → online hint 뒤 bounded check"다(`realtime-events-…md:1896`). 5.3은 transport `OFFLINE`을 online 대기 없이 재시도한다고 고쳤다(`:783-785`). 두 절이 다른 말을 한다. ⑤ 사용자 문구는 failure kind로 고른다(`:1923`). 같은 서버 장애가 SSE에서는 "오프라인", WS에서는 "서비스 이용 불가"로 보일 수 있다 |
| 발생 조건 | 브라우저 네트워크는 정상이고 서버·프록시만 닿지 않을 때 |
| 영향 | 조합 코드와 화면이 kind로 원인을 판단하면 SSE에서는 기기 문제로, WS에서는 서버 문제로 본다. "OFFLINE이면 online 이벤트를 기다렸다 다시 run"이라는 조합 코드는 다시 멈춘다. 0929/04-01과 같은 모양이 조합 쪽으로 옮겨 간 것이다(리뷰어 추론). 데이터 손상은 없다 |
| 심각도·우선순위 | Low · P3. coordinator 안의 멈춤은 고쳐졌다. 진단과 조합 판단을 헷갈리게 하는 문제다 |
| 통제·증거 | M1(5.3은 맞고 13.1은 다름) · E1 + E2(테스트가 `OFFLINE` 고정) |
| 확실성과 남은 가정 | 코드와 테스트로 확인했다. 화면 문구는 조합이 없어 미확인이다 |
| 결정의 근거 | `4d27b20`은 SSE 어휘를 바꾸는 안(지난 라운드 (c))을 버렸다. 이유는 "OFFLINE을 보고 화면에 '오프라인'을 띄우는 소비자의 분류도 바뀐다"였다. 리뷰어 판단: 서버 장애에 "오프라인"을 띄우는 것이 바로 고칠 대상이다. 41절 검토는 5.3절 |
| 이해 비용 | 조합자는 `OFFLINE`이 "기기 offline"인지 "서버에 닿지 않음"인지 kind만으로 알 수 없다. `navigator.onLine`을 따로 봐야 한다 |
| 최소 개선 방향 | 둘 중 하나. (a) SSE·polling의 네트워크 거절을 `PROVIDER_UNAVAILABLE`로 바꾸고 테스트 기대값 2곳과 polling 테스트를 고친다. `OFFLINE`은 환경 신호에서만 나온다. (b) 코드는 두고 13.1 `OFFLINE` 행을 "환경 offline: online 뒤 재시도 / transport 보고: backoff 재시도, online 상태에서도 나올 수 있음" 두 줄로 고친다 |
| 대안 비교 | 5.3절 |
| 단순화의 보존 조건 | 환경 offline 동안 타이머 없음, online 복귀 때 elapsed 재시작(R3가 잡는 테스트), 시도 상한 |
| 비용·부작용 | (a) 공개 결과 kind가 바뀐다([계약]). 코드 3곳, 테스트 몇 건. (b) 문서 1행 |
| 재검토 조건 | 실제 reachability 확인(가벼운 health 요청)을 환경 신호로 쓰게 되면 다시 본다 |
| 완료 기준 | 서버만 끊긴 경우 세 transport가 같은 kind로 끝나거나, 13.1이 두 뜻을 정확히 적는다 |
| 검증 방법 | (a)면 X1·X2 테스트 기대값과 WS 대응 테스트 비교. (b)면 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 04-05 CHANGELOG에 handoff 결과 kind 변경(`17fa8d1`)의 [계약] 행이 없고, "알려진 제한"이 고쳐진 것을 남은 것으로 적는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(문서) |
| 관련 관점 | 9, 17, 5 (+30.4) |
| 근거 | `17fa8d1`은 배럴로 공개된 handoff coordinator 결과의 kind를 바꿨다. 커밋 본문도 "배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다"고 위험에 적었다. 바꾼 파일은 설계 문서·코드·테스트 3개이고 CHANGELOG는 없다(`git show --stat 17fa8d1`). CHANGELOG [계약] 행은 stream coordinator만 적는다(`CHANGELOG.md:85`). "알려진 제한"은 아직 "handoff coordinator의 마감 4곳은 `IDLE_TIMEOUT`"이라고 적는다(`:136`). 작업 브랜치 끝(`8c39e77`)에서도 같다. 합치기 문제가 아니라 원 커밋에서 빠졌다 |
| 발생 조건 | 복사한 프로젝트가 CHANGELOG로 가져올 수정을 고를 때(`CHANGELOG.md:3`) |
| 영향 | handoff 결과를 `IDLE_TIMEOUT`으로 보던 조합 코드가 바뀐 것을 모른다. 이미 고친 문제를 남은 문제로 읽는다 |
| 심각도·우선순위 | Low · P3. 이 템플릿으로 handoff를 조합한 소비자는 아직 없다 |
| 통제·증거 | M1 · 누락 검출 없음 · E1 |
| 확실성과 남은 가정 | 확인한 사실이다 |
| 결정의 근거 | 적용 제외 — 기록 누락이다 |
| 이해 비용 | 소비자가 커밋 로그를 직접 읽어야 한다 |
| 최소 개선 방향 | 미출시 절에 [계약] 행 하나("live-poll handoff 마감 실패가 `APPLY_FAILED`/`RECOVER`(retryable), `PROVIDER_UNAVAILABLE`/`RECOVER`·`CLOSE`로 나온다 (1101/04-02) · `17fa8d1`")를 더하고 `:136`을 지운다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 2줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | CHANGELOG가 handoff kind 변경을 [계약]으로 적고, 알려진 제한에 그 줄이 없다 |
| 검증 방법 | 문서 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 04-06 V2 삭제 뒤 realtime 레지스트리의 codec·mapper 바인딩을 기능이 채울 자리가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 개선 제안(확장 지점 부재) |
| 관련 관점 | 3, 20, 22, 17 (+30.7, 32.4) |
| 근거 | ① realtime 레지스트리는 `schemaCodecs`·`mappers`·`apiOperations` 세 바인딩을 받는다(`realtime-streams.ts:105-113`). event type과 checkpoint를 여기서 대조한다(`:317-321`, `:468-469`). ② `12f3bb7`이 기능의 `runtimeSchemas`·`mappers` 칸과 `RUNTIME_SCHEMA_CODECS`·`MAPPER_REGISTRY`를 지웠다. 지금 기능은 `schemas`·`adapters`·`contractContributions`만 낸다(`src/features/feature-module.ts:51-65`). 조립은 스키마 레지스트리·contribution·API 행만 만든다(`src/features/installed-feature-runtime-registries.ts:28-74`). 세 바인딩 중 `apiOperations`만 출처가 있다. ③ V3 contribution의 `events`(`external-contract-runtime.ts:259`)는 payload 검증기를 갖지만 src 안에서 읽는 곳이 없다. realtime event type은 따로 `payloadSchemaId`·`mapperId`를 적는다. 둘을 잇는 코드가 없다. ④ 검증기에서 codec을 만드는 함수는 있다(`runtimeSchemaCodecFromValidator`, `schema-registry.ts:38-55`). mapper를 낼 칸은 없다. 레시피 문서는 "제품 feature는 이 runtime에 schema/codec/query … 주입"이라고만 적는다(`optional-adapter-recipes.md:47-49`) |
| 발생 조건 | 채택 프로젝트가 realtime을 조합할 때 |
| 영향 | 조합자가 codec·mapper 레지스트리를 새로 만들어야 한다. 같은 이벤트를 V3 `events`와 realtime event type 두 곳에 적게 되면 갈라질 수 있다 |
| 심각도·우선순위 | Low · P3. 기능 결함은 없다. 조합 비용과 미래 중복 위험이다 |
| 통제·증거 | M0(출처 규칙 없음) · E1 |
| 확실성과 남은 가정 | V2 때도 realtime이 이 레지스트리를 쓰라는 문서는 없었다. 삭제가 기존 사용처를 깬 것은 아니다 |
| 결정의 근거 | 템플릿 전제상 빈 레지스트리는 확장 지점이다. 여기는 레지스트리 자리 자체가 없다. 41절: (a) 현상 유지(조합자가 정함) (b) realtime event type을 V3 `events`에서 뽑기(codec은 `payloadValidator`로) (c) 기능에 `realtimeMappers` 칸 추가. 리뷰어는 04-02의 경로 선택 뒤에 정하기를 권한다. STOMP hint 경로면 이 바인딩 일부가 필요 없을 수 있다 |
| 이해 비용 | 조합자가 codec·mapper가 어디서 오는지 설계 문서에서 찾을 수 없다 |
| 최소 개선 방향 | 레시피 Realtime 절에 세 바인딩의 출처를 한 줄씩 적는다(`apiOperations`: `projectApiOperationRows`, codec: `runtimeSchemaCodecFromValidator`, mapper: 조합 코드). 코드 변경은 04-02 결정 뒤 |
| 대안 비교 | 위 (a)~(c) |
| 단순화의 보존 조건 | event type의 payload 스키마·mapper 대조(`realtime-streams.ts:317-321`)를 유지 |
| 비용·부작용 | 문서 3줄. (b)·(c)는 공개 계약 변경 |
| 재검토 조건 | 첫 제품이 realtime을 조합할 때 |
| 완료 기준 | 조합자가 세 바인딩의 출처를 문서 한 곳에서 안다 |
| 검증 방법 | 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 realtime 231건 통과 | O. 상태 기계·terminal close가 유지된다 |
| 2 | 구조적 성숙도 | 적용 | M4 / M4 | E2 `check:architecture` exit 0(게이트), realtime boundaries PASS·fixture 2규칙 거절(직접) | O |
| 3 | 변경 용이성 | 적용 | M2 / M1 | E1 | P. poll 조립에 V2 리터럴(04-01), codec·mapper 출처 없음(04-06), SSE bridge 직접 작성(0929/04-02) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P. `runLoop` 약 670줄 그대로. `contractVersion: 2` 같은 사라진 개념을 알아야 한다 |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 동결 규칙이 주석에 생겼다(1101/04-01 고쳐짐). poll 선언이 실행기 재시도를 숨긴다(04-01) |
| 6 | 실패 성숙도 | 적용(깊게) | M3 / M3 일부 | E2 R1~R3·D1~D4 검출 | P. 멈춤이 풀렸고 마감 kind가 정리됐다. EOF 분류 미정(0929/04-02), poll 요청 3배(04-01) |
| 7 | 운영 성숙도 | 적용(깊게) | M2 / M2 | E1·E2 | P. effect 마감과 전송 idle을 관측에서 나눈다. 서버 끊김 kind가 transport마다 다르다(04-04). 실행기 내부 재시도가 poll 관측에 안 보인다(04-01) |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1 | P. 동결 누락이 여전히 `PROTOCOL_MISMATCH`로 보인다(1101/04-01 남은 한계). 13.1 `OFFLINE` 행이 실제와 다르다(04-04) |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. CHANGELOG 누락(04-05). 설계 5.3의 줄 번호가 밀렸다(`reconnect-coordinator.ts:553-562` → 지금 `:556-568`, `:1579-1590` → `:1590-1597`). 설계 5.3·9.2·9.3이 V2 어휘다(04-01) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3 일부 | E2 변이 16건 중 8건 검출 | P. 생존 8건: S1~S3(04-03), P1~P4(04-01), R7(1101/04-03). 지난 라운드에 고친 것은 모두 잡힌다 |
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E2 | O. cursor는 effect 성공 뒤에만 전진한다. 이번 커밋들이 바꾸지 않았다 |
| 12 | 동시성 성숙도 | 적용(깊게) | M3 / M3 | E2 | O. run 1개, recovery single-flight, DRAINING·generation fence. 영역 diff는 kind 이름만 바꿨고 fence 테스트가 통과한다 |
| 13 | 확장성 | 적용(깊게) | M3 / M2 | E2 | P. 큐·dedupe·크기 상한은 유지된다. WS rate 상한 테스트 없음(1101/04-03). poll이 실행기 재시도로 최대 3배(04-01) |
| 14 | 성능 성숙도 | 적용(깊게) | M2 / M2 | E2 레시피 번들 40,857 / 42,200 gzip B | P. production 번들에는 들어가지 않는다. 브라우저 실행 성능은 미측정 |
| 15 | 보안 성숙도 | 적용 | M4 / M4 | E1 | O. 고정 same-origin HTTPS, URL credential 없음. 이번에 바뀐 곳 없음 |
| 16 | 의존성 성숙도 | 적용 | M3 / M3 | E2 boundaries PASS | O. 외부 패키지 없음 |
| 17 | API / Contract 성숙도 | 적용(깊게) | M3 / M2 | E1·E2 | P. snapshot 바인딩은 같은 것을 지키나 테스트 없음(04-03). poll 계약이 V2 어휘(04-01). 짝 백엔드 불일치(04-02). `OFFLINE` 두 뜻(04-04) |
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P. 새 이벤트 종류는 구버전 탭에서 `REGISTRY`로 드러난다. 백엔드 배포의 SSE EOF를 재연결할지 미정(0929/04-02) |
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P. `MAX_RETRY_ATTEMPTS` 기본 2가 poll에도 걸린다(04-01). 파서 `maxRetryMs`와 정책 `maxDelayMs`가 따로 논다(0929/04-03) |
| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | P. 배럴만으로 결과를 만들 수 있다(고쳐짐). SSE bridge 예시는 테스트 안에만 있다. 짝 백엔드 대응표가 없다(04-02) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 일부 | E2 | P. boundaries·architecture·레시피 예산 게이트 PASS. poll 선언과 실행 정책을 잇는 검사 없음(04-01) |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P. attempt/session 경계는 transport를 잘 숨긴다. poll 계약 추상화가 실행기와 끊겼다(04-01). V3 `events`와 realtime event type이 따로다(04-06) |
| 23 | 일관성 | 적용 | M2 / M1 | E1 | P. 서버 끊김 `OFFLINE`/`PROVIDER_UNAVAILABLE`(04-04). `APPLY_FAILED`의 `retryable`이 handoff는 true, stream은 false이고 reconnect는 이 값을 보지 않는다(2절 1101/04-02) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P. `contractVersion: 2`가 지운 버전을 가리킨다(04-01). `OFFLINE`(04-04) |
| 25 | 조직 확장성 | 적용 제외 — 작성자 1인 | - | - | -. registry `owner` 필드가 필수인 것만 확인 |
| 26 | Ownership 성숙도 | 적용 제외 — 제품 조합 없음 | - | - | -. recipe owner는 `project-owner-required` |
| 27 | 삭제 가능성 | 적용 | M3 / 미확인 | E1(제거 경로 목록과 import 방향만 정적 확인) | ?. `test:realtime-removal`을 heavy lock 대기로 실행하지 못했다(6.4절). 세 라운드째 미검증이다 |
| 28 | 회복 가능성 | 적용 | M3 / M3 일부 | E2 | P. 서버 끊김 뒤 재연결로 회복한다(0929/04-01 고쳐짐). gap·cursor 만료 뒤 snapshot 복구는 유지된다. EOF 뒤 회복은 조합 코드가 정한다(0929/04-02) |
## 5. 설계 선택 검토 (41절)
### 5.1 snapshot 바인딩을 뽑은 행(`ApiOperationRow`)으로 검사한다 (렌즈 ①, 04-03)
1. **무엇이 필요한가:** state-bearing stream의 복구가 가리키는 operation은 여러 번 불러도 안전한 조회여야 한다.
2. **지킬 성질:** 그 operation이 있다. 본문 없는 읽기다. 재전송해도 안전하다(SAFE·IDEMPOTENT).
3. **현재 보장:** `GET` + SAFE·IDEMPOTENT(`realtime-streams.ts:470-472`). V3 조립이 GET의 요청 본문과 command descriptor를 막는다(`external-contract-runtime.ts:503-511`). 실험 S로 받는 조합이 둘뿐임을 확인했다. **보장하지 않는 것:** 응답 본문이 있는지(`responseBody: "NONE"`인 GET도 통과, V2 때도 같음). checkpoint codec과 응답 스키마의 관계. 실행 정책(`retryBudget`)은 행에 없다.
4. **대안:** (a) 현재 (b) `responseBody === "REQUIRED_JSON"`을 더함 (c) 행 대신 descriptor를 바인딩으로 받음 (d) `checkpointCodecId === responseSchema`를 요구.
5. **비교:** (b)는 한 줄이고 본문 없는 snapshot을 막는다. (c)는 실행 정책까지 보지만 realtime 계약이 HTTP 실행 타입에 묶인다. 지금 행은 `check:registries`가 보는 FE-REG-API와 같은 원본이라, 거버넌스와 realtime이 같은 사실을 본다. (d)는 과하다. checkpoint는 Envelope의 `data`이거나 응답 일부일 수 있다. 설계도 그 관계를 정하지 않는다.
6. **현재 조건에서의 판단:** (a)를 유지하고 테스트를 붙인다(04-03). (b)는 선택이다.
7. **재검토 조건:** snapshot 실행을 템플릿 코드가 하게 되면(지금은 조합 코드) (c)를 다시 본다.
### 5.2 bounded poll operation을 선언으로 받는다 (렌즈 ②, 04-01)
1. **무엇이 필요한가:** poll 한 attempt는 실제 요청 한 번이어야 한다. 실행기 안의 재시도·대기가 lease 예산을 우회하면 안 된다(설계 9.3).
2. **지킬 성질:** poll에 묶인 operation은 재전송 안전한 조회이고, 실행기가 그 요청을 다시 보내지 않는다.
3. **현재 보장:** 선언 리터럴과 policy의 `operationId` 일치만 본다(`bounded-polling.ts:119-147`). **보장하지 않는 것:** 선언과 실제 descriptor·실행기의 일치. V3 실행기는 기본값에서 2번 더 보낸다(실험 P).
4. **대안:** (a) 현상 유지 (b) V3 행·실행 정책을 받아 검사 (c) 템플릿이 poll 전용 실행기 래퍼(`maxRetryAttempts: 0`)를 제공 (d) 문서만.
5. **비교:** (a)는 V2 어휘가 남고 실험 P의 3배가 그대로다. (b)는 공개 타입이 바뀌지만 조립 때 거절되고, 지운 V2 필드 6개가 사라져 읽기 쉬워진다. (c)는 행 검사가 없어 operation 종류(GET·SAFE)는 여전히 선언에 기댄다. (d)는 비용이 0이지만 검출이 없다.
6. **현재 조건에서의 판단:** 기록된 의도는 API 행을 옮겨 적는 것이었다(설계 9.2). 그 원본이 사라졌으니 (b)가 맞다. (c)는 (b)와 같이 쓸 수 있다.
7. **재검토 조건:** V3 실행기가 호출마다 재시도를 끄는 입력을 받게 되면 (c)만으로 충분한지 다시 본다.
### 5.3 서버만 끊긴 실패를 coordinator에서 처리하고 transport 어휘는 두었다 (렌즈 ③, 04-04)
1. **무엇이 필요한가:** 기기가 정말 offline이면 헛된 재시도를 하지 않는다. 서버만 끊기면 제한된 재연결을 하고, 끝나면 원인을 알 수 있는 결과를 돌려준다.
2. **지킬 성질:** 어떤 실패 뒤에도 run은 재시도하거나 끝난다. 결과 kind는 원인을 가리킨다.
3. **현재 보장:** 첫 성질은 지킨다(R1~R3 검출). **보장하지 않는 것:** 두 번째 성질. SSE·polling은 서버 끊김을 `OFFLINE`, WS는 `PROVIDER_UNAVAILABLE`로 끝낸다.
4. **대안:** (a) 현재(`4d27b20`의 수정안 b) (b) (a) + SSE·polling 어휘를 `PROVIDER_UNAVAILABLE`로 (c) (a) + 13.1 문서만 고침.
5. **비교:** (b)는 세 transport가 같은 말을 하고 `OFFLINE`이 환경 신호 하나에서만 나온다. 공개 kind가 바뀌고 테스트 기대값 몇 건을 고친다. (c)는 비용이 작지만 조합자가 `navigator.onLine`을 따로 봐야 한다.
6. **현재 조건에서의 판단:** coordinator 한 곳에서 멈춤을 고친 `4d27b20`의 선택은 맞다. 다른 transport나 조합 코드가 `OFFLINE`을 내도 멈추지 않는다. 어휘는 별개 문제이고, 운영 중인 제품이 없는 지금 (b)가 가장 싸다.
7. **재검토 조건:** 실제 reachability 확인을 환경 신호로 쓰게 되면 `OFFLINE`의 정의를 다시 본다.
## 6. 실험·변이 기록
환경: 분리 worktree(`e40684b`), `node scripts/run-vitest.ts`, 호스트 부하 15~64(다른 리뷰어와 공유). 실험 파일과 스크립트·결과는 오케스트레이터 scratchpad `r04-1103/`에 있다(`zz-review04-1103.test.ts`, `mutate.py`, `exp.jsonl`, `mutation-results.jsonl`). worktree에는 남기지 않았다.
### 6.1 기본 실행
| 명령 | 결과 |
| --- | --- |
| `node scripts/run-vitest.ts run tests/unit/realtime/` | 14파일 231건 통과, 1.73초(직전 부하 15) |
| 변이용 묶음(realtime + `contract-snapshot-bypass` + `api-operation-rows`) | 16파일 244건 통과, 4.5초 |
| `node scripts/check-realtime-boundaries.ts` / `check-realtime-boundary-fixtures.ts` | PASS / PASS(금지 규칙 2건 거절) |
| `flock … node scripts/check-optional-recipes.ts` | PASS. realtime 40,857 / 42,200 gzip B(여유 1,343). 크기 측정이라 부하 영향 없음 |
| `flock … corepack pnpm test:realtime-removal` | 실행 못 함(6.4절) |
### 6.2 실험 S — snapshot 바인딩(렌즈 ①)
V3 descriptor(`TEST_LIST_HTTP_CONTRACT`·`TEST_CREATE_HTTP_CONTRACT` 변형)를 `composeContractContributions`로 조립하고 `projectApiOperationRows`로 뽑은 행을 `createRealtimePolicyRegistry`에 넣었다. CURSOR 복구, state-bearing event.
| method | SAFE | IDEMPOTENT | KEYED | NEVER |
| --- | --- | --- | --- | --- |
| GET | 받음 (V2 받음) | 받음 (V2 받음) | 거절 (V2 거절) | 거절 (V2 거절) |
| HEAD | **거절 (V2 받음)** | **거절 (V2 받음)** | 거절 | 거절 |
| POST | 거절 | 거절 | 거절 | 거절 |
- 12조합 모두 V3 조립은 통과했다. realtime 검사가 유일한 문이다.
- 없는 operation id → 거절. `responseBody: "NONE"`인 GET×SAFE → 받음(V2 때도 검사하지 않음).
### 6.3 실험 P — poll + V3 실행기(렌즈 ②)
`createBoundedPollCoordinator` + V2 어휘 선언(검사 통과) + `execute`가 `createContractHttpExecutor`로 `TEST_LIST_HTTP_CONTRACT`(GET, SAFE, `retryBudget: 2`)를 부른다. fetcher는 항상 503(problem+json, Retry-After 없음). poll `maxAttempts: 3`. 가짜 clock, 실행기 `sleep`은 즉시 끝나는 함수로 주입.
| 실행기 `maxRetryAttempts` | poll 시도 | 실제 요청 | 실행기 내부 대기 | 결과 |
| --- | --- | --- | --- | --- |
| 2 (앱 기본값) | 3 | **9** | 6번(125, 250 ms × 3) | `POLL_BUDGET_EXHAUSTED` |
| 0 | 3 | 3 | 0 | `POLL_BUDGET_EXHAUSTED` |
### 6.4 `test:realtime-removal`
**실행하지 못했다(미검증).** `flock … corepack pnpm test:realtime-removal`을 23:17에 걸었다. 23:30까지 heavy lock 대기열에 다른 리뷰어의 작업 10개가 있어 시작하지 못했다. 이 드릴은 fixture 복사본에서 `check:types`·`lint`·`check:architecture`·`test:all`·`build`·`check:optional-recipes:source`·`check:ci`를 모두 돈다(`scripts/test-realtime-runtime-removal.ts:125-131`). 대기를 끊고 미검증으로 남긴다. 오케스트레이터 게이트 목록(`summary.txt`)에도 이 명령은 없다. 지난 두 라운드도 돌리지 못했다. 확인하려면 대기열이 빈 뒤 메인 작업 트리에서 `corepack pnpm test:realtime-removal` 한 번이면 된다.
정적으로 본 것: 드릴이 지우는 경로 목록(`:24-34`)에 이번 라운드에 바뀐 `src/contracts/realtime-streams.ts`·`bounded-polling.ts`가 들어 있다. `realtime-streams.ts`가 import하는 `api-operations.ts`는 지우지 않는 쪽이다. 방향은 realtime → contracts 한쪽이라 제거를 막는 역방향 import는 보이지 않는다(정적 확인, E1).
### 6.5 변이
한 건씩 넣고 6.1의 변이용 묶음(244건)을 돌린 뒤 원본으로 되돌렸다. 16건 중 8건 검출, 8건 생존.
| ID | 렌즈·발견 | 변이 | 결과 |
| --- | --- | --- | --- |
| S1 | ① 04-03 | snapshot 검사에서 `method === "GET"` 삭제 | **생존** |
| S2 | ① 04-03 | `retrySemantics` SAFE·IDEMPOTENT 조건 삭제 | **생존** |
| S3 | ① 04-03 | operation 조건 전체 삭제(없는 id도 통과) | **생존** |
| P1 | ② 04-01 | `contractVersion !== 2` 삭제 | **생존** |
| P2 | ② 04-01 | `replayPolicy` 조건 삭제 | **생존** |
| P3 | ② 04-01 | `retry !== "never"` 삭제 | **생존** |
| P4 | ② 04-01 | method(GET·HEAD) 조건 삭제 | **생존** |
| R1 | ③ 0929/04-01 | transport `OFFLINE` 뒤 `requireOnline()` 두 줄 되살림 | 검출(2건) |
| R2 | ③ 0929/04-01 | SSE 거절 2곳을 `PROVIDER_UNAVAILABLE`로 | 검출(2건) |
| R3 | ③ | online 복귀 때 elapsed 재시작 삭제(`reconnect-coordinator.ts:568`) | 검출(3건) |
| R4 | 1101/04-01 | reconnect 동결 검사 3곳 삭제 | 검출(3건) |
| R7 | 1101/04-03 | WS 초당 이벤트 상한 끔 | **생존** |
| D1 | ③ 1101/04-02 | stream effect 마감을 `IDLE_TIMEOUT`으로 | 검출(2건) |
| D2 | ③ 1101/04-02 | handoff quiescence 마감을 `IDLE_TIMEOUT`으로 | 검출(2건) |
| D3 | ③ 1101/04-02 | handoff checkpoint 마감을 `IDLE_TIMEOUT`으로 | 검출(1건) |
| D4 | ③ 1101/04-02 | handoff close 마감을 `IDLE_TIMEOUT`으로 | 검출(4건) |
정리: 지난 라운드에 고친 것(0929/04-01, 1101/04-01, 1101/04-02)은 모두 테스트로 고정됐다. 생존 8건은 이번 렌즈 ①·②의 검사(V2 삭제 때 바꾼 것과 남긴 것)와 지난 1101/04-03이다. P1~P4가 사는 것은 타입이 리터럴이라 테스트가 `as` 없이는 위반 값을 만들 수 없어서이기도 하다. 핵심은 리터럴 검사가 실제 실행기와 이어지지 않는다는 점이다(04-01).
@@ -0,0 +1,309 @@
# 영역 05 — 저장소·adapter kernel
> 검토일: 2026-11-03 · 기준: 브랜치 `review/2026-11-03-merged` / `e40684b` (리뷰어 worktree에서 detached, 작업 트리 깨끗함) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`. 판정에 필요해서 함께 읽은 것: `src/application/ports/browser-file-storage/opfs-ports.ts`, `src/contracts/storage-keys.ts`, `src/bootstrap/runtime-adapters.ts`·`boot-release-recovery.ts`·`optional-runtime-host.ts`, `recipes/frontend-capabilities/browser-file-storage-fakes.ts`(OPFS fake 부분), `tests/recipes/browser-file-storage-contracts.test.ts:575-625`, `config/recipes/frontend-capability-recipes.json:76-107`, `docs/operations/browser-file-storage-recovery.md`(§0·§1·§7), `docs/architecture/layers.md:77-130`, `docs/architecture/optional-adapter-recipes.md:80-86`, `.dependency-cruiser.json:254-266`
> 깊게 본 관점: 1, 11, 12, 22, 27, 28
> 이번 렌즈: partition 삭제와 다른 탭의 진행 중 put 경합(`e5b7b3e`), 손상 행 처리(`72edb55`), 로그아웃·계정 삭제 뒤 개인 데이터 잔존, kernel(`platform/`)의 공개 경계
> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 지정 범위(기본 구성)에서 쓸 수 있다. 기본 구성은 Web Storage에 개인 데이터를 두지 않는다. IndexedDB 런타임은 개인 데이터에 쓸 수 있으나 릴리스 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05, 남음). **OPFS 런타임을 개인 파일 저장에 켜는 제품은 05-01을 고친 뒤 조합한다.** 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다.
ID 표기: 이번 라운드 발견은 `05-NN`. 지난 라운드(2026-11-01) 발견은 `1101/05-NN`, 그 전 라운드(2026-09-29)는 `0929/05-NN`이다.
## 0. 결론
- **이 영역은 지난 리뷰(`d99301b`) 뒤 8개 커밋으로 바뀌었다.** 지난 발견 고침 5건(`e98a980`, `12c23fe`, `49f7cde`, `cc011bc`, `68e88b0`)과 README 14절 결정 3건(`72edb55`, `c4052f0`, `e5b7b3e`)이다. 12개 파일, +378/−79줄이다.
- **지난 발견 17건 중 8건은 고쳐졌다. 1건은 일부만 고쳐졌다(0929/05-01). 8건은 남았다.** 고친 8건은 이 커밋의 코드와 이번 실행으로 확인했다. 새 테스트가 지난 라운드에 살아남던 변이 K3·K4를 잡는다. Web Storage 변이 W4·W8은 여전히 살아남는다(1101/05-06 남음).
- **오늘 고친 partition 삭제 경합(`e5b7b3e`)은 주장한 범위에서 맞다.** 손상 때문에 partition을 통째로 지우는 길에서, 다른 탭의 진행 중 put은 삭제 앞에 끝나고 삭제가 그 결과까지 지운다. 테스트 5건과 abort 테스트 1건이 이것을 고정한다. lock을 빼거나(M1), exclusive를 shared로 바꾸거나(M2), 삭제 signal을 빼면(M3) 테스트가 실패한다.
- **그런데 손상이 없는 보통 purge에는 같은 보호가 없다(05-01, Medium).** 같은 partition에 끝나지 않은 put이 있으면 purge는 그것을 보지 않는다. 그래도 `moreObjectsAvailable: false`, `chunkSweep: "COMPLETED"`를 돌려준다. 재현 4건:
- X1: 다른 탭의 진행 중 put → purge "COMPLETED" 뒤 그 객체가 그대로 읽힌다. 실제 Chromium·Firefox 2탭에서도 같다.
- X2: commit 직전에 멈춘 put(FILES_READY) → purge 두 번 모두 "COMPLETED". 다음 reconcile이 그 put을 commit한다. 계정 삭제 뒤에 사용자 파일이 **읽을 수 있는 객체로 다시 생긴다.**
- X2b: 업로드 중 멈춘 put(PREPARING) → purge "COMPLETED". reconcile 뒤에도 chunk가 grace 기간(기본 24시간) 동안 남는다.
- X3: 그 put의 journal 행이 손상됐으면 purge는 매번 "COMPLETED"다. partition 삭제도 일어나지 않는다. bytes가 영원히 남는다. runbook(§1)은 "손상된 journal row 때문에 끝나지 못하면 partition을 지운다"고 적는다. 실제로는 purge가 "끝나지 못하는" 일이 생기지 않는다.
- 결과적으로 같은 ACCOUNT_DELETION이 손상이 있을 때 더 확실히 지운다. 손상 경로(partition 삭제)는 진행 중 put까지 기다렸다 지우고, 정상 경로는 남긴다.
- **새 발견은 4건이다.** Medium 1, Low 3. High 이상은 없다.
- 05-01 Medium: 위 내용.
- 05-02 Low: partition lock을 기다리는 put·delete가 자기 abort signal을 무시한다(X5 재현). 기다림에 상한이 없다.
- 05-03 Low: partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행은 지우지 못한다(X4 재현). 그 행은 reconcile마다 `corruptTransactions: 1`, `DEGRADED`로 영원히 남는다. runbook은 수동 삭제를 금지한다.
- 05-04 Low: recipe fake의 reconcile은 FILES_READY에서 멈춘 put을 되돌리는데 런타임은 commit한다. recipe 테스트 주석은 "Like the runtime"이라고 적는다. 다운스트림이 이 fake로 05-01을 테스트하면 통과한다.
- **kernel 공개 경계는 지난 라운드와 같다.** kernel 파일은 `contracts`·`application/ports` 타입만 import한다. 다른 adapter 그룹을 import하지 않는다. 그러나 공유 메커니즘이 아닌 port 구현 2개가 kernel 폴더에 있고(1101/05-04), 문서는 kernel 범위를 "clock, abort primitive, capacity guard"로만 적는다(0929/05-08). 둘 다 남았다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 05 |
| 커밋·작업 상태·확인 시점 | `e40684b`(두 작업 브랜치를 합친 리뷰 기준), 2026-11-03 23:00~24:00. 리뷰어 worktree, `git status` 깨끗함. 실험 파일은 끝난 뒤 지웠다 |
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행. SSR 없음 |
| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터 두 벌(`runtime-adapters.ts:395`, `boot-release-recovery.ts:57`)과 kernel의 `createBrowserMutationIntentFactory`(`runtime-adapters.ts:280`)다. IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED`, `productionComposition: false`다(`config/recipes/frontend-capability-recipes.json:76-101`). 다운스트림이 켜는 확장 지점이다 |
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다(13·14번 미검증). 데이터 요구: OPFS·IndexedDB 런타임의 정책 예시는 `classification: "PERSONAL"`, `accountDeletionAction: "PURGE_PARTITION"`이다. 그래서 "승인된 ACCOUNT_DELETION이 완료를 보고하면 그 partition의 bytes가 남지 않는다"를 이 영역의 필수 계약으로 본다(port 주석 `opfs-ports.ts:147-163`, runbook §7) |
| 읽은 코드·구성 범위 | `d99301b..e40684b`의 영역 diff 전부. `opfs-byte-store-adapter.ts`의 put·remove·reconcile·enforcePolicies·lock 함수 전부(`:171-1408`). worker의 `removePartition`·`listOrphanCandidates`·`deleteOrphanChunk`·`stagedChunkDigests`(`opfs-worker-runtime.ts:827-850`, `:1000-1180`). journal의 `begin` scope binding 검사, `listIncomplete`·`listCommittedObjects`·`removePartition`(`indexeddb-opfs-journal.ts:300-370`, `:685-920`). kernel 10개 파일의 import와 바뀐 주석. Web Storage 어댑터 diff. 지난 발견이 가리킨 위치 전부 |
| 주장으로만 읽은 것 | 커밋 `e5b7b3e`·`72edb55` 본문, runbook §0·§1·§7, `docs/architecture/layers.md` kernel 절, 지난 리뷰 문서 두 개 |
| 수행한 테스트·실험 | 6절. 영역 테스트 16파일 314/314 통과. 재현 실험 X1~X5·X2b(메모리 OPFS·IndexedDB, Node Web Locks). 변이 10개. `check:optional-recipes`(heavy lock 안). `check:browser-file-storage-boundaries` PASS. 실제 브라우저(heavy lock 안): OPFS·IndexedDB capability spec + X1 브라우저판 27/27 통과(6.4절). 전체 게이트는 다시 돌리지 않고 오케스트레이터 결과를 인용했다 |
| 확인하지 못한 범위·이유 | 제거 드릴(`test:browser-file-storage-removal`)은 heavy lock 대기열이 길어 돌리지 않았다. reconcile과 partition 삭제의 겹침은 코드로만 판단했다(`e5b7b3e` 본문도 미검증이라 적음). N-1 탭과의 partition lock 공존은 실행하지 않았다. WebKit에서는 OPFS 런타임이 기본 정책의 지원 판정을 통과하지 못해 OPFS 시나리오가 돌지 않았다. 6.5절 |
| 이전 리뷰와 비교 가능한 범위 | 지난 발견 17건을 이 커밋의 코드로 다시 판정했다(2절). 지난 라운드의 실행 결과(290/290, 변이 결과, X1·X2 재현)는 증거로 쓰지 않았다. 같은 위치를 다시 읽거나 다시 실행했다 |
오케스트레이터 게이트(같은 커밋, `scratchpad/review-gates/summary.txt`): `check:architecture`, `check:types`, `lint`, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `check:registries`, `check:i18n`, `check:design-system`, `check:diagnostics` 모두 exit 0. `test:unit` 2,580, `test:component` 263, `test:integration` 117, `test:contract` 23, `test:runtime-schema` 56 통과. `check:bundle` 초기 JS 201,848 / 204,800 gzip B.
## 2. 지난 발견 재판정
상태: **고쳐짐** / **남음** / **바뀜**(일부만 고쳐졌거나 모양이 달라짐). 심각도는 지난 판정 그대로이고, 바뀐 경우만 적는다.
| 지난 ID | 요약 | 상태 | 현재 근거 |
|---|---|---|---|
| 1101/05-01 | registry pulse 행이 실제와 다른 codec을 적어, StoragePort로 읽으면 다른 어댑터 값을 지운다 | 고쳐짐 (`e98a980`) | `StorageBackend`에 `"external"`이 생겼다(`src/contracts/storage-keys.ts:13`). pulse 행이 `backend: "external"`이다(`:116`). external 키는 정의 조회에서 거절된다(`:158`). `storage-registry.test.ts`(23건)가 이번 실행에서 통과했다 |
| 1101/05-02 | Web Storage 진단이 실패 원인을 버린다 | 고쳐짐 (`12c23fe`) | 진단 context에 `reason: cause`가 들어간다(`browser-storage-adapter.ts:382`). discard·oversize·quota 테스트가 `reason`을 본다 |
| 1101/05-03 | lifecycle "유일한 리스너 주인" 규칙이 깨졌고 테스트가 없다 | 고쳐짐 (`49f7cde`) | 주석이 규칙을 "런타임이 있을 때"로 좁히고 예외 둘(telemetry `pagehide`, 파일 선택기 `focus`)을 적는다(`browser-lifecycle.ts:1-17`). "No check enforces this"라고 스스로 적는다(`:17`). `tests/unit/browser-lifecycle.test.ts` 5건. 변이 K3(bfcache generation 증가 제거)·K4(dispose의 `pagehide` 해제 제거)를 이번에 다시 넣었고 둘 다 죽었다(6.3절) |
| 1101/05-04 | kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 예외를 받는다 | 남음 · Low · P3 | `browser-lifecycle.ts`·`browser-mutation-intent-factory.ts`를 import하는 adapter가 여전히 0이다(`grep`). bootstrap만 배럴로 쓴다(`runtime-adapters.ts:31`, `optional-runtime-host.ts:4`) |
| 1101/05-05 | kernel 주석의 `file:line` 참조가 다른 코드를 가리킨다 | 고쳐짐 (`cc011bc`) | `src/adapters/platform`, `browser-file-storage`, `storage` 전체에서 `파일:줄` 형식 참조 0건(`grep -oE '\.(ts|json|md):[0-9]+'`). 심볼 이름으로 바뀌었다 |
| 1101/05-06 | Web Storage 어댑터·codec 분기 5개를 테스트가 잡지 못한다 | 남음 · Low · P3 | codec을 직접 부르는 테스트가 없다(`grep browser-storage-codec tests` 0건). Firefox quota 이름도 테스트에 없다(`grep NS_ERROR_DOM_QUOTA_REACHED tests` 0건). 변이 W4(Firefox quota 이름 제거)·W8(만료 `<=` → `<`)을 Web Storage 관련 테스트 3파일 49건에 다시 넣었고 둘 다 살아남았다(6.3절) |
| 1101/13.6 | 여러 페이지를 다 지운 purge가 남았다고 보고한다(README 13.6) | 고쳐짐 (`c4052f0`) | 페이지 넘김이 `moreObjectsAvailable`를 바꾸지 않는다(`opfs-byte-store-adapter.ts:801-808`). 테스트 "finishes a purge that walked more than one journal page"(`tests/unit/opfs-worker-runtime.test.ts:2385`) 통과 |
| 0929/05-01 | journal·staging 손상 한 건이 계정 삭제 purge와 reconcile·GC를 멈춘다 | **바뀜**(일부 해결) · Medium · P2 | **고쳐진 것**: 두 목록이 손상 행을 건너뛰고 센다(`indexeddb-opfs-journal.ts:717-722`, `:798`). 손상 object 행, 손상 때문에 실패한 remove·sweep, `STAGING_STATE_UNREADABLE`이면 승인된 purge가 partition을 지운다(`opfs-byte-store-adapter.ts:921-946`). 그 삭제와 다른 탭 put의 경합도 막았다(`e5b7b3e`, 6.3절 M1~M3). **남은 것**: ① 손상 journal 행은 purge의 partition 삭제 조건에 들지 않는다. 그래서 그 put의 bytes가 영원히 남는다(→ 새 05-01 X3). ② `logicalKey`가 깨진 journal 행은 partition 삭제로도 지워지지 않는다(→ 새 05-03). ③ 손상 chunk reference 행은 여전히 reconcile을 실패로 끝낸다. `isChunkReferenced` 실패가 GC를 멈추고(`:1376-1378`), reconcile은 앞에서 처리한 결과를 버리고 실패를 돌려준다(`:697`). purge 쪽은 이것을 partition 삭제로 빠져나간다(`:899-902`). `72edb55` 본문이 ③을 범위 밖이라 적었다 |
| 0929/05-02 | purge가 지우지 못한 객체를 건너뛰고도 `COMPLETED`로 보고 | 고쳐짐 (`68e88b0`) | `CONFLICT`·`NOT_FOUND`면 `moreObjectsAvailable = true`, sweep을 건너뛴다(`opfs-byte-store-adapter.ts:842-849`). 테스트 `opfs-worker-runtime.test.ts:2445` 통과. 다만 **끝나지 않은 transaction**이라는 다른 원인으로 같은 거짓 완료가 생긴다(새 05-01) |
| 0929/05-03 | recipe의 같은 이름 port·fake가 src port와 다른 계약 | 고쳐짐 (`e1a4580`) | recipe contracts가 src port 타입을 import한다(`recipes/frontend-capabilities/browser-file-storage-contracts.ts:1-12`). `MemoryDurableObjectStore`가 src port를 구현한다(`browser-file-storage-fakes.ts:1660-1661`). 다만 그 fake의 reconcile 의미가 런타임과 다르다(새 05-04) |
| 0929/05-04 | offline-indexeddb 레시피 예산 여유가 거의 없다 | 고쳐짐 (`313f9ba`) | 이번 측정 `offline-indexeddb:37423/38500`(여유 1,077 B). 예산 규칙과 근거가 `docs/architecture/optional-adapter-recipes.md:80-86`에 있다. 그 표의 측정값 37,327은 `e5b7b3e`(+96 B) 이전 값이다. 3% 규칙 안이라 결함으로 세지 않는다 |
| 0929/05-05 | IndexedDB 전체 삭제 경로가 롤백 중 계정 삭제에 쓰이지 않는다 | 남음 · Low · P3 | 전체 삭제 조건은 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2574-2590`). N-1 탭은 `VersionError`를 `INCOMPATIBLE`로 바꾼다(`:663-672`). 그래서 롤백 중 ACCOUNT_DELETION은 실패를 돌려준다. 거짓 성공은 아니다. 파일은 `d99301b` 이후 바뀌지 않았다 |
| 0929/05-06 | 두 런타임이 삭제 승인 계약을 다르게 요구 | 남음 · Low · P3 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1903`) |
| 0929/05-07 | canonical JSON 3벌, `sameScope` 2벌 | 남음 · Low · P3 | `opfs-prepared-object.ts:138` `stableJson`, `cache-storage/public-cache-codec.ts:637` `stableJson`, `realtime/event-codec.ts:414` `canonicalJson`. `sameScope`는 `indexeddb-opfs-journal.ts:1361`, `opfs-worker-runtime.ts:1690` |
| 0929/05-08 | kernel 범위 설명이 실제보다 좁다 | 남음 · Low · P3 | `docs/architecture/layers.md:83-84`과 `.dependency-cruiser.json:254`는 kernel을 "clock, abort primitive, capacity guard"로 적는다. 실제 kernel은 IndexedDB 연결·트랜잭션, Retry-After, JSON 스캐너, lifecycle, mutation intent까지 10개 파일이다. 편입 기준("must never own")은 `indexeddb-connection.ts:21-25`에만 있다 |
| 0929/05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 | 남음 · Low · P3 | 주석 `opfs-policy.ts:23-28`, 검사는 범위만 본다(`:102-107`). 파일은 바뀌지 않았다. 덧붙임: 새 partition lock 대기는 이 두 값 어느 쪽에도 묶이지 않는다(새 05-02) |
| 0929/05-10 | OPFS journal DB 접두사를 바꿀 수 없다 | 남음 · Low · P3 | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` 고정 |
## 3. 이번 발견 (36.3)
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 05-01 | Medium | P2 (OPFS에 개인 파일을 두는 제품은 P1) | 확인된 결함 | 11, 15, 28, 12, 17, 5, 24, 23, 10 | 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다 |
| 05-02 | Low | P3 | 확인된 결함 | 12, 6, 19, 5 | partition lock을 기다리는 put·delete가 자기 abort signal을 무시하고, 그 기다림에 상한이 없다 |
| 05-03 | Low | P3 | 확인된 결함 | 28, 7, 5, 11 | partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행을 지우지 못해, `DEGRADED`가 영원히 남는다 |
| 05-04 | Low | P2 (05-01과 함께) | 확인된 결함 | 10, 17, 22, 5 | recipe fake의 reconcile이 FILES_READY에서 멈춘 put을 되돌리지만 런타임은 commit한다 |
### 05-01 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현 X1·X2·X2b·X3) |
| 관련 관점 | 11, 15, 28, 12, 17, 5, 24, 23, 10 |
| 근거 | ① purge가 보는 것은 두 가지다. commit된 object 행(`listCommittedObjects`, `opfs-byte-store-adapter.ts:809-878`)과, 어디서도 참조하지 않는 chunk(`reconcileOrphanChunks`, `:885-911`)다. 같은 partition의 끝나지 않은 journal 행(PREPARING·FILES_READY)은 보지 않는다.<br>② sweep은 staging receipt가 가리키는 chunk를 건너뛴다(`opfs-worker-runtime.ts:1065`, `:1108`, `stagedChunkDigests` `:1136-1180`). 진행 중인 put을 지키려는 동작이다. 그런데 건너뛰어도 결과는 `COMPLETED`다(`opfs-byte-store-adapter.ts:1397-1398`). report에는 건너뛴 수가 없다.<br>③ partition 삭제 조건은 손상 object 행, 손상으로 실패한 remove, 손상으로 실패한 sweep, `STAGING_STATE_UNREADABLE`뿐이다(`:921-924`). 손상 journal 행은 조건에 없다.<br>④ 계약 문서: port는 "Chunk bytes are gone only when it is `COMPLETED`"(`opfs-ports.ts:148-151`), runbook은 "`chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다"(`browser-file-storage-recovery.md:444`)라고 적는다. 둘 다 필요조건으로만 적혀 있다. 그런데 정상 경로에서 호출자가 받는 완료 신호는 이것 하나다. runbook §0은 손상 journal 행이 "승인된 purge로 통째로 지워질 때만 함께 지워진다"(`:40-42`), §1은 손상 journal row 때문에 끝나지 못하면 partition을 지운다(`:60-62`)고 적는다.<br>⑤ 재현(6.2절, 메모리 OPFS·IndexedDB·Node Web Locks, 실제 adapter·journal·worker 코드):<br>• X1 — 탭 W가 새 객체를 put하는 중(source 대기)에 탭 P가 ACCOUNT_DELETION purge → `{removedObjects:1, moreObjectsAvailable:false, chunkSweep:"COMPLETED"}`. 그 뒤 `object_late_0001`이 `[5]`로 읽히고 chunk·manifest가 partition에 남는다.<br>• X2 — commit 직전에 멈춘 put(FILES_READY) → purge 두 번 모두 `{removedObjects:0, chunkSweep:"COMPLETED"}`, receipt·chunk·manifest 그대로. 이어서 reconcile → `committedTransactions:1`, `object_dead_0001`이 `[9,9,9]`로 **읽힌다.**<br>• X2b — 업로드 중 멈춘 put(PREPARING, 보상 실패) → purge `COMPLETED`, 파일 3개 그대로. reconcile 뒤에도 chunk 1개가 남는다. 정상 GC는 grace(`orphanGracePeriodMs` 기본 24시간, `opfs-policy.ts:69`)가 지나야 지운다.<br>• X3 — X2의 journal 행에서 `phase`만 깨뜨림(키 필드는 그대로) → LOGOUT purge·reconcile을 두 번 돌려도 purge는 매번 `COMPLETED`, reconcile은 매번 `corruptTransactions:1`. partition 삭제는 일어나지 않는다. receipt·chunk·manifest가 남고, receipt가 chunk를 GC에서 계속 지킨다.<br>⑥ 기존 테스트가 X1의 동작을 고정한다. "never sweeps the chunk of a put that runs while the purge does"(`opfs-worker-runtime.test.ts:2417-2440`)는 purge 뒤 그 객체가 읽히기를 기대한다. report의 `chunkSweep`·`moreObjectsAvailable`은 보지 않는다 |
| 발생 조건 | OPFS 런타임을 조합한 제품에서, 승인된 LOGOUT·ACCOUNT_DELETION을 부를 때 같은 partition에 다음 중 하나가 있으면. (a) 다른 탭(같은 사용자)이 put 중이다. (b) 이전에 put이 끝나지 못했다: 업로드 중 탭 닫힘·크래시·보상 실패(PREPARING), commit 직전 중단·commit 응답 유실(FILES_READY). (c) 그 put의 journal 행이 손상됐다. 릴리스 롤백 뒤 N-1이 읽지 못하는 행도 여기 든다. "reconcile을 먼저 부르라"는 호출 순서 안내는 port·runbook·설계 문서 어디에도 없다(`grep enforcePolicies docs`) |
| 영향 | 계정 삭제·로그아웃 뒤 그 사용자의 파일 bytes가 기기에 남는다. 호출자는 "다 지웠다"를 받으므로 다시 부르지 않는다. (b)의 FILES_READY는 다음 reconcile(어느 탭이든, 다음 앱 시작)이 객체로 되살린다. (c)는 스스로 풀리지 않는다. 공유 기기에서는 다음 사용자가 앱으로는 다른 partition만 보지만, 이전 사용자 데이터가 origin 저장소에 남는다. 개인정보 삭제 요구가 있는 제품에서는 계약 위반이다 |
| 심각도·우선순위 | Medium · P2. 개인 데이터가 남고 거짓 완료를 보고하므로 피해는 크다. 다만 OPFS 런타임은 기본 구성에 없다(`productionComposition: false`). 같은 계열의 0929/05-01·05-02도 같은 조합 상태에서 Medium이었다. **OPFS에 개인 파일을 두는 제품이면 출시 전 차단(P1)으로 다룬다.** 백엔드와 짝으로 빨리 출시하는 기본 경로(Web Storage만)에는 걸리지 않는다 |
| 통제·증거 | "승인된 LOGOUT·ACCOUNT_DELETION이 완료를 보고하면 그 partition의 bytes는 0이다" 규칙: 손상 경로는 M3(테스트·변이 M1~M6), 정상 경로는 **M0 확인**(끝나지 않은 transaction을 보는 코드가 없음) · E3(X1, 실제 Chromium·Firefox), E2(X2·X2b·X3 재현, 기존 테스트 통과) |
| 확실성과 남은 가정 | 재현은 실제 adapter·worker·journal 코드와 메모리 FS·메모리 IndexedDB로 했다. 탭 크래시는 journal·worker 응답을 실패로 바꿔 흉내 냈다. 런타임 주석이 "timeout, crash, malformed response or worker failure"를 같은 경로로 다룬다(`opfs-byte-store-adapter.ts:1162-1168`). X1은 실제 Chromium·Firefox 2탭에서도 같은 report와 결과가 나왔다(6.4절). WebKit은 기본 정책에서 OPFS 런타임이 지원 판정을 통과하지 못해 확인하지 못했다. "COMPLETED"를 호출자가 "다 지웠다"로 읽는다는 것은 정상 경로에 다른 완료 필드가 없다는 사실에서 나온 추론이다 |
| 결정의 근거 | [기록] 05-04(chunk sweep)는 "Once every object is gone the partition's chunks are swept"라고 적는다(`opfs-byte-store-adapter.ts:879-883`). 기준이 "commit된 객체가 0"이다. [기록] `e5b7b3e`는 손상 경로에만 partition lock을 걸었다. runbook은 "삭제가 lock을 요청한 뒤 온 put의 데이터는 다른 purge처럼 남는다(point-in-time)"라고 적는다(`browser-file-storage-recovery.md:482-484`). [추론] point-in-time 의미라면 "purge 시작 때 이미 있던 것"까지는 지워야 한다. X1·X2·X3의 put은 purge 시작 전에 시작됐다. X2·X3은 이미 끝난(죽은) 작업이다. 그래서 point-in-time으로도 설명되지 않는다 |
| 이해 비용 | purge 결과를 믿으려면 호출자가 worker의 staging receipt 처리, reconcile의 FILES_READY roll-forward, GC grace를 모두 알아야 한다. port 주석만 보고는 알 수 없다 |
| 최소 개선 방향 | LOGOUT·ACCOUNT_DELETION에서 그 partition의 끝나지 않은 journal 행을 확인한다. 행이 있으면(읽을 수 있든 없든) 이미 있는 partition 삭제로 넘긴다. partition 삭제는 exclusive lock으로 진행 중 put을 기다린 뒤 디렉터리와 행을 모두 지운다(`e5b7b3e`). 필요한 것은 journal의 "이 partition에 끝나지 않은 행이 있는가" 질의 하나다. `removePartition`이 쓰는 같은 키 범위(`LOGICAL_KEY_INDEX`, `indexeddb-opfs-journal.ts:901`)로 셀 수 있다 |
| 대안 비교 | 5.1절. (a) 현상 유지 + 문서에 "reconcile 먼저, 다른 탭 쓰기 정지" 추가: X2·X2b는 막지만 X1(다른 탭의 진행 중 put을 기다릴 공개 API가 없음)과 X3(reconcile이 건너뜀)은 남는다. (b) report에 `incompleteTransactions` 수만 추가: 호출자가 알 수는 있지만 지우는 방법이 없다(X3). (c) 위 최소 개선: 기존 partition 삭제를 재사용한다. 조건 하나와 journal 질의 하나가 는다. (d) 승인된 LOGOUT·ACCOUNT_DELETION은 항상 partition 삭제: 가장 단순하고 정책 이름(`PURGE_PARTITION`)과 맞는다. 한 partition의 정책은 scope binding이 하나로 묶으므로(`indexeddb-opfs-journal.ts:350-360`) 객체별 판정을 잃어도 결과는 같다. 대신 예산 단위 진행을 잃는다. (c)를 권한다. 예산 단위 진행이 필요 없으면 (d)가 더 단순하다 |
| 단순화의 보존 조건 | 승인 없이 partition을 지우지 않는다(`authorizePolicyMaintenance` 뒤에만). 다른 partition의 행·파일을 건드리지 않는다. 진행 중 put을 지우는 것은 exclusive partition lock 안에서만 한다. TTL·SESSION_END·UNTIL_SYNCED·PRESSURE의 동작은 바꾸지 않는다 |
| 비용·부작용 | journal port에 질의 하나(공개 port 변경, 직접 구현한 쪽은 추가해야 함). offline-indexeddb 레시피 gzip이 늘어난다(여유 1,077 B). 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제로 바뀐다 |
| 재검토 조건 | 객체마다 다른 LOGOUT 정책이 한 partition에 섞여야 하는 요구가 생기면 (d)는 쓸 수 없다. partition이 커서 예산 없는 삭제가 화면을 오래 막으면 삭제를 나눠 하는 방법을 다시 본다 |
| 완료 기준 | X1·X2·X2b·X3 순서에서 승인된 ACCOUNT_DELETION이 `COMPLETED` 또는 `partitionDeleted`를 보고하면, 그 직후와 다음 reconcile 뒤 모두 partition 아래 파일이 0개이고 그 객체가 `NOT_FOUND`다. 그렇지 않으면 report가 남은 일을 보고한다 |
| 검증 방법 | 6.2절 실험을 `tests/unit/opfs-worker-runtime.test.ts`의 05-04 describe로 옮긴다. `opfs-worker-runtime.test.ts:2417`의 기대값을 다시 정한다. 실제 브라우저 2탭 판은 6.4절 spec을 `opfs-runtime.spec.ts`로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-02 partition lock을 기다리는 put·delete가 자기 abort signal을 무시하고, 그 기다림에 상한이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (재현 X5) |
| 관련 관점 | 12, 6, 19, 5 |
| 근거 | ① `withTransactionLock`은 partition lock을 signal 없이 요청한다: `withPartitionLock("shared", operation, undefined, run)`(`opfs-byte-store-adapter.ts:1118`). put·remove의 `request.signal`은 이 함수까지 오지 않는다(`:221-224`, `:495-498`).<br>② Web Locks 요청은 signal이 없으면 시간 제한이 없다. `mutationLockWaitTimeoutMs`(기본 10분)는 worker의 origin lease에만 적용된다(`opfs-policy.ts:22`, `:65`).<br>③ exclusive를 쥔 partition 삭제는 진행 중 put이 끝날 때까지 기다린다. 그 뒤 디렉터리 삭제는 예산에 묶이지 않는다(`:912-920` 주석). 그동안 새 put·remove는 그 뒤에 줄 선다.<br>④ 재현 X5: 다른 컨텍스트가 partition lock을 exclusive로 쥔 상태에서 `signal`을 단 put을 부르고 10 ms 뒤 abort → 200 ms 동안 put이 끝나지 않았다. lock을 풀자 그제서야 `ABORTED`를 돌려줬다 |
| 발생 조건 | 다른 탭에서 손상 때문에 partition 삭제가 진행 중일 때, 같은 partition에 put·remove(또는 만료 객체를 지우는 `open`, `:411-416`)를 부르고 취소할 때. 삭제가 느리게 진행 중인 큰 업로드를 기다리면 그 시간 전체다 |
| 영향 | 사용자가 업로드·삭제를 취소해도 화면은 대기 상태로 남는다. 화면 이동 뒤에도 작업이 남는다. 데이터 손상은 없다. lock을 얻은 뒤에는 `ABORTED`로 끝난다 |
| 심각도·우선순위 | Low · P3. 손상 partition + 승인된 purge + 같은 partition의 동시 쓰기가 모두 필요하다 |
| 통제·증거 | "취소된 쓰기는 기다리지 않고 끝난다" 규칙: origin lease는 M2(signal 전달), partition lock 대기는 **M0 확인** · E2(X5) |
| 확실성과 남은 가정 | Node의 Web Locks 구현으로 재현했다. Web Locks 표준도 signal 없는 요청에 시간 제한을 두지 않는다. 실제 브라우저로는 돌리지 않았다 |
| 결정의 근거 | 적용 제외 — 이미 받은 signal을 lock 요청에 넘기는 단순 수정이다. `withPartitionLock`은 signal을 받는 자리가 이미 있다(`:1137`, `:1144`) |
| 이해 비용 | `put`의 signal과 port 계약만 보고는 lock 대기 중 취소가 안 된다는 것을 알 수 없다 |
| 최소 개선 방향 | `withTransactionLock`에 `request.signal`을 넘기고 `withPartitionLock`에 전달한다. abort면 이미 있는 `ABORTED` 분기(`:1152-1153`)를 탄다 |
| 대안 비교 | 적용 제외 — 기존 계약 안의 수정이다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄. lock을 얻기 전 abort는 journal `begin` 전이므로 보상할 것이 없다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | partition lock이 잡혀 있을 때 abort한 put·remove가 lock 해제를 기다리지 않고 `ABORTED`를 돌려준다 |
| 검증 방법 | 6.2절 X5를 `opfs-worker-runtime.test.ts`로 옮긴다(abort 뒤 짧은 시간 안에 끝나는지) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-03 partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행을 지우지 못해, `DEGRADED`가 영원히 남는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서와 코드 불일치, 재현 X4) |
| 관련 관점 | 28, 7, 5, 11 |
| 근거 | ① `removePartition`은 object·chunk reference 행을 기본 키 접두사로 찾는다. journal 행은 `LOGICAL_KEY_INDEX` 인덱스로 찾는다(`indexeddb-opfs-journal.ts:867-920`, `:901`). 인덱스에는 `logicalKey` 값이 있는 행만 들어간다. 그래서 `logicalKey`가 없거나 깨진 journal 행은 찾지 못한다.<br>② runbook은 "값을 읽지 않고 키로 찾으므로 손상 row도 지워진다"(`browser-file-storage-recovery.md:459-460`), reconcile이 건너뛴 손상 행은 "partition이 승인된 purge로 통째로 지워질 때만 함께 지워진다"(`:40-42`)고 적는다. 그리고 journal row 수동 삭제를 금지한다(`:43-45`).<br>③ journal 단위 테스트의 "corrupt one"은 손상 object 행이다(`tests/unit/indexeddb-opfs-journal.test.ts:868-919`). 손상 journal 행 삭제는 보지 않는다.<br>④ 재현 X4: 손상 object 행과 `{transactionId, startedAtEpochMs, corrupt:true}` journal 행을 넣고 승인된 ACCOUNT_DELETION → `partitionDeleted: true`, partition 파일 0개. 그런데 journal 행은 그대로 남았다. 이어서 reconcile → `corruptTransactions: 1`. 관측은 `OBJECT_RECONCILE` `DEGRADED`/`CORRUPT_DATA`다(`opfs-byte-store-adapter.ts:705-712`) |
| 발생 조건 | journal 행의 키 필드까지 깨졌을 때. 다른 release가 다른 모양으로 쓴 행, 외부 도구가 쓴 행 등. 흔한 경우는 아니다 |
| 영향 | 그 행은 어느 partition에도 속하지 않으므로 지울 주체가 없다. reconcile은 매번 `DEGRADED`를 남긴다. 운영자는 "저장소 손상"(`opfs-ports.ts:128-131`) 신호를 계속 받는데 runbook이 허용하는 조치가 없다. 경보가 늘 켜진 상태가 되어 진짜 손상을 가린다. 파일 bytes는 남지 않는다(X4에서 partition 파일 0개) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | "승인된 partition 삭제는 그 partition의 손상 행도 지운다" 규칙: object·chunk 행 M3(변이 M4~M6 검출), journal 행 M2(값에 키가 남은 경우만) · E2(X4) |
| 확실성과 남은 가정 | 행이 어느 partition 것인지 알 수 없으면 지우지 않는 것이 안전하다는 판단도 가능하다. 그렇다면 문제는 코드가 아니라 runbook 문장과 "출구 없음"이다 |
| 결정의 근거 | [기록] 손상 행은 자동 삭제하지 않는다(runbook §0 3번). [추론] 소속을 모르는 행은 승인된 partition 삭제로도 지울 근거가 없다. 그래서 코드보다 문서와 운영 출구를 고치는 쪽이 맞다 |
| 이해 비용 | 운영자는 `corruptTransactions`가 0이 되지 않는 이유를 인덱스 정의까지 따라가야 안다 |
| 최소 개선 방향 | (a) runbook 문장을 "키(`logicalKey`)를 읽을 수 있는 손상 행만 지워진다"로 고친다. (b) 소속을 알 수 없는 손상 행을 위한 운영 출구를 정한다. 예: 이런 행은 `corruptTransactions`와 따로 세어 partition 손상 경보에서 뺀다 |
| 대안 비교 | (a)만: 가장 싸다. 경보가 계속 켜진다. (a)+(b): report 필드 하나가 는다. 경보가 의미를 되찾는다. (c) 소속을 모르는 손상 행을 자동 삭제: 그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번의 이유). 기각. (a)+(b)를 권한다 |
| 단순화의 보존 조건 | 적용 제외 — 제거 제안이 아니다 |
| 비용·부작용 | 문서 몇 줄. (b)는 report 필드 하나와 테스트 하나 |
| 재검토 조건 | 이런 행이 실제로 관측되면 원인(어느 writer가 키 없는 행을 썼는가)을 먼저 찾는다 |
| 완료 기준 | runbook 문장이 코드와 맞는다. 소속을 알 수 없는 손상 행에 대해 운영자가 할 일이 적혀 있다 |
| 검증 방법 | 6.2절 X4를 `indexeddb-opfs-journal.test.ts`로 옮긴다(손상 journal 행 두 종류: 키 있음·키 없음) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 05-04 recipe fake의 reconcile이 FILES_READY에서 멈춘 put을 되돌리지만 런타임은 commit한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (fake와 런타임의 계약 불일치) |
| 관련 관점 | 10, 17, 22, 5 |
| 근거 | ① fake `MemoryDurableObjectStore`는 `failNextPutAfter("FILES_READY")`로 "탭이 닫힌 것처럼" put을 멈출 수 있다(`recipes/frontend-capabilities/browser-file-storage-fakes.ts:1680-1683`). 그 fake의 reconcile은 멈춘 행을 모두 rollback으로 센다: `committedTransactions: 0`, `rolledBackTransactions: rows.length`(`:1855-1862`).<br>② 런타임은 FILES_READY 행을 검증한 뒤 commit하고 finalize한다(`opfs-byte-store-adapter.ts:1226-1281`). runbook도 같다(`browser-file-storage-recovery.md:435-436`). X2에서 reconcile은 `committedTransactions: 1`을 돌려줬고 객체가 읽혔다.<br>③ recipe 테스트는 FILES_READY 멈춤 뒤 reconcile이 rollback 1건을 내기를 기대한다. 주석은 "Like the runtime, reconcile rolls a stopped put back; it never resumes."다(`tests/recipes/browser-file-storage-contracts.test.ts:590-610`, `:606`).<br>④ catalog는 이 fake를 offline-indexeddb 레시피의 fake로 적는다(`config/recipes/frontend-capability-recipes.json:107`).<br>⑤ fake의 `enforcePolicies`도 멈춘 행(`#pending`)을 보지 않고 `COMPLETED`를 돌려준다(`browser-file-storage-fakes.ts:1892-1906`). 이 점은 런타임과 같다 |
| 발생 조건 | 다운스트림이 이 fake로 "업로드 중 탭이 닫히면" 시나리오나 05-01 시나리오(계정 삭제 뒤 reconcile)를 테스트할 때 |
| 영향 | fake로 쓴 테스트는 "멈춘 업로드는 reconcile 뒤 사라진다"를 통과한다. 실제로는 객체가 다시 생긴다. 05-01 X2를 fake 테스트로는 찾을 수 없다. UX도 갈린다: 사용자는 "저장 실패"를 봤는데 나중에 파일이 나타난다 |
| 심각도·우선순위 | Low · P2. fake 하나의 한 단계다. 다만 05-01을 숨기므로 함께 고친다 |
| 통제·증거 | "recipe fake는 런타임과 같은 reconcile 의미를 갖는다" 규칙: 주석으로 주장(M1), 확인 결과 둘을 비교하는 테스트 없음(M0) · E2(X2 런타임 결과와 recipe 테스트 대조) |
| 확실성과 남은 가정 | 런타임이 FILES_READY를 commit하는 것은 X2 실행과 runbook 둘 다로 확인했다. fake 쪽은 코드와 테스트로 확인했다 |
| 결정의 근거 | 적용 제외 — fake를 런타임 계약에 맞추는 단순 수정이다. 런타임의 roll-forward는 runbook과 설계 문서(`docs/architecture/browser-file-and-origin-storage.md:797-798`)에 적힌 의도다 |
| 이해 비용 | fake를 쓰는 사람은 테스트 주석을 믿는다. 차이를 알려면 런타임 reconcile을 읽어야 한다 |
| 최소 개선 방향 | fake가 멈춘 단계를 기억하고, FILES_READY면 reconcile에서 commit해 객체를 남긴다(`committedTransactions`로 센다). recipe 테스트 기대값과 주석을 런타임에 맞춘다. 05-01을 고치면 fake의 LOGOUT·ACCOUNT_DELETION도 `#pending`을 함께 지우게 한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | fake 몇 줄, 테스트 기대값 변경. recipe fake를 쓰는 다운스트림 테스트는 기대값이 바뀔 수 있다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 같은 시나리오(FILES_READY 멈춤 → reconcile → open)를 fake와 런타임에 돌린 결과가 같다 |
| 검증 방법 | 같은 시나리오를 두 구현에 돌리는 parity 테스트 하나(`tests/recipes/browser-file-storage-contracts.test.ts`) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | 적용 | M2 / M2 | E2(314/314, X1~X5) | P — CAS·fencing·partition lock·손상 행 건너뛰기가 put·remove·reconcile·purge 경로에 있다. purge의 "끝남" 규칙이 끝나지 않은 transaction을 빼고 판정한다(05-01) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(`check:architecture` exit 0, boundaries PASS 34건 거절) | O — kernel 파일은 `contracts`·`application/ports` 타입만 import한다. kernel 예외 밖 adapter 간 import 0건 |
| 3 | 변경 용이성 | 적용 | M3 / M3 | E3(레시피 측정) | P — 레시피 예산 여유가 1,077 B로 회복됐다(0929/05-04 고쳐짐). journal port가 `72edb55`에서 필수 메서드를 얻어 직접 구현한 쪽은 깨진다(본문에 적힘). 접두사 고정(0929/05-10) |
| 4 | 인지 부하 | 적용 | — | E1 | P — 큰 파일 4개(1,813~2,641줄) 그대로. purge 완료 판정이 플래그 5개(`moreObjectsAvailable`, `deadlineReached`, `corruptObjects`, `damaged`, `chunkSweep`)에 흩어져 있다(`opfs-byte-store-adapter.ts:787-946`) |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E2(X3·X4), E1 | P — runbook이 손상 journal 행 처리를 실제보다 넓게 적는다(05-01 X3, 05-03). recipe 테스트 주석이 런타임과 반대다(05-04). lifecycle 주석은 사실에 맞게 고쳐졌다(1101/05-03) |
| 6 | 실패 성숙도 | 적용 | M2 / M2 | E2(테스트, X5) | P — 손상 행이 목록·reconcile을 멈추지 않는다. 손상 chunk reference는 여전히 reconcile을 실패로 끝낸다(0929/05-01 ③). lock 대기 중 취소가 안 된다(05-02) |
| 7 | 운영 성숙도 | 적용 | M1 / M1 | E2(X4) | P — Web Storage 진단에 원인이 실린다(1101/05-02 고쳐짐). 소속 없는 손상 행이 `DEGRADED`를 영원히 남긴다(05-03). 선택형 런타임은 조합이 없어 경보 경로가 없다 |
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E2(X1~X3) | P — purge report에 건너뛴 staged chunk·끝나지 않은 transaction 수가 없다(05-01). `corruptTransactions`·`corruptObjects`는 생겼다 |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — `file:line` 참조는 없어졌다(1101/05-05). canonical JSON 3벌·`sameScope` 2벌(0929/05-07), kernel 문서가 좁다(0929/05-08) |
| 10 | 테스트 성숙도 | 적용 | M3 / M2 | E2(314/314, 변이 10개 중 8개 검출) | P — 새 OPFS·kernel 변이 8개가 모두 죽었다. Web Storage W4·W8은 살아남았다(1101/05-06). 기존 테스트가 05-01 X1 동작을 기대값으로 고정한다. recipe fake가 런타임과 다르다(05-04) |
| **11** | 데이터 성숙도 | 적용 | M3 / M2 | E2(X1~X4) | P — **"승인된 계정 삭제가 완료를 보고하면 partition bytes 0" 세부 규칙은 미충족**(05-01). 손상 object 행 경로는 충족한다(`72edb55`). IndexedDB 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05) |
| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2(테스트 5건·M1~M3), E3(X1·2탭 reconcile, Chromium·Firefox), E2(X5) | P — partition 삭제 대 다른 탭 put은 막혔다. 손상 없는 purge 대 다른 탭 put은 열려 있다(05-01 X1). lock 대기 취소 불가(05-02). reconcile 대 partition 삭제, N-1 탭 공존은 미검증 |
| 13 | 확장성 | 적용 | — | E1 | ? — 규모 목표가 없다. 배치 상한(reconcile 100행/5초, GC 배치)만 있다. partition 삭제는 예산이 없다 |
| 14 | 성능 성숙도 | 적용 | — | E3(측정) | ? — 목표가 없다. 측정값: 영역 테스트 314건 2.18초, offline-indexeddb 레시피 gzip 37,423 B. put·delete마다 Web Lock 요청이 하나 늘었다(시간 미측정) |
| 15 | 보안 성숙도 | 적용 | M2 / M2 | E2(X1~X3), E1 | P — 기본 구성은 Web Storage에 개인 데이터를 두지 않는다(`storage-keys.ts` 행 7개: 선호값 2, session 표시 2, 금지 2, external 1). OPFS 계정 삭제 뒤 개인 bytes 잔존(05-01). 승인 정규식 두 벌(0929/05-06) |
| 16 | 의존성 성숙도 | 적용 제외 | — | — | - — 외부 패키지 없이 브라우저 API만 쓴다 |
| 17 | API / Contract 성숙도 | 적용 | M2 / M1 | E2(X2·X3) | P — port의 `COMPLETED` 설명이 실제 보장보다 넓게 읽힌다(05-01). fake와 런타임의 reconcile 의미가 다르다(05-04). recipe 같은 이름 port는 없어졌다(0929/05-03) |
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P — `e5b7b3e` 이전 release 탭은 partition lock을 쥐지 않는다. 롤아웃 중에는 막은 경합이 다시 열린다(5.2절, 미검증). IndexedDB N-1 계정 삭제 실패(0929/05-05) |
| 19 | 설정 성숙도 | 적용 | M3 / M2 | E1 | P — timeout 관계 미검사(0929/05-09). partition lock 대기는 어떤 timeout에도 묶이지 않는다(05-02). 접두사 고정(0929/05-10) |
| 20 | 개발자 경험 | 다른 영역 | — | — | > — 영역 14 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M2 | E2(게이트 로그, boundaries PASS, 레시피 PASS) | P — 아키텍처·inventory·레시피·boundaries 게이트는 동작한다. lifecycle 규칙은 검사가 없다고 주석이 밝힌다. purge 완료 판정과 journal 상태를 잇는 검사는 없다 |
| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P — kernel은 메커니즘만 갖는다(import 확인). 기준 밖 파일 2개(1101/05-04), 중복 helper(0929/05-07), fake가 다른 의미(05-04) |
| 23 | 일관성 | 적용 | M1 / M1 | E2(X1) | P — 같은 ACCOUNT_DELETION이 손상 경로에서는 진행 중 put까지 지우고, 정상 경로에서는 남긴다(05-01). 승인 정규식 두 벌(0929/05-06) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2(X1~X3) | P — `chunkSweep: "COMPLETED"`는 "참조 없는 chunk를 다 훑었다"이지 "partition이 비었다"가 아니다. 이름만 보면 뒤의 뜻으로 읽힌다(05-01) |
| 25 | 조직 확장성 | 적용 | — | E0 | ? — 팀이 하나다 |
| 26 | Ownership 성숙도 | 적용 | — | E0 | ? — 선택형 런타임 조합이 없어 runbook 담당을 확인할 대상이 없다 |
| **27** | 삭제 가능성 | 적용 | M3 / M1 | E1 | P — 번들 제거 경계는 boundaries 검사가 지킨다(PASS). 제거 드릴은 이번에 돌리지 않았다. 기기 데이터 삭제는 OPFS 정상 경로에 빈틈이 있다(05-01) |
| **28** | 회복 가능성 | 적용 | M2 / M2 | E2(X2·X3·X4) | P — 손상 object 행은 승인된 purge가 스스로 빠져나간다. 손상 journal 행은 빠져나갈 길이 없다(05-01 X3, 05-03). Web Storage는 손상 값을 버리고 tombstone으로 다시 읽지 않는다 |
적용 항목 26개(16 제외, 20은 영역 14): 충족 1(2), 부분 충족 21, 미충족 0, 미검증 4(13, 14, 25, 26). 11번의 "계정 삭제 뒤 bytes 0" 세부 규칙은 미충족이다.
## 5. 설계 선택 검토 (41)
**[사실]**은 현재 코드·실행 결과, **[기록]**은 주석·문서·커밋 본문의 의도, **[추론]**은 리뷰어의 해석이다.
### 5.1 OPFS LOGOUT·ACCOUNT_DELETION을 객체 단위로 지울 것인가, partition 단위로 지울 것인가 (05-01)
1. **필요:** 계정 삭제·로그아웃이 그 사용자의 기기 데이터를 지운다. 정책 예시는 `accountDeletionAction: "PURGE_PARTITION"`이다. 예산(시간·객체 수) 안에서 나눠 진행할 수 있어야 한다. 여러 탭이 동시에 돈다.
2. **지킬 성질:** 승인 없이 지우지 않는다. 다른 partition을 건드리지 않는다. 완료를 보고했으면 그 partition의 bytes가 없다. 진행 중인 다른 탭 put의 파일을 주인 몰래 지우지 않는다(주인 없는 파일을 만들지 않는다).
3. **현재 보장:** [사실] 정상 경로는 commit된 객체를 하나씩 지우고 참조 없는 chunk를 grace 없이 지운다(`opfs-byte-store-adapter.ts:801-911`). 손상이 보이면 partition 디렉터리와 행을 통째로 지운다(`:921-946`). 손상 경로만 exclusive partition lock으로 진행 중 put을 기다린다. [사실] 한 partition에는 정책이 하나다. `begin`이 partition의 scope binding과 정책 fingerprint가 다르면 거절한다(`indexeddb-opfs-journal.ts:350-360`). **보장하지 않는 것:** 정상 경로는 끝나지 않은 transaction을 보지 않는다(X1~X3).
4. **대안:** (a) 현상 유지 + 호출 순서 문서화. (b) report에 끝나지 않은 행 수 추가. (c) 끝나지 않은 행이 있으면 partition 삭제로 넘긴다. (d) 승인된 LOGOUT·ACCOUNT_DELETION은 항상 partition 삭제.
5. **비교:** (a)는 X1·X3을 막지 못한다. 다른 탭 put을 기다릴 공개 API가 없고, 손상 행은 reconcile이 건너뛴다. (b)는 알려 주기만 한다. (c)는 이미 있고 테스트·변이로 지켜지는 partition 삭제를 재사용한다. 늘어나는 것은 조건 하나와 journal 질의 하나다. 끝나지 않은 행이 없으면 지금처럼 예산 단위로 진행한다. (d)는 가장 단순하다. 정책이 partition마다 하나라서 객체별 판정을 잃어도 결과가 같다. 잃는 것은 예산 단위 진행과 `removedObjects`·`releasedBytes` 보고다.
6. **판단:** [추론] 현재 조건에서는 (c)가 타당하다. 지금 구조를 가장 적게 바꾸면서 2번 성질을 모두 지킨다. 예산 단위 진행이 필요 없다고 정하면 (d)가 더 단순하고 코드가 준다.
7. **재검토 조건:** 한 partition에 서로 다른 LOGOUT 정책의 객체가 섞여야 할 때((d) 불가). partition이 커서 예산 없는 삭제가 화면을 오래 막을 때(나눠 지우는 partition 삭제가 필요).
### 5.2 partition Web Lock (`e5b7b3e`)
1. **필요:** partition 삭제는 두 단계(디렉터리 → journal 행)다. origin lease는 put의 BEGIN~FINISH만 막는다. 그 사이에 다른 탭 put이 끼면 주인 없는 파일이 남았다(커밋 본문의 RED 3건).
2. **지킬 성질:** 같은 partition의 mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 교착이 없다. 삭제는 취소할 수 있다.
3. **현재 보장:** [사실] put·delete는 journal `begin`부터 끝까지 partition lock을 shared로 쥐고(`:1118`), 삭제는 두 단계를 exclusive로 쥔다(`:926-940`). per-transaction lock은 `ifAvailable`이라 기다리지 않는다. 그래서 기다리는 lock은 partition lock → origin lease 순서 하나다. [사실] 테스트 5건(`opfs-worker-runtime.test.ts:2661-2757`)과 abort 테스트(`:2759-2790`)가 통과한다. lock 제거(M1), exclusive → shared(M2), 삭제 signal 제거(M3)를 테스트가 모두 잡았다. **보장하지 않는 것:** ① reconcile은 이 lock을 쥐지 않는다. [추론] reconcile의 FILES_READY 처리는 journal commit과 worker finalize다. 삭제의 두 단계 사이에 commit해도 두 번째 단계가 그 행을 지우고, finalize는 지워진 staging을 찾지 못해 실패한다. 그래서 bytes를 새로 만들지 않는다고 본다. 실행으로는 확인하지 않았다. ② `e5b7b3e` 이전 release 탭은 이 lock을 아예 쥐지 않는다. lock 이름에 `policy.mutationLockName`이 들어가므로(`:1143`) 이 값을 release마다 바꿔도 같다. 롤아웃 중 구버전 탭과 섞이면 막은 경합이 다시 열린다. 손상 partition + 승인된 purge + 구버전 탭의 동시 put이 모두 필요하다. ③ put이 lock을 기다리는 동안 취소가 안 된다(05-02). ④ 정상 purge에는 쓰이지 않는다(05-01).
4. **대안:** 커밋 본문이 넷을 비교했다. commitPut `CONFLICT` 보상, commit까지 origin lease 유지, 행 먼저 지우기, 디렉터리 → 행 → 디렉터리. 리뷰어가 더할 대안은 둘이다. (e) partition 삭제를 worker 요청 하나로 합치기: journal이 page 쪽에 있어 불가능하다. (f) journal에 "partition 삭제 중" 표시를 먼저 쓰고, put의 각 journal 단계가 확인한다.
5. **비교:** (f)는 lock 없이 journal만으로 순서를 정한다. 그러나 표시를 본 put이 이미 쓴 파일을 누가 치울지가 다시 문제다. 진행 중 put을 기다리는 지금 방식보다 상태가 많다.
6. **판단:** [추론] 유지한다. 비교한 후보 중 상태가 가장 적고, 기다리는 lock 순서가 하나이며, 테스트가 경합 순서 다섯 가지를 고정한다. 같은 lock을 정상 purge에도 쓰도록 넓히는 것이 05-01의 가장 작은 수정이다.
7. **재검토 조건:** reconcile이 파일을 새로 쓰게 바뀔 때(①이 깨진다). OPFS 런타임을 실제로 조합한 첫 release를 낼 때, 그다음 release 롤아웃에서 N-1 공존을 2탭 spec으로 확인한다(②).
### 5.3 kernel 공개 경계: 폴더 단위 예외 + 파일 경로 import + bootstrap용 배럴
1. **필요:** 여러 adapter 그룹이 같은 메커니즘(abort 경쟁, IndexedDB 연결·트랜잭션, Retry-After, JSON 중복 키)을 쓴다. adapter끼리는 import할 수 없다.
2. **지킬 성질:** kernel은 정책(이름·스키마·실패 코드·관측 모양)을 갖지 않는다. kernel은 다른 adapter 그룹을 import하지 않는다. 새 파일 단위 예외를 늘리지 않는다.
3. **현재 보장:** [사실] kernel 10개 파일의 import는 `contracts/result.ts`, `contracts/mutation-intent.ts`, `application/ports/*` 타입과 kernel 안 파일뿐이다. adapter는 kernel 파일을 경로로 직접 쓴다(abort 21곳, IndexedDB 연결·트랜잭션 9곳, clock 5곳 등). 배럴(`platform/index.ts`)은 bootstrap 2곳과 테스트 1곳만 쓴다. 배럴은 IndexedDB 연결·트랜잭션·Retry-After·JSON 스캐너를 내보내지 않는다. 그래서 그 넷은 사실상 adapter 전용이다. **보장하지 않는 것:** ① 폴더에 무엇을 넣을지는 규칙이 보지 않는다. 기준은 `indexeddb-connection.ts:21-25`에만 있다(0929/05-08). ② port 구현 2개가 같은 예외를 받는다(1101/05-04). ③ kernel이 `browser-file-storage/result.ts`(실패 코드를 가진 파일)를 import하는 것을 규칙이 막지 않는다. 그 파일도 kernel 예외라서다(`.dependency-cruiser.json:261`). 지금은 import하지 않는다.
4. **대안:** (a) 현상 유지. (b) 문서에 kernel 기준과 두 종류(공유 메커니즘 / bootstrap 전용 플랫폼 서비스)를 적는다. (c) 기준 밖 2개를 일반 adapter 그룹으로 옮긴다. (d) `platform/kernel/`과 `platform/services/`로 나눈다.
5. **비교:** 지난 라운드 4.2절과 같다. 이번 라운드에 kernel 코드는 주석만 바뀌었다(`cc011bc`, `49f7cde`). 비용·이득 판단을 바꿀 새 사실이 없다.
6. **판단:** [추론] (b)를 먼저 한다. 지난 라운드 권고가 처리되지 않았다(1101/05-04, 0929/05-08 남음). 문서 두 곳이라 비용이 가장 작다.
7. **재검토 조건:** 어느 adapter가 lifecycle·mutation intent를 직접 import하려 할 때((c)가 필요). kernel 파일이 한 그룹만 쓰는 코드로 늘어날 때.
## 6. 실험·변이 기록
### 6.1 영역 테스트·검사
| 명령 | 결과 |
|---|---|
| `node scripts/run-vitest.ts run` + 16파일(abortable-operation, browser-lifecycle, browser-storage-policy, indexeddb-connection, indexeddb-maintenance, indexeddb-opfs-journal, indexeddb-runtime, indexeddb-transaction, memory-indexeddb-fidelity, opfs-byte-store, opfs-worker-runtime, optional-runtime-host, storage-manager-adapter, storage-registry, system-clock, `tests/contract/consumer-experience/indexeddb-local-draft.test.ts`) | **314/314 통과**, 2.18초. 실행 직전 loadavg 13 |
| `corepack pnpm check:browser-file-storage-boundaries` | `PASS (owned adapter allowed, 34 direct or misplaced native access cases rejected)` |
| `flock … node scripts/check-optional-recipes.ts` | `PASS`, `file-transfer:56053/57800`, `offline-indexeddb:37423/38500`, `realtime:40857/42200`, `service-worker-pwa:9716/10100` gzip B |
### 6.2 재현 실험 (X1~X5, X2b)
방법: 리뷰어 worktree 안에서 `tests/unit/opfs-worker-runtime.test.ts`를 임시 파일로 복사하고 describe를 덧붙였다. 그 파일의 하니스를 그대로 썼다: 메모리 디렉터리, 메모리 IndexedDB(`tests/helpers/memory-indexeddb.ts`), 실제 `createOpfsByteStoreAdapter`·`createIndexedDbOpfsJournal`·`createOpfsWorkerRuntime`, loopback gateway, Node `navigator.locks`. 덧붙인 코드는 오케스트레이터 scratchpad의 `r05-1103/opfs-exp-block.ts`, `r05-1103/opfs-exp-block2.ts`에 있다. 끝난 뒤 임시 파일을 지웠다.
| ID | 시나리오 | 결과 |
|---|---|---|
| X1 | 객체 1개를 둔 뒤, 탭 W가 새 객체 put(source 대기) 중에 탭 P가 승인된 ACCOUNT_DELETION | put `ok`. report `{inspectedObjects:1, removedObjects:1, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. 뒤에 partition에 chunk 1·manifest 1이 남고 `object_late_0001`이 `[5]`로 읽힌다 |
| X2 | 탭 W의 `commitPut`이 실패(commit 직전 중단)해 FILES_READY 행이 남은 뒤, 탭 P가 ACCOUNT_DELETION 두 번, 이어서 reconcile | put `UNAVAILABLE/RETRY`. purge 두 번 모두 `{inspectedObjects:0, removedObjects:0, moreObjectsAvailable:false, chunkSweep:"COMPLETED"}`, receipt·chunk·manifest 그대로. reconcile `{committedTransactions:1, cleanedTransactions:1}`. 그 뒤 `object_dead_0001`이 `[9,9,9]`로 읽힌다 |
| X2b | 탭 W의 `markFilesReady`와 보상(`abortPreparedPut`)이 실패해 PREPARING 행이 남은 뒤 ACCOUNT_DELETION, 이어서 reconcile | put `UNAVAILABLE/RECONCILE`, 행 `PREPARING`. purge `COMPLETED`, 파일 3개 그대로. reconcile `{rolledBackTransactions:1}` 뒤 chunk 1개가 남는다(테스트 정책 grace 60초, 기본 24시간) |
| X3 | X2의 journal 행에서 `phase`만 `"GARBLED"`로 바꿈(키 필드 그대로). LOGOUT purge → reconcile을 두 번 | purge 두 번 모두 `COMPLETED`, `partitionDeleted` 없음. reconcile 두 번 모두 `corruptTransactions:1`. receipt·chunk·manifest가 남는다 |
| X4 | 손상 object 행 + `{transactionId:"transaction_corrupt1", startedAtEpochMs:1, corrupt:true}` journal 행. 승인된 ACCOUNT_DELETION, 이어서 reconcile | purge `{removedObjects:1, corruptObjects:1, partitionDeleted:true}`, partition 파일 0개. journal 행은 그대로 남는다. reconcile `corruptTransactions:1` |
| X5 | 다른 컨텍스트가 partition lock을 exclusive로 쥔 상태에서 signal 단 put → 10 ms 뒤 abort | 200 ms 동안 끝나지 않음. lock을 풀자 `{code:"ABORTED", operation:"OBJECT_WRITE"}` |
### 6.3 변이
방법: 오케스트레이터 scratchpad의 `r05-1103/mutate.mjs`가 한 번에 한 곳을 바꾸고 지정한 테스트를 돌린 뒤 원문으로 되돌린다(git을 쓰지 않음). M1~K4 실행 중 loadavg가 70까지 올랐다(다른 리뷰어 실행). M3에서는 abort 테스트 외에 10초 timeout 테스트 2건이 같이 실패했다. abort 테스트 실패는 이 변이 때문이고, 나머지는 부하 영향으로 본다.
| ID | 바꾼 것 | 돌린 테스트 | 결과 |
|---|---|---|---|
| M1 | put·delete가 partition lock을 쥐지 않음(`opfs-byte-store-adapter.ts:1118` → `run()`) | OPFS 3파일 | 검출(경합 테스트 5건 실패) |
| M2 | partition 삭제가 shared로 lock(`:927`) | OPFS 3파일 | 검출(6건 실패) |
| M3 | partition 삭제 lock 요청에 signal을 넘기지 않음(`:929`) | OPFS 3파일 | 검출("stops a partition delete … when the purge is aborted") |
| M4 | `removePartition`이 budget 행을 지우지 않음 | OPFS 3파일 | 검출(journal `removePartition` 테스트) |
| M5 | `removePartition`이 chunk reference 행을 지우지 않음 | OPFS 3파일 | 검출(같은 테스트) |
| M6 | `removePartition`이 journal 행을 지우지 않음 | OPFS 3파일 | 검출(같은 테스트) |
| K3 | bfcache 복원 때 generation 증가 제거(`browser-lifecycle.ts:126`) | lifecycle·optional-runtime-host | 검출 |
| K4 | dispose에서 `pagehide` 해제 제거(`:187`) | lifecycle·optional-runtime-host | 검출 |
| W4 | Firefox quota 이름 `NS_ERROR_DOM_QUOTA_REACHED` 제거(`browser-storage-adapter.ts:324`) | storage-registry·runtime-adapters·browser-storage-policy, 49건 | **생존** |
| W8 | 만료 비교 `<=` → `<`(`:138`) | 같은 49건 | **생존** |
10개 중 8개 검출. 살아남은 2개는 1101/05-06의 남은 공백이다. 전체 unit으로 다시 돌리려 했으나 heavy lock 대기열이 길어 Web Storage 어댑터를 부르는 테스트 파일로 좁혔다. 어댑터를 직접 부르는 테스트는 `storage-registry.test.ts` 하나다(`grep createBrowserStorageAdapter tests`).
### 6.4 실제 브라우저
오케스트레이터 scratchpad의 `r05-1103/run-browser.sh`가 heavy lock 안에서 `playwright.capabilities.config.ts`로 `opfs-runtime.spec.ts`, `indexeddb-runtime.spec.ts`, 임시 spec `zz-review05-purge.spec.ts`(X1의 브라우저판, 원본은 `r05-1103/`)를 돌리고 임시 spec과 결과 폴더를 지운다.
실행: 2026-11-03 23:41:32~23:41:57, 시작 직전 loadavg 26. 첫 시도는 vite dev 서버가 호스트의 파일 감시 한도(`ENOSPC`)로 뜨지 못했다. `CHOKIDAR_USEPOLLING=1`로 다시 돌렸다.
| 항목 | 결과 |
|---|---|
| 전체 | **27/27 통과**(23.6초). OPFS spec 2개 × 3엔진, IndexedDB spec 6개 × 3엔진, X1 spec × 3엔진 |
| X1 브라우저판 — Chromium | 탭 A의 새 객체 put이 source 대기 중일 때 탭 B가 승인된 ACCOUNT_DELETION → report `{inspectedObjects:0, removedObjects:0, releasedBytes:0, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. put 성공. purge 뒤 탭 B에서 `object_tab_12345678`이 `[2,7,1,8]`로 읽힌다 |
| X1 브라우저판 — Firefox | Chromium과 같은 report, 같은 결과(`[2,7,1,8]`) |
| X1 브라우저판 — WebKit | `inspectBrowserOpfsSupport`가 기본 정책에서 거절해 시나리오가 돌지 않았다("OPFS unsupported in this engine"). 기존 OPFS spec도 WebKit에서는 `UNSUPPORTED` 판정만 확인하고 끝나거나(`opfs-runtime.spec.ts:186-191`) 일찍 돌아간다(`:294`). 그래서 WebKit의 OPFS 통과는 fail-closed 판정의 증거일 뿐 런타임 동작의 증거가 아니다 |
| 기존 spec | OPFS 기본 흐름·2탭 reconcile(Chromium·Firefox), IndexedDB CAS·cursor·versionchange·blocked upgrade·손상 budget 행의 계정 삭제(0929/05-03)·N-1 online-only(3엔진) 통과 |
X1은 실제 OPFS·Web Locks·DedicatedWorker에서도 재현됐다(E3, Chromium·Firefox). X2·X2b·X3·X4·X5는 브라우저로 돌리지 않았다(E2).
### 6.5 미검증 목록
| 항목 | 이유 | 확인에 필요한 것 |
|---|---|---|
| 제거 드릴(`test:browser-file-storage-removal`) | heavy lock 대기열 | 오케스트레이터 실행 |
| reconcile과 partition 삭제의 겹침 | 코드로만 판단(5.2절 ①) | 삭제 두 단계 사이에 다른 탭 reconcile을 넣는 단위 테스트 |
| N-1 탭(partition lock 없음)과의 공존 | 실행하지 않음(5.2절 ②) | 이전 커밋 adapter와 현재 adapter를 같은 메모리 루트로 묶은 테스트 |
| 05-01 X2·X2b·X3, 05-02, 05-03의 실제 브라우저 재현 | 메모리 FS·Node Web Locks로만 재현 | 2탭 spec과 crash 흉내 |
| WebKit에서의 OPFS 런타임 동작 전체 | 기본 정책에서 지원 판정이 거절해 spec이 일찍 끝난다 | 정책을 바꾼 WebKit 실행 또는 지원 범위 문서화 |
| 0929/05-05·05-09의 재실행 | 파일이 바뀌지 않아 정적 확인만 함 | 지난 라운드 재현을 테스트로 옮김 |
@@ -0,0 +1,368 @@
# 06 Service Worker / Web Push 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` (`claude/happy-easley-233d07` + `fix/ui-design-audit-2026-11-01`) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/service-worker/`, `src/adapters/web-push/`, `vite.service-worker.config.ts`, `tsconfig.service-worker.json`, `scripts/build-frontend.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/lib/{service-worker-build-input,self-unregistering-service-worker,hosting-probe}.ts`, `scripts/verify-hosting-headers.ts`, `config/hosting/*.json`
> 깊게 본 관점: 7, 12, 15, 18, 19, 28
> 렌즈: 새 릴리스 배포 뒤 옛 워커·옛 탭이 스스로 회복하는가 / 캐시 정책(`config/hosting/cache-policy.json`)과 워커 상태가 맞는가 / 푸시 클릭이 base path 아래로 가는가
> 영역 판정(35.8): 기본 구성(SW `null`) **지정 범위에서 사용 가능** · SW `ACTIVE` **조건부 사용 가능** · Web Push **조건부 사용 가능** (0절)
ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 지난 라운드(2026-11-01)는 `1101/06-NN`, 그 전은 `0929/06-NN`, `0925/06-NN`이다.
## 0. 결론
**사용 결정**
| 구성 | 결정 | 조건·이유 |
| --- | --- | --- |
| 기본(SW `null`, Web Push 미선택) | 지정 범위에서 사용 가능 | 이 영역 코드가 실행되지 않는다. page controller 코드는 번들에 들어가지만 host를 만들지 않는다(`src/bootstrap/register-service-worker.ts:35-37`). 등록 조회도 하지 않는다(`service-worker-page-controller.ts:128-131`) |
| SW `ACTIVE`, 루트 base | 조건부 사용 가능 | 지난 라운드의 사용 보류 사유(`0929/06-01`)가 고쳐졌다. production 빌드가 production 설정을 싣는다(실험 ④). 조건: 업데이트 실패 관측·활성화 UI는 제품이 붙인다(`0925/06-05`). 호스팅이 CSS·글꼴 등 JS 아닌 자산 타입을 정확히 보낸다(06-03). 제거 3단계를 모두 배포한다(`0929/06-06`) |
| SW `ACTIVE`, 하위 경로(`/app/`) | 조건부 사용 가능 | 빌드 산출물의 사전 캐시·설정 URL이 base를 따른다(실험 ④). 실제 브라우저 설치는 실험 ⑦ L1로 확인했다(6.3절). 배포 게이트 FE-GATE-019는 하위 경로 URL을 거절해 통과할 수 없다. 이 부분은 13 영역 `0929/13-06`이다 |
| Web Push | 조건부 사용 가능 | 정상 클릭이 base path 아래를 연다(`1101/06-01` 고쳐짐). registry `path`의 `..`가 앱 밖을 연다(06-02, 조립 전에 고칠 수 있는 작은 결함). 서버의 짧은 TTL·send-time 인가 조건은 그대로다 |
**확인된 강점**
- 지난 라운드의 High(`0929/06-01`)가 막는 테스트와 함께 고쳐졌다. `publicDir: false`를 지우면 `service-worker-build-output.test.ts`가 실패한다(변이 B1).
- 하위 경로의 사전 캐시 URL, 워커의 설정 URL, 정상 푸시 클릭 URL이 모두 base를 따른다. 되돌리면 테스트가 잡는다(변이 N1·N2·B1).
- 워커 스크립트 `no-cache`를 호스팅 검사가 본다. 검사를 빼면 테스트가 잡는다(변이 B2).
- 새 릴리스 뒤 옛 탭의 청크는 직전 릴리스 캐시에서 응답한다. 이번에 브라우저 2종에서 다시 확인했다(6.2절).
**이번 발견 요약**: High 이상 0건. Medium 1건(06-05, P1, 원인은 이 영역 밖의 공용 제거 fixture). Low 4건(06-01~06-04), 모두 P3.
**차단 항목**: 06-05 — merge 게이트 FE-GATE-020의 `test:realtime-removal`이 이 커밋에서 항상 실패한다(제거와 무관한 문서 테스트 15건). CI를 머지 차단 장치로 쓰기 전에 고친다. 그 밖에 이 영역 코드 안의 차단 항목은 없다. SW를 하위 경로로 출시하려면 13 영역 `0929/13-06`(호스팅 probe가 루트 URL만 받음)이 먼저 풀려야 한다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` (템플릿, reference implementation) |
| 커밋·작업 상태·확인 시점 | `e40684b`, 깨끗한 분리 worktree, 2026-11-03 23시대. `git diff --stat d99301b e40684b`로 본 이 영역 변경: `vite.service-worker.config.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts`, `config/hosting/{cache-policy,response-headers.fixture}.json`, `notification-click-adapter.ts`, `notification-registry.ts`, e2e 도우미·spec 2개, 운영 문서. `src/adapters/service-worker/` 안의 7파일은 바뀌지 않았다 |
| 목적과 지원 실행 구성 | 브라우저 SPA + 정적 호스팅 + Service Worker. SW 선택 기본값 `null`(`src/features/installed-runtime-capabilities.ts:43`). `ACTIVE`는 레시피가 안내하는 지원 옵션이다(`docs/architecture/optional-adapter-recipes.md:126-153`). Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts:61-65`). 여러 탭과 하위 경로 배포(`VITE_ROUTER_BASE_PATH`)는 지원 범위다 |
| 필수 요구와 규모·운영 목표 | 합의된 SLO·업데이트 전파 시간 목표는 없다. 사전 캐시 상한은 256개·5 MiB(`src/contracts/service-worker.ts:13-16`). 사용자 목표는 백엔드 템플릿과 짝으로 빠른 출시다 |
| 읽은 코드·구성 범위 | 경로 머리의 파일 전부. 연결: `src/contracts/{service-worker,service-worker-static-manifest,web-push,env}.ts`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition}.ts`, `src/application/create-application.ts`(`recoverChunk`), `src/presentation/boundaries/chunk-recovery-boundary.tsx`, `tests/e2e/support/{service-worker-builds,fixture-builds}.ts`, `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/unit/service-worker-*.test.ts`, `tests/unit/web-push-*.test.ts`, `tests/unit/hosting-probe.test.ts` |
| 읽은 문서(주장) | `docs/operations/release-cache-rollback.md`(SW 절 `:166-199`), `docs/operations/browser-file-storage-recovery.md` 8절(`:508-612`), `docs/architecture/optional-adapter-recipes.md` 3절, `config/recipes/frontend-capability-recipes.json`(`service-worker-pwa`), `docs/architecture/realtime-events-web-push-and-bounded-polling.md` 8.4·8.5절 |
| 게이트(오케스트레이터, 같은 커밋) | `check:architecture` 0, `check:types` 0(`check:types:service-worker` 포함), `lint` 0, `test:unit` 2,580건 통과, `test:component` 263건 통과(`runtime-composition-service-worker-telemetry.test.ts` 포함), `test:integration` 117, `test:contract` 23, `test:runtime-schema` 56, `verify:documentation`·`check:adapter-inventory`·`check:ci` 0, 번들 PASS(초기 JS 201,848 / 204,800 gzip B). 출처: 오케스트레이터 `review-gates/summary.txt` |
| 수행한 테스트·실험 | 6절. ① 영역 단위 테스트 ② SW 빌드 출력 테스트 ③ 변이 13건 ④ SW `ACTIVE` + production + `/app/` 빌드 ⑤ 하위 경로 푸시 클릭(임시 vitest) ⑥ SW e2e 2 spec(chromium·webkit) ⑦ 렌즈 실험 L1~L3(Playwright, chromium·webkit) ⑧ `test:realtime-removal` |
| 확인하지 못한 범위·이유 | 7절 미검증 목록. 실제 CDN·푸시 서비스, Firefox의 SW 제어(Playwright 격리), `test:realtime-removal`의 test 단계 이후 계층(06-05로 멈춤) |
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 문서(`docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md`)와 README 13·14절의 조치 기록을 주장으로 읽었다. 판정은 이 커밋의 코드와 이번 실행으로 했다. 커밋 본문의 RED/GREEN 기록은 증거로 쓰지 않았다 |
## 2. 지난 발견 재판정
상태: **고쳐짐** = 코드가 바뀌었고 이번 실행·변이로 확인 · **남음** = 코드가 그대로 · **바뀜** = 일부만 고쳐졌거나 모양이 달라짐.
| 지난 ID | 지난 심각도 | 상태 | 근거 (이 커밋) |
| --- | --- | --- | --- |
| 0929/06-01 SW 빌드가 `dist/config.json`을 local 문서로 덮어씀 | High · P1 | **고쳐짐** | `vite.service-worker.config.ts:71-74` `publicDir: false`. 실험 ④(SW `ACTIVE`, `APP_PROFILE=production`, `/app/`): `dist/config.json`이 `APP_ENV production`·`AUTH_MODE external`·`RELEASE_MANIFEST_URL /app/release-manifest.json`이다. admission 거절은 예약 이름 2건뿐이다(13-02, 다른 영역). 변이 B1(`publicDir: false` 삭제) → `keeps the profile runtime config step 4 wrote` 실패 |
| 0929/06-02 사전 캐시 목록이 router base path를 무시함 | Medium · P2 | **고쳐짐** | `scripts/generate-service-worker-assets.ts:51-56`, `:74`, `:144`. 워커의 설정 URL도 `getBuildConfig`를 쓴다(`vite.service-worker.config.ts:99-102`). 실험 ④: 사전 캐시 48개가 모두 `/app/assets/…`, 워커 상수 `runtimeConfigUrl /app/config.json`·`releaseManifestUrl /app/release-manifest.json`. 변이 N1 → 단위 테스트 실패. 실험 ⑦ L1(6.3절): `/app/` 아래만 서빙하는 서버에서 chromium·webkit 모두 설치·제어됐고, 사전 캐시 48개가 전부 `/app/assets/`다(activation 마커 1개 별도) |
| 0929/06-03 레시피가 오프라인 셸을 SW 설치 조건으로 적지만 SW 계약은 금지함 | Medium · P2 | **남음** | catalog `trigger`에 `"a measured offline-shell requirement"`(`config/recipes/frontend-capability-recipes.json:140`), `failureKinds`에 `offline-fallback`(`:145`). 레시피 표 `install/offline shell`(`optional-adapter-recipes.md:111`). 코드는 navigation을 `NETWORK_ONLY`로 둔다(`service-worker-static-assets.ts:47`) |
| 0929/06-04 SW e2e 도우미가 SW를 켠 트리에서 멈춤 | Medium · P2 | **고쳐짐** | `turnOnServiceWorker`가 선택 값을 정규식으로 찾아 `ACTIVE`면 그대로 둔다(`tests/e2e/support/service-worker-builds.ts:76-77`, `:149-153`). `service-worker-build-output.test.ts:158-194`가 `null`·`REMOVE_REGISTRATION`·`ACTIVE` 세 경우를 본다. 실험 ②에서 통과 |
| 0929/06-05 `service-worker.js` `no-cache`가 호스팅 정책·probe에 없음 | Medium · P2 | **바뀜** | 루트 base에서는 고쳐졌다: `cache-policy.json:37-43` `serviceWorker` surface, `verify-hosting-headers.ts:84-88`이 워커를 싣는 빌드에서만 요구한다. 변이 B2 → `fails when the worker script is served with a long TTL` 실패. 남은 것 둘: 운영 문서가 아직 "헤더는 보지 않는다"고 적는다(**06-01**). 하위 경로에서는 probe가 루트 아닌 base URL을 거절한다(`hosting-probe.ts:245-252`). 이 부분은 13 영역 `0929/13-06`과 같은 원인이라 거기서 센다 |
| 0929/06-06 제거 2·3단계가 `service-worker.js`를 내보내지 않음 | Low · P3 | **남음** | 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 쓴다(`scripts/build-frontend.ts:73-78`). 운영 문서는 3단계 순서만 적고 각 단계 유지 기간이 없다(`release-cache-rollback.md:196-199`). 실험 ⑦ L3(6.3절, chromium·webkit): `ACTIVE` 다음에 바로 `null` 릴리스를 받으면 `update()`가 `TypeError`(404)로 거절되고, 이후 load에서도 옛 워커가 등록·제어된 채 남는다. 이번 실행으로 E3까지 확인했다. 심각도는 그대로다(페이지는 정상 부팅) |
| 0925/06-05 업데이트 설치 실패·`observe`·`health()` 미연결 | P2 | **남음**(문서화됨) | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). `create-runtime-composition.ts:50-54`는 `telemetry`만 넘긴다. `src`에서 `requestActivation`·`onUpdateWaiting`·`onReloadRequired`·`health()`를 읽는 곳이 없다(grep 0건). 레시피가 다운스트림 몫으로 적는다(`optional-adapter-recipes.md:128-142`) |
| 0925/06-08 이전 빌드 fallback이 `assets/`를 하드코딩 | P2 | **남음** | `service-worker-static-assets.ts:66`. `cache-policy.json:23` `pathPattern "/assets/*"`도 같은 가정이다 |
| 0925/06-10 SW Vite 설정의 `dist/config.json` 읽기 테스트 없음 | P3 | **고쳐짐** | `tests/unit/service-worker-build-output.test.ts:64-80`이 실제 빌드 결과를 `generateRuntimeConfig("production", …)`과 비교한다(변이 B1이 검출) |
| 0925 P3 route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | P3 | **남음** | `service-worker-update.spec.ts:49-61` 그대로 |
| 1101/06-01 정상 푸시 클릭이 base path를 무시함 | Low · P3 | **고쳐짐** | `notification-click-adapter.ts:118`, `:192-193`. 실험 ⑤(조립된 워커 runtime, scope `/app/`): registry `/inbox` → `openWindow("https://app.example.test/app/inbox")`. 변이 N2 → `opens an accepted click's route under the base path` 실패. 같은 결합 방식에 남은 구멍은 **06-02** |
| 1101/06-02 운영 문서의 활성화 조건이 틀림 | Low · P3 | **고쳐짐** | `browser-file-storage-recovery.md:583-590`이 두 경로(`requestActivation()` 성공, 탭을 모두 닫음)와 "새로고침만으로는 활성화되지 않는다"를 적는다. 실험 ⑦ L2와 맞다(6.3절) |
| 1101/06-03 PAGE_HELLO·UPDATE_READY·reload guard가 없고 흔적만 남음 | Low · P3 | **남음** | 파서가 세 kind를 받는다(`service-worker-protocol.ts:16-18`). 상수 `reloadGuardBytes`·`reloadGuardTtlMs`(`src/contracts/service-worker.ts:27-28`)를 읽는 곳이 없다. `retainedPreviousCaches`는 `void`로만 참조된다(`service-worker-lifecycle.ts:169`) |
| 1101/06-04 SW 보호 장치 3개는 지워도 테스트가 통과함 | Low · P3 | **남음**(+1) | 변이 M1(install fetch의 `credentials`·`redirect` 삭제), M3(nonce 재사용 허용), M9(요청받지 않은 client의 drain 응답 허용)이 이번에도 109건 통과로 생존했다. 같은 종류 1건을 더 찾았다: N8(첫 설치 워커도 "업데이트 대기"로 알림, `service-worker-page-controller.ts:336-341`의 `watched.active` 조건 삭제) → 생존. 새 발견으로 따로 세지 않는다 |
| 1101/06-05 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | Low · P3 | **남음** | `service-worker-static-assets.ts:280-285`, 이전 캐시 재사용 없음(`:221-267`). 이번 빌드 기준 48파일 782,923바이트(지난 28파일 767,076바이트). 파일 수가 는 것은 08-08의 청크 분리 때문이다 |
| 1101 R1~R4 리팩터링 후보 | — | **남음** | R1 `:169` 그대로. R2 `validateActiveFence` 두 벌(`push-event-adapter.ts:196`, `notification-click-adapter.ts:356`)은 아직 같다. R3 `SYNC_WAKE_OBSERVED`가 버전을 숫자로 직접 쓴다(`service-worker-entry.ts:170`). R4 5.0초 테스트(`service-worker-runtime.test.ts:1907`) 그대로, 실험 ①에서 5,007 ms |
## 3. 이번 발견 (36.3)
### 06-01 운영 문서가 "`verify:hosting-headers`는 워커 스크립트 헤더를 보지 않는다"고 적지만, 지금은 본다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함(운영 문서) |
| 관련 관점 | 26, 5, 28, 21 |
| 근거 | 문서: "`verify:hosting-headers`는 파일이 있는지만 보고 이 헤더는 보지 않는다 (`scripts/lib/hosting-probe.ts` `checkPublicServiceWorkers`)"(`docs/operations/browser-file-storage-recovery.md:580-582`). 코드: 워커를 싣는 빌드에서는 `serviceWorker` surface가 필수다(`config/hosting/cache-policy.json:37-43`, `scripts/verify-hosting-headers.ts:84-88`). `Cache-Control`이 `no-cache`가 아니면 FAIL이다(`:128-138`). 변이 B2와 `service-worker-build-output.test.ts:148-152`가 이를 지킨다. 다른 운영 문서는 맞게 적는다(`release-cache-rollback.md:73-74` "When the build ships a worker it requests `/service-worker.js` and expects `no-cache`") |
| 발생 조건 | 운영자가 장애 중 8절 runbook만 보고 판단한다 |
| 영향 | 운영자가 이미 자동 검사된 헤더를 손으로 다시 확인한다. 게이트가 무엇을 보는지 두 문서가 반대로 말한다. 틀린 방향이 "검사가 없다"여서 피해는 안전한 쪽이다 |
| 심각도·우선순위 | Low · P3. 문서 한 문장이다 |
| 통제·증거 | 문서 M1(틀린 서술), 코드의 워커 헤더 검사는 M3(변이 B2 검출) · E1(문서·코드 대조) + E2(빌드 출력 테스트) |
| 확실성과 남은 가정 | 문서와 코드를 직접 대조했다. 문서 마지막 수정(`e5b7b3e`, 0929/05-01)은 이 문장을 건드리지 않았다 |
| 결정의 근거 | 적용 제외 — 문서를 현재 코드에 맞추는 일이다 |
| 이해 비용 | 같은 검사에 대해 운영 문서 두 개가 반대로 말한다. 어느 쪽이 맞는지 알려면 스크립트를 읽어야 한다 |
| 최소 개선 방향 | `:580-582`를 고친다: "워커를 싣는 빌드에서 `verify:hosting-headers` live 모드가 `/service-worker.js`의 `Cache-Control: no-cache`를 확인한다. 하위 경로 배포는 probe가 지원하지 않는다(13 영역 0929/13-06)" |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 2~3줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 두 운영 문서가 같은 검사 범위를 적는다 |
| 검증 방법 | 문서 대조, `verify:documentation` 통과 |
| 담당·기한·상태 | 템플릿 소유자 · 미정 · 열림 |
| 재검증 결과 | 해당 없음(이번 라운드 발견) |
### 06-02 Web Push registry `path`의 `..` 또는 `%2e%2e`가 router base path 밖을 연다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 15, 19, 17, 1 |
| 근거 | 계약: registry `path`는 "router base path를 뺀 앱 기준 경로"이고 정상 클릭은 "같은 앱 루트 아래에서 연다"(`docs/architecture/realtime-events-web-push-and-bounded-polling.md:1550-1553`, 타입 주석 `src/adapters/web-push/notification-registry.ts:22`). registry 검사는 `/` 시작, `//`·`\`·`#` 금지, 같은 origin만 본다(`notification-registry.ts:107-123`). dot segment는 막지 않는다. 클릭은 문자열을 이어 붙인 뒤 URL로 푼다(`notification-click-adapter.ts:118`, `:193`). URL 파서가 `..`와 `%2e%2e`를 정규화하므로 base가 사라진다. **실험 ⑤**(임시 `tests/unit/review06-click-base.test.ts`, 실제 `createWebPushServiceWorkerRuntime`, scope `https://app.example.test/app/`): `/inbox` → `…/app/inbox`, `/../admin` → `https://app.example.test/admin`, `/%2e%2e/admin` → `https://app.example.test/admin`. 세 registry 모두 생성 검사를 통과했고, 세 경우 모두 `openWindow`가 위 URL로 1번 불렸다 |
| 발생 조건 | 제품이 Web Push를 조립하고 하위 경로에 배포하며, registry에 dot segment가 든 경로를 적는다(오타, 상대 경로 복사, 인코딩된 값) |
| 영향 | 열린 창이 없을 때 클릭이 같은 origin의 다른 앱 경로를 연다. 열린 창이 있으면 같은 `path`가 handoff로 가서 router가 해석한다. payload는 `routeIntent`만 싣고 경로를 고르지 못하므로 외부 입력으로 악용되지는 않는다 |
| 심각도·우선순위 | Low · P3. registry는 제품 코드이고 Web Push는 `NOT_SELECTED`다. 같은 origin 안에서만 벗어난다 |
| 통제·증거 | "클릭 URL은 앱 루트 아래" 규칙: M0(정규화 뒤 범위 검사 없음). same-origin 규칙은 M2 · E2(실험 ⑤) |
| 확실성과 남은 가정 | 클릭 URL은 실행으로 확인했다. 제품이 실제로 dot segment를 쓸 가능성은 낮다(추론) |
| 결정의 근거 | 확인한 사실: 위 실행. 기록된 의도: `1101/06-01` 수정 커밋(`c67edd2`) 본문은 `new URL(path.slice(1), appRootUrl)`을 버리고 pathname 접두를 골랐다(base가 `/`로 끝나지 않는 경우와 `a:b` 경로 때문). 리뷰어의 추론: 접두 방식은 맞지만 정규화 뒤 범위 검사가 빠졌다. 5.3절에서 비교한다 |
| 이해 비용 | 제품 개발자는 registry 검사를 통과하면 앱 경로라고 믿는다. 실제 범위는 클릭 어댑터의 문자열 결합과 URL 정규화를 같이 읽어야 안다 |
| 최소 개선 방향 | registry `safePath`가 정규화 결과와 입력이 같을 때만 받는다: `new URL(path, "https://registry.invalid").pathname`이 입력의 경로 부분과 같아야 한다. `..`·`.`·`%2e%2e`가 모두 거절된다 |
| 대안 비교 | 5.3절. (a) registry에서 거절 (b) 클릭 때 `target.pathname.startsWith(appRootPathname)` 검사 (c) 현상 유지. (a)가 가장 이르고 작다 |
| 단순화의 보존 조건 | `/` 시작·`//`·`\`·`#` 금지, 같은 origin, 512자 상한, 거절 클릭은 앱 루트를 연다(0925/06-09) |
| 비용·부작용 | 수 줄. realtime 레시피 번들 여유가 작다(지난 README 13.7에서 3 B, 그 뒤 예산 규칙이 바뀜). 측정이 필요하다 |
| 재검토 조건 | registry가 서버가 내려주는 런타임 데이터로 바뀌면 (b)를 함께 둔다. 그때 경로는 외부 입력이다 |
| 완료 기준 | `createWebPushNotificationRegistry`가 `/../admin`, `/%2e%2e/admin`, `/./inbox`를 거절하고 `/inbox`는 받는다 |
| 검증 방법 | `web-push-worker-runtime.test.ts`에 거절 사례 3개. 실험 ⑤를 다시 돌리면 registry 생성에서 throw |
| 담당·기한·상태 | 템플릿 소유자 · Web Push 조립 전 · 열림 |
| 재검증 결과 | 해당 없음 |
### 06-03 워커 install은 7가지 확장자의 Content-Type을 정확히 요구하지만, 호스팅 정책과 probe는 JavaScript만 본다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 18, 19, 21, 7, 8 |
| 근거 | 워커: 사전 캐시 대상은 `.css .js .mjs .png .svg .webp .woff2`이고(`src/contracts/service-worker-static-manifest.ts:45-55`), install은 응답 MIME이 manifest 값과 정확히 같아야 한다. 예외는 JS 별칭뿐이다(`service-worker-static-assets.ts:302-315`). 하나라도 틀리면 install 전체가 `CONTENT_TYPE_INVALID`로 거절된다(`:154-208`). 호스팅: `hashedAsset.contentTypes`는 `text/javascript`·`application/javascript`뿐이고(`config/hosting/cache-policy.json:22-27`), live probe는 index가 가리키는 entry script 하나만 요청한다(`scripts/lib/hosting-probe.ts:116-127`). 실험 ④의 사전 캐시는 JS 47개 + CSS 1개다. 페이지는 글꼴 MIME이 틀려도 글꼴을 쓴다. 워커만 실패한다 |
| 발생 조건 | 제품이 글꼴(`.woff2`)·이미지를 Vite 자산으로 싣고(12-04 결정의 `PRODUCT_LOADED_FONT_FAMILIES`가 글꼴 탑재를 예상한다), 호스팅이 그 확장자를 `application/octet-stream` 등으로 보낸다(MIME 표가 오래된 서버, content-type 없이 올린 object storage) |
| 영향 | 호스팅 게이트는 PASS다. 페이지는 정상이다. 워커는 첫 설치부터 업데이트마다 install이 거절된다. 첫 방문은 `service-worker.start.failed`(`error_kind: INSTALL_FAILED`)가 남지만 이유 코드는 페이지에 오지 않는다(`service-worker-lifecycle.ts:143-145`는 throw만 한다). 업데이트 실패는 아무 신호가 없다(`0925/06-05`). 사용자는 옛 워커에 머문다. 데이터 손상은 없다 |
| 심각도·우선순위 | Low · P3. 기능 장애가 아니라 SW가 조용히 동작하지 않는 문제다. 템플릿 기본 빌드에는 글꼴·이미지 자산이 없다 |
| 통제·증거 | "호스팅 응답 MIME = manifest MIME" 규칙: 워커 쪽 M2(install이 강제), 게이트 쪽 M0(비JS 확장자를 보지 않음) · E1(코드) + 빌드 산출물(실험 ④) |
| 확실성과 남은 가정 | 코드 경로와 빌드 산출물(실험 ④)은 확인했다. 틀린 MIME을 보내는 호스트로 브라우저 install을 돌리지는 않았다. `CONTENT_TYPE_INVALID` 분기는 단위 테스트가 이미 다룬다 |
| 결정의 근거 | 5.2절. 워커의 정확한 MIME 검사는 설계(§18, `browser-file-storage-recovery.md:530-535` 확인 순서 3·4)가 요구한다. 어긋난 쪽은 호스팅 검사 범위다 |
| 이해 비용 | 운영자는 호스팅 게이트 PASS를 "워커가 받을 응답도 맞다"로 읽는다. 실제 요구는 manifest codec 표와 install 코드를 같이 읽어야 안다 |
| 최소 개선 방향 | live probe가 후보 `dist/assets`에 있는 확장자마다 파일 1개를 요청하고 `CACHEABLE_ASSET_CONTENT_TYPES`와 비교한다. `cache-policy.json`의 `hashedAsset.contentTypes`는 그 표에서 만든다(손으로 두 벌 두지 않는다) |
| 대안 비교 | 5.2절. (a) probe 범위 확장 (b) 워커가 비JS 자산 MIME을 느슨하게 받음 (c) 사전 캐시를 줄임 (d) 문서에만 적음 |
| 단순화의 보존 조건 | 워커는 바이트 수·sha256·MIME을 모두 확인한 뒤에만 캐시에 넣는다. 하나라도 실패하면 이번에 만든 후보 캐시만 지운다 |
| 비용·부작용 | probe 요청이 확장자 수만큼 는다(지금 2개). 호스팅 검사 코드는 13 영역 파일이라 그 영역과 함께 고친다 |
| 재검토 조건 | 사전 캐시에서 비JS 자산을 빼기로 하면 이 항목은 닫힌다 |
| 완료 기준 | live probe가 `.css`를 `text/plain`으로 보내는 호스트를 FAIL로 판정한다 |
| 검증 방법 | `hosting-probe.test.ts`의 fetcher 대역으로 CSS MIME이 틀린 응답 사례 1개 |
| 담당·기한·상태 | 템플릿 소유자(13 영역과 공동) · 미정 · 열림 |
| 재검증 결과 | 해당 없음 |
### 06-04 waiting 워커가 바뀔 때마다 밀려난 후보 캐시가 남아, 활성화가 일어날 때까지 쌓인다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 13, 14, 11, 28 |
| 근거 | 캐시를 지우는 곳은 activate 하나다(`service-worker-lifecycle.ts:152-199`, 현재 + 마커가 가장 높은 이전 1개만 남긴다). install은 실패할 때 자기가 만든 후보만 지운다(`service-worker-static-assets.ts:191-206`). 템플릿은 `requestActivation()`을 부르지 않으므로 활성화는 그 scope의 탭이 모두 닫혀야 일어난다(`browser-file-storage-recovery.md:583-590`). 그 사이 릴리스가 나올 때마다 새 후보가 이전 waiting 워커를 밀어내지만, 밀려난 워커의 캐시는 남는다. **실험 ⑦ L2**(6.3절): A 활성 + 탭 1개 유지 상태에서 B를 받으면 소유 캐시 2개, 이어서 C를 받으면 B가 밀려나고 C가 waiting이 되며 소유 캐시 3개(A, B, C)다. 탭을 닫고 새 탭을 열자 C가 활성화되고 2개(C, A)로 줄었다. chromium·webkit 결과가 같다 |
| 발생 조건 | SW `ACTIVE` 제품에서 사용자가 탭을 계속 열어 두고(고정 탭, 새로고침만 함) 릴리스가 여러 번 나온다 |
| 영향 | 릴리스마다 사전 캐시 크기(지금 782,923바이트, 상한 5 MiB)만큼 저장소가 는다. 활성화가 일어나면 한 번에 정리된다. 쿼터에 닿으면 다음 install이 `QUOTA_EXCEEDED`로 실패한다. 저장소 압박 때 브라우저가 origin 저장소 전체를 지울 수 있다(이 앱의 IndexedDB·OPFS 포함, 05 영역) |
| 심각도·우선순위 | Low · P3. 탭을 모두 닫는 순간(브라우저 종료 포함, 추론) 한 번에 정리되므로 실제로 쌓이는 수는 작을 것으로 본다. 측정한 운영 데이터는 없다 |
| 통제·증거 | "waiting 기간 소유 캐시 수의 상한" 규칙: M0(정리 수단은 activate뿐) · E3(실험 ⑦ L2, 두 엔진) + E2(변이 N4·N5가 지키는 activate 정리 테스트) |
| 확실성과 남은 가정 | 쌓이는 동작은 실험으로 확인했다. 실제 사용자의 탭 패턴과 쿼터는 확인하지 않았다 |
| 결정의 근거 | 5.1절. install 때 지우지 않는 데는 이유가 있다(마커 없는 활성 캐시를 지울 위험). 그래서 결함이 아니라 위험으로 적는다 |
| 이해 비용 | 운영 문서는 "현재 + 직전 1개"만 말한다(`release-cache-rollback.md:171-184`). waiting 기간의 캐시 수는 코드와 SW 수명주기를 같이 알아야 보인다 |
| 최소 개선 방향 | (a) 운영 문서에 waiting 기간의 캐시 수(릴리스 수만큼)와 정리 시점을 적는다. (b) install이 성공한 뒤 "마커가 없고, 이번 후보가 아니며, 활성 워커의 캐시도 아닌" 소유 캐시를 지운다. 활성 워커의 캐시를 모르면 지우지 않는다 |
| 대안 비교 | 5.1절 |
| 단순화의 보존 조건 | 활성 워커가 읽는 현재 캐시와 마커가 있는 직전 캐시는 어떤 경우에도 지우지 않는다(변이 N5가 지키는 테스트) |
| 비용·부작용 | (a) 문서 몇 줄. (b) install 코드 수십 줄과 테스트. install하는 워커가 활성 워커의 캐시 이름을 알 방법이 필요하다 |
| 재검토 조건 | 제품이 활성화 UI를 붙여 waiting 기간이 짧아지면 (a)로 충분하다. 사전 캐시가 1 MiB를 넘고 릴리스가 잦으면 (b) |
| 완료 기준 | (a) 문서가 waiting 기간 캐시 수를 적는다. (b) A 활성 + 탭 유지 상태에서 B·C를 받은 뒤 소유 캐시가 2개(A, C)다 |
| 검증 방법 | 실험 ⑦ L2와 같은 순서의 e2e |
| 담당·기한·상태 | 템플릿 소유자 · 미정 · 열림 |
| 재검증 결과 | 해당 없음 |
### 06-05 `test:realtime-removal`(merge 게이트 FE-GATE-020)이 이 커밋에서 실패한다. 제거와 무관한 문서 테스트 15건이 fixture에 없는 파일을 읽는다
> 원인 파일은 이 영역 밖(`scripts/lib/removal-fixture.ts`, 문서 테스트 2개)이다. 이 영역의 삭제 가능성(27) 증거를 만들려다 찾았다. 다른 영역이 같은 결함을 적었다면 오케스트레이터가 합친다.
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 27, 20 |
| 근거 | **실행**(`flock … corepack pnpm test:realtime-removal`, 23:47~23:49): exit 1, `Realtime runtime removal failed: test`. junit `artifacts/tests/realtime-runtime-removal.xml` 7 check 중 `typecheck`·`lint`·`architecture`·`build`·`optional-catalog`·`ci-contract` 통과, `test`만 실패(`corepack pnpm test:all exited 1`). fixture 안 `test:unit`: 154파일 중 2파일 실패, 15건 실패 / 1,831건 통과. 실패는 모두 `tests/unit/changelog-review-ids.test.ts`(`ENOENT … open 'CHANGELOG.md'`, `:15`)와 `tests/unit/documentation-readiness.test.ts`(14건, `ENOENT … lstat 'README.md'`)다. fixture 복사 목록 `REMOVAL_FIXTURE_COPY_TARGETS`에 `README.md`·`CHANGELOG.md`·`docs`가 없다(`scripts/lib/removal-fixture.ts:25-39`). 두 테스트는 그 뒤에 생겼다(`003832b` 1101/14-02, `61baf96`·`16202fd` 1101/14-03·14-05). `test:all`은 `&&`로 이어져 있어(`package.json:83`) `test:unit` 실패 뒤의 contract·component·integration·platform·recipes는 fixture에서 돌지 않았다. 이 게이트는 merge 단계 FE-GATE-020이다(`config/ci/gates.json` `FE-GATE-020` `commandIds`, stage `merge`) |
| 발생 조건 | 이 커밋에서 FE-GATE-020을 돌리면 항상. 같은 복사 목록과 `test:all`을 쓰는 다른 제거 드릴(`test:sample-removal`, `test:optional-recipe-removal`, `test:browser-file-storage-removal`)도 같은 실패를 낼 것으로 본다(코드 읽기, 실행 안 함) |
| 영향 | merge 게이트가 web-push·realtime 변경과 무관하게 빨간색이다. 게이트가 늘 실패하면 실제 제거 회귀(예: 엔트리가 web-push를 다시 import)도 같은 빨간색에 묻힌다. CI가 꺼져 있어(지난 README U-1) 지금은 아무도 이 실패를 보지 못한다 |
| 심각도·우선순위 | Medium · P1. merge 게이트 하나가 항상 실패한다. 지난 라운드의 같은 모양(`test:system` 항상 실패, 1101/11-01)을 Medium · P1로 매겼다. 사용자 피해는 없지만 CI를 머지 차단 장치로 믿을 수 없게 만든다 |
| 통제·증거 | 제거 드릴 M3(검사는 있음) · 검사 자체가 깨짐 · E3(이 커밋에서 fixture 실행) |
| 확실성과 남은 가정 | 실패 원인(파일 없음)과 실패 범위(15건)는 로그로 확인했다. 다른 세 드릴은 돌리지 않았다. web-push를 지운 뒤 component·integration 계층이 통과하는지는 이번에 확인하지 못했다(앞 단계 실패로 실행되지 않음) |
| 결정의 근거 | 적용 제외 — 복사 목록과 테스트 전제가 어긋난 단순 결함이다. 어느 쪽을 고칠지만 고르면 된다(최소 개선 방향) |
| 이해 비용 | 문서 테스트를 더한 사람은 제거 fixture가 문서를 복사하지 않는다는 것을 알기 어렵다. 실패는 "Realtime runtime removal failed: test"로만 보여 원인이 제거와 무관하다는 것을 로그를 끝까지 읽어야 안다 |
| 최소 개선 방향 | 둘 중 하나. (a) `REMOVAL_FIXTURE_COPY_TARGETS`에 `README.md`·`CHANGELOG.md`·`docs`를 더한다. (b) 두 문서 테스트를 제거 fixture에서 빼는 목록에 넣는다. 제거 뒤에도 문서가 맞는지 보는 것이 목적이면 (a)다. (a)를 고르면 `documentation-readiness`가 지운 runtime 경로를 가리키는 문서 링크를 실패로 잡을 수 있다. 그건 실제 제거 비용이므로 드릴이 드러내는 것이 맞다 |
| 대안 비교 | 위 (a)·(b). 비용은 둘 다 수 줄이다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | (a)는 fixture 복사량이 는다(`docs`는 리뷰 문서 포함). (b)는 제거 뒤 문서 정합성을 보지 않는다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 이 커밋 위에서 `test:realtime-removal`이 exit 0이고 junit 7 check가 모두 통과한다. FE-GATE-020의 다른 네 명령도 통과한다 |
| 검증 방법 | `corepack pnpm test:realtime-removal`과 FE-GATE-020 전체 실행 |
| 담당·기한·상태 | 템플릿 소유자 · merge 게이트를 믿기 전 · 열림 |
| 재검증 결과 | 해당 없음 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외. 통제는 "목표 / 확인"이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | P. 런타임 검증은 exact하다. 지난 base path 결함 3건이 고쳐졌다. registry 경로 정규화 구멍이 남았다(06-02) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1·E2 | O. worker·page realm을 tsconfig로 나누고(`tsconfig.service-worker.json:8-17`) `check:types:service-worker`가 통과한다. 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`) |
| 3 | 변경 용이성 | 적용 | M1 / M1 | E1 | P. 활성화 UI·observe·WEB_PUSH 조립은 템플릿 파일을 고쳐야 한다(0925/06-05). e2e 도우미는 SW를 켠 제품에서도 돈다(0929/06-04 고쳐짐) |
| 4 | 인지 부하 | 적용 | - | E1 | P. 계약 주석은 충실하다. lifecycle 736줄, page controller 642줄, subscription adapter 1,203줄. 쓰지 않는 kind·상수가 기능이 있는 것처럼 보이게 한다(1101/06-03) |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 빌드 단계 주석이 `publicDir`를 적는다(`build-frontend.ts:21-22`). 운영 문서 한 곳이 검사 범위를 틀리게 적는다(06-01) |
| 6 | 실패 성숙도 | 적용 | M2 / M2 | E1·E2 | P. install 거절 11종, drain 시간 초과와 명시 거절을 구분한다. 워커의 거절 코드는 페이지에 오지 않는다(06-03의 진단 공백) |
| 7 | 운영 성숙도 **(깊게)** | 적용 | M2 / M1~M2 | E1·E2 | P. 시작 실패만 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:129-135`, component 통과). 업데이트 실패·`health()`는 연결되지 않았다(0925/06-05). 호스팅 게이트 PASS가 워커 install 성공을 뜻하지 않는다(06-03) |
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | P. `observe` hook과 reason 코드는 있으나 조립되지 않는다. install 실패 이유가 페이지에 오지 않는다 |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. 읽히지 않는 상수 3개와 kind 3개(1101/06-03), `validateActiveFence` 두 벌(R2) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(일부) | E2·E3 | P. 영역 단위 187건 + 빌드 출력 7건 통과. 변이 13건 중 9건 검출, 4건 생존(M1·M3·M9·N8, 1101/06-04). SW e2e 12건 통과(chromium 6, webkit 6, 6.2절). 하위 경로·여러 릴리스 e2e는 저장소에 없다(L1·L2는 임시 실험). 제거 드릴이 무관한 문서 테스트로 실패한다(06-05) |
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 소유 캐시 이름은 exact 비교다(`src/contracts/service-worker.ts:129-134`). push fence에 계정 ID·endpoint가 없다 |
| 12 | 동시성 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E2·E3 | P. 활성화는 탭 안 single-flight(`service-worker-page-controller.ts:369-376`), 범위 검사(변이 N7 검출). nonce 재사용·요청받지 않은 응답 거절은 테스트가 없다(M3·M9 생존). Web Push 제어는 origin Web Lock으로 직렬화한다(`push-subscription-adapter.ts`, 코드 변경 없음). 탭을 연 채 여러 릴리스를 받는 순서는 L2로 확인했다 |
| 13 | 확장성 | 적용 | M2 / M2 | E1·E3 | P. 256개·5 MiB 상한을 빌드에서 막는다(`generate-service-worker-assets.ts:68-94`). 지금 48개·782,923 B(개수 19%, 바이트 15%). waiting 기간에 캐시가 쌓인다(06-04) |
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1·E3 | P. fetch 리스너는 해시 GET만 가로챈다. 릴리스마다 사전 캐시 전체를 다시 받는다(1101/06-05). B 페이지가 A 워커 아래에서 돌 때 B 자산 요청마다 이전 캐시 마커를 읽은 뒤 네트워크로 간다(`service-worker-lifecycle.ts:228-248`, 지연은 측정 안 함) |
| 15 | 보안 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2 | P. payload는 route intent만 고르고 클릭 URL은 same-origin만 연다. registry 경로가 base 밖으로 나갈 수 있다(06-02, same-origin 안). install의 `credentials`·`redirect` 설정은 테스트가 없다(M1 생존, sha256이 바이트를 지킨다) |
| 16 | 의존성 성숙도 | 적용 | - | E3 | P. 런타임 외부 패키지 없음. SW 빌드가 `inlineDynamicImports option is deprecated, please use codeSplitting: false`를 이번에도 냈다(실험 ④ 로그) |
| 17 | API / Contract 성숙도 | 적용 | M2 / M2 | E1·E2 | P. SW 메시지 V1은 exact하다. 처리하지 않는 kind 3개를 받는다(1101/06-03). registry `path` 계약("앱 기준 경로")을 검사가 다 지키지 못한다(06-02). catalog가 오프라인 셸을 약속한다(0929/06-03) |
| 18 | 배포 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E3 | P. SW `ACTIVE` production 빌드가 맞는 설정을 싣는다(실험 ④). 옛 탭 청크 fallback과 자기 해제 워커를 브라우저로 다시 확인했다(6.2절). 하위 경로 설치도 확인했다(L1). 남은 것: 호스팅 검사가 비JS MIME을 안 본다(06-03), 하위 경로 호스팅 게이트 불가(13 영역 0929/13-06), 제거 단계를 건너뛴 사용자의 옛 등록(0929/06-06, L3) |
| 19 | 설정 성숙도 **(깊게)** | 적용 | M3 / M3 | E2·E3 | P. 지난 라운드 X에서 올라왔다. 프로필 설정과 base path가 워커 빌드까지 같은 함수(`getBuildConfig`)로 흐르고 변이 N1·B1이 지킨다. registry `path`의 기준은 정했지만 검사가 덜 됐다(06-02) |
| 20 | 개발자 경험 | 적용 | M1 / M1 | E1·E3 | P. SW 켜기 체크리스트(`optional-adapter-recipes.md:126-153`)가 있고 e2e 도우미가 제품 구성에서 돈다. 활성화 UI·observe는 composition을 직접 고친다 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(일부) | E2·E3 | P. build-input 거절, 워커 파일 존재 검사, 워커 헤더 검사(B2 검출), SW 빌드 출력 검사(B1 검출)가 동작한다. 비JS 자산 MIME은 검사하지 않는다(06-03). merge 게이트 FE-GATE-020이 이 커밋에서 항상 실패한다(06-05) |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1·E3 | O. 구조적 facade로 워커 없이 테스트한다. 실제 브라우저 결과(6.2·6.3절)와 단위 테스트 가정이 어긋난 곳을 찾지 못했다 |
| 23 | 일관성 | 적용 | - | E1 | P. 두 운영 문서가 워커 헤더 검사를 반대로 적는다(06-01). `SYNC_WAKE_OBSERVED`만 버전을 숫자로 쓴다(R3). 정상·거절 클릭은 이제 같은 앱 루트를 쓴다 |
| 24 | 네이밍 / 의미 | 적용 | - | E1 | P. `retainedPreviousCaches`는 읽히지 않고 "이전 1개"는 코드에 고정돼 있다(R1) |
| 25 | 조직 확장성 | 적용 제외 | - | - | -. 1인 관리 전제(0.1) |
| 26 | Ownership 성숙도 | 적용 | M1 / M1 | E1 | P. 운영 문서가 코드 경로를 가리키고 활성화 조건은 맞게 고쳐졌다(1101/06-02). 검사 범위 문장이 틀렸고(06-01) 제거 단계 유지 기간이 없다(0929/06-06) |
| 27 | 삭제 가능성 | 적용 | M3 / M3(드릴 깨짐) | E3 | P. 엔트리가 web-push를 import하지 않아 파일 삭제로 뺄 수 있다고 주장한다(`service-worker-entry.ts:157-158`). `test:realtime-removal`을 이번에 돌렸다: web-push·realtime을 지운 fixture에서 typecheck·lint·architecture·build·catalog·ci-contract는 통과했다. test는 제거와 무관한 문서 테스트 15건으로 실패했고, 그 뒤 계층(component·integration 등)은 돌지 않았다(06-05) |
| 28 | 회복 가능성 **(깊게)** | 적용 | M3 / M3 | E2·E3 | P. 런타임 kill switch와 자기 해제 워커가 있고, 자기 해제 워커는 이번 e2e로 다시 확인했다. 옛 탭은 직전 캐시로 청크를 받고(6.2절), 새로고침 뒤에는 A 워커 아래에서 B를 부팅한다(L2). `null` 릴리스 뒤에는 옛 워커를 걷어내는 장치가 없어 `REMOVE_REGISTRATION`을 다시 내야 한다(0929/06-06, L3) |
집계: 적용 27개 중 O 3 · P 24 · X 0 · ? 0, 적용 제외 1. 지난 라운드의 X 1건(19번)과 ? 1건(27번)이 P로 바뀌었다.
## 5. 설계 선택 검토 (41절)
### 5.1 캐시 정리를 activate에서만 한다 (현재 + 마커가 가장 높은 이전 1개)
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 옛 탭이 직전 릴리스 청크를 계속 받는다. 저장소가 끝없이 늘지 않는다. 활성 워커가 읽는 캐시를 다른 워커가 지우지 않는다 |
| 2. 지킬 성질 | 활성 워커의 현재 캐시와 직전 캐시는 어떤 순서로도 지워지지 않는다 |
| 3. 현재 보장 | activate가 소유 캐시 중 현재와 마커 최고 1개만 남긴다(`service-worker-lifecycle.ts:152-199`, 변이 N5 검출). install은 자기 후보만 되돌린다(`service-worker-static-assets.ts:167`, 변이 N4 검출). 마커 쓰기가 실패해도 활성화는 진행한다(Q-6.6-9, `service-worker-lifecycle.ts:193-196`). **보장하지 않는 것**: waiting 기간에 밀려난 후보 캐시는 다음 활성화까지 남는다(06-04, L2) |
| 4. 대안 | (a) 현행 + 문서에 waiting 기간 캐시 수를 적음 (b) install 성공 뒤 "마커 없음 + 이번 후보 아님 + 활성 캐시 아님" 소유 캐시를 지움 (c) install 성공 뒤 이번 후보를 뺀 모든 무마커 캐시를 지움 |
| 5. 비교 | (a) 코드 변경 없음. 쌓이는 양은 waiting 기간의 릴리스 수 × 사전 캐시 크기다. (b) 쌓이지 않는다. install하는 워커가 활성 워커의 캐시 이름을 알아야 한다. 지금은 그 정보가 없다(마커는 캐시 안에만 있고, 마커 쓰기에 실패한 활성 캐시는 무마커다). (c) 가장 단순하지만 마커 쓰기에 실패한 활성 캐시를 지운다. 활성 워커가 사전 캐시를 잃고 모든 요청을 네트워크로 보낸다. 성질 2를 깬다 |
| 6. 현재 조건의 선택 | (a)가 타당하다. (c)는 필수 성질을 깨므로 후보가 아니다. (b)는 활성 캐시를 식별할 수단이 생길 때 비교한다. 지금 조건(탭을 모두 닫으면 정리됨, 사전 캐시 0.75 MiB)에서는 쌓이는 양이 작다 |
| 7. 재검토 조건 | 사전 캐시가 1 MiB를 넘고 릴리스가 주 여러 번이면 (b). 제품이 활성화 UI를 붙이면 waiting 기간이 짧아져 (a)로 충분하다 |
- 확인한 사실: 위 코드, 변이 N4·N5, 실험 L2.
- 기록된 의도: §17.15 주석(`service-worker-lifecycle.ts:148-151`), Q-6.6-8·Q-6.6-9 주석.
- 리뷰어의 추론: 실제로 쌓이는 양은 사용자가 그 앱의 탭을 모두 닫는 빈도가 정한다. 브라우저 종료로도 활성화될 것으로 보지만 실행하지 않았다. 측정은 없다.
### 5.2 워커는 자산 MIME을 정확히 요구하고, 호스팅 검사는 JS만 본다
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 워커가 캐시에 넣는 응답은 빌드가 만든 바이트·타입과 같다(§18). 운영자는 호스팅 게이트 결과로 배포를 판단한다 |
| 2. 지킬 성질 | 게이트 PASS면 워커 install이 호스팅 때문에 실패하지 않는다. 워커는 타입이 틀린 응답을 캐시에 넣지 않는다 |
| 3. 현재 보장 | 워커 쪽은 보장한다(`service-worker-static-assets.ts:302-315`). 게이트 쪽은 entry JS 1개만 본다(`hosting-probe.ts:116-127`). 둘 사이가 비었다(06-03) |
| 4. 대안 | (a) probe가 확장자별 1개씩 요청하고 codec 표와 비교 (b) 워커가 비JS 자산은 MIME을 보지 않고 sha256만 봄 (c) 사전 캐시를 JS·CSS로 줄임 (d) 문서에만 적음 |
| 5. 비교 | (a) 요청 수가 확장자 수만큼 는다. 표가 하나라 어긋나지 않는다. (b) 설치는 되지만, 캐시에서 꺼낸 응답이 틀린 MIME을 그대로 갖는다. 설계가 거절한 선택이다(확인 순서 4 "type mismatch candidate는 폐기"). (c) 글꼴·이미지가 캐시 대상이 아니면 단순하다. 글꼴은 첫 화면에 쓰여 캐시 이득이 큰 자산이다. (d) 비용이 없지만 운영자가 놓친다 |
| 6. 현재 조건의 선택 | 워커 검사를 유지하고 (a)로 게이트를 맞추는 것이 타당하다. 지금 빌드에는 비JS 자산이 CSS 1개뿐이라 급하지 않다 |
| 7. 재검토 조건 | 제품이 글꼴·이미지를 Vite 자산으로 싣기 시작하면 그때 (a). 호스팅이 확장자별 MIME을 강제하는 환경으로 고정되면 (d)로 충분하다 |
### 5.3 registry 경로를 앱 루트 pathname 뒤에 이어 붙인다 (`1101/06-01` 수정 방식)
| 질문 | 답 |
| --- | --- |
| 1. 무엇이 필요한가 | 정상 클릭이 base path 아래 앱 경로를 연다. 열린 창에 보내는 handoff `path`는 base 없는 앱 경로다(router basename과 겹치지 않게) |
| 2. 지킬 성질 | 클릭이 여는 URL은 같은 origin이고 앱 루트 아래에 있다 |
| 3. 현재 보장 | `safeTarget(origin, ${appBasePath}${path})`(`notification-click-adapter.ts:193`)가 same-origin·userinfo·hash를 막는다. "앱 루트 아래"는 보장하지 않는다(06-02, 실험 ⑤) |
| 4. 대안 | (a) 현행 + registry가 정규화해도 바뀌지 않는 경로만 받음 (b) 현행 + 클릭 때 `target.pathname.startsWith(appRootPathname)` 검사 (c) `new URL(path.slice(1), appRootUrl)` (수정 커밋이 버린 안) |
| 5. 비교 | (a) 잘못된 registry가 생성 시점에 throw한다. 가장 이르다. (b) 클릭 때 실패하므로 사용자는 앱 루트로 간다(거절 경로). 런타임에야 드러난다. (c) 수정 커밋 본문이 적은 대로 base가 `/`로 끝나지 않거나 `a:b` 경로에서 틀리고, dot segment 문제도 그대로다 |
| 6. 현재 조건의 선택 | 이어 붙이는 방식은 유지할 근거가 있다(c의 두 문제). 거기에 (a)를 더하는 것이 가장 작다 |
| 7. 재검토 조건 | registry가 서버가 내려주는 런타임 데이터로 바뀌면 (b)를 함께 둔다. 그때는 경로가 외부 입력이다 |
## 6. 실험·변이 기록
모든 실행은 분리 worktree(`agent-a04a4fcd1de7a2048`, `e40684b`)에서 했다. 무거운 실행은 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock`으로 감쌌다. 끝난 뒤 `git checkout -- . && git clean -fd`로 되돌렸다. 커밋하지 않았다. 임시 실험 파일(`mutate.mjs`, `review06-click-base.test.ts`, `review06-sw-lens.spec.ts`, `playwright.review06.config.ts`)과 로그 사본은 오케스트레이터 scratchpad의 `review06/` 폴더에 있다.
### 6.1 테스트·빌드·변이
| # | 실행 | 결과 |
| --- | --- | --- |
| ① | `node scripts/run-vitest.ts run` 영역 단위 12파일(`hosting-probe`, `optional-runtime-host`, `service-worker-{build-input,runtime,web-push-remediation}`, `sub-path-deployment`, `web-push-*` 6개) | 187건 통과, 6.0초(부하 8.6). `bounds a stream that never produces a chunk` 1건이 5,007 ms(R4) |
| ② | `flock … node scripts/run-vitest.ts run tests/unit/service-worker-build-output.test.ts` | 7건 통과, 2.45초. 실제 SW `ACTIVE`·production·`/app/` 빌드 1회 포함 |
| ③ | 변이 13건(`.review06/mutate.mjs`, 한 번에 하나, 관련 테스트만) | 9건 검출, 4건 생존. 아래 표 |
| ④ | SW `ACTIVE`로 바꾼 뒤 `APP_PROFILE=production VITE_BUILD_ID=rev06-prod RELEASE_ID=rev06-prod VITE_ROUTER_BASE_PATH=/app/ node scripts/build-frontend.ts` | exit 0. `dist/config.json` production 문서(`RELEASE_MANIFEST_URL /app/release-manifest.json`). 사전 캐시 48개(JS 47, CSS 1), 782,923 B, 최대 190,561 B, 전부 `/app/assets/`. 워커 상수 `/app/config.json`·`/app/release-manifest.json`. `service-worker.js` 24.70 kB, gzip 9.15 kB. `inlineDynamicImports` deprecated 경고. `RELEASE_TARGET=production check-release-admission` → 예약 이름 2건만 거절(13-02) |
| ⑤ | 임시 `tests/unit/review06-click-base.test.ts`(조립된 `createWebPushServiceWorkerRuntime`, fake fence store) | scope `/app/`: `/inbox` → `…/app/inbox`, `/../admin` → `…/admin`, `/%2e%2e/admin` → `…/admin`. scope `/`: `/inbox` → `…/inbox` |
| ⑧ | `flock … corepack pnpm test:realtime-removal` (23:47~23:49, 직전 부하 34) | exit 1. junit 7 check 중 `test`만 실패. fixture `test:unit` 15건 실패 / 1,831건 통과, 실패는 모두 `CHANGELOG.md`·`README.md`가 fixture에 없어서다(06-05) |
| ID | 바꾼 것 | 결과 | 잡은 테스트 |
| --- | --- | --- | --- |
| M1 | install fetch의 `credentials: "omit"`·`redirect: "error"` 삭제 | **생존**(109 통과) | — (1101/06-04) |
| M3 | 같은 activate nonce 재사용 허용 | **생존**(109 통과) | — (1101/06-04) |
| M9 | 요청받지 않은 client의 `CLIENT_DRAINED` 허용 | **생존**(109 통과) | — (1101/06-04) |
| N1 | 사전 캐시 URL 생성에서 base 무시 | 검출 | `puts every asset URL under the router base path` |
| N2 | 정상 클릭에서 `appBasePath` 삭제 | 검출 | `opens an accepted click's route under the base path` |
| N3 | 이전 빌드 fallback을 `assets/` 밖 해시 이름까지 확장 | 검출(5건) | `passes /api/v1/user-profiles.json through` 외 |
| N4 | install 실패 때 이미 있던 캐시도 지움 | 검출 | `keeps a candidate cache that already existed when install fails (Q-6.6-8)` |
| N5 | activate가 마커 대신 가장 오래된 캐시를 직전으로 고름 | 검출(2건) | `retains the immediately previous verified static cache on activation` 외 |
| N6 | 숨은 탭에서도 6시간 업데이트 검사 | 검출 | `skips update checks while the injected host document is hidden (Q-6.6-12)` |
| N7 | drain 대상에서 제어받지 않는 창 제외 | 검출 | `enumerates uncontrolled window clients before an activation drain` |
| N8 | `onUpdateWaiting`의 `watched.active` 조건 삭제(첫 설치도 알림) | **생존**(109 통과) | — (1101/06-04에 합침) |
| B1 | SW Vite 설정의 `publicDir: false` 삭제 | 검출 | `keeps the profile runtime config step 4 wrote` |
| B2 | 호스팅 검사에서 `serviceWorker` surface를 늘 뺌 | 검출 | `fails when the worker script is served with a long TTL` |
### 6.2 SW e2e (실험 ⑥)
조건: 임시 `playwright.review06.config.ts`(webServer 없음, workers 1, chromium·webkit). spec이 스스로 A·B 빌드를 만들고 자체 서버를 띄운다.
명령: `flock … npx playwright test -c playwright.review06.config.ts tests/e2e/service-worker-update.spec.ts tests/e2e/service-worker-recovery.spec.ts`. 시작 23:37, 직전 부하 7.9.
- 결과: **12건 통과**(chromium 6, webkit 6), 37.3초.
- 확인한 것: `application/javascript`·gzip 응답으로 사전 캐시 install. update-waiting·reload-required 알림과 handshake 활성화. B가 제어한 뒤 서버에서 지워진 A 청크를 직전 캐시에서 200으로 응답. `REMOVE_REGISTRATION` 자기 해제 워커가 부팅을 막는 워커를 걷어냄. 수정하지 않은 빌드 스크립트가 워커 1파일을 냄.
- 한계: 루트 base, local 프로필이다. firefox는 돌리지 않았다(격리).
### 6.3 렌즈 실험 L1~L3 (실험 ⑦)
임시 `tests/e2e/review06-sw-lens.spec.ts`. strict page fixture 없이 자체 browser context를 썼다. 결과는 `REVIEW06 …` 로그 줄에서 옮겼다.
빌드는 모두 저장소 자신의 `prepareFixtureBuilds`·`prepareServiceWorkerBuilds`(임시 복사본, 수정하지 않은 `scripts/build-frontend.ts`)로 만들었다. 두 엔진 결과가 같았다.
**L1 — 하위 경로 설치** (SW `ACTIVE`, `VITE_ROUTER_BASE_PATH=/app/`, local 프로필. 서버는 `/app/` 아래만 응답하고 나머지는 404)
| 항목 | chromium | webkit |
| --- | --- | --- |
| registration scope / script | `…/app/` / `…/app/service-worker.js` | 같음 |
| 소유 캐시 수 / 항목 수 | 1 / 49 (manifest 48 + activation 마커 1) | 같음 |
| `/app/assets/` 밖 항목 | 0 | 0 |
| 두 번째 load 제어 | 됨 | 됨 |
| 캐시된 JS 재요청 | 200, 서버 요청 없음 | 같음 |
| `/app/config.json` 요청 | 200, 서버까지 감(network-only) | 같음 |
결론: `0929/06-02`의 브라우저 쪽 완료 기준(하위 경로에서 설치·제어)이 충족됐다.
**L2 — 탭 하나를 연 채 릴리스 A → B → C** (루트 base, `requestActivation()` 부르지 않음)
| 단계 | 결과 (chromium·webkit 같음) |
| --- | --- |
| A load 2회 | A가 제어, `start` = `ACTIVE sw-e2e-a`, 소유 캐시 1 |
| B 배포 + `update()` | B waiting(`installed`), 소유 캐시 2 |
| 같은 탭 새로고침 | B의 HTML(entry `index-BDOMh--G.js`, B dist와 같음)이 A 워커 제어 아래에서 부팅. entry는 서버에서 받음. B는 여전히 waiting. `start` = `UPDATE_WAITING` |
| C 배포 + `update()` | `update-waiting` 알림. C가 B를 밀어내고 waiting. **소유 캐시 3**(A, 밀려난 B, C) |
| 탭을 닫고 새 탭 | C 활성, 새 탭이 C 제어, `start` = `ACTIVE sw-e2e-c`, 소유 캐시 2(C + 직전 A) |
결론: 옛 탭은 새로고침 뒤에도 A 워커 아래에서 B를 정상 부팅한다(네트워크로 받음). 새 워커는 탭을 모두 닫을 때만 활성화된다(`1101/06-02` 문서와 맞다). waiting 기간에는 밀려난 후보 캐시가 남는다(06-04).
부수 관찰: 처음 실행에서는 A가 부팅을 끝내기 전에 서버를 B로 바꿨다. 두 엔진 모두 페이지가 스스로 다시 load했다(`Execution context was destroyed`). 부팅 중 읽은 설정·manifest가 HTML과 다른 릴리스여서 reload한 것으로 보인다. 원인은 확인하지 않았다(09 영역 범위). 두 번째 실행은 `start` 결과를 기다린 뒤 서버를 바꿨다.
**L3 — `ACTIVE` 다음에 바로 `null` 릴리스** (제거 2·3단계를 받지 못한 사용자. B는 SW 선택 `null`이라 `service-worker.js`가 없다)
| 단계 | 결과 (chromium·webkit 같음) |
| --- | --- |
| A load 2회 | A가 제어 |
| B 배포 + `update()` | `TypeError`로 거절(워커 스크립트 404) |
| B load 1·2회(각 3초 대기) | 등록 남음, A가 계속 제어, 소유 캐시 1, entry는 B의 것 |
결론: `null` 릴리스에서는 page controller가 아무것도 하지 않으므로(`service-worker-page-controller.ts:128-131`) 옛 워커가 계속 등록·제어된다. 페이지는 정상 부팅한다. 옛 워커를 걷어내려면 `REMOVE_REGISTRATION` 릴리스를 다시 내야 한다(`0929/06-06`).
## 7. 미검증
| 항목 | 이유 | 확인하려면 |
| --- | --- | --- |
| `test:realtime-removal`(web-push 삭제 가능성, 27) | 이번에 실행했지만 06-05 때문에 test 단계에서 멈췄다. web-push를 지운 뒤 component·integration·platform·recipes 계층은 확인하지 못했다 | 06-05를 고친 뒤 다시 실행 |
| 실제 CDN의 `service-worker.js`·자산 헤더 | 실제 호스트 없음. 호스팅 검사는 fixture 모드로만 돌았다(②) | staging 호스트로 `HOSTING_BASE_URL` live probe |
| 비JS MIME이 틀린 호스트에서의 브라우저 install(06-03) | 코드·단위 테스트로 대신했다 | e2e 도우미 `CONTENT_TYPES`에서 `.css`를 `text/plain`으로 바꿔 첫 설치 결과 확인 |
| Firefox의 SW 제어 | Playwright Firefox는 페이지를 제어하지 못한다(격리 `expires=2027-03-31`) | 수동 확인 |
| Web Push end-to-end(실제 푸시 서비스, VAPID, Safari의 무알림 push 구독 취소) | 푸시 서버 없음. `WEB_PUSH`는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 |
| 얼어 있는 탭이 Web Lock을 쥔 경우 | 재현 환경 없음 | `Page.setWebLifecycleState(frozen)` 실험 |
| B 페이지가 A 워커 아래에서 도는 동안의 요청 지연(14) | 측정하지 않았다 | resource timing으로 A 워커 아래 B 부팅과 B 워커 아래 B 부팅 비교 |
@@ -0,0 +1,319 @@
# 07 contracts (공유 어휘·외부 계약) — 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `src/contracts/`(44파일, 8,913줄), `schemas/`, `config/contracts/`(4파일)
> 깊게 본 관점: 1, 3, 17, 19, 22, 23, 24
> 렌즈: V2 API 행 삭제와 FE-REG-API 투영(`projectApiOperationRows`, `registry-governance.json`, 기준선 재승인)이 이전보다 약해진 곳, `responseEnvelope` 선택 필드와 조립 검사, 쿠키 쓰기 CSRF 조립 검사(`external-contract-runtime.ts`), FE-REG-ENV 행 변경(`d0414c8`, `ece944d`)
> 영역 판정(35.8): **조건부 사용 가능.** 외부 계약 조립기, `responseEnvelope` 칸, fixture 출처 규칙, 공유 zod 어댑터, 쿠키 쓰기 CSRF 조립 검사는 그대로 써도 된다. 조건은 셋이다. (1) descriptor의 status 목록·바이트 상한·마감·재시도 예산·problem 스키마를 바꾸는 PR은 사람이 직접 본다. 레지스트리가 이 칸을 보지 않는다(07-01). (2) 제품 설정 키 이름에 `TOKEN`·`COOKIE`·`SECRET` 같은 금지 조각을 쓰지 않는다. 빌드와 CI는 통과하고 부팅에서만 거절된다(07-04). (3) 짝 백엔드에 붙일 기능은 참조 기능이 아니라 `create:feature` 뼈대에서 시작한다. 참조 기능은 Envelope를 읽지 않는다(5.2절).
ID 표기: 이 문서의 `07-NN`은 2026-11-03 라운드 ID다. 지난 라운드(2026-11-01) 발견은 `1101/07-NN`, 2026-09-29 라운드 발견은 `P-07-NN`(= `0929/07-NN`)으로 적는다.
## 0. 결론
- **지난 라운드 발견 14건 중 9건이 고쳐졌다.** 1101/07-01·03·04·06과 P-07-01~04는 코드와 테스트로 닫혔다. 이번에 변이와 실험을 다시 돌려 확인했다(2절). 1101/07-02(API 이중 기술)는 V2 행을 지워 구조가 바뀌었다. 남은 것은 1101/07-05·07-07, P-07-05(일부)·06·07이다. 모두 Low다.
- **V2 삭제로 실행 사본과 검사 사본이 하나가 됐다.** FE-REG-API 행을 실행되는 descriptor에서 뽑는다. 지난 라운드 L1(검증기 schemaId 변경)이 이제 `check:registries`에서 실패한다(X1). 새 operation은 additive로 스냅샷에 남는다.
- **그러나 V2가 간접으로 지키던 검사 3개가 사라졌다(07-01, Medium).** 이전에는 V2/V3 일치 테스트가 V3 `acceptedStatuses`·`responseByteLimit`·`retrySemantics`를 V2 행에 묶었고, V2 행 값 전체가 기준선에 있었다. 지금 투영은 12칸만 뽑는다. 같은 변경을 두 커밋에서 실행했다. 생성 API의 `acceptedStatuses`를 `[200, 201]`→`[201]`로 줄이면 `d99301b`에서는 breaking 증거를 요구하며 실패했고(O1), `e40684b`에서는 모든 게이트와 관련 테스트 885건이 통과했다(X2). 응답 상한 변경은 기록에서 사라졌고(X3), GET에 `KEYED`를 적어도 조립된다(R1). 새로 생긴 `problemSchema` 칸은 breaking도 참조 검사 대상도 아니다(X4).
- **`responseEnvelope`는 제대로 잠겨 있다.** 값은 조립에서 검사하고(변이 M4가 죽음), 생략과 `"NONE"`은 같은 행이며(X7a), `"NONE"`→`"ENVELOPE_V1"`은 breaking이다(X7b).
- **쿠키 쓰기 CSRF 조립 검사는 맞게 동작하지만 테스트가 POST 한 사례뿐이다(07-02, Low).** 검사를 POST만으로 좁히거나(M2), "CSRF 헤더" 대신 "아무 필수 헤더"로 바꿔도(M3) 테스트가 통과한다. realtime snapshot 바인딩 조건도 지워도 통과한다(M9b). 검사는 descriptor HTTP만 본다. 쿠키를 늘 싣고 POST하는 resumable upload 제어 요청은 CSRF 헤더를 요구하지 않는다. 이것은 영역 01에 넘긴다.
- **FE-REG-ENV는 한 방향만 맞춘다.** `d0414c8`은 스키마 키마다 행이 있는지 본다. 행 쪽 값 5곳(required·default)은 여전히 스키마와 다르고, 스키마에 없는 행도 통과한다(P-07-05 일부 남음). 실제 스키마 변경은 FE-GATE-014가 잡는다. `ece944d`가 연 제품 키 경로에서는 금지 이름 검사가 부팅 때만 돈다(07-04, Low).
- High 이상 발견은 없다. 이번 라운드 신규 5건(Medium 1, Low 4).
## 1. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 07 |
| 커밋·작업 상태·확인 시점 | `review/2026-11-03-merged` / `e40684b`. 격리 worktree(`agent-a9b3e3c71bdcdad5b`). 실험마다 `git checkout -- src config`로 되돌렸고(스크립트 실험은 원본을 다시 썼다), 끝 상태는 `git status` 깨끗. 2026-11-03 23:00~ (호스트 load 약 14) |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 템플릿(`clean-architecture-backend-template`)과 함께 써서 빨리 출시하는 것이 목표 |
| 필수 요구와 규모·운영 목표 | 합의된 규모·운영 목표 없음. 짝 백엔드 응답 모양은 백엔드 `docs/web/http-contract.md`(읽기만)를 기준으로 했다 |
| 읽은 코드·구성 범위 | 줄 단위: `api-operations.ts` 전체, `external-contract-runtime.ts:25-900`, `rest-profiles.ts` 전체, `env.ts:1-140`, `product-contracts.ts`, `schema-registry.ts`, `boundary-mapper.ts:1-105`, `zod-validator.ts`, `unvalidated-payload.ts`, `release-artifacts.ts:51-290`, `realtime-streams.ts:455-475`(바뀐 부분), `config/contracts/*` 4파일, `scripts/check-registries.ts:380-731`, `scripts/lib/registry-compatibility.ts` 전체, `scripts/update-registry-baseline.ts`. 렌즈를 따라 함께 읽은 곳: `src/features/installed-feature-runtime-registries.ts`, `loaded-feature-runtimes.ts`, `feature-module.ts:51-90`, 참조 기능 `contracts/` 3파일, `scripts/create-feature.ts:540-720`, `scripts/generate-runtime-config.ts:36-106`, `src/bootstrap/load-runtime-config.ts:100-125`, `src/adapters/http/http-execution-v3.ts:436-470`, 테스트 `api-operation-rows`, `rest-profile-contract`, `second-api-feature-registries:1-140`, `env-registry-coverage`, 이전 커밋 `d99301b`의 `api-operations.ts`·parity 테스트·기준선 |
| 읽은 문서(주장) | `docs/manual/01-add-a-feature.md:155-215, 490-512`, `docs/manual/02-decision-tables.md:79-112`, `docs/contracts/compatibility.md:1-80`, `docs/architecture/starter-experience.md:130-206`, CHANGELOG 미출시 절, 커밋 `12f3bb7`·`365d8c3`·`d0414c8`·`ece944d` 본문, 지난 라운드 07 문서와 README 13~14절 |
| 수행한 테스트·실험 | 6절. 게이트는 다시 돌리지 않고 오케스트레이터가 같은 커밋에서 돌린 결과를 인용한다: `check:architecture`, `check:types`, `lint`, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `check:registries`(`11 registries PASS; compatibility=additive`), `check:i18n`, `check:design-system`, `check:diagnostics` 모두 rc=0. `test:unit` 2,580, `test:component` 263, `test:integration` 117, `test:contract` 23, `test:runtime-schema` 56건 통과. 번들 초기 JS 201,848 / 204,800 B. 영역 실험은 관련 테스트 77파일(885건, 변경 없이 17.2초 통과)로 돌렸다 |
| 확인하지 못한 범위·이유 | `browser-rpc.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `query-keys.ts`, `server-state.ts`, `routes.ts`·`deployment-admission.ts`의 새 줄은 diff만 봤다(이번 렌즈 밖). `build`·e2e·Playwright는 돌리지 않았다(렌즈에 브라우저 실행이 필요한 주장이 없다). 다운스트림 두 repo는 이번에 읽지 않았다. V2 시절 realtime snapshot 조건이 테스트로 잠겨 있었는지는 확인하지 않았다(07-02) |
| 이전 리뷰와 비교 가능한 범위 | 1101/07-01~07, P-07-01~07을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다. 지난 실험 L1·L3·L7·X3·X4·X5·Z1과 변이 MX1·MX2·MX6·MX9는 이 커밋에서 다시 돌렸다. 07-01의 "이전에는 막았다"는 `d99301b`를 같은 worktree에 체크아웃해 직접 돌린 결과(O1·O2)다 |
## 2. 지난 발견 재판정
| ID | 내용 | 판정 | 근거 (이 커밋) |
|---|---|---|---|
| 1101/07-01 | `MappingResult` 이름 하나가 두 모양을 가리키고 실행 API가 폐기 별칭을 요구한다 | **고쳐짐** | 바인딩과 helper 반환 타입이 `BoundaryMappingResult`다(`boundary-mapper.ts:51, 87, 99, 103`). 정본 주석이 실제와 맞다(`external-contract-runtime.ts:42-49`). 폐기 별칭 import는 lint가 막는다(`eslint.config.ts:56-68`). 참조 mapper에 별칭 import를 넣으면 `no-restricted-imports` 오류(6절 L-1). 같은 이름 두 개는 다운스트림 호환 때문에 남아 있다(별칭 주석 `boundary-mapper.ts:20-28`) |
| 1101/07-02 | API 하나를 V2 행과 V3 descriptor에 두 번 쓰고 둘을 잇는 검사는 6필드뿐 | **바뀜** | V2 행과 parity 테스트를 지웠다(`12f3bb7`). 행은 descriptor에서 뽑는다(`api-operations.ts:34-57`). X1(옛 L1): 검증기 schemaId 변경이 `references unknown FE-REG-SCHEMA`와 breaking 증거 누락으로 실패한다. 옛 L6(새 operation)은 additive로 남는다(`second-api-feature-registries.test.ts`). 남은 것 두 가지는 새 ID로 적었다: parity가 지키던 칸이 빠진 것(07-01), 스키마 메타데이터가 손 사본인 것(옛 L7, 07-03). 옛 L3(마감 6배)은 지금도 통과한다(X6, 07-01에 포함) |
| 1101/07-03 | zod 어댑터가 참조 기능 안에만 있고 검증 생략을 구분하지 못한다 | **고쳐짐** | 어댑터는 `src/contracts/zod-validator.ts:16` 한 곳(grep: 정의 1개). 생략은 `unvalidatedPayload(schemaId, reason)`(`unvalidated-payload.ts:13-31`)로만 이름 붙이고 `listUnvalidatedPayloads`가 모은다. X5: GET 출력 검증기를 생략으로 바꾸면 `starter-platform-overview-page.test.tsx:125`가 잡는다. 한계는 타입 주석에 적혀 있다: 표시 없이 아무것도 안 하는 손 검증기는 못 찾는다(`external-contract-runtime.ts:61-67`). 생략 전환이 레지스트리 행에 남지 않는 것은 07-01에 적었다 |
| 1101/07-04 | `TEMPLATE_FIXTURE`를 아무 기능이나 쓸 수 있다 | **고쳐짐** | fixture id에서 주인 기능을 뽑아 다른 `featureId`를 거부하고, fixture 기여는 하나만 허용한다(`external-contract-runtime.ts:852-873`). 변이 M5·M6이 각각 `external-contract-runtime.test.ts`, `reference-fixture-provenance.test.ts`에서 죽었다 |
| 1101/07-05 | 오류 어휘 둘(`AppFailure`·`AppError`)과 두 "retry"의 관계가 타입 옆에 없다 | **남음** · Low · P3 | `AppFailure` 정의(`errors.ts:121-136`)와 `retryable` 칸에 주석이 그대로 없다. `src/platform/errors/app-error.ts`도 그대로다 |
| 1101/07-06 | 조립기·선언 검증의 쓰기 API 규칙 5개가 테스트 없이 남았다 | **고쳐짐** | 변이 MX1(읽기의 command descriptor 금지), MX2(mapper 키), MX6(`NEVER`+재시도 예산), MX9(`KEYED` 복구 descriptor)가 모두 죽었다. MX5(V2 `KEYED_COMMAND` 정합)는 V2 코드가 없어져 해당 없음 |
| 1101/07-07 | `commandRecovery`를 실행기가 읽지 않고 수습 책임이 타입 옆에 없다 | **남음** · Low · P3 | `CommandRecoveryDescriptor`(`external-contract-runtime.ts:130-134`)에 주석이 없다. `src/`에서 읽는 곳은 플랫폼 개요 화면뿐이다(`platform-overview-page.tsx:303-305`) |
| P-07-01 | breaking 증거가 값과 묶이지 않는다 | **고쳐짐** | 증거에 `after` 값이 필요하고 다르면 실패한다(`registry-compatibility.ts:410-425`). 맞는 변경이 없는 증거 행도 실패한다(`:441-452`). 옛 X3 재실행: 다른 값의 증거로 경로 변경을 덮으려 하면 `evidence explains after=… the change is after=…`로 실패 |
| P-07-02 | nullable 전환·allowlist 확장을 breaking으로 본다 | **고쳐짐** | `isDeclaredNullableChange`, `onlyExtendsAllowedValues`(`registry-compatibility.ts:101-139`). 옛 X4 재실행: `errorSurface` 허용값 추가가 `allowed-values-extended additive` |
| P-07-03 | 기능 라우트 하나에도 governance allowlist를 고쳐야 한다 | **고쳐짐** | `paramsSchema`·`searchSchema` allowlist를 지우고 `loadingSurface`는 형식만 본다(`registry-governance.json:41-53`). 옛 X5 재실행: 새 loading surface 이름이 `behavior-change` PASS |
| P-07-04 | 다운스트림 증거 절차가 안내되지 않는다 | **고쳐짐** | 매뉴얼에 두 경로(재승인, 증거 행)가 있다(`docs/manual/01-add-a-feature.md:499-512`, `docs/manual/reference/errors.md:147-149`). 실패 메시지 자체는 여전히 changeId뿐이다(`registry-compatibility.ts:407`) |
| P-07-05 | `ENV_REGISTRY` runtime 행이 zod 스키마와 다르다 | **일부 고쳐짐** · Low · P3 | 스키마에만 있던 키 2개(`RELEASE_ID`, `BUILD_ID`)는 행이 생겼고 테스트가 스키마→행 방향을 지킨다(`tests/unit/env-registry-coverage.test.ts:10-18`). 남은 것: 값 불일치 5곳(E-1: `TELEMETRY_ENABLED`·`AUTH_MODE` default, `RELEASE_MANIFEST_URL` required, `CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` default). 반대 방향 검사 없음(E-2: 스키마에 없는 제품 행이 테스트와 `check:registries`를 통과). 제품 행의 required가 스키마와 달라도 통과(E-3). 실제 스키마 변경은 FE-GATE-014가 잡는다(E-3에서 `check-compatibility.ts` breaking 실패). 그래서 피해는 "스냅샷이 틀린 설명을 기록한다"에 그친다 |
| P-07-06 | zod facade 규칙이 `"zod"`만 막는다 | **남음** · Low · P3 | 규칙의 `to.path`가 `^zod$`다(`.dependency-cruiser.json:60-70`). Z1: `"zod/v4"` import에 `check:architecture` rc=0, `"zod"`는 `zod-is-reached-through-contracts-zod` 위반. eslint 규칙도 없다 |
| P-07-07 | CHANGELOG 0.2.0 [계약] 행이 레지스트리 분류기를 잘못 가리킨다 | **남음** · Low · P3 | `CHANGELOG.md:174`가 "레지스트리 호환성 분류기"라 적고 `src/contracts/compatibility.ts`(config 스키마 분류기)를 가리킨다. 레지스트리 분류기는 `scripts/lib/registry-compatibility.ts`다 |
| F-07-03 · F-07-07 | (지난 라운드에 1101/07-02·07-01로 합침) | 각각 위 행을 따른다 | — |
## 3. 이번 발견 (36.3)
### 3.1 발견 목록
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 07-01 | Medium | P2 | 확인된 결함 | 17, 21, 3, 5, 10, 13, 20, 22 | V2 행과 V2/V3 일치 테스트를 지우면서 V3 descriptor에 간접으로 걸리던 검사 3개가 사라졌고, 새 `problemSchema` 칸은 반만 잠겼다 |
| 07-02 | Low | P3 | 확인된 결함 | 10, 15, 21 | V2에서 옮긴 검사 두 개(쿠키 쓰기 CSRF, realtime snapshot operation)가 한 사례만 테스트된다 |
| 07-03 | Low | P3 | 구조적 위험 | 17, 23, 24, 10, 9 | FE-REG-SCHEMA 행의 `unknownFieldPolicy`·`direction`이 검증기와 묶이지 않은 손 사본이다 |
| 07-04 | Low | P3 | 구조적 위험 | 19, 8, 15, 20 | 제품 런타임 설정 키의 금지 이름 검사가 부팅 때만 돈다 |
| 07-05 | Low | P3 | 확인된 결함 | 20, 9, 4 | `starter-experience.md`가 지워진 V2 모양으로 `FeatureRuntime`을 설명한다 |
High 이상 발견은 없다. 남은 지난 발견(1101/07-05·07-07, P-07-05~07, 모두 Low)은 2절에 있다.
### 07-01 V2 행과 V2/V3 일치 테스트를 지우면서 V3 descriptor에 간접으로 걸리던 검사 3개가 사라졌고, 새 `problemSchema` 칸은 반만 잠겼다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (같은 변경을 이전 커밋 `d99301b`와 현재 커밋 `e40684b`에서 실행해 비교했다) |
| 관련 관점 | 17, 21, 3, 5, 10, 13, 20, 22 |
| 근거 | **지금:** FE-REG-API 행은 descriptor에서 12칸만 뽑는다(`src/contracts/api-operations.ts:15-28, 34-57`). `acceptedStatuses`, `emptyBodyStatuses`, `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`, `retryBudget`, `traffic`, `commandEffect`, `commandRecovery`, 검증 생략 표시(`validation`)는 행에 없다. `check:registries`는 breaking 변경만 실패시킨다. breaking 칸이 아닌 값 변경은 `behavior-change`로 통과한다(`scripts/lib/registry-compatibility.ts:346-351`, `scripts/check-registries.ts:650-680`). **이전:** V2 행 27칸 전부가 기준선 행 값이었다(`d99301b:config/contracts/registry-baseline.json` FE-REG-API rows). parity 테스트가 V3 `acceptedStatuses`↔V2 `successStatuses`, `responseByteLimit`↔`maxResponseBytes`, `retrySemantics`↔`replayPolicy`를 묶었다(`d99301b:tests/unit/http-operation-v2-v3-parity.test.ts:36-53`). V2 `defineRestOperation`은 QUERY에 `SAFE`·`IDEMPOTENT`만 허용했다(`d99301b:src/contracts/api-operations.ts:182-199`). **(a) 상태 목록 축소:** O1(이전 커밋) 생성 API의 V3만 `[200, 201]`→`[201]`이면 parity 테스트 실패. V2도 같이 바꾸면 `breaking change missing evidence: FE-REG-API:CREATE_REFERENCE_RESOURCE:successStatuses:allowed-value-removed`로 실패. X2(현재) 같은 변경에 `check:registries` PASS(FE-REG-API 변화 없음), 관련 77파일 885건 통과. `[200]`으로 줄이면 MSW가 201을 보내는 테스트 1건(`reference-runtime-composition.test.ts`)이 잡는다. 즉 그 status를 우연히 쓰는 테스트가 있을 때만 잡힌다. **(b) 응답 상한:** O2(이전) 두 사본을 32,768→8,388,608로 바꾸면 `maxResponseBytes:field-changed behavior-change`가 스냅샷에 남는다. X3(현재) 같은 변경이 스냅샷에 아무것도 남기지 않는다. 마감 6배(X6, 옛 L3)도 그대로 통과한다. **(c) 읽기의 재시도 의미:** R1 GET에 `retrySemantics: "KEYED"`(`commandRecovery` 없음)나 `"NEVER"`를 적어도 조립되고 행에 그 값이 기록된다. `KEYED` 복구 descriptor 검사가 쓰기 분기 안에만 있다(`external-contract-runtime.ts:503-529`). 매뉴얼은 "읽기(GET)는 늘 `SAFE`다"(`docs/manual/02-decision-tables.md:83`), "`KEYED`에 `commandRecovery`가 없으면 거부한다"(`:106`)고 적는다. 실행기는 이 GET을 쓰기로 보지 않아(`src/adapters/http/http-execution-v3.ts:449-458`) 재시도 없는 읽기로 돈다. **(d) 새 칸 `problemSchema`:** `requiredFields`에는 있지만 `breakingFields`·`references`에는 없다(`config/contracts/registry-governance.json:135-229`). X4 세 operation의 problem 검증기 id를 바꿔도 `behavior-change` PASS, 관련 테스트 885건 통과. 기준선의 FE-REG-SCHEMA에 `ReferenceProblem` 행이 없다. 생성 뼈대와 두 번째 기능 테스트도 problem 스키마 행을 만들지 않는다(`scripts/create-feature.ts:597-625`, `tests/unit/second-api-feature-registries.test.ts:99-117`). **(e) 검증 생략:** X5 출력 검증기를 `unvalidatedPayload`로 바꿔도 행은 같다. 템플릿에서는 "생략 목록이 비어 있다"는 화면 테스트가 잡지만, 생략이 이미 있는 제품에서는 그 테스트가 다른 단언을 한다. **문서:** 매뉴얼은 "행을 빼거나 바꾸면 breaking 변경이다"(`01-add-a-feature.md:500`)라 적고, "못 잡는 것"에 행에 없는 칸을 적지 않는다. `12f3bb7` 본문과 README 14.7은 사라진 V2 동작 3개(401 재전송, KEYED 재시도, 보안 프로필)를 판정했지만 parity 테스트가 지키던 칸은 다루지 않았다 |
| 발생 조건 | 기능 작성자가 descriptor의 `acceptedStatuses`·`emptyBodyStatuses`를 줄이거나, 상한·마감·재시도 예산을 바꾸거나, problem 스키마를 바꾸거나, 검증을 생략으로 바꾸거나, GET에 `KEYED`를 적을 때 |
| 영향 | 짝 백엔드는 생성에 201, 본문 없는 응답에 204를 쓴다(백엔드 `docs/web/http-contract.md:32`). 이 status를 descriptor에서 빼면 그 API 호출이 배포 뒤 모두 실패한다. 리뷰어는 레지스트리 스냅샷에서 이 변경을 볼 수 없다. 쓰기라면 사용자는 결과 불명 화면을 본다. 같은 키 재전송 규칙이 중복 생성을 막는다(추론, 실행 안 함). 이 governance 정의는 모든 다운스트림에 그대로 복제된다 |
| 심각도·우선순위 | Medium · P2 — 데이터 손상은 없다. 그러나 V2 삭제 전에는 막던 wire 호환 변경이 지금은 어떤 게이트에도 걸리지 않는다는 것을 두 커밋에서 실행으로 확인했다. 짝 백엔드와 맞춰 빨리 출시한다는 목표에서 status 목록은 자주 손대는 칸이다. 고치는 비용은 작다 |
| 통제·증거 | 목표 M3(wire 호환 칸이 스냅샷에 있고 축소는 breaking) / 확인: (a) M0(이전 M3), (b) M0(이전에는 기록만), (c) M1(매뉴얼만, 이전 M3 간접), (d) M1(기록만) · E2(O1, O2, X2, X3, X4, X5, X6, R1) |
| 확실성과 남은 가정 | 실행으로 확인했다. 짝 백엔드가 실제로 어떤 status를 쓰는지는 백엔드 문서로만 확인했다. 결과 불명 쓰기의 화면 동작은 영역 03·08 범위라 실행하지 않았다 |
| 결정의 근거 | 기록된 결정: "행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다"(`12f3bb7` 본문). 투영은 실행되는 값을 기록해 L1·L6을 풀었다. 확인한 사실: 투영 칸은 V2 governance의 `requiredFields`를 V3 이름으로 옮긴 것과 거의 같다. V2 행 값 전체가 기준선에 들어가던 효과와 parity 테스트의 연결은 옮기지 않았다. 리뷰어 추론: 칸 선택이 "V2 governance가 선언한 칸"을 기준으로 이뤄졌고 "V2 기준선이 실제로 기록하던 칸"은 기준이 되지 않았다 |
| 이해 비용 | 기능 작성자는 descriptor의 어느 칸이 레지스트리에 남는지 알려면 `api-operations.ts`와 governance JSON을 함께 읽어야 한다. 매뉴얼은 반대로 "바꾸면 breaking"이라고 말한다 |
| 최소 개선 방향 | (1) 투영에 `acceptedStatuses`, `emptyBodyStatuses`, `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`, `retryBudget`, `responseValidation`(`validation === "NONE"`이면 `"NONE"`, 아니면 `"SCHEMA"`)을 더한다. 배열 칸의 항목 제거는 지금 분류기가 이미 breaking으로 본다(`registry-compatibility.ts:329-342`). `acceptedStatuses`·`emptyBodyStatuses`·`responseValidation`은 `breakingFields`에 넣고, 숫자 칸은 behavior-change로 기록만 한다. (2) 조립기에서 GET·HEAD는 `SAFE`·`IDEMPOTENT`만 허용한다. (3) `problemSchema`를 `breakingFields`에 넣는다. FE-REG-SCHEMA 참조까지 걸려면 boundary 값(예: `api-problem`)과 뼈대의 스키마 행이 필요하다. 이것은 선택이다. (4) 매뉴얼 01 ③에 "행에 없는 descriptor 칸(`commandEffect`, `commandRecovery`, `traffic`)은 PR에서 본다"를 적는다 |
| 대안 비교 | 5.1절. (A) 현 상태: 비용 0, 빈틈 그대로. (B) 위 (1)~(4): 칸 몇 개와 기준선 재승인 1회. (C) descriptor 전체(함수 제외)를 행으로 투영: 빠진 칸이 없지만 `traffic`·`policyId`처럼 리뷰 가치가 낮은 값까지 기준선이 흔들린다. (D) V2/V3 parity 테스트를 되살림: 두 사본이 다시 생겨 사용자 지시(사본 하나)와 반대다 |
| 단순화의 보존 조건 | operation은 descriptor 한 곳에만 쓴다. 검증기 schemaId 변경은 breaking이고 FE-REG-SCHEMA를 참조한다(X1). 새 operation은 additive다. `responseEnvelope`는 생략과 `"NONE"`이 같은 행이고 변경은 breaking이다(X7) |
| 비용·부작용 | governance 계약(`requiredFields`·`breakingFields`) 변경은 `contract-field-changed` breaking이라 기준선 재승인 1회가 필요하다. 행 칸 추가 자체는 `field-added` additive다. 다운스트림은 동기화 때 재승인 1회 |
| 재검토 조건 | 계약 패키지(`@org-contracts/*`)가 descriptor를 생성해 배포하고 패키지 쪽에 호환 검사가 생기면, 프론트 레지스트리는 패키지 identity와 operation id만 기록해도 된다 |
| 완료 기준 | X2(`[201]`), X4, R1을 다시 하면 실패한다. X3·X6은 `behavior-change`로 스냅샷에 남는다. X5는 breaking으로 실패한다 |
| 검증 방법 | 위 실험 재실행. `tests/unit/api-operation-rows.test.ts`에 새 칸을 고정. `tests/unit/external-contract-runtime.test.ts`에 "GET + KEYED 거부" 사례 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 미실시 |
### 07-02 V2에서 옮긴 검사 두 개(쿠키 쓰기 CSRF, realtime snapshot operation)가 한 사례만 테스트된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (테스트 공백, 변이로 재현) |
| 관련 관점 | 10, 15, 21 |
| 근거 | **CSRF:** 조립기가 쿠키 프로필로 쓰기(GET·HEAD 밖)를 하면서 `x-csrf-token`·`x-xsrf-token`을 요구하지 않는 operation을 거절한다(`external-contract-runtime.ts:543-556`, `365d8c3`). 테스트는 POST 하나, 필수 헤더 `[]` 대 `["x-xsrf-token"]` 하나다(`tests/unit/rest-profile-contract.test.ts:65-107`). 변이 M1(검사 삭제)은 죽었다. M2(`!isRead`를 `method === "POST"`로) 생존: PUT·PATCH·DELETE가 검사에서 빠져도 모른다. M3(CSRF 헤더 이름 검사를 "필수 헤더가 하나라도 있으면"으로) 생존: `x-tenant-context`만 요구하는 쿠키 쓰기 프로필이 통과해도 모른다. **Realtime snapshot:** `validSnapshotBindings`의 조건이 V2 `QUERY`·`replayPolicy`에서 `method === "GET"`·`retrySemantics`로 바뀌었다(`src/contracts/realtime-streams.ts:458-475`). M9(method 조건 삭제)·M9b(method·retrySemantics 조건 모두 삭제) 생존. **범위 메모(이 문서에서 세지 않음):** CSRF 검사는 descriptor HTTP만 본다. resumable upload 제어 요청은 쿠키를 늘 싣고(`credentials: "include" | "same-origin"`) POST하지만 CSRF 헤더를 요구하지 않는다(`src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts:34, 236-241`). 영역 01에 넘긴다 |
| 발생 조건 | 조립기나 realtime 등록 코드를 고칠 때 조건 일부가 빠지는 경우 |
| 영향 | CSRF: 쿠키 인증 PUT·PATCH·DELETE가 CSRF 헤더 없이 나가는 회귀를 CI가 모른다. 쿠키 인증 제품에서 다른 사이트가 사용자의 쓰기를 대신 보낼 수 있게 된다. Realtime: 쓰기 operation을 snapshot으로 등록해 재연결 때마다 쓰기를 보내는 회귀를 모른다 |
| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 회귀를 못 잡는 위험이다. CSRF는 보안 경계라 같은 P3 안에서 먼저 한다 |
| 통제·증거 | 목표 M3 / 확인 M2(구현), 검출은 M1 변이만 · E2(M1~M3, M9, M9b) |
| 확실성과 남은 가정 | 관련 77파일로 돌렸다. e2e·system은 돌리지 않았다. 조립 단위 규칙이라 그쪽에서 잡힐 가능성은 낮다고 봤다. V2 시절 snapshot 조건이 테스트됐는지는 미확인이라 "약해졌다"고 판정하지 않는다 |
| 결정의 근거 | 적용 제외 — 규칙은 정해져 있고 테스트 사례만 빠졌다 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | `rest-profile-contract.test.ts`에 PUT·PATCH·DELETE 각각 거부, `x-tenant-context`만 요구하는 쿠키 쓰기 거부, `x-csrf-token` 허용을 더한다. realtime 등록 테스트에 POST snapshot operation 거부, GET + `KEYED` snapshot 거부를 더한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 사례 6개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | M2, M3, M9, M9b가 모두 죽는다 |
| 검증 방법 | 6절 변이 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규. upload 제어 요청은 영역 01 |
| 재검증 결과 | 미실시 |
### 07-03 FE-REG-SCHEMA 행의 `unknownFieldPolicy`·`direction`이 검증기와 묶이지 않은 손 사본이다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (지난 1101/07-02의 L7 부분이 남았다) |
| 관련 관점 | 17, 23, 24, 10, 9 |
| 근거 | 참조 기능 메타데이터는 응답 스키마를 `STRIP_UNKNOWN`이라 적는다(`src/features/reference-feature/contracts/reference-schema-metadata.ts:35-52`). 실제 정책은 zod `.strip()`이다(`reference-schemas.ts:26-33`). `unknownFieldPolicy`·`direction`을 읽는 실행 코드는 없다. 타입(`schema-registry.ts:15-16`), 메타데이터, 생성 뼈대만 있다. X8: `.strip()`을 `.strict()`로 바꿔도 `check:registries` PASS, 관련 77파일과 `tests/runtime-schema`·`contract`·`features` 27파일이 통과한다. `docs/contracts/compatibility.md:28`은 이 경계를 "additive"라고 적는다. V2 삭제 뒤 FE-REG-API가 검증기 schemaId를 뽑아 FE-REG-SCHEMA를 참조하므로 id 연결은 생겼다(X1). 내용 연결은 없다 |
| 발생 조건 | 기능 작성자가 응답 스키마를 `.strict()`로 바꾸거나, 생성 뼈대의 `STRIP_UNKNOWN` 행을 그대로 두고 스키마를 엄격하게 만들 때 |
| 영향 | 백엔드가 응답에 필드 하나를 더할 때마다 그 API가 `SCHEMA_MISMATCH`로 실패한다. 스냅샷과 호환 문서는 여전히 additive라 말한다. 짝 백엔드와 따로 배포하면 백엔드 배포 직후 화면이 깨진다 |
| 심각도·우선순위 | Low · P3 — 실행 동작은 zod가 정하고 코드에서 보인다. 틀린 것은 기록이다. 다만 호환 문서의 주장을 잠그는 테스트가 없다 |
| 통제·증거 | 목표 M3(정책 기록과 실제 스키마의 대조) / 확인 M1(선언만) · E2(X8) |
| 확실성과 남은 가정 | 실행으로 확인했다. 생성 뼈대가 만드는 DTO 스키마의 정책은 읽지 않았다 |
| 결정의 근거 | 기록된 결정: `12f3bb7`은 스키마 메타데이터를 검증기에서 뽑지 않았다. "boundary·unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다." 리뷰어 판단: 이 이유는 타당하다. 빠진 것은 손 사본과 실제 정책의 대조다 |
| 이해 비용 | 기능 작성자는 메타데이터의 `unknownFieldPolicy`가 아무 효과가 없다는 것을 코드를 찾아봐야 안다 |
| 최소 개선 방향 | 가장 작은 것: 참조 기능 테스트에 "응답에 모르는 필드를 하나 더해도 통과한다" 1건을 더해 `compatibility.md:28`을 잠근다. 구조: 응답 스키마마다 모르는 키 하나를 넣은 값으로 검증기를 돌려 메타데이터의 `unknownFieldPolicy`와 맞는지 보는 테스트 하나(`env-registry-coverage`와 같은 방식) |
| 대안 비교 | (A) 현 상태. (B) 위 테스트: 검증기 한 번씩 호출, 실행 비용 거의 없음. (C) 메타데이터에서 `unknownFieldPolicy`·`direction`을 지움: 읽는 곳이 없어 가장 단순하지만 기준선 행 값이 바뀌어 재승인이 필요하고 호환 문서의 근거가 사라진다 |
| 단순화의 보존 조건 | FE-REG-SCHEMA의 `schemaId`·`boundary`·`runtime` breaking 판정과 FE-REG-API 참조 검사가 유지된다 |
| 비용·부작용 | (B) 테스트 1개 |
| 재검토 조건 | 검증기가 정책을 스스로 보고하게 되면(외부 계약 패키지의 생성 검증기 등) 메타데이터 칸을 검증기에서 뽑는다 |
| 완료 기준 | X8을 다시 하면 테스트가 실패한다 |
| 검증 방법 | X8 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 (1101/07-02 L7에서 이어짐) |
| 재검증 결과 | 미실시 |
### 07-04 제품 런타임 설정 키의 금지 이름 검사가 부팅 때만 돈다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (실험으로 재현, 실제 제품 피해는 미확인) |
| 관련 관점 | 19, 8, 15, 20 |
| 근거 | 금지 조각(`PASSWORD`, `SECRET`, `TOKEN`, `COOKIE`, `AUTHORIZATION` 등, `src/contracts/env.ts:7-17`) 검사 `assertSafeConfigNames`(`:108-129`)는 부팅 때 한 곳에서만 부른다(`src/bootstrap/load-runtime-config.ts:119`). 빌드의 config 생성은 zod 스키마만 본다(`scripts/generate-runtime-config.ts:78-85`). FE-REG-ENV 범위 테스트(`env-registry-coverage.test.ts`)와 `check:registries`도 이름 조각을 보지 않는다. `ece944d`는 제품이 템플릿 파일을 고치지 않고 키를 더하는 길(`product-contracts.ts`의 `PRODUCT_RUNTIME_CONFIG_FIELDS`, `PRODUCT_ENV_REGISTRY`)을 열었다. 그 파일 주석(`product-contracts.ts:1-16`)에는 이름 규칙이 없다. **E-4:** 제품 키 `PRODUCT_COOKIE_NOTICE`(zod 필드 + FE-REG-ENV 행 + `config/runtime/local.json` 값)를 더했다. `generateRuntimeConfig("local")` 통과, 범위 테스트 통과, `check:registries` additive PASS. 같은 config에 `assertSafeConfigNames`는 `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE`로 던진다. 부팅 오류는 키 이름 없이 `CONFIG_SECRET_NAME_REJECTED`만 남긴다(`load-runtime-config.ts:118-124`) |
| 발생 조건 | 쿠키 세션이나 토큰을 쓰는 제품이 `SESSION_COOKIE_NAME`, `CSRF_TOKEN_HEADER`처럼 금지 조각이 든 설정 키를 더할 때(이름 예는 리뷰어 추론) |
| 영향 | 그 키가 든 `config.json`으로 배포하면 모든 사용자가 부팅 실패 화면을 본다. 로컬 개발도 같은 부팅 경로를 지나므로 처음 실행할 때 드러날 가능성이 높다(추론, `dev` 서버는 띄우지 않음). 오류 코드에 키 이름이 없어 원인을 찾는 데 시간이 든다 |
| 심각도·우선순위 | Low · P3 — 비밀 노출을 막는 규칙은 부팅 경계에서 지켜진다. 문제는 늦게, 이유 없이 드러난다는 것이다 |
| 통제·증거 | 목표 M3(빌드·CI에서 이름 규칙 검출) / 확인: 부팅 경계 M4, 빌드·CI 검출 M0 · E2(E-4) |
| 확실성과 남은 가정 | 실험은 템플릿 파일만 바꿔 했다. 다운스트림에 이런 키가 있는지는 보지 않았다 |
| 결정의 근거 | 적용 제외 — 규칙은 정해져 있고 검사 위치만 늦다 |
| 이해 비용 | 제품 작성자는 `env.ts`의 금지 목록을 읽어야 규칙을 안다 |
| 최소 개선 방향 | (1) `env-registry-coverage.test.ts`에 스키마 키와 FE-REG-ENV runtime 키 전부를 `assertSafeConfigNames`로 검사하는 사례 하나. (2) `product-contracts.ts` 주석에 금지 조각 한 줄. (3) `CONFIG_SECRET_NAME_REJECTED`에 거절한 키 이름을 싣는다. 키 이름은 공개 `config.json`에 이미 있는 값이라 비밀이 아니다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 1건, 주석 1줄, 오류 상세 1칸 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-4를 다시 하면 범위 테스트가 실패하고 키 이름을 말한다 |
| 검증 방법 | E-4 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 (`ece944d` 이후 생긴 경로, 영역 09와 함께) |
| 재검증 결과 | 미실시 |
### 07-05 `starter-experience.md`가 지워진 V2 모양으로 `FeatureRuntime`을 설명한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서와 코드 불일치) |
| 관련 관점 | 20, 9, 4 |
| 근거 | `docs/architecture/starter-experience.md:135-137`은 `defineFeatureRuntime`이 "the API contract (operations, schema metadata, runtime schemas, mappers)"를 받는다고 적는다. 실제 타입은 `schemas`, `adapters`, `contractContributions`만 받는다(`src/features/feature-module.ts:51-65`). operations·runtime schemas·mappers는 `12f3bb7`에서 지워졌다. 같은 단계 뒤쪽(`:144-149`)은 새 모양을 맞게 적어 한 단계 안에서 서로 다르다. `verify:documentation`은 산문을 대조하지 않아 통과한다 |
| 발생 조건 | 기능 추가를 이 문서로 시작하는 사람 |
| 영향 | 없는 필드를 찾다가 시간을 쓴다. 타입 검사가 잘못된 필드를 막으므로 런타임 피해는 없다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M1(문서가 코드와 같음) / 확인 M1(일부 틀림) · E1 |
| 확실성과 남은 가정 | 영역 14가 같은 줄을 적었다면 하나로 센다 |
| 결정의 근거 | 적용 제외 — 문서 정정 |
| 이해 비용 | 적음 |
| 최소 개선 방향 | 괄호를 "schema metadata (`schemas`, FE-REG-SCHEMA rows)"로 고친다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `grep -n "runtime schemas, mappers" docs/architecture/starter-experience.md`가 0건 |
| 검증 방법 | grep, `verify:documentation` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 미실시 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | 적용. 조립기가 계약 규칙의 유일한 입구다 | M4 / M3 | E2(M1~M9b, MX, R1) | P — 복사 후 검증, Envelope 값 검사, fixture 주인 검사가 있다. GET + `KEYED`가 매뉴얼 규칙과 달리 조립된다(07-01 c) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(`check:architecture` rc=0, 오케스트레이터) | O — 계약은 application·presentation·bootstrap을 import하지 않는다. 이번 diff에서 새 간선 없음 |
| **3** | 변경 용이성 | 적용. 렌즈 과제 "API 하나 추가·변경" | M3 / M2 | E2(X1, X2, second-api 테스트) | P — API 하나의 작성 위치가 7곳에서 4곳(descriptor, 스키마 메타데이터, zod 스키마, mapper)으로 줄었다. 상태 목록·상한 변경은 검출되지 않는다(07-01) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — V2/V3 두 이름 체계가 HTTP에서는 사라졌다. 오류 어휘 둘(1101/07-05), 같은 이름 `MappingResult` 둘(lint가 import만 막음) |
| 5 | 위험 가시성 | 적용 | M2 / M2 | E2(X5) | P — 검증 생략이 이름과 목록으로 드러난다. 레지스트리가 보지 않는 칸이 매뉴얼에 없다(07-01). `commandRecovery`를 누가 읽는지 타입 옆에 없다(1101/07-07) |
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | O — 조립 실패는 부팅을 멈추고 operation·method·프로필 이름을 말한다. 금지 설정 키는 부팅에서 막힌다(늦음은 07-04) |
| 7 | 운영 성숙도 | 다른 영역 | - | - | > 영역 03·13 |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2(E-4) | P — CSRF·fixture 거절 메시지가 고칠 곳을 말한다. `CONFIG_SECRET_NAME_REJECTED`는 키 이름을 버린다(07-04) |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — 낡은 문서 줄(07-05), CHANGELOG 행(P-07-07), 메타데이터 손 사본(07-03) |
| 10 | 테스트 성숙도 | 적용 | M3 / M2 | E2(변이 14종) | P — 14종 중 10종이 죽었다. 생존 4종은 CSRF 2, realtime snapshot 2(07-02). 게이트를 통과하는 계약 변경 실험 5개(X2·X3·X4·X6·X8) |
| 11 | 데이터 성숙도 | 다른 영역 | - | - | > 영역 05 |
| 12 | 동시성 성숙도 | 적용 제외. 계약은 순수 선언과 검사다 | - | - | - |
| 13 | 확장성 | 적용 | M2 / M2 | E2(second-api 테스트) | P — 기능 추가에 governance 수정이 없다. API 수에 비례해 레지스트리 밖 칸의 사람 리뷰가 는다(07-01) |
| 14 | 성능 성숙도 | 적용(게이트 범위) | - / - | E2(`check:bundle` 201,848 / 204,800 B, 오케스트레이터) | O — V2 코드 삭제로 초기 JS가 줄었다(README 14.7). 이번에 따로 재지 않았다 |
| 15 | 보안 성숙도 | 적용 | M4 / M3 | E2(M1~M3, Z1, E-4) | P — 쿠키 쓰기 CSRF 조립 검사가 생겼다. 테스트는 POST 한 사례(07-02). upload 제어 요청은 영역 01. zod subpath 빈틈(P-07-06) |
| 16 | 의존성 성숙도 | 다른 영역 | - | - | > 영역 13 |
| **17** | API / Contract 성숙도 | 적용 | M3 / M3(부분) | E2(X1~X8, O1, O2, R1) | P — 레지스트리가 실행되는 descriptor를 기록한다(큰 개선). V2 parity가 지키던 status·상한·읽기 의미가 빠졌고 `problemSchema`는 반만 잠겼다(07-01). 스키마 정책은 손 사본(07-03). Envelope 칸은 잘 잠겼다 |
| 18 | 배포 성숙도 | 다른 영역 | - | - | > 영역 13. fixture 기여가 계약 집합에서 조용히 빠지던 문제(1101/07-04)는 닫혔다 |
| **19** | 설정 성숙도 | 적용 | M3 / M2 | E2(E-1~E-4) | P — 스키마 키마다 FE-REG-ENV 행이 있다. 행 값 5곳이 스키마와 다르고 반대 방향 검사가 없다(P-07-05). 금지 이름 검사가 늦다(07-04). 스키마 자체는 FE-GATE-014가 잠근다 |
| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | P — 매뉴얼이 Envelope·검증 생략·증거 절차를 안내한다. "바꾸면 breaking"이 실제보다 넓다(07-01). 낡은 문서 줄(07-05) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E2 | P — breaking 칸 10개와 참조 검사는 동작한다. parity 경유 검사 손실(07-01), CSRF 테스트 공백(07-02), zod subpath(P-07-06) |
| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E2 | P — 실행되지 않던 V2 층을 지워 추상화가 하나 줄었고 보호 기능 대부분이 유지됐다. 줄일 때 parity가 하던 일 일부를 옮기지 않았다(07-01). 스키마 메타데이터 층은 남았다(07-03, 남길 근거 있음) |
| **23** | 일관성 | 적용 | M2 / M1 | E1 | P — HTTP는 `KEYED`·`NEVER` 한 체계다. Browser RPC는 여전히 `KEYED_COMMAND`·`NON_REPLAYABLE`이다(`src/contracts/browser-rpc.ts:51-52`). 오류 어휘 둘(1101/07-05) |
| **24** | 네이밍 / 의미 성숙도 | 적용 | M2 / M1 | E1 | P — `retryable`과 `action: "retry"`(1101/07-05), `commandRecovery`(1101/07-07). `SAME_ORIGIN_COOKIE` 전송은 `credentials: "include"`도 허용해 이름보다 넓다(`rest-profiles.ts:177-183`). `unknownFieldPolicy`라는 이름이 효과 없는 칸이다(07-03) |
| 25 | 조직 확장성 | 적용 | M2 / M2 | E2(second-api 테스트) | O — 기능 팀이 governance JSON이나 기준선을 고치지 않고 API·라우트·무효화를 더한다 |
| 26 | Ownership 성숙도 | 적용 | M2 / M2 | E1 | P — 폐기 별칭은 owner·제거 조건이 있고 저장소 안 import는 lint가 막는다. 재승인 기록에 owner·이유가 있다. 오래된 CHANGELOG 행 정리 책임은 없다(P-07-07) |
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | P — V2 경로를 이름 목록과 옮기는 법을 남기고 지웠다(CHANGELOG `12f3bb7` 행). `composeBoundaryMapperRegistry`는 `src` 호출처가 없다. realtime recipe용 확장 지점으로 본다. 샘플 제거 드릴은 이번에 돌리지 않았다 |
| 28 | 회복 가능성 | 적용 제외. 계약은 복구 절차를 소유하지 않는다 | - | - | - |
X(미충족)인 관점은 없다.
## 5. 설계 선택 검토 (41절)
### 5.1 FE-REG-API 행을 descriptor에서 투영하고 12칸만 기록한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 짝 백엔드와 맞는 wire 계약(메서드·경로·스키마·인증·재전송·응답 모양·상태)이 PR에서 식별돼야 한다. 사본은 하나여야 한다(사용자 지시) |
| 2. 지킬 성질 | (a) 실행되는 operation은 모두 행이 있다. (b) 행 값은 실행되는 값과 같다. (c) wire 호환을 깨는 변경은 breaking이다 |
| 3. 현재 보장 | (a)(b)는 지켜진다(X1, `api-operation-rows.test.ts:72-79`). (c)는 10개 breaking 칸에서만 지켜진다. 상태 목록·상한·마감·재시도 예산·검증 생략·problem 스키마는 보장하지 않는다(07-01) |
| 4. 현실적인 대안 | (A) 현 상태. (B) wire 호환 칸 몇 개 추가(07-01 최소 개선). (C) 함수를 뺀 descriptor 전체 투영. (D) V2 행 부활 + parity |
| 5. 대안의 비용 | (A) 0, 빈틈 그대로. (B) 칸 6~7개, 재승인 1회. 정책 값 조정이 behavior-change로 보인다. (C) 빠짐 없음. `policyId`·`traffic`·`diagnosticsOperation`까지 기준선이 흔들려 리뷰 잡음이 늘어난다. (D) 사본 둘과 parity 테스트가 다시 생긴다. 사용자 지시와 반대다 |
| 6. 현재 조건에서의 선택 | 투영(사본 하나)은 유지한다. 칸 선택은 (B)로 넓힌다. 확인한 조건에서 status 목록은 짝 백엔드(201·204)와 직접 맞물리는 칸이고, 예전에는 막혔다가 지금 빠진 것이 실행으로 확인됐다 |
| 7. 재검토 조건 | 계약 패키지가 descriptor를 생성·배포하고 패키지 쪽 호환 검사가 생기면 프론트 행은 identity 중심으로 줄인다. behavior-change 칸이 리뷰 잡음이 된다는 측정이 나오면 숫자 칸을 뺀다 |
### 5.2 `responseEnvelope`를 선택 칸으로 두고 생략을 `"NONE"`으로 읽는다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 짝 백엔드의 Envelope(`{success, data\|error, meta}`)를 읽는다. 감싸지 않는 백엔드도 operation 단위로 지원한다 |
| 2. 지킬 성질 | 모드가 바뀌면 리뷰에서 보인다. 허용되지 않은 값은 부팅 전에 거절된다 |
| 3. 현재 보장 | 값 검사(`external-contract-runtime.ts:486-492`, M4 죽음). 생략과 `"NONE"`은 같은 행(`api-operations.ts:49`, X7a). 모드 변경은 breaking(X7b). 생성 뼈대는 `"ENVELOPE_V1"`을 적는다(`scripts/create-feature.ts:674-676`). **보장하지 않는 것:** 참조 기능을 복사한 기능이 짝 백엔드에 붙으면 첫 호출에서 `SCHEMA_MISMATCH`로 실패한다. 조용히 틀리지는 않는다(DTO 필수 칸이 Envelope 최상위에 없다) |
| 4. 현실적인 대안 | (A) 현 상태. (B) 필수 칸으로 바꿔 모든 descriptor가 모드를 적게 한다. (C) 기본값을 `"ENVELOPE_V1"`로. (D) 참조 기능을 Envelope로 옮긴다 |
| 5. 대안의 비용 | (B) 참조 기능·테스트 fixture·recipe의 descriptor를 모두 고친다. "고르지 않음"이 사라진다. (C) 생략한 기존 descriptor 전부의 동작이 조용히 바뀐다. 호환 위반이다. (D) 참조 기능의 problem 스키마·`mapProblem`·MSW 본문을 바꾼다(README 14.6 "남은 것") |
| 6. 현재 조건에서의 선택 | (A)는 유지할 근거가 있다. 기존 descriptor의 동작이 바뀌지 않고, 생성 뼈대와 매뉴얼(`01-add-a-feature.md:188-215`)이 짝 백엔드 경로를 안내한다. 남은 위험은 "가장 많이 복사되는 샘플"(가이드 30.5)이 짝 백엔드 모양이 아니라는 것이다. 이 영역에서는 결함으로 세지 않고 영역 판정 조건 (3)으로 둔다 |
| 7. 재검토 조건 | 다운스트림이 참조 기능을 복사해 짝 백엔드에 붙이다 막힌 사례가 나오면 (D)를 먼저 한다. 감싸지 않는 백엔드 지원을 끊기로 하면 (B)로 간다 |
### 5.3 쿠키 쓰기 CSRF 검사를 조립 시점, operation 단위로 둔다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 쿠키로 인증하는 쓰기 요청은 페이지만 넣을 수 있는 헤더를 싣는다. 짝 백엔드는 `x-xsrf-token`을 쓴다 |
| 2. 지킬 성질 | 쿠키 프로필 + GET·HEAD 밖 method인 operation은 CSRF 헤더를 필수로 요구하는 프로필만 쓴다 |
| 3. 현재 보장 | 조립기가 같은 프로필 레지스트리(`INSTALLED_REST_AUTH_PROFILES`, 실행기도 같은 객체, `runtime-adapters.ts:479`)로 검사한다. 쿠키를 싣는 전송은 `SAME_ORIGIN_COOKIE`뿐이다(다른 전송은 `credentials: "omit"` 강제, `rest-profiles.ts:158-186`). 실행기는 필수 헤더가 없으면 fetch를 하지 않는다. **보장하지 않는 것:** 헤더 값이 맞는 토큰인지(서버 책임), descriptor 밖의 쿠키 POST(upload 제어 요청), 테스트되지 않은 method·헤더 조합(07-02) |
| 4. 현실적인 대안 | (A) 조립 시점, operation 단위(현 상태). (B) 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구. (C) 요청 시점 검사 |
| 5. 대안의 비용 | (B) 읽기 전용 쿠키 프로필까지 막는다. method는 operation에만 있다. (C) 설정 실수가 사용자 요청 때까지 숨는다 |
| 6. 현재 조건에서의 선택 | (A)가 타당하다. 설정 실수를 부팅 전에 잡고 읽기 쿠키 프로필을 허용한다. 보강할 것은 테스트 사례다(07-02) |
| 7. 재검토 조건 | 쿠키 쓰기를 descriptor 밖에서 보내는 recipe(upload 등)를 기본 제공하게 되면, 같은 규칙을 그 전송 설정에도 건다 |
## 6. 실험·변이 기록
모든 실험은 격리 worktree에서 했다. 각 실험 뒤 `git checkout -- src config`(또는 스크립트가 원본을 다시 썼다)로 되돌렸다. 커밋하지 않았다. "관련 테스트"는 이 영역 모듈·참조 기능·HTTP 어댑터·realtime 계약을 import하는 77파일 885건이다. 변경 없이 17.2초에 모두 통과했다. 레지스트리 검사는 `node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts`다. 변경 없을 때 `11 registries PASS; compatibility=additive`(FE-REG-ENV `BUILD_ID`·`RELEASE_ID` 행 추가 2건)다. 실험 스크립트는 오케스트레이터 scratchpad의 `r07/`에 있다.
### 6.1 계약 변경 실험
| ID | 커밋 | 무엇 | 결과 |
|---|---|---|---|
| X1 | e40684b | GET 출력 검증기 schemaId를 `"Whatever"`로(옛 L1) | **실패(잡힘).** `references unknown FE-REG-SCHEMA.schemaId=Whatever`, `responseSchema:field-changed` breaking 증거 누락 |
| X2 | e40684b | 생성 API `acceptedStatuses` `[200, 201]`→`[201]` | **통과.** 레지스트리 FE-REG-API 변화 없음. 관련 테스트 885건 통과 |
| X2b | e40684b | 같은 칸 → `[200]` | 관련 테스트 1건 실패(`reference-runtime-composition.test.ts`, MSW가 201을 보냄). 레지스트리는 통과 |
| O1 | d99301b | X2를 V3만 / V2·V3 둘 다 | V3만: parity 테스트 실패. 둘 다: `successStatuses:allowed-value-removed` breaking 증거 누락으로 실패 |
| X3 | e40684b | GET `responseByteLimit` 32,768→8,388,608 | **통과.** 스냅샷에 기록 없음. 관련 테스트 통과 |
| O2 | d99301b | X3를 두 사본에 | parity 통과, 스냅샷에 `maxResponseBytes:field-changed behavior-change` 기록 |
| X4 | e40684b | problem 검증기 id `ReferenceProblem`→`WhateverProblem` | **통과.** `problemSchema:field-changed behavior-change` 3건. 관련 테스트 885건 통과 |
| X5 | e40684b | GET 출력 검증기를 `unvalidatedPayload`로(id 같음) | 레지스트리 통과. `starter-platform-overview-page.test.tsx` 1건 실패(템플릿의 "생략 없음" 단언) |
| X6 | e40684b | GET `totalDeadlineMs` 10,000→60,000(옛 L3) | **통과.** 레지스트리·관련 테스트 모두 |
| X7a | e40684b | GET에 `responseEnvelope: "NONE"` 명시 | 행 변화 없음(생략과 같음) |
| X7b | e40684b | 같은 칸을 `"ENVELOPE_V1"`로 | **실패(잡힘).** `responseEnvelope:field-changed` breaking 증거 누락 |
| X8 | e40684b | 응답 DTO `.strip()`→`.strict()`(옛 L7, 메타데이터는 `STRIP_UNKNOWN` 그대로) | **통과.** 레지스트리, 관련 77파일, `tests/runtime-schema`·`contract`·`features` 27파일 178건 |
| R1 | e40684b | 테스트 fixture의 GET을 `KEYED`(복구 descriptor 없음)·`NEVER`로 조립 | **둘 다 조립됨.** 행에 `retrySemantics: "KEYED"` 기록 |
| 옛 X3 | e40684b | 라우트 경로 변경 + 다른 `after` 값의 증거 행 | 실패(잡힘). `evidence explains after=… the change is after=…` |
| 옛 X4 | e40684b | FE-REG-ROUTE `errorSurface` 허용값 추가 | `allowed-values-extended additive` PASS |
| 옛 X5 | e40684b | `loadingSurface`를 새 이름으로 | `behavior-change` PASS |
| Z1 | e40684b | 참조 기능 한 파일의 import를 `"zod/v4"`로 / `"zod"`로 | `"zod/v4"`: `check:architecture` rc=0. `"zod"`: `zod-is-reached-through-contracts-zod` 위반 |
| L-1 | e40684b | 참조 mapper에 `import type { MappingResult } from ".../boundary-mapper.ts"` | eslint `no-restricted-imports` 오류(잡힘) |
### 6.2 설정(FE-REG-ENV) 실험
| ID | 무엇 | 결과 |
|---|---|---|
| E-1 | FE-REG-ENV runtime 행과 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, {io: "input"})` 비교(`r07/env-vs-zod.ts`) | 행 13, 스키마 키 13. 불일치 5곳: `TELEMETRY_ENABLED` default(행 false, 스키마 없음), `AUTH_MODE` default(행 "external", 스키마 없음), `RELEASE_MANIFEST_URL` required(행 true, 스키마 선택), `CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` default(행 null, 스키마 객체) |
| E-2 | 제품 FE-REG-ENV 행만 추가(zod 필드 없음) | 범위 테스트 통과, `check:registries` additive PASS. E-1이 "스키마 키 없는 행"을 보고 |
| E-3 | 제품 zod 필드 `z.string().min(1)`(필수) + 행 `required: false` | 범위 테스트·`check:registries` 통과. `node scripts/check-compatibility.ts`는 breaking으로 실패(FE-GATE-014가 스키마를 잠근다) |
| E-4 | 제품 키 `PRODUCT_COOKIE_NOTICE`(zod + 행 + `config/runtime/local.json`), `r07/env-name.ts` | `generateRuntimeConfig("local")` 통과, 범위 테스트·`check:registries` 통과. `assertSafeConfigNames`는 `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE` |
### 6.3 변이 (관련 테스트 77파일)
| ID | 변이 | 결과 | 잡은 테스트 |
|---|---|---|---|
| M1 | CSRF 조립 검사 끔 | 죽음 | `rest-profile-contract.test.ts` |
| M2 | CSRF 검사를 POST만으로 | **생존** | — (07-02) |
| M3 | CSRF 헤더 이름 검사를 "필수 헤더가 하나라도 있으면"으로 | **생존** | — (07-02) |
| M4 | `responseEnvelope` 값 검사 끔 | 죽음 | `http-execution-v3-envelope.test.ts` |
| M5 | fixture 주인 기능 검사 끔 | 죽음 | `external-contract-runtime.test.ts` |
| M6 | fixture 기여 하나만 허용 검사 끔 | 죽음 | `reference-fixture-provenance.test.ts` |
| M7 | 투영의 `responseEnvelope`를 늘 `"NONE"`으로 | 죽음 | `api-operation-rows.test.ts` |
| M8 | 투영의 `problemSchema`를 출력 검증기 id로 | 죽음 | `api-operation-rows.test.ts` |
| M9 | realtime snapshot의 `method === "GET"` 조건 삭제 | **생존** | — (07-02) |
| M9b | realtime snapshot의 method·retrySemantics 조건 모두 삭제 | **생존** | — (07-02) |
| MX1 | 읽기 operation의 command descriptor 금지 삭제 | 죽음 | `external-contract-runtime.test.ts` |
| MX2 | mapper 레지스트리 키 = `mapperId` 검사 삭제 | 죽음 | `boundary-mapper.test.ts` |
| MX6 | `NEVER` + 재시도 예산 모순 거부 삭제 | 죽음 | `external-contract-runtime.test.ts` |
| MX9 | `KEYED` 복구 descriptor 필수 삭제 | 죽음 | `external-contract-runtime.test.ts` |
14종 중 10종이 죽었다. 지난 라운드에 살아남았던 MX1·MX2·MX6·MX9는 모두 죽었다(1101/07-06 고쳐짐). 이번에 옮겨진 검사 두 개(CSRF, realtime snapshot)에서 4종이 살아남았다.
@@ -0,0 +1,328 @@
# 08 presentation 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/presentation/` · 깊게 본 관점: 4, 5, 8, 14, 15, 23, 24
> 이번 라운드 렌즈: 폼이 서버 거절(필드 검증 400, 422, 결과 불명)을 어떻게 보이고 다시 저장하게 하는가 · 백엔드 필드 검증 code별 문구(`8a09c90`) · 라우트·레이아웃 충돌 검사(`7d85589`, `8469554`, `7c8cb19`, `27f4523`) · 접근성
> **영역 판정: 조건부 사용 가능.** 셸, 디자인 시스템, 읽기 화면, 필드 검증 400을 받는 폼은 쓸 수 있다. **짝 백엔드에 붙는 쓰기 폼은 해당 용도의 사용 보류(08-01을 고치기 전까지).**
## 0. 결론
- **지난 라운드 발견 9건(1101/08-01~08-09)은 모두 고쳐졌다.** 코드에서 하나씩 다시 확인했다. 지난 라운드에 살아남은 접근성 변이 4종(건너뛰기 링크, `aria-live`, 상태 제목, 사이드바 이름)은 이번에 모두 테스트에 잡혔다(6.1절).
- **필드 검증 400은 잘 된다.** 짝 백엔드의 `400 VALIDATION_FAILED` + 필드 목록이 V3 실행기 → 코디네이터 → 폼의 실제 경로로 필드 오류가 된다. 값을 고치면 새 키로 다시 저장된다(`form-foundation.test.tsx:811-837`). 백엔드 필드 code 20개는 모두 자기 문구가 있고, 백엔드 HEAD(`7ef8d0b4`)의 code 목록과도 같다(`8a09c90` 확인).
- **업무 규칙 거절은 막다른 길이다(08-01, High·P1).** 짝 백엔드가 `409 POSTER_ALREADY_EXISTS`, `409 DB_UNIQUE_VIOLATION`, `400 BAD_PARAMETER` 같은 거절을 보내면 폼은 "변경 결과를 확인할 수 없습니다."만 보인다. 거절 이유는 화면에 없다. 값을 고쳐도 저장 버튼은 꺼져 있다. "같은 요청으로 다시 보내기"는 백엔드에서 `500 IDEMPOTENCY_RECOVERY_REQUIRED`를 받아 다시 결과 불명이 된다. 남은 버튼 "변경됨으로 확인"을 누르면 저장되지 않은 입력이 지워지고 "저장했습니다"가 나온다. 기능이 매뉴얼대로 `mapProblem`으로 필드 오류를 만들어도 저장 버튼은 꺼진 채다. 화면을 떠났다 돌아와도 막힌 채다. 실제 실행기·바인딩·코디네이터·폼을 묶은 probe로 확인했다.
- 라우트 충돌 검사(`7d85589`, `8469554`)는 앱 조립 때 실패하는 방식이라 방향이 맞다. 다만 경로를 문자열로 비교해서 대소문자나 끝 슬래시만 다른 두 기능 라우트를 놓친다(08-04, Low). 라우터는 그중 하나만 그린다.
- **접근성.** 키보드로 저장했다가 필드 오류가 아닌 실패를 받으면 세 엔진 모두 포커스가 `body`로 떨어진다(08-02, Low·P2). 필드 오류일 때는 첫 필드로 간다(정상).
- 새 발견 6건: High 1(P1), Low 5(P2 1, P3 4). Critical·Medium 없음.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `e40684b`(브랜치 `review/2026-11-03-merged` = `claude/happy-easley-233d07` + `fix/ui-design-audit-2026-11-01`). 분리 worktree `agent-aa32fb83360602db8`, detached HEAD. 시작 때 작업 트리 깨끗함. 2026-11-03 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 사용자 목표: 짝 백엔드(`clean-architecture-backend-template`)와 함께 서비스를 빨리 출시 |
| 필수 요구와 규모·운영 목표 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어. 짝 백엔드 Envelope 계약(`docs/architecture/backend-api-and-server-state-contract.md` 4.1·4.2·6.1절). 화면 규모 목표 없음 |
| 읽은 코드·구성 범위 | `src/presentation/` 중 forms 전부, `components/async-surface.tsx`, `layouts/app-shell.tsx`, `routes/app-router.tsx`(160-260, 470-760행), `routes/route-codecs.ts`, `templates/page-templates.tsx`(40-200행), `i18n/message-contract.ts`·`locale-provider.tsx`·`catalog.ts` 일부, `design-system/primitives/field.tsx`·`text-field.tsx`, `adapters/query/application-query.ts`(200-720, 840-905행). 연결 확인: `src/adapters/http/backend-envelope.ts` 전체, `http-execution-v3.ts` 1680-1745행, `feature-http-binding.ts` 77-110·380-430행, `src/contracts/errors.ts`·`validation-issues.ts` 일부, `src/apps/deployable-app-module.ts`, 참조 기능 폼 페이지·계약·gateway, `docs/manual/01`·`02`·`reference/patterns.md` 해당 절, VD-04. 백엔드(읽기만): `IdempotencyExecutor.java` 80-240행, `IdempotencyScripts.java` 50-70행, `ClientSafeValidationDetails.java`, `docs/web/http-contract.md` 1·2·4절 |
| 수행한 테스트·실험 | 1.1절과 6절. 게이트는 오케스트레이터가 같은 커밋에서 돌린 결과를 읽었다(아래) |
| 확인하지 못한 범위·이유 | 1.2절 |
| 이전 리뷰와 비교 가능한 범위 | 지난 `2026-11-01-maturity-review/08-presentation.md` 08-01~08-09, 거기서 넘겨받은 0929 항목, 같은 README 13·14절의 presentation 관련 항목, UI 감사 UI-01~08. 지난 실행 결과는 증거로 쓰지 않았다 |
게이트(오케스트레이터, `e40684b`, `scratchpad/review-gates/summary.txt`): `check:architecture`·`check:types`·`lint`·`verify:documentation`·`check:adapter-inventory`·`check:ci`·`check:registries`·`check:i18n`·`check:design-system`·`check:diagnostics` 모두 exit 0. `test:unit` 2,580 / `test:component` 263 / `test:integration` 117 / `test:contract` 23 / `test:runtime-schema` 56 통과. `bundle` PASS(초기 JS 201,848 / 204,800 gzip B).
### 1.1 실행한 명령
worktree에서 `corepack pnpm install --frozen-lockfile`을 한 번 했다. 그 뒤로는 `node scripts/run-vitest.ts`와 Playwright(잠금 안에서)만 썼다. 측정 중 호스트 부하(1분)가 40~80으로 높았다. 다른 리뷰어와 함께 쓰는 22코어 호스트다.
| ID | 명령·실험 | 부하 | 결과 |
|---|---|---|---|
| B0 | `node scripts/run-vitest.ts run tests/component tests/architecture`(probe 2파일 포함) | 41.9 | 48 files / 316 tests 통과 |
| P1 | probe `tests/component/probe-08-form.test.tsx`. 실제 `createContractHttpExecutor` + `createFeatureHttpBinding`(Envelope, KEYED) + `useApplicationMutation` + `useAppForm` + 참조 폼 페이지와 같은 배선(`AsyncSurface`, 결과 불명이면 저장 끔). `fetch`만 가짜 | 약 40 | 4케이스 3.3초. 결과는 3.0절, 08-01, 08-03, 08-05 |
| P2 | probe `tests/architecture/probe-08-route-dup.test.ts`. `defineDeployableAppModule` + React Router `matchRoutes` | 약 40 | 08-04 |
| P3 | probe P1에 "결과 불명 뒤 폼 다시 마운트" 케이스 추가 | — | 6.3절 |
| P4 | probe `tests/e2e/probe-08-focus.spec.ts`(키보드로 저장한 뒤 포커스 위치, 3엔진, 빌드 preview, 잠금 안에서) | 17.5 | 9 passed. 6.2절, 08-02 |
| M1~M14 | 변이 → `node scripts/run-vitest.ts run <대상>` → 원문으로 되돌림 | 66~80 | 6.1절 |
### 1.2 확인하지 못한 범위
- 짝 백엔드를 실제로 띄우지 않았다. 도메인 거절이 `EFFECT_UNKNOWN_ABANDONED`로 기록되고 같은 키 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`가 된다는 것은 백엔드 코드를 읽은 결과다(E1). 프론트 probe는 그 응답을 그대로 흉내 냈다.
- 실제 스크린 리더 발표. 수동 접근성 기록 10건(`artifacts/tests/a11y-manual/*.md`)은 모두 `pending-manual-review`다.
- e2e 전체와 시각 테스트는 돌리지 않았다(영역 11). 1101/08-01 수정을 지키는 `tests/e2e/responsive.spec.ts:22-49`도 이번에 돌리지 않았다.
- 변이를 넣은 빌드로 e2e를 돌리지 않았다. 변이 M9(서랍의 테마 선택 제거)는 e2e에서만 잡힐 것으로 보이며 확인하지 않았다.
## 2. 지난 발견 재판정
줄 번호는 `e40684b` 기준이다. "변이"는 6.1절 표의 ID다.
| ID | 내용 | 판정 | 근거(현재 커밋) |
|---|---|---|---|
| 1101/08-01 | 좁은 화면에서 테마 선택·세션 상태가 사라진다 | 고쳐짐 | `app-shell.tsx:143-146` 서랍에 `ThemePreferenceSelect id="mobile-theme-preference"`와 `SessionStatus`. 지키는 테스트는 e2e(`responsive.spec.ts:22-49`)뿐이다. component 계층에서는 변이 M9가 살아남는다 |
| 1101/08-02 | 검색값만 바뀌어도 라우트 이동으로 처리 | 고쳐짐 | `app-router.tsx:208-215` effect 의존값 `[definition.routeId, pathname]`. 변이 M5(검색값을 다시 포함)가 `router.test.tsx`에 잡힌다 |
| 1101/08-03 | 서버 상태 훅이 raw 쓰기 입력을 공개 API로 받는다 | 고쳐짐(분기 남음) | 공개 overload는 bound만(`application-query.ts:317-330`). 타입 fixture `application-mutation-admission.test.tsx:249-263`(`@ts-expect-error`, `check:types` 게이트 통과). LEGACY 실행 분기는 harness용으로 남았다(`:224-228`, `:324-327`). 파일은 925줄 → 981줄 |
| 1101/08-04 | h2·h3 크기가 본문과 같다 | 고쳐짐 | `styles/theme/base.css:48-66` h2·h3·h4 크기·굵기 |
| 1101/08-05 | 상태 화면 제목이 h2 고정 | 고쳐짐 | `headingLevel`: `async-surface.tsx:44,51,73,82,132`, `form-components.tsx:38,47`. 변이 M3(빈 화면 제목 → `<p>`)이 잡힌다 |
| 1101/08-06 | 한국어 단어 중간 줄바꿈 | 고쳐짐 | `base.css:18-19` `:lang(ko) { word-break: keep-all }` |
| 1101/08-07 | en-US에서 예제 화면 `lang` 불일치 | 고쳐짐 | 예제 4곳 루트 `section lang="ko-KR"`(`ui-gallery-page.tsx:73`, `state-gallery-page.tsx:29`, `auth-example-page.tsx:13`, `platform-overview-page.tsx:354`) |
| 1101/08-08 | 갤러리 전용 primitive가 초기 청크에 | 고쳐짐 | primitive를 파일마다 나눔(`6dd4bc1`), `vite.config.ts` + `tests/unit/design-system-initial-chunk.test.ts`(`51941a5`). 게이트 `bundle` 201,848 B |
| 1101/08-09 | 접근성 기본 장치 일부를 지키는 테스트가 없다 | 고쳐짐 | 변이 M1(건너뛰기 링크), M2(`aria-live`), M3(제목 → `<p>`), M4(사이드바 이름) 모두 잡힘(6.1절) |
| 0929/08-01 | 제품이 지원 locale을 선언할 곳이 없다 | 남음 | `message-contract.ts:8-13` 고정 목록, `app-shell.tsx:85-90` 선택지에 `en-XA`·`ar-EG` 그대로. 1101 README 5절 확장 지점 결정에 묶여 있다 |
| 0929/08-04 | 폼 실패·결과 불명 화면에 문의 식별자 없음 | 고쳐짐 | `use-app-form.ts:368-371` `supportReference`, `async-surface.tsx:227-233`, `form-components.tsx:111-112`. P1에서 결과 불명 화면에 "지원 참조"가 보였다. 변이 M12가 잡힌다. 재전송하면 값이 바뀐다(3.6절) |
| 0929/08-06 | 라우트 제목이 세 곳에 있다 | 판정 안 함 | 이번 렌즈 밖이다. 영역 16 소관 |
| 0929/08-07 | 제품 폰트·전역 스타일 자리 없음 | 판정 안 함 | 이번 렌즈 밖이다 |
| 0929/08-08 | 로그인 복귀 주소가 라우터 기준 경로 | 남음 | `session-provider.tsx:70,81` `beginSignIn(pathname + search + hash)`. `useLocation()`은 basename을 뺀 값이다. 1101 이후 이 파일 변경 없음 |
| 1101 README 14.4 "백엔드 필드 검증 code가 폼 문구 표에 없다" | | 고쳐짐 | `form-contracts.ts:40-63`(`8a09c90`). 20개 code가 백엔드 `ClientSafeValidationDetails.java`의 code literal 20개와 같다(백엔드 HEAD `7ef8d0b4`에서 다시 셈). 커밋 본문은 "V2 client 경로"라고 적었지만 V2가 지워진 뒤에도 실제 경로(`backend-envelope.ts:200-217` → `safeValidationIssues`)가 같은 `details[].code`를 넘긴다. `form-foundation.test.tsx:256-318`이 V3 실행기로 확인한다. 변이 M7이 잡힌다 |
| 1101 README 14.4 "레이아웃의 skip link·`<main>`은 실행 검사가 없다" | | 고쳐짐(범위 제한) | `tests/component/layout-landmarks.test.tsx`(`27f4523`). 변이 M1이 잡힌다. `<main>`의 `tabIndex={-1}`은 보지 않는다(변이 M10 생존, 3.6절) |
| 1101 README 14.4 "플랫폼 라우트와 같은 경로의 기능 라우트를 검사하지 않는다" | | 고쳐짐(빈틈 있음) | `deployable-app-module.ts:104-114`(`7d85589`), `:115-123`(`8469554`). 변이 M11·M14가 잡힌다. 대소문자·끝 슬래시만 다른 경로는 놓친다(08-04) |
| 1101 README 14.3 "등록 라우트 없는 URL의 진단 `route_id`가 `NOT_FOUND`" | | 고쳐짐 | `app-router.tsx:477-482` `failedRouteIdAt` → `UNREGISTERED_ROUTE`(`7c8cb19`). 세 실패 경로가 같은 함수를 쓴다(`:583`, `:597`, `ContextLayout`의 `:655`) |
| UI 감사 UI-01~08 | | 유지 | 게이트 `check:design-system` PASS(UI-01·02·03·05 규칙). `src/presentation`에 `in oklch` 0건, 예제 eyebrow 0건(UI-06). UI-04는 e2e라 이번에 돌리지 않았다 |
## 3. 이번 발견 (36.3)
### 3.0 서버 거절마다 폼이 보이는 것 (짝 백엔드, Envelope operation)
P1 probe와 코드 읽기로 채웠다. "다시 저장"은 값을 고친 뒤 저장 버튼이 켜지는지다. 참조 폼 페이지의 배선(`reference-resource-form-page.tsx:52-55`, `:116-123`)을 그대로 썼다.
| 서버 답 | 판정(`backend-envelope.ts`) | 폼 결과 | 사용자가 보는 것 | 다시 저장 |
|---|---|---|---|---|
| 400 `VALIDATION_FAILED` + 필드 목록 | `VALIDATION_REJECTED`, `NOT_APPLIED` | `validation-error` | 필드 옆 code 문구("필수 입력값입니다."), 오류 요약, 첫 오류 필드로 포커스 | 됨(새 키) |
| 400 `VALIDATION_FAILED` + `{cause}`·details 없음 | `UNKNOWN_CLIENT_FAILURE`, `NOT_APPLIED` | `unavailable` | 실패 상태 + 지원 참조 | 됨 |
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | `VALIDATION_REJECTED`, `NOT_APPLIED` | `validation-error` | "입력값을 다시 확인해 주세요." 입력 문제가 아니다(08-05) | 됨 |
| 409·400 도메인 code, `DB_*` 409, `BAD_PARAMETER` | 표 밖 → `MAYBE_APPLIED` | `effect-unknown` | "변경 결과를 확인할 수 없습니다." + 두 버튼. 거절 이유 없음 | **안 됨(08-01)** |
| 같은 경우, 기능이 `mapProblem`으로 필드 오류를 만듦 | kind만 바뀜, effect는 `MAYBE_APPLIED` | `validation-error`, 값을 고치면 `idle` | 필드 오류와 결과 불명 화면이 같이 보임 | **안 됨(08-01)** |
| 그 밖의 422(fileserver, 또는 422로 필드 검증을 보내는 다른 백엔드) | `VALIDATION_REJECTED`, `MAYBE_APPLIED` | `validation-error` | 필드 오류 + 결과 불명. `form-foundation.test.tsx:866-883`이 고정한 동작 | 안 됨(의도, 1101 README 14.6 위험) |
| 409 `IDEMPOTENT_IN_FLIGHT` | `MAYBE_APPLIED`, `retryAfterMs` | `effect-unknown` | 결과 불명. 재전송이 `Retry-After`만큼 기다린다 | 재전송으로 해결 |
공통: 담당·기한·상태는 `미정 · 미정 · 신규`, 재검증 결과는 `없음(신규)`이다.
### 08-01 짝 백엔드의 업무 규칙 거절(도메인 400·409, `DB_UNIQUE_VIOLATION`, `BAD_PARAMETER`)이 폼에서 결과 불명이 되어, 사용자가 값을 고쳐 다시 저장할 길이 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 28, 17, 5, 24, 20, 22, 4 |
| 근거 | **판정.** Envelope operation의 400·409·422는 표 `REFUSED_BEFORE_WRITE`(`backend-envelope.ts:97-117`)의 세 code만 `NOT_APPLIED`이고 나머지는 모두 `MAYBE_APPLIED`다(`:163-174`). 이 판정이 기능의 `classifyProblem`보다 앞선다(`http-execution-v3.ts:1722-1730`). 기능의 `mapProblem`은 kind·code·필드 목록만 바꾸고 effect는 실행기 값을 그대로 쓴다(`feature-http-binding.ts:405-426`). **폼.** `MAYBE_APPLIED`면 결과가 `effect-unknown`이다(`use-app-form.ts:221-226`). 코디네이터는 그 시도를 `UNKNOWN`으로 붙든다(`application-query.ts:654-665`). 참조 폼 페이지는 그동안 저장 버튼을 끈다(`reference-resource-form-page.tsx:52-55`, `:116-123`). 결과 불명 화면은 고정 문구 하나만 보이고 실패의 code·`userMessageKey`를 쓰지 않는다(`async-surface.tsx:190-234`). "변경됨으로 확인"은 `settleApplied` → `settleSuccessfulValues`로 가서 입력을 기본값으로 되돌리고 결과를 `success`로 바꾼다(`use-app-form.ts:163-188`). **백엔드(읽기만).** KEYED 작업 안에서 던진 예외는 종류와 상관없이 `EFFECT_UNKNOWN_ABANDONED`로 기록된다(`IdempotencyExecutor.java:211-217`). 같은 키로 다시 오면 `RECOVERY_REQUIRED`(`IdempotencyScripts.java:59-61`) → `500 IDEMPOTENCY_RECOVERY_REQUIRED`(`http-contract.md:106`)다. **실행(P1).** `409 POSTER_ALREADY_EXISTS` → 결과 `effect-unknown`. 화면 글자는 "변경 결과를 확인할 수 없습니다. / 변경됨으로 확인 / 같은 요청으로 다시 보내기 / 지원 참조: …"뿐이고 저장 버튼은 꺼짐. 이름을 고쳐도 꺼짐. 재전송(같은 키 `key-1`) → 500 → 그대로 `effect-unknown`. "변경됨으로 확인" → 결과 `success`, 이름 값 `""`, "saved" 표시. `mapProblem`이 `VALIDATION_REJECTED` + 필드 목록을 돌려준 경우: 필드 `aria-invalid="true"`, 오류 요약 "Name: 입력값을 확인해 주세요.", 저장 꺼짐. 값을 고치면 결과 `idle`인데 저장은 여전히 꺼짐. `400 BAD_PARAMETER`도 `effect-unknown`. **문서 주장과 다름.** VD-04 결정 5 "409 conflict는 … 입력과 dirty 상태를 보존한다"(`VD-04-native-form-facade.md:26`). 매뉴얼 "필요하면 `mapProblem`을 둔다(예: 409, 422를 업무 실패로)"(`docs/manual/01-add-a-feature.md:329`), 패턴표 "문제 응답 → 업무 실패: `mapProblem`"(`docs/manual/reference/patterns.md:87`). 참조 기능은 409 `CONFLICT`를 `NOT_APPLIED`로 분류해 "충돌을 해결한 뒤 다시 제출" 흐름을 보여 준다(`reference-feature-contract-contribution.ts:41-63`). 그 기능이 Envelope operation이 아니어서 가능한 흐름이다. 짝 백엔드에 붙는 기능은 같은 흐름을 만들 수 없다 |
| 발생 조건 | 짝 백엔드 + `responseEnvelope: "ENVELOPE_V1"`(`create:feature` 기본값) 쓰기 + 실패가 표 밖의 400·409·422. 계약 문서 6.1절 표의 `BAD_PARAMETER`(어느 층이든 `IllegalArgumentException`), `DB_UNIQUE_VIOLATION` 등 `DB_*` 409, 도메인 `*_INVALID`·`*_ALREADY_EXISTS`·`*_CONFLICT`가 모두 해당한다. 이름 중복, 상태 전이 거절처럼 제품 폼이 가장 먼저 만나는 거절이다 |
| 영향 | (1) 사용자는 왜 실패했는지 모른다. (2) 값을 고쳐 다시 저장할 수 없다. (3) 재전송은 백엔드가 `RECOVERY_REQUIRED`로 막아 끝나지 않는다. (4) 화면 안에 남은 출구 "변경됨으로 확인"은 저장되지 않은 요청을 "저장했습니다"로 바꾸고 입력을 지운다. 사용자는 저장됐다고 믿고 떠난다. (5) 결과 불명 시도는 같은 세션 세대에서 화면을 떠났다 돌아와도 남는다(`application-query.ts:895`: admission이 있으면 채널을 놓지 않음). P3: 폼을 내렸다 다시 그리고 새 이름을 넣어도 결과는 `idle`인데 저장이 꺼져 있고 결과 불명 문구가 그대로 보였다. 새로고침이나 세션 교체 전까지 그 폼으로는 아무것도 만들 수 없다. 짝으로 출시하는 모든 쓰기 화면이 같은 상태를 물려받는다 |
| 심각도·우선순위 | High · P1 — 지원하는 구성(짝 백엔드)에서 저장이라는 핵심 기능이 흔한 거절 뒤에 멈추고, 거짓 성공 경로가 열려 있다. 서버 데이터가 망가지지는 않아 Critical은 아니다. 두 템플릿을 짝으로 빨리 출시한다는 목표에 바로 걸린다 |
| 확실성과 남은 가정 | 프론트 동작은 실제 실행기·바인딩·코디네이터·폼으로 확인했다(jsdom). 백엔드가 도메인 거절을 `ABANDONED`로 남기고 재전송에 500을 준다는 것은 코드 읽기다. 실제 짝 백엔드로는 돌리지 않았다. "트랜잭션 안 DB 변경은 예외와 함께 롤백된다"는 백엔드 문서의 설명이다(`http-contract.md:108-111`). 트랜잭션 밖 부작용이 있는 use case는 정말로 결과 불명일 수 있다. 판정 표는 `src/adapters/http`(영역 03·07)에 있다. 그쪽이 같은 원인을 올리면 하나로 합치고, 이 항목의 관점은 화면 결과(막힌 저장, 거짓 성공) 쪽으로 붙인다 |
| 결정의 근거 | 확인한 사실: 표 밖 400·409·422를 `MAYBE_APPLIED`로 고정한 것은 기록된 결정이다(1101 README 14.6 "6.1 표 반영", `3261208`). 이유는 백엔드가 code만으로 쓰기 전·후를 알려 주지 않는다는 것이다. 백엔드도 같은 이유로 작업 안 예외를 모두 "효과 모름"으로 기록한다. 리뷰어 추론: 두 저장소가 각자 안전한 쪽을 골랐고, 그 결과 "쓰기 전에 업무 규칙으로 거절됨"을 말할 수단이 어디에도 없다. 폼과 결과 불명 화면은 이 경우를 따로 다루지 않는다. 5.1절 |
| 이해 비용 | 기능 작성자가 "409를 받으면 화면에 무엇이 보이나"를 알려면 매뉴얼(`mapProblem`이면 된다고 읽힘) → `feature-http-binding.ts`(effect는 못 바꿈) → `http-execution-v3.ts`(표가 앞섬) → `backend-envelope.ts`(표) → `application-query.ts`(UNKNOWN 보유) → `use-app-form.ts`(분기 순서) → `async-surface.tsx`(고정 문구) 7곳을 읽어야 한다. 매뉴얼만 따르면 P1의 `mapProblem` 상태를 만든다 |
| 최소 개선 방향 | 두 단계. (가) 화면: 결과 불명 화면이 실패 code의 기능 문구를 보이게 한다(`mapProblem`의 code → 기능 catalog). 서버가 업무 거절 code를 보낸 결과 불명에는 "변경됨으로 확인" 대신 "목록에서 저장 여부 확인" 안내를 둔다. 응답이 없거나 5xx인 진짜 결과 불명의 "변경됨으로 확인 → 폼 정리"는 의도된 동작이라 그대로 둔다(`reference-page.test.tsx:522-550`). (나) 계약: "쓰기 전에 업무 규칙으로 거절됨"을 표현할 자리를 만든다. 5.1절의 (B) |
| 대안 비교 | 5.1절. (A) 현상 유지. (B) 백엔드가 트랜잭션 안 업무 거절을 "효과 없음"으로 기록하고 그 code를 계약 문서 6.1절 "쓰기 전"에 올린다 → 프론트 표에 추가. (C) 기능 descriptor에 "이 code는 쓰기 전 거절"을 선언하는 칸을 두고 표와 합친다. (D) (가)만 한다 |
| 단순화의 보존 조건 | 표가 지키는 것을 잃지 않는다: `409 IDEMPOTENT_IN_FLIGHT`는 계속 `MAYBE_APPLIED`·같은 키(`application-query.ts:547-553`). 모르는 code는 계속 `MAYBE_APPLIED`. 참조 분류기처럼 400·422를 통째로 `NOT_APPLIED`로 보는 패키지가 표를 우회하지 못한다(1101 README 14.6 버린 대안 2). 진짜 결과 불명에서 "변경됨으로 확인" 뒤 폼을 정리하는 동작(`reference-page.test.tsx:522-550`). 변이 M13(확인 뒤 입력 유지)이 이 테스트에 잡히므로 이 동작은 지금 지켜지고 있다 |
| 비용·부작용 | (가) 화면 2곳, 문구 키, 테스트. (B) 백엔드 executor·문서와 프론트 표를 함께 바꾸는 두 저장소 작업. (C) descriptor 칸 하나와 조립 검사. 잘못 선언하면 결과 불명을 새 키로 보내 중복이 생길 수 있고, 그 책임이 기능 작성자에게 간다 |
| 재검토 조건 | 백엔드가 응답에 쓰기 단계를 싣게 되면(예: `details.stage`) (B)·(C) 대신 그 값을 읽는다. 짝 백엔드가 KEYED 엔드포인트에서 도메인 예외를 던지지 않게 바뀌면 다시 본다 |
| 완료 기준 | P1과 같은 구성에서 쓰기 전으로 확인된 업무 거절(예: `409 POSTER_ALREADY_EXISTS`) 뒤 (1) 화면에 거절 이유가 보이고 (2) 값을 고치면 저장 버튼이 켜져 새 키로 저장된다. 쓰기 전으로 확인되지 않은 code는 지금처럼 결과 불명이지만 거절 code의 문구가 보이고, 저장되지 않은 요청을 "저장했습니다"로 바꾸는 버튼이 없다. P3(다시 마운트)에서도 같다 |
| 검증 방법 | `form-foundation.test.tsx`의 "correcting a field after a server validation refusal" 묶음에 409 도메인 code 행, `mapProblem` 행, 결과 불명 뒤 다시 마운트하는 행을 넣는다. 짝 백엔드로는 계약 테스트 한 건 |
### 08-02 키보드로 저장했다가 필드 오류가 아닌 실패(결과 불명, 429 등)를 받으면 포커스가 `body`로 떨어진다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 1, 6, 10 |
| 근거 | 참조 폼 페이지가 저장 중과 결과 불명 동안 저장 버튼에 `disabled`를 준다(`reference-resource-form-page.tsx:120-123`, 취소·초기화도 `:116`, `:131`). 포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 내려놓는다. 폼은 필드 오류일 때만 포커스를 옮긴다(`use-app-form.ts:214`, `:276`). 실패 상태와 결과 불명 화면은 폼 위쪽 `feedback` 자리에 그려진다(`page-templates.tsx:68-70`). P4(3엔진, 빌드 preview, 저장 버튼에 포커스 → Enter): **500(결과 불명)** 세 엔진 모두 저장 뒤 `document.activeElement`가 `body`. 다음 Tab은 두 엔진에서 문서 맨 앞 "본문으로 건너뛰기", 한 엔진에서는 여전히 `body`. 복구 버튼("같은 요청으로 다시 보내기")은 폼 위에 있어 셸 머리말·탐색을 다시 지나야 닿는다. **429** 세 엔진 모두 `body`, 다음 Tab은 "초기화". **422 필드 오류** 세 엔진 모두 이름 입력란에 포커스(정상). 디자인 시스템 `Button`에는 끄지 않고 진행 중을 알리는 `pending` prop이 이미 있다(`design-system/primitives/button.tsx:12-13`, `:44-46`) |
| 발생 조건 | 키보드나 스크린 리더로 저장 버튼을 눌렀고, 결과가 필드 오류가 아닐 때(결과 불명, 429, 403, 서버 실패). 08-01의 업무 거절도 여기에 든다 |
| 영향 | 키보드·스크린 리더 사용자가 실패 뒤 위치를 잃는다. 결과 불명이면 복구 버튼까지 문서 처음부터 다시 이동해야 한다. 상태 문구 자체는 `role="status"`·`role="alert"`로 읽힌다(P4의 `statuses`·`alerts`) |
| 심각도·우선순위 | Low · P2 — 기능은 남아 있고 문구는 발표된다. 다만 모든 파생 폼이 이 배선을 복사하고, `PRODUCT.md`가 WCAG 2.2 AA를 요구한다 |
| 확실성과 남은 가정 | 세 엔진에서 확인(E3). 어느 엔진이 Tab 뒤에도 `body`였는지는 기록하지 않았다. 실제 스크린 리더 발표는 미확인 |
| 결정의 근거 | 적용 제외 — 이미 있는 `pending` prop과 필드 오류용 포커스 이동을 실패 상태에도 적용하는 누락이다 |
| 이해 비용 | 필요한 범위만 |
| 최소 개선 방향 | (1) 참조 폼 페이지의 저장 버튼이 저장 중에는 `disabled` 대신 `pending`을 쓰고, 중복 제출은 지금처럼 `submitForm`이 막는다(`use-app-form.ts:306`). (2) 결과가 `effect-unknown`·실패 상태로 바뀌면 `feedback`의 제목(또는 첫 행동 버튼)으로 포커스를 옮긴다. `useAppForm`이 결과 전이 때 포커스할 대상을 받게 하면 페이지마다 복사하지 않는다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 필드 오류 때 첫 필드 포커스(`reference-form.spec.ts` "focuses the first invalid field"), 중복 제출 차단 |
| 비용·부작용 | 페이지 몇 줄, `useAppForm` 선택 인자 하나, e2e 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | P4의 500·429 행에서 저장 뒤 포커스가 실패 상태 안에 있고, Tab 한 번에 복구 버튼에 닿는다 |
| 검증 방법 | `tests/e2e/reference-save.spec.ts`에 키보드 저장 + `toBeFocused` 단언 |
### 08-03 폼 문구 표를 `Object.prototype` 이름까지 찾아, `constructor` 같은 code가 "요청한 문구를 표시할 수 없습니다."가 된다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 23, 1 |
| 근거 | `validationMessage`가 `VALIDATION_COPY[code]`로 찾는다(`form-contracts.ts:70-78`). `Object.freeze({...})`는 `Object.prototype`을 물려받는다. 그래서 `constructor`·`toString`·`hasOwnProperty`·`__proto__`는 `undefined`가 아니라 함수나 객체가 되고 `?? "form.validation.unknown"`이 걸리지 않는다. 그 값이 문구 키로 넘어가 `resolveMessage`의 대체 문구가 된다(`message-contract.ts:101-104`). 서버 code는 길이만 검사한다(`validation-issues.ts:41-47`). P1: `NOT_BLANK` → "필수 입력값입니다.", `SOMETHING_NEW` → "입력값을 확인해 주세요.", `constructor`·`__proto__`·`toString`·`hasOwnProperty` → "요청한 문구를 표시할 수 없습니다.". 같은 영역의 다른 표는 `Object.hasOwn`을 쓴다(`route-codecs.ts:26-27`, `backend-envelope.ts:120`) |
| 발생 조건 | 서버가 필드 code로 소문자 JS 내장 이름을 보낼 때. 짝 백엔드는 대문자 code만 보내므로 짝 구성에서는 닿지 않는다 |
| 영향 | 필드 옆에 엉뚱한 문구가 나온다. 예외·화면 깨짐·보안 문제는 없다 |
| 심각도·우선순위 | Low · P3 |
| 확실성과 남은 가정 | 확인(P1) |
| 결정의 근거 | 적용 제외 — 같은 영역의 다른 표와 같은 방식으로 맞추면 되는 단순 결함이다 |
| 이해 비용 | 필요한 범위만 |
| 최소 개선 방향 | `Object.hasOwn(VALIDATION_COPY, code)`로 찾는다. 변이 M8이 이 수정이다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 3줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `validationMessage("constructor")`가 "입력값을 확인해 주세요."다 |
| 검증 방법 | `form-foundation.test.tsx` "keeps the default copy for a code it does not know"에 내장 이름 3개를 더한다. 지금은 M8 수정을 넣어도 실패하는 테스트가 없다(unit·component 2,847건 통과) |
### 08-04 기능 라우트 경로 중복 검사가 대소문자·끝 슬래시만 다른 두 경로를 놓쳐, 라우터가 그중 하나만 그린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 23, 1 |
| 근거 | 같은 모양 검사가 파라미터 이름만 지운 문자열을 `Map` 키로 비교한다(`deployable-app-module.ts:115-123`). React Router `matchRoutes`는 기본이 대소문자 무시이고 끝 슬래시를 같은 경로로 본다. 라우트 경로 문법을 정하는 검사는 없다(`contractRoutePaths`는 문자열이면 그대로 받는다, `bounded-context-module.ts:106-120`). P2: `/shop/items/:itemId`와 `/shop/Items/:id` → 조립 통과, `matchRoutes`는 앞에 둔 쪽만 고른다. `/shop/items`와 `/shop/items/` → 조립 통과, 어느 순서든 `/shop/items/` 쪽만 고른다. 이름만 다른 `/shop/items/:id`는 지금처럼 거절된다 |
| 발생 조건 | 두 기능이 같은 경로를 대소문자나 끝 슬래시만 다르게 적을 때(오타, 복사) |
| 영향 | 메뉴·레지스트리에는 두 라우트가 다 나오지만 한쪽은 그려지지 않는다. `8469554`가 막으려던 결과와 같다 |
| 심각도·우선순위 | Low · P3 — 오타가 있어야 생기고 화면에서 바로 보인다 |
| 확실성과 남은 가정 | 조립 결과와 `matchRoutes` 순위는 확인. 실제 `AppRouter`에 두 기능을 마운트하지는 않았다. 파일은 `src/apps`라 영역 09와 겹칠 수 있다. 합칠 때 하나로 센다 |
| 결정의 근거 | 적용 제외 — 비교 키를 라우터와 같은 규칙으로 맞추면 된다 |
| 이해 비용 | 필요한 범위만 |
| 최소 개선 방향 | 모양 키를 만들 때 소문자로 바꾸고 끝 슬래시를 지운다. 또는 라우트 경로를 소문자·끝 슬래시 없음으로 제한하는 조립 검사를 하나 둔다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | `/a/new`와 `/a/:id`는 계속 허용(`context-route-roots.test.ts:226`) |
| 비용·부작용 | 1~3줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | P2의 두 경우가 조립 때 실패한다 |
| 검증 방법 | `context-route-roots.test.ts`에 P2 두 행 추가 |
### 08-05 422 `IDEMPOTENT_REQUEST_MISMATCH`(같은 키, 다른 본문)를 입력 오류로 보여 "입력값을 다시 확인해 주세요."라고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 24, 8, 23 |
| 근거 | `isFieldValidationFailure`가 422를 모두 필드 검증으로 본다(`backend-envelope.ts:140-150`). 그래서 kind가 `VALIDATION_REJECTED`다(`:208-212`). 필드 목록이 없으면 폼이 `form.validation.retry`를 넣는다(`form-contracts.ts:93-95`). P1: 결과 `validation-error`, 알림 "입력 내용을 확인해 주세요. 입력값을 다시 확인해 주세요.", 저장 켜짐. 백엔드는 이 code를 "같은 키를 다른 본문으로 보냄"으로 정한다(계약 문서 6.1절 표, `backend-envelope.ts:112-116` 주석). 같은 종류의 400 `IDEMPOTENCY_KEY_INVALID`는 `UNKNOWN_CLIENT_FAILURE`로 읽는다(`reference-http-gateway.ts:44-51`) |
| 발생 조건 | 프론트의 같은 입력 판정(`canonicalInputIdentity`)과 백엔드 지문이 어긋날 때. 정상 흐름에서는 드물다 |
| 영향 | 사용자는 고칠 것이 없는 입력을 고치라는 말을 듣는다. 지원 참조도 보이지 않는다(`use-app-form.ts:368-371`은 `validation-error`에 참조를 주지 않음). 다음 저장은 새 키라 동작은 이어진다 |
| 심각도·우선순위 | Low · P3 |
| 확실성과 남은 가정 | 확인(P1) |
| 결정의 근거 | 적용 제외 — kind 판정 한 줄의 문제다 |
| 이해 비용 | 필요한 범위만 |
| 최소 개선 방향 | 422 중 필드 목록이 있을 때만 `VALIDATION_REJECTED`로 보고, `IDEMPOTENT_REQUEST_MISMATCH`는 `UNKNOWN_CLIENT_FAILURE`로 둔다. 폼은 `unavailable` 상태와 지원 참조를 보인다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | effect는 `NOT_APPLIED` 그대로 |
| 비용·부작용 | `backend-envelope.ts` 한 곳과 테스트 1~2행. 파일은 영역 03 소관이다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | P1의 422 행에서 결과가 `unavailable`이고 "입력값" 문구가 없다 |
| 검증 방법 | `tests/integration/http-execution-v3-envelope.test.ts`에 kind 단언, `form-foundation.test.tsx`에 화면 단언 |
### 3.6 발견으로 올리지 않은 관찰
- **영역 03 인계.** Envelope operation의 `500 IDEMPOTENCY_RECOVERY_REQUIRED`와 `503 IDEMPOTENCY_COMPLETION_UNKNOWN`은 표(`backend-envelope.ts:163-174`)에 없다. 그래서 효과를 기능의 `classifyProblem`이 정한다(`http-execution-v3.ts:1722-1730`). 백엔드는 두 code 모두 "새 키 금지"라고 적는다(백엔드 `http-contract.md:105-114`). P1 첫 실행에서 `classifyProblem`이 `NOT_APPLIED`를 돌려주게 하자 재전송 결과가 `retry-later`가 됐고 "다시 시도"가 새 키로 열렸다. 참조 기능의 분류기는 5xx에 `MAYBE_APPLIED`를 돌려주므로 그대로 복사한 기능은 안전하다. 두 code를 표에서 `MAYBE_APPLIED`로 고정할지는 영역 03이 판단한다.
- 결과 불명 화면의 "지원 참조"는 마지막 시도의 correlation id다. 재전송하면 바뀐다(P1: 첫 값과 재전송 뒤 값이 다름). 지원 담당이 첫 요청을 찾으려면 사용자가 바뀌기 전 값을 적어 둬야 한다.
- 결과 불명 상태는 `role="status"` 영역 안에 버튼 두 개를 함께 둔다(`async-surface.tsx:193-234`). 스크린 리더가 상태 문장과 버튼 이름을 한 덩어리로 읽을 수 있다. 실제 발표는 미확인이다.
- `layout-landmarks.test.tsx`는 레이아웃 `<main>`의 `tabIndex={-1}`을 보지 않는다. 없으면 라우터의 `main.focus()`(`app-router.tsx:189`)가 아무 일도 하지 않는다(변이 M10 생존). 템플릿 자체에는 레이아웃을 가진 context가 없고 AppShell은 따로 지켜진다. 제품이 레이아웃을 더할 때의 빈틈이다.
- 라우트 충돌 검사는 라우터의 마운트 순서를 따로 흉내 낸다(`deployable-app-module.ts:62-69` 주석, 라우터는 `app-router.tsx:676-735`). 커밋(`7d85589`)이 이 한계를 적었다. 5.2절에서 판단했다.
- `tests/component/boot-unexpected-failure.test.tsx`가 부하 66~80에서 변이와 상관없이 자주 실패했다(14번 중 8번, 6.1절). `main.tsx` 전체를 동적으로 불러온 뒤 `findByRole`의 기본 대기(1초) 안에 알림이 나와야 한다. 영역 10 인계.
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | M3 / M2 | E3 | P — 지난 9건 고쳐짐. 실패 뒤 포커스 유실(08-02, 3엔진), 08-03(내장 이름 조회), 08-04(경로 비교) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2 | O — `check:architecture` 통과(게이트). presentation이 HTTP를 직접 모른다 |
| 3 | 변경 용이성 | 적용 | M3 / M1 | E1 | P — locale 목록이 셸에 박혀 있다(0929/08-01 남음) |
| **4** | 인지 부하 | 적용 | — | E2 | P — "409를 받으면 무엇이 보이나"에 7곳을 읽어야 하고 매뉴얼을 따르면 틀린 결과가 나온다(08-01) |
| **5** | 위험 가시성 | 적용 | M2 / M1 | E2 | P — `mapProblem` 자리에서 effect를 바꿀 수 없다는 것이 보이지 않는다. 결과 불명 화면이 거절 이유를 숨긴다(08-01) |
| 6 | 실패 성숙도 | 적용 | M3 / M2 | E2 | X — 업무 거절과 결과 불명을 가를 수단이 없어 저장이 멈춘다(08-01). 필드 검증 400은 충족 |
| 7 | 운영 성숙도 | > | — | — | 영역 09·13 |
| **8** | 디버깅 가능성 | 적용 | M3 / M3 | E2 | P — 폼 실패·결과 불명에 지원 참조(0929/08-04 고쳐짐, M12 잡힘). 진단 `UNREGISTERED_ROUTE`(`7c8cb19`). 422 불일치가 입력 오류로 보인다(08-05). 참조가 재전송마다 바뀐다(3.6절) |
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P — `application-query.ts` 981줄. harness용 LEGACY 분기가 남았다 |
| 10 | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 변이 14종 중 11종이 잡힌다(6.1절, 생존 M9·M10, 양성 대조 M8). 08-01~08-04를 지키는 테스트는 없다. 좁은 화면 테마는 e2e만 지킨다(M9). 부하가 높으면 `boot-unexpected-failure.test.tsx`가 흔들린다 |
| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 |
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O — 중복 제출 차단, 결과 불명 같은 키 재사용(P1에서 재전송 키 `key-1` 동일), `REJECT_WHILE_ACTIVE` |
| 13 | 확장성 | > | — | — | 영역 09·15·16 |
| **14** | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — 초기 JS 201,848 / 204,800 B(게이트). 문구 catalog가 초기 청크에 있어 문구를 더할 때마다 여유가 준다(`8a09c90` +395 B). 렌더 측정은 하지 않음 |
| **15** | 보안 성숙도 | 적용 | M3 / M3 | E2 | P — 백엔드 message를 그리지 않는다(`form-foundation.test.tsx:318`). raw HTML 금지 lint(게이트). 로그인 복귀 주소(0929/08-08) 남음 |
| 16 | 의존성 성숙도 | > | — | — | 영역 13 |
| 17 | API / Contract 성숙도 | 적용 | M3 / M2 | E2 | P — VD-04 결정 5(409 뒤 입력 보존·재제출)가 짝 백엔드 operation에서 성립하지 않는다(08-01) |
| 18 | 배포 성숙도 | 적용 | M3 / M3 | E2 | O — 청크 복구 경계 변경 없음, component 게이트 통과 |
| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 0929/08-01 남음 |
| 20 | 개발자 경험 | 적용 | — | E2 | P — 매뉴얼·패턴표가 `mapProblem`으로 409를 업무 실패로 만들라고 하지만 저장이 풀리지 않는다(08-01) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | P — 라우트·레이아웃 충돌을 조립 때 막는다(`7d85589`, `8469554`, `27f4523`, M11·M14 잡힘). 대소문자·끝 슬래시는 놓친다(08-04) |
| 22 | 추상화 성숙도 | 적용 | — | E2 | P — 폼 결과와 코디네이터 상태가 따로 있고 페이지가 둘을 합친다. "결과 `idle`인데 저장 꺼짐" 조합이 생긴다(08-01, 5.3절) |
| **23** | 일관성 | 적용 | — | E2 | P — 같은 영역의 표 조회가 `Object.hasOwn`과 일반 조회로 갈렸다(08-03). 경로 비교 규칙이 라우터와 다르다(08-04) |
| **24** | 네이밍 / 의미 성숙도 | 적용 | — | E2 | P — "변경됨으로 확인"이 거절된 요청을 "저장했습니다"로 바꾼다(08-01). `form.validation.retry`가 입력과 무관한 거절에 쓰인다(08-05) |
| 25 | 조직 확장성 | 적용 | — | E1 | P — locale 목록이 셸 파일에 있어 제품이 템플릿 파일을 고친다(0929/08-01) |
| 26 | Ownership 성숙도 | 적용 | — | E1 | ? — 수동 접근성 기록 10건이 모두 `pending-manual-review` |
| 27 | 삭제 가능성 | > | — | — | 영역 09·16 |
| 28 | 회복 가능성 | 적용 | M2 / M1 | E2 | X — 업무 거절 뒤 화면 안에서 정상으로 돌아갈 길이 거짓 성공 버튼뿐이다(08-01). 라우트·청크 실패의 "한 번 새로고침"은 그대로 |
## 5. 설계 선택 검토 (41절)
### 5.1 Envelope 표가 400·409·422의 효과를 기능 판정보다 앞에 정한다 → 변경 권고(08-01)
1. **무엇이 필요한가.** 결과를 모르는 쓰기를 새 키로 다시 보내면 안 된다(중복 생성). 동시에 사용자는 업무 규칙 거절(이름 중복 등)을 보고 값을 고쳐 다시 저장할 수 있어야 한다.
2. **지킬 성질.** 서버가 "쓰기 전 거절"을 보장한 것만 `NOT_APPLIED`로 본다(매뉴얼 02 4절 원칙). 그 밖은 같은 키로만 다시 보낸다. 사용자에게 거절 이유를 알리고, 거짓 성공을 만들지 않는다.
3. **현재 보장.** 첫째는 지킨다: 표(`backend-envelope.ts:97-174`), 실행기가 표를 앞세움(`http-execution-v3.ts:1722-1730`), 코디네이터의 같은 키 재사용(`application-query.ts:547-553`). 둘째·셋째는 못 지킨다(P1). 기록된 의도: 1101 README 14.6이 "표 밖은 `MAYBE_APPLIED`"를 정했고 이유는 백엔드가 단계를 말하지 않는다는 것이다. 폼에 미치는 결과는 기록되지 않았다.
4. **대안.** (A) 현상 유지. (B) 백엔드가 트랜잭션 안에서 던진 업무 거절을 "효과 없음"(executor의 `RetryableNoEffect`와 같은 기록)으로 남기고, 그 code를 계약 문서 6.1절 "쓰기 전"으로 올린다. 프론트는 표에 code를 더한다. (C) 기능 descriptor에 "쓰기 전 거절 code" 목록 칸을 두고 표와 합친다. (D) 화면만 고친다(이유 표시, 확인 뒤 입력 유지).
5. **비용.** (A) 모든 쓰기 폼이 막다른 길. (B) 두 저장소 변경. 백엔드가 "트랜잭션 밖 부작용 없음"을 use case마다 보장해야 한다. 판정의 정본이 서버에 남는다. (C) 한 저장소로 빠르다. 대신 기능 작성자가 백엔드 use case를 알고 선언해야 하고, 틀리면 중복 생성이 생긴다. 표가 막으려던 "패키지가 400을 통째로 `NOT_APPLIED`로 보는 것"이 다시 가능해진다. (D) 이유는 보이지만 여전히 고쳐 저장할 수 없다.
6. **판단.** (D)를 먼저 하고, 계약은 (B)로 고친다. (B)가 "서버가 보장한 것만 `NOT_APPLIED`" 원칙을 지키는 유일한 후보다. 두 저장소 모두 같은 사용자 소유라 (B)의 조율 비용이 크지 않다. (C)는 (B)가 늦어질 때 기능 단위 임시 수단으로만 비교한다.
7. **재검토 조건.** 백엔드가 응답에 쓰기 단계를 싣게 되면 code 목록 대신 그 값을 읽는다. 짝이 아닌 백엔드(problem details)를 쓰는 제품은 지금처럼 `classifyProblem`이 정한다.
### 5.2 라우트 충돌을 앱 조립 때 라우터 순위를 흉내 내 검사한다(`7d85589`, `8469554`) → 유지, 보강(08-04)
1. **무엇이 필요한가.** 메뉴에 나오는 기능 라우트는 실제로 그 기능이 그린다. 다운스트림이 기능을 더한 빌드에서도 지켜져야 한다.
2. **지킬 성질.** 기능 라우트 URL마다 그 기능의 context가 답한다. 플랫폼 라우트나 다른 기능이 가로채지 않는다.
3. **현재 보장.** 확인한 사실: `assertFeatureRoutesReachOwningContext`가 `matchRoutes`로 [플랫폼 라우트, context가 붙는 자리]를 만들어 비교하고, 앱 모듈을 평가할 때 throw한다(fail-closed). 변이 M11·M14가 `context-route-roots.test.ts`에 잡힌다. 보장하지 않는 것: 대소문자·끝 슬래시(08-04), 부분 겹침(`/a/:slug`의 한 값, 커밋이 적은 한계), 라우터 마운트 순서가 바뀔 때의 동기화(주석으로만).
4. **대안.** (A) 현 상태. (B) 라우터 표(`createRegisteredRoutes`) 자체를 검사 — 순위가 정확하지만 `AppRouter` 마운트 때에야 실패하고 fixture가 따로 필요하다(커밋이 버린 이유). (C) (A)에 라우트 경로 문법 제한(소문자, 끝 슬래시 없음)을 더한다.
5. **비용.** (A) 오타 경로를 놓친다. (B) 실패 시점이 늦다. (C) 조립 검사 몇 줄. 대문자 경로를 쓰는 제품이 있으면 [계약] 변경.
6. **판단.** (C). 흉내 낸 모델이 라우터와 어긋나는 위험은 남는다. 지금 구조에서는 라우터가 플랫폼 라우트를 먼저 붙이는 한, 어긋나면 검사가 더 엄격해지는 쪽이다. 라우터 순서를 바꾸는 변경은 드물고 주석이 있다.
7. **재검토 조건.** `app-router.tsx`의 마운트 순서를 바꿀 때, 또는 `caseSensitive` 라우트를 쓰기 시작할 때.
### 5.3 폼 결과 상태와 코디네이터 상태를 따로 두고 페이지가 합친다 → 조건부 유지(08-01과 함께 정리)
1. **무엇이 필요한가.** 폼은 입력·필드 오류·dirty를, 코디네이터는 키·결과 불명을 가진다. 결과 불명은 화면을 다시 그려도 남아야 한다.
2. **지킬 성질.** 화면이 "저장할 수 있음"으로 보이면 실제로 저장할 수 있다. 결과 불명이면 새 제출이 막히고 그 이유가 보인다.
3. **현재 보장.** 두 상태가 따로 있고 참조 페이지가 `mutationBlocked`로 합친다(`reference-resource-form-page.tsx:52-55`). 폼도 자기 쪽에서 막는다(`use-app-form.ts:307`). `VALIDATION_REJECTED` + `MAYBE_APPLIED`에서는 폼이 막지 않고 코디네이터가 막아 "결과 `idle`인데 저장 꺼짐"이 된다(P1). 이 조합은 테스트가 고정한 의도다(`form-foundation.test.tsx:866-883`). 변이 M6(이 조합을 결과 불명으로 먼저 보냄)은 그 테스트에 잡힌다.
4. **대안.** (A) 현 상태. (B) `useAppForm`이 코디네이터 상태를 받아(예: `heldBy: mutation.state`) 결과를 하나로 낸다. (C) `applyOutcome`에서 effect를 kind보다 먼저 본다(M6).
5. **비용.** (A) 페이지마다 합치는 코드를 복사한다. 매뉴얼은 이 합치기를 "기능 테스트로만 잡힌다"고 적는다(`01-add-a-feature.md:483`). (B) 폼 API 한 칸. (C) 필드 오류를 잃는다.
6. **판단.** 단독으로는 바꿀 만큼 급하지 않다. 08-01을 고칠 때 (B)를 같이 한다.
7. **재검토 조건.** 코디네이터 없이 쓰는 로컬 폼이 대부분이 되면 (A).
## 6. 실험·변이 기록
모든 실험은 분리 worktree(`agent-aa32fb83360602db8`, `e40684b`)에서 했다. 변이는 스크립트(`scratchpad/mutate-08.py`)가 한 줄을 바꾸고 테스트를 돌린 뒤 원문으로 되돌렸다. 끝난 뒤 `git status`에서 `src/` 변경 0건을 확인했다. probe 파일 3개는 리뷰가 끝나고 worktree에서 지웠다(`git checkout -- . && git clean -fd`). 같은 파일을 `scratchpad/review-08/`에 남겼다(`probe-08-form.test.tsx`, `probe-08-route-dup.test.ts`, `probe-08-focus.spec.ts`). 저장소에 넣으면 그대로 다시 돌릴 수 있다.
### 6.1 변이
부하(1분) 66~96. 결과 원본: `scratchpad/mutate-08-results.jsonl`.
| ID | 변이 | 돌린 테스트 | 결과 | 잡은 테스트 |
|---|---|---|---|---|
| M1 | 건너뛰기 링크 `href`를 `#content`로(`app-shell.tsx:59`) | component | 잡힘 | `app-shell.test.tsx`, `context-layouts.test.tsx`, `layout-landmarks.test.tsx` |
| M2 | `LoadingSurface`의 `aria-live` 제거 | component | 잡힘 | `async-surface.test.tsx` |
| M3 | 빈 화면 제목 `Heading` → `<p>` | component | 잡힘 | `async-surface.test.tsx`, `starter-pages.test.tsx`, `boot-module-failure.test.tsx` |
| M4 | 사이드바 `aria-label` 제거 | component | 잡힘 | `app-shell.test.tsx` |
| M5 | `RouteLifecycle`이 검색값 변경도 이동으로 봄(1101/08-02 되돌림) | component | 잡힘 | `router.test.tsx` |
| M6 | `applyOutcome`이 `VALIDATION_REJECTED` + `MAYBE_APPLIED`를 결과 불명으로 먼저 보냄 | component | 잡힘 | `form-foundation.test.tsx`(422 행) |
| M7 | 폼 문구 표에서 `NOT_BLANK` 제거 | component | 잡힘 | `form-foundation.test.tsx` 4건 |
| M8 | 폼 문구 표를 `Object.hasOwn`으로 조회(08-03 수정, 양성 대조) | unit + component | 통과(216 files / 2,847 tests) | 없음. 고쳐도 깨지는 테스트가 없고 지금 동작을 지키는 테스트도 없다 |
| M9 | 서랍의 테마 선택 제거(1101/08-01 되돌림) | component | **생존** | 없음. e2e `responsive.spec.ts`만 지킨다(미실행) |
| M10 | fixture 레이아웃 `<main>`의 `tabIndex={-1}` 제거 | component | **생존** | 없음(3.6절) |
| M11 | 같은 모양 경로 검사 끔(`8469554` 되돌림) | architecture + component | 잡힘 | `context-route-roots.test.ts` |
| M12 | 결과 불명 화면의 지원 참조 숨김 | component | 잡힘 | `async-surface.test.tsx` |
| M13 | "변경됨으로 확인" 뒤 입력을 지우지 않음 | component + features | 잡힘 | `reference-page.test.tsx:522-550` |
| M14 | 레이아웃을 가진 context도 루트에 붙는다고 보고 검사 | architecture + component | 잡힘 | `context-route-roots.test.ts`, `app-build-input.test.ts`, `context-layouts.test.tsx` |
잡음: `boot-unexpected-failure.test.tsx`가 14번 중 9번(M1, M4, M5, M7, M10~M14) 변이와 상관없이 실패했다. 변이 없는 트리에서 그 파일만 돌리면 부하 36~38에서 3/3 통과했다. 위 "잡은 테스트"에서는 뺐다(3.6절, 영역 10 인계).
### 6.2 브라우저 포커스 (P4)
`flock /tmp/claude-1000/review-2026-11-03-heavy.lock bash scratchpad/run-probe-08-focus.sh` → `corepack pnpm exec playwright test tests/e2e/probe-08-focus.spec.ts --project=chromium --project=firefox --project=webkit`. 저장소 `playwright.config.ts`의 webServer(`pnpm build` + preview 4173)를 그대로 썼다. 변이를 모두 되돌린 뒤의 깨끗한 트리에서 돌렸다. 23:35:24~23:35:41, 부하 17.5 → 15.5. 9 passed(15.9s). 로그: `scratchpad/probe-08-focus.log`.
절차: 참조 폼 열기 → 데모 로그인 → 이름 입력 → 저장 버튼에 `focus()` → Enter → 1.5초 → `document.activeElement` 기록 → Tab → 다시 기록.
| 응답 | 저장 뒤 포커스(3엔진) | Tab 뒤 | 저장 버튼 | 읽히는 영역 |
|---|---|---|---|---|
| 500(결과 불명) | `body` / `body` / `body` | 건너뛰기 링크 / 건너뛰기 링크 / `body` | 꺼짐 | `status`: "변경 결과를 확인할 수 없습니다. … 지원 참조: …" |
| 422 필드 오류 | 이름 입력란 ×3 | 메모 입력란 ×3 | 켜짐 | `alert`: "입력 내용을 확인해 주세요. 새 항목 이름: 입력값이 너무 짧습니다." |
| 429 | `body` ×3 | "초기화" 버튼 ×3 | 켜짐 | `alert`: "요청이 많습니다. … 다시 시도 … 지원 참조: …" |
출력 줄에 엔진 이름을 싣지 않아 행 안의 엔진 순서는 알 수 없다.
### 6.3 probe 결과 요약
| ID | 입력 | 관찰 |
|---|---|---|
| P1-1 | `409 POSTER_ALREADY_EXISTS` → 이름 수정 → 재전송(`500 IDEMPOTENCY_RECOVERY_REQUIRED`) → "변경됨으로 확인" | `effect-unknown`, 저장 꺼짐 → 수정 뒤에도 꺼짐 → 재전송 키 `key-1`·`key-1`, 그대로 `effect-unknown` → `success`, 이름 `""`, "saved" |
| P1-2 | 같은 409, 기능 `mapProblem`이 `VALIDATION_REJECTED` + `[{path:"name", code:"DUPLICATE"}]` | 필드 `aria-invalid="true"`, 요약 "Name: 입력값을 확인해 주세요.", 저장 꺼짐 → 수정 뒤 결과 `idle`, 저장 꺼짐 |
| P1-3 | `400 BAD_PARAMETER` / `422 IDEMPOTENT_REQUEST_MISMATCH` | `effect-unknown`, 저장 꺼짐 / `validation-error`, "입력값을 다시 확인해 주세요.", 저장 켜짐 |
| P1-4 | `validationMessage` | `NOT_BLANK` "필수 입력값입니다.", 모르는 code "입력값을 확인해 주세요.", `constructor`·`__proto__`·`toString`·`hasOwnProperty` "요청한 문구를 표시할 수 없습니다." |
| P1-0 | P1-1을 `classifyProblem: () => "NOT_APPLIED"`로 | 첫 409는 그대로 `effect-unknown`(표가 앞섬). 재전송의 500은 `retry-later`가 되고 저장이 켜짐(3.6절 영역 03 인계) |
| P2 | 두 기능 라우트 경로 쌍 | `/shop/items/:itemId`·`/shop/Items/:id`: 조립 통과, 라우터는 앞의 것만. `/shop/items`·`/shop/items/`: 조립 통과, 라우터는 `/shop/items/`만. `/shop/items/:itemId`·`/shop/items/:id`: 조립 거절 |
| P3 | `409 DB_UNIQUE_VIOLATION` → 폼 내림 → 같은 QueryClient·scope로 다시 그림 → 새 이름 입력 | 결과 `idle`, 저장 꺼짐, 결과 불명 문구 그대로, 요청 1회 |
@@ -0,0 +1,428 @@
# 09 애플리케이션 코어·기능·조립 — 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`
> 깊게 본 관점: 2, 3, 4, 9, 13, 22, 25, 27
> 렌즈: 바뀐 기능 모양(`FeatureRuntime.schemas`, V2 API 행 삭제, `installed-feature-runtime-registries.ts`), 참조 기능이 완성된 예시인가, 제품 확장 지점(`product-composition.ts`, `product-contracts.ts`, `ece944d`)만으로 제품을 만들 수 있는가, bootstrap의 401 처리와 세션 복구 동선
> 영역 판정(35.8): **조건부 사용 가능.** 기능은 생성 명령과 제품 소유 파일 두 개로 템플릿 파일을 고치지 않고 설치된다(E-PROD에서 템플릿 파일 diff 0). 조건은 다섯 가지다. (1) 제품 설정 키는 `.optional()`로만 쓰고, 제품 capability 보강은 기능 파일 안에 둔다(09-02 해결 전). (2) 짝 백엔드에 붙이기 전에 세션 owner를 제품이 직접 쓴다(09-03). (3) 릴리스 전에 예제 화면 4개를 지우거나 접근성 서명을 한다(09-04). (4) Service Worker를 켜면 템플릿 파일을 고친다(09-05). (5) 공개 API가 401을 주면 로그인한 사용자가 로그아웃된다는 것을 안다(09-01).
## 0. 결론
- 지난 라운드의 Medium 이상 네 건(1101/09-01 High, 09-02, 09-03, 09-06)은 모두 코드와 테스트로 닫혔다. 변이 세 개(M1~M3)를 넣으니 각각 테스트가 실패했다. Low 두 건(09-07, 09-09)도 닫혔다.
- 제품 확장 지점은 실행 경로에서 동작한다. 생성한 기능에 제품 인증 프로필·설정 키·FE-REG-ENV 행·capability를 붙여도 `check:architecture`, `check:registries`(additive)가 통과하고 템플릿 파일은 바뀌지 않았다.
- 타입 검사 경로에서는 막힌다(09-02). 문서대로 `product-composition.ts`에서 capability를 보강하면 `check:types:node`가 실패한다. 기본값 있는 제품 설정 키 하나가 템플릿 테스트 7개 파일의 타입을 깬다.
- 401 처리는 자격증명이 어디서 왔는지 보지 않는다(09-01). 헤더 없이 나간 `ANONYMOUS` 요청이 401을 받아도 로그인한 사용자가 로그아웃되고 서버 상태 캐시가 비워진다(E-A401).
- 사용자 목표(두 템플릿을 짝으로 빨리 출시)에 걸리는 공백이 둘이다. 짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 세션 owner가 없다(09-03). 참조 기능은 짝 백엔드의 Envelope wire가 아니어서 쓰기 경로 예제가 짝 백엔드에서 쓰이지 않는 분기를 보여 준다(09-06).
- 발견: High 0 · Medium 6 · Low 5. P1 2 · P2 5 · P3 4. 이월 2건(09-08, 09-09), 흡수 1건(1101/09-05 → 09-05), 새 발견 8건.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `e40684b`(`claude/happy-easley-233d07` + `fix/ui-design-audit-2026-11-01` 병합). 격리 worktree `agent-a9162b2ee3ef1b90f`에서 `git checkout --detach e40684b`, `corepack pnpm install --frozen-lockfile`. 2026-11-03 23시대 확인. 실험 뒤 `git checkout -- . && git clean -fd`로 되돌림 |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template`, 읽기만)와 함께 서비스를 빨리 출시. 정량 운영 목표 없음 |
| 읽은 코드·구성 범위 | `src/bootstrap/` 전체(`runtime-adapters.ts` 전문, `product-composition*.ts`, `create-runtime-composition.ts`, `composition-root.ts`, `boot.tsx`, `main.tsx`, `optional-runtime-host.ts`), `src/features/` 최상위 파일 전부, `reference-feature/`의 module·runtime·context-routes·contribution·gateway·failure action, `local-draft-feature/NOT_INSTALLED`, `src/apps/*`, `src/contexts/*`, `src/application/create-application.ts`·`ports/auth-session-port.ts`·`result.ts`. 연결 확인: `src/adapters/auth/external-session-adapter.ts`, `src/adapters/http/http-execution-v3.ts`(401·scope·Envelope 판정 부분), `src/contracts/{product-contracts,rest-profiles,env,release-artifacts,routes,external-contract-runtime}.ts`, `src/presentation/{providers/session-provider,layouts/app-shell,routes/navigation-policy,routes/app-router}.tsx`, `scripts/{create-feature,generate-product-feature-index,test-sample-removal,check-registries,verify-a11y-manual}.ts`, `scripts/lib/manual-a11y-evidence.ts`, `tsconfig.{app,node,test}.json`, `.dependency-cruiser.json`, `docs/manual/01~03`, `docs/architecture/{starter-experience,optional-adapter-recipes,frontend-application-foundation}.md`. 짝 백엔드: `docs/web/http-contract.md` 1절, `src/adapter/inbound/web/README.md` 69~73행, `app-bootstrap/.../application-local.yml` |
| 수행한 테스트·실험 | 1.1절. 전체 게이트는 다시 돌리지 않고 오케스트레이터 결과를 인용했다 |
| 확인하지 못한 범위·이유 | 1.2절 |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-01-maturity-review/09-app-core.md`의 09-01~09-09와 FOLLOW-UP 두 건, README 13~14절의 이 영역 조치. 지난 실행 결과는 증거로 쓰지 않았다. 각 항목을 현재 코드와 새 실행으로 다시 판정했다(2절) |
### 1.1 게이트 결과(인용)와 이 리뷰의 실행
오케스트레이터가 같은 커밋에서 돌린 결과(`scratchpad/review-gates/summary.txt`): `check:architecture`, `check:types`, `lint`, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `check:registries`, `check:i18n`, `check:design-system`, `check:diagnostics` 모두 exit 0. `test:unit` 2,580 · `test:component` 263 · `test:integration` 117 · `test:contract` 23 · `test:runtime-schema` 56 통과. `bundle` PASS(초기 JS 201,848 / 204,800 gzip B).
이 리뷰에서 직접 돌린 것은 6절에 모았다. 요약:
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | 영역 테스트 묶음(`tests/features`, `tests/architecture`, `tests/platform`, `tests/contract/reusable-capability`, 조립·제품·라우터 관련 unit·component 18개) | 77 files / 522 tests 통과, 12.74s(load 10.9) |
| E-A401 | `ANONYMOUS` operation이 401을 받을 때 세션 | demo: 로그아웃·scope fence. external: `notifyUnauthenticated` 1회 |
| E-PROD | 생성 기능 + 제품 소유 파일 두 개만으로 제품 구성 | 템플릿 파일 diff 0. node 타입 검사 실패(보강 위치), test 타입 검사 8건 실패(기본값 키) |
| E-AUTHID | 제품 인증 프로필 id 오타 | 게이트 출력에 operation·프로필 id 없음 |
| E6 | `needs: ["telemetry"]` 기여가 받는 키 | `["telemetry","http"]` |
| M1~M3 | 1101/09-01·09-06 수정을 하나씩 끄는 변이 | 각각 6·11·3개 테스트 실패 |
### 1.2 확인하지 못한 범위
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 짝 백엔드에 실제로 붙인 로그인·401 | Keycloak·백엔드를 띄우지 않았다 | 백엔드 local + Keycloak로 bearer operation 1회, 공개 경로 401 1회 |
| 09-01의 브라우저 화면 | vitest로 조립 루트만 실행했다 | Playwright로 공개 화면 401 뒤 세션 표시 확인 |
| 401과 scope 변경이 겹치는 경쟁 | 재현 장치를 만들지 않았다. 실행기는 scope fence 때 요청을 끊지만 401 분류 직전 scope 확인은 없다(`http-execution-v3.ts:1270-1275`) | 응답 도착과 계정 전환을 같은 tick에 맞춘 단위 테스트 |
| 09-04·09-05 제안의 실제 효과 | 설계 제안이다 | 구현 뒤 `test:sample-removal`, SW 켠 제품 픽스처로 템플릿 diff 0 확인 |
| 다운스트림(tech-log, memento) 현재 상태 | 이번에는 읽지 않았다 | `git diff --name-status` 재추출 |
| `test:sample-removal`, `product-feature-selection-build`, e2e | 무거운 검사이고 이 영역 판단에 필요한 증거는 단위 실행으로 충분했다 | heavy lock 아래 실행 |
## 2. 지난 발견 재판정
지난 ID는 `1101/09-NN`이다. "이번 ID"는 3절 기준이다.
| 지난 ID | 판정 | 이번 ID | 근거 |
|---|---|---|---|
| 1101/09-01 `ANONYMOUS` 요청이 전송되지 않음 (High·P1) | **고쳐짐** | — (관련 새 결함 09-01) | `attachCredentials`가 scope 확인 다음에 프로필 transport를 본다(`src/bootstrap/runtime-adapters.ts:484-493`). `tests/unit/runtime-adapters-auth-profile.test.ts`가 네 세션 상태를 본다. **M1**: `"ANONYMOUS"` 비교를 깨면 2 files 6 tests 실패. 다만 401 응답 처리 쪽은 프로필을 보지 않는다(09-01) |
| 1101/09-02 제품 capability·자격증명·설정 확장 지점 없음 (Medium·P1) | **고쳐짐(실행 경로) · 바뀜(타입 경로)** | 09-02, 09-05 | 제품 소유 파일 `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, 계약 `product-composition-contract.ts`. 조립 루트가 session owner(`:284-290`), provider(`:494-504`), capability(`:607-629`)를 받는다. 제품 키·프로필·env 행은 템플릿 이름과 겹치면 로드 때 throw(`release-artifacts.ts:159-168`, `rest-profiles.ts:204-214`, `env.ts:80-90`). `tests/unit/product-composition-fixture.test.ts` 13건 통과(R1). E-PROD에서 템플릿 파일 diff 0. 그러나 타입 검사 경로 두 곳이 막힌다(09-02). 선택 런타임 연결은 여전히 템플릿 파일이다(09-05) |
| 1101/09-03 라우터가 `AppShell`·`APP_HOME` 고정 (Medium·P1) | **고쳐짐** | — | 기능이 `APP_HOME`을 대신한다(`src/contracts/routes.ts:107-139`). context가 레이아웃을 선언한다(`src/contexts/bounded-context-module.ts:9-20`). `tests/component/context-layouts.test.tsx` 6건, `layout-landmarks.test.tsx`가 설치된 제품의 레이아웃을 읽어 skip link·`<main>`을 검사한다. README 14.4의 "플랫폼 라우트와 같은 경로를 검사하지 않음"은 `7d85589e`·`84695549`로 닫혔다(`src/apps/deployable-app-module.ts:92-127`) |
| 1101/09-04 `NOT_INSTALLED` 다의, 졸업 경로 없음 (Low·P3) | **남음** | 09-09 | 생성기는 `feature-module.ts`가 없을 때만 표시를 읽는다(`scripts/generate-product-feature-index.ts:292-305`). 같은 단어가 런타임 상태로도 쓰인다(`src/contracts/product-features.ts:32`) |
| 1101/09-05 선택 파일에 템플릿 설명과 제품 상수가 섞임 (Low·P3) | **바뀜 → 흡수** | 09-05 | 주석은 1101/09-07 내용으로 고쳐졌다(`src/features/installed-runtime-capabilities.ts:21-24`). 템플릿 상태 설명은 여전히 같은 블록이다(`:26-37`). 원인이 넓어졌다: SW를 켜려면 이 파일을 고쳐야 하는데 "Product-owned." 표시가 없고 매뉴얼은 `installed-*.ts`를 고치지 말라고 한다 |
| 1101/09-06 루트 밖 라우트가 `NOT_FOUND` (Medium·P2) | **고쳐짐** | — | 앱 정의 때 throw(`src/apps/deployable-app-module.ts:38`, `:70-127`), 핸들 검사는 라우트 적재 때(`src/contexts/bounded-context-module.ts:81-103`). `tests/architecture/context-route-roots.test.ts` 20건. **M2**: 호출을 주석 처리하면 11 tests 실패. **M3**: 핸들 검사를 `continue`로 바꾸면 3 tests 실패 |
| 1101/09-07 선택만 하고 시작 안 되는 capability (Low·P3) | **고쳐짐** | — (안내 문구 문제는 09-05) | 시작 수단 없는 선택이면 조립이 throw한다(`src/bootstrap/optional-runtime-host.ts:51-65`). 그 메시지가 템플릿 파일 수정을 안내한다(09-05) |
| 1101/09-08 `needs` 좁히기가 타입에서만 (Low·P3) | **남음(범위 넓어짐)** | 09-08 | `invokeContribution`이 context 전체를 넘긴다(`src/features/feature-adapter-contribution.ts:229-237`, `:285-291`). E6 결과가 지난번과 같다. 생성 뼈대가 같은 틀린 주석을 모든 기능에 쓴다(`scripts/create-feature.ts:834`). 이제 제품 capability도 모든 기능에 간다 |
| 1101/09-09 바깥 경계 실패 진단 없음 (Low·P2) | **고쳐짐** | — | gateway가 두 경계에 `onError`→`reportRenderFailure`, 화면에 `<buildId>:<incidentId>`(`src/presentation/routes/app-router.tsx:549-562`). `tests/component/context-boundary-diagnostics.test.tsx` 통과(R1) |
| 0925 FOLLOW-UP 09-07 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | **남음** | — (지난 판정 유지) | `scripts/test-sample-removal.ts:400-415` 목록에 셋이 없다 |
| 0925 FOLLOW-UP 09-08 local-draft ABA를 주석으로 닫음 | **남음(허용한 대안)** | — | `src/features/local-draft-feature/domain/local-draft.ts:2-11` |
| README 14.4 "09-02 이식: FE-REG-ENV 행과 부트 전 BFF owner는 템플릿 수정 필요" | **고쳐짐** | — | `ece944d`. `PRODUCT_ENV_REGISTRY`가 `ENV_REGISTRY`에 합쳐지고(`env.ts:44`, `:80-90`), `composeProductSessionOwner`가 external 모드에서 host 전역보다 먼저 불린다(`runtime-adapters.ts:284-290`). 픽스처 테스트가 확인한다 |
| README 14.6 "참조 기능을 Envelope로 옮길지 결정 필요" | **남음(결정 기록 없음)** | 09-06 | `src/features`에 `responseEnvelope` 0건 |
## 3. 이번 발견 (36.3)
요약: High 0 · Medium 6 · Low 5. P1 2(09-02, 09-03) · P2 5(09-01, 09-04, 09-05, 09-06, 09-07) · P3 4(09-08~09-11).
### 09-01 세션 자격증명을 싣지 않은 요청의 401도 템플릿 세션을 로그아웃시킨다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 6, 5, 7, 8, 15, 17, 28, 10 (29.3 인증 범위, 32 세션 만료) |
| 근거 | 조립 루트는 응답이 있는 `UNAUTHENTICATED`면 프로필을 보지 않고 `authSession.onUnauthenticated()`를 부른다(`src/bootstrap/runtime-adapters.ts:588-593`). `ANONYMOUS` 요청은 세션을 묻지 않고 헤더 없이 `credentials: "omit"`으로 나간다(`:484-493`, `src/contracts/rest-profiles.ts` ANONYMOUS 행). 제품 provider 프로필도 세션 대신 provider가 답한다(`:494-504`). **E-A401**: demo 로그인 뒤 `ANONYMOUS` operation이 401을 받으면 결과는 `UNAUTHENTICATED`, 보낸 자격증명 헤더 0개, 세션은 `unauthenticated`, 이전 scope는 current가 아니다(서버 상태를 비움). external owner로 같은 요청을 보내면 `attachCredential` 0회, `notifyUnauthenticated` 1회. 대조군 bearer 401도 1회(의도된 동작). 제품 provider 프로필의 401은 코드로만 확인했다. 기존 테스트는 bearer 401만 본다(`tests/features/reference-feature/reference-runtime-composition.test.ts` "still signs out when the server answers 401") |
| 발생 조건 | 공개로 선언한 operation에 서버가 401을 준다. 예: 백엔드가 그 경로를 인증 필요로 바꿨는데 옛 탭·옛 빌드가 `ANONYMOUS`로 부른다. 프론트가 프로필을 잘못 골랐다. 짝 백엔드 local은 `/api/healthcheck`만 공개다(`application-local.yml:161`). 또는 쿠키 provider 프로필 요청이 401인데 세션 owner는 bearer owner나 demo다 |
| 영향 | 토큰이 유효한 사용자가 로그아웃된다. scope fence가 서버 상태 캐시를 모두 비운다. 그 화면에 다시 들어가면 또 로그아웃된다. 진단에는 그 operation의 `http.request.completed` 1건만 남고 로그아웃 원인과 연결되지 않는다 |
| 심각도·우선순위 | Medium · P2 — 정보 노출은 없다. 그러나 공개 화면 하나의 계약 어긋남이 앱 전체 세션을 끊는다. 공개 화면은 흔한 요구이고 수정은 몇 줄이다 |
| 통제·증거 | 목표 M3(조립 루트 경유 테스트) / 확인 M0 · E2(E-A401), provider 경로 E1 |
| 확실성과 남은 가정 | demo·external 두 경우를 재현했다. 짝 백엔드가 실제로 공개 경로에 401을 주는 빈도는 모른다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: "R-3.2. Only a server 401 is a session verdict"(`:588`), 설계 §8.4 "response 401은 terminal `UNAUTHENTICATED`". 리뷰어 추론: 401이 세션 판정이 되려면 그 요청이 세션의 자격증명을 실었어야 한다. `ANONYMOUS` 요청은 아무것도 싣지 않는다 |
| 이해 비용 | 401→로그아웃 규칙을 보려면 같은 파일의 두 곳(`attachCredentials` 분기, `execute` 끝)을 함께 읽어야 한다 |
| 최소 개선 방향 | `execute` 끝의 조건에 "이 operation의 자격증명을 세션이 냈다"를 더한다. 프로필 transport가 `ANONYMOUS`가 아니고 `productCredentialProviders`에 없는 프로필일 때만 `onUnauthenticated`를 부른다. 제품 provider에는 401을 받을 선택 hook을 둔다(BFF 제품은 거기서 owner에게 알린다) |
| 대안 비교 | (A) 현 상태: 비용 0, 과잉 로그아웃. (B) `ANONYMOUS`만 제외: 2줄, provider 경로는 남는다. (C) 자격증명 출처별 판정 + provider hook: 수십 줄, 출처마다 책임이 맞다. (D) 401을 세션 판정으로 쓰지 않고 owner가 스스로 판단: owner 계약이 바뀌고 만료 감지가 늦어진다. 5.2절 |
| 단순화의 보존 조건 | bearer 401은 지금처럼 로그아웃한다. 보내기 전 거절(metadata 없음)은 계속 세션 판정이 아니다(R-3.2). 401 뒤 재전송은 없다(§8.4) |
| 비용·부작용 | (C)를 고르면 BFF 제품이 provider hook 한 줄을 쓴다 |
| 재검토 조건 | 한 앱이 operation마다 다른 세션(계정·테넌트)을 쓰게 되면 판정 단위를 다시 본다 |
| 완료 기준 | E-A401의 `ANONYMOUS` 두 경우에서 세션 상태 유지, `notifyUnauthenticated` 0회, scope 유지. bearer 대조군은 1회 |
| 검증 방법 | `tests/unit/runtime-adapters-auth-profile.test.ts`에 E-A401 세 케이스를 더하고 수정 전 실패를 먼저 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-02 제품 확장 지점의 타입 검사 경로가 막힌다: 문서 위치의 capability 보강은 node 검사에서 안 보이고, 기본값 있는 제품 설정 키는 템플릿 테스트 7개 파일의 타입을 깬다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 3, 21, 25, 4, 8, 10, 19, 20 (30.3) |
| 근거 | **(a) 보강 위치.** 문서는 "augment `FeaturePlatformCapabilities` and return the capability here"(`docs/architecture/starter-experience.md:189`, `src/features/feature-adapter-contribution.ts:135-137`)라고 한다. `tsconfig.node.json`은 `scripts/**`와 `*.config.ts`만 포함한다. 스크립트는 기능 코드를 끌어오지만 `product-composition.ts`는 끌어오지 않는다. 그래서 보강 선언이 node 프로그램에 없다. **E-PROD**: `product-composition.ts`에 보강하면 `check:types:app` 통과, `check:types:node` 실패 2건. 오류 위치는 기능 파일(`'noticeSettings' is not assignable to type 'keyof FeaturePlatformCapabilities'`)이다. 같은 보강을 기능 파일로 옮기면 통과한다. **(b) 기본값 키.** `RuntimeConfig`는 템플릿 필드 & `Pick<RuntimeConfigV2, 제품 키>`다(`src/bootstrap/runtime-config-schema.ts:33-63`). zod `.default()` 키는 출력 타입에서 필수다. 템플릿 테스트는 `RuntimeConfig`를 리터럴로 만든다. E-PROD에서 `NOTICE_PAGE_SIZE: z.int().min(1).max(100).default(20)` 하나로 `check:types:test`가 8건 실패했다: `tests/unit/runtime-adapters.test.ts:13`, `runtime-adapters-auth-profile.test.ts:86`, `runtime-adapters-credential-order.test.ts:92`, `feature-override-diagnostics.test.ts:21`, `release-coherence.test.ts:58,78`, `tests/runtime-schema/release-manifest.test.ts:24`, `tests/features/reference-feature/reference-runtime-composition.test.ts:17`. `.optional()`로 바꾸면 0건이다. 제품 계약 주석은 FE-REG-ENV 행에 `defaultValue`를 적게 하고(`src/contracts/product-contracts.ts:7-11`), 픽스처도 `.default("MOCK")`를 쓴다(`tests/unit/product-composition-fixture.test.ts:80`). 픽스처는 두 파일을 `vi.mock`으로 바꾸므로 타입 경로를 지나지 않는다. `two-feature-install-typecheck.test.ts`는 `tsconfig.app.json`만 돈다(`:153-183`) |
| 발생 조건 | 제품이 템플릿이 만들지 않는 capability를 기능에 주면서 문서 위치에 보강한다. 또는 기본값이 있거나 필수인 제품 설정 키를 더한다(tech-log의 `TECH_LOG_STUDIO_SOURCE`가 기본값 키다) |
| 영향 | merge 게이트 `check:types`가 실패한다. 통과하려면 템플릿 테스트 7개 파일을 고치거나(동기화 충돌 자리가 다시 생긴다) 규칙을 스스로 알아내야 한다. (a)의 오류는 원인과 먼 기능 파일을 가리키고 app 검사는 통과해 헷갈린다 |
| 심각도·우선순위 | Medium · P1 — 실행 결과는 맞다. 그러나 1101/09-02를 닫은 근거("템플릿 파일을 고치지 않는다")가 첫 제품 키·첫 capability에서 merge 게이트로 깨진다. 빠른 출시 목표의 첫 단계다 |
| 통제·증거 | 목표 M3(제품 파일을 실제로 채운 복사본에서 tsc 3종) / 확인 M0 · E3(E-PROD, 실제 tsc) |
| 확실성과 남은 가정 | tsc로 재현했다. 다운스트림의 실제 이식은 보지 않았다 |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `ece944d` 본문이 "제품 행을 as const 없이 쓰면 tsc 오류가 env.ts:78(템플릿 파일)에서 난다"고 타입 경로 위험의 일부를 적었다. 리뷰어 추론: 런타임 mock 픽스처만 있고 실제 파일로 채운 타입 검사가 없어서 생긴 틈이다 |
| 이해 비용 | 제품 개발자가 tsconfig 세 개의 포함 범위와 zod 출력 타입 규칙을 알아야 한다 |
| 최소 개선 방향 | (1) 보강 위치를 하나로 정한다. 제품 소유 빈 파일(예: `src/features/product-capabilities.ts`)을 두고 `feature-adapter-contribution.ts`가 `import type`으로 읽으면 모든 프로그램에 들어간다. 최소안은 문서를 "필요한 기능 파일 안에서 보강"으로 고치는 것이다. (2) 템플릿 테스트가 `RuntimeConfig`를 리터럴 대신 `validateRuntimeConfig(문서)`나 공용 helper로 만든다. 그러면 제품 기본값이 채워진다. (3) 제품 파일을 실제 파일로 채운 복사본에서 `check:types` 3종을 도는 테스트를 더한다 |
| 대안 비교 | (A) 문서에 "optional 키만, 기능 안에서 보강": 비용 작음, 기본값 키를 쓰는 기존 제품이 막힘. (B) 위 (1)~(3): 템플릿 수십 줄 + 테스트 7개 한 번 수정. (C) `RuntimeConfig`의 제품 키를 모두 `Partial`: 기본값 키도 `undefined` 처리를 강요해 타입이 느슨해진다 |
| 단순화의 보존 조건 | 제품 키는 strict 스키마로 검증된다. 템플릿 키와 이름이 겹치면 로드 때 throw한다. 픽스처의 "제품 소유 두 파일만 mock" 검사(`product-composition-fixture.test.ts:415-440`)는 유지한다 |
| 비용·부작용 | 테스트 helper 1개, 템플릿 테스트 7개 한 번 수정, typecheck 테스트 실행 수 초 |
| 재검토 조건 | 제품 키 값이 템플릿 테스트의 기대값에 들어가야 하는 요구가 생기면 |
| 완료 기준 | E-PROD(문서 위치 보강, `.default()` 키)로 `check:types` 3종 통과, 템플릿 파일 diff 0 |
| 검증 방법 | (3)의 테스트. 보강을 지우거나 키를 템플릿 이름으로 바꾸면 그 테스트가 실패하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-03 짝 백엔드의 인증 방식에 맞는 세션 owner가 없어, 제품마다 첫 연동 전에 owner를 처음부터 써야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(사용자 목표 기준의 공백) |
| 관련 관점 | 3, 15, 20, 22, 25, 13(제품 수 축) (30.5, 30.8) |
| 근거 | demo 세션은 local 밖에서 설정 검증이 거부한다(`src/contracts/release-artifacts.ts:104`). development·staging·production 설정은 `AUTH_MODE: "external"`이다(`config/runtime/*.json`). external은 제품이 owner 8개 메서드를 구현해야 한다(`docs/architecture/starter-experience.md:47-53`, `src/adapters/auth/external-session-adapter.ts:10-27`). src·recipes·매뉴얼에 OIDC·Keycloak·PKCE owner가 없다(git grep 0건). 짝 백엔드는 JWT(issuer 기본값 `http://localhost:8081/realms/ca-skeleton`) 또는 Redis session(쿠키 + CSRF) 중 하나다(백엔드 `src/adapter/inbound/web/README.md:69-73`, `application-local.yml:92`, `:159-161`). demo 표식 `Bearer demo-session-not-a-secret`은 JWT 검증을 통과할 수 없다(추론). 401이 오면 demo 세션은 로그아웃된다(`external-session-adapter.ts:152`). 쿠키 세션 owner의 모양은 테스트 파일 안 스케치뿐이다(`tests/unit/product-composition-fixture.test.ts:117-160`). 그 스케치는 시간 제한 없는 raw fetch로 세션을 묻는다. owner context는 config와 raw `fetcher`만 준다(`src/bootstrap/product-composition-contract.ts:19-23`) |
| 발생 조건 | 제품이 짝 백엔드에 처음 붙인다. local 개발도 해당한다 |
| 영향 | owner가 생기기 전까지 인증 필요한 기능은 짝 백엔드에서 한 번도 성공하지 않는다. 제품마다 토큰 획득·갱신·subject·상태 전이·만료 처리를 새로 쓴다. 보안 코드라 실수 비용이 크다. 템플릿이 owner 결함을 고쳐도 제품에 전할 경로가 없다 |
| 심각도·우선순위 | Medium · P1 — 코드 결함이 아니라 공백이다. 템플릿은 owner를 제품 책임으로 적었다. 그러나 "두 템플릿을 짝으로 빨리 출시"라는 목표에서 첫 연동을 막는다 |
| 통제·증거 | 목표 M2(짝 백엔드 모드별 owner recipe와 테스트) / 확인 M1(계약 문서만) · E1 |
| 확실성과 남은 가정 | 실제로 짝 백엔드에 붙여 보지 않았다. demo 토큰 거부는 백엔드 JWT 설정으로 추론했다 |
| 결정의 근거 | 기록된 의도: "It owns token acquisition and storage"(`starter-experience.md:50`). 가이드 0.2: 템플릿은 "신뢰 경계, 확장 위치, 허용·거부 예제"를 준다. 확장 위치(`composeProductSessionOwner`)는 있다. 허용·거부 예제는 테스트 안에만 있다 |
| 이해 비용 | owner 작성자는 `SessionGateway` 주석, subject와 scope fence 규칙, R-3.2, recover 규약을 여러 파일에서 모아야 한다 |
| 최소 개선 방향 | recipes에 짝 백엔드 두 모드의 owner를 둔다. (1) OIDC PKCE + Keycloak bearer owner. (2) Redis session 쿠키 owner + CSRF provider(픽스처 스케치를 승격). 각각 상태 전이·subject·401·recover를 테스트한다. owner context에 시간 제한 있는 fetch를 준다. 매뉴얼에 "짝 백엔드에 처음 붙이기" 절을 둔다 |
| 대안 비교 | (A) 현 상태. (B) 선택 recipe(번들 밖): OIDC 라이브러리 의존을 recipe에만 둔다. (C) src에 기본 owner 내장: 라이브러리 의존과 IdP 결합이 템플릿 본체에 들어간다. (D) 매뉴얼만: 코드가 없어 제품마다 같은 실수를 반복한다 |
| 단순화의 보존 조건 | owner가 없으면 `integration-failed`로 닫힌다. demo는 local 전용이다. 자격증명은 프로필 허용 헤더만 나간다 |
| 비용·부작용 | recipe 수백 줄과 테스트. 백엔드 인증 설정이 바뀌면 함께 맞춘다 |
| 재검토 조건 | 짝 백엔드가 인증 모드를 바꾸거나, 제품 대부분이 다른 IdP를 쓰게 되면 |
| 완료 기준 | 짝 백엔드 local(Keycloak)에 recipe owner로 로그인해 `EXTERNAL_BEARER` operation 1회 성공. Redis session 모드에서 쿠키 owner로 쓰기 1회 성공(CSRF 헤더 포함) |
| 검증 방법 | recipe 단위 테스트 + 짝 백엔드 local 대상 e2e 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-04 플랫폼 예제 화면 4개를 제품이 끌 자리가 없고, 릴리스 게이트가 그 화면의 접근성 서명을 요구한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 27, 3, 23, 25, 18 (30.1, 30.7) |
| 근거 | `/examples/platform`, `/examples/ui`, `/examples/states`, `/examples/auth`는 플랫폼 레지스트리에 고정이다(`src/contracts/routes.ts:33-84`). 탐색 메뉴에도 나온다(`navigationOrder` 15~40). 기능이 대신할 수 있는 플랫폼 라우트는 `APP_HOME` 하나다(`routes.ts:114-115`). `VITE_PRODUCT_FEATURES`와 `FEATURE_OVERRIDES`는 기능만 뺀다. 릴리스 게이트 FE-GATE-028은 `ROUTE_REGISTRY`의 모든 라우트에 서명된 수동 접근성 기록을 요구한다(`scripts/lib/manual-a11y-evidence.ts:1-4`, `scripts/verify-a11y-manual.ts`). `artifacts/tests/a11y-manual/EXAMPLES_*.md` 네 개는 `pending-manual-review`다. 문서는 화면과 테스트를 "delete them together"라고 한다(`docs/architecture/starter-experience.md:86-95`). 지우려면 src의 템플릿 파일 5개(`routes.ts`, `route-runtime-contract.ts`, `presentation/routes/route-runtime.tsx`, `presentation/i18n/catalog.ts`, `presentation/pages/home-page.tsx`)와 `src/presentation/examples/`를 고친다. 이 ID들을 참조하는 파일은 src·tests·scripts·config·artifacts에 19개다 |
| 발생 조건 | 제품을 staging·production으로 릴리스한다 |
| 영향 | 제품은 (1) UI 갤러리 같은 템플릿 화면을 운영 메뉴에 두고 접근성 서명까지 하거나, (2) 템플릿 파일을 지우고 동기화마다 충돌을 감수한다. `/examples/platform`은 열면 모든 기능 실행부를 내려받는다(`src/presentation/examples/platform-overview-page.tsx:599`) |
| 심각도·우선순위 | Medium · P2 — 기능 실패는 없다. 출시마다 반복되는 비용이고 동기화 충돌 자리다 |
| 통제·증거 | 목표 M2(선택 장치) / 확인 M0 · E1 |
| 확실성과 남은 가정 | 정적으로 확인했다. 실제 릴리스 게이트는 돌리지 않았다 |
| 결정의 근거 | 기록된 의도: 예제 화면은 "template content"(`starter-experience.md:88`). 기능에는 선택·제거 장치가 있다. 같은 장치를 예제 화면에 쓰지 않은 이유는 기록에 없다 |
| 이해 비용 | 예제를 지우려면 레지스트리·runtime 표·문구·테스트·a11y 기록의 연결을 찾아야 한다 |
| 최소 개선 방향 | 예제 화면 4개를 기능 하나(예: `platform-examples-feature`)로 옮긴다. 그러면 `VITE_PRODUCT_FEATURES`, 제거 드릴, a11y 목록이 그대로 적용된다 |
| 대안 비교 | (A) 현 상태: 제품이 지운다. (B) 기능으로 옮김: 기존 장치 재사용, 플랫폼 테스트 일부를 fixture로 옮김(대부분 이미 `tests/helpers/fixture-feature.tsx`로 돈다). (C) 빌드 변수로 숨김: 선택 장치가 하나 더 생긴다 |
| 단순화의 보존 조건 | `APP_HOME`·`NOT_FOUND`는 남는다. 플랫폼 컴포넌트 테스트는 fixture 기능으로 돈다. 예제 화면의 e2e·시각 테스트는 예제가 설치된 구성에서 돈다 |
| 비용·부작용 | 라우트 4개 이동, 테스트 경로 조정 |
| 재검토 조건 | 운영자가 `/examples/platform`을 운영 진단 화면으로 쓰게 되면 접근 제어와 함께 다시 본다 |
| 완료 기준 | 예제 기능을 선택에서 빼면 4 라우트가 레지스트리·메뉴·번들·a11y 목록에서 사라지고 템플릿 파일 diff가 0이다 |
| 검증 방법 | `test:sample-removal -- --feature=<예제 기능>` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-05 Service Worker 등 선택 런타임을 켜고 연결하는 일이 제품 확장 지점 밖에 있고, 매뉴얼은 그 파일을 고치지 말라고 한다 (흡수: 1101/09-05)
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 3, 25, 23, 4, 20, 22 (30.3) |
| 근거 | SW를 켜는 방법은 `src/features/installed-runtime-capabilities.ts`의 `SERVICE_WORKER` 상수를 바꾸는 것뿐이다(`:43`, `docs/architecture/optional-adapter-recipes.md:129-130`). 이 파일에는 "Product-owned." 표시가 없고, 픽스처의 제품 소유 검사도 두 파일만 본다(`tests/unit/product-composition-fixture.test.ts:415-440`). 매뉴얼 D절은 `src/features/installed-*.ts`를 고치지 말라고 한다(`docs/manual/03-outside-feature-folder.md:126`). SW 운영에 필요한 blockers·observe·health 연결은 "다운스트림이 `createRuntimeComposition`에서 연결한다"(`optional-adapter-recipes.md:136-141`)고 적혀 있고, 그 파일은 템플릿 소유다. realtime·worker·offline을 고르면 조립이 "Connect a runtime in src/bootstrap/optional-runtime-host.ts"로 거절한다(`src/bootstrap/optional-runtime-host.ts:60-64`). `ProductComposition`에는 이 자리가 없다(`product-composition-contract.ts:56-64`). 1101/09-05의 "템플릿 상태 설명과 선택 상수가 한 블록"도 그대로다(`installed-runtime-capabilities.ts:26-45`) |
| 발생 조건 | 제품이 지원 실행 형태인 SW를 켜거나 realtime을 쓴다 |
| 영향 | `ece944d`가 없앤 "부트 전 훅이 템플릿 파일에 남는다"와 같은 종류의 수정이 SW·realtime에 남는다. 동기화마다 손으로 병합한다. 매뉴얼을 그대로 따르면 SW를 켤 수 없다 |
| 심각도·우선순위 | Medium · P2 — SW는 기본 꺼짐이라 첫 출시를 막지 않는다. 켜는 순간 템플릿 파일을 고친다 |
| 통제·증거 | 목표 M2(제품 소유 선택 파일 + 연결 칸) / 확인 M0 · E1 |
| 확실성과 남은 가정 | 정적으로 확인했다. SW를 실제로 켜 보지 않았다 |
| 결정의 근거 | 기록된 의도: "§3.5. Static optional capability selection SSOT"(`installed-runtime-capabilities.ts:15-19`), 런타임 설정은 빼기만 한다. 리뷰어 추론: 선택을 정적으로 두는 것은 맞다(설정 문자열로 import 경로를 만들지 않는다). 문제는 그 정적 선택이 제품 소유 파일에 있지 않다는 점이다 |
| 이해 비용 | 제품 개발자는 선택 파일, optional host, 레시피 문서, 매뉴얼 D절이 서로 다른 말을 하는 것을 맞춰 읽어야 한다 |
| 최소 개선 방향 | 선택 상수를 제품 소유 파일(`product-contracts.ts` 또는 새 제품 소유 선택 파일)로 옮기고 `installed-runtime-capabilities.ts`는 검증·투영만 한다. `composeProduct` 결과에 SW 연결 칸(`blockers`, `observe`)을 둔다. 매뉴얼 C절에 "SW 켜기"를 넣는다 |
| 대안 비교 | (A) 현 상태 + 매뉴얼에 "이 파일만 예외로 고친다": 충돌이 남는다. (B) 위 제안. (C) 런타임 설정으로 켜기: §3.5가 금지한다(설정은 빼기만) |
| 단순화의 보존 조건 | 런타임 설정은 빼기만 한다. SW 선택 시 두 단계 빌드(`scripts/build-frontend.ts`)가 돈다. 시작 수단 없는 선택은 조립이 거절한다(1101/09-07) |
| 비용·부작용 | 파일 이동과 검사 몇십 줄 |
| 재검토 조건 | realtime 런타임이 조립에 연결되면 그 연결 칸도 같은 자리에 둔다 |
| 완료 기준 | SW `ACTIVE` + blockers 1개를 제품 소유 파일만 고쳐 켜고, 템플릿 파일 diff 0, SW 관련 테스트 통과 |
| 검증 방법 | 제품 픽스처에 SW 케이스(실제 파일) + `build` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-06 참조 기능이 짝 백엔드의 응답 모양이 아니어서, 쓰기 경로 예제가 짝 백엔드에서 쓰이지 않는 분기를 보여 준다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(샘플 대표성) |
| 관련 관점 | 17, 4, 9, 20, 23 (30.5) |
| 근거 | `src/features`에 `responseEnvelope`가 0건이다. 참조 기능은 problem details와 DTO를 읽는다(`docs/manual/01-add-a-feature.md:219`). 생성 뼈대는 `ENVELOPE_V1`이지만 GET 목록 하나뿐이다(`scripts/create-feature.ts:16-19`). 쓰기(KEYED POST, 결과 불명, 필드 오류)의 예제는 참조 기능뿐이다(`docs/manual/reference/patterns.md:87-98`). 참조 `CREATE_EFFECT`는 400·422를 `NOT_APPLIED`로 본다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:49-70`). Envelope operation에서는 400·409·422 판정을 실행기의 표가 정하고 `classifyProblem`은 쓰이지 않는다(`src/adapters/http/http-execution-v3.ts:1722-1731`, 매뉴얼 02:142). 참조 `mapProblem`은 422를 필드 오류로 읽는다(`src/features/reference-feature/adapters/reference-http-gateway.ts:53-58`). 짝 백엔드는 필드 검증을 400 `VALIDATION_FAILED`로 보낸다(1101 README 14.6 표). 14.6이 "참조 기능을 Envelope로 옮길지는 결정이 필요하다"로 남겼고 결정 기록은 없다 |
| 발생 조건 | 제품 개발자가 쓰기 기능을 참조 기능 모양대로 옮긴다 |
| 영향 | 옮긴 `classifyProblem` 분기는 Envelope에서 아무 일도 하지 않는다. 422 분기는 짝 백엔드에서 거의 타지 않는다. 개발자는 문제 스키마·`mapProblem`·MSW 본문을 직접 바꾼다. 저장 실패의 판정(적용 안 됨/결과 불명)을 잘못 이해하기 쉽다 |
| 심각도·우선순위 | Medium · P2 — 실행기 표가 판정을 지키므로 중복 쓰기 위험은 낮다. 쓰기 기능마다 이해·작성 비용이 든다 |
| 통제·증거 | 목표 M2(짝 백엔드 wire의 쓰기 예제가 테스트에서 실행됨) / 확인 M1(매뉴얼이 차이를 적음) · E1 |
| 확실성과 남은 가정 | 정적으로 확인했다. 실제로 쓰기 기능을 옮겨 보지 않았다 |
| 결정의 근거 | 기록된 의도: 참조 기능은 "예제일 뿐, 모양을 보고 생성 뼈대에 옮긴다"(`patterns.md:9`). 14.6은 값이 없는 descriptor를 그대로 두어 참조 기능·테스트 계약·recipe를 건드리지 않으려 했다. 리뷰어 추론: 그 선택은 Envelope 도입의 파급을 줄였다. 대신 가장 많이 복제되는 쓰기 예제가 짝 백엔드와 다른 wire에 남았다(5.3절) |
| 이해 비용 | 쓰기 기능 작성자는 참조 기능, 실행기 표(`backend-envelope.ts`), 매뉴얼 02 4절을 함께 읽어야 어떤 분기가 실제로 쓰이는지 안다 |
| 최소 개선 방향 | (1) `create:feature`에 쓰기 slice 선택(예: `--with-create`)을 더해 Envelope KEYED POST·폼·결과 불명 화면을 생성한다. 또는 (2) 참조 기능을 Envelope로 옮긴다 |
| 대안 비교 | (A) 현 상태 + 매뉴얼. (B) 생성 명령 확장: 참조 기능·테스트 계약 그대로, 템플릿 문자열이 는다. (C) 참조 기능 이행: 참조 테스트와 MSW fixture를 바꾸고 예제가 하나로 모인다 |
| 단순화의 보존 조건 | 처리 중 409는 같은 키로 결과 불명(0929/03-01), 결과 불명 화면, 504 재전송 테스트는 유지한다 |
| 비용·부작용 | (B) 수백 줄 템플릿 문자열과 생성 테스트. (C) 참조 기능 테스트 다수 수정 |
| 재검토 조건 | 짝 백엔드가 problem details 모드를 제공하면(14.6 (나)) 다시 본다 |
| 완료 기준 | 짝 백엔드 wire의 KEYED 생성·400 필드 오류·409 `IDEMPOTENT_IN_FLIGHT`를 실행하는 기능 예제가 `tests/features`에서 돈다 |
| 검증 방법 | 그 기능의 테스트, `tests/unit/create-feature.test.ts` |
| 담당·기한·상태 | 미정 · 미정 · 이월된 결정(14.6) |
| 재검증 결과 | 해당 없음(신규) |
### 09-07 제품 인증 프로필 id를 잘못 적으면 게이트가 원인 없는 메시지만 보이고, 문서는 사라진 메시지를 약속한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 20, 4, 9, 24 |
| 근거 | V2 보안 프로필 해석기는 `12f3bb7`에서 지워졌다. 지금은 V3 계약 조립이 `ContractContributionError`를 던진다. 세부는 `reason` 필드에만 있고 message는 "Installed contract contribution is not composable"이다(`src/contracts/external-contract-runtime.ts:266-276`, `:386-389`). `check:registries`는 message 첫 줄만 적는다(`scripts/check-registries.ts:372-375`). **E-AUTHID**: 생성 기능의 `authProfileId`를 `NOTICE_UNKNOWN`으로 바꾸면 출력이 "missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable" 두 줄이다. operation id와 프로필 id가 없다. `tsc`는 통과한다. 매뉴얼 `docs/manual/02-decision-tables.md:199-204`와 `docs/architecture/starter-experience.md:190`은 "REST security profiles are incoherent for <operationId>: unknown authProfileId …"를 약속한다. 그 문자열은 src·scripts에 없다(git grep 0건). 두 번째 약속(`auth "external-session" cannot use the ANONYMOUS profile`)은 V3 descriptor에 `auth` 칸이 없어 생길 수 없다 |
| 발생 조건 | 제품 프로필 이름 오타, 또는 제품 프로필을 `product-contracts.ts`에 넣지 않음 |
| 영향 | 매뉴얼의 문구가 나오지 않아 개발자가 원인을 직접 추적한다. "missing registry source"는 파일 문제처럼 보인다 |
| 심각도·우선순위 | Low · P2 — 개발 단계에서만 드러나고 데이터 피해는 없다. 확장 지점의 주 경로에서 진단이 후퇴했고 수정이 작다 |
| 통제·증거 | 목표 M3(게이트 출력에 operation·프로필 id) / 확인 M0 · E2(E-AUTHID) |
| 확실성과 남은 가정 | `check:registries`와 `second-api-feature-registries.test.ts` 출력을 봤다. 브라우저에서 기능 적재가 실패할 때의 화면·진단은 보지 않았다 |
| 결정의 근거 | 적용 제외 — 진단 문구 누락과 문서 불일치다 |
| 이해 비용 | 원인을 찾으려면 계약 조립기 소스를 읽어야 한다 |
| 최소 개선 방향 | `ContractContributionError`의 message에 `reason`을 넣거나, `check-registries.ts`가 `reason`을 적는다. 문서 두 곳의 문구를 실제 출력으로 바꾼다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 같은 변이에서 게이트 출력에 `NOTICE_LIST_ITEMS`와 `NOTICE_UNKNOWN`이 나온다. 매뉴얼 문구가 그 출력과 같다 |
| 검증 방법 | E-AUTHID를 `second-api-feature-registries.test.ts`류 테스트로 옮긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-08 기능이 선언한 capability만 받는다는 설명은 여전히 타입에서만 지켜지고, 이제 생성 뼈대마다 그 주석이 복제된다 (이월: 1101/09-08)
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안(주석과 실행이 다름) |
| 관련 관점 | 22, 5, 2 |
| 근거 | 조립 루트 주석 "Each installed contribution receives only the capabilities it declares"(`src/bootstrap/runtime-adapters.ts:618`). 실제로는 context 전체를 넘긴다(`src/features/feature-adapter-contribution.ts:229-237`, `:285-291`). **E6**: `needs: ["telemetry"]` 기여가 `["telemetry","http"]`를 받았다. 생성 뼈대가 "The feature receives only the capabilities it names in `needs`."를 모든 기능에 쓴다(`scripts/create-feature.ts:834`). 제품 capability도 모든 기능에 간다(`runtime-adapters.ts:625-629`) |
| 발생 조건 | 기능 코드가 cast로 선언하지 않은 capability를 쓴다 |
| 영향 | 지금은 동작한다. 그 capability를 주던 쪽이 빠지면 그때 깨진다. `needs`가 실제 의존을 다 말하지 않게 된다 |
| 심각도·우선순위 | Low · P3 — cast가 필요해 실수로 일어나기 어렵다 |
| 통제·증거 | 타입 경계 M4 / 실행 경계 M0 · E2(E6) |
| 확실성과 남은 가정 | repo 안에 cast하는 기능은 없다 |
| 결정의 근거 | 적용 제외 — 주석과 실행의 작은 차이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | `invokeContribution`이 `needs`의 키만 골라 새 frozen 객체로 넘긴다. 또는 두 주석을 "타입이 선언한 capability만 보인다"로 고친다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 누락 capability 오류 메시지(`:276-283`), 중복 기여·featureId 불일치 오류, 호출부 타입 추론은 그대로 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E6이 `["telemetry"]`만 기록한다 |
| 검증 방법 | E6을 `tests/contract/reusable-capability/feature-adapter-composition.test.ts`에 더한다 |
| 담당·기한·상태 | 미정 · 미정 · 이월(2회째) |
| 재검증 결과 | 2026-11-03 E6 재실행: 같은 결과 |
### 09-09 `NOT_INSTALLED` 표시가 여러 뜻이고, 표시와 `feature-module.ts`가 함께 있어도 조용히 설치된다 (이월: 1101/09-04)
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(이름과 졸업 경로) |
| 관련 관점 | 24, 21, 27, 4 (30.7) |
| 근거 | 생성기는 `feature-module.ts`를 못 읽을 때만 표시 파일을 찾는다(`scripts/generate-product-feature-index.ts:292-305`). 둘 다 있으면 표시는 무시된다. 같은 단어가 런타임 상태 "선언됐지만 선택 안 됨"으로도 쓰인다(`src/contracts/product-features.ts:32`, `:106-122`). 표시 파일은 "아키텍처 샘플"이라고 적는다(`src/features/local-draft-feature/NOT_INSTALLED`) |
| 발생 조건 | 샘플을 졸업시키며 `feature-module.ts`를 더하고 표시를 지우지 않는다 |
| 영향 | 표시를 보고 "설치 안 됨"이라 믿은 사람이 틀린다. 영향은 작다 |
| 심각도·우선순위 | Low · P3 — 지난 판정 유지 |
| 통제·증거 | 이름 구분 M0 · E1 |
| 확실성과 남은 가정 | 코드로 확인했다. 실행 실험은 하지 않았다 |
| 결정의 근거 | 지난 문서 4.1절 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 샘플 표시 이름을 뜻대로 나눈다(예: `NOT_A_FEATURE`). 표시와 `feature-module.ts`가 함께 있으면 생성기가 실패한다 |
| 대안 비교 | 지난 문서 09-04와 같다 |
| 단순화의 보존 조건 | 표시 없는 디렉터리는 계속 실패한다 |
| 비용·부작용 | 생성기 몇 줄, 파일 이름 변경 |
| 재검토 조건 | local-draft가 기능으로 졸업하거나 지워지면 닫는다 |
| 완료 기준 | 동시 존재 픽스처로 생성 단계가 실패한다 |
| 검증 방법 | `tests/scripts/generate-product-feature-index.test.ts`에 픽스처 추가 |
| 담당·기한·상태 | 미정 · 미정 · 이월(3회째) |
| 재검증 결과 | 코드 그대로(정적) |
### 09-10 V2 삭제 뒤 기능 실행부의 모양 설명이 네 곳에 남았다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설명이 코드와 다름) |
| 관련 관점 | 9, 4, 24, 20 |
| 근거 | 지금 `FeatureRuntime`은 `featureId`, `schemas`, `adapters`, `contractContributions`다(`src/features/feature-module.ts:51-65`). 그런데 같은 파일 머리 주석은 실행부를 "API contracts with their runtime schemas and mappers"라고 한다(`:12-13`). `installed-feature-contracts.ts:12`는 "The V2 API registries … live in `loaded-feature-runtimes.ts`"라고 한다. `docs/architecture/frontend-application-foundation.md:121`은 "composes the V2 API registries"라고 한다. `docs/architecture/starter-experience.md:136-137`은 기능 추가 2단계에서 "the API contract (operations, schema metadata, runtime schemas, mappers)"를 만들라고 한다. `verify:documentation`은 통과했다(게이트 인용). 이 내용은 검사하지 않는다 |
| 발생 조건 | 기능 작성자가 머리 주석이나 2단계를 읽고 따른다 |
| 영향 | 없는 칸(mappers, runtime schemas, V2 registry)을 찾는다. 생성 명령을 쓰면 실제 모양을 보게 되므로 영향은 작다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M1 / 확인 M0(해당 문장) · E1 |
| 확실성과 남은 가정 | 정적으로 확인했다 |
| 결정의 근거 | 적용 제외 — `12f3bb7`이 "starter-experience의 V2 설명을 지웠다"고 적었지만 일부가 남았다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 네 문장을 지금 모양으로 고친다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문장 4개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | src·docs/architecture에서 "V2 API registr", "runtime schemas, mappers"가 0건 |
| 검증 방법 | git grep |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 09-11 세션 복구 버튼이 `recover()` 결과를 버리고, owner의 상태 전이 계약이 적혀 있지 않다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 28, 22, 5 (32 세션 만료) |
| 근거 | `useSessionAction`이 `await recover()`의 결과를 버린다(`src/presentation/providers/session-provider.tsx:80`). 라우트 문은 owner 상태가 `recovery-pending`인 동안 "세션 복구" 화면과 같은 버튼을 계속 보인다(`src/presentation/routes/navigation-policy.ts:20-22`, `app-router.tsx:275-297`). `SessionGateway.recover` 주석은 반환값 뒤의 상태 전이를 정하지 않는다(`src/application/ports/auth-session-port.ts:23-33`). 템플릿 안에서 `recovery-pending`으로 가는 경로는 외부 owner뿐이다(demo의 `onUnauthenticated`는 `unauthenticated`로 간다, `external-session-adapter.ts:145-152`). `"no-session"` 결과의 화면 테스트는 없다 |
| 발생 조건 | owner가 `recoverSession`에서 `"no-session"`을 돌려주고 상태를 `recovery-pending`으로 둔다 |
| 영향 | 사용자가 "세션 복구"를 눌러도 화면이 그대로이고 로그인으로 가는 버튼이 없다 |
| 심각도·우선순위 | Low · P3 — owner 구현에 달렸다. 픽스처 스케치 owner는 상태를 바꾼다 |
| 통제·증거 | 목표 M2(어댑터가 전이를 강제) / 확인 M0 · E1 |
| 확실성과 남은 가정 | 정적으로 확인했다. 화면을 렌더하지 않았다 |
| 결정의 근거 | 적용 제외 — 계약 문장 하나와 작은 처리 누락이다 |
| 이해 비용 | owner 작성자가 화면 동작까지 읽어야 전이 규칙을 추론한다 |
| 최소 개선 방향 | `"no-session"`이면 화면이 sign-in 단계로 넘어가게 하거나, 계약에 "`no-session`을 돌려주기 전에 상태를 `unauthenticated`로 바꾼다"를 적고 어댑터가 검사한다. 09-03의 recipe와 함께 한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄 + 테스트 1개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `recovery-pending`에서 `"no-session"` 뒤 화면에 로그인 버튼이 보인다 |
| 검증 방법 | 컴포넌트 테스트 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | 조립 불변식 M3 / M3 | E2(R1, M2·M3) | P — 라우트 루트·핸들·중복·needs·예산은 throw한다. 401 판정이 자격증명 출처를 보지 않는다(09-01) |
| 2 | 구조적 성숙도 | 적용 | 공개 경계 M3 / M3 | E2(R1, `check:architecture`) | P — 제품 소유 파일 두 개 + 판단 순서는 템플릿. 예제 화면·선택 런타임은 템플릿 파일에 붙어 있다(09-04, 09-05) |
| 3 | 변경 용이성 | 적용 | 제품 변경 = 제품 파일만 M2 / M1 | E3(E-PROD) | P — 지난 X에서 올림. 기능 추가는 템플릿 diff 0. 제품 키·capability는 타입 검사에서 막히고(09-02), SW·예제 제거는 템플릿 수정(09-04, 09-05) |
| 4 | 인지 부하 | 적용 | 확장 위치 한 표 M1 / M1 | E1 | P — 확장 위치는 `starter-experience.md` 표와 매뉴얼 03에 있다. 보강 위치·optional 키 규칙은 숨은 전제다(09-02). 사라진 오류 문구를 가리킨다(09-07) |
| 5 | 위험 가시성 | 적용 | 판단 규칙이 호출부에서 보임 M1 / M1 | E1 | P — 401→로그아웃 규칙이 한 줄 주석이고 `ANONYMOUS` 예외가 없다(09-01). `needs` 주석이 실행과 다르다(09-08) |
| 6 | 실패 성숙도 | 적용 | 안전한 기본 M2 / M2 | E2(E-A401) | P — fail-closed는 유지된다. 401 처리 범위가 넓다(09-01). 제품 owner가 throw하면 부트 실패 화면이다 |
| 7 | 운영 성숙도 | 적용 | 경계 실패 진단 M2 / M2 | E2(R1) | P — 바깥 경계 진단 연결(1101/09-09 고쳐짐). 401발 로그아웃은 원인이 진단에 남지 않는다(09-01) |
| 8 | 디버깅 가능성 | 적용 | 조립 오류가 원인을 말함 M3 / M2 | E2(E-AUTHID), E3(E-PROD) | P — 라우트 조립 오류는 기능·라우트·context를 담는다. 프로필 오타는 원인 없는 메시지(09-07). node 타입 오류가 먼 파일을 가리킨다(09-02) |
| 9 | 유지보수 성숙도 | 적용 | 낡은 경로 정리 M1 / M1 | E1 | P — 지난 결함 대부분이 고쳐졌다(2절). V2 삭제 뒤 설명이 남았다(09-10). `src/application/result.ts` deprecated 재수출은 repo 안 소비자 0, 제거 조건 없음 |
| 10 | 테스트 성숙도 | 적용 | 핵심 판단 M3 / M3(일부) | E2(R1, M1~M3) | P — 영역 522개 통과, 변이 셋을 잡는다. `ANONYMOUS` 401, 제품 파일 타입 경로를 잡는 테스트가 없다(09-01, 09-02). 픽스처가 `vi.mock`이라 타입 경로를 안 본다 |
| 11 | 데이터 성숙도 | 적용(샘플 범위) | — / M1 | E1 | P — local-draft ABA는 주석으로만 막는다(지난 판정). 이 영역에 데이터 손상 경로는 없다 |
| 12 | 동시성 성숙도 | > 03 영역 | — | E1 | > — 이 영역은 provider 응답 뒤에도 scope를 다시 본다(`runtime-adapters.ts:501-503`). 401과 계정 전환의 경쟁은 미확인(1.2) |
| 13 | 확장성 | 적용 | 기능·제품 수 축 M3 / M2 | E2(R1) | P — 기능 1개 증가 1 KiB 상한, context 루트 충돌 검사. 제품 수 축은 확장 지점이 열렸지만 09-02·09-04·09-05가 남았다 |
| 14 | 성능 성숙도 | > 15 영역 | — | 게이트 인용 | > — 초기 JS 201,848 / 204,800 B |
| 15 | 보안 성숙도 | 적용 | fail-closed M3 / M3 | E2(R1, M1) | P — `ANONYMOUS`는 세션을 안 묻고, provider 뒤 fence를 다시 본다. 과잉 로그아웃은 가용성 문제(09-01). owner 예제가 없어 제품마다 보안 코드를 새로 쓴다(09-03) |
| 16 | 의존성 성숙도 | 적용 제외 — 이 영역 고유 의존성 없음 | — | — | - |
| 17 | API / Contract 성숙도 | 적용 | 제품 계약 검사 M3 / M3 | E3(E-PROD `check:registries` additive) | P — 제품 프로필·키·env 행이 템플릿 검사를 함께 받는다. 401의 세션 의미가 프로필을 보지 않는다(09-01). 참조 기능이 짝 백엔드 wire가 아니다(09-06) |
| 18 | 배포 성숙도 | > 13 영역 | — | E1 | > — 예제 라우트의 a11y 서명 요구는 09-04 |
| 19 | 설정 성숙도 | 적용 | 제품 키 strict 검증 M3 / M3 | E3(E-PROD) | P — 제품 키가 strict 스키마에 합쳐진다. 기본값 키가 템플릿 테스트 타입을 깬다(09-02). 제품 키에 FE-REG-ENV 행을 요구하는 검사는 없다 |
| 20 | 개발자 경험 | 적용 | 생성 → 게이트 통과 M3 / M2 | E3(E-PROD) | P — `create:feature` 결과가 게이트를 통과한다. 보강 위치(09-02), 오류 문구(09-07), owner 예제(09-03)에서 막힌다 |
| 21 | Guardrail 성숙도 | 적용 | 조립 실수 차단 M3 / M3 | E2(M2·M3) | P — 라우트 루트·핸들·플랫폼 경로·needs·예산을 막는다. 제품 파일 타입 경로와 node 검사는 게이트가 보지 않는다(09-02) |
| 22 | 추상화 성숙도 | 적용 | 계약이 짧고 정확 M2 / M2 | E1, E2(E6) | P — `ProductComposition` 계약은 짧다. capability 좁히기는 타입만(09-08). owner context가 raw fetch만 준다(09-03) |
| 23 | 일관성 | 적용 | 같은 선택은 같은 장치 M2 / M1 | E1 | P — 기능은 선택으로 빼는데 예제 화면은 못 뺀다(09-04). 제품이 고치는 선택 파일에 제품 소유 표시가 없다(09-05) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | — / M1 | E1 | P — `NOT_INSTALLED` 다의(09-09). `TEMPLATE_APP_MODULE`이 선택된 아무 앱을 가리킨다(지난 6.2 그대로) |
| 25 | 조직 확장성 | 적용 | 동기화 충돌 자리 분리 M2 / M2 | E3(E-PROD), 픽스처 | P — 지난 X에서 올림. 제품 소유 두 파일이 충돌 자리를 나눴다. 남은 충돌 자리는 템플릿 테스트(09-02), 예제 화면(09-04), 선택 파일(09-05). 다운스트림 실제 이식은 미확인 |
| 26 | Ownership 성숙도 | > 14 영역 | — | E2(픽스처) | > — "Product-owned." 표시 두 파일을 테스트가 고정한다 |
| 27 | 삭제 가능성 | 적용 | 기능·예제 제거 M3 / M2 | E1 | P — 기능 제거 드릴이 있다. lint·i18n·e2e는 건너뛴다(0925 FOLLOW-UP 남음). 예제 화면 제거 경로가 없다(09-04) |
| 28 | 회복 가능성 | 적용 | 세션·부트 회복 M2 / M2 | E1, E2(E-A401) | P — 부트 실패 화면과 reload TTL. 세션 복구는 `recover` 결과를 버린다(09-11). 401발 로그아웃이 반복될 수 있다(09-01) |
집계(판정한 23개): 충족 0 · 부분 충족 23 · 미충족 0 · 미검증 0. 적용 제외 1(16), 다른 영역 4(12, 14, 18, 26). 지난 라운드의 미충족 두 개(3, 25)는 1101/09-02·09-03 수정으로 P가 됐다.
## 5. 설계 선택 검토 (41절)
### 5.1 제품 확장 지점을 "제품 소유 파일 두 개 + 템플릿이 판단 순서를 쥔다"로 열었다 (1101/09-02 결정 (가))
1. **무엇이 필요한가.** 제품이 템플릿 파일을 고치지 않고 capability·자격증명·설정 키·FE-REG-ENV 행·세션 owner를 더한다. 템플릿 동기화 때 충돌이 없어야 한다.
2. **지킬 성질.** scope fence → `ANONYMOUS` → 제품 provider → 세션 순서. provider 응답 뒤 fence 재확인. 템플릿 capability(`http`, `telemetry`)는 제품이 바꾸지 못한다. 제품 이름이 템플릿 이름과 겹치면 실패한다. 제품 파일은 템플릿이 다시 고치지 않는다.
3. **현재 보장.** 확인한 사실: 순서는 `runtime-adapters.ts:480-531`. 템플릿 capability가 뒤에 펼쳐져 제품 값을 덮는다(`:625-629`). 이름 충돌은 로드 때 throw(`withProduct*`). `runtime-adapters-credential-order.test.ts`, 픽스처 13건, E-PROD(템플릿 diff 0, `check:architecture`·`check:registries` 통과). 보장하지 않는 것: 타입 검사 경로(09-02), 선택 런타임(09-05), 예제 화면(09-04), 401 판정과 provider의 관계(09-01).
4. **대안.** (A) 템플릿 파일 수정을 공식 경로로 문서화(14.1에서 버림). (B) 현재. (C) 제품 모듈 등록 목록(여러 제품 파일을 등록). (D) 제품이 `createRuntimeAdapters`를 감싸는 wrapper.
5. **비용 비교.** (B) 파일 두 개와 64줄 계약. 칸이 늘 때마다 계약 타입이 는다. (C) 등록 규약과 순서 규칙이 하나 더 생긴다. (D) fence 순서를 제품이 다시 구현해 보안 규칙이 갈라진다.
6. **현재 조건에서의 판단.** (B)를 유지할 근거가 있다. 판단 순서를 템플릿 한 곳이 쥐는 것이 보안 규칙을 지킨다. 빠진 칸(SW 연결, 예제 선택)을 같은 두 파일에 더하고, 실제 파일로 채운 타입 검사(09-02 (3))를 붙이면 된다.
7. **재검토 조건.** 제품 소유 칸이 다섯 개를 넘거나, 제품이 판단 순서 자체를 바꿔야 하는 요구(요청별 테넌트 전환)가 생기면 (C)를 비교한다.
### 5.2 응답 401을 세션 판정으로 본다 (R-3.2)
1. **무엇이 필요한가.** 만료된 토큰을 빨리 알아 재로그인을 안내한다. 401 뒤 숨은 재전송은 하지 않는다(§8.4).
2. **지킬 성질.** 세션이 낸 자격증명이 거절됐을 때만 세션 상태를 바꾼다. 보내기 전 거절은 판정이 아니다.
3. **현재 보장.** metadata 유무로 보내기 전·후만 나눈다(`runtime-adapters.ts:588-593`). 자격증명 출처(세션 / provider / 없음)는 보지 않는다. E-A401로 확인했다.
4. **대안.** (A) 현 상태. (B) 출처별 판정: 세션 출처일 때만 `onUnauthenticated`, provider에는 hook. (C) owner에게 401과 operation binding을 넘기고 owner가 판단. (D) 401을 세션 판정으로 쓰지 않음.
5. **비용 비교.** (A) 0, 과잉 로그아웃. (B) 수십 줄, 출처마다 책임이 맞는다. (C) owner 계약 변경, 모든 owner가 판단 로직을 쓴다. (D) 만료 감지가 다음 사용자 행동까지 늦어진다.
6. **현재 조건에서의 판단.** (B). 템플릿은 이미 `attachCredentials`에서 출처를 가른다. 같은 구분을 응답 쪽에 쓰면 된다.
7. **재검토 조건.** 한 앱에서 operation마다 다른 계정·테넌트 세션을 쓰면 판정 단위를 다시 본다.
### 5.3 참조 기능은 problem details로 두고, 생성 뼈대만 Envelope로 만들었다 (1101 README 14.6)
1. **무엇이 필요한가.** 짝 백엔드의 Envelope를 읽는 기능을 바로 만든다. 기존 참조 기능·테스트 계약·recipe를 크게 흔들지 않는다.
2. **지킬 성질.** 같은 응답에 같은 판정. 결과 불명 쓰기는 같은 키로 다시 보낸다.
3. **현재 보장.** 실행기 한 곳이 Envelope 판정 표를 쥔다(`http-execution-v3.ts:1722-1731`, `backend-envelope.ts`). 뼈대는 GET 목록만 Envelope로 만든다. 쓰기 예제는 참조 기능의 problem details 모양뿐이다(09-06).
4. **대안.** (A) 현 상태. (B) 뼈대에 쓰기 slice 추가. (C) 참조 기능 이행.
5. **비용 비교.** (A) 0, 쓰기 기능마다 번역 비용. (B) 템플릿 문자열 수백 줄, 참조 기능은 그대로. (C) 참조 테스트·MSW fixture 다수 수정, 예제가 하나로 모인다.
6. **현재 조건에서의 판단.** 도입 시점의 (A)는 파급을 줄인 타당한 선택이었다. 짝으로 빨리 출시하는 목표에서는 (B)가 비용 대비 낫다. 참조 기능은 problem details 백엔드의 예제로 남겨도 된다.
7. **재검토 조건.** 짝 백엔드가 problem details 모드를 제공하거나, 제품 대부분이 다른 백엔드를 쓰면 (A)로 돌아간다.
## 6. 실험·변이 기록
모두 격리 worktree(`agent-a9162b2ee3ef1b90f`, `e40684b`)에서 했다. 끝난 뒤 `git checkout -- . && git clean -fd`, 생성기 재실행, `git rev-parse --short HEAD` = `e40684b`를 확인했다. 커밋하지 않았다.
| ID | 무엇 | 결과 |
|---|---|---|
| R1 | `node scripts/run-vitest.ts run tests/features tests/architecture tests/platform tests/contract/reusable-capability tests/unit/{product-composition-fixture,runtime-adapters-auth-profile,runtime-adapters-credential-order,runtime-adapters,optional-runtime-host,product-features,two-feature-install-typecheck,second-api-feature-registries,feature-shape-growth,installed-feature-messages,feature-override-diagnostics,product-index-entrypoints}.test.ts tests/component/{context-layouts,context-route-gateway,context-boundary-diagnostics,router,boot-module-failure}.test.tsx tests/scripts/generate-product-feature-index.test.ts` | 77 files / 522 tests 통과, 12.74s(load 10.87) |
| E-A401 | `runtime-adapters-auth-profile.test.ts`의 mock·helper를 복사한 임시 테스트. fetcher가 401 problem을 답한다. (a) demo 로그인 후 `ANONYMOUS` operation (b) external owner(`notifyUnauthenticated` spy) + `ANONYMOUS` (c) 대조군 bearer | (a) `UNAUTHENTICATED`, fetch 1회, 자격증명 헤더 0개, `credentials: "omit"`, 세션 `unauthenticated`, 이전 scope current=false (b) `attachCredential` 0회, `notifyUnauthenticated` 1회 (c) `notifyUnauthenticated` 1회 |
| E-PROD | `corepack pnpm create:feature notice-feature`(새 context `notice-context`, `/notice`). `product-contracts.ts`: 쿠키 프로필 `NOTICE_BFF_COOKIE`, 설정 키 `NOTICE_PAGE_SIZE`(`.default(20)`), FE-REG-ENV 행. `product-composition.ts`: `FeaturePlatformCapabilities` 보강(`noticeSettings`), capability 반환, provider. 기능: `needs`에 `noticeSettings`, descriptor `authProfileId: "NOTICE_BFF_COOKIE"` | 템플릿 파일 diff 0(`git status`: 제품 소유 2파일 + 생성 파일만). `check:types:app` 통과. `check:types:node` 실패 2건(기능 파일). 보강을 기능 파일로 옮기면 node 통과. `check:types:test` 8건 실패(템플릿 테스트 7파일, `NOTICE_PAGE_SIZE` 누락). 키를 `.optional()`로 바꾸면 0건. `check:architecture` 통과. `check:registries` 11 registries PASS, `compatibility=additive`. 생성된 `notice-http-gateway.test.ts` 5건 실패: 기능 소유 harness가 bearer 헤더를 고정해 쿠키 프로필이 거절한다. 기능 쪽 테스트라 예상한 결과다 |
| E-AUTHID | E-PROD 상태에서 `authProfileId`를 `NOTICE_UNKNOWN`으로 바꾸고 `check:registries`, `second-api-feature-registries.test.ts`, `check:types:app` | 출력은 "missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable" 두 줄. operation·프로필 id 없음. tsc 0건 |
| E6 | `needs: ["telemetry"]` 기여를 `composeFeatureAdapterInputs`로 실행하고 `createInput`이 받은 키 기록 | `["telemetry","http"]` |
| M1 | `runtime-adapters.ts:490`의 `"ANONYMOUS"`를 `"ANONYMOUS_MUTATED"`로 바꾸고 `runtime-adapters-auth-profile`·`credential-order` 테스트 | 2 files 실패, 6 tests 실패 / 13 통과. 되돌림 |
| M2 | `deployable-app-module.ts:38`의 `assertFeatureRoutesReachOwningContext` 호출을 주석 처리하고 `tests/architecture`, `router`, `context-layouts` | 1 file 실패, 11 tests 실패 / 51 통과. 되돌림 |
| M3 | `bounded-context-module.ts:97`의 핸들 검사를 `continue`로 바꾸고 `context-route-roots`, `context-boundary-diagnostics` | 2 files 실패, 3 tests 실패 / 24 통과. 되돌림 |
| S1 | 정적 검사: `git grep`으로 `responseEnvelope`(src/features 0건), OIDC·Keycloak·PKCE(0건), "security profiles are incoherent"(src·scripts 0건), 예제 라우트 ID 참조 파일(19개) | 3절 근거에 사용 |
@@ -0,0 +1,311 @@
# 10 테스트 — 빠른 계층 성숙도 리뷰 (2026-11-03)
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b`(`claude/happy-easley-233d07`와 `fix/ui-design-audit-2026-11-01`을 합친 커밋)
> 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `tests/unit`, `tests/component`, `tests/integration`, `tests/contract`, `tests/runtime-schema`, `tests/features`, `tests/platform`, `tests/recipes`, `tests/helpers`, `tests/mocks`, `tests/support`
> 깊게 본 관점: 10 테스트, 12 동시성, 20 개발자 경험, 21 Guardrail
> 렌즈: (1) V2 클라이언트·V2 API 행 삭제(`048f490`, `12f3bb7`)로 지워진 테스트가 지키던 동작 가운데 V3에 남은 것을 지금 누가 지키는가. (2) 새 테스트 3종(`tests/integration/http-execution-v3-envelope.test.ts`, `tests/unit/api-operation-rows.test.ts`, `tests/unit/rest-profile-contract.test.ts`)이 결함을 실제로 잡는가. (3) 시간·부하에 기대는 테스트.
> 영역 판정(35.8): **조건부 사용 가능**. 빠른 계층은 V3 HTTP 경로의 핵심 규칙 대부분을 지킨다(V3·계약 변이 40종 중 28종을 빠른 계층이, 1종을 `check:registries`가 잡음. 동등 변이 2종 제외). 조건: 짝 백엔드에 붙여 출시하기 전에 10-02(Envelope 판정 경계)를 테스트로 고정한다. CI 러너 사양을 정할 때(U-1) 10-01(부하에서 떨어지는 자식 프로세스 테스트)을 함께 고친다.
## 0. 결론
- **V2 삭제로 지워진 테스트의 빈자리는 대부분 다른 테스트가 메운다.** `048f490`·`12f3bb7`은 `tests` 아래 테스트 파일 9개와 도우미 1개를 지웠다(`git diff --stat 048f490^ 12f3bb7 -- tests`: 2,911줄 삭제, 415줄 추가). 지운 테스트마다 V3에 같은 규칙이 남았는지 보고 변이를 넣었다. 28종 중 22종을 빠른 계층이, 1종을 `check:registries`가 잡았다. 재시도 상한·지터·Retry-After 상한, KEYED 재전송 금지, 자격증명 헤더 검사, 경로 `.`·`..` 거절, 매퍼 예외 처리, 401 세션 통지, 필드 오류의 백엔드 문구 제거가 여기에 든다(6절 M 표).
- **빠진 보호는 다섯 곳이다(10-04, 10-02, 10-03).** 운영 설정 `MAX_RETRY_ATTEMPTS`가 실행기에 닿는지, 호출자 signal의 listener를 지우는지는 이제 아무 테스트도 보지 않는다. scope signal listener는 nightly tier의 테스트 하나만 본다. 게이트웨이 408·425 판정과 PUT·PATCH·DELETE의 CSRF 요구도 지운 테스트가 보던 자리다.
- **새로 만든 규칙에도 빈 곳이 있다(10-02, 10-03).** 머지 게이트를 통과한 변이 11종 중 7종이 이번 라운드에 만든 `src/adapters/http/backend-envelope.ts`(Envelope 판정 표)와 쿠키 CSRF 조립 검사(`365d8c3`)에 있다. 새 테스트는 "표의 code를 제 status로 보낸 경우"와 "POST"만 본다. code만 맞고 status가 다른 응답, 표 밖 422, PUT·PATCH·DELETE는 아무도 보지 않는다. `backend-envelope.ts`는 커버리지가 100%다. 그래서 커버리지 하한으로는 이 빈 곳을 찾지 못한다.
- **부하에서 떨어지는 테스트를 재현했다(10-01).** `tests/unit/task3-selective-integration.test.ts:151-173`은 자식 Node의 기동 시간까지 1,000ms 안에 넣는다. 한 코어에 바쁜 이웃 6개를 두면 5회 모두 "provider scope EOF close timed out"으로 실패했다. 이웃 4개에서는 통과했지만 테스트 시간이 659~977ms로 한도에 붙었다. 2코어 4 worker(커버리지 포함)에서는 여유 있게 통과했다. 지난 라운드에 guardian 테스트를 같은 원인으로 고친 방식(`c862004`, 준비 신호)이 이 파일에는 적용되지 않았다. 이 파일은 한 번의 머지에서 최대 5번 돈다.
- **지난 라운드 발견 8건 중 3건을 고쳤다.** 이벤트 계약 테스트(1101/10-01), Popover 포커스(1101/10-02), skip·todo·only 차단(1101/10-04)은 변이와 재실험으로 고쳐진 것을 확인했다. 세션 복구 분기(1101/10-03)는 변이가 그대로 살아남았다. 실행 비용 4건(1101/10-05~08)은 그대로다.
- **§10.8 마지막 검사(0929/10-04)는 세 라운드째 아무 테스트도 고정하지 않는다.** 이번에도 변이 L01이 94파일 813개를 통과했다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 테스트 파일 수: unit 176, component 39, integration 10, contract 3, runtime-schema 3, features 21, platform 29, recipes 3. 지원 코드: helpers 9, mocks 6, support 1. 설정: `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts`, `scripts/lib/no-skipped-tests-reporter.ts` |
| 커밋·작업 상태·확인 시점 | `e40684b`(2026-11-03 22:49 커밋). 격리 worktree `agent-a1906b089fc371330`에서 `git checkout --detach e40684b`, `corepack pnpm install --frozen-lockfile`. 확인 2026-11-03 22:59~23:58. 실험이 끝난 뒤 `git status`가 깨끗한 것을 확인했다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.10, Node 24.14.0, jsdom 29.1.1, MSW 2.15.0 |
| 필수 요구와 규모·운영 목표 | 빠른 계층은 머지 게이트다: FE-GATE-004(runtime-schema), 005(unit·contract·coverage·scale pr), 006(component), 007(integration·features·recipes), 020(샘플 제거·기능 생성 드릴 안에서 다시). 러너 사양과 허용 실패율은 정해져 있지 않다(U-1, CI 꺼짐) |
| 읽은 코드·구성 범위 | 위 설정 전체. 지운 테스트 10개 파일(`048f490^`, `12f3bb7^`에서 꺼내 읽음)과 그 V3 대응 코드: `src/adapters/http/http-execution-v3.ts`, `http-contract-bridge.ts`, `http-retry-lifecycle.ts`, `backend-envelope.ts`, `feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts:184-272`·`:468-595`, `src/contracts/external-contract-runtime.ts:440-565`, `api-operations.ts`, `realtime-streams.ts:460-475`. 새 테스트 3종 전체. `config/testing/risk-coverage.json`, `config/ci/gates.json`의 FE-GATE-005·020, `scripts/test-feature-scaffold.ts`, `docs/testing/taxonomy.md`. 지난 발견의 근거 파일 |
| 읽은 문서(주장으로만) | `docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md`, 같은 폴더 README 13~14절, 두 삭제 커밋과 `365d8c3`·`c05f41a`·`c862004`의 본문 |
| 수행한 테스트·실험 | 변이 46종(6절 M 표, `node scripts/run-vitest.ts related <파일> --run`). skip·todo·only 재실험(P-B). 자식 프로세스 기동 시간 측정과 부하 재현(F1~F7). 커버리지 측정(C1). H20 상태의 `check:registries`(R1). 오케스트레이터 junit에서 테스트별 시간 추출 |
| 확인하지 못한 범위·이유 | 실제 Gitea 러너의 코어 수와 실패율(CI 꺼짐). `test:coverage`의 모듈별 수치(게이트 요약에 없고 다시 돌리지 않았다). 조용한 호스트에서의 측정(실험 중 호스트 부하 8~90, 다른 리뷰어와 공유). 브라우저 계층(11 영역) |
| 이전 리뷰와 비교 가능한 범위 | 지난 결과는 증거로 쓰지 않았다. 지난 변이 M01·M10·M15·M17·M18은 같은 자리에 다시 넣었다(L01~L04). 실행 비용 수치는 이번 게이트 junit으로 다시 셌다 |
### 1.1 게이트 결과 (오케스트레이터, `e40684b`, 인용)
`check:architecture`, `check:types`, `lint`, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `check:registries`, `check:i18n`, `check:design-system`, `check:diagnostics` 통과. `test:unit` 2,580, `test:component` 263, `test:integration` 117, `test:contract` 23, `test:runtime-schema` 56개 모두 통과. 이 영역에서는 다시 돌리지 않았다. 오케스트레이터 junit(`artifacts/tests/*.xml`, 22:50)에서 빠른 계층 3,039개의 테스트 시간 합은 220.2s다(unit 154.4s, component 44.2s, integration 21.4s).
## 2. 지난 발견 재판정
| 지난 ID | 판정 | 근거 |
|---|---|---|
| 1101/10-01 이벤트 계약 테스트가 첫 줄에서 return | **고쳐짐** | `dddf635`. `tests/unit/contract-registry-immutability.test.ts:328-415`가 정상 이벤트 1개와 hostile 9종을 실제로 넣는다. 변이 L04(`external-contract-runtime.ts:901`의 `assertEventContract` 호출 제거)를 6개 테스트가 잡았다 |
| 1101/10-02 Popover Escape 포커스 단언이 전제를 만들지 않음 | **고쳐짐** | `ba98048`. `tests/component/design-system-platform.test.tsx:323-326`이 Tab으로 포커스를 내용으로 옮기고 그것을 단언한다. 변이 L03(`popover.tsx:30` 포커스 반환 제거)이 잡혔다 |
| 1101/10-03 보호 라우트의 세션 복구 분기 미고정 | **남음** | 변이 L02(`navigation-policy.ts:21` `wait-for-session`→`show-sign-in`)가 18파일 105개를 통과했다. `tests/`에 `wait-for-session` 문자열이 없다. `route-status-surfaces.test.tsx:77`은 로그인 분기만 본다 |
| 1101/10-04 skip·todo가 게이트를 통과 | **고쳐짐** | `95e7d11`. `vitest.config.ts:31` `allowOnly: false`, `scripts/run-vitest.ts:66-71`이 모든 실행에 `no-skipped-tests-reporter`를 붙인다. P-B 재실험: skip+todo, `.only`(CI 없이), `context.skip()`, `skipIf(true)` 파일 모두 종료 코드 1. 남은 범위: `run-vitest.ts`를 거치지 않는 직접 `vitest` 실행(IDE)에는 reporter가 없다. 게이트는 모두 `run-vitest.ts`를 쓴다(`package.json`에 직접 호출 없음) |
| 1101/10-05 `tests/unit`에 도구 테스트가 섞여 시간 대부분을 씀 | **남음 — 조금 커짐** | 176파일 중 `scripts/`만 import하는 파일 44개가 unit 합산 시간의 51%(78.4s / 154.4s)를 쓴다. 아무것도 import하지 않고 스크립트를 자식으로 띄우는 파일 11개가 15%(23.0s)를 더 쓴다. 지난 라운드는 39파일 58%였다. `tests/scripts`는 여전히 2파일이고 `test:coverage`에서만 돈다 |
| 1101/10-06 머지 단계가 빠른 계층을 두 번 돌림 | **남음 — 범위 넓어짐** | `config/ci/gates.json:1837-1843` FE-GATE-005가 `test-unit`, `test-contract`, `test-coverage`를 한 job에서 돈다. 여기에 FE-GATE-020의 `test:feature-scaffold`가 생성한 복사본에서 `test:unit`과 `test:coverage`를 다시 돌고(`scripts/test-feature-scaffold.ts:54`, `:58`), 같은 파일 `:405`가 샘플을 지운 뒤 `test:coverage`를 또 돈다. `tests/unit` 한 파일이 한 머지에서 최대 5번 돈다(10-01의 실패 기회와 직결) |
| 1101/10-07 프로덕션 시간 상수를 실제 시계로 기다림 | **남음** | junit: `service-worker-runtime.test.ts:1907` 5.01s(`service-worker-lifecycle.ts:558` 5,000ms), `browser-rpc-remediation.test.ts` 4개 1.06~1.07s |
| 1101/10-08 `scopeSnapshot` 갈라진 복사본 | **남음** | 공유 도우미(`tests/helpers/traffic-test-kit.ts:13`) 외에 5개 파일이 각자 정의한다. `identities: Object.freeze({}) as never`가 9곳이다. `deferred()` 7벌 그대로 |
| 0929/10-01 실행 속도에 기대는 테스트 | **고쳐짐 — 같은 원인 1곳 남음** | `c03bf02`(전역 `asyncUtilTimeout` 5s, `tests/setup.ts:13`), `5826300`(극한 규모 테스트 비율 비교), `c862004`(guardian 준비 신호). 같은 원인(자식 기동 시간이 짧은 실제 시계 한도 안에 듦)이 `task3-selective-integration.test.ts:169`에 남아 이번에 재현했다 → 새 10-01 |
| 0929/10-02 플랫폼 테스트가 스타터 화면을 대상으로 씀 | **고쳐짐** | `ca74caa`, `498ae87`. `chunk-recovery-boundary.test.tsx:16-26`은 `fixture-feature`를 설치한다. 스타터 검사는 `starter-*` 파일로 모였다 |
| 0929/10-03 실행기가 마감을 두 번 읽음(= 0929/03-05) | **고쳐짐** | `4da0466`. `http-execution-v3.ts:1002`가 최종 검사의 `DEADLINE_EXPIRED`를 TIMEOUT으로 끝낸다. `http-execution-v3-observability.test.ts:349`가 고정한다. 변이 H55 결과는 6절 |
| 0929/10-04 §10.8 마지막 검사 미고정 | **남음** | 변이 L01(`http-execution-v3.ts:1475-1476` 조건을 `false`로)이 94파일 813개를 통과했다. 세 라운드째다 |
| 0929/10-05 `test:all`이 CI 빠른 테스트 일부를 빠뜨림 | **남음** | `package.json:83`은 `test:reference-feature`만 돈다. `tests/features` 나머지와 `tests/scripts`가 없다 |
| (지난 2절) `boot-unexpected-failure.test.tsx`의 `vi.stubGlobal` 미복원 | **남음 — 영향은 그 파일 안** | `:25`. 설정에 `unstubGlobals` 없음 |
| (지난 2절) `test:platform`만 `--no-file-parallelism`, 이유 없음 | **남음** | `package.json:139` |
| (지난 2절) `test:runtime-schema`의 `--passWithNoTests` | **남음** | `package.json:48` |
| (FOLLOW-UP 07-03) V2/V3 일치 테스트가 V2 행 0개면 통과 | **바뀜 — 대상 없어짐** | `12f3bb7`이 V2 행과 일치 테스트를 함께 지웠다. FE-REG-API 행은 이제 descriptor에서 뽑는다(`api-operations.ts:35-56`) |
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | **남음** | `tests/setup.ts:1-3`. 게이트 로그(`test:unit.log`)의 Duration 줄에서 unit의 setup 누적 시간은 69.38s다 |
| (지난 R6) `typescript-tooling-smoke` 두 파일 | **남음** | `tests/unit/typescript-tooling-smoke.test.ts`, `tests/component/typescript-tooling-smoke.test.tsx` |
| (지난 2절 21) `tsc-diagnostics-parser.test.ts` 제외 사유 | **남음 — 12 영역** | `config/ci/ungated-tests.json` 마지막 항목 그대로 |
## 3. 이번 발견 (36.3)
### 10-01 자식 프로세스 EOF 테스트가 자식 Node의 기동 시간까지 1초 안에 넣는다 — 부하에서 머지 게이트가 코드와 무관하게 떨어진다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(부하 의존 실패) |
| 관련 관점 | 10, 12, 20, 21, 8, 23 |
| 근거 | `tests/unit/task3-selective-integration.test.ts:151-173`. 테스트는 `scripts/lib/provider-scope-wrapper.ts`를 새 Node로 띄우고(`:157-163`), 준비 신호 없이 75ms를 잔 뒤(`:165`) stdin을 닫고, 자식이 끝나기를 1,000ms 동안 기다린다(`:169`, `within(completion, 1_000, …)`). 75ms 안에 자식이 기동을 끝내지 못하면 Node 기동과 TS 모듈 3개 import가 그 1,000ms 안에 들어간다. `:166`의 `expect(child.exitCode).toBeNull()`도 자식이 아직 시작하지 않았으면 그냥 참이다. 같은 구조를 guardian 테스트는 `c862004`에서 준비 신호(fd 7에 1바이트)로 고쳤다. 이 파일은 그때 범위에 들어가지 않았다. `docs/testing/taxonomy.md:91-94`는 오래 사는 자식 프로세스 프로토콜 테스트를 `tests/integration`에 두고 그 시간 제한을 "test watchdog"으로 본다. 이 테스트는 `tests/unit`에 있고 watchdog이 1초다. 실험 F1~F7(6절): 한 코어에 바쁜 이웃 6개면(F5) 5회 중 5회 "provider scope EOF close timed out"(1,235~1,272ms). 이웃 4개면 5회 통과했지만 테스트 시간이 659~977ms였다(F4). 2코어 4 worker에서는 393ms(F6)였고 커버리지를 켜도 300ms 아래였다(F7). 1101 README 14.6은 `f3b87b3`의 `test:feature-scaffold`에서 호스트 load 약 20일 때 같은 실패를 적었다 |
| 발생 조건 | 러너 코어가 적거나 job이 겹쳐 자식 Node 기동이 늦을 때. `tests/unit`은 한 머지에서 최대 5번 돈다: FE-GATE-005의 `test:unit`·`test:coverage`(V8 계측, `--maxWorkers=4`), FE-GATE-020의 `test:feature-scaffold` 안 `test:unit`·`test:coverage`(`scripts/test-feature-scaffold.ts:54`, `:58`), 샘플 제거 뒤 `test:coverage`(`:405`). 그중 커버리지 실행이 가장 무겁다 |
| 영향 | 코드와 무관한 머지 실패. 다시 돌리면 통과하므로 사람이 "다시 돌리기"를 습관으로 삼게 된다. 그러면 진짜 실패도 다시 돌리기로 넘긴다. 템플릿을 복사한 다운스트림도 같은 테스트를 가진다 |
| 심각도·우선순위 | Medium · P2 — 같은 원인을 0929/10-01에서 Medium으로 고쳤다. 실제 게이트 실행에서 한 번 떨어졌다. 다만 2코어 4 worker(F6, 커버리지 포함 F7)에서는 여유 있게 통과해, 러너가 job을 겹쳐 돌릴 때만 문제가 된다. 러너 사양을 정할 때(U-1) 함께 고친다. 수정 비용은 몇 줄이다 |
| 확실성과 남은 가정 | 실패와 원인은 실험으로 확인했다(E3, 공유 호스트). 실제 러너의 실패율은 모른다. 이웃 6개(코어 1/7)는 job 하나만 도는 2코어 러너보다 나쁜 조건이다. 14.6의 실제 실패는 22코어 호스트 load 약 20, `test:feature-scaffold`가 머지 게이트를 겹쳐 돌릴 때 났다 |
| 결정의 근거 | [확인한 사실] guardian 파일은 같은 문제를 준비 신호로 풀었고 그 커밋 본문이 "lease 늘리기는 같은 문제가 더 드물게 남는다"고 버린 이유를 적었다. [추론] 이 테스트의 1초는 "EOF를 받으면 명령 프레임을 기다리지 않고 바로 끝난다"를 보려는 것이다. 그 성질은 한도가 5초여도 똑같이 검사된다. 자식이 EOF를 무시하면 끝나지 않기 때문이다 |
| 이해 비용 | 실패 문구는 "EOF close timed out"이라 래퍼가 EOF를 놓친 것처럼 읽힌다. 실제 원인(자식 기동이 느림)을 알려면 테스트의 시간 계산을 따라가야 한다 |
| 최소 개선 방향 | ⓐ 준비 신호: stdin을 닫기 전에 래퍼가 liveness 채널을 연 것을 확인한다. 래퍼에는 이미 `PROVIDER_PROCESS_TRACE_PATH`로 켜는 자기 기록(`traceOwnProviderProcess("scope-wrapper")`, 래퍼 `:10`)이 있어 운영 코드를 바꾸지 않고 기동 완료 근처를 알 수 있다. guardian처럼 import 래퍼를 둘 수도 있다. ⓑ 한도를 같은 파일 계열의 watchdog(5,000ms, `provider-guardian-transaction.test.ts:34`)으로 올린다. ⓒ 파일을 taxonomy대로 `tests/integration`으로 옮긴다 |
| 대안 비교 | ⓑ만 하면 한 줄이고 실패 확률이 크게 준다. 기동 시간은 여전히 한도 안에 든다. ⓐ는 기동 시간을 한도 밖으로 뺀다. 테스트가 수십 줄 늘어난다. guardian과 같은 방식이라 읽는 사람이 새 규칙을 배우지 않는다. ⓒ는 위치 규칙을 맞추지만 실패를 줄이지 않는다. [추론] ⓐ+ⓑ를 같이 한다. ⓒ는 1101/10-05(도구 테스트 위치)와 함께 정한다 |
| 단순화의 보존 조건 | "EOF 뒤 명령 프레임 없이 끝난다(종료 코드 125)", "고정한 raw 파일만 지운다", "디렉터리가 빈다"는 단언을 그대로 둔다 |
| 비용·부작용 | 테스트 수십 줄. 자식이 정말 멈추는 회귀는 실패까지 5초 걸린다 |
| 재검토 조건 | 러너 사양이 정해지고 20회 실행에서 실패가 0이면 ⓑ만으로 충분하다 |
| 완료 기준 | F5(한 코어, 이웃 6개) 5회가 모두 통과한다. 래퍼의 EOF 처리(`provider-scope-wrapper.ts`의 `liveness.once("end", …)`)를 지우면 테스트가 실패한다 |
| 검증 방법 | F5 재실행. EOF 처리 제거 변이 |
| 담당·기한·상태 | 미정 · 러너 사양 결정(U-1) 때 · 신규(12 영역 도구와 겹침) |
### 10-02 Envelope 실패 판정의 경계 다섯 곳을 어떤 테스트도 고정하지 않는다 — 커버리지는 100%다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 17, 6, 11, 21, 24 |
| 근거 | 이번 라운드에 만든 판정 표 `src/adapters/http/backend-envelope.ts`와 실행기의 실패 Envelope 처리에 변이 5종을 넣었다. 모두 관련 94~95파일 813~819개를 통과했다. ① H14: `:123`의 `refusal.status === status`를 지워 code만 맞으면 "쓰기 전 거절"로 본다. 주석(`:88-90`)은 status와 code를 함께 봐야 한다고 적는다. ② H45: `:170`의 `status === 422 ||`를 지워 표 밖 422를 패키지 분류기에 맡긴다. ③ H15: `:194`에서 408·425를 지워 Envelope 실패의 kind가 `SERVER_FAILURE`에서 빠진다. ④ H23: `http-execution-v3.ts:1616-1621`이 실패 Envelope를 min(64 KiB, 응답 한도)로 읽는 것을 64 KiB 고정으로 바꾼다. ⑤ H10b: `:1638` 실패 응답의 media type 검사를 지운다. 테스트를 보면 이유가 보인다. 판정 표 테스트(`tests/integration/http-execution-v3-envelope.test.ts:417-527`)는 표의 code를 모두 제 status로만 보낸다. "패키지가 적용 안 됨이라고 해도 표 밖은 결과 불명" 테스트(`:541-587`)에는 409·400·503·404만 있고 422가 없다. 크기 테스트(`:387-400`)는 성공 Envelope만 본다. 실패 응답의 `CONTENT_TYPE_MISMATCH`를 이름으로 확인하는 V3 테스트는 없다(V2의 `http-client.test.ts:150-165`가 성공 응답 쪽을 봤고 지워졌다). 같은 관련 테스트로 커버리지를 재면 `backend-envelope.ts`는 문장·분기·함수·줄 모두 100%다(실험 C1) |
| 발생 조건 | 표를 고칠 때. 표 주석은 백엔드 SHA가 바뀌면 이 표를 다시 보라고 한다(`:88-89`). 패키지 분류기가 400·422를 모두 "적용 안 됨"으로 보는 기능(1101 README 14.6: 참조 기능 분류기가 그렇다)이 Envelope를 선언할 때 ②가 드러난다 |
| 영향 | ①·②가 깨지면 서버가 이미 썼을 수 있는 응답을 "적용 안 됨"으로 본다. 폼은 저장 버튼을 다시 켜고 다음 저장은 새 멱등 키를 쓴다. 짝 백엔드에서 중복 생성이 생길 수 있다(예: fileserver의 쓰기 뒤 422 `INTEGRITY_MISMATCH`). ③은 게이트웨이 408·425를 재시도 가능한 서버 장애로 보이지 못한다. ④·⑤는 기능이 정한 한도·media type 밖의 실패 본문을 문제로 읽는다 |
| 심각도·우선순위 | Medium · P2 — 지금 코드는 맞다. 깨지면 쓰기 중복이라는 데이터 피해로 이어지고, 두 템플릿을 짝으로 쓰는 출시 경로의 한가운데다. 이 표는 백엔드 변경 때마다 손이 가는 곳이다 |
| 확실성과 남은 가정 | 변이 생존과 커버리지 100%는 실행으로 확인했다(E2). 백엔드가 표의 code를 다른 status로 보내는 경로가 지금 있는지는 백엔드 코드를 보지 않아 모른다 |
| 결정의 근거 | 적용 제외 — 테스트 행 누락이다. 판정 규칙 자체는 계약 문서 6.1절과 맞는다 |
| 이해 비용 | 표 테스트의 이름("follow the backend's refusal table")만 보면 표 전체가 고정된 것처럼 읽힌다 |
| 최소 개선 방향 | `backend-envelope.ts`의 `envelopeFailureEffect`·`idempotencyRefusalReason`·`envelopeFailureReading`을 직접 부르는 status × code 표 단위 테스트를 둔다. 행: 표의 code를 다른 status로(409 `VALIDATION_FAILED`, 400 `IDEMPOTENT_REQUEST_MISMATCH`, 422 `IDEMPOTENCY_KEY_INVALID` → `MAYBE_APPLIED`), 표 밖 422, 408·425 kind. 통합 테스트에는 LENIENT 묶음에 422 `INTEGRITY_MISMATCH` 한 행, 응답 한도보다 크고 64 KiB보다 작은 실패 Envelope 한 행, `text/plain` JSON 실패 본문 한 행을 더한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 40~60줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | H14·H45·H15·H23·H10b가 각각 테스트 하나 이상에서 실패한다 |
| 검증 방법 | 6절 변이를 다시 넣고 `node scripts/run-vitest.ts related src/adapters/http/backend-envelope.ts --run` |
| 담당·기한·상태 | 미정 · 짝 백엔드 출시 전 · 신규(03 영역 코드) |
참고: 이 파일은 `config/testing/risk-coverage.json`의 모듈별 하한에 없다. 그러나 이미 100%라서 하한을 더해도 이 공백은 잡히지 않는다. 빠진 것은 줄이 아니라 경계 값이다.
### 10-03 쿠키 프로필 쓰기의 CSRF 조립 검사를 POST와 `x-xsrf-token` 한 경우로만 고정한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 15, 17, 24 |
| 근거 | `src/contracts/external-contract-runtime.ts:544-557`은 GET·HEAD가 아닌 모든 method(`isRead`, `:503`)에 대해 쿠키 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 요구하게 한다(`365d8c3`). 테스트 `tests/unit/rest-profile-contract.test.ts:65-109`는 fixture의 세 operation(GET, GET, POST) 중 POST만 쓰고, CSRF 헤더는 `x-xsrf-token`만 쓴다. 변이 H18(`!isRead`를 `method === "POST"`로)과 H19(`x-csrf-token` 허용을 지움)가 관련 104파일 904개를 통과했다 |
| 발생 조건 | 누군가 이 조건을 "쓰기 = POST"로 좁히거나 헤더 목록을 바꿀 때 |
| 영향 | H18 쪽: 쿠키 프로필로 PUT·PATCH·DELETE를 하면서 CSRF 헤더를 요구하지 않는 operation이 조립을 통과한다. 백엔드가 CSRF를 검사하면 실행 때 403으로 드러나고, 조립 때 막는다는 이 검사의 목적이 사라진다. H19 쪽: `x-csrf-token`만 요구하는 프로필이 조립에서 거절된다(닫힌 쪽 실패라 바로 보인다) |
| 심각도·우선순위 | Low · P2 — 서버 검사가 최종 방어선이라 피해는 늦은 발견에 그친다. 보안 규칙이라는 이름을 단 테스트가 일부만 고정하고, 고치는 비용이 작다 |
| 확실성과 남은 가정 | 변이 생존은 확인했다. 짝 백엔드가 모든 쓰기 method에 CSRF를 검사하는지는 보지 않았다 |
| 결정의 근거 | 적용 제외 — 테스트 경우 누락이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | `withProfile`이 method를 바꾼 operation을 만들게 하고 POST·PUT·PATCH·DELETE × (`x-csrf-token`, `x-xsrf-token`, 없음)을 표로 돈다. 읽기(GET·HEAD)는 CSRF 없이 통과하는 행을 둔다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 20줄 안팎 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | H18·H19가 실패한다 |
| 검증 방법 | 변이 후 `node scripts/run-vitest.ts related src/contracts/external-contract-runtime.ts --run` |
| 담당·기한·상태 | 미정 · 미정 · 신규(07 영역 코드) |
### 10-04 V2 삭제 과정에서 V3 동작 세 가지가 머지 게이트 테스트의 보호를 잃었다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 21, 19, 12, 14, 27 |
| 근거 | ① 운영 설정 `MAX_RETRY_ATTEMPTS` 전달. `048f490`이 지운 `tests/unit/runtime-adapters.test.ts`의 "injects runtime timeout and max-attempt policy into HTTP execution"은 V2 클라이언트로 이 값이 실행에 닿는지 봤다. V3는 `src/bootstrap/runtime-adapters.ts:470`에서 넘긴다. 변이 H53(값을 상수 2로)이 15파일 143개를 통과했다. 같은 자리의 `REQUEST_TIMEOUT_MS`(`:475`)는 H54로 참조 수직 테스트가 잡았다. ② 호출자 signal의 listener 정리. 지워진 `http-execution-contract.test.ts`의 "distinguishes a runtime timeout from caller navigation abort and cleans listeners"(`048f490^` `:287-337`)가 `removeEventListener` 호출을 셌다. V3 `http-execution-v3.ts:646`을 지운 H56이 94파일 813개를 통과했다. scope signal 쪽(`:648`)을 지운 H57은 `tests/scale/session/long-session.test.ts` 하나만 잡았다. 이 파일은 nightly tier에서만 돌고 머지 게이트에 없다(`config/ci/ungated-tests.json:13`, `scripts/scale/run-scale-profile.ts:93`). ③ realtime snapshot 바인딩의 GET 조건. `12f3bb7`이 V2의 `semantics === "QUERY"` 등을 `operation?.method === "GET"`(`src/contracts/realtime-streams.ts:470`)으로 옮겼다. 이 조건을 지운 H21이 6파일 112개를 통과했다 |
| 발생 조건 | 이 줄들을 리팩터링할 때. ①은 운영자가 장애 때 `MAX_RETRY_ATTEMPTS`를 0으로 낮출 때 드러난다. ②는 같은 signal로 요청을 여러 번 보내는 화면·긴 세션에서. ③은 기능이 PUT 같은 멱등 쓰기를 snapshot으로 묶을 때 |
| 영향 | ① 지금 모든 프로필 값이 2이고 실행기 상한도 2라 평소 동작은 같다. 장애 때 재시도를 끄는 손잡이만 조용히 사라진다(§6.1에서 `REQUEST_TIMEOUT_MS`가 같은 방식으로 버려진 적이 있다, `runtime-adapters.ts:471-474` 주석). ② 요청마다 listener 함수가 signal에 남아 메모리가 는다. 머지 게이트로는 발견하지 못한다. ③ 재연결 때 snapshot 조회가 쓰기를 다시 보낼 수 있다 |
| 심각도·우선순위 | Low · P2 — 지금 코드는 맞다. 셋 다 고치는 비용이 작고, 한 번 깨진 적이 있는 종류(①)와 데이터 쪽 결과(③)가 섞여 있다 |
| 확실성과 남은 가정 | 변이 결과는 확인했다(E2). ②의 실제 누수량은 재지 않았다 |
| 결정의 근거 | [확인한 사실] 14.7절의 V2 동작 판정 표는 동작 셋(401 재전송, KEYED 재시도, 보안 프로필 검사)만 다뤘다. 지운 테스트 이름과 V3 대응 테스트를 하나씩 맞춘 기록은 없다. 이번 리뷰가 그 대조를 6절 M 표로 했다 |
| 이해 비용 | 지운 테스트가 무엇을 지켰는지는 삭제 커밋의 부모에서 파일을 꺼내 봐야 안다 |
| 최소 개선 방향 | ① `runtime-adapters.test.ts`에 `MAX_RETRY_ATTEMPTS: 0`으로 조립한 런타임이 503을 한 번만 보내는 테스트. ② `http-execution-v3.test.ts`에 caller·scope signal의 `add/removeEventListener`를 세는 테스트(지운 테스트를 V3로 옮긴 판). ③ `realtime-stream-registry.test.ts`에 PUT·IDEMPOTENT operation을 snapshot으로 묶으면 거절하는 행 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 3개 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | H53·H56·H57·H21이 머지 게이트가 도는 테스트에서 실패한다 |
| 검증 방법 | 6절 변이 재실행. H57은 `tests/scale` 밖 테스트가 잡아야 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규(03·04 영역 코드) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 03·07 | — | — | 이 영역에서 새 코드 결함은 찾지 않았다. 변이는 모두 테스트 검출력을 본 것이다 |
| 2 | 구조적 성숙도 | > 16 | — | — | — |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1·E2 | **P** — 테스트 전용 기능·레이아웃 fixture로 새 테스트를 쉽게 만든다. 스타터 화면에서 플랫폼 테스트를 떼어냈다(0929/10-02 고쳐짐). 도구 테스트 위치 규칙은 여전히 둘이다(1101/10-05) |
| 4 | 인지 부하 | 적용 | M2 / M2 | E1 | **P** — taxonomy가 계층·위치를 적는다. 한 unit 파일이 한 머지에서 몇 번 도는지 알려면 `gates.json`, `package.json`, `test-feature-scaffold.ts` 세 곳을 맞춰야 한다(최대 5번) |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E2 | **P** — 판정 표 주석은 "status와 code를 함께 본다"고 적지만 테스트가 고정하지 않는다(10-02). 10-01의 1초가 자식 기동을 포함한다는 사실이 테스트에 적혀 있지 않다 |
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | **P** — 실패 경로 변이 대부분을 잡았다(H07~H09, H12, H22, H25, H29, H30, H55). Envelope 실패의 경계 다섯 곳은 못 잡았다(10-02) |
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | — |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E3 | **P** — skip reporter는 이유와 다음 행동을 출력한다. 10-01 실패 문구("EOF close timed out")는 원인(느린 기동)을 가린다 |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | **P** — `scopeSnapshot` 5벌, `as never` scope 9곳(1101/10-08). `test:platform`의 `--no-file-parallelism` 이유 없음 |
| **10** | **테스트 성숙도** | 적용 | 목표 M3 / 확인 M3 | E2(변이 46종), E3(부하) | **P** — V3·계약 변이 40종(동등 2종 제외) 중 28종을 빠른 계층이, 1종을 `check:registries`가 잡았다. 살아남은 11종은 10-02·10-03·10-04. 지난 변이 4종 중 2종이 여전히 산다(§10.8, 세션 복구). `backend-envelope.ts`는 커버리지 100%인데 변이 5종이 산다. 부하 재현 5/5 실패(10-01) |
| 11 | 데이터 성숙도 | > 05 | — | — | 10-02가 깨지면 짝 백엔드 쓰기 중복으로 이어진다(영향만 연결) |
| **12** | **동시성 성숙도** | 적용(테스트 격리·CPU 경쟁) | M3 / M2 | E3 | **P** — 테스트 사이 상태 격리는 좋다(`vitest.config.ts`의 `restoreMocks`·`clearMocks`·`mockReset`, `tests/setup.ts`의 `useRealTimers`). 2코어 4 worker 실행에서 unit 2,580개 통과. CPU 경쟁이 심하면 자식 프로세스 기동을 1초 안에 넣는 테스트가 떨어진다(10-01). 같은 원인의 guardian 테스트는 고쳐졌다 |
| 13 | 확장성 | > 11·15 | — | — | — |
| 14 | 성능 성숙도 | 적용(테스트 실행 비용) | M2 / M1 | E2 | **P** — 빠른 계층 테스트 시간 합 220s 중 unit 154s. 그중 도구 테스트가 66%(1101/10-05). 실제 시계 대기 약 9s(1101/10-07). setup 누적 69s(R1). 중복 실행(1101/10-06) |
| 15 | 보안 성숙도 | 적용(보안 규칙의 테스트) | M3 / M2 | E2 | **P** — 자격증명 헤더 변이 4종 모두 잡았다(H07~H09, H28). 필드 오류에서 백엔드 문구 제거도 잡았다(H13). 쿠키 CSRF 조립 검사는 POST만 고정한다(10-03) |
| 16 | 의존성 성숙도 | > 13 | — | — | — |
| 17 | API / Contract 성숙도 | 적용(계약 테스트) | M3 / M2 | E2 | **P** — V2에서 V3로 옮긴 조립 규칙 3종(H50~H52)을 잡았다. FE-REG-API 행 변이는 `check:registries`가 잡는다(H20). Envelope 판정 경계(10-02)와 snapshot GET 조건(10-04 ③)은 아무도 고정하지 않는다 |
| 18 | 배포 성숙도 | > 13 | — | — | — |
| 19 | 설정 성숙도 | 적용(러너·런타임 설정) | M3 / M2 | E2 | **P** — `allowOnly: false`와 skip reporter가 생겼다. `REQUEST_TIMEOUT_MS` 전달은 고정되고 `MAX_RETRY_ATTEMPTS` 전달은 아니다(10-04 ①). `--passWithNoTests`가 남았다 |
| **20** | **개발자 경험** | 적용 | M2 / M2 | E2·E3 | **P** — 새 worktree에서 설치 7초, `node scripts/run-vitest.ts related …`가 문서대로 돈다. skip을 남기면 실패 문구가 할 일을 알려 준다. `test:all`이 CI 빠른 테스트 일부를 빠뜨린다(0929/10-05). 부하에서 거짓 실패가 머지를 막는다(10-01) |
| **21** | **Guardrail 성숙도** | 적용 | M3 / M3 | E2 | **P** — skip·todo·only·`context.skip()`·`skipIf`가 모든 게이트 실행에서 실패한다(1101/10-04 고쳐짐, M3). 커버리지 하한은 경계 값 누락을 보지 못한다(10-02: 100%인데 변이 5종 생존). scope listener 누수를 잡는 유일한 테스트가 머지 게이트 밖에 있다(10-04 ②) |
| 22 | 추상화 성숙도 | 적용(테스트 도우미) | M2 / M2 | E1 | **P** — `fixture-feature.tsx`, `fixture-layout-product.tsx`, `external-contract-fixture.ts`가 샘플 대신 쓸 대상을 준다. scope fixture 복사본은 그대로다 |
| 23 | 일관성 | 적용 | M2 / M1 | E1 | **P** — 자식 프로세스 대기 방식이 둘이다: guardian은 준비 신호, task3은 고정 75ms + 1초(10-01). `deferred()` 7벌 |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2 | **P** — "refuses a write whose cookie profile requires no CSRF header"는 POST 하나만 본다(10-03). "verdicts follow the backend's refusal table"은 status 조건을 보지 않는다(10-02) |
| 25 | 조직 확장성 | - | 작성자 1인 | — | — |
| 26 | Ownership 성숙도 | 부분 적용 | M2 / M1 | E1 | **P** — 커버리지 모듈에는 owner가 있다. `ungated-tests.json` 항목에는 담당·재검토 시점이 없다(12 영역) |
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E2 | **P** — 샘플을 지워도 플랫폼 검사가 남는다(0929/10-02 고쳐짐). V2 경로를 지울 때 지운 테스트와 V3 대응 테스트를 맞추지 않아 보호 세 개가 빠졌다(10-04) |
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | — |
집계(적용 18개, `>`·`-` 제외): 충족 0 · 부분 충족 18 · 미충족 0 · 미검증 0. 지난 라운드와 같다. 21번은 skip 차단이 생겨 확인 통제가 M2에서 M3으로 올랐지만 새 공백(커버리지가 못 보는 경계, 게이트 밖 유일 검출)이 있어 P로 둔다.
## 5. 설계 선택 검토 (41절)
### 5.1 V2 전용 테스트를 V2 코드와 함께 지운다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 아무도 부르지 않는 V2 클라이언트와 V2 행을 지워 코드와 초기 JS를 줄인다(사용자 지시). 동시에 V3에 남은 같은 규칙은 계속 지켜져야 한다 |
| 2. 지킬 성질 | V3가 가진 규칙마다 그것이 깨지면 실패하는 머지 게이트 테스트가 하나 이상 있다 |
| 3. 현재 보장 | [확인한 사실] `048f490`은 V2 전용 테스트 7개를 지우고 섞인 파일은 V2 블록만 지웠다. 폼 테스트와 Envelope 테스트는 V3로 옮겼다. `12f3bb7`은 V2 행 테스트와 일치 테스트를 지웠다. V2에만 있던 동작 셋은 14.7절에서 하나씩 판정했고 CSRF 검사(`365d8c3`)와 KEYED 재전송(`c05f41a`)을 테스트와 함께 되살렸다. 이번 대조(6절): 지운 테스트가 보던 V3 규칙 28종 중 22종은 빠른 계층이, 1종은 `check:registries`가 잡았다. [보장하지 않음] 지운 테스트 이름과 V3 대응 테스트를 하나씩 맞춘 기록. 그 대조가 없어 다섯 곳(`MAX_RETRY_ATTEMPTS` 전달, listener 정리 둘, 게이트웨이 408·425, POST 밖 CSRF)이 빠졌다(10-02~10-04) |
| 4. 대안 | ⓐ 현 상태(지우고 필요한 것만 옮김) ⓑ 지우기 전에 V2 테스트 이름마다 V3 대응 테스트를 표로 맞춤 ⓒ V2 테스트를 모두 V3 실행기 대상으로 바꿔 옮김 ⓓ 지우기 전후 대표 규칙에 변이를 넣어 비교 |
| 5. 비용 비교 | ⓐ 가장 싸다. 대응이 없는 보호가 조용히 빠진다. ⓑ 테스트 이름 100여 개를 한 번 훑는 비용. 대응이 없는 것만 옮기면 된다. ⓒ 이미 V3 테스트가 있는 규칙까지 두 번 적게 된다. ⓓ 정확하지만 이번 리뷰에서 46종에 약 1시간이 들었다(공유 호스트) |
| 6. 현재 조건에서의 선택 | [추론] ⓑ. 코드 삭제 결정 자체는 맞다(부르는 곳이 없고 다운스트림도 쓰지 않는다). 빠진 보호는 대조 한 번으로 찾을 수 있는 종류다. 변이(ⓓ)는 대조에서 대응이 애매한 몇 개에만 쓴다 |
| 7. 재검토 조건 | 다음에 실행 경로 하나를 통째로 지울 때(예: legacy query 분기, 08-03) 같은 대조를 한다. 지운 테스트가 수십 개를 넘으면 ⓓ를 대표 규칙에 한정해 더한다 |
### 5.2 skip·todo·only 차단을 `run-vitest.ts`가 붙이는 reporter로 한다 (1101/10-04의 수정)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 실패하는 테스트를 `it.skip`으로 끄고 머지하는 것을 막는다. 일부러 좁힌 로컬 실행(`-t`, `file:line`)은 막지 않는다 |
| 2. 지킬 성질 | 모든 게이트 실행에서 실행되지 않은 테스트가 있으면 실패한다 |
| 3. 현재 보장 | [확인한 사실] `scripts/run-vitest.ts:66-71`이 reporter를 붙이고, 호출자가 `--reporter`를 주면 기본 reporter만 빼고 이 reporter는 남긴다. `package.json`의 모든 Vitest 실행이 `run-vitest.ts`를 거친다. P-B에서 skip·todo·`.only`·`context.skip()`·`skipIf(true)` 모두 종료 코드 1. 좁힌 실행은 제외된다(`no-skipped-tests-reporter.ts`의 `isNarrowedRun`). [보장하지 않음] IDE에서 `vitest`를 직접 돌릴 때. 게이트와 무관하다 |
| 4. 대안 | ⓐ 현 상태 ⓑ ESLint `vitest/no-disabled-tests`·`no-focused-tests` ⓒ junit의 `skipped` 수를 보는 사후 검사 |
| 5. 비용 비교 | ⓐ 의존성 없이 실행 결과로 막아 동적 skip도 잡는다. 실행을 끝까지 돌린 뒤에야 실패한다. ⓑ 편집기에서 바로 보이지만 동적 skip을 못 잡고 의존성이 하나 는다. ⓒ 증거 파일 이름을 아는 검사가 하나 더 생긴다 |
| 6. 현재 조건에서의 선택 | [추론] ⓐ가 맞다. 이 템플릿은 모든 실행을 이미 한 진입점으로 모았고, 그 진입점에 붙이면 새 개념이 없다. `skipIf`까지 막는 것은 14.1절 결정(빠른 계층에 quarantine 없음)과 맞는다 |
| 7. 재검토 조건 | 플랫폼별 조건부 테스트가 필요해지면 허용 목록을 둔다. 게이트가 `run-vitest.ts`를 거치지 않는 실행을 갖게 되면 그 실행에도 붙인다 |
### 5.3 자식 프로세스 테스트의 시간 한도를 실제 시계로 둔다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 스크립트가 자식 프로세스로 지키는 프로토콜(EOF 뒤 정리, lease 만료)을 머지 전에 검사한다. 멈추는 회귀는 테스트 제한(10s)보다 먼저 이유와 함께 실패해야 한다 |
| 2. 지킬 성질 | 한도는 "멈춤"만 판정한다. 자식 기동이 느린 것은 실패가 아니다 |
| 3. 현재 보장 | [확인한 사실] guardian 파일은 준비 신호 뒤에 마감을 계산하고 watchdog 5초를 쓴다(`c862004`). task3 파일은 고정 75ms 대기와 1초 한도를 쓴다. taxonomy는 이런 테스트를 `tests/integration`에 두고 한도를 watchdog으로 본다. [보장하지 않음] task3의 1초가 기동 시간을 포함하지 않는다는 것 |
| 4. 대안 | ⓐ 현 상태 ⓑ 한도만 5초로 ⓒ 준비 신호 뒤에 stdin을 닫음(guardian 방식) ⓓ 자식 대신 같은 프로세스에서 래퍼 함수를 부름 |
| 5. 비용 비교 | ⓐ 부하에서 떨어진다(F5 5/5). ⓑ 한 줄. 기동이 5초를 넘는 극단 조건만 남는다. ⓒ 기동을 한도 밖으로 뺀다. 수십 줄. ⓓ 가장 빠르지만 래퍼가 실제로 쓰는 libuv pipe 동작(래퍼 주석이 fs 읽기로는 교착한다고 적는다)을 검사하지 못한다 |
| 6. 현재 조건에서의 선택 | [추론] ⓒ+ⓑ. 이 테스트가 보려는 것이 자식 프로세스 경계 자체라 ⓓ는 목적을 잃는다. guardian과 같은 방식으로 맞추면 규칙이 하나가 된다 |
| 7. 재검토 조건 | 자식 프로세스 테스트가 더 늘면 준비 신호를 `tests/helpers`의 공용 도우미로 뺀다 |
## 6. 실험·변이 기록
모든 실험은 격리 worktree(`agent-a1906b089fc371330`, `e40684b` detached)에서 했다. 원본을 고친 뒤 `node scripts/run-vitest.ts related <파일> --run --maxWorkers=5`를 돌리고 원본을 되돌렸다(harness가 실행마다 복원). 끝난 뒤 `git status`가 깨끗한 것을 확인했다. 실험 중 호스트 1분 부하는 8~90이었고 다른 리뷰어와 호스트를 나눠 썼다. 그래서 시간 값은 비교용이 아니다. 변이 결과는 실패한 테스트 이름이 바꾼 규칙과 맞는지 하나씩 확인했다(부하로 우연히 떨어진 테스트는 없었다).
### 6.1 변이 (M)
"지운 테스트" 칸은 그 규칙을 V2 경로에서 보던, `048f490`·`12f3bb7`이 지운 테스트다. "생존"은 관련 테스트 전부가 통과했다는 뜻이다.
| ID | 지키는 규칙 | 바꾼 곳(`e40684b`) | 지운 테스트 | 결과 | 잡은 테스트 |
|---|---|---|---|---|---|
| H01 | NEVER는 상태 응답에도 재시도하지 않는다 | `http-retry-lifecycle.ts:33` NEVER도 허용 | `retry-policy.test.ts` "retries 408 and 425 … only for safe or keyed" | 잡힘(1) | `http-retry-lifecycle.test.ts` |
| H02 | 응답 재시도 상한 | `http-execution-v3.ts:1108` `<`→`<=` | `http-client.test.ts` "retries a safe request at most twice" | 잡힘(5) | `http-execution-v3.test.ts` 4, envelope 1 |
| H02b | 전송 실패 재시도 상한 | `:1046` `<`→`<=` | 같음 | 잡힘(1) | observability "emits one failure telemetry event" — 텔레메트리 수로 간접 검출 |
| H03 | Retry-After 상한 5s | `http-retry-lifecycle.ts:60` 제거 | `retry-policy.test.ts` "does not automatically wait beyond 30 seconds" | 잡힘(2) | `http-retry-lifecycle.test.ts`, `tests/scale/traffic/retry-after-jitter.test.ts` |
| H04 | 지터 상한 2s | `:37` 상한 제거 | `retry-policy.test.ts` "uses capped exponential full jitter" | 잡힘(1) | `http-retry-lifecycle.test.ts` |
| H05 | KEYED는 보낸 뒤 재전송하지 않는다 | `:27` 항상 true | — | 잡힘(2) | `http-execution-v3.test.ts`, `http-retry-lifecycle.test.ts` |
| H06 | KEYED 키 형식 | `http-execution-v3.ts:486` 형식 검사를 `undefined` 검사로 | `http-client.test.ts` 키 4종 it.each | **동등 변이** | 앞 단계 `defineMutationIntent`가 같은 함수로 먼저 거른다. 그 단계는 `legacy-and-optional-network-remediation.test.ts:132-164`가 고정한다 |
| H07 | bearer 필수 헤더 | `http-contract-bridge.ts:101` 조건 false | `legacy-http-credential-authority.test.ts` LEG-02 | 잡힘(1) | `http-execution-v3-auth-profile.test.ts` |
| H08 | 같은 헤더 중복 거절 | `:87` 조건 false | LEG-02 "duplicated" | 잡힘(1) | `http-contract-bridge.test.ts` |
| H09 | 헤더 값 문자 검사 | `:92` 제거 | LEG-02 "malformed" | 잡힘(8) | live-authority, bridge |
| H10 | 성공 응답 media type | `http-execution-v3.ts:1402` 조건 false | `http-client.test.ts` "rejects a non-JSON response" | 잡힘(1) | `http-scenario-catalog.test.ts` 하나 |
| H10b | 실패 응답 media type | `:1638` 조건 false | — | **생존** (94파일 813개) | 없음 → 10-02 |
| H11 | 경로 값 `.`·`..` 거절 | `http-contract-bridge.ts:203-204` | `request-builder.test.ts` "." ".." | 잡힘(2) | `http-contract-bridge.test.ts` |
| H12 | 결과 불명 응답은 재전송하지 않는다 | `http-execution-v3.ts:1105` 제거 | `http-client.test.ts` "keeps the Retry-After of an in-flight 409 without resending" | 잡힘(1) | `http-execution-v3.test.ts` |
| H13 | 필드 오류는 path·code만 넘긴다 | `backend-envelope.ts:215` 원본 details 그대로 | `http-client.test.ts` "projects only approved 422 issue path and code" | 잡힘(4) | `form-foundation.test.tsx` 3, envelope 1 |
| H14 | 쓰기 전 거절 = code와 status 둘 다 | `backend-envelope.ts:123` status 조건 제거 | — | **생존** (95파일 819개) | 없음 → 10-02 |
| H15 | 게이트웨이 408·425는 SERVER_FAILURE | `:194` 408·425 제거 | `http-client.test.ts` Q-6.3-3b 묶음(`:167-230`) | **생존** (95파일 819개) | 없음 → 10-02 |
| H16 | 관측의 시도 횟수 | `http-execution-v3.ts:676` 상수 1 | `http-diagnostics.test.ts` "summarizes retry recovery once" | 잡힘(1) | `http-scenario-catalog.test.ts` |
| H18 | 쿠키 쓰기 CSRF — 모든 쓰기 method | `external-contract-runtime.ts:547` `!isRead`→`method === "POST"` | `rest-profile-contract.test.ts`(V2판) | **생존** (104파일 904개) | 없음 → 10-03 |
| H19 | 쿠키 쓰기 CSRF — `x-csrf-token`도 허용 | `:550` `x-csrf-token` 제거 | — | **생존** (104파일 904개) | 없음 → 10-03 |
| H20 | FE-REG-API 행의 authProfileId | `api-operations.ts:45` 상수 `ANONYMOUS` | `http-operation-v2-v3-parity.test.ts` | 빠른 계층 생존(20파일 117개) · **`check:registries`가 잡음** | "breaking change missing evidence: FE-REG-API:…:authProfileId" 3건(실험 R1). `api-operation-rows.test.ts`의 fixture는 `ANONYMOUS`뿐이고 셋째 테스트는 같은 함수 결과끼리 비교한다 |
| H21 | realtime snapshot은 GET만 | `realtime-streams.ts:470` 조건 제거 | — | **생존** (6파일 112개) | 없음 → 10-04 ③ |
| H22 | 재시도 뒤 effect를 낮추지 않는다 | `http-execution-v3.ts:1131` 누적값 무시 | — | 잡힘(2) | `http-execution-v3.test.ts` |
| H23 | 실패 Envelope 한도 = min(64 KiB, 응답 한도) | `:1616` 항상 64 KiB | — | **생존** (94파일 813개) | 없음 → 10-02 |
| H25 | 자격증명 대기도 마감 안에서 | `:806` 그냥 await | `http-client.test.ts` "bounds a non-cooperative legacy credential owner" | 잡힘(8) | auth-profile, `http-execution-v3.test.ts` |
| H26a | 보내기 전 거절은 세션에 알리지 않는다 | `runtime-adapters.ts:591` metadata 조건 제거 | `auth-recovery.test.ts` | 잡힘(1) | `reference-runtime-composition.test.ts` |
| H26b | 서버 401은 세션에 알린다 | `:591` 조건 false | `legacy-http-credential-authority.test.ts` LEG-01 | 잡힘(2) | reference vertical, composition |
| H27 | 503 `IDEMPOTENCY_UNAVAILABLE`은 같은 키로 재전송 | `http-execution-v3.ts:1101` 제거 | — (`c05f41a` 새 규칙) | 잡힘(2) | envelope |
| H28 | 자격증명 쪽이 `Idempotency-Key`를 넣지 못한다 | `:848` 대소문자 구분 | — | 잡힘(1) | `http-execution-v3.test.ts` |
| H29 | `mapProblem` 예외는 매핑 위반 | `feature-http-binding.ts:408` 예외 다시 던짐 | `http-client.test.ts` "guards mapper exceptions" | 잡힘(1) | `feature-http-binding.test.ts`(contract) |
| H30 | `mapSuccess` 예외는 매핑 위반 | `:392` 같음 | 같음 | 잡힘(1) | 같음 |
| H40 | 취소는 실패 텔레메트리가 아니다 | `runtime-adapters.ts:254` 제거 | `http-diagnostics.test.ts` "records navigation abort without failure telemetry" | **동등 변이** | 아래 `cancellationOwner` 검사(`:262-267`)가 같은 경우를 거른다 |
| H42 | correlation id는 텔레메트리에 싣지 않는다 | `:227` 속성 추가 | — | 잡힘(2) | observability |
| H45 | 표 밖 422는 결과 불명 | `backend-envelope.ts:170` 422 제거 | — | **생존** (95파일 819개) | 없음 → 10-02 |
| H50 | KEYED는 recovery 서술이 필요 | `external-contract-runtime.ts:527` 조건 false | `api-operation-v2.test.ts` "KEYED_COMMAND whose idempotency key is not required" | 잡힘(1) | `external-contract-runtime.test.ts` |
| H51 | 읽기에는 command 서술이 없다 | `:505` 조건 false | `api-operation-v2.test.ts` "rejects a COMMAND sent as GET" | 잡힘(1) | 같음 |
| H52 | NEVER에는 재시도 예산이 없다 | `:558` 조건 false | `api-operation-v2.test.ts` "unsafe query/replay policy" | 잡힘(1) | 같음 |
| H53 | `MAX_RETRY_ATTEMPTS`가 실행기에 닿는다 | `runtime-adapters.ts:470` 상수 2 | `runtime-adapters.test.ts` "injects runtime timeout and max-attempt policy" | **생존** (15파일 143개) | 없음 → 10-04 ① |
| H54 | `REQUEST_TIMEOUT_MS`가 실행기에 닿는다 | `:475` 제거 | 같음 | 잡힘(1) | `reference-production-vertical.test.tsx` |
| H55 | 최종 검사의 마감 만료는 TIMEOUT(0929/10-03) | `http-execution-v3.ts:1002` 조건 false | — | 잡힘(1) | observability P-03-05 |
| H56 | 호출자 signal listener 정리 | `:646` 제거 | `http-execution-contract.test.ts` "… and cleans listeners" | **생존** (94파일 813개) | 없음 → 10-04 ② |
| H57 | scope signal listener 정리 | `:648` 제거 | 같음 | **머지 게이트 생존** | `tests/scale/session/long-session.test.ts`만 잡음(nightly, 게이트 밖) → 10-04 ② |
| L01 | §10.8 오래된 scope의 성공 응답 버림(0929/10-04) | `http-execution-v3.ts:1476` 조건 false | — | **생존** (94파일 813개) | 없음 |
| L02 | 세션 복구 중 보호 라우트는 복구 대기(1101/10-03) | `navigation-policy.ts:21` | — | **생존** (18파일 105개) | 없음 |
| L03 | Popover Escape 뒤 포커스 반환(1101/10-02) | `popover.tsx:30` 제거 | — | 잡힘(1) | `design-system-platform.test.tsx` |
| L04 | 이벤트 계약 검증(1101/10-01) | `external-contract-runtime.ts:901` 호출 제거 | — | 잡힘(6) | `contract-registry-immutability.test.ts` |
집계: V3·계약 변이 42종 중 동등 2종(H06, H40)을 빼면 40종이다. 빠른 계층이 28종을 잡았고 `check:registries`가 1종(H20)을 잡았다. 11종이 머지 게이트를 통과했다. 지운 테스트가 보던 규칙만 세면 28종 중 22종을 빠른 계층이, 1종을 `check:registries`가 잡았고 5종(H15, H18, H53, H56, H57)이 살아남았다. 지난 라운드 변이 4종(L) 중 2종이 여전히 산다.
### 6.2 그 밖의 실험
| ID | 방법 | 결과 |
|---|---|---|
| P-B | 임시 파일 `tests/zz-r10-tmp/{skip,only,dyn}.test.ts`(skip+todo / `.only` / `context.skip()`+`skipIf(true)`)를 `node scripts/run-vitest.ts run`으로 실행. 끝난 뒤 지움 | 셋 다 종료 코드 1. skip+todo는 `CI` 없이도 실패. 출력: "2 test(s) did not run. A skipped or todo test fails the run (10-04)" + 다음 행동 안내. `.only`는 "Unexpected .only modifier" |
| C1 | `related src/adapters/http/backend-envelope.ts --coverage --coverage.include=<그 파일>` | `backend-envelope.ts` 문장 100%(20/20)·분기 100%(34/34)·함수 100%·줄 100%. 같은 방식으로 binding+실행기를 함께 재면 `feature-http-binding.ts` 87.7% / 84.0%(문장/분기), `http-execution-v3.ts` 90.8% / 84.2% |
| R1 | H20을 넣고 `node scripts/check-registries.ts` | 종료 코드 1. 참조 기능 operation 3개 모두 `authProfileId:field-changed` |
| F1 | 측정기(`scratchpad/r10/eof-probe.mjs`): 래퍼를 띄우고 75ms 뒤 stdin을 닫아 종료까지 잼, 10회. CPU 제한 없음, 부하 27 | 86~149ms |
| F2 | F1을 `taskset` 한 코어로 | 42~100ms |
| F3 | 한 코어 + 같은 코어의 바쁜 이웃(`node -e 'for(;;){}'`) 2개 / 4개 | 409~530ms / 592~762ms |
| F4 | 실제 테스트 파일 `tests/unit/task3-selective-integration.test.ts`, 한 코어 + 이웃 4개, 5회 | 5회 통과. 해당 테스트 659~977ms(한도 1,000ms) |
| F5 | 같은 파일, 한 코어 + 이웃 6개, 5회 | **5회 모두 실패**. "provider scope EOF close timed out", 1,235~1,272ms |
| F6 | `taskset -c 10,11 node scripts/run-vitest.ts run tests/unit --maxWorkers=4`, 1회(부하 약 20) | 176파일 2,580개 통과, 115s. 해당 테스트 393ms |
| F7 | F6에 `--coverage`(V8)를 더해 1회 | 176파일 2,580개 통과, 142.9s. 해당 테스트는 느린 테스트 표시 기준(300ms) 아래라 목록에 없었다 |
| J1 | 오케스트레이터 junit에서 테스트별 시간, `tests/unit` 파일을 import 대상으로 분류 | 3,039개 220.2s. unit 176파일: `src`만 109파일 28.3s(18%), `scripts`만 44파일 78.4s(51%), 둘 다 12파일 24.7s(16%), import 없음(자식 실행) 11파일 23.0s(15%) |
### 6.3 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 CI 러너에서 10-01의 실패율 | CI 꺼짐(U-1). 러너 사양 없음 | U-1 뒤 FE-GATE-005·020을 20회 돌려 센다 |
| 짝 백엔드가 표의 code를 다른 status로 보내는 경로(10-02 ①) | 백엔드 코드를 보지 않았다 | 백엔드 `docs/web/http-contract.md` §2와 예외 처리기 대조 |
| 10-04 ②의 실제 누수량 | 재지 않았다 | long-session 테스트를 H56·H57 상태로 돌려 listener 수 기록 |
| 조용한 호스트의 측정 | 공유 호스트 | 전용 호스트에서 F4·F5 각 20회 |
@@ -0,0 +1,317 @@
# 영역 11 — 테스트: 브라우저·릴리스·규모
> 검토일: 2026-11-03 · 기준: 브랜치 `review/2026-11-03-merged` / `e40684b` (두 작업 브랜치 `claude/happy-easley-233d07`, `fix/ui-design-audit-2026-11-01`을 합친 커밋). 리뷰 worktree는 이 커밋에서 깨끗한 상태로 시작했다. 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `playwright*.config.ts` 5개. 판정에 필요해서 함께 읽은 것: `scripts/create-feature.ts`(생성 기능 모양), `scripts/test-feature-scaffold.ts`, `scripts/write-a11y-report.ts`, `scripts/lib/manual-a11y-evidence.ts`, `src/presentation/components/async-surface.tsx`, `scripts/run-and-validate-provider.ts`(`.git` 가리기), `scripts/check-system-test-prerequisites.ts`, `scripts/generate-ci-workflow.ts`·`.gitea/workflows/quality-gates.yml`(브라우저 설치 단계), `config/ci/gates.json`(FE-GATE-008·013), `scripts/drill-runbook.ts`, `docs/manual/reference/create-feature.md`, `docs/testing/frontend-platform-testing-strategy.md` 13.4절.
> 깊게 본 관점: 10, 13, 14, 18, 28.
> 이번 라운드 렌즈: (1) 이 커밋에서 e2e·visual·system을 실제로 돌린다. (2) `create:feature`로 만든 기능의 라우트를 접근성 e2e가 무엇으로 검사하는지 확인한다. (3) webkit `old-tab-chunk-recovery.spec.ts` 간헐 실패가 `267c724`로 닫혔는지 확인한다.
> 영역 판정(35.8): **조건부 사용 가능.** e2e·visual·storybook은 세 엔진 모두 실패 0이다(e2e 187 통과·3 quarantine skip, visual 6/6, storybook 1/1). capability는 63개 중 61개가 통과했고 2개는 부하 타이밍 실패다(11-05). webkit 구 탭 청크 테스트는 loadavg 38~71에서 20/20 통과했다. 참고 구현으로 써도 된다. 다음은 그대로 믿지 않는다. (a) `create:feature`로 만든 기능의 라우트는 접근성 e2e가 빈 목록이 아니라 Envelope 불일치 오류 화면을 검사하고, 릴리스 증거는 그 라우트를 "passed"로 적는다(11-01). (b) CI merge job이 시각 테스트 글꼴을 설치하지 않아 빈 러너에서 FE-GATE-008이 실패한다(11-02). (c) `test:system` provider 테스트 10개(선언 8개)는 10초 상한에 묶여 부하에서 시간 초과로 떨어진다(11-03). (d) `test:system`은 git worktree에서 돌지 않는다(11-04). (e) IndexedDB 차단 업그레이드 capability 테스트가 500 ms 전이 상태를 폴링해 부하에서 흔들린다(11-05).
## 0. 결론
- **e2e·visual·storybook은 이 커밋에서 모두 통과했다.** e2e는 chromium 63, chromium-compact 1, firefox 60(+SW quarantine 3 skip), webkit 63으로 187 통과·0 실패다(벽시계 94초, loadavg 12→31). visual은 글꼴 확인 1 + 화면 5 = 6/6(12초)이다. storybook은 1/1(19초, 빌드 포함)이다. 재시도는 0이다. capability는 세 엔진 63개 중 61개가 통과했다. 실패 2개(`indexeddb-runtime.spec.ts:982`, chromium·webkit)는 단독으로 18번 돌리면 모두 통과한다(11-05). capability dev 서버는 호스트 inotify 한도 때문에 두 번 뜨지 못해 세 번째에 폴링 감시로 돌렸다.
- **`test:system`은 worktree에서 16개가 실패하고, `.git`이 디렉터리인 clone에서는 112개 중 111개가 통과한다.** worktree 실패 16건은 원인이 하나다. provider 샌드박스가 `.git` 자리에 tmpfs를 만들려 하는데 worktree의 `.git`은 파일이다(11-04). clone의 1건은 `kills descendants … timeout termination`이 10초 상한을 넘긴 시간 초과다(10,116 ms, loadavg 13~15). 같은 테스트를 따로 8번 돌리면 2번 시간 초과였다(loadavg 27~33, 11-03).
- **생성한 기능의 라우트는 접근성 e2e에서 오류 화면으로 검사된다.** `create:feature sample-feature`로 만든 `/sample`에 접근성 spec과 같은 `[]`를 답하면, 세 엔진 모두 "서버 응답 구조가 예상과 다릅니다." 경고 상자를 그린다. axe는 그 화면을 보고 통과한다. Envelope 빈 목록을 답하면 같은 라우트가 빈 상태 화면을 그린다. 빈·목록 상태에만 접근성 위반(이름 없는 버튼)을 넣어도 원래 spec은 세 엔진 모두 통과했다. 같은 화면에 Envelope로 답하면 세 엔진 모두 axe가 `button-name`을 잡았다(11-01).
- **시각 테스트 글꼴 고정(1101/11-02)은 코드에 들어왔지만 CI에는 안 들어왔다.** `fonts.conf`와 `visual-fonts` 확인은 동작한다. 하지만 CI workflow와 그 생성기는 글꼴 패키지를 설치하지 않는다. `fonts.conf`를 Playwright가 까는 글꼴 디렉터리로 바꿔 빈 러너를 흉내 내자, 글꼴 확인이 "WenQuanYi Zen Hei"를 보고 설치 안내와 함께 실패했고 화면 5장은 돌지 않았다(11-02).
- **지난 라운드 영역 11 발견 4건 중 3건은 고쳐졌고 1건은 절반만 고쳐졌다.** 1101/11-01(cgroup 테스트), 11-03(허용치), 11-04(문서 목록)는 고쳐졌다. 1101/11-02는 CI 반영이 빠져 새 11-02로 다시 적는다. webkit 간헐 실패(1101/14.3)는 `267c724` 뒤 20/20 통과로 고쳐짐으로 본다. 생성 기능을 넣은 상태의 e2e 전체는 190 통과와 호스트 원인 실패 9개였다(다시 돌려 9/9 통과). 기능 하나를 더해도 다른 e2e는 깨지지 않았다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 11 |
| 커밋·작업 상태·확인 시점 | `e40684b`(2026-11-03 22:49 +0900). 확인은 2026-11-03 22:55~23:50. 리뷰 worktree는 이 커밋에서 깨끗했다. 지난 영역 11 기준(`d99301b`) 이후 이 영역 경로에서 38개 파일이 바뀌었다(`git diff --stat d99301b e40684b -- <영역 경로>`). 시각 골든 5장, `tests/visual/fonts.conf`·`fonts.setup.ts` 추가, e2e spec 11개와 helper 2개, `tests/system` 1개, `tests/architecture/context-route-roots.test.ts` 추가가 크다 |
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음. 짝 백엔드(`clean-architecture-backend-template`)는 모든 JSON 응답을 Envelope(`{success, data\|error, meta}`)로 보낸다 |
| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿을 짝으로 써서 서비스를 빨리 출시한다. 성능 예산은 `config/performance/budgets.json`, 기능 규모 상한은 `config/scale/feature-shape-ceilings.json`. RPO/RTO 목표는 없다 |
| 실행 환경 | Ubuntu 24.04.5, Node v24.14.0, pnpm 11.17.0, Playwright 1.62.0(chromium 1234, firefox 1538, webkit 2336), Intel Core Ultra 7 155H(22 스레드). 다른 영역 리뷰어가 동시에 돌아 loadavg가 8~96이었다. 무거운 실행은 모두 공용 잠금(`/tmp/claude-1000/review-2026-11-03-heavy.lock`)으로 직렬화했다 |
| 읽은 코드·구성 범위 | 머리의 경로 전체와 함께 읽은 파일. `tests/release`·`tests/scale`·`tests/architecture`·`tests/scripts`는 바뀐 파일과 실패 경로 위주로 읽었다 |
| 수행한 테스트·실험 | 6절. e2e 4개 프로젝트 전체 2회(기본, 생성 기능 + 변이)와 실패분 재실행 1회, visual 4회(기본, 변이 3종, 무효 1회 별도), storybook 1회, capability 전체 3회(2회는 호스트 원인으로 서버 미기동)와 표적 반복 18회, `test:system` 2회(worktree, clone)와 표적 반복 8회, webkit 구 탭 spec 20회 반복, 영역 vitest 1회, 생성 기능 실험 spec(세 엔진), drill 소스 검사 변이 1회 |
| 확인하지 못한 범위·이유 | 실제 Gitea 러너(U-1, Actions 꺼짐). capability 전체 실행의 반복(호스트 inotify 한도 때문에 두 번은 dev 서버가 뜨지 않았고, 세 번째는 폴링 감시로 돌렸다). lab 성능 재측정(영역 15 범위). main·nightly·release scale tier(기준선 기계와 긴 시간이 필요). 생성 기능을 기존 context에 넣는 경우(`--context`)와 파라미터가 있는 생성 라우트 |
| 이전 리뷰와 비교 가능한 범위 | 2026-11-01 영역 11의 발견 4건, 그 문서 2절이 이월한 2026-09-29 발견, README 14.3·14.6의 이 영역 항목(2절). 지난 실행 결과는 증거로 쓰지 않았다. 단위 게이트는 오케스트레이터가 같은 커밋에서 돌린 결과를 인용했다(`review-gates/summary.txt`: unit 2,580, component 263, integration 117, contract 23, runtime-schema 56 통과, `check:ci`·`check:architecture` 등 통과). `test:system`은 그 목록에 없어서 이 영역이 돌렸다 |
## 2. 지난 발견 재판정
상태 판단은 현재 코드 위치와 이번 실행 결과로 했다. 지난 라운드 ID는 `1101/11-NN`, 그보다 앞선 것은 `0929/11-NN`으로 적는다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1101/11-01 | `tests/system` cgroup 테스트가 끝난 PID의 argv를 조회해 항상 실패 | **고쳐짐** | `tests/system/ci-runner/ci-artifact-contract.test.ts:808-845`가 `/proc` 표본 대신 실행 단계가 직접 남긴 trace(`PROVIDER_PROCESS_TRACE_VARIABLE`)를 읽는다(`a6560be`). clone 실행에서 `applies effective aggregate cgroup limits …`가 3,321 ms로 통과했다 |
| 1101/11-02 | 시각 골든이 작성자 PC 글꼴에 묶이고 실행 환경 글꼴을 고정하지 않음 | **바뀜 → 새 11-02** | 고쳐진 절반: `playwright.visual.config.ts:34-44`가 `FONTCONFIG_FILE`을 `tests/visual/fonts.conf`로 덮고, `tests/visual/fonts.setup.ts`가 화면 비교 전에 실제로 그린 글꼴 4종을 확인한다. visual 6/6 통과. 바깥 `FONTCONFIG_FILE`을 빈 러너 흉내 설정으로 줘도 6/6 통과했다(설정이 덮는다). 빠진 절반: 지난 문서의 최소 개선 방향에 있던 "CI merge job에 패키지 설치 한 줄"이 없다(`08b5ccc` 본문 "CI workflow는 바꾸지 않았다"). 지난 README 13.3은 이 항목을 "충족"으로 닫았다 |
| 1101/11-03 | 허용치 0.2%가 UI-04 회귀(1,146 px)를 통과시킴 | **고쳐짐** | `playwright.visual.config.ts:26` `maxDiffPixels: 50`. **변이:** UI-04 수정(`5d2ed17`)의 `shell.css` 변경을 되돌린 빌드에서 `test:visual`이 넓은 셸 1장을 1,145 px 차이로 실패시켰다(잡음). 나머지 4장과 글꼴 확인은 통과했다 |
| 1101/11-04 | 전략 문서의 "필수 baseline" 목록이 실제 기준선과 다름 | **고쳐짐** | `docs/testing/frontend-platform-testing-strategy.md` 13.4절이 현재 기준선 5장과 "추가할 후보"를 나눠 적는다(`1604ef1`). 골든 파일 5장과 같다 |
| 1101/14.3 | webkit `old-tab-chunk-recovery.spec.ts` 간헐 실패(preload 경고) | **고쳐짐** | `tests/e2e/old-tab-chunk-recovery.spec.ts:88-113`이 WebKit에서만, 빠진 두 페이지가 정적으로 import하는 청크의 preload 경고만 허용한다(`267c724`). 허용 청크 이름은 각 빌드의 `.vite/manifest.json`에서 구한다. 이번 실행: 전체 e2e에서 통과. clone에서 webkit만 20회 반복(workers 4)해 20/20 통과(3.1분, loadavg 38→71) |
| 1101/14.6 남은 것 | 접근성 e2e가 생성 기능 라우트를 Envelope 불일치 오류 화면으로 검사한다(e2e 미실행) | **확인됨 → 새 11-01** | 이번에 생성 기능을 만들어 세 엔진에서 돌렸다(3절 11-01) |
| 0929/11-01 | `tests/system` 기대 문자열이 출력과 달라 FE-GATE-013이 항상 실패 | 고쳐짐 | `tests/system/ci-runner/ci-artifact-contract.test.ts:1281`이 실제 출력 `Exact promotion bundle verification (current): PASS`를 기대한다(`c024182`). clone 실행에서 `passes the downstream CLI for a real finalized exact-five …`가 통과했다 |
| 0929/11-02 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없음 | 남음 | `scripts/drill-runbook.ts:245`, `:350`, `:392`, `:433`의 `providerVerificationRequired: true` 상수 그대로다. `main()`은 runbook ID와 `--release-root`만 받는다(`:518-522`). provider 증거를 넣을 입력이 없다. 거짓 PASS는 내지 않는다(`:538-555`, UNVERIFIED면 종료 코드 3) |
| 0929/11-03 | SW e2e 두 spec의 전제가 소스 문자열 치환에 숨어 있음 | 고쳐짐 | `tests/e2e/support/service-worker-builds.ts:41-53`이 전제 3개와 바꿀 곳을 적는다. 선택 선언은 값과 무관하게 정규식으로 바꾸고(`:73-74`, `setServiceWorkerSelection`), 이미 `ACTIVE`인 선택은 그대로 둔다(`turnOnServiceWorker`). spec 머리 주석이 네 번째 전제(`CHANGED_ROUTE_SOURCE`)를 적는다(`service-worker-update.spec.ts:28-33`). SW spec 두 개는 이번에 chromium·webkit 통과, firefox는 quarantine |
| 0929/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(코드 기준) | `scripts/test-performance.ts`, `scripts/lib/performance-budgets.ts`는 `d99301b` 뒤로 바뀌지 않았다. 이번에 다시 재지 않았다. 실측은 영역 15 범위다 |
| 0929/11-05 | 규모 기준선에 소스 커밋이 없음 | 고쳐짐 | `config/scale/feature-shape-growth.json:16` `"commit": "373b27b…"`(`41e7962`). 다만 그 측정 뒤 87커밋에서 `src` 158파일이 바뀌었다(V2 경로 삭제 등). 기준선이 지금 코드를 대표하는지는 다시 재야 안다(미검증) |
| 0929/11-07 | 두 빌드 helper가 두 벌이고, SW 쪽은 실패 시 복사본을 남김 | 바뀜(일부 남음) | 고쳐진 것: SW helper도 준비 실패 때 임시 폴더를 지운다(`service-worker-builds.ts:226`). 남은 것: 복사 제외 목록이 다르다(`fixture-builds.ts:23`에만 `.tmp`). `run`(`fixture-builds.ts:54`, `service-worker-builds.ts:173`)과 한 번 치환(`editOnce` `fixture-builds.ts:42`, `replaceOnce` `service-worker-builds.ts:107`)이 두 벌이다. 일반 서버 `startBuildServer`(`service-worker-builds.ts:268`)를 SW와 무관한 spec 2개가 가져다 쓴다(`old-tab-chunk-recovery.spec.ts:11`, `boot-module-failure.spec.ts:10`). 결함으로 새로 올리지 않았다(5절 끝 R-1) |
| 0929/11-08 | drill "상수 판정 금지" 검사가 옛 모양(`true`)만 찾음 | 남음 | `tests/unit/runbook-drill.test.ts:122-127` 정규식 3개 그대로다. drill은 이제 문자열 판정(`verdict()`, `scripts/drill-runbook.ts:129-131`)을 쓴다. **변이:** `:238`의 `verdict(await builtAssetsPresent(context.root))`를 상수 `"PASS"`로 바꾸자 이 검사는 통과했다(놓침). 같은 변이를 동작 테스트 `FE-RB-002 fails when the build lost its JavaScript assets`가 잡았다. 그래서 지금 피해는 작다 |
| 0929/11-09 | 규모 tier 실행 로그가 커밋돼 있음 | 남음 | `git ls-files 'artifacts/**/*.log'` 63개. `.gitignore`에 `*.log` 규칙이 없다 |
| FOLLOW-UP | `resumable-upload.spec.ts` 포트 하드코딩 | 남음 | `tests/browser-capabilities/resumable-upload.spec.ts:7` `PAGE_ORIGIN = "http://127.0.0.1:4174"`. 설정 포트(`playwright.capabilities.config.ts`의 `baseURL`)와 같아서 동작한다 |
| FOLLOW-UP | SW update spec의 route chunk 변경을 helper 옵션으로 | 바뀜 | 아직 spec 안에서 덧붙인다(`service-worker-update.spec.ts:46-63`). 대신 전제로 문서화했다(위 0929/11-03) |
| FOLLOW-UP | Firefox SW quarantine | 남음(만료 2027-03-31) | `service-worker-update.spec.ts:172`, `service-worker-recovery.spec.ts:84`. 이번 firefox 실행에서 3건 skip. 만료 검사는 `scripts/check-test-evidence.ts:294-303` |
## 3. 이번 발견 (36.3)
심각도 분포: Critical 0 · High 0 · Medium 2 · Low 3. 우선순위: P1 1 · P2 3 · P3 1. 성격: 확인된 결함 4 · 구조적 위험 1.
### 11-01 생성한 기능의 라우트는 접근성 e2e에서 빈 목록이 아니라 Envelope 불일치 오류 화면으로 검사되고, 릴리스 증거는 그 라우트를 "passed"로 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 5, 24, 20, 17 (+30.5, 32.3) |
| 근거 | **spec:** `tests/e2e/accessibility.spec.ts:34-38`은 `session-required` 라우트마다 `http://localhost:8080/api/**`에 `[]`를 답한다. 주석은 "any API answers an empty list"다(`:35`). 통과 조건은 h1이 보이고 로그인 제목이 아닌 것뿐이다(`:42-43`). **생성기:** `scripts/create-feature.ts:488` `access: "session-required"`, `:666-668` `responseEnvelope: "ENVELOPE_V1"`. `[]`는 Envelope가 아니다. 그래서 실행기가 `ENVELOPE_MISMATCH`로 끝낸다. `AsyncSurface`는 terminal-error에서 `role="alert"` 상자를 그린다(`src/presentation/components/async-surface.tsx:157-163`). 페이지 h1(CollectionPage 제목)은 상태와 무관하게 남아서 spec의 통과 조건을 채운다. 참조 기능은 `responseEnvelope`를 선언하지 않아 `[]`가 맞는다. **실행(세 엔진):** worktree에서 `create:feature sample-feature`로 `/sample`을 만들었다. 실험 spec이 접근성 spec과 같은 `[]`를 답하자 세 엔진 모두 경고 상자 "서버 응답 구조가 예상과 다릅니다. 지원 참조: <id>"를 그렸다. 목록 요소 0, 콘솔 오류·경고 0, axe 차단 위반 0이었다. `{success: true, data: [], meta}`를 답하면 "총 0개 항목 / 표시할 항목이 없습니다." 빈 상태가 나왔다. 항목 2개를 답하면 목록 2줄이 나왔다. 원래 spec의 `@a11y /sample`은 세 엔진 모두 통과했다(54/54). **변이:** 생성 페이지에 빈·성공 상태에서만 보이는 이름 없는 버튼(axe `button-name`, critical)을 넣고 e2e 전체를 돌렸다. 원래 spec의 `@a11y /sample`은 firefox·webkit에서 통과했다(놓침). chromium은 이 실행에서 호스트의 `net::ERR_NETWORK_CHANGED`로 다른 5개와 함께 실패했다. 변이를 둔 채 다시 돌리자 chromium도 통과했다(놓침, 6절 11번). 같은 실행에서 실험 spec이 Envelope로 답한 화면(빈 목록, 항목 2개)은 세 엔진 모두 axe가 `button-name`을 찾았다(잡음). **문서 주장:** `docs/manual/reference/create-feature.md:76`은 "빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`가 모든 API에 `[]`를 답하기 때문이다"라고 적는다. 지금 동작과 반대다. **증거 파일:** `scripts/write-a11y-report.ts:11-15`는 `scope`를 모든 라우트 ID(`scripts/lib/manual-a11y-evidence.ts:3-5`, 생성 라우트 포함)로 두고 `automatedStatus: "passed"`를 쓴다. **드릴:** `test:feature-scaffold`는 브라우저 테스트를 돌리지 않는다(`scripts/test-feature-scaffold.ts:44-58`, 매뉴얼 `create-feature.md:138`도 그렇게 적는다). 생성기는 기능 전용 e2e spec을 만들지 않는다(생성 파일 21개, 6절) |
| 발생 조건 | `create:feature`로 만든 기능, 또는 descriptor에 `responseEnvelope: "ENVELOPE_V1"`을 적은 기능이 `session-required` 라우트를 가질 때. 짝 백엔드에 붙이는 제품의 기본 경로다 |
| 영향 | FE-GATE-008·009의 자동 접근성 검사가 생성 기능 화면의 빈 상태와 목록을 한 번도 보지 않는다. 그런데 릴리스 증거(`artifacts/tests/a11y.json`)는 그 라우트를 범위에 넣고 "passed"라 적는다. 기능을 고칠 때 목록·빈 상태에 생긴 접근성 회귀를 CI가 놓친다. 템플릿을 받은 모든 제품이 같은 spec을 받는다. 사람이 하는 FE-GATE-028(라우트별 수동 검토)은 남아 있어 출시 전 마지막 확인은 있다 |
| 심각도·우선순위 | Medium · P2 — 거짓 통과 검사가 모든 생성 기능에 복제된다. 다만 기능 동작은 깨지지 않고, 출시 전에 수동 검토 게이트가 있다 |
| 통제·증거 | 목표 M3(라우트의 실제 데이터 상태를 검사) / 확인 M2(검사는 돌지만 오류 화면만 본다) · E3(세 엔진 실행 + 변이) |
| 확실성과 남은 가정 | 오류 화면 검사와 거짓 통과는 실행으로 확정이다. 기존 context에 넣은 생성 기능(`--context`)과 파라미터가 있는 라우트는 돌리지 않았다. 원인이 같으니 결과도 같을 것이다(추론) |
| 결정의 근거 | 5.1절. 전역 `[]` 하나는 참조 기능(DTO 응답)에는 맞고 Envelope operation에는 맞지 않는다. 1101 README 14.6 결정이 "operation 단위 Envelope"를 골랐다(기록된 결정). 그래서 응답 모양은 operation마다 다르다 |
| 이해 비용 | 기능 작성자가 접근성 spec이 자기 라우트를 어떤 상태로 검사하는지 알려면 spec의 전역 mock, 실행기의 Envelope 판정, `AsyncSurface` 분기를 모두 읽어야 한다. 통과 표시만으로는 알 수 없다. 매뉴얼은 반대로 말한다 |
| 최소 개선 방향 | 5.1절 (b). spec이 설치된 descriptor에서 요청 경로와 `responseEnvelope`를 찾아 빈 목록을 그 모양으로 답한다. 그리고 "경고 상자(`role="alert"`)가 없다"를 단언한다. 그러면 다음에 모양이 어긋날 때 통과 대신 실패한다. 매뉴얼 `create-feature.md:76`을 실제 동작에 맞춘다 |
| 대안 비교 | 5.1절 (a)~(d) |
| 단순화의 보존 조건 | 적용 제외 — 단순화가 아니라 검사 보강이다 |
| 비용·부작용 | spec 수십 줄. 참조 기능은 계속 DTO `[]`를 받는다. descriptor를 e2e에서 읽으려면 계약 조립 모듈을 import해야 한다(지금도 `ROUTE_REGISTRY`를 import한다) |
| 재검토 조건 | 참조 기능도 Envelope로 옮기면(1101 README 14.6 "남은 것") 전역 Envelope 응답 하나로 단순화할 수 있다. 생성기가 기능마다 접근성 e2e를 만들기로 하면 (c)를 다시 본다 |
| 완료 기준 | 생성 기능을 만든 상태에서 `@a11y /sample`이 빈 상태 화면을 검사한다. 이번 변이(빈 상태에서만 보이는 이름 없는 버튼)를 넣으면 세 엔진 모두 실패한다. 응답 모양을 일부러 틀리게 하면 axe가 아니라 경고 상자 단언으로 실패한다. 매뉴얼 문장이 동작과 같다 |
| 검증 방법 | `corepack pnpm create:feature sample-feature` 뒤 `corepack pnpm exec playwright test tests/e2e/accessibility.spec.ts -g /sample` 세 엔진. 이번 변이를 다시 넣고 같은 명령 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1101 README 14.6 "남은 것"을 실행으로 확인) |
### 11-02 CI merge job이 시각 테스트 글꼴 패키지를 설치하지 않아, 빈 러너에서는 FE-GATE-008이 코드와 무관하게 `visual-fonts` 단계에서 실패한다 (1101/11-02 남은 절반)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 19, 20, 16, 5 (+30.8) |
| 근거 | **설정:** `tests/visual/fonts.conf`는 `/usr/share/fonts/truetype/noto`, `/usr/share/fonts/opentype/noto`, `/usr/share/fonts/truetype/liberation`만 보게 한다. 디렉터리가 없으면 조용히 건너뛴다(파일 머리 주석). `tests/visual/fonts.setup.ts:19-22`는 필요한 패키지 4개(`fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`)를 안내하며 실패한다. `docs/testing/frontend-platform-testing-strategy.md` 13.4절도 "러너에는 … 패키지가 필요"라고 적는다. **CI:** `.gitea/workflows/quality-gates.yml:68-70`의 브라우저 단계는 `playwright install --with-deps chromium firefox webkit` 한 줄이다. 이 줄은 생성기 `scripts/generate-ci-workflow.ts:195-200`이 쓰고 `check:ci-workflow`가 대조한다. 그래서 workflow 파일만 고치면 `check:ci`가 실패한다. FE-GATE-008은 `test-visual`을 포함한다(`config/ci/gates.json`의 FE-GATE-008 `commandIds`). Playwright 1.62가 Ubuntu 24.04에 까는 글꼴에는 Noto Sans·Noto Sans CJK가 없다(`fonts-noto-color-emoji`만 `truetype/noto`에 들어간다). **실험:** `fonts.conf`의 세 디렉터리를 Playwright 의존 글꼴 디렉터리(freefont, ipafont-gothic, liberation, tlwg, unifont, wqy와 emoji만 든 noto)로 바꿔 빈 러너를 흉내 냈다. `fc-match`로 그 설정이 읽히는 것을 먼저 확인했다(sans·한글 모두 WenQuanYi Zen Hei). `test:visual` 결과: `visual-fonts`가 실패했다(받은 값 latin·korean·korean-800 = "WenQuanYi Zen Hei", code = "Liberation Mono"). 메시지에 설치 명령이 나왔다. 화면 5장은 "did not run"이었다(8초). 첫 시도는 실험 파일의 XML 주석에 `--`가 들어가 fontconfig가 파일을 거부하고 호스트 설정으로 돌아가 6/6 통과했다. 그 결과는 버렸다 |
| 발생 조건 | Noto Sans·Noto Sans CJK가 없는 러너에서 FE-GATE-008을 돌릴 때. `ubuntu-latest` 러너 이미지의 글꼴 구성은 U-1이라 미확인이다 |
| 영향 | CI를 켜면 FE-GATE-008이 코드와 무관하게 실패할 가능성이 높다. 실패는 이제 픽셀 diff가 아니라 설치 안내로 나와서 원인은 바로 안다. 그래도 PR마다 막힌다. 팀은 러너를 손으로 고치거나 시각 검사를 끄게 된다 |
| 심각도·우선순위 | Medium · P1 — 지원하는 CI 조건에서 merge 게이트가 코드와 무관하게 실패한다. 지난 라운드 11-02와 같은 조정 규칙(CI 꺼짐, 수정 비용 작음)을 적용했다 |
| 통제·증거 | 목표 M3 / 확인 M2(작성자 PC에서만 M3) · E3(글꼴 디렉터리 변이 실험). 실제 러너는 미확인 |
| 확실성과 남은 가정 | 글꼴이 없을 때 실패한다는 것은 실험으로 확정이다. 실제 러너 이미지에 Noto가 이미 있을 가능성은 남는다(U-1) |
| 결정의 근거 | 5.2절. 1101/11-02의 결정 (c′)는 "글꼴은 OS 패키지로 설치하고 `fonts.conf`가 그 디렉터리만 보게 한다"였다. 설치 쪽이 빠졌다 |
| 이해 비용 | 적용 제외 — 실패 문구가 설치 명령을 보여 주므로 원인을 찾는 비용은 작다. 남은 것은 CI 설정의 누락이다 |
| 최소 개선 방향 | `scripts/generate-ci-workflow.ts:195-200`의 `browser-install` 단계에 `sudo apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`을 더하고 `generate:ci-workflow`로 workflow를 다시 쓴다. 패키지 목록은 `fonts.setup.ts`의 안내와 한 곳에서 읽게 한다 |
| 대안 비교 | 5.2절 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 생성기 한 줄. CJK 패키지는 수십 MB라 브라우저 job 설치 시간이 는다. 패키지 이름으로 고정하므로 배포판이 바뀌면 글자 모양이 바뀔 수 있다(1101/11-02 재검토 조건 그대로) |
| 재검토 조건 | 러너를 job container로 고정하게 되면 이미지에 글꼴을 넣는다(5.2 (c)). macOS·Windows 개발자가 골든을 갱신해야 하면 컨테이너 방식이 필요하다 |
| 완료 기준 | 생성된 workflow의 브라우저 단계가 글꼴 패키지를 설치한다. `check:ci-workflow`가 통과한다. Noto가 없는 깨끗한 Ubuntu 24.04 컨테이너에서 그 단계 뒤 `test:visual`이 6/6 통과한다 |
| 검증 방법 | 이번 실험처럼 글꼴 디렉터리를 바꿔 실패를 확인하고, 패키지 설치 뒤 통과를 확인한다. 가능하면 러너 1대에서 FE-GATE-008 1회 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1101/11-02 남은 절반) |
### 11-03 `test:system`의 provider 테스트 10개(선언 8개)가 10초 상한에 묶여 부하에서 시간 초과하고, 하나만 골라 돌리면 첫 테스트가 기반 fixture 빌드를 떠안아 항상 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 20, 8 |
| 근거 | **기록된 의도:** `tests/system/ci-runner/ci-artifact-contract.test.ts:58-64`는 provider 묶음에 30초 예산(`PROCESS_HEAVY_TIMEOUT_MS`)을 두고 이유를 적는다. "10s default is sized for pure-JS unit tests". **코드:** 같은 describe의 테스트 선언 8개(실행 케이스 10개)는 여전히 10초다(`:692`, `:733`, `:899`, `:939`, `:1030`, `:1051`, `:1068` `it.each` 2개, `:1113` `it.each` 2개 — 줄 번호는 테스트 시작, 상한은 각 테스트 끝의 `10_000`). 상수를 쓰는 곳은 cgroup 테스트 하나다(`:854`). 기반 fixture(`build:release-candidate` 실행)는 처음 `createProviderFixture()`를 부른 테스트 안에서 만든다(`:2056-2059`, `:2176-2230`). 매 테스트도 그 복사본을 `cp`로 복사한다(`:2059`). **실행:** clone 전체 실행에서 `kills descendants … timeout termination`이 10,116 ms로 시간 초과했다(112개 중 유일한 실패, loadavg 13~15). `-t 'kills descendants'`로 두 테스트만 8번 돌렸다. 첫 테스트(`output`)는 8/8 실패했다(17~32초, 기반 빌드를 떠안음). 두 번째(`timeout`)는 6/8 통과, 2/8 시간 초과였다(10,359·10,363 ms, loadavg 27~33). 통과한 실행도 4.8~10.2초로 상한에 붙어 있다 |
| 발생 조건 | (1) 호스트가 바쁠 때 전체 `test:system`. (2) provider 테스트 하나를 `-t`로 골라 돌릴 때, 그 테스트가 10초짜리면 항상 |
| 영향 | FE-GATE-013(merge)이 코드와 무관하게 가끔 빨개진다. 실패 메시지는 "Test timed out"뿐이라 샌드박스 회귀와 구분하기 어렵다. 실패한 테스트 하나를 다시 돌려 보는 개발자는 매번 실패를 본다. 지난 라운드 완료 기준도 `-t`로 표적 실행을 적었다 |
| 심각도·우선순위 | Low · P2 — 게이트 결과를 흔들지만 데이터·보안 피해는 없다. 고치는 비용이 몇 줄이다 |
| 통제·증거 | 목표 M3 / 확인 M2(부하가 낮을 때만 결정적) · E3(전체 1회 + 표적 8회) |
| 확실성과 남은 가정 | 시간 초과와 표적 실행 실패는 재현했다. CI 러너의 부하에서 얼마나 자주 나는지는 모른다. 이 호스트는 다른 리뷰어 때문에 평소보다 훨씬 바빴다 |
| 결정의 근거 | 적용 제외 — 파일이 이미 정한 예산을 일부 테스트가 쓰지 않는 단순 누락이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 선언 8개의 `10_000`을 `PROCESS_HEAVY_TIMEOUT_MS`로 바꾼다. 기반 fixture는 provider describe의 `beforeAll`(자기 시간 상한)에서 만든다 |
| 대안 비교 | 적용 제외 — 이미 기록된 예산을 따르는 수정이다. 전역 상한을 올리는 안은 파일 주석이 이미 버렸다("would hide a genuinely hung test") |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 실제로 멈춘 provider 테스트가 실패하기까지 최대 30초가 걸린다 |
| 재검토 조건 | 러너에서 30초도 넘는 실행이 나오면, 상한을 늘리기 전에 기반 fixture 복사를 줄인다 |
| 완료 기준 | `-t 'kills descendants'`가 단독으로 통과한다. loadavg 20 이상에서 `test:system` 전체 5회가 모두 통과한다 |
| 검증 방법 | 이번 반복 스크립트(6절)를 다시 돌린다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-04 `test:system`은 git worktree에서 provider 테스트 16개가 `.git` 때문에 실패하는데, 사전 점검은 PASS라고 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 8, 10, 26 |
| 근거 | `scripts/run-and-validate-provider.ts:277-282`는 작업 폴더에 `.git`이 있으면 그 자리에 `--tmpfs`를 건다. 테스트 fixture는 현재 폴더를 통째로 복사한다(`tests/system/ci-runner/ci-artifact-contract.test.ts:2176-2190`). git worktree에서는 `.git`이 디렉터리가 아니라 `gitdir:` 한 줄짜리 파일이다. 그래서 bwrap이 `Can't mkdir /tmp/ci-provider-upload-*/.git: Not a directory`로 끝난다. `scripts/check-system-test-prerequisites.ts`는 bwrap·systemctl·tar·cgroup만 본다. **실행:** worktree에서 `corepack pnpm test:system` → "System test prerequisites: PASS" 뒤 16 failed / 96 passed(58초). 16개는 모두 `candidate archive and provider upload boundaries` 묶음이고 메시지가 같다. 같은 커밋의 clone에서는 111/112(1건은 11-03) |
| 발생 조건 | `git worktree`나 `.git` 파일을 쓰는 checkout(서브모듈 포함)에서 `test:system`을 돌릴 때. 이 repo의 리뷰 절차(루트 `CLAUDE.md`)는 영역마다 worktree를 쓴다. `actions/checkout`의 checkout은 디렉터리라 CI는 해당하지 않는다 |
| 영향 | worktree에서 일하는 개발자·에이전트가 샌드박스 경계 테스트 16개 실패를 본다. 실패가 보안 회귀처럼 보인다. 지난 라운드도 "worktree에서 `test:system`이 돌지 않는다"고만 적었다(1101/11 6절 관점 20). provider는 실패로 닫히므로 정보가 새지는 않는다 |
| 심각도·우선순위 | Low · P3 — 개발 편의 문제다. 운영 경로와 CI에는 영향이 없다 |
| 통제·증거 | 목표 M3(전제가 없으면 사전 점검이 이유를 말함) / 확인 M1 · E3(worktree·clone 실행) |
| 확실성과 남은 가정 | 원인은 실행 메시지와 코드로 확정이다. `.git` 파일을 읽기 전용으로 가리는 수정이 provider 경계 테스트의 다른 단언과 맞는지는 확인하지 않았다 |
| 결정의 근거 | 적용 제외 — 지원 범위를 사전 점검에 적는 단순 보강이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 둘 중 하나. (1) `check-system-test-prerequisites.ts`가 `.git`이 파일이면 "clone에서 돌린다"는 안내로 실패한다. (2) 샌드박스가 `.git`이 파일이면 파일 자리에 빈 파일을 읽기 전용으로 겹친다. (1)이 작다 |
| 대안 비교 | 적용 제외(두 안 모두 몇 줄이고 계약을 바꾸지 않는다) |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | (1)은 worktree에서 `test:system`을 아예 못 돌린다는 사실을 굳힌다 |
| 재검토 조건 | CI 러너가 worktree 방식 checkout을 쓰게 되면 (2)가 필요하다 |
| 완료 기준 | worktree에서 `test:system`이 16개 실패 대신 사전 점검 단계에서 이유와 함께 멈추거나, 112개가 통과한다 |
| 검증 방법 | worktree와 clone에서 `corepack pnpm test:system` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 11-05 IndexedDB 차단 업그레이드 capability 테스트가 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려 해서, 전체 실행에서 두 엔진이 실패했다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(간헐 실패를 한 번 관찰) |
| 관련 관점 | 10, 12, 21, 8 |
| 근거 | `tests/browser-capabilities/indexeddb-runtime.spec.ts:982` 테스트는 다른 페이지가 v1 연결을 쥔 상태에서 v2 runtime을 `blockedTimeoutMs` 500으로 시작한다(`:1023`, helper `:21-27`의 기본값은 1,000). 그다음 `expect.poll(lifecycleStatus)`로 `{kind: "BLOCKED", …}`를 기다린다(`:1024-1030`). 이 상태는 500 ms 뒤 `CLOSED/NOT_OPENED`로 바뀐다. 폴링 한 번은 `page.evaluate` 왕복이다(`:230-241`). 그래서 부하로 왕복이 늦으면 첫 관찰 전에 창이 닫힌다. 바로 뒤의 `settleLifecycleRuntime` 단언(`:1032-1044`)이 이미 `opened.error.code: "BLOCKED"`를 확인하므로, 전이 상태 폴링 없이도 차단은 검증된다. **실행:** `test:browser-capabilities` 전체(세 엔진, 63개)에서 61 통과, 이 테스트만 chromium·webkit에서 실패했다. 받은 값은 `{kind: "CLOSED", reason: "NOT_OPENED"}`이었다(loadavg 18~29, 54초). 같은 테스트만 엔진마다 6번(합계 18번) 돌리면 18/18 통과했다(loadavg 23~34) |
| 발생 조건 | 전체 capability 실행처럼 worker가 많고 호스트가 바쁠 때. 단독 실행에서는 재현하지 못했다 |
| 영향 | FE-GATE-008이 코드와 무관하게 가끔 빨개진다. 실패 diff가 "차단이 안 됐다"처럼 읽혀 IndexedDB 회귀로 오해하기 쉽다. 저장소 동작 자체의 결함은 아니다 |
| 심각도·우선순위 | Low · P2 — 피해는 게이트 신뢰도에 한정된다. 수정은 몇 줄이다 |
| 통제·증거 | 목표 M3 / 확인 M2 · E3(전체 1회 실패 + 단독 18회 통과). 빈도는 미확인 |
| 확실성과 남은 가정 | 실패 모양(받은 값이 다음 상태)과 코드 순서로 원인은 거의 확실하다. 전체 실행을 여러 번 돌려 빈도를 재지는 않았다. 이 실행은 inotify 한도 때문에 `CHOKIDAR_USEPOLLING=true`로 dev 서버를 띄웠다(6절 16번). 폴링 감시가 CPU를 더 썼을 수 있다 |
| 결정의 근거 | 적용 제외 — 테스트가 지킬 계약(차단되면 열지 않고 닫는다)은 그대로 두고 관찰 방법만 바꾸는 수정이다 |
| 이해 비용 | 적용 제외 |
| 최소 개선 방향 | 전이 상태 폴링(`:1024-1030`)을 없애고 `settleLifecycleRuntime`의 `BLOCKED` 결과로 판정한다. 전이 상태를 꼭 보려면 runtime이 상태 변화를 기록하게 하고 그 기록을 읽는다(1101/11-01의 trace와 같은 방식) |
| 대안 비교 | 적용 제외 — `blockedTimeoutMs`만 늘리는 안은 창을 넓힐 뿐 경쟁을 남긴다 |
| 단순화의 보존 조건 | "다른 context가 쥐고 있으면 v2는 열지 않고 `RELOAD_OTHER_CONTEXTS`로 닫는다", "차단이 풀린 뒤 늦게 열린 연결을 닫는다", "삭제가 막히지 않는다" 세 단언은 남긴다 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | runtime이 상태 변화 이벤트를 공개 계약으로 내보내게 되면 그 이벤트를 단언한다 |
| 완료 기준 | 전체 `test:browser-capabilities`를 loadavg 20 이상에서 5회 돌려 이 테스트가 모두 통과한다 |
| 검증 방법 | `corepack pnpm test:browser-capabilities` 반복 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 이유와 근거 |
|---|---|---|---|
| 1 | 코드 성숙도 | > | src 담당 영역(01~09) |
| 2 | 구조적 성숙도 | > | 12·16 |
| 3 | 변경 용이성 | P | SW harness 전제가 문서화되고 선택 값과 무관하게 동작한다(0929/11-03 고쳐짐). 기능을 추가하면 접근성 spec이 자동으로 그 라우트를 돈다. 하지만 응답 모양을 모른다(11-01) |
| 4 | 인지 부하 | P | 접근성 spec이 생성 라우트를 무슨 상태로 검사하는지 알려면 mock·실행기·AsyncSurface를 함께 읽어야 한다(11-01). 빌드 helper 두 벌(0929/11-07) |
| 5 | 위험 가시성 | P | 시각 테스트는 글꼴이 다르면 설치 안내로 실패한다(1101/11-02 고쳐진 절반). 매뉴얼은 생성 라우트가 빈 상태로 검사된다고 말하고, 증거 파일은 "passed"라고 적는다(11-01) |
| 6 | 실패 성숙도 | O | 429 재시도, 스키마 위반, 청크 누락 뒤 1회 reload, 부트 오류 화면, 깨진 SW 해제가 이번 실행에서 통과했다(SW는 chromium·webkit, firefox quarantine) |
| 7 | 운영 성숙도 | P | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(0929/11-02 남음) |
| 8 | 디버깅 가능성 | P | trace `retain-on-failure`. 글꼴 실패는 설치 명령을 보여 준다. 시간 초과는 "Test timed out"뿐이다(11-03). worktree의 16개 실패는 사전 점검이 PASS라 원인을 숨긴다(11-04) |
| 9 | 유지보수 성숙도 | P | helper 두 벌(0929/11-07), 커밋된 로그 63개(0929/11-09), 규모 기준선이 87커밋 전 측정(0929/11-05 뒤 남은 것) |
| 10 | 테스트 성숙도 (깊게) | P | 강점: e2e 187 통과·0 실패, visual 6/6, storybook 1/1, webkit 구 탭 20/20(loadavg 최대 71), 재시도 0, 엄격 콘솔 fixture, 영역 vitest 171/171, UI-04 변이를 시각 비교가 잡음(모두 이번 실행). 약점: 생성 라우트의 접근성 검사가 오류 화면을 본다(11-01), provider 테스트 시간 상한과 순서 의존(11-03), worktree 실행 불가(11-04), 전이 상태 폴링(11-05), drill 원장 검사가 상수 `"PASS"`를 놓친다(0929/11-08) |
| 11 | 데이터 성숙도 | - | 이 영역에 데이터 이관·보관 경로가 없다 |
| 12 | 동시성 성숙도 | P | 두 페이지·두 context로 BroadcastChannel, localStorage 대체 경로, IndexedDB versionchange, 다른 탭 reconcile을 확인하는 capability 테스트가 세 엔진에서 통과했다(이번 실행 61/63). 차단 업그레이드 테스트는 500 ms 전이 상태를 폴링해 부하에서 흔들린다(11-05) |
| 13 | 확장성 (깊게) | P | 기능을 하나 추가하면 e2e가 그 라우트를 자동으로 포함한다(접근성 spec). 생성 기능을 넣은 상태에서 e2e 전체를 돌려도 다른 spec은 깨지지 않았다(6절 11번). 규모 기준선은 커밋을 적지만 87커밋 전 측정이다. 기능 성장 재측정과 main 이상 tier는 돌리지 않았다 |
| 14 | 성능 성숙도 (깊게) | P | 테스트 실행 비용은 작다(6.3절). lab 성능 게이트의 판정 뒤집힘은 코드가 그대로다(0929/11-04, 이번 미실행, 영역 15) |
| 15 | 보안 성숙도 | > | 13(`tests/system`의 샌드박스 내용). 이 영역은 테스트 결정성(11-03)과 실행 위치(11-04)만 다룬다 |
| 16 | 의존성 성숙도 | P | `@playwright/test` 1.62.0 고정, 브라우저는 패키지가 고정한다. 시각 테스트가 기대는 OS 글꼴 패키지를 CI가 설치하지 않는다(11-02) |
| 17 | API / Contract | > | 07. 이 영역 관련: e2e의 API 응답 모의가 operation의 응답 계약(Envelope)을 따르지 않는다(11-01) |
| 18 | 배포 성숙도 (깊게) | P | 구 탭 청크 복구는 세 엔진 통과, webkit 20/20. SW A→B 업데이트와 이전 캐시 응답은 chromium·webkit 통과(이번 실행). provider 전환은 drill로 기록할 수 없다(0929/11-02). CI에 글꼴이 없어 merge 게이트가 막힌다(11-02) |
| 19 | 설정 성숙도 | P | 시각 테스트 실행 환경이 설정(`fonts.conf`)에 들어왔다. 러너 쪽 설치가 빠졌다(11-02). `resumable-upload.spec.ts:7` 포트 하드코딩 남음 |
| 20 | 개발자 경험 | P | spec 하나도 전체 빌드를 하지만 빌드가 짧다. worktree에서 `test:system`이 돌지 않는다(11-04). provider 테스트 하나만 골라 돌리면 실패한다(11-03) |
| 21 | Guardrail 성숙도 | P | FE-GATE-013의 결정적 실패 2건(1101/11-01, 0929/11-01)이 고쳐졌다. 남은 것: 생성 라우트에 거짓 통과(11-01), 빈 러너에서 FE-GATE-008 실패(11-02), FE-GATE-013 부하 흔들림(11-03), FE-GATE-008 capability 부하 흔들림(11-05). `forbidOnly`·quarantine 만료 검사는 동작한다. 지난 라운드 X에서 P로 올렸다 |
| 22 | 추상화 성숙도 | P | 두 빌드 helper(0929/11-07). 나머지 helper는 얇다 |
| 23 | 일관성 | P | 공용 엄격 fixture를 모든 브라우저 spec이 쓴다. provider 테스트 시간 상한이 파일 안에서 갈린다(11-03). helper 두 벌의 제외 목록이 다르다 |
| 24 | 네이밍 / 의미 | P | 접근성 spec 주석 "any API answers an empty list"와 매뉴얼 문장이 실제 동작과 다르다(11-01). "keeps no constant recovery verdict"는 실제 검사보다 넓다(0929/11-08) |
| 25 | 조직 확장성 | > | 14 |
| 26 | Ownership 성숙도 | P | quarantine에 owner·expires가 있다. 골든 갱신 환경이 문서(13.4절)에 적혔다. `test:system`을 어디서 돌려야 하는지는 사전 점검이 말하지 않는다(11-04) |
| 27 | 삭제 가능성 | P | 커밋된 로그를 다운스트림이 지워야 한다(0929/11-09). 시각 테스트는 production 코드 변경 없이 뗄 수 있다 |
| 28 | 회복 가능성 (깊게) | P | 깨진 SW를 `REMOVE_REGISTRATION`으로 해제하는 흐름(chromium·webkit)과 구 탭 청크 복구(세 엔진)가 통과했다. provider 전환 뒤 smoke를 증거로 넣을 방법이 없다(0929/11-02). 이전 release 재검증 경로의 system test는 이제 통과한다(1101/11-01 고쳐짐) |
집계(적용 22개): 충족 1(6) · 부분 충족 21 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 5(1, 2, 15, 17, 25).
지난 라운드와 달라진 곳: 21은 X → P(FE-GATE-013의 결정적 실패 2건이 고쳐짐). 12는 O → P(11-05). 10·13은 이번에 생성 기능을 넣고 돌려 근거가 바뀌었다(11-01).
## 5. 설계 선택 설명 (41절)
### 5.1 접근성 e2e가 기능 API에 무엇을 답할 것인가 (11-01)
1. **무엇이 필요한가:** 모든 라우트가 실제 데이터 상태(빈 목록 포함)에서 WCAG 차단 위반 없이 그려지는지 merge 단계에서 확인한다. 소비자는 PR 작성자, 릴리스 증거(`artifacts/tests/a11y.json`), 템플릿을 받은 제품이다. 기능 데이터의 내용은 이 spec의 주제가 아니다(spec 주석 `:35`).
2. **지킬 성질:** 라우트마다 오류가 아닌 데이터 상태를 검사한다. 응답 모양이 어긋나면 통과하지 않고 실패한다. 기능을 추가해도 spec을 고치지 않는다.
3. **현재 보장:** 라우트를 자동으로 모두 돈다(`ROUTE_REGISTRY` 순회, `accessibility.spec.ts:24-25`). 보호 라우트는 로그인 뒤 검사한다(`:40-43`). **보장하지 않는 것:** 응답 모양. 전역 `[]` 하나는 DTO operation에만 맞는다. 오류 화면인지도 확인하지 않는다(11-01 실험).
4. **대안:**
- (a) 현상 유지.
- (b) spec이 설치된 descriptor에서 요청 경로와 `responseEnvelope`를 찾아 빈 목록을 그 모양으로 답한다. 그리고 경고 상자(`role="alert"`)가 없다고 단언한다.
- (c) 생성기가 기능마다 접근성 e2e를 만들고, 전역 spec은 플랫폼 라우트만 돈다.
- (d) 전역 응답을 Envelope `{success: true, data: []}`로 바꾼다.
5. **대안별 비용:**
| 대안 | 얻는 것 | 비용·한계 |
|---|---|---|
| (a) | 비용 0 | 생성 라우트는 오류 화면만 검사한다. 증거는 "passed"다(11-01) |
| (b) | 참조 기능(DTO)과 생성 기능(Envelope)이 모두 빈 상태로 검사된다. 모양이 어긋나면 실패한다. 수정이 한 곳이다 | spec 수십 줄. URL을 `pathTemplate`에 맞추는 작은 매칭 코드가 필요하다 |
| (c) | 기능마다 빈·목록·오류 상태를 정확히 검사할 수 있다 | 생성 파일이 하나 는다. 기능마다 세 엔진 e2e 시간이 는다. 전역 spec과 범위를 나누는 규칙이 하나 더 생긴다 |
| (d) | 한 줄 | 참조 기능(DTO)이 거꾸로 불일치가 된다. 참조 라우트 4개가 오류 화면 검사로 바뀐다. 참조 기능을 Envelope로 옮긴 뒤에만 맞다 |
6. **현재 조건에서의 판단:** (b)가 타당하다. 1101 README 14.6 결정이 응답 모양을 operation 단위로 정했다. 그래서 e2e 응답도 operation 단위로 정하는 것이 같은 단위다. 경고 상자 단언을 함께 넣어야 다음 어긋남을 통과 대신 실패로 드러낸다(리뷰어 판단).
7. **재검토 조건:** 참조 기능을 Envelope로 옮기면 (d)로 단순화한다. 생성기가 목록 외 화면(폼·상세)을 만들기 시작하면 (c)를 다시 비교한다.
### 5.2 시각 테스트 글꼴을 CI 러너에 어떻게 맞출 것인가 (11-02)
1. **무엇이 필요한가:** FE-GATE-008의 시각 비교가 CI 러너에서 작성자 PC와 같은 판정을 낸다.
2. **지킬 성질:** 같은 커밋이면 어느 지원 호스트에서도 같은 판정이다. 글꼴이 없으면 픽셀 diff가 아니라 설치 안내로 실패한다(이미 보장된다).
3. **현재 보장:** `fonts.conf`와 `fonts.setup.ts`가 로컬에서 글꼴을 고정하고 확인한다. 바깥 `FONTCONFIG_FILE`도 덮는다(6절 실험 3). **보장하지 않는 것:** 러너에 글꼴이 설치되는 것. workflow와 생성기에 설치 단계가 없다.
4. **대안:** (a) 현상 유지, 러너 관리자가 손으로 설치. (b) 생성기의 `browser-install` 단계에 `apt-get install` 한 줄. (c) job container(Playwright 공식 이미지 + 글꼴)로 러너를 고정. (d) `ci:gate`가 FE-GATE-008 전에 패키지를 설치.
5. **대안별 비용:** (a) 비용 0. 러너마다 숨은 수동 상태가 생긴다. (b) 생성기 한 줄과 설치 시간(CJK 패키지 수십 MB). 패키지 이름 고정이라 배포판이 바뀌면 흔들릴 수 있다. (c) 가장 강하게 고정한다. 러너의 컨테이너 지원(U-1 미확인)과 이미지 관리가 필요하다. (d) 게이트 스크립트가 시스템 패키지를 설치하면 개발자 PC에서도 sudo를 요구한다. 게이트가 환경을 바꾸는 부작용이다.
6. **현재 조건에서의 판단:** (b)가 타당하다. 1101/11-02가 고른 (c′)의 남은 절반이다. 러너 환경을 모르는 지금 가장 작은 변경이다.
7. **재검토 조건:** 러너가 job container를 지원한다는 것이 확인되면 (c). 러너에서 골든이 흔들리면 (c). 제품이 웹폰트를 싣게 되면 고정 대상이 그 웹폰트로 줄어든다.
### 5.3 WebKit의 preload 경고를 어떻게 다룰 것인가 (`267c724`, 1101/14.3)
1. **무엇이 필요한가:** 구 탭 청크 복구 테스트가 엔진 경고 때문에 가끔 실패하지 않아야 한다. 그러면서 엄격 콘솔 검사는 다른 경고를 계속 잡아야 한다.
2. **지킬 성질:** 테스트가 일부러 지운 청크의 결과만 허용한다. 다른 청크와 다른 브라우저의 같은 경고는 실패한다. 재시도로 흔들림을 숨기지 않는다(retries 0).
3. **현재 보장:** `old-tab-chunk-recovery.spec.ts:88-113`. WebKit에서만, 빠진 두 페이지가 정적으로 import하는 청크(각 빌드의 `.vite/manifest.json`에서 계산)의 경고만 허용한다. 이번 실행 20/20(loadavg 38~71). 커밋 본문의 RED는 loadavg 15~17에서 30회 중 2회 실패였다. 이번 조건이 훨씬 바쁘다. **보장하지 않는 것:** Vite의 실제 preload 목록(`__vite__mapDeps`)과 manifest가 갈라지는 경우. 그때는 덮이지 않고 실패하는 쪽으로 틀린다. WebKit 문구가 바뀌어도 실패한다.
4. **대안:** (a) 이번 방식. (b) `build.modulePreload`를 끈다. (c) B를 배포하기 전에 3초 넘게 기다린다. (d) 엄격 fixture에서 이 경고를 전역으로 허용한다. (e) 재시도로 흡수한다.
5. **대안별 비용:** (a) spec 약 25줄. (b) 모든 lazy 화면 전환에 왕복이 하나 는다. 테스트 때문에 제품 성능을 깎는다. (c) WebKit 내부 상수(3초)에 묶인 고정 대기다. 원인을 설명하지 않는다. (d) 다른 spec의 진짜 불필요한 preload까지 덮는다. (e) retries 0 정책과 반대이고 flaky를 숨긴다(관점 10).
6. **현재 조건에서의 판단:** (a) 유지가 타당하다. 허용 범위가 원인과 같은 크기이고, 틀릴 때 덮이지 않는 쪽으로 틀린다.
7. **재검토 조건:** Vite를 올려 preload 목록을 만드는 방식이 바뀌면 이 spec이 먼저 실패할 것이다. 그때 계산 방식을 다시 본다. 다른 spec에서도 같은 경고가 나오기 시작하면 manifest 계산을 공용 helper로 옮긴다.
### 5.4 리팩토링 후보 (결함으로 올리지 않은 것)
| 후보 | 무엇을 왜 | 보존해야 할 동작·실패 계약 |
|---|---|---|
| R-1 두 빌드 helper 통합(0929/11-07 남은 것) | `service-worker-builds.ts`가 `prepareFixtureBuilds`를 쓰고 SW 선택·probe 치환만 `edit`로 넘긴다. `startBuildServer`를 공용 파일로 옮긴다. `run`·한 번 치환·제외 목록 중복이 없어진다 | 작업 트리와 `dist`를 건드리지 않는다. 빌드 ID 주입. `edit`가 그 빌드 직전에 돌고 다음 빌드에 남는 순서. 준비 실패 시 임시 폴더 삭제. 치환 대상이 정확히 1회일 때만 진행 |
| R-2 provider 기반 fixture를 `beforeAll`로(11-03) | 처음 부른 테스트가 빌드를 떠안는 순서 의존을 없앤다 | 기반 fixture는 실행당 한 번. 각 테스트는 자기 복사본을 쓴다. 실행 뒤 임시 폴더 정리(`temporaryRoots`) |
## 6. 실험·실행 기록
### 6.1 어디서 무엇을 돌렸나
- 리뷰 worktree(`e40684b` detached, `corepack pnpm install --frozen-lockfile` 9.9초)에서 e2e·visual·생성 기능 실험을 돌렸다. e2e·visual 설정의 webServer가 매번 `corepack pnpm build`를 한다.
- `test:system`은 worktree에서 돌지 않아(11-04) scratchpad에 `git clone --no-hardlinks`로 만든 clone(같은 `e40684b`, `.git`이 디렉터리)에서 돌렸다. storybook·webkit 반복도 그 clone(깨끗한 트리)에서 돌렸다.
- 무거운 실행은 모두 공용 잠금으로 감쌌다. 잠금 대기 때문에 실행 사이 간격이 길다. 호스트에는 다른 영역 리뷰어가 함께 돌아 loadavg가 계속 높았다.
- 실험 파일(`tests/e2e/zz-review-sample.spec.ts`, 생성 기능, 변이)은 끝난 뒤 `git checkout -- .`과 `git clean -fd`(이 문서 폴더 제외)로 지웠다. 마지막 `git status`에는 이 문서 폴더만 남았다. 커밋하지 않았다.
### 6.2 실행 표
| # | 명령·실험 | 결과 | 시간·조건 |
|---|---|---|---|
| 1 | `corepack pnpm test:e2e`(4개 프로젝트) | chromium 63, chromium-compact 1, firefox 60 + 3 skip, webkit 63. 187 통과·0 실패·재시도 0 | 벽시계 94초. 테스트 시간 합계 chromium 116초, firefox 181초, webkit 261초. loadavg 12→31 |
| 2 | `corepack pnpm test:visual` | 6/6(글꼴 확인 1 + 화면 5) | 12초. loadavg 17~20 |
| 3 | `corepack pnpm test:storybook`(clone) | 1/1 | 19초(storybook 빌드 포함). loadavg 16~19 |
| 4 | `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts tests/scale` | 26파일 171개 통과 | 9.7초. loadavg 8~15 |
| 5 | `corepack pnpm test:system`(worktree) | 사전 점검 PASS 뒤 16 failed / 96 passed. 16개 모두 `bwrap: Can't mkdir /tmp/ci-provider-upload-*/.git: Not a directory` | 58초. loadavg 9~17 |
| 6 | `corepack pnpm test:system`(clone) | 111 passed / 1 failed. 실패는 `kills descendants … timeout termination` 10,116 ms 시간 초과 | 89초. loadavg 8~15. 같은 시간에 4번이 잠금 밖에서 10초 돌았다 |
| 7 | clone에서 `-t 'kills descendants'` 8회(`scratchpad/r11/repeat-system-kill.sh`) | `output` 8/8 실패(17~32초, 기반 fixture 빌드를 떠안음). `timeout` 6/8 통과(4.8~10.2초), 2/8 시간 초과(10,359·10,363 ms) | 4분 10초. loadavg 18~36 |
| 8 | clone에서 webkit `old-tab-chunk-recovery.spec.ts --repeat-each=20 --workers=4` | 20/20 통과. 한 번에 10.8~15.4초 | 3.1분. loadavg 38→71 |
| 9 | worktree에서 `corepack pnpm create:feature sample-feature` | 21개 파일 생성(`src/features/sample-feature/**` 16, `src/contexts/sample-context/context-module.ts`, `tests/features/sample-feature/**` 3, a11y pending 기록 1). e2e spec은 만들지 않는다. "Next" 안내에 e2e가 없다 | 수 초 |
| 10 | 실험 spec `zz-review-sample.spec.ts` + `accessibility.spec.ts`, 세 엔진 | 54/54 통과. `[]` 응답: 세 엔진 모두 경고 상자 "서버 응답 구조가 예상과 다릅니다.", 목록 0, 콘솔 0, axe 0. Envelope 빈 목록: "총 0개 항목 / 표시할 항목이 없습니다.". Envelope 항목 2개: 목록 2줄. `@a11y /sample` 세 엔진 통과. 요청은 모두 `GET /api/sample-items`, bearer 첨부 | 94초. loadavg 19~41 |
| 11 | 9번 상태 + 빈·성공 상태에만 이름 없는 버튼을 넣는 변이, `corepack pnpm test:e2e` | 190 통과·9 실패·3 skip. `@a11y /sample`: firefox·webkit 통과(변이를 놓침). 실험 spec의 Envelope 화면: 세 엔진 모두 axe `button-name`(변이를 잡음). 9 실패 내역: chromium 6개는 모두 `requestfailed … net::ERR_NETWORK_CHANGED`(같은 시각 호스트 네트워크 변경), webkit 3개는 h1·대상 요소를 5초 안에 못 찾음(실패 스크린샷에는 제목이 그려져 있음). 변이와 생성 기능을 둔 채 `--last-failed`로 9개를 다시 돌리자 9/9 통과했다(14.8초, loadavg 18). 그래서 9개 실패는 호스트 원인으로 보고, 생성 기능이 다른 e2e를 깨지 않는다고 판단했다. chromium `@a11y /sample`도 이때 변이를 둔 채 통과했다 | 220초. loadavg 69~79 |
| 12 | `tests/unit/runbook-drill.test.ts`, drill 판정 한 줄을 상수 `"PASS"`로 바꾼 변이 | "keeps no constant recovery verdict" 통과(놓침). `FE-RB-002 fails when the build lost its JavaScript assets` 실패(잡음) | 수 초 |
| 13 | UI-04 되돌림(`git apply -R` `5d2ed17`의 `shell.css`) → `test:visual` | 1 실패·5 통과. 넓은 셸 `app-shell-wide-light` 1,145 px 차이(허용 50). 글꼴 확인 통과 | 13초. loadavg 16~18 |
| 14 | `tests/visual/fonts.conf`를 빈 러너 흉내(Playwright 의존 글꼴 디렉터리)로 바꿈 → `test:visual` | `visual-fonts` 실패, 화면 5장 did not run. 받은 글꼴 latin·korean·korean-800 = WenQuanYi Zen Hei, code = Liberation Mono. 메시지에 설치 명령. (첫 시도는 실험 파일 XML 오류로 무효, 버림) | 8초. loadavg 20 |
| 15 | 깨끗한 트리, 바깥 `FONTCONFIG_FILE`을 14번 파일로 → `test:visual` | 6/6 통과. 설정의 `launchOptions.env`가 바깥 값을 덮는다 | 15초. loadavg 20 |
| 16 | `corepack pnpm test:browser-capabilities` | 1·2회(clone, worktree): dev 서버가 `ENOSPC: System limit for number of file watchers reached`로 뜨지 않음(호스트 inotify 한도 65,536을 다른 프로세스가 씀, 판정에서 뺌). 3회(worktree, `CHOKIDAR_USEPOLLING=true`): 61 통과·2 실패. 실패는 `indexeddb-runtime.spec.ts:982` chromium·webkit, 받은 값 `{kind: "CLOSED", reason: "NOT_OPENED"}`(11-05) | 54초. loadavg 18~29 |
| 17 | 같은 테스트만 `--repeat-each=6`(세 엔진, 폴링 감시) | 18/18 통과 | 21초. loadavg 23~34 |
### 6.3 테스트 실행 비용 (관점 14)
| 대상 | 측정 | 조건 |
|---|---|---|
| e2e 4개 프로젝트 | 187개, 벽시계 94초(빌드 포함) | 11 worker, loadavg 12→31 |
| 가장 오래 걸린 e2e | webkit `i18n.spec.ts:60` 9.2초, webkit `@a11y /examples/platform` 7.3초 | 1번 실행 |
| webkit 구 탭 청크 spec | 평소 7.0초, loadavg 38~71에서 10.8~15.4초 | 1번, 8번 |
| visual | 6개, 12초(빌드 포함) | 1 worker |
| storybook | 1개, 19초(storybook 빌드 포함) | |
| `test:system` | 112개, 89초. 첫 provider 테스트가 기반 fixture 빌드로 14.1초 | clone |
| 영역 vitest | 26파일 171개, 9.7초 | |
e2e는 엔진마다 fixture 빌드를 7번 한다(SW update 2, SW recovery 2, old-tab 2, boot 1). 지난 라운드와 같다. 빌드가 짧아 결함으로 올리지 않았다.
### 6.4 미검증 목록
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 실제 CI 러너의 글꼴 구성과 FE-GATE-008·013 결과 | Gitea Actions가 꺼져 있다(U-1) | 러너 1대와 PR 1건 |
| 부하가 낮은 호스트에서 `test:system` 반복 결과 | 이번 호스트는 다른 리뷰어 때문에 loadavg 8~96이었다 | 조용한 기계에서 `test:system` 10회 |
| 생성 기능을 기존 context에 넣은 경우, 파라미터가 있는 생성 라우트 | 이번 실험은 새 context 하나만 만들었다 | `create:feature x --context reference-context` 뒤 e2e |
| 규모 기준선이 현재 코드를 대표하는지 | 측정 뒤 87커밋. 재측정에 기준선 기계와 긴 시간이 필요하다 | `measure-feature-shape-growth.ts` 재실행 |
| main·nightly·release scale tier, lab 성능 | 긴 시간과 기준선 CPU가 필요하다. lab 성능은 영역 15 | 기준선 기계에서 `check:scale:nightly`, `test:performance` |
| 0929/11-02 drill의 provider 경로 | 입력 경로 자체가 없다 | provider 증거 입력이 생긴 뒤 drill 1회 |
@@ -0,0 +1,399 @@
# 12 — 가드레일·CI 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `scripts/check-*.ts`·`scripts/verify-*.ts`·`scripts/lib/`, `.gitea/workflows/`, `config/ci/`, `eslint.config.ts`, `tsconfig*.json` 8개, `.dependency-cruiser.json`. `config/architecture/`는 이 커밋에 없다
> 깊게 본 관점: 2, 16, 21, 25, 26
> 렌즈: V2 삭제 뒤 검사가 지운 파일·이름을 가리키는가 · 템플릿 파일을 고치지 않고 기능 하나를 더하면 모든 게이트가 통과하는가(`test:feature-scaffold`) · 게이트 밖 검사의 상태(`check:remediation-ledger`) · `verify:documentation`이 못 잡는 범위
> 영역 판정(35.8): **조건부 사용 가능.** V2 삭제 뒤 게이트 입력(진단 생산자, risk-coverage, 아키텍처 fixture, adapter INVENTORY, 레지스트리 소비자)은 모두 현재 파일을 가리키고, 지운 경로를 다시 넣으면 각 검사가 실패한다. 지난 라운드 12번 발견 5건 중 4건이 고쳐졌다. 조건은 넷이다. (1) **`create:feature`로 기능 하나를 더하면 merge 게이트 FE-GATE-008의 `test:visual`이 실패한다.** 시각 골든 3장이 설치된 기능 목록을 담기 때문이다. 고칠 때까지 제품은 첫 기능 PR에서 템플릿 소유 골든 PNG를 다시 찍어야 한다(12-01, High). (2) 생성한 기능 경로의 a11y 통과를 믿지 않는다. 게이트는 빈 목록이 아니라 "서버 응답 구조가 예상과 다릅니다" 오류 화면을 검사하고 통과한다(12-03). (3) `create:feature`의 "모든 merge 게이트 통과"는 merge 단계 명령 88개 중 15개만 자동으로 확인된 주장이다(12-02). (4) 배포 job과 제품 전용 게이트는 템플릿 소유 `config/ci/gates.json`을 고쳐야 붙는다. 템플릿 동기화 때마다 충돌 후보다(12-07).
ID 표기: 이 문서의 `12-NN`은 2026-11-03 라운드 ID다. 지난 라운드(2026-11-01) 발견은 `1101/12-NN`, 2026-09-29 라운드 발견은 `0929/12-NN`으로 적는다.
## 0. 결론
- **V2 삭제 뒤 검사 입력에 남은 옛 경로는 없다.** `check:diagnostics` 생산자 표(`scripts/check-diagnostics.ts:31-53`), `REQUIRED_HIGH_RISK_PATHS`(`scripts/lib/risk-coverage.ts:22-29`), 금지 fixture(`tests/fixtures/architecture/forbidden/*`), INVENTORY, `registry-governance.json` 소비자가 모두 있는 파일을 가리킨다. 지운 경로 25개를 저장소 전체에서 검색했다. 이 다섯 검사 중 넷은 없는 경로를 만나면 실패한다(6.1절). 옛 경로가 남은 곳은 검사 밖 문서뿐이다(12-05).
- **기능을 더하는 일 자체는 템플릿 파일을 건드리지 않는다.** `create:feature`로 기능 1개, 이어서 같은 context에 3개를 더 만들었다. 드릴이 도는 15개 밖의 비브라우저 merge 명령 20개(`check:bundle` 포함)가 모두 통과했다. 생성 경로의 a11y 검사 4건(chromium)도 통과했다.
- **그러나 시각 회귀 게이트가 기능 하나에 실패한다(12-01, High).** 깨끗한 `e40684b`에서 `test:visual` 6건이 모두 통과했다. 기능 1개를 더하면 3건이 실패했다. 넓은 셸 185 px, 좁은 서랍 3,106 px(허용 50 px, `playwright.visual.config.ts:26`), 플랫폼 구성 화면은 높이가 3,814 → 3,964 px로 바뀌었다. 내비게이션과 플랫폼 구성 화면이 설치된 기능을 그리기 때문이다. 통과시키려면 템플릿 소유 `tests/visual/__snapshots__/` PNG 3장을 다시 찍어야 한다. 매뉴얼·생성 명령·드릴 어디에도 이 단계가 없다.
- **a11y 게이트는 생성 기능의 실제 화면을 보지 않는다(12-03, Medium).** `tests/e2e/accessibility.spec.ts:36-38`이 모든 API에 맨 배열 `[]`를 답한다. 생성 기능은 Envelope를 읽으므로 화면은 오류 상태다. probe로 읽은 `main` 글자는 "서버 응답 구조가 예상과 다릅니다. | 지원 참조: …"였다. 콘솔 오류가 없어 strict 검사도 통과한다. `docs/manual/reference/create-feature.md:76`은 반대로 "빈 상태 화면으로 그린다"고 적는다.
- **"모든 merge 게이트 통과"는 15개 명령의 결과다(12-02, Medium).** merge 단계는 14게이트·명령 참조 88개다. `test:feature-scaffold`는 15개를 돈다(`scripts/test-feature-scaffold.ts:46-61`). 브라우저 게이트(FE-GATE-008·009)는 아무도 생성 기능으로 돌리지 않는다. 그래서 12-01과 12-03이 FE-GATE-020을 통과했다.
- **금지 fixture가 운영 규칙이 아닌 fixture 전용 규칙을 시험한다(12-04, Low).** 운영 ESLint 설정에서 presentation의 `fetch` 금지와 import 금지를 지워도 `check:architecture`는 "9 forbidden rejected"로 통과했다(변이 M2). import 방향은 그래프가 따로 지킨다. `fetch`·`localStorage` 같은 전역 금지는 지킬 다른 검사가 없다.
- **문서 검사가 못 잡는 범위가 넷이다(12-05, Low).** 공백이 든 명령 안의 경로, `../`로 나가는 저장소 밖 링크, 지운 심볼 이름, `docs/README.md` 1절이 링크하지 않은 문서. 지금 실제로 세 곳이 지운 V2 테스트 파일을 가리킨다.
- **짝 백엔드 계약의 기준 커밋을 지키는 검사가 없다(12-06, Medium).** 기준은 문서 문장(`backend-api-and-server-state-contract.md:166-170`)뿐이다. 백엔드 작업 트리는 이미 그 기준에 없는 code를 적고 있다. 그 code의 처리 판정은 03-04에 있다.
- **배포 슬롯과 제품 전용 게이트가 템플릿 파일 안에 있다(12-07, Medium).** 다운스트림 tech-log는 이미 제품 커밋 3개에서 `gates.json`을 고쳤다.
- **merge 게이트가 커밋된 로그를 다시 쓴다(12-08, Low).** `check:scale:pr` 한 번에 추적 파일 3개가 바뀌고 1개가 새로 생겼다. 커밋된 로그에는 다른 기계의 절대 경로가 들어 있다.
- **게이트 밖 검사는 지금 통과한다.** `check:remediation-ledger` PASS(0.2초), `check:feature-index` PASS. 다만 원장 산문의 N-06~N-08 행은 지운 테스트를 가리킨다. 원장 검사도 문서 검사도 이 행을 읽지 않는다(12-05).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 12 |
| 커밋·작업 상태·확인 시점 | `e40684b`(merge: `93c81df` + `8c39e77`). 격리 worktree `agent-ab7d755ced2794f71`, detached, 미커밋 변경 없이 시작. `corepack pnpm install --frozen-lockfile`. 2026-11-03 23시대, 호스트 load 15~24 |
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 `config/ci/gates.json`에서 생성하는 Gitea Actions workflow |
| 필수 요구와 규모·운영 목표 | 짝 백엔드 템플릿과 함께 서비스를 빨리 출시한다. CI 시간·실패율 목표는 없다 |
| 읽은 코드·구성 범위 | 전체: `check-design-system.ts`, `lib/design-system-rules.ts`, `check-diagnostics.ts`, `check-remediation-ledger.ts`, `test-feature-scaffold.ts`, `lib/ungated-scripts.ts`, `config/ci/ungated-*.json`, `contract-baseline.json`, `tsconfig.base.json`. 부분: `check-architecture.ts:105-280`·`:920-990`, `verify-documentation-readiness.ts:153-300`, `lib/risk-coverage.ts:22-29`·`:300-330`·`:840-880`, `check-adapter-inventory.ts:1-200`, `check-registries.ts`(diff, `:560-620`), `check-request-fanout.ts:15-30`·`:100-185`, `lib/ungated-tests.ts:15-100`, `lib/oklch-contrast.ts:1-30`, `create-feature.ts:1-60`·`:1410-1424`, `lib/removal-fixture.ts:25-40`, `eslint.config.ts:40-75`·`:495-700`·`:840-960`, `.dependency-cruiser.json` 규칙 31개, `gates.json`의 stage·job·명령, workflow diff, `tests/e2e/accessibility.spec.ts`, `tests/visual/platform.visual.spec.ts`, `tests/support/browser/strict-browser-test.ts` |
| 읽은 문서(주장) | `docs/README.md` 1절, `docs/manual/reference/create-feature.md`, `docs/manual/01-add-a-feature.md:600-625`, `docs/operations/ci-quality-gates.md:15-35`·`:335-350`, `docs/operations/adapter-remediation-ledger.md:76-95`·`:585-590`, `docs/styling/design-system-platform.md:248-262`, `docs/architecture/backend-api-and-server-state-contract.md:160-170`, 지난 라운드 12번 문서와 README 13~14절 |
| 게이트 결과 | 오케스트레이터가 이 커밋에서 실행(`scratchpad/review-gates/summary.txt`): `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` 모두 exit 0. `check:bundle` 201,848 / 204,800 B |
| 수행한 테스트·실험 | 6절. 지운 경로 검색, 문서 검사 probe 9종, 게이트 밖 검사 2종, 생성 기능 1·4개 상태의 merge 명령 25종(드릴 밖 20개 + 겹치는 5개), 생성 경로 a11y(chromium) 4건과 화면 probe 1건, 시각 회귀 3회(기능 4개·1개·0개), 변이 3종 |
| 확인하지 못한 범위·이유 | 실제 Gitea runner 실행과 머지 시점 강제(외부 API를 부르지 않았다). 생성 기능 상태의 firefox·webkit e2e, `test:storybook`, `test:system`, `build:release-candidate`, FE-GATE-020의 다른 드릴(시간). 다운스트림 repo는 `gates.json` 커밋 이력만 읽었다 |
| 이전 리뷰와 비교 가능한 범위 | `d99301b..e40684b` 177커밋. 영역 파일 55개 변경(+3,326/−417). 큰 것: `create-feature.ts` 새 파일(1,468줄), `verify-documentation-readiness.ts`(+304), `lib/design-system-rules.ts` 새 파일, `check-release-admission.ts`, `lib/registry-compatibility.ts`. 지난 실험 결과는 증거로 다시 쓰지 않았다 |
## 2. 지난 발견 재판정
| 지난 ID | 내용 | 판정 | 현재 근거 |
|---|---|---|---|
| 1101/12-01 | 컴포넌트 토큰 독자를 이름 앞부분으로 셈 | **고쳐짐** | `scripts/lib/design-system-rules.ts:79-92`가 `var\(\s*(--[^\s,)]+)\s*[,)]`로 이름 전체를 맞추고 주석을 지운 뒤 센다. 입력란이 토큰을 읽는다(`primitives.css:163` `var(--field-border)`). 단위 테스트 "does not count a longer token that starts with the same name", "does not count a read inside a comment"(`tests/unit/design-system-rules.test.ts:85`, `:105`)가 오케스트레이터 `test:unit`에서 통과 |
| 1101/12-02 | 디자인 규칙 4개를 지키는 테스트가 없음 | **고쳐짐** | 규칙이 순수 함수로 분리됐고 규칙마다 실패·통과 단위 테스트가 있다. 배선도 본다. 복사본 CSS에 규칙별 위반을 넣고 `check-design-system.ts`를 실행해 위반 수를 단언한다(`design-system-rules.test.ts:149-171`). 성공 메시지는 여전히 "N tokens and headless vendor boundary PASS"다(`check-design-system.ts:181-183`, 경미) |
| 1101/12-03 | 디자인 규칙이 정해진 파일·소문자만 봄 | **일부 고쳐짐, 남음** | 대문자 `OKLCH`는 잡는다(`design-system-rules.ts:67-69` `/gi`, 테스트 `:65`). 남은 것: 그라디언트(`color-mix`만 본다), TSX 인라인(TSX는 hex·`oklch(`·`rgb(`만, `check-design-system.ts:144-149`), `base.css`의 토큰 재정의(값은 primitive·semantic에서만 읽음, `:93-100`), feature 폴더 CSS(대상은 `src/presentation/styles`뿐, `:44-48`), `outline-offset` 전제. 모두 코드 판독(E1). 템플릿 CSS는 아직 모두 검사 위치 안에 있다 |
| 1101/12-04 | 정상 CSS 거부, 규칙 문서 없음 | **고쳐짐** | 파서가 `deg`를 받는다(`lib/oklch-contrast.ts:14`). 기본 글꼴에 `-apple-system`·`BlinkMacSystemFont`가 있다(`design-system-rules.ts:99-109`). 제품이 싣는 글꼴은 `PRODUCT_LOADED_FONT_FAMILIES`(`token-contract.ts:65`). `color-mix`·알파는 계속 거부하되 메시지가 지원 형식을 적는다(`:40-42`). 규칙 4개와 지원 형식이 `docs/styling/design-system-platform.md:248-262`에 있다 |
| 1101/12-05 | 사문화 npm script 4개, 검사 접두어 5개 | **고쳐짐** | `scan:security:fixture`·`build:profile`·`generate:contract-set`·`build:app-only`가 `package.json`에 없다. `VERIFICATION_SCRIPT`에 `scan`이 들어갔다(`lib/ungated-scripts.ts:15`). `check:feature-index`는 결정대로 이유 문구만 고쳤다(`ungated-scripts.json:5`) |
| 1101 FOLLOW-UP | `check:remediation-ledger` 실패 | **고쳐짐(게이트 밖)** | 이번 실행 PASS(`25 dispositions … 0 open`). 다만 예외 이유가 "It passes at this commit"이라는 시점 문장을 담는다(`ungated-scripts.json:17`). 아무도 돌리지 않으면 다음 커밋에서 거짓이 될 수 있다. 원장 산문의 지운 테스트 참조는 12-05 |
| 1101 FOLLOW-UP | `noUnusedParameters`, `no-deprecated` 없음 | **바뀜** | `tsconfig.base.json:14`는 여전히 `noUnusedLocals`뿐이다. `no-deprecated` 대신 손 목록 2개를 `no-restricted-imports`로 막는다(`eslint.config.ts:53-68`). `src`의 `@deprecated` 10곳 중 2곳만 목록에 있다. 사용처 판정은 영역 09·16 |
| 1101 FOLLOW-UP U-1 | Actions 꺼짐·상태 0개 | **미확인** | Gitea API를 부르지 않았다. 트리거는 `push [main, develop]`, `pull_request`, 수동(`.gitea/workflows/quality-gates.yml:3-9`) |
| 0929/12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 안 봄 | **남음** | 바뀐 것은 주석 한 줄(`§12` → `scale-architecture.md §12`). receiver 이름 정규식(`check-request-fanout.ts:23`), 같은 줄 `fanout-reviewed:`만 인정(`:109`), 메시지에 해결 방향 없음(`:173-176`). 허용 fixture는 `bulk-read.ts` 하나 |
| 0929/12-02 (= 08-02) | `check:i18n`이 "파일에 한글이 있는가"를 봄 | **고쳐짐(범위 제한)** | 화면 문구 literal은 ESLint 선택자가 본다(`eslint.config.ts:477-490`, JSXText·표시 속성). `check:i18n`에 `가-힣` 정규식이 없다. template literal·삼항식·객체 prop 문구는 여전히 못 본다(1101 README 14.2에 기록된 제한) |
| 0929/12-03 | feature 안 layer 밖 폴더에 경계 규칙 없음 | **남음** | 해당 규칙(`feature-and-app-roots-do-not-reach-adapters`, `concrete-adapters-compose-only-in-bootstrap`)이 바뀌지 않았다(`.dependency-cruiser.json` diff는 새 규칙 1개와 주석 2줄). 변이 M4: `src/features/reference-feature/support/direct-http.ts`가 adapter 배럴을 import하고 같은 기능의 `presentation/` 파일이 그것을 import해도 `check:architecture`·ESLint 모두 통과(6.4절) |
| 0929/12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | **남음** | `config/ci/contract-baseline.json`(27/99/103/110/5)과 `tests/unit/ci-workflow-generation.test.ts:197-203`의 상수(99, 103, 110, 5, 그 밖에 jobs 10·fail 30·evidence 88). 문서 절차(`docs/operations/ci-quality-gates.md:23-27`)에 테스트 갱신 단계가 없다 |
| 0929/12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | **남음** | `package.json:180` `"dependency-cruiser": "18.1.0"`. `check-architecture.ts:115-117`은 자기 그래프가 유일한 검사기라고 적는다. `config/security/dependency-baseline.json`에도 올라 있다 |
| 0929/12-06 | Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 셈 | **남음** | 변이 M3: `tests/unit/r12-orphan.spec.ts`(항상 실패하는 단언)를 넣어도 `check:ci` PASS. Vitest는 그 파일을 돌지 않는다(`include: tests/**/*.test.{ts,tsx}`, `vitest.config.ts:38`). 원인 `lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어로 판정) |
| 0929/12-07 | 예외 목록에 담당·재검토 시점 없음 | **남음** | 두 스키마가 `path|script`와 `reason`뿐이다(`lib/ungated-tests.ts:20-32`, `lib/ungated-scripts.ts:17-29`). 항목 6개·17개. 대조: `contract-baseline.json`에는 `owner`·`reason`이 있다 |
요약: 지난 라운드 12번 5건 중 4건 고쳐짐, 1건 일부 남음. 0929 7건 중 1건 고쳐짐(범위 제한), 6건 남음. FOLLOW-UP 3건은 고쳐짐 1, 바뀜 1, 미확인 1.
## 3. 이번 발견 (36.3)
### 3.1 발견 목록
| ID | 심각도·우선순위 | 성격 | 관련 관점 | 한 줄 |
|---|---|---|---|---|
| 12-01 | High · P1 | 확인된 결함 | 10, 25, 3, 21, 20, 26 | `create:feature`로 기능 하나를 더하면 merge 게이트 `test:visual`이 실패하고, 통과시키려면 템플릿 소유 골든 PNG 3장을 다시 찍어야 한다 |
| 12-02 | Medium · P2 | 확인된 결함 | 10, 21, 20, 5, 25 | `create:feature`의 "모든 merge 게이트 통과"를 드릴은 15개 명령으로만 확인한다 |
| 12-03 | Medium · P2 | 확인된 결함 | 10, 21, 5, 17 | a11y 게이트가 생성 기능 경로에서 Envelope 불일치 오류 화면을 검사하고 통과한다 |
| 12-04 | Low · P2 | 확인된 결함 | 21, 10, 2, 5, 23 | 아키텍처 금지 fixture가 fixture 전용 ESLint 규칙을 시험해, 운영 규칙을 지워도 통과한다 |
| 12-05 | Low · P3 | 확인된 결함 | 21, 9, 27, 26 | `verify:documentation`이 명령 안 경로·저장소 밖 링크·지운 심볼·1절 밖 문서를 보지 않는다 |
| 12-06 | Medium · P2 | 구조적 위험 | 17, 21, 16, 25, 26 | 짝 백엔드 계약의 기준 커밋이 문서 문장뿐이고 어긋남을 알리는 검사가 없다 |
| 12-07 | Medium · P2 | 구조적 위험 | 25, 26, 3, 19, 18 | 배포 슬롯과 제품 전용 게이트를 붙이려면 템플릿 소유 `gates.json`을 고쳐야 한다 |
| 12-08 | Low · P3 | 확인된 결함 | 9, 20, 27 | merge 게이트 `check:scale:pr`가 커밋된 로그 파일을 다시 쓴다 |
### 12-01 `create:feature`로 기능 하나를 더하면 merge 게이트 `test:visual`이 실패하고, 통과시키려면 템플릿 소유 골든 PNG 3장을 다시 찍어야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 25, 3, 21, 20, 26 |
| 근거 | **게이트:** `test:visual`은 FE-GATE-008의 명령이고 FE-GATE-008은 `merge` stage에 있다(`config/ci/gates.json:2232` 이하). **골든이 기능에 묶임:** `tests/visual/platform.visual.spec.ts:13-20`은 `/` 전체 페이지, `:22-32`는 좁은 화면 서랍, `:55-65`는 `/examples/platform`의 `main`을 찍는다. 내비게이션은 설치된 기능의 링크를 그린다(실패 맥락 `error-context.md`의 `link "Reference feature"`, `link "Probe"` …). 플랫폼 구성 화면은 설치된 기능 목록을 그린다. 허용치는 절대 50 px다(`playwright.visual.config.ts:26`). **실험(6.3절 P-V0·P-V1·P-V4):** 같은 worktree, 같은 lock 안에서 깨끗한 `e40684b`는 6건 모두 통과(11.2초). `create:feature probe-feature` 1개를 더하면 3건 실패: 넓은 셸 185 px, 좁은 서랍 3,106 px, 플랫폼 구성은 이미지 크기 1040×3814 → 1040×3964. 기능 4개면 1,179 px, 4,016 px, 1040×4878. 나머지 3건(갤러리·화면 상태·글꼴)은 통과. **안내 없음:** `docs/manual/`, `create-feature.ts`의 `Next:`, `test-feature-scaffold.ts` 어디에도 시각 골든 갱신이 없다(`grep test:visual\|골든 docs/manual` 0건) |
| 발생 조건 | 제품이 `create:feature`로 첫 기능을 더하고 merge 단계 CI를 돌릴 때. 기능을 더하거나 지울 때마다. 참조 기능을 지울 때도 내비게이션이 바뀌므로 같을 것으로 본다(추론, 실행 안 함) |
| 영향 | 기능 추가 PR이 merge 게이트에서 빨갛게 된다. 생성 명령 문서는 템플릿 쪽 파일을 "고칠 필요가 없다"고 적고(`create-feature.md:82-89`) 첫 줄에서 "모든 merge 게이트를 통과"한다고 하므로, 제품 팀은 원인부터 찾아야 한다. 해결책인 `test:visual:update`는 템플릿 소유 PNG 3장을 바꾼다. 그 뒤 템플릿이 골든을 바꿀 때마다(다운스트림 기준점 `af3d8e6` 이후 `c0c5d9c` `373b27b` 두 번) 바이너리 충돌이 생긴다. 골든은 고정 글꼴 환경에서만 맞으므로(`tests/visual/fonts.conf`) 아무 기계에서나 다시 찍을 수도 없다. 두 다운스트림도 기능을 더할 때 같은 일을 겪는다(추론) |
| 심각도·우선순위 | High · P1 — 런타임 피해는 없다. 그러나 이 템플릿의 핵심 약속("생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다")이 지원하는 기본 사용에서 첫 기능부터 깨진다. 사용자 목표인 빠른 출시의 첫 PR을 막는다 |
| 통제·증거 | 목표 M3(기능 추가 뒤에도 템플릿 계약만 비교) / 확인 M0 · E3(시각 회귀 3회: 기능 0·1·4개) |
| 확실성과 남은 가정 | 실패와 원인 위치는 확정. CI runner에서도 같은지는 돌리지 않았다. 깨끗한 커밋이 로컬에서 0 px로 통과하므로 차이는 기능 추가에서 온다 |
| 결정의 근거 | 확인한 사실: 시각 테스트는 템플릿 셸·갤러리·플랫폼 화면의 "모양 계약"을 지키려고 만들었다(11-02·11-03 주석). 셸과 플랫폼 화면은 설치된 기능을 그리는 화면이라 계약에 제품 상태가 섞였다. 추론: 템플릿에 기능이 참조 기능 하나뿐이라 이 결합이 드러나지 않았다 |
| 이해 비용 | 제품 개발자는 실패한 diff 이미지를 보고 원인이 내비게이션 링크라는 것을 알아낸 뒤, 골든을 다시 찍을 환경을 찾아야 한다 |
| 최소 개선 방향 | 시각 계약을 설치된 기능과 떼어 낸다. (a) 셸 스크린샷에서 기능 링크 목록을, 플랫폼 구성 스크린샷에서 설치 기능 절을 `mask`로 가린다. 또는 그 영역 밖 요소만 찍는다. (b) 이어서 `test:feature-scaffold`가 생성 기능 상태로 `test:visual`을 한 번 돌게 한다(12-02) |
| 대안 비교 | (a) mask·영역 축소: 수 줄. 기능 수와 무관해진다. 대신 링크 목록의 모양 회귀는 시각 검사 밖이 된다(링크 개수·순서는 컴포넌트 테스트가 본다). (b) 시각 테스트만 고정 fixture 제품(참조 기능 1개)으로 빌드: 계약이 정확하지만 빌드 경로가 하나 더 생긴다. (c) 골든을 제품 소유로 선언하고 생성 명령이 `test:visual:update`를 안내: 가장 싸지만 동기화마다 PNG 충돌이 남고 "템플릿 파일 무수정" 약속과 맞지 않는다. 지금 규모에는 (a)가 작고 충분하다 |
| 단순화의 보존 조건 | 깨끗한 템플릿에서 6건은 계속 0 px로 통과한다. 11-03이 잡은 UI-04 회귀(1,146 px)처럼 셸 자체의 모양 회귀는 계속 실패한다 |
| 비용·부작용 | spec 수십 줄, 골든 3장 1회 재생성 |
| 재검토 조건 | 셸이 기능별 아이콘·배지처럼 기능마다 다른 모양을 그리게 되면 (b)를 다시 본다 |
| 완료 기준 | 기능 1개·4개를 더한 상태에서 `test:visual`이 골든 변경 없이 통과한다. 셸 CSS를 바꾸면 여전히 실패한다 |
| 검증 방법 | 6.3절 P-V1·P-V4 재실행, 셸 CSS 변이 1개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-02 `create:feature`의 "모든 merge 게이트 통과"를 드릴은 15개 명령으로만 확인한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(주장과 검증 범위가 다르다) |
| 관련 관점 | 10, 21, 20, 5, 25 |
| 근거 | **주장:** `scripts/create-feature.ts:15-16` "writes the smallest feature that passes every merge gate". `docs/manual/reference/create-feature.md:3` "모든 merge 게이트를 통과하는 가장 작은 기능". 생성 명령 출력은 `Next: 2. Run the merge gates:` 뒤에 14개 명령만 적는다(`create-feature.ts:1418`). **실제 merge 단계:** `gates.json:2232`의 `merge` stage는 FE-GATE-001~013·020이고 명령 참조가 88개다. **드릴:** `scripts/test-feature-scaffold.ts:46-61`이 15개(`check:types`, `lint`, `check:architecture`, `check:registries`, `check:i18n`, `check:design-system`, `check:diagnostics`, `verify:documentation`, `test:unit`, `test:component`, `test:integration`, `tests/features`, `test:coverage`, `check:ci`, `build`)를 돈다. 빠진 것 중 기능에 반응하는 것: FE-GATE-008(e2e·시각·storybook), FE-GATE-009(`test:a11y`), FE-GATE-012(`check:bundle`), `test:contract`, `test:runtime-schema`, `test:http-scenario-evidence`, `check:request-fanout`, `check:app-build-input`. **이번 실험(6.3절):** 빠진 비브라우저 명령 20개(`check:bundle`·`check:app-build-input:bundle`·`check:optional-recipes` 포함)를 생성 기능 상태에서 돌렸고 모두 통과했다. 생성 경로 a11y 4건(chromium)도 통과했지만 오류 화면을 본 통과다(12-03). `test:visual`은 기능 1개로 3건 실패했다(12-01). 매뉴얼은 `check:bundle`이 드릴 밖이라고만 적는다(`docs/manual/01-add-a-feature.md:619-623`) |
| 발생 조건 | 템플릿이 브라우저 게이트·번들·계약 테스트에 영향을 주는 변경을 할 때. 생성 뼈대가 바뀔 때(이번 라운드의 Envelope 전환이 그 예다) |
| 영향 | 생성 기능이 FE-GATE-008·009를 깨는 회귀가 생겨도 FE-GATE-020은 통과한다. 제품 팀은 첫 PR의 CI에서 처음 알게 된다. 이번에 그 범위 밖에서 12-01(시각 회귀 실패)과 12-03(a11y가 오류 화면 검사)이 실제로 생겼다. 생성 명령은 모든 다운스트림의 첫 기능 경로라 영향이 복제된다 |
| 심각도·우선순위 | Medium · P2 — 드릴 자체는 데이터·화면 피해를 만들지 않는다. 그러나 사용자 목표("템플릿 파일 수정 없이 기능 추가")를 증명하는 유일한 드릴이 범위를 넓게 말하고, 그 범위 밖에서 12-01·12-03이 생겼다. 12-01을 고쳐도 이 틈이 남으면 같은 종류가 다시 숨는다 |
| 통제·증거 | 목표 M3(merge 단계 전체) / 확인 M3(15개 명령), 나머지 M0 · E3(생성 기능 1·4개로 비브라우저 명령 25개, a11y·시각 실행) |
| 확실성과 남은 가정 | 드릴 범위와 문구는 확정. firefox·webkit e2e, storybook, `test:system`은 생성 기능 상태로 돌리지 않았다 |
| 결정의 근거 | 확인한 사실: 드릴은 저장소 복사본에서 명령을 하나씩 실행한다(`lib/removal-fixture.ts`). 브라우저 게이트는 수 분이 걸린다. 추론: 시간 때문에 비브라우저 핵심만 골랐다. 선택 비교는 5.1절 |
| 이해 비용 | 제품 개발자는 출력과 매뉴얼 첫 줄을 믿고 "merge 게이트를 다 통과한다"고 생각한다. 실제 범위를 알려면 `test-feature-scaffold.ts`와 `gates.json`을 대조해야 한다 |
| 최소 개선 방향 | (1) 드릴의 명령 목록을 손으로 적지 말고 `gates.json` merge stage에서 뽑는다. 제외는 이유와 함께 목록으로 둔다(브라우저·system·드릴 자신). (2) 생성 경로만 도는 chromium a11y·시각 회귀 1회를 드릴에 더하거나, 그 둘을 제외 목록에 이유와 함께 적는다. (3) `create-feature.ts:15-16`, `create-feature.md:3`, `Next:` 문구를 실제 범위로 고친다 |
| 대안 비교 | 5.1절 |
| 단순화의 보존 조건 | 드릴은 계속 복사본에서 돌고 원본을 바꾸지 않는다. 지금의 15개 검사와 JUnit 보고서(`artifacts/tests/feature-scaffold.xml`)는 유지한다 |
| 비용·부작용 | (1)은 수십 줄과 실행 시간 증가. 이번 측정으로 추가 20개 명령이 약 3분이었다(대부분 `check:browser-file-storage-boundaries` 97초, load 20대). (2)는 빌드 1회와 브라우저 약 1분 |
| 재검토 조건 | merge 단계에 명령이 늘거나, 생성 뼈대가 라우트·요청 모양을 바꿀 때 |
| 완료 기준 | 드릴이 merge stage에서 명령을 뽑는다. 제외 목록 밖의 merge 명령을 하나 더하면 드릴이 그것을 돈다. 문구가 실제 범위와 같다 |
| 검증 방법 | `gates.json` merge stage에 무해한 명령 하나를 더한 복사본에서 드릴 출력에 그 명령이 나오는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-03 a11y 게이트가 생성 기능 경로에서 Envelope 불일치 오류 화면을 검사하고 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 10, 21, 5, 17 |
| 근거 | **모의 응답:** `tests/e2e/accessibility.spec.ts:36-38`은 로그인이 필요한 모든 경로에서 `http://localhost:8080/api/**`에 `json: []`를 답한다. **생성 기능:** descriptor가 `responseEnvelope: "ENVELOPE_V1"`을 선언한다(생성 파일 `src/features/probe-feature/contracts/probe-contract-contribution.ts:37`). 맨 배열은 Envelope가 아니므로 `ENVELOPE_MISMATCH`가 된다(1101 README 14.6 "성공 status인데 Envelope가 아닌 본문 … 새 위반"). **단언:** spec은 h1이 보이고 로그인 제목이 아닌지, axe 위반이 없는지만 본다(`:39-49`). 오류 상태인지는 보지 않는다. **probe(6.3절 P-A2):** 같은 흐름으로 `/probe`를 열고 `main`의 글자를 읽었다. 결과는 "Probe \| create:feature가 만든 목록입니다. … \| 서버 응답 구조가 예상과 다릅니다. \| 지원 참조: f7d676e4-…". 콘솔 출력이 0줄이라 strict fixture(`strict-browser-test.ts:28-52`)도 통과한다. 같은 상태에서 `@a11y /probe…` 4건이 통과했다. **주장:** `docs/manual/reference/create-feature.md:76` "빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`가 모든 API에 `[]`를 답하기 때문이다". 1101 README 14.6 "남은 것"이 이 틈을 적었지만 e2e는 돌리지 않았고 매뉴얼 문장은 그대로다 |
| 발생 조건 | `create:feature`로 만든 모든 기능의 경로. 곧 Envelope operation을 쓰는 모든 제품 기능 |
| 영향 | FE-GATE-009의 axe 검사가 제품 경로마다 목록·빈 상태 대신 오류 화면을 본다. 목록 표, 빈 상태, 행 동작의 접근성 회귀를 CI가 잡지 못한다. 그 경로의 a11y 결과는 통과로 남는다. 기능 자신의 페이지 테스트(`tests/features/<id>/<base>-list-page.test.tsx`)는 빈 상태를 보지만 axe를 돌리지 않는다 |
| 심각도·우선순위 | Medium · P2 — 화면이 깨지는 결함은 아니다. 그러나 출시 전 접근성 증거가 모든 제품 경로에서 엉뚱한 화면의 증거가 되고, 모든 다운스트림에 복제된다. 고치는 비용이 작다 |
| 통제·증거 | 목표 M3 / 확인 M0(생성 기능 경로의 내용 화면) · E3(probe P-A2, a11y 4건) |
| 확실성과 남은 가정 | chromium에서 확인. firefox·webkit도 같은 모의 응답을 쓰므로 같다고 본다(추론) |
| 결정의 근거 | 적용 제외 — 모의 응답이 Envelope 전환을 따라가지 않은 누락이다 |
| 이해 비용 | 통과한 a11y 보고서를 본 사람은 목록 화면이 검사됐다고 생각한다 |
| 최소 개선 방향 | (1) spec이 operation의 `responseEnvelope`를 보고 `{ success: true, data: [], meta: {} }` 모양으로 답한다. MSW용 `createHttpScenarioHandler`가 이미 같은 판단을 한다(1101 README 14.6). (2) 검사 전에 오류 alert가 없음을 단언한다. 그러면 다음 모양 변경 때 spec이 바로 실패한다. (3) `create-feature.md:76` 문장을 고친 동작과 맞춘다 |
| 대안 비교 | 적용 제외 — 단순 누락 수정이다. "오류 화면도 접근성 검사 대상이니 괜찮다"는 빈·목록 상태를 검사하지 못하므로 같은 후보가 아니다 |
| 단순화의 보존 조건 | 템플릿 경로(참조 기능은 problem details·DTO)와 공개 경로의 검사는 그대로 통과한다 |
| 비용·부작용 | spec 수십 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 생성 기능 상태에서 `@a11y /<route>`가 빈 상태 제목(`async.empty`)을 본 뒤 axe를 돈다. 모의 응답을 맨 배열로 되돌리면 spec이 실패한다 |
| 검증 방법 | 6.3절 P-A2 probe 재실행. 맨 배열 변이로 spec 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-04 아키텍처 금지 fixture가 fixture 전용 ESLint 규칙을 시험해, 운영 규칙을 지워도 통과한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 21, 10, 2, 5, 23 |
| 근거 | **fixture 규칙:** `tests/fixtures/architecture/forbidden/**`에는 별도 ESLint 블록이 붙는다(`eslint.config.ts:937-960`). 모든 계층의 금지 패턴(`**/adapters/**`, `**/application/**`, `react`, `@tanstack/**` …)과 `fetch`·`localStorage`·`sessionStorage` 전역 금지를 합친 것이다. 메시지도 "forbidden architecture fixture: this import must be rejected"다. 운영 블록(`:627-697`, `:795-910`)과 다른 설정이다. **판정:** `check-architecture.ts:222-275`는 fixture 파일마다 ESLint exit code가 0이 아니면 거부됐다고 센다. 어떤 규칙이 걸렸는지는 보지 않는다. **변이 M2:** 운영 `src/presentation/**` 블록에서 layer import 금지를 지우고 `no-restricted-globals`에서 `fetch`를 지웠다. `corepack pnpm check:architecture` exit 0, "Architecture fixtures: allowed PASS, 9 forbidden rejected". **다른 보호:** import 방향은 그래프 규칙 31개와 회귀 fixture 28개가 따로 지킨다(같은 실행의 "28 regression checks PASS"). 전역 `fetch`·`localStorage`·`indexedDB` 금지를 보는 검사는 ESLint 운영 블록 말고 없다(`tests/`·`scripts/` 검색. `check:request-fanout`은 반복 안 호출만 본다) |
| 발생 조건 | 누군가 `eslint.config.ts`의 운영 블록을 정리하다 규칙을 잃을 때. 제품이 ESLint 설정을 고칠 때(1101 README 14.1은 ESLint 설정을 "제품이 덮어쓸 수 있는 자리"로 본다) |
| 영향 | presentation·application·domain 코드가 `fetch`·`localStorage`를 직접 써도 게이트가 통과한다. 그러면 HTTP 실행기의 마감·자격 증명·진단과 저장소 adapter의 사용자 범위를 우회한다. 출력 "9 forbidden rejected"는 운영 규칙이 시험됐다는 거짓 신호다 |
| 심각도·우선순위 | Low · P2 — 규칙을 잃는 변경이 먼저 있어야 한다. import 방향은 그래프가 지켜 피해 범위가 전역 금지로 좁다. 고치는 비용이 작고 거짓 증거라 P2 |
| 통제·증거 | 목표 M3 / 확인: import 방향 M3(그래프), 운영 ESLint 전역 금지 M2(구현만) · E3(변이 M2) |
| 확실성과 남은 가정 | 확정. fixture 전용 블록을 둔 이유 기록은 찾지 못했다(`6c52cdb`에서 들어옴) |
| 결정의 근거 | 확인한 사실: fixture는 `src` 밖에 있어 운영 블록의 `files` glob에 걸리지 않는다. 그래서 fixture용 블록이 필요했다. 추론: 운영 블록을 fixture에 그대로 적용하는 방법을 쓰지 않았다 |
| 이해 비용 | 운영 규칙을 바꾸는 사람은 fixture가 그 규칙을 지킨다고 믿는다. 실제로는 두 설정을 따로 맞춰야 한다 |
| 최소 개선 방향 | (1) fixture 파일을 계층 이름이 있는 가상 경로로 검사한다. ESLint `lintText(code, { filePath: "src/presentation/__fixture__/x.tsx" })`로 운영 블록을 그대로 적용한다. (2) 거부 판정을 exit code가 아니라 기대 rule id(`no-restricted-imports`, `no-restricted-globals`)와 위치로 한다. (3) fixture 전용 블록을 지운다 |
| 대안 비교 | 현 상태: 비용 0, 거짓 신호 유지. ESLint 금지 fixture 전체 삭제: import는 그래프가 지키지만 전역 금지의 검출이 0이 된다. (1)+(2)가 가장 작다 |
| 단순화의 보존 조건 | 9개 fixture는 계속 거부된다. 허용 fixture는 계속 통과한다. 그래프 회귀 fixture 28개는 그대로다 |
| 비용·부작용 | `check-architecture.ts` 수십 줄, ESLint 블록 1개 삭제 |
| 재검토 조건 | 그래프가 전역 사용(`fetch` 등)까지 보게 되면 ESLint 금지 fixture를 지울 수 있다 |
| 완료 기준 | 변이 M2를 다시 넣으면 `check:architecture`가 `presentation-direct-fetch.tsx`와 `presentation-imports-adapter.*`에서 실패한다 |
| 검증 방법 | 변이 M2 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-05 `verify:documentation`이 명령 안 경로·저장소 밖 링크·지운 심볼·1절 밖 문서를 보지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(검사 범위의 틈. 범위 일부는 문서에 적혀 있다) |
| 관련 관점 | 21, 9, 27, 26 |
| 근거 | **규칙:** 경로는 공백·`*<>{}$()\|`가 없는 backtick 조각만 본다(`verify-documentation-readiness.ts:212-220`). `../`로 저장소를 벗어나는 링크는 버린다(`:221-226`). 대상 문서는 `docs/README.md` 1절이 링크한 문서뿐이다(`:228-235`). 심볼 이름은 보지 않는다. `docs/README.md` 1절 끝 문단이 "설명·수치가 코드와 맞는지는 검사하지 않는다"고 적는다. **probe(6.2절):** 지운 경로 `src/adapters/http/client.ts`를 대상 문서에 backtick으로 적으면 실패한다(D0, 메시지가 파일과 경로를 적는다). 그러나 명령 안(D1), `../../../clean-architecture-backend-template/…/no-such.md` 링크(D2), `createHttpClient` 이름(D3), 1절 밖 문서(D4 testing strategy, D5 설계 정본)는 모두 PASS. **지금 실제로 남은 곳:** `docs/operations/adapter-remediation-ledger.md:91-93`(대상 폴더 안. N-06~N-08 행의 `corepack pnpm exec vitest run tests/integration/http-client.test.ts …`, 셋 다 지운 파일), `docs/testing/frontend-platform-testing-strategy.md:765`(`tests/integration/auth-recovery.test.ts`, 1절 밖), `docs/architecture/decisions/VD-23-…:3-6`·`:67`(상태 "REST v2 … COMPOSED", `defineRestOperation`, 1절 밖). 원장 검사는 dispositions JSON의 증거 경로만 읽어 N-06~N-08 산문을 보지 않는다(`check-remediation-ledger.ts:81-98`) |
| 발생 조건 | 경로를 명령 예시 안에 쓸 때, 짝 백엔드 문서로 링크할 때, 파일·심볼을 지울 때 |
| 영향 | 지운 V2 테스트를 실행하라는 명령이 대상 문서에 남는다. 복사해 실행하면 "No test files found"가 난다. 짝 백엔드 정본 링크(`backend-api-and-server-state-contract.md:166`, `:244`)가 깨져도 모른다. VD-23의 낡은 결정 내용은 03-06·14-03이 다룬다. 이 항목은 검사 범위만 다룬다 |
| 심각도·우선순위 | Low · P3 — 문서 탐색 비용이다. 검사 메시지와 대상 범위 설명은 좋다 |
| 통제·증거 | 목표 M3(대상 문서의 경로·명령) / 확인 M3(backtick 단독 경로·script·게이트 ID), 명령 안 경로·외부 링크 M0 · E3(probe D0~D8) |
| 확실성과 남은 가정 | 확정 |
| 결정의 근거 | 확인한 사실: 1절 밖 문서는 목표 설계·기록이라 의도적으로 뺐다(`docs/README.md` 1절 끝 문단). 명령 안 경로 누락은 기록된 의도가 없다 |
| 이해 비용 | 문서 작성자는 문서 검사가 경로를 본다고 생각한다. 명령 예시는 그 밖이다 |
| 최소 개선 방향 | (1) `corepack pnpm exec vitest run <경로…>`·`node <경로>` 형태의 명령에서 경로 인자를 뽑아 같은 존재 검사를 한다. (2) `../`로 나가는 링크는 형제 repo가 있으면 존재를 검사하고, 없으면 보고서에 "확인 안 함"으로 센다. (3) 원장 산문 N-06~N-08 행을 LEG-01 행처럼 "V2와 함께 삭제"로 고친다. (4) `ungated-scripts.json:17`의 "It passes at this commit"을 시점 없는 문장으로 바꾼다 |
| 대안 비교 | 심볼 이름 검사는 넣지 않는다. 지운 이름 목록을 따로 관리해야 하고 오탐이 많다. 명령 인자 경로와 외부 링크가 비용 대비 낫다(5.2절) |
| 단순화의 보존 조건 | 지금 PASS인 문서는 (3) 수정 뒤에도 PASS다. `CHANGELOG.md` 제외와 지울 수 있는 이력 규칙은 그대로다 |
| 비용·부작용 | 스크립트 수십 줄. 형제 repo가 없는 CI에서는 외부 링크가 "확인 안 함"으로 남는다 |
| 재검토 조건 | 짝 백엔드 문서를 패키지나 서브모듈로 가져오게 되면 외부 링크를 존재 검사로 바꾼다 |
| 완료 기준 | probe D1이 실패하고, D2가 보고서에 "확인 안 함" 또는 실패로 나온다 |
| 검증 방법 | `scratchpad/r12-doc-probes.sh` 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-06 짝 백엔드 계약의 기준 커밋이 문서 문장뿐이고 어긋남을 알리는 검사가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 17, 21, 16, 25, 26 |
| 근거 | **기준:** `docs/architecture/backend-api-and-server-state-contract.md:166-170`이 "기준 커밋: 백엔드 `5786126c` … 백엔드 기준 커밋을 올리면 6.1절 표를 같은 변경에서 다시 확인한다"고 적는다. 이 SHA를 읽는 코드·설정·테스트가 없다(`scripts`·`config`·`tests` 검색). **코드 쪽 사본:** 쓰기 전 거절 표 `REFUSED_BEFORE_WRITE`(`src/adapters/http/backend-envelope.ts:97-121`)와 503 재전송 판정(`:160-186`)은 백엔드 `docs/web/http-contract.md` §2를 손으로 옮긴 것이다. 테스트 fixture도 그 문서를 주석으로 인용할 뿐이다(`tests/integration/http-execution-v3-envelope.test.ts` 등 4파일). **실제 어긋남(관찰):** 백엔드 repo HEAD `7ef8d0b4`는 기준에서 1커밋 앞이고, `http-contract.md`가 미커밋으로 바뀌어 있다. 그 작업 트리는 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`("결과 불명, 같은 키로 다시")을 새로 적는다(`git diff 5786126c -- docs/web/http-contract.md`, +30/−9). 프론트의 어떤 검사도 이것을 알리지 않는다. 그 code의 처리 판정은 03-04 |
| 발생 조건 | 백엔드가 code·status·Envelope 규칙을 바꾸고 프론트 문서의 기준 커밋을 아무도 옮기지 않을 때 |
| 영향 | 프론트가 쓰기 결과를 잘못 분류할 수 있다. 결과 불명을 "적용 안 됨"으로 보면 다음 저장이 새 키로 나가 중복 생성이 된다. 지금 새 code는 표 밖이라 `MAYBE_APPLIED`로 떨어진다(03-04). 두 템플릿을 짝으로 쓰는 모든 제품에 같은 틈이 복제된다 |
| 심각도·우선순위 | Medium · P2 — 사용자 목표가 두 템플릿의 짝 사용이다. 지금 확인된 오분류는 없고 백엔드 변경은 미커밋이다 |
| 통제·증거 | 목표 M3(기준 어긋남 검출) / 확인 M1(문서 문장) · E1(검색, 백엔드 diff) |
| 확실성과 남은 가정 | 검사 부재는 확정. 백엔드 작업 트리 변경이 그대로 커밋될지는 모른다 |
| 결정의 근거 | 확인한 사실: 백엔드 문서는 다른 repo에 있고 CI에서 함께 체크아웃되지 않는다. 그래서 링크 검사로는 풀 수 없다(12-05). 추론: 기준을 기계가 읽는 칸으로 두지 않은 것은 두 repo의 배포 단위가 달라서다 |
| 이해 비용 | 백엔드를 바꾸는 사람은 프론트 문서의 기준 커밋 문장을 알아야 한다. 프론트를 바꾸는 사람은 백엔드 변경을 직접 따라가야 한다 |
| 최소 개선 방향 | (1) 기준을 기계가 읽는 파일로 옮긴다(예: `config/contracts/backend-contract-pin.json`: repo, SHA, 대조한 절, 담당). (2) 백엔드 §2 표를 code·status·"쓰기 전 거절" 열로 JSON 하나에 두고, 프론트 단위 테스트가 그 JSON과 `REFUSED_BEFORE_WRITE`를 대조한다. 백엔드는 같은 JSON을 자기 오류 코드 레지스트리(`docs/registries/error-codes.yaml`)와 대조한다. (3) 형제 repo가 있으면 로컬 검사가 백엔드 HEAD의 `http-contract.md`와 기준 SHA 판의 차이를 보고한다(게이트 밖) |
| 대안 비교 | 현 상태: 비용 0, 사람이 기억해야 한다. 공유 JSON(2): 두 repo가 같은 사실을 기계로 대조한다. 대신 파일 복사 절차가 하나 는다. 백엔드가 계약 패키지(npm)를 발행: 가장 강하지만 백엔드 빌드에 JS 패키지 발행이 생긴다. 지금 규모에는 (1)+(2)가 작다 |
| 단순화의 보존 조건 | 지금 `REFUSED_BEFORE_WRITE`의 판정과 테스트는 그대로다 |
| 비용·부작용 | 파일 1개, 테스트 1개, 백엔드 쪽 같은 크기의 대조. 두 repo에 걸친 결정이라 `design-docs/`에 기록할 일이다 |
| 재검토 조건 | 백엔드가 계약을 패키지로 발행하게 되면 그것으로 바꾼다 |
| 완료 기준 | 백엔드 표에 code 하나를 더한 JSON을 넣으면 프론트 테스트가 실패한다. 기준 SHA가 파일 하나에 있다 |
| 검증 방법 | JSON에 `IDEMPOTENCY_COMPLETION_UNKNOWN` 행을 넣어 프론트 테스트 실패 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-07 배포 슬롯과 제품 전용 게이트를 붙이려면 템플릿 소유 `gates.json`을 고쳐야 한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 25, 26, 3, 19, 18 |
| 근거 | **배포 슬롯:** `config/ci/gates.json:2789-2805`의 `deployment` job은 `deploy` 단계에 `script`가 없다. `docs/operations/ci-quality-gates.md:339-344`는 "To fill it, edit the `deployment` job in `config/ci/gates.json` and run `generate:ci-workflow`"라고 적는다. 그러면 생성 파일 `.gitea/workflows/quality-gates.yml`도 바뀐다. **제품 게이트:** 제품이 자기 검사(예: 12-06의 백엔드 계약 대조)를 merge에 넣을 자리도 `gates.json`뿐이다. 게이트를 더하면 `contract-baseline.json`과 `tests/unit/ci-workflow-generation.test.ts:197-203`의 상수까지 바뀐다(0929/12-04). **크기·변경 빈도:** `gates.json` 2,984줄, workflow 484줄. `gates.json`은 다운스트림 기준점 `af3d8e6` 이후 템플릿에서 3번 바뀌었다. **다운스트림 관찰:** tech-log-frontend는 제품 커밋 `3af9be9e`, `fe6b56a9`, `071405a6`에서 `gates.json`을 고쳤다(제품 경로의 a11y 기록 산출물 추가). 그 필요는 이 커밋에서 사라졌다. 생성 기능 상태에서 `check:ci`가 통과한다. 그러나 배포와 제품 게이트에는 같은 모양이 남는다. 대조: 기능 조립은 1101 결정(가)로 제품 소유 파일(`src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`)을 얻었다 |
| 발생 조건 | 제품이 CD를 붙이거나 자기 merge 검사를 더할 때. 그 뒤 템플릿 `gates.json`이 바뀌어 동기화할 때 |
| 영향 | 모든 제품이 출시 전에 템플릿 파일 2개(+기준선)를 고친다. 템플릿 동기화마다 3,000줄 JSON과 생성 YAML에서 충돌을 손으로 푼다. 잘못 풀면 게이트 ID·산출물 연결이 깨지거나 생성 YAML이 계약과 달라진다. 후자는 `check:ci`가 잡는다 |
| 심각도·우선순위 | Medium · P2 — 빠른 출시 목표의 마지막 단계(배포)가 템플릿 파일 수정을 요구한다. 데이터 피해는 없고 `check:ci`가 깨진 결과를 잡는다 |
| 통제·증거 | 목표: 제품 소유 확장 지점 / 확인 M1(문서로 "gates.json을 고쳐라") · E1(코드·문서 판독, 다운스트림 커밋 이력) |
| 확실성과 남은 가정 | 확장 지점 부재는 확정. 다운스트림이 실제로 배포 job을 채웠는지는 보지 않았다 |
| 결정의 근거 | 확인한 사실: 게이트·job·산출물을 한 계약 파일에 모아 workflow를 생성하고 기준선 digest로 고정한다. 이것이 CI에 아무 job이나 끼우지 못하게 하는 보호다. 선택 비교는 5.3절 |
| 이해 비용 | 제품 개발자는 배포를 붙이려고 템플릿 계약 파일의 job·단계 스키마(`scripts/contracts/ci-gates.ts:368-397`)를 알아야 한다 |
| 최소 개선 방향 | 제품 소유 overlay 파일 하나(예: `config/ci/product-gates.json`)를 둔다. 허용 범위는 `deployment` job의 `deploy.script`, `vars.*`·`secrets.*` 바인딩, 제품 전용 게이트(ID 접두어를 따로 둔다)로 제한한다. 생성기와 `check:ci`가 두 파일을 합쳐 읽는다. 템플릿 기준선은 템플릿 몫만 센다 |
| 대안 비교 | 5.3절 |
| 단순화의 보존 조건 | 템플릿 게이트의 ID·명령·산출물 계약과 기준선 digest는 그대로다. overlay는 템플릿 게이트를 지우거나 바꾸지 못한다 |
| 비용·부작용 | 생성기·계약 로더 수십~백 줄, 스키마 1개, 테스트. 계약 파일이 둘이 된다. 배포 secrets 노출 범위(13-05)를 overlay 설계 때 함께 정한다 |
| 재검토 조건 | 제품이 템플릿 게이트 자체를 바꿔야 하는 사례가 반복되면 overlay 범위를 다시 본다 |
| 완료 기준 | 복사본에서 overlay에 배포 script를 적고 `generate:ci-workflow`·`check:ci`가 통과한다. 그 상태에서 템플릿 `gates.json`을 바꿔도 overlay와 충돌하지 않는다 |
| 검증 방법 | 템플릿 `gates.json` 변경 커밋 하나를 overlay가 있는 복사본에 3-way 병합해 충돌 0 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-08 merge 게이트 `check:scale:pr`가 커밋된 로그 파일을 다시 쓴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 20, 27 |
| 근거 | `scripts/scale/run-scale-profile.ts:21`·`:153`이 단계 출력을 `artifacts/scale/<tier>/<step>.log`에 쓴다. `artifacts/scale/pr/*.log` 4개가 git에 추적된다(`git ls-files`). `.gitignore:11-20`은 `json`·`xml`·`txt`·`sarif`만 무시하고 `.log`는 무시하지 않는다. **실행:** `corepack pnpm check:scale:pr`(FE-GATE-005, 32초) 뒤 추적 파일 3개가 바뀌었고(`architecture-topology.log`, `scale-units.log`, `traffic-budgets.log`) `composition-s0-s2.log`가 새로 생겼다. 커밋된 판은 ANSI 색 코드와 다른 기계의 경로(`/shared/codebase/clean-architecture-frontend-template`)를 담는다. `main`·`nightly`·`release` 계층 로그도 같은 방식으로 추적된다(`artifacts/scale/` 아래 `.log` 35개. `artifacts/` 전체로는 추적되는 `.log`가 63개) |
| 발생 조건 | 개발자가 merge 게이트를 로컬에서 돌릴 때마다 |
| 영향 | 작업 트리가 더러워진다. 실수로 로그 변경을 커밋하거나, 커밋 전에 매번 되돌린다. 다운스트림은 동기화 때 이 파일들을 걸러낸다(사용자 메모 기록. 현재 커밋의 증거가 아니라 참고) |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 해당 없음 · E3(실행 후 `git status`) |
| 확실성과 남은 가정 | 확정. 커밋된 로그가 어떤 문서의 증거로 쓰이는지는 찾지 못했다 |
| 결정의 근거 | 적용 제외 — 생성물 무시 규칙의 누락이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | `artifacts/scale/**/*.log`를 `.gitignore`에 넣고 추적을 끊는다. 기준 측정을 남기려면 이미 있는 `config/scale/benchmark-baseline.json`처럼 정해진 JSON으로 남긴다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | `check:scale:*`의 판정과 기준선 파일은 그대로다 |
| 비용·부작용 | `.gitignore` 한 줄과 파일 35개 추적 해제 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `check:scale:pr` 뒤 `git status`가 깨끗하다 |
| 검증 방법 | 같은 명령 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 제외 — 이 영역에 도메인 규칙이 없다 | — | — | - · 검사기 정확성은 10·21에서 본다 |
| **2** | 구조적 성숙도 | 적용 — 경계 강제 장치 | M3 / import 방향 M3(그래프 31규칙·회귀 fixture 28개), feature 안 layer 밖 폴더 M0 | E3 | P · 0929/12-03 남음(변이 M4). ESLint 금지 fixture는 운영 규칙을 시험하지 않는다(12-04) |
| 3 | 변경 용이성 | 적용 | M3 / P | E3 | P · 기능 하나 추가가 템플릿 골든 PNG 3장 갱신을 부른다(12-01). 게이트 하나 변경이 계약·기준선·테스트 상수·생성 YAML 네 곳을 움직인다(0929/12-04). 배포는 템플릿 파일 수정이다(12-07) |
| 4 | 인지 부하 | 적용 | — | E1 | P · CI 메타 층(`gates.json` 2,984줄 등)이 그대로 크다. 생성 명령의 "merge 게이트" 문구가 실제 범위와 다르다(12-02) |
| 5 | 위험 가시성 | 적용 | M3 / P | E3 | P · 통과한 a11y가 오류 화면을 본 통과다(12-03). "9 forbidden rejected"가 운영 규칙을 시험한 것처럼 보인다(12-04) |
| 6 | 실패 성숙도 | 적용 제외 — 런타임 실패 처리가 없는 영역 | — | — | - |
| 7 | 운영 성숙도 | 다른 영역 | — | — | > 영역 13 |
| 8 | 디버깅 가능성 | 적용 | M3 / P | E3 | P · 문서 검사·디자인 규칙 메시지는 파일·이유·해결 방향을 적는다(probe D0). fanout 메시지는 그대로다(0929/12-01) |
| 9 | 유지보수 성숙도 | 적용 | — | E3 | P · 커밋된 로그 churn(12-08), 미사용 `dependency-cruiser`(0929/12-05), 원장의 지운 테스트 명령(12-05) |
| 10 | 테스트 성숙도 | 적용 | M3 / P | E3 | P · 디자인 규칙 테스트는 고쳐졌다(1101/12-02). 시각 골든이 설치된 기능에 묶였다(12-01). 생성 기능 드릴 범위(12-02), a11y 모의 응답(12-03), 고아 `*.spec.ts`(0929/12-06) |
| 11 | 데이터 성숙도 | 적용 제외 — 저장 데이터 없음 | — | — | - |
| 12 | 동시성 성숙도 | 적용 제외 | — | — | - |
| 13 | 확장성 | 일부 적용 | — | E3 | > 영역 09·15. 이 영역 몫: 생성 기능 1개(새 context) +598 B, 같은 context에 3개 더 +914 B(개당 약 305 B). 기준 여유 2,952 B로 같은 context 기능 약 9개다. 새 context마다 더 빨리 찬다. 매뉴얼이 팀 결정으로 적었다 |
| 14 | 성능 성숙도 | 적용 | — | 로컬만 | ? · runner가 없어 CI 시간을 재지 못했다. 로컬: 드릴 밖 명령 20개 약 3분(load 20대) |
| 15 | 보안 성숙도 | 적용(workflow 범위) | M4 / M4 | E1 | O · `permissions: contents: read`, action 33개 모두 40자 SHA, `persist-credentials: false` 9곳, `--frozen-lockfile` 9곳, `pull_request_target` 0. 배포 슬롯 secrets 노출은 13-05 |
| **16** | 의존성 성숙도 | 적용 | M3 / P | E1 | P · 미사용 `dependency-cruiser@18.1.0`(0929/12-05). 짝 백엔드 계약을 버전처럼 고정하는 장치가 문장뿐이다(12-06) |
| 17 | API / Contract | 적용 | M3 / P | E3 | P · 짝 백엔드 표 대조 없음(12-06). a11y 모의 응답이 Envelope 계약을 따라가지 않았다(12-03) |
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 영역 13. 이 영역 몫: 배포 슬롯이 템플릿 파일 안에 있다(12-07) |
| 19 | 설정 성숙도 | 적용 | — | E1 | P · 제품 설정(배포 script, 제품 게이트)이 템플릿 계약 파일 안에 있다(12-07). 제품 글꼴 목록은 토큰 계약 옆으로 왔다(1101/12-04) |
| 20 | 개발자 경험 | 적용 | — | E3 | P · 첫 기능 PR이 시각 회귀로 실패하고 안내가 없다(12-01). 생성 명령 `Next:`가 범위를 넓게 말한다(12-02). 로컬 게이트 실행이 트리를 더럽힌다(12-08) |
| **21** | Guardrail 성숙도 | 적용 | M3 / 로컬 P, 머지 시점 미확인 | E3 | P(로컬) · ?(머지 시점) · V2 삭제 뒤 입력이 모두 맞고 옛 경로를 다시 넣으면 대부분 실패한다(6.1절). 남은 틈: 12-01(기능 추가가 merge 게이트를 깨는데 드릴이 못 봄)·12-02·12-03·12-04·12-05, 0929/12-03·0929/12-06 |
| 22 | 추상화 성숙도 | 적용 | — | E1 | P · 디자인 규칙을 순수 함수로 뺀 것은 규모에 맞다. 타입 음성 fixture 23개가 명령·기준선에 하나씩 적힌다(1101 R-3 그대로) |
| 23 | 일관성 | 적용 | — | E3 | P · 금지 fixture용 ESLint 설정과 운영 설정이 따로다(12-04). 문서 검사는 backtick 경로만 보고 명령 안 경로는 보지 않는다(12-05) |
| 24 | 네이밍 / 의미 | 적용 | — | E1 | P · "Run the merge gates:" 뒤 14개, "9 forbidden rejected", 디자인 검사 성공 메시지가 실제보다 넓게 말한다 |
| **25** | 조직 확장성 | 적용(팀 하나라 구조만) | — | E3 | P(구조만) · 기능 추가는 템플릿 파일 무수정으로 비브라우저 merge 명령 35개(드릴 15 + 추가 20)와 a11y를 통과하지만 `test:visual`에서 실패해 템플릿 골든을 고치게 된다(12-01). 배포·제품 게이트는 템플릿 파일 수정이 필요하고, 다운스트림이 이미 같은 파일을 고쳤다(12-07) |
| **26** | Ownership | 적용 | M1 / P | E1 | P · 시각 골든이 템플릿 소유인데 제품 상태를 담는다(12-01). 예외 목록에 담당·재검토가 없다(0929/12-07). 짝 백엔드 기준을 옮길 담당이 없다(12-06). 대조: CI 기준선·레지스트리 기준선에는 owner·승인자가 있다 |
| 27 | 삭제 가능성 | 적용 | M3 / P | E3 | P · V2 삭제는 게이트 입력까지 정리됐다. 검사 밖 문서 세 곳에 지운 파일이 남았다(12-05) |
| 28 | 회복 가능성 | 적용 제외 — 이 영역에 복구 경로가 없다 | — | — | - |
## 5. 설계 선택 검토 (41절)
### 5.1 기능 생성 드릴이 merge 단계의 일부 명령만 손 목록으로 도는 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | "생성한 기능은 템플릿 파일을 고치지 않고 merge를 통과한다"는 주장을 CI가 지킨다. 쓰는 사람은 제품 팀이고, 이 주장이 매뉴얼의 기능 추가 경로 전체를 받친다 |
| 2. 지킬 성질 | 생성 뼈대를 깨는 템플릿 변경이 FE-GATE-020에서 먼저 실패한다. 드릴이 말하는 범위와 실제 범위가 같다 |
| 3. 현재 보장 | 복사본에 기능 1개를 만들고 15개 명령을 돈다(`test-feature-scaffold.ts:39-61`). 비브라우저 핵심 검사는 보장한다. **보장하지 않는 것:** FE-GATE-008·009·012와 계약·스키마·시나리오 테스트 등 나머지 merge 명령. 이번에 그 밖에서 12-01(시각 회귀 실패)과 12-03(a11y 오류 화면 검사)이 생겼다 |
| 4. 대안 | (a) 현 상태. (b) 목록을 `gates.json` merge stage에서 뽑고 제외만 손 목록으로 둔다. (c) (b) + 생성 경로만 도는 chromium a11y·시각 1회. (d) 복사본에서 merge 단계 전체(3엔진 e2e 포함)를 돈다 |
| 5. 대안별 비용 | (a) 0, 범위가 조용히 벌어진다. (b) 수십 줄, 비브라우저 명령 약 3분 추가(이번 측정, load 20대). 새 merge 명령이 자동으로 들어온다. (c) (b) + 빌드 1회·브라우저 약 1분. 12-01·12-03 같은 화면 틈을 잡는다. (d) e2e 3엔진과 storybook·system까지 수십 분. 드릴이 merge job을 한 번 더 도는 셈이다 |
| 6. 현재 조건에서의 선택 | **(c).** 드릴의 목적이 "생성 기능이 merge를 통과한다"이므로 목록이 merge stage에서 와야 범위가 어긋나지 않는다. 브라우저 게이트 전체는 비싸지만 생성 경로만 도는 1회는 싸다. 리뷰어 추론이며 작성 당시 비교 기록은 없다 |
| 7. 재검토 조건 | 드릴 시간이 merge job의 임계 경로를 넘으면 (b)로 줄인다. 생성 뼈대에 화면이 여러 개 생기면 브라우저 범위를 다시 본다 |
### 5.2 문서 검사를 "1절 문서의 backtick 경로·script·게이트 ID"로 좁힌 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 현재 계약 문서가 없는 경로·명령·게이트를 가리키지 않는다. 템플릿을 받은 사람이 문서대로 명령을 쳤을 때 동작한다 |
| 2. 지킬 성질 | 대상 문서에 적힌 실행 가능한 참조(경로, 명령, 게이트 ID)가 이 커밋에 있다. 대상 밖 문서는 기록임을 밝힌다 |
| 3. 현재 보장 | backtick 단독 경로, `pnpm` script, FE-GATE ID, 저장소 안 링크(`verify-documentation-readiness.ts:212-280`). 메시지가 파일과 경로를 적는다. **보장하지 않는 것:** 명령 인자 경로, 저장소 밖 링크, 심볼 이름, 1절 밖 문서(12-05) |
| 4. 대안 | (a) 현 상태. (b) 명령 인자 경로와 형제 repo 링크 추가. (c) 모든 `docs/**`로 확대. (d) 심볼 이름까지 TypeScript 프로그램으로 확인 |
| 5. 대안별 비용 | (a) 0. (b) 수십 줄, 오탐 거의 없음. (c) 목표 설계·기록 문서가 일부러 옛 경로를 적어 예외가 폭증한다. (d) 문서의 모든 코드 이름을 분류해야 해서 오탐이 많고 비싸다 |
| 6. 현재 조건에서의 선택 | **(a)를 유지하고 (b)만 더한다.** 대상을 1절로 좁힌 것은 기록 문서를 지켜야 하는 이유가 있다. 명령 인자 경로는 같은 규칙의 빈칸이라 메우는 비용이 작다. 지금 실제 누락(원장 N-06~N-08)이 그 빈칸에 있다 |
| 7. 재검토 조건 | 1절 밖 문서를 현재 계약으로 승격하면 대상에 넣는다. 짝 백엔드 문서를 서브모듈·패키지로 가져오면 외부 링크를 존재 검사로 바꾼다 |
### 5.3 CI 확장 지점을 단일 계약 파일(`gates.json`) 안에 둔 선택
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | CI가 선언한 게이트만 돌고 산출물·승격 순서가 계약대로다(현재 강점). 동시에 제품이 배포와 자기 검사를 붙이고 템플릿 업데이트를 받는다 |
| 2. 지킬 성질 | 템플릿 게이트는 제품이 지우거나 약하게 할 수 없다. 생성 workflow는 계약과 바이트가 같다. 제품 설정은 템플릿 동기화 때 충돌하지 않는다 |
| 3. 현재 보장 | 앞의 두 성질은 기준선 digest와 `check:ci`가 지킨다(M3). 세 번째는 없다. 배포는 `gates.json`을 고치라고 문서가 말한다(`ci-quality-gates.md:342-344`) |
| 4. 대안 | (a) 현 상태. (b) 제품 overlay 파일 하나(배포 script·바인딩·제품 게이트만). (c) 제품 전용 workflow 파일을 따로 두고 템플릿 workflow의 산출물을 받는다. (d) 배포만 저장소 변수(`vars.DEPLOY_SCRIPT` 등)로 받는다 |
| 5. 대안별 비용 | (a) 0, 동기화마다 3,000줄 JSON 충돌. (b) 생성기·로더 수십~백 줄. 템플릿 계약 보호는 그대로 둔다. (c) Gitea에서 run 사이 산출물 전달은 검증되지 않았다(1101 README 14.1의 13-01 결정에서 버린 대안 (d)와 같은 이유). (d) 가장 작지만 제품 게이트는 풀지 못하고, 실행할 명령이 저장소 밖 변수에 숨는다 |
| 6. 현재 조건에서의 선택 | **(b).** 1101 결정(가)가 기능 조립에 제품 소유 파일을 연 것과 같은 모양이다. 템플릿 게이트의 보호를 잃지 않는다. 다운스트림이 이미 같은 파일을 고친 기록이 있다. 리뷰어 추론이다 |
| 7. 재검토 조건 | 제품이 템플릿 게이트 자체를 끄거나 바꿔야 하는 요구가 반복되면 overlay 권한을 다시 본다. Gitea가 run 사이 산출물 전달을 지원하면 (c)를 다시 비교한다 |
## 6. 실험·변이 기록
모든 실험은 격리 worktree(`e40684b`)에서 했고, 끝난 뒤 `git checkout -- . && git clean -fd`와 intent-to-add 해제로 되돌렸다. Playwright·`build`는 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock`으로 감쌌다. 스크립트는 오케스트레이터 scratchpad의 `r12-*.sh`.
### 6.1 V2 삭제 뒤 옛 경로·이름
`d99301b..e40684b`에서 지워지거나 이름이 바뀐 경로 25개를 저장소 전체(리뷰·CHANGELOG 제외)에서 검색했다(`r12-stale-refs.sh`). V2 심볼(`createHttpClient`, `createRuntimeHttpClient`, `defineRestOperation`, `resolveRestSecurityProfiles`, `RuntimeHttpContract`)은 `scripts`·`config`·`tests`·ESLint·그래프 설정에 0건이다.
| 검사 입력 | 현재 상태 | 옛 경로를 다시 넣으면 |
|---|---|---|
| `check:diagnostics` 생산자 표 | `api.request.failed`, `http.request.completed` → `src/bootstrap/runtime-adapters.ts`(`:207`, `:227`에 실제 호출) | 파일 읽기 실패로 종료한다. 다만 판정은 "파일에 이벤트 이름 문자열이 있는가"다(`check-diagnostics.ts:69-90`). 주석에만 이름이 있어도 통과한다(코드 판독). 실제 호출은 단위 테스트가 본다 |
| `REQUIRED_HIGH_RISK_PATHS`·`risk-coverage.json` | 6개 경로 모두 존재 | "high-risk module is outside production inventory"로 실패(`risk-coverage.ts:861-864`). 필수 목록에서 빠지면 "required high-risk path is missing"(`:318-321`) |
| 아키텍처 금지 fixture | V3 실행기(`http-execution-v3.ts`)를 import | ESLint exit code만 본다(12-04). 그래프 barrel fixture의 `client.ts`는 fixture 자신의 파일이라 옛 경로가 아니다(`tests/fixtures/architecture/dependency-graph/barrel/adapters/http/client.ts`) |
| adapter INVENTORY | `git ls-files src/adapters`와 양방향 대조 | "unexpected <path>"로 실패(`check-adapter-inventory.ts:41-52`) |
| `registry-governance.json` 소비자 | 11개 레지스트리의 source·consumer 경로 모두 존재 | "consumer source is missing"으로 실패(`check-registries.ts:563-575`) |
| 검사 밖 문서 | 원장 `:91-93`, testing strategy `:765`, 설계 정본(`2026-07-30-…closed-deep-design.md:238-240`, `:1239-1242`), VD-23 | 문서 검사가 못 본다(12-05) |
### 6.2 문서 검사 probe (`r12-doc-probes.sh`)
한 줄씩 문서 끝에 더하고 `verify-documentation-readiness.ts`를 돌린 뒤 되돌렸다.
| ID | 문서 | 더한 줄 | 결과 |
|---|---|---|---|
| D0 | `docs/operations/ci-quality-gates.md` | `` `src/adapters/http/client.ts` `` | 실패(기대). "names paths that do not exist: src/adapters/http/client.ts" |
| D1 | 같은 문서 | `` `corepack pnpm exec vitest run tests/integration/http-client.test.ts` `` | **통과** |
| D2 | 같은 문서 | `[contract](../../../clean-architecture-backend-template/docs/web/no-such.md)` | **통과** |
| D3 | 같은 문서 | `` `createHttpClient` `` | **통과**(심볼은 범위 밖, 문서화됨) |
| D4 | `docs/testing/frontend-platform-testing-strategy.md` | D0과 같은 경로 | **통과**(1절 밖) |
| D5 | 설계 정본 `2026-07-30-…closed-deep-design.md` | D0과 같은 경로 | **통과**(1절 밖) |
| D6 | `ci-quality-gates.md` | `` `src/adapters/http/client.ts:12` `` | 실패(기대. 줄 번호를 떼고 검사) |
| D7 | 같은 문서 | `FE-GATE-099` | 실패(기대) |
| D8 | `docs/manual/01-add-a-feature.md` | `` `corepack pnpm check:nope` `` | 실패(기대) |
### 6.3 생성 기능 상태의 merge 명령 (`r12-scaffold-extra.sh`)
`corepack pnpm create:feature probe-feature`(새 context)를 만들고, 이어 `probe-two`·`probe-three`·`probe-four`(같은 context)를 만들었다. 생성 파일은 `git add -N`으로 git 기반 검사에 보이게 했다. 생성 명령은 기능 폴더·테스트 폴더·새 context·a11y 기록만 만들었고 추적 파일은 바꾸지 않았다(`git status`).
| 상태 | 명령 | 결과 |
|---|---|---|
| 기능 1개 | 드릴 밖 명령 13개: `check:types:recipes`, `test:runtime-schema`, `test:contract`, `check:request-fanout`, `check:app-build-input`, `check:browser-file-storage-boundaries`(97초), `check:realtime-boundaries`, `check:realtime-boundaries:fixture`, `check:optional-recipes:source`, `check:optional-recipe-fixtures`, `check:registries:compatibility-fixtures`, `check:adapter-inventory`, `review:a11y-manual -- --format-only`. 드릴과 겹치는 `check:registries`·`check:i18n`·`check:design-system`·`check:diagnostics`·`verify:documentation`도 다시 돌렸다 | 모두 exit 0 |
| 기능 1개 | `test:http-scenario-evidence`(11초), `test:reference-feature`(11초), `test:recipes`, `check:scale:pr`(32초) | 모두 exit 0. `check:scale:pr`가 추적 로그를 바꿨다(12-08) |
| 기능 1개 | `build`, `check:bundle`, `check:app-build-input:bundle`, `check:optional-recipes` | 모두 exit 0. 초기 JS 202,446 / 204,800 B(기준 201,848, +598 B) |
| 기능 4개 | `build`, `check:bundle` | exit 0. 초기 JS 203,360 B(기능 1개 대비 +914 B) |
| 기능 4개 | P-A1: `playwright test --grep "@a11y /probe" --project chromium` | 4건 통과(12.2초) |
| 기능 4개 | P-A2: 임시 spec(`tests/e2e/zz-r12-probe.spec.ts`, 실행 뒤 삭제)이 a11y spec과 같은 흐름 뒤 `main` 글자와 콘솔을 모음 | `main` = "Probe \| create:feature가 만든 목록입니다. 제품 문구로 바꾸세요. \| 서버 응답 구조가 예상과 다릅니다. \| 지원 참조: …", 콘솔 0줄(12-03) |
| 기능 4개 | P-V4: `playwright test --config playwright.visual.config.ts` | **3건 실패**, 3건 통과: 넓은 셸 1,179 px, 좁은 서랍 4,016 px, 플랫폼 구성 1040×3814 → 1040×4878. 실패 맥락의 내비게이션에 `Probe`~`Probe four` 링크 4개(12-01) |
| 기능 1개 | P-V1: 같은 명령(기능 2~4를 지운 뒤, 같은 lock 안) | **3건 실패**: 넓은 셸 185 px, 좁은 서랍 3,106 px, 플랫폼 구성 1040×3964(12-01) |
| 기능 0개 | P-V0: 같은 명령(깨끗한 `e40684b`, 같은 lock 안) | 6건 통과(11.2초) |
드릴 밖 명령 수: 첫 행 13개 + 둘째 행 4개 + 셋째 행 3개(`build`는 드릴과 겹침) = 20개. 브라우저 명령은 `test:a11y`의 생성 경로 부분(P-A1, 통과)과 `test:visual`(P-V, 실패)만 돌렸다. 생성 기능 상태에서 돌리지 않은 merge 명령: FE-GATE-001 2개, FE-GATE-003 타입 음성 fixture 23개, `check:coverage:fixture`, 음성 fixture 기대 실패 7개, FE-GATE-008 7개 중 시각 1개 외, FE-GATE-009 `test:a11y` 전체, FE-GATE-011 `build:storybook`, FE-GATE-013 8개, FE-GATE-020의 다른 드릴 4개.
### 6.4 변이
| ID | 바꾼 것 | 기대 | 결과 |
|---|---|---|---|
| M2 | `eslint.config.ts` 운영 `src/presentation/**` 블록: layer import 금지를 별칭 금지만 남기고, `no-restricted-globals`에서 `fetch` 삭제 | `check:architecture` 실패 | **exit 0**, "9 forbidden rejected", 그래프 "28 regression checks PASS"(12-04) |
| M3 | `tests/unit/r12-orphan.spec.ts`(항상 실패) 추가, `git add -N` | `check:ci` 실패 | **exit 0**. `run-vitest.ts run <그 파일>`은 "include: tests/**/*.test.{ts,tsx}"를 출력하며 그 파일을 돌지 않는다(0929/12-06) |
| M4 | `src/features/reference-feature/support/direct-http.ts`(adapter 배럴에서 `createContractHttpExecutor` import)와 그것을 import하는 `src/features/reference-feature/presentation/r12-probe-leak.ts` 추가, `git add -N` | `check:architecture` 또는 ESLint 실패 | **둘 다 통과**. presentation이 layer 밖 폴더를 거쳐 adapter에 닿는다(0929/12-03) |
### 6.5 게이트 밖 검사
| 명령 | 결과 | 비고 |
|---|---|---|
| `node scripts/check-remediation-ledger.ts` | PASS, 0.2초 | "25 dispositions … 0 open". 산문 N-06~N-08은 읽지 않는다(12-05) |
| `corepack pnpm check:feature-index` | exit 0 | 예외 이유대로 로컬 확인용 |
| `check:scale:main`·`nightly`·`release`·`baseline`, `verify:extreme-scale`, `drill:runbooks`, `verify:promotion`, `check:test-evidence` | 돌리지 않음 | 기준 CPU 모델 전용이거나 승격 입력·브라우저 결과가 필요하다(예외 이유) |
@@ -0,0 +1,349 @@
# 13 — 빌드·릴리스·설정·공급망 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`
> 경로: `scripts/build-frontend.ts`, `scripts/generate-{runtime-config,build-manifest,supply-chain}.ts`, `scripts/check-release-admission.ts`, `scripts/verify-hosting-headers.ts`, `scripts/lib/{hosting-probe,build-environment,supply-chain,local-policy-evidence}.ts`, `scripts/contracts/ci-gates.ts`(배포 슬롯 부분), `scripts/generate-ci-workflow.ts`(배포 슬롯 렌더링), `vite.config.ts`, `vite.service-worker.config.ts`, `config/{release,hosting,runtime,security}/`, `config/ci/gates.json`(FE-GATE-019·027, `deployment` job), `src/contracts/{deployment-admission,env}.ts`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`
> 깊게 본 관점: 15, 16, 18, 19, 26
> 렌즈: 릴리스 승인과 라이브 probe의 후보 대조(`de379ea`) · 런타임 설정과 FE-REG-ENV(`d0414c8`, `ece944d`) · 정적 호스팅 HTTP/2 전제(`8c39e77`, `3f9c087`) · 의존성 감사(`pnpm audit`)
> 영역 판정(35.8): **조건부 사용 가능.** "빌드 → 공개 대상 승인 → 손으로 배포"는 그대로 써도 된다. 지난 라운드의 거짓 PASS(이전 release를 보고 통과)는 막혔다. **배포 슬롯을 채워 desktop 서버로 자동 배포(CD)하는 용도는 13-01을 고친 뒤에 쓴다.** 슬롯 계약이 승격 후보를 배포하라고 강제하지 않고, FE-GATE-019는 같은 run에서 다시 빌드한 로컬 프로필 release도 통과시킨다(실험 E-2c). **템플릿의 nginx 예시를 그대로 쓰면 HTTP/2와 압축이 모두 꺼진다(13-02).** 성능 예산과 청크 분할 판단은 둘 다 켜져 있다고 보고 쟀다. 지금 lockfile은 템플릿 자신의 취약점 정책(high 이상 차단)을 어기는데 merge·release 단계에서 그 사실을 알 길이 없다(13-03). 운영 승격 provider가 없으면 배포 슬롯까지 가지 못하는 지난 1101/13-03은 그대로 남았다.
## 0. 결론
- **지난 라운드 5건 중 4건이 고쳐졌다.** 1101/13-01(`de379ea`), 13-02(`7b34756`), 13-04(`629c8f0`), 13-05(`b3af26f`). 고친 규칙 6개를 하나씩 끄는 변이를 넣었더니 6개 모두 단위 테스트가 잡았다(6.2절 M1~M6). 0929/13-01(SW `ACTIVE` 빌드가 로컬 설정을 싣던 결함)도 `c7b9cb8`로 고쳐졌다. 1101/13-03(provider runner 전제)은 남았고, 배포 슬롯이 provider 뒤에 생기면서 영향이 커졌다.
- **FE-GATE-019가 "배포된 바이트가 승격 후보인가"를 아직 끝까지 보지 않는다(13-01, Medium, P1).** 대조하는 값은 `release-manifest.json`의 `buildId`·`releaseId` 둘이다. 이 둘은 workflow 전체 env의 run 번호로 만든 이름이다(`.gitea/workflows/quality-gates.yml:28-30`). 그래서 같은 run 안에서 다시 빌드한 release와 후보를 구분하지 못한다. 공개 대상 승인(FE-GATE-027)을 받은 파일인 `config.json`은 내용을 대조하지 않는다. 배포 슬롯 계약은 `download`·`extract` 없이 `deploy` 하나만 있어도 통과한다(실험 E-3). 실험 E-2c에서 `APP_ENV=local`, `AUTH_MODE=demo`, `API_BASE_URL=http://localhost:8080/`인 재빌드를 호스트에 올렸더니 FE-GATE-019가 `PASS (live)`로 끝났다.
- **HTTP/2 전제는 문서 한 단락뿐이고, 템플릿의 nginx 예시가 그 전제를 어긴다(13-02, Medium, P2).** `static-delivery.md:43`은 "HTTP/2 이상으로 서빙하라"고 적는다. 같은 템플릿의 nginx 예시는 `listen 443 ssl;`만 쓰고 `http2`도 `gzip`도 켜지 않는다(`release-cache-rollback.md:100-147`). 초기 JS는 압축 전 646,132 B, gzip 201,876 B다(3.2배). probe는 Node `fetch`를 써서 HTTP/2를 볼 수 없고(실험 E-4: 서버가 h2를 지원해도 `httpVersion=1.1`), `content-encoding`도 검사하지 않는다.
- **의존성 취약점 판정은 운영 승격의 외부 provider에만 있다(13-03, Medium, P1).** `pnpm audit`(2026-11-03, 네트워크 됨) 결과 advisory 44건: critical 1, high 16, moderate 23, low 4. 런타임 의존성은 `zod@4.4.3`(high), `react-router@7.18.1`(high, RSC 모드 전용이라 이 SPA에는 해당 없음 추정) 두 개다. 템플릿 정책은 `blockAtSeverity: "high"`, 예외 0건이다(`config/security/vulnerability-policy.json`). merge·release 단계에는 advisory를 보는 검사가 없고, 의존성 갱신 자동화(renovate 등)도 없다. 짝 백엔드 템플릿에는 `renovate.json`이 있다.
- **FE-REG-ENV는 키가 빠지는 것만 막는다(13-04, Low, P3).** `d0414c8`의 새 테스트는 설정 키마다 runtime 행이 있는지만 본다. 런타임 행 13개 중 5개는 `required`·`defaultValue`가 실제 스키마와 다르다(실험 E-5). 예: `AUTH_MODE` 행은 기본값 `"external"`인데 스키마에는 기본값이 없다.
- **이 영역의 테스트는 있는 규칙을 잘 지킨다.** 빠진 것은 규칙이다: 배포물 내용 대조, 슬롯의 후보 사용 강제, 압축·HTTP/2 확인, advisory 신호.
## 1. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 |
| 커밋·작업 상태·확인 시점 | `e40684b`(`review/2026-11-03-merged`, 두 작업 브랜치 합본). 분리 worktree `agent-a648a90bec4f23d25`를 `e40684b`로 detach하고 `corepack pnpm install --frozen-lockfile` 뒤 실험했다. 2026-11-03 23:00~24:00 |
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + SW(기본 `null`). 사용자 목표: 짝 백엔드 템플릿과 함께 빨리 출시하고 desktop 서버에 배포한다 |
| 필수 요구와 규모·운영 목표 | 수치 목표는 초기 JS 예산 204,800 gzip B(`config/performance/budgets.json:4`)뿐. 서빙 프로토콜 목표는 문서 한 줄("HTTP/2 이상", `docs/architecture/static-delivery.md:43`) |
| 읽은 코드·구성 범위 | 머리의 경로 전체. 그 밖에 `.gitea/workflows/quality-gates.yml`(env, `promotion`~`production_gate`), `scripts/run-and-validate-provider.ts:60-130`, `scripts/run-ci-gate.ts:60-110`, `scripts/update-dependency-baseline.ts`, `src/contracts/{release-artifacts,product-contracts}.ts`(설정 스키마·제품 행), `config/contracts/registry-governance.json`(FE-REG-ENV), `tests/unit/{hosting-probe,deployment-admission,env-registry-coverage,build-environment-bundle}.test.ts`. 주장 자료: `README.md:24-75`, `:255-266`, `:376-381`, `.env.example`, `docs/operations/{ci-quality-gates,release-cache-rollback,performance-evidence}.md`, `docs/architecture/static-delivery.md`, `docs/runbooks/FE-RB-001.md`, 커밋 본문 `de379ea`, `d0414c8`, `ece944d`, `8c39e77`, `3f9c087` |
| 수행한 테스트·실험 | 게이트는 오케스트레이터 결과(`scratchpad/review-gates/summary.txt`, 같은 커밋)를 읽었다. 직접 실행: E-1 빌드 4회(flock), E-2 실제 `verify-hosting-headers.ts`를 가짜 호스트(fetch 교체)로 4회, E-3 CI 계약 변이, E-4 Node fetch 프로토콜·압축 확인, E-5 FE-REG-ENV·스키마 대조, E-6 공개 대상 승인 함수 호출, E-7 `pnpm audit`, M1~M6 규칙 변이. 상세는 6절 |
| 확인하지 못한 범위·이유 | 실제 Gitea runner 실행, 실제 HTTPS 호스트(nginx)에서 probe·HTTP/2·압축, provider 실행, 브라우저 부팅(E-2c의 로컬 프로필 release), HTTP/1.1·비압축 첫 화면 시간 재측정, zod advisory의 실제 도달 가능성. 6.3절 |
| 이전 리뷰와 비교 가능한 범위 | `2026-11-01-maturity-review/13-build-release-supply-chain.md`의 새 발견 5건과 그 문서 2절이 다시 판정한 0929 발견 10건, FOLLOW-UP, R-1~R-5. 지난 실험 결과는 증거로 쓰지 않았다 |
### 1.1 게이트 결과 중 이 영역에 해당하는 것 (오케스트레이터 실행, `e40684b`)
| 게이트 | 결과 | 이 영역에 주는 의미 |
|---|---|---|
| `test:unit` | rc=0, 2,580 통과 | `hosting-probe`(26), `deployment-admission`(25), `env-registry-coverage`(1), `ci-workflow-generation`(423) 포함. 이 넷은 직접도 돌렸다(6.2절) |
| `check:ci` | rc=0, "27 gates, strict v2 graph … PASS" | 계약과 생성 workflow가 맞다. 배포 슬롯은 비어 있다 |
| `build` | rc=0, local 프로필, SW `null` | `runtime config: local profile written` |
| `bundle` | rc=0, 초기 JS 201,848 / 204,800 gzip B | 여유 2,952 B(지난 라운드 마지막 984 B) |
| supply chain(`bundle` 로그) | `LOCAL PASS (561 dependencies); promotion=FAIL_UNVERIFIED` | 취약점 판정은 로컬에 없다(13-03) |
## 2. 지난 발견 재판정
### 2.1 1101 라운드 발견
| ID | 내용 | 판정 | 현재 근거 |
|---|---|---|---|
| 1101/13-01 | 운영 단계 검사가 배포된 release를 후보와 대조하지 않고 배포 job 자리가 없다 | **고쳐짐(일부 남음 → 이번 13-01)** | probe가 배포된 manifest의 `buildId`·`releaseId`를 후보와 비교한다(`scripts/lib/hosting-probe.ts:128-137`). FE-GATE-019는 다시 빌드하지 않고 후보를 본다(`config/ci/gates.json:506-514`의 `--release-root .release/promoted-release`). `promotion`과 `production_gate` 사이에 `deployment` 슬롯이 있고 비어 있으면 `UNVERIFIED`(exit 3)다(`.gitea/workflows/quality-gates.yml:369-391`, `scripts/verify-hosting-headers.ts:77-81`, `:205-210`). 실험 E-2b: 이전 release(run 76)를 띄운 호스트 → FAIL(build-id·release-id 불일치). 변이 M1·M3 검출. **남은 것:** 대조 값이 run 이름뿐이고 `config.json` 내용과 슬롯의 후보 사용을 보지 않는다(이번 13-01) |
| 1101/13-02 | 공개 대상 승인이 `*.example.com` 자리표시자를 통과시킨다 | **고쳐짐** | `src/contracts/deployment-admission.ts:159-181` 예약 이름 거절. README 예시가 `<your-api-origin>`으로 바뀌었고 CI에서는 프로필 커밋이 유일한 방법이라고 적었다(`README.md:54-75`). 실험 E-6: 동봉 staging·production 프로필이 각각 `API_BASE_URL`·`TELEMETRY_ENDPOINT` 2건으로 거절. 변이 M2 검출. 남은 작은 틈: 한 단어 호스트 `test`는 통과한다(`.test`만 막음). 실제로 쓰일 일이 없어 발견으로 세지 않는다 |
| 1101/13-03 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고 provider 없는 배포 경로가 없다 | **남음(영향 커짐)** | provider job은 여전히 `runs-on: ubuntu-latest`(workflow `:208`, `:254`)이고 문서는 이 label을 컨테이너 image에 매핑하라고 적는다(`docs/operations/ci-quality-gates.md:294-296`). 전제 검사(`scripts/run-and-validate-provider.ts:77-125`)는 그대로다. "provider 없이 배포할 때" 절이 없다(`docs/operations`·`README.md` grep). **바뀐 점:** 배포 슬롯이 `needs: [immutable_build, promotion]`이라(workflow `:371`) provider가 없으면 슬롯까지 가지 못한다. 이 템플릿이 지원하는 CD 경로는 provider 두 개·서명 키·호스트 모드 runner가 있어야만 열린다. 우선순위를 P2 → **P1**로 올린다(사용자 목표의 CD 자동화를 막는다). 심각도는 Medium 유지(fail-closed라 틀린 것이 나가지는 않는다) |
| 1101/13-04 | 호스팅 계약이 SPA fallback·SW 스크립트 헤더를 선언·검사하지 않는다 | **고쳐짐** | `config/hosting/cache-policy.json`에 `appRoute`(`/__probe/deep-link`)와 `serviceWorker`(`requiredWhen: service-worker-shipped`) 표면. probe가 fallback 응답의 entry script를 `index.html`과 비교한다(`hosting-probe.ts:138-147`). SW 표면은 SW를 싣는 빌드에서만 요구한다(`verify-hosting-headers.ts:84-88`). 단일 서버용 nginx 예시가 생겼다(`docs/operations/release-cache-rollback.md:83-149`). 변이 M6 검출. **남은 것:** 그 예시가 HTTP/2·압축을 켜지 않는다(이번 13-02) |
| 1101/13-05 | 재빌드 없는 설정 변경에 검증 명령·절차가 없다 | **고쳐짐** | `check:release-admission --config <edited> --original <deployed>`가 비상 스위치 두 개 밖의 필드 변경을 거절한다(`scripts/check-release-admission.ts:34-43`, `:114-138`). 런북 4단계(`docs/runbooks/FE-RB-001.md`). `.env.example:8-11`이 "비상 스위치만"으로 좁혀졌다. 변이 M4 검출. 실제 호스트에서 문서를 바꿔 부팅해 보지는 않았다 |
### 2.2 1101 문서가 다시 판정한 0929 발견
| ID | 내용 | 판정 | 현재 근거 |
|---|---|---|---|
| 0929/13-01 (= 06-01) | SW `ACTIVE` 빌드가 프로필 대신 로컬 설정을 싣는다 | **고쳐짐** | `vite.service-worker.config.ts:71-74` `publicDir: false`(`c7b9cb8`). `build:app-only`는 지워졌다(`package.json` grep 0건). 이번에 SW `ACTIVE` 빌드는 돌리지 않았다. 막는 테스트 `tests/unit/service-worker-build-output.test.ts`는 오케스트레이터 `test:unit`에서 통과(E2) |
| 0929/13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:16`만 `loadEnv`를 쓰고(미선언 변수 거절용), asset base는 `:143` `process.env`다. `generate-runtime-config.ts:59`, `:70-74`, `generate-build-manifest.ts:36-38`, `vite.service-worker.config.ts:58-59`도 `process.env`. 번들은 `import.meta.env`로 `.env*` 값을 읽는다(`src/contracts/env.ts:154-160`). `.env.example:14`는 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다. 정적 확인(E1), 이번에 재현 빌드는 하지 않았다 |
| 0929/13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **바뀜(일부 고쳐짐)** | 테스트는 이름 대신 내용(`ui-button--pending`)으로 청크를 찾는다(`tests/unit/build-environment-bundle.test.ts:68-79`). route chunk 대조는 여전히 `entry.name === runtime.moduleId`다(`scripts/generate-build-manifest.ts:64-72`). 어긋나면 `Missing built route chunk`로 빌드가 멈춘다(fail-closed). Low 유지 |
| 0929/13-04 | 운영 CSP 확장 안내·내용 검사 없음, 여러 벌 복사 | **남음(복사본 증가)** | 같은 CSP 문자열이 6곳이다: `config/hosting/security-headers.json` 1, `response-headers.fixture.json` 4(`appRoute` 추가로 1벌 늘었다), nginx 예시 1(`release-cache-rollback.md:92`). fixture 4벌은 fixture 모드에서 정책과 비교되지만 nginx 예시는 아무것도 비교하지 않는다. `scripts/check-browser-security.ts`에 CSP 내용 검사가 없다(grep 0건) |
| 0929/13-05 | SBOM이 `deduped` 노드를 따라가지 않는다 | **남음** | `scripts/lib/supply-chain.ts`에 `deduped` 0건. 기준선 production 행 10개에 `scheduler`(react-dom 의존)가 없다(`config/security/dependency-baseline.json`) |
| 0929/13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳 | **일부 고쳐짐** | SW 사전 캐시·설정 URL은 base를 따른다(`85d55e0`, `vite.service-worker.config.ts:99-105`). live probe는 여전히 루트가 아닌 URL을 거절해(`hosting-probe.ts:245-252`) 하위 경로 배포는 FE-GATE-019를 통과할 수 없다 |
| 0929/13-07 | 청크 설정이 폐기 예정 별칭 `build.rollupOptions`에 있다 | **남음** | `vite.config.ts:151`, `vite.service-worker.config.ts:79`. `node_modules/vite/dist/node/index.d.ts:859-862`에 `@deprecated Use rolldownOptions` |
| 0929/13-08 | pnpm 설치 정책을 지키는 검사가 없다 | **일부 고쳐짐** | `pnpm-workspace.yaml`의 `engineStrict`·`saveExact`가 실제로 적용된다(`corepack pnpm config get` → `true`, `true`). pnpm 11은 `minimumReleaseAge` 기본 1440분(느슨한 모드)이다(pnpm 11.17.0 CHANGELOG). 이 설정이 빠지거나 바뀌면 실패하는 검사는 여전히 없다(`scripts`·`tests` grep). Low 유지 |
| 0929/13-09 | README 변수 표에 staging·production의 `VITE_BUILD_ID` 필수 조건이 없다 | **남음** | `README.md:46` 기본값 `local-build`만. 같은 규칙은 `src/contracts/env.ts:45-48` 주석과 `generate-runtime-config.ts:70-72`에 있다 |
| 0929/13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | `README.md:376-381` "unmodified checkout" 문구 그대로 |
### 2.3 FOLLOW-UP·리팩토링 후보
| 항목 | 판정 | 근거 |
|---|---|---|
| 초기 JS 예산 여유 | **나아짐** — 201,848 / 204,800, 여유 2,952 B | 오케스트레이터 `bundle.log`. 실험 E-1a 후보 빌드는 201,876 B(같은 계산, 다른 build id) |
| 레시피 번들 예산 | 미재측정 | 이번에 돌리지 않았다 |
| R-1 `build:app-only` 제거 | 고쳐짐 | `98b9682`, `package.json` grep 0건 |
| R-2 빌드 입력 기본값을 한 곳에서 | 남음 | `generate-runtime-config.ts:73`(`\|\|`)·`:74`(`??`), `generate-build-manifest.ts:36`(`??`), `vite.service-worker.config.ts:58`(`??`), `src/contracts/env.ts:162`(`\|\|`) |
| R-3 CSP 한 벌 | 남음 | 0929/13-04 |
| R-4 FE-GATE-019의 재빌드 제거 | 고쳐짐 | `de379ea` |
| R-5 `rollupOptions` → `rolldownOptions` | 남음 | 0929/13-07 |
## 3. 이번 발견 (36.3)
### 3.1 렌즈별 확인 결과
| 렌즈 | 확인한 것 | 결과 |
|---|---|---|
| 후보 대조(`de379ea`) | 이전 release 호스트(E-2b), 후보 호스트(E-2a), 같은 run 재빌드 호스트(E-2c·E-2d), 슬롯 계약 변이(E-3), 규칙 변이 M1·M3·M5 | 이전 release는 막는다. 같은 run의 재빌드·로컬 프로필은 막지 못한다 → **13-01**. 슬롯 secret 노출 범위 → **13-05** |
| 런타임 설정·FE-REG-ENV(`d0414c8`, `ece944d`) | 새 커버리지 테스트, 제품 행 합치기, 행·스키마 대조(E-5) | 키 누락은 막는다. 행 값이 스키마와 달라도 모른다 → **13-04**. 제품 키가 템플릿 키 이름을 쓰면 모듈 로드 때 throw한다(`env.ts:80-90`) |
| HTTP/2 전제(`8c39e77`, `3f9c087`) | 전제 문서, nginx 예시, probe 전송 계층(E-4), 초기 JS 압축 전후 크기 | 예시가 전제를 어기고 probe가 볼 수 없다. 압축도 같은 상태다 → **13-02** |
| 의존성 감사 | `pnpm audit --json`(E-7), 취약점 정책·로컬 보고서, 갱신 자동화 | 네트워크 됨. 44건. 정책 위반 상태를 승격 전에 알 수 없다 → **13-03** |
### 3.2 발견 목록
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 한 줄 |
|---|---|---|---|---|---|
| 13-01 | Medium | P1 | 확인된 결함 | 18, 21, 15, 19, 5, 28 | FE-GATE-019가 run 이름만 대조하고 `config.json` 내용과 슬롯의 후보 사용을 보지 않아 같은 run 재빌드를 통과시킨다 |
| 13-02 | Medium | P2 | 확인된 결함 | 14, 18, 19, 20, 21, 5 | HTTP/2·압축 전제가 호스팅 계약·probe에 없고, 템플릿 nginx 예시가 둘 다 켜지 않는다 |
| 13-03 | Medium | P1 | 확인된 결함 | 16, 15, 26, 21, 5 | 취약점 판정이 운영 승격 provider에만 있다. 지금 lockfile은 자체 정책을 어기는데 merge·release에서 모른다 |
| 13-04 | Low | P3 | 확인된 결함 | 19, 17, 23, 9 | FE-REG-ENV 런타임 행 13개 중 5개의 `required`·`defaultValue`가 스키마와 다르고 대조 검사가 없다 |
| 13-05 | Low | P3 | 개선 제안 | 15, 18, 26 | 채운 배포 슬롯의 `secrets.*`가 job 전체 env로 렌더링돼 checkout·setup-node·download action에도 보인다 |
### 13-01 FE-GATE-019가 run 이름만 대조하고 `config.json` 내용과 슬롯의 후보 사용을 보지 않아, 같은 run에서 다시 빌드한 release를 통과시킨다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-01(라운드 밖: `1103/13-01`) — 위 제목 |
| 성격 | 확인된 결함. 계약이 허용하는 슬롯 구성에서 게이트의 주장("checks that the host serves that release", `docs/architecture/static-delivery.md:35-36`)이 틀린 PASS를 낸다는 것을 실험으로 확인했다 |
| 관련 관점 | 18, 21, 15, 19, 5, 28 |
| 근거 | **대조 값:** probe는 배포된 manifest의 `buildId`·`releaseId` 두 값만 후보와 비교한다(`scripts/lib/hosting-probe.ts:128-137`). 두 값은 workflow 전체 env에서 온다: `VITE_BUILD_ID: "gitea-${run_id}-${run_attempt}"`, `RELEASE_ID: "${ref}-${run_id}-${run_attempt}"`(`.gitea/workflows/quality-gates.yml:28-30`). 빌드는 이 값을 그대로 쓴다(`scripts/generate-build-manifest.ts:36-38`, `scripts/generate-runtime-config.ts:73-76`). 같은 run의 어느 job에서 빌드해도 같은 이름이 나온다. **내용 미대조:** probe는 `/config.json`을 받지만 헤더만 본다(`scripts/verify-hosting-headers.ts:127-163`). 공개 대상 승인(FE-GATE-027)을 받은 것은 후보의 `config.json`이다. 호스트가 내주는 `config.json`은 승인을 거치지 않는다. **슬롯 계약:** `deployment` job에 허용된 단계는 `checkout`, `setup-node`, `frozen-install`, `download`, `extract`, `deploy`다(`scripts/contracts/ci-gates.ts:1257`). 강제하는 것은 "마지막이 `deploy` 하나"뿐이다(`:1265-1269`). `download`(promoted-release)와 검증된 `extract`(`verify-ci-candidate-archive.ts`)는 요구하지 않는다. 문서도 허용 목록만 적는다(`docs/operations/ci-quality-gates.md:340-349`). **실험 E-3:** 슬롯을 `checkout → setup-node → frozen-install → deploy(script: build)`로 채우고 env에 `APP_PROFILE: ${{ vars.APP_PROFILE }}`을 넣었다. `generate-ci-workflow` → `check-ci-contract.ts` PASS, `generate-ci-workflow --check` PASS. 생성된 job 이름은 그대로 `deploy-promoted-release`, 단계 이름은 "Deploy the promoted release"다. **실험 E-2c:** 후보 = `APP_PROFILE=production`, run 77 빌드(승인 `ADMITTED`). 호스트 = 같은 run 77 이름으로 `APP_PROFILE` 없이 다시 빌드한 `dist`(`APP_ENV=local`, `AUTH_MODE=demo`, `API_BASE_URL=http://localhost:8080/`). 실제 `scripts/verify-hosting-headers.ts`를 `HOSTING_BASE_URL=https://desktop.r13-review.dev/`, `RELEASE_DEPLOYED=true`, `--release-root <후보>`로 돌리고 전역 `fetch`만 가짜 호스트로 바꿨다. 결과 `Hosting header contract: PASS (live)`, rc=0, 실패 항목 0개. 대조군 E-2b(run 76 production 호스트)는 FAIL(build-id·release-id) |
| 발생 조건 | 프로젝트가 배포 슬롯을 채우면서 (a) 슬롯 안에서 다시 빌드하거나, (b) 후보 archive가 아닌 다른 경로(로컬 `dist`, 수동 업로드)로 올리거나, (c) 배포 스크립트가 일부 파일(`config.json`)만 다른 버전으로 남길 때. 손으로 FE-GATE-019를 돌리는 운영자가 `--release-root`에 후보가 아닌 같은 이름의 빌드를 줄 때도 같다. CI에서 `pnpm build`를 그냥 부르면 `SOURCE_DATE_EPOCH`가 없어 실패한다(`scripts/lib/build-environment.ts:1-16`. 이 값은 `run-ci-gate.ts:68-84`만 채운다). 그래서 (a)는 프로젝트가 그 변수를 직접 채운 경우에 생긴다 |
| 영향 | 운영 호스트가 승인받지 않은 설정(로컬 프로필, demo 인증, loopback API)을 내주는데 운영 단계 hosting 게이트가 초록이다. 사용자는 첫 부팅에서 API 실패를 본다. 서버 인가가 별도라 데이터 노출은 없다고 추정한다(`README.md` "server authorization remains authoritative"). 배포 검증의 핵심 질문(가이드 18절 1번)에 다시 틀린 답이 나온다. 템플릿 복사본 모두가 같은 틈을 받는다 |
| 심각도·우선순위 | Medium · P1 — 나가는 순간 보이는 장애라 피해 시간은 짧다. 대신 슬롯을 채우는 일(CD 자동화, 사용자 로드맵)의 바로 그 지점에서 게이트가 거짓 PASS를 낸다. 고치는 비용이 작아 슬롯을 채우기 전에 고친다 |
| 통제·증거 | 이전 release 거절 M3(변이 M1, E2·E3) / 후보 바이트 대조 M0 / 슬롯의 후보 사용 강제 M0(문서 M1) · E3(실험 E-2c, E-3) + E1 |
| 확실성과 남은 가정 | 실험은 실제 검사 스크립트를 썼고 바꾼 것은 전송 계층(`fetch`)뿐이다. 실제 Gitea runner와 실제 nginx에서는 돌리지 않았다. 프로젝트가 슬롯을 실제로 어떻게 채울지는 모른다. 깨끗한 작업 트리에서 같은 커밋을 다시 빌드하면 `config.json`·`release-manifest.json` 밖의 파일이 후보와 같았다(E-2d). 그래서 `assetManifestHash`나 entry script 비교로는 E-2c를 잡지 못하고 `config.json` 비교만 잡는다 |
| 결정의 근거 | 확인한 사실: probe의 대조 값은 run 이름이고 슬롯 계약은 단계 종류만 제한한다. 기록된 의도: "requires the live host to serve a `release-manifest.json` with the candidate's `buildId` and `releaseId`, so a host still serving an earlier release fails"(`ci-quality-gates.md:334-338`) — 막으려던 것은 "이전 release"였다. 리뷰어 추론: 같은 run의 다른 빌드는 설계 때 고려하지 않았다. 5.1절에서 대안을 비교한다 |
| 이해 비용 | 슬롯을 채우는 사람은 "deploy 단계가 후보를 배포해야 한다"를 계약·이름(`deploy-promoted-release`)에서 추측해야 한다. 어겨도 아무것도 실패하지 않는다 |
| 최소 개선 방향 | (1) probe가 받은 `/config.json`을 후보의 `dist/config.json`과 비교한다. 비상 스위치 두 개(`CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`)를 뺀 필드가 다르면 FAIL. `check-release-admission.ts:40-43`, `:70-80`의 `EMERGENCY_SWITCHES`·`changedBuildFields`를 공용 함수로 옮겨 같이 쓴다. (2) 받은 `index.html`의 entry script를 후보 `index.html`의 entry script와도 비교한다(지금은 호스트 자신의 두 응답끼리만 비교, `hosting-probe.ts:138-147`). 다른 커밋이 같은 이름으로 올라온 경우를 잡는다. (3) 슬롯 계약에 "`deploy`가 `script`를 가지면 그 앞에 `download`(transferId promoted-release)와 `extract`가 있어야 한다"를 넣는다 |
| 대안 비교 | (a) 현상 유지 — 문서의 주장과 동작이 다시 어긋난다. (b) (3)만 — 슬롯이 후보를 받게는 하지만 deploy 스크립트가 받은 파일을 쓰는지는 모른다. (c) (1)(2)만 — 호스트가 내주는 결과를 보므로 배포 방법과 무관하게 잡는다. (d) (1)~(3) — 결과 검사와 입력 강제를 둘 다 한다. 5.1절 |
| 단순화의 보존 조건 | 이전 release 거절(M1), 빈 슬롯 `UNVERIFIED`(M3), fixture 모드 `UNVERIFIED`, SPA fallback 비교(M6), 슬롯 env 제한(M5)을 유지한다. 비상 스위치만 바꾼 뒤 다시 probe하면 통과해야 한다(FE-RB-001 절차와 충돌하지 않기) |
| 비용·부작용 | (1)(2)는 probe에 비교 두 개와 테스트 몇 건. (3)은 계약 규칙 한 줄과 `ci-workflow-generation` 테스트. 아직 슬롯을 채운 다운스트림은 없다(`de379ea` 이후 이식 전) |
| 재검토 조건 | 템플릿이 단일 호스트용 배포 스크립트를 직접 제공하면 (3) 대신 그 job을 고정한다. 배포 단위가 archive SHA로 식별되는 호스팅(객체 저장소 버전 등)을 쓰게 되면 archive SHA 대조로 바꾼다 |
| 완료 기준 | E-2c를 다시 돌리면 FE-GATE-019가 `runtimeConfig` 필드 차이로 FAIL한다. E-3의 슬롯 구성이 `check:ci`에서 실패한다. 비상 스위치만 바꾼 `config.json`을 내주는 호스트는 PASS한다 |
| 검증 방법 | `tests/unit/hosting-probe.test.ts`에 "manifest 이름은 같고 config.json의 APP_ENV가 다르다 → FAIL", "비상 스위치만 다르다 → PASS" 케이스. `tests/unit/ci-workflow-generation.test.ts`에 "extract 없는 deploy(script) → 계약 실패" 케이스. 실제 runner 1회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 13-02 HTTP/2·압축 전제가 호스팅 계약과 probe에 없고, 템플릿의 nginx 예시가 둘 다 켜지 않는다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-02(`1103/13-02`) — 위 제목 |
| 성격 | 확인된 결함. 템플릿이 적은 서빙 전제와 템플릿이 준 참조 설정이 서로 어긋난다 |
| 관련 관점 | 14, 18, 19, 20, 21, 5 |
| 근거 | **전제:** "Serve the app over HTTP/2 or later. … Over HTTP/1.1 they queue for six connections per host, and the first screen on Fast 3G came about one second later"(`docs/architecture/static-delivery.md:43-51`). `vite.config.ts:162-167` 주석이 초기 청크 25개 분할의 근거로 HTTP/2를 든다. 측정 기록도 gzip 응답으로 쟀다(`docs/operations/performance-evidence.md:114-125`). 예산은 gzip 바이트다(`config/performance/budgets.json:4` `initialJsGzipBytes`). **참조 설정:** nginx 예시는 `listen 443 ssl;`이고(`docs/operations/release-cache-rollback.md:102`) `http2`·`gzip`·`gzip_types`·`brotli`·`gzip_static`이 없다(`:83-149`, grep 0건). nginx는 HTTP/2와 gzip을 켜지 않으면 쓰지 않는다. Debian·Ubuntu 기본 `nginx.conf`는 `gzip on`이지만 `gzip_types`가 주석이라 `text/html`만 압축한다(리뷰어 지식, 이번에 확인 안 함). **크기:** 실험 E-1a 후보의 초기 JS 25개 파일은 압축 전 646,132 B, gzip 201,876 B(3.20배). **검사 없음:** `config/hosting/cache-policy.json`에 압축·프로토콜 항목이 없다. probe는 Node 전역 `fetch`를 쓴다(`hosting-probe.ts:72`). 실험 E-4: h2와 HTTP/1.1을 둘 다 받는 로컬 HTTPS 서버에서 `fetch`는 `httpVersion=1.1`로 왔고 `accept-encoding: br, gzip, deflate`를 보냈다. 같은 서버에 `http2.connect`는 ALPN `h2`. `fetch` 응답은 `content-encoding` 헤더를 그대로 보여 준다. 즉 probe가 이미 받는 헤더로 압축은 검사할 수 있고, HTTP/2는 `node:http2`로 따로 확인해야 한다. `3f9c087` 본문도 "호스팅 HTTP 버전을 검사하는 게이트는 없다"고 적었다 |
| 발생 조건 | 프로젝트가 desktop 서버의 nginx에 템플릿 예시를 그대로 옮길 때. 사용자의 목표 배포 경로다. 짝 백엔드 템플릿에는 프론트 호스팅 설정이 없어(`clean-architecture-backend-template`의 nginx 설정은 fileserver·websocket 테스트용뿐) 이 예시가 유일한 참조다 |
| 영향 | 모든 첫 방문자가 초기 JS를 압축 없이 약 444 KB 더 받고, 26개 요청을 연결 6개로 나눠 받는다. 계산상 Fast 3G(180,000 B/s)에서 내려받기만 약 2.5초 늘고, 측정 기록상 HTTP/1.1 줄서기 비용이 약 1초다(두 값은 함께 잰 적이 없어 더하지 않는다). 기능은 정상이라 아무도 실패로 보지 않는다. FE-GATE-019는 PASS한다 |
| 심각도·우선순위 | Medium · P2 — 기능 실패가 아니라 성능 저하다. 대신 복사되는 참조 설정에서 조용히 생기고, 템플릿이 성능 판단(청크를 묶지 않음)의 근거로 삼은 전제를 스스로 깨뜨린다. 고치는 비용이 몇 줄이다 |
| 통제·증거 | HTTP/2 전제 M1(문서) / 압축 전제 M0(문서에도 없음) / 검사 M0 · E3(실험 E-4) + E1(예시·계약) + 크기 측정 E3. 실제 nginx·브라우저 시간 미측정 |
| 확실성과 남은 가정 | 예시가 HTTP/2·gzip을 켜지 않는다는 것은 문서 본문으로 확인했다. nginx 기본 동작과 배포판 기본 설정은 리뷰어 지식이고 이 기계에서 nginx를 띄워 보지 않았다. 첫 화면 시간 증가는 계산과 기존 측정 기록이며 이번에 재지 않았다 |
| 결정의 근거 | 확인한 사실: 청크 분할 유지 결정(`3f9c087`)이 HTTP/2를 전제로 한다. 기록된 의도: "HTTP/1.1로만 서빙해야 하는 제품은 초기 청크를 묶는 그룹을 넣는다"(`performance-evidence.md:157-159`) — 제품이 자기 프로토콜을 안다고 가정했다. 리뷰어 추론: 제품은 대개 예시를 복사하므로 예시가 그 전제를 지켜야 한다 |
| 이해 비용 | 서버를 설정하는 사람이 `static-delivery.md` 끝 단락, `performance-evidence.md`, nginx 예시를 함께 읽어야 어긋남을 안다. 압축은 어디에도 없다 |
| 최소 개선 방향 | (1) nginx 예시에 `http2 on;`(nginx 1.25.1 이상, 그 전 버전은 `listen 443 ssl http2;`)과 `gzip on; gzip_types text/javascript application/javascript application/json text/css;`(또는 빌드에서 `.gz`를 만들고 `gzip_static on;`)을 넣는다. (2) `cache-policy.json`의 `hashedAsset`에 허용 `content-encoding`(`br`, `gzip`)을 선언하고 probe가 entry script 응답에서 확인한다(받은 헤더에 이미 있다). (3) probe가 `node:http2`로 base URL에 붙어 ALPN이 `h2`인지 기록한다. FAIL로 할지 기록만 할지는 5.2절 판단을 따른다 |
| 대안 비교 | (a) 현상 유지. (b) 초기 청크를 묶어 HTTP/1.1에서도 빠르게 한다 — `3f9c087`이 숨은 결합(고정 목록)이라 기각했다. 압축 문제는 그대로 남는다. (c) 예시만 고친다 — 가장 싸지만 다른 호스트(caddy는 기본으로 h2·압축을 켬, 직접 만든 node 서버는 둘 다 끔)를 쓰는 프로젝트는 여전히 모른다. (d) (1)~(3) — 예시와 검사가 같은 전제를 말한다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 예시 몇 줄과 probe 검사 하나. 압축을 앞단(CDN)이 맡는 구성에서도 probe는 최종 응답을 보므로 그대로 맞다. `gzip_static`을 고르면 빌드에 압축 단계가 하나 는다 |
| 재검토 조건 | HTTP/3 전용 호스팅이나 예산 계산 방식(gzip → brotli)이 바뀌면 선언 값을 다시 정한다. 초기 청크 수가 크게 줄면 HTTP/2 확인을 기록만으로 낮춘다 |
| 완료 기준 | 예시 설정의 호스트에 probe를 돌리면 entry script가 압축되어 오고 ALPN이 `h2`로 기록된다. 압축을 끈 호스트에서 FE-GATE-019가 FAIL한다 |
| 검증 방법 | `hosting-probe.test.ts`에 "content-encoding 없음 → FAIL" 케이스. 실제 nginx(desktop 서버)에 예시를 올리고 live probe 1회 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 13-03 의존성 취약점 판정이 운영 승격 provider에만 있고, 지금 lockfile이 템플릿 자신의 정책을 어기는데 merge·release에서 알 수 없다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-03(`1103/13-03`) — 위 제목 |
| 성격 | 확인된 결함. 정책(high 이상 차단, 예외 0건)과 현재 lockfile 상태가 어긋나는 것을 실행 결과로 확인했고, 그것을 승격 전에 드러내는 장치가 없다 |
| 관련 관점 | 16, 15, 26, 21, 5 |
| 근거 | **정책:** `config/security/vulnerability-policy.json` — `providerMode: external-file`, `blockAtSeverity: high`, `missingProviderStatus: FAIL_UNVERIFIED`. `vulnerability-exceptions.json`은 빈 목록. 판정 함수는 high 이상이고 유효한 예외가 없으면 막는다(`scripts/lib/supply-chain.ts:440-492`). **로컬:** `createLocalVulnerabilityReport`는 스캔하지 않고 `provider: UNCONFIGURED`, `findings: []`를 만든다(`scripts/lib/local-policy-evidence.ts:42-53`). 게이트 출력은 `LOCAL PASS … promotion=FAIL_UNVERIFIED`(오케스트레이터 `bundle.log`). merge·release 게이트에 advisory를 보는 명령이 없다(`config/ci/gates.json`·`package.json`·`scripts/`에서 `audit`·`osv` grep 0건). 갱신 자동화 파일이 없다(`renovate.json`·dependabot 없음). 짝 백엔드 템플릿에는 `renovate.json`이 있다. **실행(E-7, 2026-11-03, `corepack pnpm audit --json`, rc=1):** 561개 의존성에서 advisory 44건 — critical 1, high 16, moderate 23, low 4. 런타임(`dev=false`) 두 개: `zod@4.4.3` high GHSA-mrhx-c7xc-m3w5(제한이 걸린 큰 컬렉션 검증 중 메모리 고갈, 4.6.6에서 수정), `react-router@7.18.1` high GHSA-qwww-vcr4-c8h2(RSC 모드 CSRF, 7.18.2에서 수정). 개발 전용: `storybook@10.5.4` critical GHSA-f2ph-cmg5-wxc8와 high GHSA-px85-f4q5-jh77(dev 서버 코드 주입), `vite@8.1.5` 5건(high 1, 8.1.6에서 수정), `vitest`·`@vitest/mocker@4.1.10` 3건, `undici@7.28.0`(jsdom 경유) 20건(high 6), `brace-expansion@5.0.8` 4건(high 3), `nanoid@3.3.16` high, `source-map-js@1.2.1` high, `postcss`·`minimatch`·`glob` moderate |
| 발생 조건 | 항상. 템플릿에서 새 프로젝트를 만들면 이 lockfile을 그대로 받는다. provider를 붙이면 승격에서 처음 막힌다(provider가 lockfile 전체를 판정한다면). provider를 붙이지 않으면 아무 데서도 알려 주지 않는다 |
| 영향 | 런타임: `zod` advisory는 브라우저에 실리는 코드다. 이 앱은 HTTP 응답 바이트에 상한이 있어(`src/adapters/http/http-execution-v3.ts:507-508` `readBoundedBytes`) 큰 컬렉션이 들어올 길이 좁다(추정, 미확인). `react-router`는 RSC 모드 전용이라 `createBrowserRouter` SPA에는 해당하지 않는다고 본다(추정). 개발: storybook·vite dev 서버 advisory는 개발자 기계에서 dev 서버를 띄울 때의 위험이다. 운영: provider를 붙인 프로젝트는 첫 운영 승격에서 high 이상 17건으로 막힌다. 갱신하려면 직접 production 의존성 변경 증거(owner ≠ reviewer, `supply-chain.ts:389-430`)나 기준선 재승인이 필요하다 |
| 심각도·우선순위 | Medium · P1 — 실제 런타임 피해는 작다고 추정한다. 대신 템플릿이 복사될 때마다 알려진 advisory가 그대로 퍼지고, 템플릿 자신의 차단 정책이 승격 전에는 아무 신호도 주지 않는다. 갱신 비용이 작아 다음 다운스트림 동기화 전에 한다 |
| 통제·증거 | 승격 시 차단 M3(판정 함수·테스트) / merge·release 신호 M0 / 갱신 경로 M1(기준선 스크립트) · E3(`pnpm audit`, 실제 advisory DB) + E1. advisory 도달 가능성은 미확인 |
| 확실성과 남은 가정 | advisory 목록은 실행 시점의 DB 결과다. 외부 provider가 dev 의존성까지 판정하는지는 provider마다 다르다(이 repo에는 provider가 없다). 위 "해당 없음" 판단 두 개는 코드 경로를 다 따라가지 않은 추정이다 |
| 결정의 근거 | 확인한 사실: 판정 주체를 빌드 주체와 떼려고 외부 provider + 서명으로 설계했다(1101 5.2). 리뷰어 추론: 그 설계는 "승격의 증거"로는 맞지만, 개발 중에 알려진 advisory를 일찍 보는 신호까지 대신하지 않는다. 5.3절 |
| 이해 비용 | 의존성 상태를 알려면 개발자가 `pnpm audit`를 따로 떠올려야 한다. 템플릿 문서는 provider만 말한다 |
| 최소 개선 방향 | (1) 지금 lockfile을 갱신한다: `zod` 4.6.6 이상, `react-router`·`react-router-dom` 7.18.2 이상, `vite` 8.1.6 이상, `vitest`·`@vitest/coverage-v8` 4.1.12 이상, `storybook` 계열 10.6.2 이상, 그 밖은 전이 의존성 갱신이나 `pnpm.overrides`. 기준선을 다시 승인한다. (2) release 단계에 `pnpm audit --prod --audit-level high` 결과를 비차단 증거로 남기는 명령을 둔다(네트워크 필요, 실패하면 `UNVERIFIED`). (3) 백엔드처럼 갱신 자동화 설정을 둔다 |
| 대안 비교 | (a) 현상 유지 — provider가 있는 조직에만 맞다. (b) (1)만 — 지금 상태는 고치지만 다음 advisory도 모른다. (c) (2)를 merge 차단으로 — 코드가 안 바뀌어도 advisory DB가 바뀌면 merge가 깨진다. 템플릿 CI에서 비결정적 실패는 비용이 크다. (d) (1) + (2) 비차단 + (3). 5.3절 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 승격의 provider 판정·서명 검증은 그대로 둔다 |
| 비용·부작용 | (1) 버전 갱신과 테스트 한 바퀴, 기준선 재승인. (2) 명령 하나와 산출물 스키마 하나. 네트워크가 없는 runner에서는 `UNVERIFIED`로 남는다 |
| 재검토 조건 | 조직 단위 provider가 생겨 merge 단계에서도 서명된 판정을 받을 수 있으면 (2)를 그것으로 바꾼다 |
| 완료 기준 | `pnpm audit --prod --audit-level high`가 0건이다. release 단계 산출물에 advisory 수가 남는다. 갱신 PR이 자동으로 열린다 |
| 검증 방법 | `pnpm audit --json` 재실행. release 게이트 산출물 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 13-04 FE-REG-ENV 런타임 행 13개 중 5개의 `required`·`defaultValue`가 실제 스키마와 다르고, 대조 검사가 없다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-04(`1103/13-04`) — 위 제목 |
| 성격 | 확인된 결함(계약 메타데이터의 불일치) |
| 관련 관점 | 19, 17, 23, 9 |
| 근거 | FE-REG-ENV의 필수 필드는 `phase`, `classification`, `required`, `defaultValue`다(`config/contracts/registry-governance.json:263-282`). `d0414c8`의 새 테스트는 스키마 키마다 `phase: runtime` 행이 있는지만 본다(`tests/unit/env-registry-coverage.test.ts:9-17`). 실험 E-5(스키마 필드에 `undefined`를 넣어 필수 여부·기본값 확인): 다른 행 5개 — `TELEMETRY_ENABLED` 행 기본값 `false` / 스키마 필수·기본값 없음, `AUTH_MODE` 행 기본값 `"external"` / 스키마 기본값 없음, `RELEASE_MANIFEST_URL` 행 `required: true` / 스키마 선택(기본값 있음), `CAPABILITY_OVERRIDES` 행 기본값 `null` / 스키마 기본값 네 항목 모두 `DEFAULT`, `FEATURE_OVERRIDES` 행 기본값 `null` / 스키마 기본값 `{}`. 행 정의는 `src/contracts/env.ts:52-69`, 스키마는 `src/contracts/release-artifacts.ts:142-153`, `:189-199` |
| 발생 조건 | 제품 개발자나 다운스트림이 FE-REG-ENV를 보고 설정 문서를 쓸 때. 예: `AUTH_MODE`를 빼도 `external`이 된다고 읽으면 부팅이 스키마 오류로 멈춘다 |
| 영향 | 부팅 시 스키마 검증이 있어 잘못된 문서가 조용히 통과하지는 않는다. 피해는 헷갈림과 재작업이다. 이 레지스트리는 기준선 호환성 검사 대상이라(`check:registries`) 틀린 값이 "계약"으로 굳는다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 키 누락 검출 M3(새 테스트) / 행 값 대조 M0 · E3(실험 E-5) |
| 확실성과 남은 가정 | 대조는 스키마 필드의 `safeParse(undefined)` 결과로 했다. `defaultValue: null`이 "기본값 없음"인지 "덮어쓰기 없음"인지 레지스트리 정의에 적혀 있지 않다 |
| 결정의 근거 | 적용 제외 — 같은 사실의 두 선언이 어긋난 단순 불일치다 |
| 이해 비용 | 설정 키 하나를 더하는 사람이 스키마와 행 두 곳에 필수 여부·기본값을 따로 적고 손으로 맞춘다 |
| 최소 개선 방향 | 커버리지 테스트에 "런타임 행의 `required`·`defaultValue`는 스키마 필드의 필수 여부·기본값과 같다"를 더하고 5개 행을 맞춘다. 행 값 변경이 breaking으로 분류되면 기준선 재승인을 한 번에 묶는다 |
| 대안 비교 | 런타임 행의 `required`·`defaultValue`를 스키마에서 계산해 채우는 방법도 있다. 손으로 맞출 일이 사라지지만 레지스트리 모양(정적 객체)을 바꿔야 해서 비용이 더 크다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 테스트 한 건과 행 5개 수정 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-5 대조가 13개 모두 같다. 스키마 기본값을 바꾸고 행을 안 바꾸면 테스트가 실패한다 |
| 검증 방법 | `tests/unit/env-registry-coverage.test.ts` 확장 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 13-05 채운 배포 슬롯의 `secrets.*`가 job 전체 env로 렌더링돼 다른 단계에도 보인다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-05(`1103/13-05`) — 위 제목 |
| 성격 | 개선 제안. `de379ea` 본문이 한계로 적은 내용이고, action은 커밋 SHA로 고정돼 있다 |
| 관련 관점 | 15, 18, 26 |
| 근거 | 생성기는 job의 `environment`를 job 수준 `env:`로 쓴다(`scripts/generate-ci-workflow.ts:147-152`). 슬롯 계약은 그 자리에 `secrets.*`를 허용한다(`scripts/contracts/ci-gates.ts:1018-1029`). 실험 E-3의 생성 결과: `DEPLOY_SSH_KEY: "${{ secrets.DEPLOY_SSH_KEY }}"`가 job env에 있고, 같은 job의 `actions/checkout`, `actions/setup-node`, `frozen-install` 단계가 그 값을 환경변수로 받는다. 슬롯에 `download`를 넣으면 제3자 action(`ChristopherHX/gitea-download-artifact`)도 받는다 |
| 발생 조건 | 프로젝트가 배포 자격증명을 슬롯 env에 넣을 때(계약이 허용하는 유일한 방법) |
| 영향 | 고정된 action이 바뀌지 않는 한 실제 유출은 없다. 침해된 action 버전으로 SHA를 갱신하면 배포 키가 그 action에 보인다. 피해 반경을 줄일 여지다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | action SHA 고정 M4 / secret 범위 제한 M0 · E3(실험 E-3) |
| 확실성과 남은 가정 | Gitea act_runner가 job env를 `uses:` action 프로세스에 넘긴다는 것은 GitHub Actions와 같은 동작이라고 본다(이번에 runner에서 확인 안 함) |
| 결정의 근거 | 적용 제외 — 범위를 좁히는 단일 수정이다 |
| 이해 비용 | 슬롯을 채우는 사람이 secret이 어느 단계까지 보이는지 생성 YAML을 읽어야 안다 |
| 최소 개선 방향 | 슬롯 계약에서 `secrets.*` 바인딩만 `deploy` 단계의 `env:`로 렌더링한다. `vars.*`와 후보 digest는 job 수준에 둬도 된다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 생성기 분기 하나, 스냅샷 갱신 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 슬롯을 채운 생성 YAML에서 `secrets.`가 `deploy` 단계 env에만 나온다 |
| 검증 방법 | `tests/unit/ci-workflow-generation.test.ts` 스냅샷 케이스 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이 영역이 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 영역 09·12 | — | — | > — 빌드 스크립트는 짧고 단계 주석이 정확하다(`build-frontend.ts:10-39`) |
| 2 | 구조적 성숙도 | > 영역 12 | — | — | > |
| 3 | 변경 용이성 | 적용 | 목표 M2 / 확인 M2 | E3(E-3) | P — 배포 job을 계약을 고치지 않고 채울 수 있게 됐다. 채우는 규칙이 단계 종류뿐이라 잘못 채워도 통과한다(13-01) |
| 4 | 인지 부하 | 적용 | M1 | E1 | P — 운영 단계까지 job 10개, provider 전제, 변수 10여 개. HTTP/2 전제가 세 문서에 흩어져 있고 압축은 어디에도 없다(13-02) |
| 5 | 위험 가시성 | 적용 | M3 / 일부 M0 | E3 | P — 빈 슬롯·fixture가 `UNVERIFIED`로 드러난다(M3). FE-GATE-019 PASS가 무엇을 증명하지 않는지, advisory 상태는 드러나지 않는다(13-01, 13-03) |
| 6 | 실패 성숙도 | 적용 | M3 | E2·E3 | O — 빌드 단계 실패 즉시 중단, 승인 fail-closed, 빈 슬롯은 probe 없이 `UNVERIFIED` |
| 7 | 운영 성숙도 | 적용(일부) | M1 | E1 | P — 비상 스위치 절차가 생겼다(1101/13-05). provider 없는 배포 경로 문서 없음(1101/13-03) |
| 8 | 디버깅 가능성 | 적용 | M2 | E3 | P — 실패 항목이 표면·헤더·기대·관측으로 남는다(E-2b 출력). `VITE_BUILD_ID=""` 처리 갈림(R-2) 남음 |
| 9 | 유지보수 성숙도 | 적용 | M2 | E1 | P — CSP 6벌(0929/13-04), 폐기 별칭(0929/13-07), 기본값 4곳(R-2), FE-REG-ENV 값 이중 선언(13-04) |
| 10 | 테스트 성숙도 | 적용 | M3 | E2·E3 | P — 이번 규칙 변이 6/6 검출. 빠진 규칙(배포물 내용 대조, 압축, advisory)은 테스트도 없다 |
| 11 | 데이터 성숙도 | > 저장소 영역 | — | — | > |
| 12 | 동시성 성숙도 | > 탭·저장소 영역 | — | — | > |
| 13 | 확장성 | > 영역 11·15 | — | — | > |
| 14 | 성능 성숙도 | 적용 | 예산 M3 / 서빙 전제 M1 | E3 | P — 초기 JS 201,848/204,800(여유 2,952 B). 압축 전 646,132 B. 예산이 전제한 압축·HTTP/2를 호스팅에서 확인하지 않는다(13-02) |
| **15** | 보안 성숙도 | 적용 | M3 / 일부 M0 | E3 | P — 예약 이름 거절, 미선언 `VITE_*` 거절, CSP 기본값 강함. 승인받지 않은 `config.json`이 배포돼도 게이트가 PASS(13-01). 런타임 advisory 2건(13-03). 슬롯 secret 범위(13-05) |
| **16** | 의존성 성숙도 | 적용 | 판정 M3(승격만) / 신호 M0 | E3 | P — lockfile·기준선 digest 일치(`bedf1bbc…`), action SHA 고정, `engineStrict`·`saveExact` 적용. advisory 44건을 승격 전에 모르고 갱신 자동화가 없다(13-03). SBOM `scheduler` 분류(0929/13-05) |
| 17 | API / Contract 성숙도 | 적용(설정 계약) | M3 | E3 | P — 설정 스키마 하나, 제품 키 충돌 거절. FE-REG-ENV 행 값 불일치(13-04) |
| **18** | 배포 성숙도 | 적용 | M3 / 일부 M0 | E3 | P(지난 X) — 재빌드 제거, 이전 release 거절, 배포 슬롯, SPA fallback 검사. 같은 run 재빌드 통과(13-01), provider 없이는 슬롯 도달 불가(1101/13-03), 하위 경로 PASS 불가(0929/13-06) |
| **19** | 설정 성숙도 | 적용 | M3 | E3 | P(지난 X) — SW 로컬 설정 덮어쓰기 고쳐짐, 자리표시자 거절, 배포 후 변경 검사. `.env*` 입력 갈림(0929/13-02), 서빙 설정의 전제 누락(13-02), 레지스트리 값 불일치(13-04) |
| 20 | 개발자 경험 | 적용 | M1 | E1 | P — nginx 예시·런북 4단계가 생겼다. 예시가 성능 전제를 어긴다(13-02). README build id 필수 조건 누락(0929/13-09) |
| 21 | Guardrail 성숙도 | 적용 | M3 | E3 | P — 계약이 슬롯 env·단계 종류를 제한한다(M5). 슬롯이 후보를 쓰는지, 호스트가 압축하는지는 막지 않는다(13-01, 13-02) |
| 22 | 추상화 성숙도 | > 영역 09·12 | — | — | > |
| 23 | 일관성 | 적용 | M1 | E1 | P — 빌드 변수 출처 갈림(0929/13-02), 기본값 `\|\|`·`??` 갈림(R-2), 레지스트리와 스키마 갈림(13-04), 전제 문서와 예시 갈림(13-02) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 | E1 | P — 슬롯 job 이름 `deploy-promoted-release`가 내용과 무관하게 고정된다(13-01). `.env.example` 문구는 고쳐졌다 |
| 25 | 조직 확장성 | - 1인 관리 전제 | — | — | - |
| **26** | Ownership 성숙도 | 적용 | M1 | E1 | P — 배포는 프로젝트 몫이라고 문서화했다. 그 몫을 받는 슬롯이 provider 뒤에 있다(1101/13-03). advisory 대응 담당·절차가 없다(13-03). 선택 기능 결함 분류(0929/13-10) |
| 27 | 삭제 가능성 | > 영역 14 | — | — | > |
| 28 | 회복 가능성 | 적용 | M2 | E1 | P — 비상 스위치 검사·되돌리기 절차가 있다(FE-RB-001). 슬롯 배포 뒤 FE-GATE-019가 실패해도 자동 되돌림은 없다(문서상 프로젝트 몫) |
## 5. 설계 선택 설명 (41절)
### 5.1 FE-GATE-019가 "배포된 것이 후보인가"를 run 이름으로 판단한다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 운영 단계 hosting PASS는 "지금 호스트가 승인된 후보를 내준다"는 뜻이어야 한다 |
| 2. 지킬 성질 | 호스트의 `index.html`·`config.json`·`release-manifest.json`·entry script가 후보 archive의 것과 같다(비상 스위치 두 개는 예외) |
| 3. 현재 보장 | manifest의 `buildId`·`releaseId`가 후보와 같다(`hosting-probe.ts:128-137`). 이전 run의 release는 잡는다(E-2b, M1). **보장하지 않는 것:** 같은 run의 다른 빌드(E-2c), 일부 파일만 다른 배포, 슬롯의 입력 |
| 4. 대안 | (a) 현상 유지. (b) archive SHA를 호스트에 같이 올리고 probe가 대조. (c) 작은 파일(`config.json`, `index.html`) 내용을 후보와 대조. (d) 슬롯이 후보를 받도록 계약으로 강제 |
| 5. 비교 | (a) 가장 싸지만 E-2c를 통과시킨다. (b) 가장 강한 식별이지만 호스트에 새 파일 규약이 생기고, 그 파일과 다른 파일을 올리는 실수는 여전히 못 잡는다. (c) 호스트가 실제로 내주는 결과를 본다. 비상 스위치 예외만 다루면 된다(기존 규칙 재사용). (d) 입력을 맞추지만 결과는 보지 않는다 |
| 6. 현재 조건에서의 판단(리뷰어 추론) | (c)+(d). 단일 desktop 서버이고 환경마다 다른 파일이 `config.json` 하나인 구조라 `config.json` 비교 하나가 가장 많은 실수를 잡는다. 같은 커밋 재빌드는 JS가 같아서(E-2d) `assetManifestHash`로는 부족하다 |
| 7. 재검토 조건 | 환경별 설정을 빌드 밖에서 주입하는 방식(1101 5.1 (b))으로 바꾸면 `config.json` 비교 기준을 승인 기록으로 옮긴다 |
### 5.2 템플릿이 HTTP/2를 전제로 초기 청크를 나눠 둔다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 초기 JS 바이트 예산을 지키면서 첫 화면을 빠르게 한다 |
| 2. 지킬 성질 | 예산 계산(gzip)과 성능 판단(HTTP/2)의 전제가 실제 서빙에서 성립한다 |
| 3. 현재 보장 | 예산은 merge 게이트가 막는다(FE-GATE-012, M3). 서빙 전제는 문서 한 단락(M1). 템플릿 예시는 전제를 어긴다(13-02). **보장하지 않는 것:** 실제 호스트의 프로토콜·압축 |
| 4. 대안 | (a) 현상 유지. (b) 청크를 묶어 HTTP/1.1에서도 빠르게(`3f9c087`의 (나)). (c) 전제를 예시와 probe에 넣는다. (d) 전제를 "HTTP/1.1 허용"으로 바꾸고 예산을 압축 전 바이트로 잰다 |
| 5. 비교 | (b) Fast 3G에서 0.96초 빠르지만 고정 목록이 셸 변경마다 낡고 검사가 없다(기록된 기각 사유, 타당하다). 압축 문제는 남는다. (c) 비용이 몇 줄이고 결정 근거를 그대로 지킨다. (d) 현실과 맞지 않는 보수적 예산이 되고 기능 추가 여유가 사라진다 |
| 6. 현재 조건에서의 판단(리뷰어 추론) | 분할 유지는 타당하다. 그 판단을 지키려면 (c)가 필요하다. 지금은 "선택 이유는 타당하지만 현재 구현이 그 보장을 하지 못한다"(41.11 표 3행) 상태다 |
| 7. 재검토 조건 | 실제 desktop 서버가 HTTP/2를 못 쓰는 구성(예: HTTP/1.1 전용 프록시 뒤)으로 확정되면 (b)를 다시 잰다 |
### 5.3 취약점 판정을 운영 승격의 외부 provider에만 맡긴다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 배포물의 취약점 판정을 빌드 주체가 아닌 쪽이 서명한다(승격 증거). 그리고 개발 중에 알려진 advisory를 일찍 안다(유지 신호) |
| 2. 지킬 성질 | 승격한 archive와 판정한 lockfile이 같다. high 이상은 예외 없이 승격하지 않는다 |
| 3. 현재 보장 | 첫 번째는 provider·서명·lockfile digest 대조로 지킨다(M3). 두 번째는 없다(M0). 지금 lockfile에 high 16·critical 1(E-7) |
| 4. 대안 | (a) 현상 유지. (b) merge 차단 `pnpm audit`. (c) release 단계 비차단 advisory 기록 + 갱신 자동화. (d) 로컬 scanner를 provider로 내장 |
| 5. 비교 | (b) 코드가 안 바뀌어도 DB 변경으로 merge가 깨지고 네트워크에 기댄다. (c) 신호는 생기고 승격 판정의 의미는 그대로다. (d) 서명 주체 분리라는 원래 목적이 사라진다(1101 5.2) |
| 6. 현재 조건에서의 판단(리뷰어 추론) | (c). 1인 운영에서 provider를 붙이기 전까지 유일한 신호가 된다. 백엔드 템플릿과 같은 갱신 방식을 쓰면 짝 운영 비용도 준다 |
| 7. 재검토 조건 | 조직 provider가 merge 단계에서 서명된 판정을 줄 수 있게 되면 (c)를 그것으로 바꾼다 |
## 6. 실험·변이 기록
모든 실험은 분리 worktree(`agent-a648a90bec4f23d25`, `e40684b`)의 `.r13/`(스크립트·출력) 안에서 했다. 빌드는 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock`으로 감쌌다. 실험 중 부하 평균은 18~67(다른 리뷰어 동시 실행). 끝난 뒤 `git checkout -- . && git clean -fd`로 되돌렸다. 커밋하지 않았다.
### 6.1 실험
| ID | 무엇을 | 결과 | 쓰인 곳 |
|---|---|---|---|
| E-1a | 후보 빌드: `APP_PROFILE=production`, `VITE_BUILD_ID=gitea-77-1`, `RELEASE_ID=refs/heads/main-77-1`, `RUNTIME_API_BASE_URL=https://api.r13-review.dev/`, `RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.r13-review.dev/v1/events` → `check:release-admission`(`RELEASE_TARGET=production`) | 빌드 rc=0(4.3초, 부하 18). `production ADMITTED`. 초기 JS 25파일 압축 전 646,132 B / gzip 201,876 B | 13-01, 13-02, 2.3 |
| E-1b | 이전 release 빌드: production, run 76 | rc=0 | E-2b |
| E-1c | 슬롯 재빌드 흉내: run 77 이름, `APP_PROFILE` 없음 | rc=0. `config.json` `APP_ENV=local`, `AUTH_MODE=demo`, `API=http://localhost:8080/`, `BUILD_ID=gitea-77-1`. manifest `buildId`·`releaseId`는 후보와 같다 | E-2c |
| E-2a | 실제 `scripts/verify-hosting-headers.ts`를 `node --import .r13/fake-host.mjs`(전역 `fetch`를 디렉터리 서빙으로 교체, 헤더는 `response-headers.fixture.json`의 표면별 값)로 실행. `HOSTING_BASE_URL=https://desktop.r13-review.dev/`, `RELEASE_DEPLOYED=true`, `--release-root <E-1a>`. 호스트 = 후보 | `PASS (live)`, rc=0 | 대조군 |
| E-2b | 같은 방법, 호스트 = E-1b(run 76) | `FAIL`, rc=1. 실패 2건: `releaseManifest/build-id`(기대 `gitea-77-1`, 관측 `gitea-76-1`), `release-id` | 2.1 1101/13-01 |
| E-2c | 같은 방법, 호스트 = E-1c(같은 run, 로컬 프로필) | **`PASS (live)`, rc=0, 실패 0건** | 13-01 |
| E-2d | E-1c를 작업 트리에 ignore되지 않은 빌드 복사본이 없는 상태에서 다시 빌드하고 후보와 파일 비교, 그리고 E-2c 재실행 | 빌드 rc=0. 후보와 `assetManifestHash`(`34435c85fad3c5ca`)·`index.html`(sha256 `ff14479d…`)·`assets/` 전체가 같다. 다른 파일은 `config.json`과 `release-manifest.json`(`builtAt`, 로컬이라 `SOURCE_DATE_EPOCH` 없음) 둘뿐. FE-GATE-019 다시 `PASS (live)`, rc=0 | 13-01 확실성, 5.1 |
| E-3 | `config/ci/gates.json`의 `deployment` job을 `checkout → setup-node → frozen-install → deploy(script: build)`, env `APP_PROFILE: vars`, `DEPLOY_SSH_KEY: secrets`로 바꾸고 `generate-ci-workflow` → `check-ci-contract.ts` → `generate-ci-workflow --check` | 셋 다 PASS("27 gates, strict v2 graph … PASS", "CI workflow bytes: PASS"). 생성 job 이름 `deploy-promoted-release`, secret이 job env에 있다 | 13-01, 13-05 |
| E-4 | 로컬 HTTPS 서버(`http2.createSecureServer`, `allowHTTP1: true`, 자체 서명)에 Node 전역 `fetch` 요청, 그리고 `http2.connect`. 별도로 gzip 응답을 `fetch`로 받기 | 서버가 본 요청 `httpVersion=1.1`, `accept-encoding: "br, gzip, deflate"`. `http2.connect` ALPN `h2`. `fetch` 응답의 `content-encoding` 헤더 `"gzip"`이 보인다 | 13-02 |
| E-5 | `runtimeConfigV2ArtifactSchema.shape`의 각 필드에 `safeParse(undefined)` → 필수 여부·기본값을 FE-REG-ENV 행과 비교 | 13개 중 5개 다름(13-04 근거) | 13-04 |
| E-6 | `findAdmissionViolations`를 동봉 프로필과 호스트 6개로 호출 | 동봉 staging·production 프로필 각 2건 거절. `api.r13-review.dev`·`desktop.tail1234.ts.net` 승인, `api.example` 거절, `192.168.0.10`·`100.101.102.103` 거절, 한 단어 호스트 `test` 승인 | 2.1 1101/13-02 |
| E-7 | `corepack pnpm audit --json`(네트워크 됨, 2026-11-03 23시대) | rc=1. advisory 44건: critical 1, high 16, moderate 23, low 4. 의존성 561(dev 550) | 13-03 |
| 설정 확인 | `corepack pnpm config get engineStrict / saveExact / minimumReleaseAge` | `true` / `true` / `undefined`(pnpm 11 내장 기본 1440분) | 2.2 0929/13-08 |
### 6.2 규칙 변이 (`node scripts/run-vitest.ts run <파일>`, 바꾼 줄은 실행마다 `git checkout`으로 되돌림)
기준선: `hosting-probe`·`deployment-admission`·`env-registry-coverage` 3파일 52건 통과(4.6초).
| 변이 | 대상 | 결과 |
|---|---|---|
| M1 manifest 이름 대조를 끈다 | `scripts/lib/hosting-probe.ts:135` | 잡음 — 2 failed / 26 |
| M2 예약 이름 거절을 끈다 | `src/contracts/deployment-admission.ts:159` | 잡음 — 2 failed / 25 |
| M3 빈 슬롯을 무시하고 항상 probe | `scripts/verify-hosting-headers.ts:81` | 잡음 — 1 failed / 26 |
| M4 편집본이 빌드 필드를 바꿔도 허용 | `scripts/check-release-admission.ts:76` | 잡음 — 3 failed / 25 |
| M5 슬롯 env 바인딩 검사를 끈다 | `scripts/contracts/ci-gates.ts:1027` | 잡음 — 1 failed / 423 |
| M6 SPA fallback 비교를 끈다 | `scripts/lib/hosting-probe.ts:145` | 잡음 — 2 failed / 26 |
### 6.3 확인하지 못한 것
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 Gitea runner에서 production 단계와 채운 슬롯 | runner를 쓰지 않음 | dispatch `stage=production` 1회 |
| 실제 nginx(desktop 서버)에서 probe, ALPN, 압축 | 호스트 없음 | 예시 설정으로 띄우고 live probe |
| HTTP/1.1·비압축 첫 화면 시간 | 이번에 재지 않음(기존 기록과 계산만) | `performance-evidence.md`의 방법에 비압축 조건을 더해 측정 |
| E-2c release의 브라우저 부팅 | 브라우저를 띄우지 않음 | `vite preview` + Playwright 1회 |
| `zod`·`react-router` advisory의 도달 가능성 | 코드 경로를 끝까지 따라가지 않음 | advisory 조건과 사용 지점 대조 |
| provider가 dev 의존성까지 판정하는지 | provider 없음 | provider 계약 문서 |
| Gitea act_runner가 job env를 `uses:` action에 넘기는지 | runner 미실행 | 슬롯을 채운 job에서 env를 출력하는 action 1회 |
| `.env*` 입력 갈림(0929/13-02) 재현 | 이번에는 정적 확인만 | `.env.production.local`에 `VITE_BUILD_ID`만 두고 빌드 |
### 6.4 실험 중 알게 된 것
- 작업 트리에 ignore되지 않은 빌드 복사본(`.r13/served-cand/`)이 있으면 다음 빌드의 CSS가 277 B 커지고 entry 파일 해시가 바뀌었다(Tailwind 자동 소스 탐지가 그 파일을 읽었다). CI가 후보를 푸는 `.release/promoted-release/dist/`는 `.gitignore`의 `dist/` 규칙에 걸려 해당하지 않는다(`git check-ignore`로 확인). 그래서 발견으로 세지 않는다. 다만 E-2c 첫 실행에서 후보와 재빌드의 `assetManifestHash`가 달랐던 이유가 이것이라, E-2d에서 깨끗한 트리로 다시 확인했다.
@@ -0,0 +1,360 @@
# 14 — 템플릿 제품성·문서·DX·업데이트 전파
> 검토일: 2026-11-03 · 기준: `e40684b` (브랜치 `review/2026-11-03-merged`, `claude/happy-easley-233d07`와 `fix/ui-design-audit-2026-11-01`을 합친 커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
>
> 경로: `README.md`, `CHANGELOG.md`, `PRODUCT.md`, `docs/`(특히 `docs/manual/`, `docs/architecture/`), `recipes/`, 제거 스크립트(`scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`), 루트 추적 파일
>
> 깊게 본 관점: 9 유지보수, 20 개발자 경험, 26 Ownership, 27 삭제 가능성, 30절 전체
>
> 렌즈: 오늘 들어온 BREAKING 변경(V2 클라이언트·V2 API 행 삭제, `FeatureRuntime` 모양, CSRF 조립 검사)을 `CHANGELOG.md` 미출시 절만 보고 tech-log·memento가 옮길 수 있는가. 설계 문서 중 지금 코드와 어긋난 주장. 매뉴얼만 보고 기능을 더할 때 막히는 곳.
>
> 영역 판정(35.8): **조건부 사용 가능.** 새 프로젝트를 복사해 시작하고 `create:feature`와 매뉴얼로 기능을 더하는 용도는 사용 가능하다. 지난 라운드의 문서 결함 7건 중 6건이 고쳐졌고, 이번에 변이·삭제 실험으로 다시 확인했다(E3). 다만 **이 미출시 묶음을 다운스트림에 전파하는 용도는 보류**다. `CHANGELOG.md` 미출시 절이 기준 커밋의 한 브랜치 16커밋을 빠뜨리고(14-01), memento-web 이행 안내가 실제 파일과 다르다(14-02). 참조 기능을 지운 제품은 매뉴얼 때문에 merge 게이트 FE-GATE-017이 실패한다(14-04).
>
> ID 표기: 이 문서의 새 발견은 `14-01`부터다. 지난 라운드(2026-11-01) 발견은 `1101/14-NN`, 그 전 라운드(2026-09-29)는 `0929/14-NN`이다.
## 0. 결론
핵심은 둘이다. "새로 시작하는 프로젝트"용 문서는 좋아졌다. "이미 복사한 프로젝트를 따라오게 하는" 문서는 이번 묶음에서 아직 쓸 수 없다.
```text
새 프로젝트 시작
README → docs/manual/ → create:feature → merge 게이트
: scaffold를 만들어 check:registries(additive PASS)·verify:documentation(PASS) 확인 (E-9)
: 지난 라운드 1101/14-01·02·03·04·05·06 고쳐짐 (E-6·E-7·E-8)
이미 복사한 프로젝트 동기화 (tech-log·memento)
CHANGELOG 미출시 절 → 옮기는 법 → 충돌 해결 → 게이트
: fix 브랜치 16커밋이 CHANGELOG에 없다 (14-01)
: memento-web 옮기는 법이 실제 파일·작업량과 다르다 (14-02)
: 다음 동기화 충돌 memento 25경로, tech-log 76경로 (E-5)
: 참조 기능을 지운 제품은 매뉴얼 때문에 FE-GATE-017이 실패한다 (14-04)
```
| 심각도 | 수 | ID |
|---|---:|---|
| Critical | 0 | |
| High | 0 | |
| Medium | 4 | 14-01, 14-02, 14-03, 14-04 |
| Low | 2 | 14-05, 14-06 |
High가 없는 이유: 위 결함은 모두 동기화하거나 기능을 더하는 사람이 **게이트 실패로 바로 알게** 된다. 조용히 바뀌는 것은 진단 값 두 개(`route_id`, realtime 관측 `reason`)가 기록 없이 바뀐 것뿐이고, 관측 쪽 영향이다(14-01).
지금 이해하면 되는 것:
1. 새 프로젝트용 경로(README → 매뉴얼 → `create:feature`)는 이 커밋에서 동작한다.
2. 이 미출시 묶음을 tech-log·memento에 옮기기 전에 CHANGELOG를 기준 커밋에 맞게 다시 써야 한다(14-01, 14-02).
3. 목표 설계 문서의 상태 값과 VD-23은 V2 삭제를 반영하지 않았다. 401 재전송 규칙은 정본·코드와 반대다(14-03).
4. 매뉴얼이 지울 수 있는 참조 기능의 경로에 기대고, 제거 드릴은 문서 게이트를 돌리지 않는다(14-04).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 읽기만 한 저장소: `clean-architecture-backend-template`, `tech-log-frontend`(`7a4e201a`), `memento-frontend`(`d3810a0`) |
| 커밋·작업 상태·확인 시점 | `e40684b`, 격리 worktree(detached), 2026-11-03. 실험 뒤마다 `git checkout -- . && git clean -fd`로 되돌렸다. 커밋하지 않았다 |
| 목적과 지원 실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 짝 백엔드 템플릿과 함께 쓴다. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿으로 서비스를 빨리 출시한다. 두 다운스트림(tech-log, memento)이 이 템플릿을 복사해 쓰고 동기화한다. 문서 규모 목표는 없다 |
| 지난 리뷰 뒤 바뀐 것 | `d99301b..e40684b` 177커밋. 두 브랜치의 공통 조상 `ec7435c` 뒤로 `claude/happy-easley-233d07` 12커밋(Envelope, V2 삭제, 거절 표, CSRF, KEYED 재전송)과 `fix/ui-design-audit-2026-11-01` 16커밋(남은 위험 수정)이 갈라졌다. 두 다운스트림의 기준점 `af3d8e6` 뒤 템플릿 파일 583개가 바뀌었다 |
| 읽은 코드·구성 범위 | `README.md`·`CHANGELOG.md`·`PRODUCT.md`·`docs/README.md` 전체. `docs/manual/` 전체(1,620줄). `starter-experience.md` "Adding a feature" 표, `layers.md`, `backend-api-and-server-state-contract.md` 4~6절, VD-23 머리·1·2·8절, VD-24 머리, `api-contract-schema-mapper-and-server-state.md` 상태 표, 정본 8.4절. `scripts/verify-documentation-readiness.ts` 150~300행, `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts` 25~39행, `scripts/check-registries.ts` 360~380·525~560행, `config/contracts/registry-governance.json` FE-REG-API·FE-REG-SCHEMA, `src/contracts/api-operations.ts`, `src/contracts/product-contracts.ts`, `src/features/feature-module.ts`, `tests/unit/env-registry-coverage.test.ts`, `tests/unit/changelog-review-ids.test.ts`. memento-web의 `contracts/`·`feature-module.ts`·`presentation/memento-feature-runtime-descriptor.ts`. 두 다운스트림의 기준점 파일 |
| 수행한 테스트·실험 | 6절 E-1~E-12. CHANGELOG 해시 위치, 변이 5개, 이력 삭제 실험, 참조 기능 삭제 실험, `create:feature` 실험, 두 다운스트림 다음 동기화 merge-tree 재현, 매뉴얼 오류 문구 대조, `test:sample-removal` 1회(`flock`) |
| 게이트 결과(오케스트레이터, 같은 커밋) | `check:architecture`·`check:types`·`lint`·`verify:documentation`·`check:adapter-inventory`·`check:ci`·`check:registries`·`check:i18n`·`check:design-system`·`check:diagnostics` exit 0. unit 2,580 / component 263 / integration 117 / contract 23 / runtime-schema 56건 통과. 번들 초기 JS 201,848 / 204,800 B. 출처: 오케스트레이터 scratchpad `review-gates/summary.txt` |
| 확인하지 못한 범위·이유 | 깨끗한 환경의 `install` → `dev`(공유 환경). 나머지 제거 드릴 3개(`test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal`, 시간). 다운스트림에서 실제 병합 뒤 게이트(충돌을 먼저 풀어야 해서 merge-tree로 충돌 수만 쟀다). 목표 설계 문서 본문 전체(약 3만 줄, 상태 줄과 검색 결과만 봤다). 백엔드 `docs/web/http-contract.md`의 미커밋 수정(working tree `M`) 내용 |
| 이전 리뷰와 비교 가능한 범위 | 지난 발견 13건(1101 7건, 0929 6건)과 FOLLOW-UP 1건을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 |
## 2. 지난 발견 재판정
| ID | 상태 | 근거 (이 커밋) |
|---|---|---|
| 1101/14-01 결정 근거가 지워도 되는 이력 문서에만 있음 | **고쳐짐** (E3) | 이름 없는 `Spec §` 참조 0건, `scale-architecture.md §` 참조 87건(`git grep`). 실험 E-8: README 목록대로 이력(`docs/superpowers/`, `docs/reviews/`(adapters 제외), `SPEC.md`, `tasks/`, `CLAUDE.md`, `PRODUCT.md`)을 지운 뒤 `verify:documentation` PASS_SCOPED, `check:adapter-inventory` PASS, `deletable-history-documents`·`changelog-review-ids` 테스트 3건 통과. 남은 끊긴 링크는 3개이고 모두 `docs/README.md` 3절이 지운 폴더 자신을 가리키는 링크다. 코드·설정에서 지운 이력을 가리키는 줄 0 |
| 1101/14-02 리뷰 ID가 라운드마다 같은 형식 | **고쳐짐**, 작은 잔여 | `CHANGELOG.md:10` 표기 규칙과 `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 `NN-MM`을 막는다. 잔여: `(README 13.6)`(`CHANGELOG.md:123`), `(G-1)`(`:117`)은 검사 정규식(`NN-MM`·`F-N`) 밖이라 라운드 없이 남는다. 리뷰 절 참조도 `(1101/14.4)`, `(1101 README 14.3)` 두 꼴이 섞였다. 새 발견으로 세지 않는다 |
| 1101/14-03 입구 문서가 폴더 9개 중 3개를 빠뜨림 | **고쳐짐** (E3) | 실험 E-7: `layers.md`에서 규칙 행 하나를 지우면 `docs/architecture/layers.md does not name .dependency-cruiser.json rules: features-do-not-import-other-features`로 실패한다. `src/platform` 행 이름을 바꾸면 `frontend-application-foundation.md does not describe src folders as the layers.md table does: platform`으로 실패한다 |
| 1101/14-04 `PRODUCT.md` 제거 주장 | **고쳐짐** | `PRODUCT.md:33`이 드릴 범위(참조 기능만)와 같다. `README.md:230`이 `PRODUCT.md`를 지울 파일 목록에 둔다. `PRODUCT.md:56`은 `docs/accessibility/manual-checklist.md`를 근거로 든다 |
| 1101/14-05 현재 계약 문서 drift 검사가 좁음 | **고쳐짐**(경로·script·게이트 ID 범위) | `scripts/verify-documentation-readiness.ts:153-` `documentReferences`. 실험 E-6에서 문서 8개의 없는 경로 18개를 문서별로 적었다. 남은 범위: 설명·오류 문구는 검사하지 않는다(설계상, `docs/README.md` 1절). 그 빈칸에서 생긴 drift는 14-05, 목표 설계 문서 drift는 14-03 |
| 1101/14-06 실패 메시지가 원인을 말하지 않음 | **고쳐짐** | 실험 E-6·E-7 출력 끝 줄이 `FAIL_UNVERIFIED (failed: document references)`, `(failed: source structure)`처럼 실패한 검사 이름을 적는다 |
| 1101/14-07 문서 위치가 상태를 드러내지 않음 | **남음** | `docs/README.md:63`이 7월 roadmap·capability-review를 여전히 "목표 설계"로 둔다. 새 사례: 지금 코드가 따르는 거절 판정표(6.1절)가 "목표 설계" 문서(`backend-api-and-server-state-contract.md`, 머리 `:11-12` "backend implementation/evidence pending", 기준일 2026-07-28)에 있다. 구체 결함은 14-03에 묶었다 |
| 0929/14-01 실행 로그·작업 기록이 복사 대상에 섞임 | **남음** | 추적 중인 `.log` 63개(`git ls-files artifacts`). `SPEC.md`·`tasks/`가 루트에 있고 `docs/README.md:81`의 이유("이 라운드가 쓰는 중")가 그대로다 |
| 0929/14-02 README 업데이트 절차가 범위 반영을 다루지 않음 | **남음** | `README.md:343-381`은 cherry-pick 1건 절차뿐이다. 두 제품의 기준점 형식도 다르다(memento `.template-origin` 한 줄 `af3d8e6 2026-09-29`, tech-log `template.lock.json`). 이번 다음 동기화는 177커밋·583파일 범위다(E-5) |
| 0929/14-03 제품이 고치는 템플릿 파일 목록이 없음 | **바뀜** | 확장 지점이 열렸다: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`(09-02), `APP_HOME`·`context-layout.tsx`(09-03). 목록은 `starter-experience.md:189-190`과 `docs/manual/03-outside-feature-folder.md` C절에 있다. 그러나 두 제품 모두 아직 옮기지 않았다. 다음 동기화에서 확장 지점이 대신하려던 파일이 그대로 충돌한다: memento `runtime-adapters.ts`·`app-router.tsx`·`installed-feature-contracts.ts`, tech-log `installed-*` 4개·`installed-feature-runtimes.tsx`(E-5). 효과는 제품이 옮긴 뒤에야 확인된다 |
| 0929/14-04 CHANGELOG [계약]이 변경을 빠뜨림 | **바뀜 → 14-01** | 미출시 절(`CHANGELOG.md:13-140`)이 생겼고 BREAKING 행에 지운 이름 목록까지 있다. 그러나 이번에는 한 브랜치 전체(16커밋)가 빠졌다 |
| 0929/14-05 `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적음 | **남음** | `docs/operations/ci-quality-gates.md:69` 그대로. 코드는 경고를 낸다(`scripts/check-release-admission.ts:149-160`, `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`) |
| 0929/14-06 제품이 찾은 템플릿 결함 후보가 돌아오지 않음 | **바뀜**(일부) | 결함 분류 문단은 `README.md:376-381`(09-26부터)에 있다. 새로 생긴 경로는 반대 방향이다. 템플릿 리뷰가 다운스트림 코드를 직접 읽어 결함을 찾는다(`ece944d` 본문: tech-log `env.ts:63-70`, `create-runtime-composition.ts`). 다운스트림이 보내는 기록은 repo에 여전히 없다 |
| FOLLOW-UP(09-25) 09-07 제거 검사가 lint·`check:i18n`·e2e를 건너뜀 | **남음 → 14-04에 합침** | `scripts/test-sample-removal.ts:401-414` 검사 목록에 `lint`, `check:i18n`, `check:design-system`, `verify:documentation`이 없다. 이번에 이 빈칸이 실제 실패를 숨기는 것을 확인했다(14-04) |
## 3. 이번 발견 (36.3)
### 14-01 CHANGELOG 미출시 절이 리뷰 기준 커밋과 맞지 않는다 — 한 브랜치 16커밋이 없고, 머리에 적은 브랜치에는 인용 커밋 7개가 없고, 알려진 제한 13줄 중 9줄이 이미 사실이 아니다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 9, 17, 26, 5, 24 |
| 근거 | **① 빠진 브랜치.** 두 브랜치의 공통 조상은 `ec7435c`다. `git log ec7435c..8c39e77 -- CHANGELOG.md`는 비어 있다(실험 E-2). `fix/ui-design-audit-2026-11-01` 쪽 16커밋은 CHANGELOG를 한 번도 고치지 않았다. 그중 제품 코드나 관측이 함께 바뀌어야 하는 것: `ece944d`(`product-composition.ts`에 `composeProductSessionOwner` export 추가, `PRODUCT_ENV_REGISTRY` 신설. 커밋 본문 "이 파일을 이미 복사한 제품은 composeProductSessionOwner를 더해야 한다"), `d0414c8`(런타임 설정 키마다 FE-REG-ENV 행 필수, `tests/unit/env-registry-coverage.test.ts`), `8469554`·`7d85589`(같은 경로를 쓰는 기능 라우트, 플랫폼 라우트에 가려진 기능 라우트를 조립 때 throw), `7c8cb19`(진단 `route_id`가 `NOT_FOUND` → `UNREGISTERED_ROUTE`), `17fa8d1`(live-poll handoff 관측 kind 변경. 같은 종류의 stream-coordinator 변경은 `CHANGELOG.md:85`에 [계약]으로 있다), `27f4523`(제품의 모든 `context-layout.tsx`를 실행 검사), `8a09c90`(짝 백엔드 필드 code별 폼 문구), `e5b7b3e`(partition 삭제가 다른 탭의 put을 기다림). **② 머리와 해시.** `CHANGELOG.md:13`은 "브랜치 `fix/ui-design-audit-2026-11-01`", `:16`은 "커밋 해시는 이 브랜치 기준이다"라고 적는다. 미출시 절 해시 78개는 모두 `e40684b`에서 닿는다. 그러나 7개(`048f490`, `12f3bb7`, `3261208`, `365d8c3`, `7db32e1`, `bd83b49`, `c05f41a` — BREAKING 2건, [보안] 1건 포함)는 그 브랜치에 없다(실험 E-1). **③ 낡은 알려진 제한.** `:126-140`의 13줄 중 9줄이 이 커밋에서 사실이 아니다: `:128` 백엔드 `http-contract.md` 미커밋(백엔드 `34565130`·`1400dc15`에 있고, 계약 문서 4.1절도 그렇게 적는다), `:129` 필드 code 문구 없음(`8a09c90`), `:131` V3와 V2의 차이 세 가지(V2는 `048f490`에서 지워졌고, KEYED 503 재전송은 `c05f41a`가 V3에 넣었다. 같은 절 `:79`와 반대), `:133` webkit 경고(`267c724`), `:134` 레이아웃 실행 검사 없음(`27f4523`), `:135` OPFS 다른 탭 경합(`e5b7b3e`가 partition Web Lock으로 막았다), `:136` live-poll `IDLE_TIMEOUT`(`17fa8d1`), `:137` 진단 `NOT_FOUND`(`7c8cb19`), `:138` 갤러리 커버리지 0%(`7ee1df5`). `:112`의 "V2/V3 대조 테스트 보강"도 그 테스트가 `12f3bb7`에서 지워졌다 |
| 발생 조건 | 다운스트림이 이 묶음을 동기화할 때 미출시 절을 체크리스트로 쓰면. 두 브랜치 중 하나를 `main`에 합치고 이 절을 그대로 출시할 때 |
| 영향 | tech-log가 `env.ts`의 제품 행과 `create-runtime-composition.ts`의 부트 전 세션 owner(두 커밋 본문이 직접 가리키는 tech-log 수정)를 어디로 옮길지 CHANGELOG에서 찾지 못한다. 충돌을 풀며 템플릿 변경 이유를 커밋 본문에서 다시 캐야 한다. 진단 값 두 개(`route_id`, realtime `reason`)가 기록 없이 바뀌어, 그 값으로 거른 대시보드·알림이 조용히 비게 된다. 알려진 제한을 믿은 사람은 이미 고친 문제를 우회한다. 머리의 브랜치만 받은 사람은 BREAKING 2건과 [보안] 1건을 못 찾는다 |
| 심각도·우선순위 | Medium · P1 — 빠진 변경은 대부분 게이트가 바로 막는다(throw, 테스트 실패). 조용한 영향은 관측 값 두 개다. 그러나 이 절은 템플릿이 정한 업데이트 경로(`README.md:345-348`)의 출발점이고, 이 묶음을 내보내기 전에 고쳐야 한다 |
| 통제·증거 | 목표 M3(출시할 절의 해시가 그 기준 커밋에 모두 있고, 기준 범위의 [계약]급 커밋이 모두 행을 가진다). 확인: ID 형식만 M3(`changelog-review-ids.test.ts`). 완전성·해시 위치·알려진 제한의 최신성은 M0 · E1(커밋 대조), E3(해시 위치 스크립트) |
| 확실성과 남은 가정 | 16커밋 누락과 해시 위치는 git으로 확인했다. 어느 커밋이 [계약]급인지는 커밋 본문·diff로 판단했고 템플릿 관리자의 분류와 다를 수 있다. 진단 값을 거르는 대시보드가 두 제품에 실제로 있는지는 미확인 |
| 결정의 근거 | 기록된 사실: 기준 커밋 `e40684b`은 "어느 브랜치를 main에 합칠지는 사용자가 정한다"는 리뷰용 합치기다(커밋 본문). fix 브랜치는 CHANGELOG 대신 리뷰 README 14절에 결과를 적었다. 리뷰어의 추론: 두 브랜치가 각자 기록을 남겼고 합칠 때 CHANGELOG를 다시 만들지 않았다. 선택 비교는 5.1절 |
| 이해 비용 | 동기화 담당자는 177커밋 로그, 리뷰 README 14절, CHANGELOG를 서로 대조해야 한다 |
| 최소 개선 방향 | ① 미출시 절 머리를 "기준 커밋 `<sha>`(브랜치 이름)"으로 바꾸고, 그 범위의 커밋을 모두 대조해 행을 더한다(위 ①의 8커밋). ② 알려진 제한을 기준 커밋에서 다시 쓴다. 고친 줄은 지우고 고친 커밋을 해당 행에 적는다. ③ 같은 절 안에서 뒤 행이 앞 행을 뒤집는 경우(`:74-77` V2 행 → `:81` V2 삭제)는 최종 상태만 남기거나 "`:81`이 대체" 표시를 붙인다 |
| 대안 비교 | 5.1절: (a) 브랜치마다 누적 기록(현재) (b) 동기화 단위(기준 커밋)마다 순 변경 요약 (c) 커밋 trailer에서 후보 목록 생성. (b) 권장, (c)는 빠짐 검사로 |
| 단순화의 보존 조건 | BREAKING 행의 "지운 이름" 목록과 "옮기는 법"은 유지한다. `MMDD/NN-MM` 규칙과 그 테스트는 유지한다 |
| 비용·부작용 | 문서 수정 1회. (c)를 하면 커밋 규칙이 하나 늘어난다 |
| 재검토 조건 | 템플릿을 태그 단위로만 내보내게 되면 미출시 절은 태그 직전에만 맞추면 된다 |
| 완료 기준 | 미출시 절의 모든 해시가 머리에 적은 기준 커밋에서 닿는다. `ec7435c..8c39e77`의 [계약]급 커밋이 모두 행을 가진다. 알려진 제한의 각 줄이 기준 커밋에서 재현된다 |
| 검증 방법 | 실험 E-1 스크립트를 머리의 기준 커밋으로 다시 돌린다. 알려진 제한 줄마다 그 줄이 가리키는 코드·테스트를 확인한다. (선택) `git log <이전 기준>..<새 기준>`의 커밋이 CHANGELOG 행이나 "기록 안 함" 목록 중 한 곳에 있는지 보는 테스트 |
| 담당·기한·상태 | 미정 · 미출시 절을 `main`에 합치기 전 · 신규 |
| 재검증 결과 | 미실시 |
### 14-02 BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 — memento-web은 V2 행이 0개이고 실제 작업은 스키마 행 약 42개와 zod 전용 칸이다. tech-log의 직접 조립 경로는 안내가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 30.4, 30.3, 17, 20, 24, 25 |
| 근거 | **memento-web(실제 파일, `memento-frontend` `d3810a0`).** ① `CHANGELOG.md:80`은 "`<base>-api-contract.ts`의 `schemas`를 `<base>-schema-metadata.ts`로 옮겨 … memento-frontend의 `memento-web`이 해당한다"고 적는다. 리뷰 README(`docs/reviews/2026-11-01-maturity-review/README.md:627`)도 "memento-web 기능은 V2 API 행을 쓰므로"라고 적는다. 그러나 memento-web에는 `*-api-contract.ts`가 없다. V2 필드는 `contracts/memento-feature-contract.ts`에 있고, `apiOperations: Object.freeze({})`(`:295`)와 `mappers: Object.freeze({})`(`:29`)는 비어 있다. V2 API 행은 0개다. 남은 V2 필드는 라우트 codec 7개(`runtimeSchemas: MEMENTO_RUNTIME_SCHEMA_CODECS`, `:28`)다. 이 경우 맞는 안내는 15-01 1단계("기능 계약에서 `schemas`를 별도 파일로", `CHANGELOG.md:28`)이고, `:80`의 파일 이름은 맞지 않는다. ② **안내가 말하지 않는 실제 작업.** memento-web의 HTTP는 V3 descriptor 29개(`memento-http-contract-contribution.ts`)뿐이다. memento의 지금 FE-REG-API는 V2 행에서만 만들어져 이 29개를 검사하지 않았다. `12f3bb7` 뒤에는 descriptor에서 행을 뽑으므로(`src/contracts/api-operations.ts:34-56`) 29개 행이 새로 생긴다. 각 행의 `requestSchema`·`responseSchema`는 FE-REG-SCHEMA를 참조해야 한다(`config/contracts/registry-governance.json:200-210`). memento-web 검증기의 스키마 ID는 요청·응답 합쳐 42개이고, 스키마 메타데이터 7행(라우트용)에는 하나도 없다. 그래서 동기화 직후 `check:registries`는 29 × 2 = 58줄로 실패한다(메커니즘은 실험 E-3에서 확인). 또 FE-REG-SCHEMA의 `runtime`은 `"zod"`만 허용하는데(`registry-governance.json:252`), memento 검증기는 zod가 아니라 손으로 쓴 `isRecord` 검사다(`memento-http-contract-contribution.ts:131-150`). 제품은 42개 검증기를 zod로 다시 쓰거나, 사실과 다른 `runtime: "zod"`를 적거나, 템플릿 governance를 고쳐야 한다. 안내에는 셋 다 없다. ③ memento의 runtime descriptor에는 제품이 붙인 `ownsShell: true`(`presentation/memento-feature-runtime-descriptor.ts:35`)와 라우터 다리(`src/presentation/routes/app-router.tsx:545-561`)가 있다. 15-01은 runtime descriptor를 지웠고(`CHANGELOG.md:24`), 갈 곳은 `context-layout.tsx`의 `CONTEXT_LAYOUT`(`:70`)이다. 두 행을 잇는 안내가 없다. **tech-log(`7a4e201a`).** 제품 도메인을 `NOT_INSTALLED`로 두고 `installed-*` 파일에 직접 조립한다(`src/features/tech-log/NOT_INSTALLED`). tech-log가 고친 `src/features/installed-feature-runtimes.tsx`(`af3d8e6` 대비 12줄)는 이 커밋에서 지워졌다. 15-01 이행 순서(`CHANGELOG.md:26-36`)는 `feature-module.ts`가 있는 기능만 다룬다. 직접 조립 제품이 실행부를 어디에 두는지는 CHANGELOG·매뉴얼·`starter-experience.md` 어디에도 없다. **재현(E3, 실험 E-5).** 다음 동기화 충돌은 memento 25경로(내용 24, modify/delete 1), tech-log 76경로(내용 40, modify/delete 36, rename/delete 1) |
| 발생 조건 | 두 제품이 이 묶음을 동기화할 때 |
| 영향 | memento 담당자는 안내대로 `*-api-contract.ts`를 찾다가 없음을 알고, 동기화 뒤 처음 만나는 `check:registries` 58줄 실패에서 원인을 다시 찾는다. zod 전용 칸 때문에 검증기 42개를 다시 쓰는 일이 생길 수 있다(일정에 걸리는 작업량). tech-log는 실행부 위치를 스스로 설계하거나 템플릿 파일을 다시 고친다. 그러면 0929/14-03의 영구 충돌이 이어진다 |
| 심각도·우선순위 | Medium · P1 — 모든 누락은 게이트가 막는다(조용한 실패 없음). 그러나 CHANGELOG가 이름으로 가리킨 바로 그 다운스트림의 이행 안내가 틀렸고, 두 제품 동기화의 첫 장애물이다 |
| 통제·증거 | 목표 M3(이행 안내를 다운스트림 모양의 fixture에 적용해 게이트가 통과하는지 본다). 확인: M1(안내 문장만) · memento 모양 E1, 게이트 동작 E3(실험 E-3), 충돌 수 E3(실험 E-5) |
| 확실성과 남은 가정 | 42개는 descriptor의 `*Validator("Memento…")` 인자 문자열을 센 값이다(`MementoProblem` 제외). 실제 병합 뒤 실패 줄 수는 확인하지 않았다(충돌을 먼저 풀어야 한다). `check-registries.ts`는 `runtime` 값만 보고 검증기가 실제 zod인지 보지 않는다. 그래서 사실과 다른 값을 적어도 통과한다는 것은 코드에서 읽은 추론이다 |
| 결정의 근거 | 확인된 사실: 템플릿 리뷰는 다운스트림이 V2 클라이언트를 부르지 않는다는 것은 확인했다(`CHANGELOG.md:81`). 기록된 판단: "memento-web이 V2 API 행을 쓴다"(`12f3bb7` 본문). 리뷰어의 추론: `apiOperations` 필드가 있다는 것을 행이 있다고 읽었다. 선택 비교는 5.1절 |
| 이해 비용 | 동기화 담당자가 템플릿의 `12f3bb7` diff, governance, 자기 descriptor 29개를 대조해야 작업량을 안다 |
| 최소 개선 방향 | ① `:80`의 옮기는 법을 두 경우로 나눈다: "스키마가 `*-api-contract.ts`에 있으면 …", "기능 계약(`*-feature-contract.ts`)에 있으면 15-01 1단계". ② "V2 행이 없어도 V3 descriptor가 있는 기능은 동기화 뒤 FE-REG-API 행이 새로 생기고, 그 입력·응답 스키마 ID마다 FE-REG-SCHEMA 행이 필요하다. `runtime`은 `zod`만 허용한다"를 적는다. memento-web은 29 operation·42 스키마 ID라고 숫자를 적는다. ③ runtime descriptor에 제품 필드를 붙였다면 `CONTEXT_LAYOUT`(`:70`)으로 옮긴다는 줄을 15-01 5단계에 더한다. ④ `NOT_INSTALLED` 직접 조립 제품의 이행 길을 정한다(기능 모듈로 바꾸기 / 직접 조립 위치). 정할 때까지 "직접 조립 제품은 안내 없음"을 알려진 제한에 적는다 |
| 대안 비교 | (A) 안내 문장만 고친다: 싸다. 다음 BREAKING에서 다시 틀릴 수 있다. (B) (A) + 다운스트림 모양 fixture 두 개(빈 `apiOperations`·V3 descriptor·손으로 쓴 검증기를 가진 기능, `NOT_INSTALLED` 직접 조립)로 "이행 안내 적용 후 게이트 통과" 테스트: 이행 안내가 검증된다. fixture 유지비가 든다. (C) `runtime` 허용 값에 `"custom"`을 더한다: memento 검증기를 다시 쓰지 않아도 된다. 대신 검증 품질 표시가 약해진다(07 영역 판단). (A)를 지금, (B)는 다음 BREAKING 전에 |
| 단순화의 보존 조건 | FE-REG-API·FE-REG-SCHEMA 참조 검사는 약하게 하지 않는다. 제품이 검사를 피하려고 governance를 고치는 길을 안내하지 않는다 |
| 비용·부작용 | (A) CHANGELOG 몇 줄. (B) fixture 2개와 테스트 1개 |
| 재검토 조건 | 다운스트림이 셋 이상이 되거나, `create:feature`로 만든 기능만 쓰는 제품만 남으면 안내 대상이 바뀐다 |
| 완료 기준 | memento-web 모양에 안내를 그대로 적용하면 `check:registries`가 통과한다. tech-log 모양의 이행 길이 CHANGELOG나 매뉴얼에 있다 |
| 검증 방법 | (B)의 fixture 테스트. 또는 memento clone에서 실제 병합 뒤 안내만 보고 `check:registries`·`check:types`를 통과시키는 실험 |
| 담당·기한·상태 | 미정 · memento·tech-log 동기화 전 · 신규 |
| 재검증 결과 | 미실시 |
### 14-03 목표 설계 문서의 상태 값과 결정이 V2 삭제를 반영하지 않는다 — VD-23은 정본 8.4와 반대로 "401 recovery 한 번"을 적고, 지금 실행 규칙(6.1 표)은 "구현 대기" 문서에 있다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 5, 17, 24, 4, 15 |
| 근거 | **읽는 법이 정해져 있다.** `docs/README.md:11-13`은 목표 설계 문서의 기능이 지금 동작하는지 "문서 안의 상태 값(`COMPOSED` …)으로 확인한다"고 적는다. **① 지운 것이 `COMPOSED`.** VD-23 머리 `:3-7` "REST v2 security/execution baseline: `COMPOSED`", `:26` "401 replay를 포함한 physical attempt", 2절 `:67` 목표 API `defineRestOperation`(지운 이름, `CHANGELOG.md:80`). `api-contract-schema-mapper-and-server-state.md:83` "shared REST JSON executor … bounded auth recovery" `COMPOSED`, `:85` "REST v2 security/execution baseline … named bearer/CSRF profile" `COMPOSED`(V2 프로필 해석은 `12f3bb7`에서 지움), `:101` "schema/mapper v2 reference baseline" `COMPOSED`, `:267` "현재 installed reference operation은 REST v2 metadata를 사용한다". VD-24 머리 `:3-4` "reference typed codec/mapper baseline composed"(`MAPPER_REGISTRY` 삭제). **② 401 규칙이 반대.** VD-23 `:422` "401 recovery는 auth-required이면서 replay-safe한 operation만 한 번 수행한다", `:423` "동시 401은 session owner의 single-flight recovery를 공유한다". 정본 `2026-07-30-…-closed-deep-design.md:1636-1643`(8.4, FRT-D016 `:5687`)은 "401 response 뒤 hidden refresh-and-replay를 하지 않는다", "command를 새 credential로 자동 replay하지 않는다"다. 코드도 정본과 같다(`src/adapters/http/http-execution-v3.ts:777-778` "A response 401 is terminal; there is no hidden refresh-and-replay"). 코드 주석 5곳이 결정 근거로 `VD-23`을 가리킨다(`http-contract-bridge.ts:20`, `http-execution-v3.ts:226`, `external-contract-runtime.ts:385`, `rest-profiles.ts:11`, `:112`). VD-23에는 다른 목표 설계 문서에 있는 "정본과 충돌하면 정본을 따른다" 머리 안내가 없다. **③ 지금 실행 규칙이 "구현 대기" 문서에.** `src/adapters/http/backend-envelope.ts:84-90`의 `REFUSED_BEFORE_WRITE` 표는 `backend-api-and-server-state-contract.md` 6.1절(`:257-`)을 근거로 들고, 백엔드 SHA가 바뀌면 그 절과 다시 맞추라고 적는다. 그 문서는 `docs/README.md:65`에서 "목표 설계"이고, 머리(`:11-12`)는 "backend implementation/evidence pending", 기준일 2026-07-28이다. 그래서 6.1절은 `verify:documentation` 검사 밖이다 |
| 발생 조건 | 개발자가 HTTP 인증 실패 처리나 자격증명 owner를 구현하며 VD-23을 근거로 읽을 때. 상태 값으로 "무엇이 동작하나"를 판단할 때. 백엔드 기준 커밋이 바뀌어 6.1 표를 다시 맞출 때 |
| 영향 | VD-23대로 401 뒤 자동 재전송을 제품 쪽에 만들면 정본이 막으려던 command 중복 재실행 위험이 생긴다(V3 실행기 안에서는 막혀 있다. 위험은 제품이 바깥에 감싼 코드다). 지운 V2 경로를 동작하는 것으로 믿고 찾는다. 6.1 표를 "목표"로 보고 무시하거나 갱신을 놓친다 |
| 심각도·우선순위 | Medium · P2 — 실행기 자체는 정본대로라 템플릿 기본 동작에는 피해가 없다. 그러나 코드가 직접 가리키는 결정 기록이 인증·재전송이라는 위험 경로에서 반대 규칙을 적는다 |
| 통제·증거 | 목표 M2(지운 기능의 상태 값을 같은 변경에서 고친다)·M1(VD에 정본 우선 안내). 확인: M0(V2 삭제 커밋 `048f490`·`12f3bb7`이 고친 `docs/architecture/` 문서는 `backend-api-and-server-state-contract.md`, `frontend-platform-capability-review.md`, `starter-experience.md`다. VD-23·VD-24·`api-contract-schema-mapper-and-server-state.md`는 없다) · E1 |
| 확실성과 남은 가정 | 문장과 코드 대조는 직접 확인했다. 목표 설계 문서 전체(약 3만 줄)는 읽지 않았다. 같은 종류의 낡은 상태 값이 더 있을 수 있다(`git grep -i -E 'rest v2|v2 (client|metadata|baseline)|mapper registry|operation mapper' -- docs/architecture README.md` 결과 8개 파일 17곳) |
| 결정의 근거 | 기록된 판단: 리뷰 README 14.7절이 VD-23 문장을 "리뷰 대상"으로 넘겼다. 선택 비교는 5.3절 |
| 이해 비용 | 코드 주석 → VD-23 → 정본 8.4 → 코드 순으로 읽어야 어느 쪽이 맞는지 안다 |
| 최소 개선 방향 | ① VD-23 `:422-423`을 정본 8.4 문장으로 바꾸고 머리에 정본 우선 안내를 붙인다. ② VD-23·VD-24·`api-contract-schema-mapper-and-server-state.md`의 V2 행 상태를 `REMOVED (2026-11-03, 048f490·12f3bb7)`로 바꾸거나 행을 지운다. 지금 경로(V3 실행기, descriptor 투영)를 `COMPOSED` 행으로 적는다. ③ 6.1절을 현재 계약 문서로 옮기거나(예: `docs/contracts/` 아래), `docs/README.md` 1절에서 그 절만 링크해 경로 검사를 받게 한다 |
| 대안 비교 | 5.3절: (a) 현 상태 (b) 지울 때 함께 고치기 + 정본 우선 안내 (c) V2 시절 서술을 이력으로 옮기기 (d) 상태 값을 코드 옆 레지스트리로. (b)+③ 권장 |
| 단순화의 보존 조건 | 정본(07-30 문서)의 8절은 바꾸지 않는다. 6.1 표의 내용과 백엔드 줄 참조는 그대로 옮긴다 |
| 비용·부작용 | 문서 3~4개 수정. ③을 하면 6.1의 백엔드 repo 경로(`../../../clean-architecture-backend-template/…`)를 검사가 어떻게 볼지 정해야 한다(지금 검사는 이 repo 밖 링크를 건너뛰는지 확인 필요) |
| 재검토 조건 | 목표 설계 문서를 상태별 폴더로 나누게 되면(1101/14-07 (C)) 함께 정한다 |
| 완료 기준 | VD-23에 "401 … 한 번 수행" 문장이 없다. 목표 설계 문서에서 지운 V2 구성요소가 `COMPOSED`로 남지 않는다. 6.1 표가 현재 계약 문서에 있거나 `docs/README.md` 1절에서 링크된다 |
| 검증 방법 | `git grep -n -E '401 recovery는|REST v2 .*COMPOSED|v2 reference baseline' -- docs/architecture` 0건. 6.1 표에 적힌 이 repo 경로 하나를 없는 경로로 바꾸는 변이에서 `verify:documentation` 실패 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 미실시 |
### 14-04 참조 기능을 지우면 매뉴얼·입구 문서 8개가 merge 게이트 FE-GATE-017을 실패시킨다. 제거 드릴은 문서를 복사하지 않고 그 게이트를 돌리지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 27, 30.5, 30.3, 20, 10, 21 |
| 근거 | **약속.** `README.md:90`·`:108`은 참조 기능을 "removable reference feature"로 Default 계층에 둔다. `docs/manual/README.md`는 작업 이력에 기대지 않는다고 적지만, 예시는 참조 기능 경로로 든다. **실험 E-6(E3).** 참조 기능·참조 context·그 테스트 폴더를 지우고 `verify:documentation`을 돌리면 `FAIL_UNVERIFIED (failed: document references)`다. 문서 8개가 없는 경로 18개를 적는다: `docs/manual/01-add-a-feature.md` 9개(`src/features/reference-feature/domain`, `…/presentation/reference-resource-form-page.tsx` 등), `starter-experience.md` 2개, `docs/manual/reference/patterns.md` 2개, `README.md`·`02-decision-tables.md`·`reference/create-feature.md`·`scale-architecture.md`·`compatibility.md` 각 1개. **드릴이 못 보는 이유.** `scripts/lib/removal-fixture.ts:25-39`의 복사 대상에 `docs/`·`README.md`가 없다. `scripts/test-sample-removal.ts:205-214`는 문서 검사 테스트(`documentation-readiness.test.ts`, `changelog-review-ids.test.ts`)를 fixture에서 지우며 이유를 "removing a feature does not change them"이라고 적는다. 실험이 이 전제가 틀렸음을 보인다. 검사 목록(`:401-414`)에도 `verify:documentation`·`lint`·`check:i18n`·`check:design-system`이 없다(FOLLOW-UP 09-07). CHANGELOG는 이 결과를 안다(`CHANGELOG.md:100` "참조 기능을 지운 복사본은 그 파일을 가리키는 문서를 고쳐야 통과한다"). 그러나 README의 제거 안내(`:232-236`)와 매뉴얼은 말하지 않는다. **다운스트림.** tech-log는 참조 기능을 `NOT_INSTALLED`로 두고 `presentation/`, `feature-module.ts`, `context-routes.ts`를 지웠다(E-5의 modify/delete 목록). 동기화로 `docs/manual/`과 고친 `docs/README.md` 1절이 들어오면 tech-log의 FE-GATE-017이 실패한다 |
| 발생 조건 | 제품이 README·드릴의 안내대로 참조 기능을 지우고 merge 게이트를 돌릴 때. 참조 기능을 지운 제품이 이 묶음을 동기화할 때 |
| 영향 | 제품이 merge 게이트를 통과하려면 템플릿 소유 문서(매뉴얼)를 고치거나 지워야 한다. 고치면 다음 동기화마다 그 문서가 충돌한다(0929/14-03과 같은 원리). 지우면 매뉴얼을 잃는다. 드릴 PASS가 "지울 수 있다"의 증거로 쓰이지만 merge 게이트 일부만 덮는다 |
| 심각도·우선순위 | Medium · P2 — 게이트가 실패를 드러내므로 조용한 피해는 없다. 그러나 "샘플은 지울 수 있다"는 기본 약속과 "매뉴얼을 유지한다"가 서로 부딪친다 |
| 통제·증거 | 목표 M3(제거 드릴이 merge 게이트 전체를 돈다). 확인: 드릴 범위 M3(그 안의 검사), 문서 게이트 M0 · E3(실험 E-6), 드릴 실행 E2(실험 E-12) |
| 확실성과 남은 가정 | 실험은 드릴 대신 폴더 삭제로 했다. 드릴은 `SAMPLE_EXTRAS`도 지우므로 없는 경로 수는 늘 수 있다. tech-log의 실제 병합 뒤 실패는 실행하지 않았다(경로 대조로 추론) |
| 결정의 근거 | 설계 선택이다. 5.2절 |
| 이해 비용 | 제품 개발자는 드릴 PASS를 보고 지운 뒤, merge 게이트에서 문서 실패를 처음 만난다 |
| 최소 개선 방향 | ① 매뉴얼의 예시 경로를 지워지지 않는 자리로 옮긴다: 생성 명령이 만드는 경로 모양(`src/features/<id>/…`, 검사가 경로로 보지 않는 꼴)이나 테스트 fixture(`tests/helpers/fixture-feature.tsx`). 참조 기능은 "있으면 더 볼 곳"으로 백틱 없이 적는다. ② 드릴의 복사 대상에 `docs/`·`README.md`를 넣고 검사 목록에 `verify:documentation`·`lint`·`check:i18n`·`check:design-system`을 더한다. `test-sample-removal.ts:210-211` 주석을 고친다. ③ ②가 비싸면 README 제거 안내에 "지운 뒤 FE-GATE-017이 가리키는 문서 줄을 고친다"를 적는다 |
| 대안 비교 | 5.2절: (a) 현 상태 (b) 예시를 지워지지 않는 자리로 (c) 검사가 참조 기능 경로를 "없어도 되는 경로"로 예외 처리 (d) 참조 기능을 지울 수 없는 기본 구성으로. (b) + 드릴에 문서 게이트 추가 권장 |
| 단순화의 보존 조건 | `documentReferences` 검사 자체는 약하게 하지 않는다. 매뉴얼의 단계 구성과 오류 문구 표는 유지한다 |
| 비용·부작용 | (b) 매뉴얼 18곳 수정. 드릴 시간 증가(lint 약 13초, 문서 검사 약 2초, 오케스트레이터 게이트 시간 기준) |
| 재검토 조건 | 참조 기능을 지울 수 없는 기본 구성으로 바꾸기로 하면 이 발견은 "README 약속 정정"으로 바뀐다 |
| 완료 기준 | 참조 기능을 지운 복사본에서 `verify:documentation`이 통과한다. 드릴이 그것을 검사한다 |
| 검증 방법 | 실험 E-6 재실행. 드릴 JUnit에 문서 검사 항목이 생긴다 |
| 담당·기한·상태 | 미정 · 미정 · 신규. FOLLOW-UP(09-25) 09-07을 이 항목에 합친다 |
| 재검증 결과 | 미실시 |
### 14-05 기능 폴더 밖 정본 표와 결정표 5절이 지운 검사의 메시지와 틀린 게이트 기대를 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 20, 8, 9, 19, 21 |
| 근거 | ① `docs/manual/02-decision-tables.md:202-203`과 `docs/architecture/starter-experience.md:190`이 `REST security profiles are incoherent for <operationId>: …` 메시지를 적는다. 이 문자열은 `src`·`scripts`에 없다. `12f3bb7`이 `resolveRestSecurityProfiles`와 함께 지웠다(실험 E-11). 지금 메시지는 `<featureId>/<operationId>: unknown authProfileId <id>`이고, `01-add-a-feature.md:268`·`reference/errors.md:74`는 맞게 적는다. 02 `:201`의 "`auth`와 조합이 틀리면"도 V3 descriptor에 없는 칸(`auth`)을 말한다. ② `starter-experience.md:190`은 제품 런타임 설정 키의 FE-REG-ENV 행에 대해 "nothing requires the row"라고 적는다. 그 뒤 `d0414c8`의 `tests/unit/env-registry-coverage.test.ts:9-18`이 그 행을 요구한다. 실험 E-10: `PRODUCT_RUNTIME_CONFIG_FIELDS`에 키 하나를 더하고 행을 빼면 이 테스트가 `expected [ 'NOTICE_SOURCE' ] to deeply equal []`로 실패하고, `check:registries`는 통과한다. 매뉴얼 03 C절은 이 표를 정본으로 가리킨다. ③ `verify:documentation`은 설명·문구를 보지 않는다(`docs/README.md:52-54`, 설계상) |
| 발생 조건 | 매뉴얼로 제품 인증 프로필이나 제품 설정 키를 더하다가 실패를 만났을 때 |
| 영향 | 오류 문구로 매뉴얼을 검색하면 찾지 못한다. 설정 키를 더하는 사람은 `check:registries` 통과를 끝으로 알고 있다가 `test:unit`에서 실패를 만난다. 데이터·보안 영향은 없다 |
| 심각도·우선순위 | Low · P2 — 문서 몇 줄의 어긋남이다. 다만 매뉴얼은 "메시지는 코드의 문자열을 그대로 옮긴다"(`docs/manual/README.md`)를 약속하고, 이번 BREAKING이 그 문구를 지웠다 |
| 통제·증거 | 목표 M3(매뉴얼·정본 표의 오류 문구가 코드에 있는지 검사). 확인: M0 · E3(실험 E-10, E-11) |
| 확실성과 남은 가정 | 매뉴얼의 백틱 문구 중 오류 메시지로 보이는 27개를 코드와 대조했다. 템플릿 문자열로 만드는 메시지는 고정 부분으로 확인했다. 없는 것은 위 2개뿐이었다 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다. 문구 검사를 둘지는 아래 대안 |
| 이해 비용 | 작다. 실패 원인을 매뉴얼 대신 코드에서 찾는다 |
| 최소 개선 방향 | ① 02 `:201-203`을 `01-add-a-feature.md:268`과 같은 문구로 바꾸고, 쿠키 프로필 쓰기의 CSRF 거절(`reference/errors.md:75`)을 더한다. ② `starter-experience.md:190`의 두 셀을 고친다: 메시지, "FE-REG-ENV row: `tests/unit/env-registry-coverage.test.ts`(`test:unit`)가 키마다 요구한다". ③ (선택) `reference/errors.md` 첫 열의 고정 부분이 `src`·`scripts`·`eslint.config.ts`에 있는지 보는 단위 테스트 |
| 대안 비교 | ③ 검사: 문구 drift를 잡는다. 템플릿 문자열 메시지는 고정 부분만 볼 수 있다. 검사 없이 BREAKING 커밋 체크리스트에 "매뉴얼 문구 grep"을 두는 방법은 더 싸지만 이번처럼 빠질 수 있다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 3곳. ③은 테스트 수십 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `git grep 'REST security profiles are incoherent' -- docs/manual docs/architecture/starter-experience.md` 0건. 정본 표가 FE-REG-ENV 행을 요구하는 테스트를 적는다 |
| 검증 방법 | 실험 E-11 스크립트 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 미실시 |
### 14-06 `check:registries`가 계약 조립 실패의 원인(`reason`)을 버리고, 레지스트리가 통째로 지워진 것처럼 breaking 증거 누락을 연쇄로 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 20 |
| 근거 | 실험 E-9: `create:feature notice-feature`로 만든 기능의 `authProfileId`를 없는 값으로 바꾸면 `check:registries` 출력은 `missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable`(2번), `FE-REG-API is not an object registry`, `FE-REG-ROUTE references unknown registry FE-REG-SCHEMA` 등 4줄, `breaking change missing evidence: FE-REG-API:*:*:removed`, `…FE-REG-SCHEMA:*:*:removed`다. 원인(`notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE`)은 없다. 원인은 `ContractContributionError.reason`에 있고(`src/contracts/external-contract-runtime.ts:266-275`), 검사기는 `error.message` 첫 줄만 적는다(`scripts/check-registries.ts:374`). 같은 변경에서 vitest(`tests/features/notice-feature`)는 `reason`을 보여 준다. 매뉴얼은 이 빈칸을 안다: `reference/errors.md:90` "메시지만 보이면 `reason`을 출력해 본다" |
| 발생 조건 | 기능 계약 조립이 실패하는 실수(인증 프로필, 중복 operation, fixture 출처, CSRF 프로필)에서 `check:registries`를 먼저 돌릴 때 |
| 영향 | 끝의 두 줄은 "breaking 증거를 더하라"로 읽힌다. 실수 하나에 틀린 다음 행동을 제안한다. 원인을 보려면 다른 명령을 돌린다 |
| 심각도·우선순위 | Low · P3 — 게이트는 올바르게 실패하고, 매뉴얼에 우회 방법이 있다 |
| 통제·증거 | M2(검사는 있음, 진단이 원인을 버림) · E3(실험 E-9) |
| 확실성과 남은 가정 | 없음 |
| 결정의 근거 | 적용 제외 — 진단 출력 보강 |
| 이해 비용 | 실패 하나마다 vitest를 따로 돌려 원인을 본다 |
| 최소 개선 방향 | ① `check-registries.ts:374`에서 오류에 `reason`이 있으면 함께 적는다. ② 레지스트리 source를 읽지 못한 경우 그 레지스트리의 호환성 비교(`removed` 증거 요구)를 건너뛴다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 실험 E-9 변이에서 `check:registries` 출력이 `unknown authProfileId NOTICE_NOPE`를 포함하고 `removed` 줄이 없다 |
| 검증 방법 | 실험 E-9 재실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규. 12 영역(guardrail)과 겹칠 수 있다 |
| 재검증 결과 | 미실시 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 01~13 영역 | - | - | 이 영역은 문서·스크립트만 본다 |
| 2 | 구조적 성숙도 | > 09·12 영역 | M3 / M3(문서-규칙 대조) | E3 | 구조 설명 문서가 규칙과 맞고 검사된다(1101/14-03 고쳐짐) |
| 3 | 변경 용이성 | 적용 | M2 / M1 | E3 | P — 다음 동기화 충돌 memento 25, tech-log 76. 확장 지점은 열렸지만 제품이 옮기기 전이라 효과 미확인(0929/14-03) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 문서 177개 86,108줄(지난 라운드 151개 75,450줄). 기능 추가는 매뉴얼 1,620줄 한 경로로 줄었다. 목표 설계 상태 값이 실제와 달라 확인 부담이 남는다(14-03) |
| 5 | 위험 가시성 | 적용 | M2 / M1 | E1 | P — CHANGELOG 알려진 제한 13줄 중 9줄이 낡았다(14-01). VD-23이 인증 재전송 규칙을 반대로 적는다(14-03) |
| 6 | 실패 성숙도 | > 다른 영역 | - | - | - |
| 7 | 운영 성숙도 | > 11·13 영역 | - | - | runbook은 이 영역에서 다시 보지 않았다 |
| 8 | 디버깅 가능성 | 적용 | M3 / M2 | E3 | P — `verify:documentation` 실패 메시지는 검사·문서·경로를 적는다(1101/14-06 고쳐짐). `check:registries`가 조립 실패 원인을 버린다(14-06) |
| 9 | 유지보수 성숙도 | **깊게 봄** | M3 / M1~M3 | E3 | P — 이력 삭제 뒤에도 근거가 남는다(1101/14-01 고쳐짐, E-8). BREAKING 변경이 CHANGELOG·목표 설계 문서·정본 표를 함께 고치지 않았다(14-01, 14-03, 14-05) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(범위 안) | E2·E3 | P — 문서 검사는 변이 4개를 모두 잡았다. 제거 드릴은 문서·lint·i18n·디자인 게이트를 돌리지 않는다(14-04) |
| 11 | 데이터 성숙도 | - 이 영역에 데이터 경계가 없다 | - | - | - |
| 12 | 동시성 성숙도 | - 이 영역에 동시 실행 경로가 없다 | - | - | - |
| 13 | 확장성 | > 11 영역 | - | - | - |
| 14 | 성능 성숙도 | > 13·15 영역 | - | - | 문서 규모만 4번에 적었다 |
| 15 | 보안 성숙도 | > 다른 영역 | - | E1 | CSRF 조립 검사는 CHANGELOG `:78`에 [보안][계약]으로 있다. VD-23의 401 재전송 문장은 위험한 쪽으로 틀렸다(14-03) |
| 16 | 의존성 성숙도 | 적용(제품에게 템플릿은 의존성) | M2 / M1 | E3 | P — 태그 `v0.2.0` 뒤 177커밋이 태그 없이 쌓였다. 두 제품의 기준점 형식이 다르다(0929/14-02) |
| 17 | API / Contract 성숙도 | 적용 | M3 / M1 | E1·E3 | P — BREAKING 행에 지운 이름 목록이 있다. 이행 안내가 실제 다운스트림과 다르고(14-02), 한 브랜치의 계약 변경이 빠졌다(14-01) |
| 18 | 배포 성숙도 | > 13 영역 | - | - | - |
| 19 | 설정 성숙도 | 적용 | M3 / M1~M3 | E3 | P — README 변수 표는 검사된다. FE-REG-ENV 행 요구가 정본 표에 반대로 적혔다(14-05). `FEATURE_OVERRIDES` "조용히 무시"(0929/14-05) |
| 20 | 개발자 경험 | **깊게 봄** | M3 / M2 | E3 | P — `create:feature`로 만든 기능이 `check:registries`(additive)·`verify:documentation`을 통과했다(E-9). 매뉴얼 오류 문구 27개 중 2개가 지운 메시지다(14-05). 참조 기능을 지우면 문서 게이트가 실패한다(14-04). 깨끗한 환경 설치는 미검증 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M0~M3 | E3 | P — 문서 경로·폴더·규칙 이름은 M3(변이). 오류 문구, CHANGELOG 완전성, 목표 설계 상태 값은 M0(14-01, 14-03, 14-05) |
| 22 | 추상화 성숙도 | > 09 영역 | - | - | - |
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 기준점 형식 2개(0929/14-02). CHANGELOG 리뷰 참조가 `MMDD/NN-MM`, `1101/14.4`, `1101 README 14.3`, `README 13.6` 네 꼴로 섞였다(1101/14-02 잔여) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P — "V2 API 행을 쓴다"가 행 0개를 가리킨다(14-02). 지운 경로가 `COMPOSED`다(14-03) |
| 25 | 조직 확장성 | 적용 | M2 / M1 | E3 | P — 두 제품이 다른 동기화 방식(merge / 3-way)을 쓰고 둘 다 이번에 크게 충돌한다(E-5). 다운스트림 모양을 검증하는 장치가 없다(14-02) |
| 26 | Ownership 성숙도 | **깊게 봄** | M1 / M0~M1 | E1 | P — CHANGELOG 행에 이행 담당·확인 칸이 없다. 알려진 제한을 고친 커밋이 그 줄을 닫지 않았다(14-01). 다운스트림 결함 보고 경로는 기록이 없다(0929/14-06) |
| 27 | 삭제 가능성 | **깊게 봄** | M3 / M3(드릴 범위) | E2·E3 | P — 이력 삭제는 게이트와 근거를 모두 지킨다(E-8). 참조 기능 삭제는 드릴 범위에서는 검사되지만(E-12) merge 게이트 FE-GATE-017에서 실패한다(14-04) |
| 28 | 회복 가능성 | > 다른 영역 | - | - | 동기화 되돌림(`git revert`, `README.md:374`)은 실행하지 않았다 |
### 4.1 30절 템플릿 기준
| 절 | 판정 | 근거 |
|---|---|---|
| 30.1 최소 구성과 안전한 기본값 | P | `create:feature`의 자리표시자 계약 신원은 staging·production 승인이 거절한다(`CHANGELOG.md:96`, 매뉴얼 1단계). 생성 명령도 같은 경고를 출력한다(E-9). 깨끗한 환경 실행은 이번에도 확인하지 못했다 |
| 30.2 옵션 조합의 수와 검증 책임 | P | 지원 범위 표(`README.md:101-`)는 있다. 조합 검증 범위는 이 영역에서 새로 보지 않았다 |
| 30.3 생성·복사 후 수정 권한 | P | 제품 소유 파일 두 개와 "고치지 않는다" 목록(매뉴얼 03 C·D절)이 생겼다. 생성 명령은 있는 파일을 덮어쓰지 않는다(매뉴얼 1단계). 그러나 참조 기능을 지운 제품은 템플릿 소유 매뉴얼을 고쳐야 게이트를 통과한다(14-04) |
| 30.4 버전과 업데이트 전파 | **X(이 묶음)** | 미출시 절이 기준 커밋과 맞지 않고(14-01) 이행 안내가 다운스트림과 다르다(14-02). 다음 동기화 충돌 25/76(E-5). README 업데이트 절차는 범위 반영을 다루지 않는다(0929/14-02) |
| 30.5 샘플 코드의 대표성 | P | 매뉴얼은 "참조 기능을 복사하지 말라"고 하고 생성 명령으로 시작하게 한다(01 문서 `:8-10`). 생성 기능은 짝 백엔드 Envelope를 읽고, 참조 기능은 읽지 않는다(`CHANGELOG.md:130`). 예시 경로는 여전히 참조 기능이다(14-04) |
| 30.6 도입·유지 비용 | P | package script 140개, CI 게이트 27개, 문서 177개 86,108줄(그중 `docs/reviews/` 30,905줄). 이번 동기화 범위 177커밋·583파일 |
| 30.7 템플릿에서 졸업할 수 있는가 | P | 확장 지점이 늘어 템플릿 파일을 고치지 않는 길이 넓어졌다. `runtime: "zod"` 같은 닫힌 값이 제품 검증기 선택을 묶는다(14-02) |
| 30.8 배포 판단에 필요한 최소 증거 | P | "새 프로젝트 시작": 깨끗한 환경 증거 없음. "기본 패턴으로 기능 추가": `create:feature` 실험(E-9). "선택 기능 분리": 드릴 E2, 문서 게이트 실패 E3. "패치 전달": 충돌 재현 E3, 이행 안내 검증 없음 |
## 5. 설계 선택 검토 (41절)
### 5.1 CHANGELOG 미출시 절을 "작업 브랜치의 누적 기록"으로 쓰는 방식 (14-01, 14-02)
1. **무엇이 필요한가.** 다운스트림이 한 번의 동기화(기준 커밋 A → B)에 필요한 일을 한 곳에서 안다. 동시에 템플릿 작업자는 변경마다 기록을 남긴다.
2. **지킬 성질.** 미출시 절이 가리키는 범위의 모든 계약 변경이 행을 가진다. 해시는 그 범위에서 찾을 수 있다. 같은 절 안에 서로 반대되는 행이 없다.
3. **현재 보장.** 행은 커밋할 때마다 손으로 더한다. 브랜치를 합칠 때 다시 맞추는 단계가 없다. 그래서 한 브랜치의 16커밋이 빠졌고, V2를 고친 행(`:74-77`)과 V2를 지운 행(`:81`)이 함께 있고, 알려진 제한은 쓴 시점에 멈췄다. ID 형식만 테스트가 본다.
4. **대안.** (a) 현 상태. (b) 동기화 단위 순 변경 요약: 태그·기준 커밋마다 "옮기기 전 / 옮기는 법 / 옮긴 뒤 확인"을 최종 상태로 쓴다. 중간 상태 행은 지운다. (c) 커밋 trailer(`Changelog: 계약 | 없음`)에서 후보 목록을 만들고, 사람이 (b)를 쓴다. (d) CHANGELOG를 없애고 커밋 본문만 쓴다.
5. **비교.**
- (a)는 쓰는 비용이 가장 낮다. 동기화하는 쪽 비용이 가장 높다(이번 사례).
- (b)는 출시 직전 한 번의 정리 비용이 든다. 다운스트림이 읽을 양이 줄어든다. 중간 기록은 git에 남는다.
- (c)는 빠짐을 기계가 잡는다. 커밋 규칙이 하나 늘어난다. `commit-and-pr.md` 규칙과 맞춰야 한다.
- (d)는 177커밋을 읽게 만든다. 지금 README의 업데이트 절차와 맞지 않는다.
6. **선택.** (b)를 하고, 빠짐 검사로 (c)를 선택적으로 둔다. 이 템플릿의 소비자는 두 다운스트림이고 둘 다 "범위 단위"로 동기화한다(memento merge, tech-log 3-way). 커밋 단위 cherry-pick 안내(`README.md:354-363`)보다 범위 단위 요약이 실제 사용과 맞다.
7. **재검토 조건.** 다운스트림이 커밋 단위 cherry-pick으로 바뀌거나, 템플릿을 패키지·생성기로 배포하게 되면 다시 본다.
### 5.2 매뉴얼 예시를 지울 수 있는 참조 기능에 묶는 선택 (14-04)
1. **무엇이 필요한가.** 매뉴얼을 읽는 사람이 실제로 동작하는 예제를 본다. 동시에 참조 기능을 지운 제품도 매뉴얼과 merge 게이트를 그대로 쓴다.
2. **지킬 성질.** README가 "지울 수 있다"고 한 것을 지워도 merge 게이트가 통과한다. 템플릿 소유 문서를 제품이 고치지 않는다.
3. **현재 보장.** 매뉴얼은 참조 기능 경로를 백틱 경로로 적고, `verify:documentation`이 그 경로의 존재를 검사한다. 드릴은 문서를 복사하지 않아 이 충돌을 보지 못한다. 결과적으로 두 성질이 동시에 성립하지 않는다(E-6).
4. **대안.** (a) 현 상태. (b) 예시를 지워지지 않는 자리(생성 경로 모양, `tests/helpers/fixture-feature.tsx`)로 옮기고, 참조 기능은 백틱 없는 "더 볼 곳"으로. (c) 검사기가 README "지울 수 있는" 목록처럼 참조 기능 경로를 "없어도 되는 경로"로 본다. (d) 참조 기능을 지울 수 없는 기본 구성으로 바꾼다.
5. **비교.**
- (a)는 비용이 없다. 참조 기능을 지운 제품마다 문서를 고친다.
- (b)는 매뉴얼 18곳을 고친다. 예제의 구체성이 조금 줄지만 생성 명령이 같은 모양을 만든다.
- (c)는 문서를 안 고친다. 대신 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 독자는 링크를 따라가다 막힌다.
- (d)는 README 약속과 `test:sample-removal`의 존재 이유를 바꾼다. 범위가 크다.
6. **선택.** (b)를 하고 드릴에 문서 게이트를 더한다. 매뉴얼은 "생성 명령으로 시작한다"를 이미 기본 길로 정했다(01 문서 `:5-10`). 예시도 같은 기준에 맞추는 것이 일관된다.
7. **재검토 조건.** 참조 기능을 지우는 제품이 없다고 확인되면 (a)도 받아들일 수 있다. 지금은 tech-log가 일부를 지웠다.
### 5.3 목표 설계 문서의 상태 값을 손으로 유지하는 방식 (14-03)
1. **무엇이 필요한가.** "이 기능이 지금 있나"를 문서에서 답할 수 있다. 결정의 이유는 오래 남는다.
2. **지킬 성질.** 코드가 지운 구성요소는 상태 값이 `COMPOSED`로 남지 않는다. 결정 기록이 정본과 반대 규칙을 적지 않는다. 코드가 따르는 규칙표는 검사받는 문서에 있다.
3. **현재 보장.** 상태 값은 문서 작성 때 손으로 적는다. 삭제 커밋이 목표 설계 문서를 고칠 의무나 검사가 없다. 정본 우선 안내가 없는 VD도 있다. 6.1 표는 "구현 대기" 문서 안에 있다.
4. **대안.** (a) 현 상태. (b) 삭제·BREAKING 커밋이 `git grep`으로 찾은 상태 줄을 함께 고치고, VD 머리에 정본 우선 안내를 붙인다. 코드가 따르는 표는 현재 계약 문서로 옮긴다. (c) V2 시절 서술을 목표 설계에서 이력으로 옮긴다. (d) 상태 값을 코드 옆 레지스트리(JSON)로 옮기고 테스트가 구성요소 존재와 대조한다.
5. **비교.**
- (a)는 비용이 없다. `docs/README.md`가 안내한 읽는 법이 틀린 답을 준다.
- (b)는 이번에 문서 3~4개. 다음부터는 BREAKING 체크리스트 한 줄.
- (c)는 목표 설계 문서가 가벼워진다. 문서 재분류 작업이 크다(1101/14-07 (C)와 같이 할 일).
- (d)는 가장 강하다. 상태 어휘가 문서 수십 개에 흩어져 있어 이행 비용이 크다.
6. **선택.** (b). 이 묶음의 문제는 "삭제가 문서를 따라 고치지 않은 것"이라 그 지점만 막으면 된다.
7. **재검토 조건.** 목표 설계 문서가 현재 계약으로 하나씩 승격되기 시작하면(1101/14-07), 그때 (c)나 (d)를 다시 본다.
## 6. 실험 기록
모든 실험은 격리 worktree에서 했고, 끝날 때마다 `git checkout -- . && git clean -fd`로 되돌렸다(`git status --short` 0줄 확인). 보조 스크립트는 오케스트레이터 scratchpad의 `a14/`에 있다.
| ID | 무엇을 | 어떻게 | 결과 |
|---|---|---|---|
| E-1 | CHANGELOG 해시 위치 | 미출시 절(`:13-141`) 해시 78개를 `git merge-base --is-ancestor`로 `e40684b`와 `fix/ui-design-audit-2026-11-01`에 대조(`a14/hashes.sh`) | 78개 모두 `e40684b`에서 닿는다. 7개가 머리의 브랜치에 없다(14-01) |
| E-2 | CHANGELOG를 고친 브랜치 | `git log ec7435c..8c39e77 -- CHANGELOG.md`, `git log ec7435c..93c81df -- CHANGELOG.md` | fix 브랜치 0커밋, happy-easley 5커밋 |
| E-3 | descriptor 스키마 ID가 메타데이터에 없을 때 | 참조 기능 `reference-schema-metadata.ts`에서 `ReferenceResourcePayload` 행 삭제 → `check:registries` | FAIL: `FE-REG-API.GET_REFERENCE_RESOURCE.responseSchema references unknown FE-REG-SCHEMA.schemaId=ReferenceResourcePayload` 외 2줄 |
| E-4 | memento-web 모양 | memento `d3810a0`의 `memento-http-contract-contribution.ts`·`memento-feature-contract.ts` 정적 집계 | descriptor 29개, 요청·응답 스키마 ID 42개(+`MementoProblem`), 스키마 메타데이터 7행(라우트용만), V2 `apiOperations` 0행 |
| E-5 | 다음 동기화 재현 | scratchpad clone에서 `git merge-tree --write-tree --name-only`(`a14/sync-sim.sh`, `a14/sync-sim-techlog.sh`). memento: `HEAD` vs `e40684b`, merge base `af3d8e6`. tech-log: `--merge-base=af3d8e6` | memento 25경로(내용 24, modify/delete 1 `primitives/core.tsx`). tech-log 76경로(내용 40, modify/delete 36, rename/delete 1. `src/features/` 13경로, 그중 `installed-feature-runtimes.tsx`는 템플릿이 지움). 제품 repo는 clone만 했다 |
| E-6 | 참조 기능 삭제 뒤 문서 게이트 | `src/features/reference-feature`, `src/contexts/reference-context`, `tests/features/reference-feature` 삭제 → `verify:documentation` | FAIL `(failed: document references)`, 문서 8개·없는 경로 18개 |
| E-7 | 입구 문서 검사 | `layers.md`에서 규칙 행 1개 삭제 / `src/platform` 행 이름 변경 → `verify:documentation` | 둘 다 FAIL. 원인 문서·규칙·폴더를 적는다 |
| E-8 | 이력 삭제 | README "Files you can delete after copying" 목록 삭제 → `verify:documentation`, `check:adapter-inventory`, `deletable-history-documents`·`changelog-review-ids` 테스트, 끊긴 링크 집계(`a14/broken-links.py`) | 모두 PASS. 끊긴 상대 링크 19 → 3(지운 폴더를 가리키는 `docs/README.md` 3절 링크뿐. 삭제 전 19개는 지울 이력 폴더 안의 링크). 코드·설정의 이력 참조 0 |
| E-9 | 매뉴얼 1단계와 조립 실패 진단 | `create:feature notice-feature` → `check:registries`, `verify:documentation`. 이어서 `authProfileId`를 `NOTICE_NOPE`로 바꿔 `check:registries`와 기능 vitest | 생성 직후 `11 registries PASS; compatibility=additive`, `PASS_SCOPED`. 변이 뒤 `check:registries`는 원인 없이 연쇄 실패, vitest는 `reason`을 보인다(14-06) |
| E-10 | 제품 설정 키의 FE-REG-ENV 행 | `PRODUCT_RUNTIME_CONFIG_FIELDS`에 `NOTICE_SOURCE` 추가, 행 없음 → `env-registry-coverage` 테스트, `check:registries` | 테스트 FAIL `expected [ 'NOTICE_SOURCE' ] to deeply equal []`, `check:registries` PASS(14-05) |
| E-11 | 매뉴얼 오류 문구 대조 | 매뉴얼·정본 표의 오류 문구 27개 고정 부분을 `src`·`scripts`·`eslint.config.ts`에서 `git grep -F`(`a14/msg-check.sh`) | 없는 것 2개: `REST security profiles are incoherent for`, `cannot use the ANONYMOUS profile`. 나머지는 리터럴이나 템플릿 문자열로 있다 |
| E-12 | 샘플 제거 드릴 | `flock /tmp/claude-1000/review-2026-11-03-heavy.lock /usr/bin/time -v corepack pnpm test:sample-removal` | PASS(23개 검사). 상세 6.1절 |
### 6.1 샘플 제거 드릴 (E-12)
| 항목 | 값 |
|---|---|
| 명령 | `flock /tmp/claude-1000/review-2026-11-03-heavy.lock /usr/bin/time -v corepack pnpm test:sample-removal` (이 worktree, `e40684b`) |
| 결과 | exit 0. `reference-feature removal: PASS (23 checks, no fixture IDs)`. 샘플을 지운 fixture에서 unit·integration 2,914건 통과, risk coverage 399/399 모듈 PASS, CI 계약 27게이트 PASS. 샘플 제거 뒤 `create:feature` 생성 단계 포함 |
| 시간·자원 | wall 8:35.6, user 1,697.7 s, sys 281.3 s(CPU 383%), 최대 RSS 1,280,816 KB. 다른 리뷰어와 겹친 시간이라 끝난 직후 load average 10.7 / 25.3 / 34.9(1·5·15분)였다. 지난 라운드 수치(2:12)와 직접 비교하지 않는다 |
| 정리 | 끝난 뒤 `.tmp/` 비어 있음, worktree 변경 0줄 |
| 드릴이 보지 않는 것 | `verify:documentation`, `lint`, `check:i18n`, `check:design-system`, e2e, visual(`scripts/test-sample-removal.ts:401-414`). fixture는 `docs/`·`README.md`를 복사하지 않는다(`scripts/lib/removal-fixture.ts:25-39`). 그래서 이 PASS와 실험 E-6의 FAIL이 같은 커밋에서 함께 성립한다(14-04) |
## 7. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` | 새 clone이나 컨테이너에서 README 명령만 실행 |
| 나머지 제거 드릴 3개 | 시간 | `flock` 아래에서 `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal` |
| 두 제품의 실제 병합 뒤 게이트 | 충돌 25/76을 먼저 풀어야 한다 | 제품 sync 브랜치에서 병합하고 CHANGELOG만 보고 `check:types`·`check:registries`·`verify:documentation`까지 진행하는 실험 |
| memento 검증기를 zod 없이 `runtime: "zod"`로 적었을 때의 동작 | 실행하지 않았다(14-02 추론) | memento clone에서 스키마 행 하나를 그렇게 적고 `check:registries` |
| 목표 설계 문서 본문 전체의 낡은 주장 | 약 3만 줄 | `git grep -i -E 'v2|replay|mapper registry'`로 후보를 모아 코드와 대조 |
| 진단 값(`route_id`, realtime `reason`)을 쓰는 다운스트림 대시보드 | repo 밖 | 두 제품 운영 설정 확인 |
| 백엔드 `docs/web/http-contract.md`의 미커밋 수정 | 백엔드 working tree, 이 영역 밖 | 백엔드 리뷰에서 확인. 6.1 표 기준 커밋이 바뀌면 14-03 ③과 함께 |
@@ -0,0 +1,315 @@
# 영역 15 — 성능 실측·최적화
> 검토일: 2026-11-03(측정은 11-04 새벽까지) · 기준: 브랜치 `review/2026-11-03-merged` / `e40684b`. 두 작업 브랜치를 합친 커밋이다. 첫 부모 `93c81df`는 `claude/happy-easley-233d07`(V2 HTTP 경로 삭제), 둘째 부모 `8c39e77`은 `fix/ui-design-audit-2026-11-01`(오케스트레이터의 1101/14.4 후속, `3f9c087` 포함)이다. 공통 조상은 `ec7435c`. 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: 빌드 산출물(`dist/`, `artifacts/performance/{bundle,lab}.json`), `vite.config.ts`, `config/performance/budgets.json`, `config/scale/feature-shape-{ceilings,growth}.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,classify-vite-bundle}.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/test-performance.ts`, `tests/unit/feature-shape-growth.test.ts`, `docs/operations/performance-evidence.md`, `docs/architecture/static-delivery.md`, 빠른 테스트 계층(unit·component·integration)의 실행 시간
> 깊게 본 관점: 14, 13, 10, 20
> 렌즈: V2 삭제 뒤 초기 JS 재고(오케스트레이터 쪽 변경이 합쳐진 값). 기능을 몇 개 더 넣을 수 있는가(참조 모양 복사, `create:feature`). 초기 청크 수와 HTTP/1.1 비용(`3f9c087`의 근거) 재확인. 테스트 실행 시간 분포.
> 영역 판정(35.8): **조건부 사용 가능.** 기능을 더하고 merge하는 데까지는 예산과 검사가 동작한다. 초기 JS는 201,848 / 204,800 B이고, 참조 모양 기능 3개 또는 `create:feature` 기능 8개까지 들어간다. 기능을 9개 더해도 초기 파일 수는 25개 그대로다. 그러나 **release 단계 lab 게이트(FE-GATE-026)는 이 커밋에서 실패한다**(15-01). 템플릿 CI의 `RELEASE_READY`를 출시 근거로 쓰는 용도는 15-01을 고치기 전까지 사용 보류다.
## 0. 결론
- **초기 JS는 201,848 / 204,800 gzip B(98.6%), 여유 2,952 B, 파일 25개(entry 포함)다.** 오케스트레이터 게이트 기록(`review-gates/summary.txt`)의 201,848 B와 같다.
- 공통 조상 `ec7435c`는 202,774 B·26개였다. V2 삭제 쪽(첫 부모)이 −1,716 B, 오케스트레이터 쪽(둘째 부모)이 +816 B다. 합친 결과는 조상보다 924 B 작다. 같은 빌드 ID로 네 커밋을 다시 빌드해 쟀다(6절).
- 보고된 "약 200,900 B"(1101 README 14.7의 200,911 B)는 첫 부모 끝(`93c81df`, 201,058 B)보다 147 B 작다. 그 뒤 커밋 `365d8c3`·`c05f41a`가 더한 것으로 보인다(추론, 커밋별로 재지 않음).
- 파일이 26개에서 25개로 준 것은 V2 삭제 쪽이다.
- **기능 여유.** 참조 기능 모양 복사본은 3개까지 들어간다(204,306 B, 남는 494 B). 5개면 205,722 B로 넘는다. `create:feature`로 만든 최소 기능은 8개까지 들어간다. 9개째에 204,822 B로 22 B 넘는다.
- 첫 복사본은 +984 B다(새 context 포함). 둘째부터는 +716~758 B다. 생성 기능은 +278~597 B다.
- 기능을 늘려도 초기 파일 수는 25개 그대로다. 15-01의 `feature-declarations` 그룹이 동작한다.
- **lab 게이트가 실패한다(15-01, High).** 이름 붙은 상호작용(플랫폼 구성 화면 진입)이 227~271ms다. 예산은 200ms다. 지난 라운드 커밋 `d99301b`를 같은 호스트에서 번갈아 재면 117~118ms로 통과한다. 원인은 1101/15-01 수정(`298201f`)이다. 그 커밋부터 이 화면은 설치된 모든 기능의 실행부를 받은 뒤 그린다. 이 게이트는 release 단계에서만 돌아 147 커밋 동안 드러나지 않았다.
- **HTTP/1.1 비용을 다시 쟀다.** 같은 서버 코드를 HTTP/1.1과 HTTP/2로 띄워 번갈아 5회씩 쟀다. 첫 화면은 Fast 3G에서 6,022 vs 5,009ms(+1.0초), Fast 4G에서 1,900 vs 1,502ms(+0.4초)다. `3f9c087`의 "HTTP/1.1이면 약 1초 늦다"와 맞다. 다만 이 전제를 확인하는 장치가 없고, 초기 파일 수에도 상한이 없다(15-05).
- **성능 기준선 숫자가 다시 어긋났다(15-02).** `performance-evidence.md`는 202,509 B·16개 파일·기능당 +650~750 B를 적는다. 같은 문서의 다른 절은 26개라고 적는다. `feature-shape-ceilings.json`은 한 문장 안에서 203,816 B와 202,509 B를 함께 쓴다. 지난 라운드 1101/15-02를 손으로 고친 뒤 다시 낡았다.
- **예산을 넘으면 `check:bundle`이 무엇이 얼마나 넘었는지 출력하지 않는다(15-03).** 출력은 `Bundle budget or manifest integrity failed: ` 한 줄이고 콜론 뒤가 비어 있다. 기능 9개 실험에서 재현했다.
- **기능당 1 KiB 상한의 여유가 40 B다(15-04).** 지금 +984 B다. `ca16187`에서는 +1,025 B로 상한을 넘는 값이었다. 첫 복사본 값에는 새 context 비용이 섞여 있다.
- **release마다 초기 JS의 49.4%(99,784 B)가 캐시에서 버려진다(15-06).** build id만 바꾼 두 빌드에서 `boot`·`index`·`render-boot-failure`(react-dom 포함)의 이름이 바뀐다. 지난 라운드 O1(react-dom 분리)은 결정 기록 없이 그대로다.
- **react-router 개발 빌드가 운영 번들에 들어간다(15-07).** 운영 빌드로 바꾸면 초기 JS가 604 B 준다(실험).
- **테스트 시간.** unit 176파일 2,580건 22.7초, component 39파일 11.6초, integration 10파일 14.7초다(부하 18~24). unit 테스트 시간 합의 61%가 자식 프로세스를 띄우는 21개 파일이다(지난 라운드 16개·54%). integration 시간 합의 58%(12.5초)는 테스트 안에서 release candidate를 빌드하는 파일 하나다. 지난 1101/15-04는 남았고 커졌다. `npx vitest` 실패(1101/15-05)는 고쳐졌다(423/423 통과).
심각도별 이번 발견: High 1(15-01), Medium 0, Low 6(15-02~15-07).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 | `clean-architecture-frontend-template` 영역 15(성능 실측·최적화) |
| 커밋·작업 상태·확인 시점 | `e40684b`(detached), 미커밋 변경 없음, 2026-11-03 22:57 ~ 11-04 새벽. 실험은 리뷰어 worktree(`agent-a23a40a312e269973`) 안에서만 했다. `create:feature` 실험, `vite.config.ts` alias 실험, 다른 커밋 checkout은 끝난 뒤 `git checkout -- . && git clean -fd`와 `git checkout --detach e40684b`로 되돌렸다 |
| 실행 환경 | Ubuntu, Intel Core Ultra 7 155H(논리 CPU 22), Node v24.14.0, pnpm 11.17.0, Vite 8.1.5(rolldown), Vitest 4.1.10, Playwright 1.62.0 / Chromium 151.0.7922.34. 무거운 실행은 공용 `heavy.lock` 안에서 했다. 락 밖의 다른 리뷰어 작업과 다른 프로젝트(gradle) 때문에 loadavg(1분)는 측정 내내 7.5~40이었다. 각 측정의 부하는 6절에 적었다 |
| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 |
| 성능 목표 | `config/performance/budgets.json:3-11`: 초기 JS 204,800 gzip B, lazy 청크 파일당 122,880 B, lab LCP 2,500ms·CLS 0.1·상호작용 200ms. 기능당 초기 JS +1 KiB 이하(`tests/unit/feature-shape-growth.test.ts:139-144`). field p75는 표본 기준이 미정이라 설계대로 `FAIL_UNVERIFIED` |
| 읽은 코드·구성 | 머리말 경로, `src/bootstrap/main.tsx`, `src/features/installed-feature-runtime-registries.ts`, `src/presentation/examples/platform-overview-page.tsx:594-606`, `config/ci/gates.json`(FE-GATE-005·011·012·026, stages), `tests/setup.ts`, `vitest.config.ts`, `tests/unit/service-worker-runtime.test.ts:1907-1923`, `scripts/create-feature.ts` 머리 주석, `docs/manual/01-add-a-feature.md` 1단계, 빌드된 `dist/index.html`과 entry 청크 |
| 수행한 테스트·실험 | 6절 표. 요약: `build`+`check:bundle`, 빌드 ID 두 개의 자산 비교, 기능 모양 복사 0·1·2·3·5·10개, `create:feature` 1·2·3·4·9개, 커밋 4개 바이트 귀속, 기능당 비용 bisect 5개 커밋, HTTP/1.1 vs HTTP/2 첫 화면, `test:performance` 11회(커밋 6개), lab 화면 진입 요청 추적, react-router 운영 빌드 alias, `check:optional-recipes`, 빠른 테스트 계층 시간(JSON reporter), `npx vitest` 재확인 |
| 확인하지 못한 범위·이유 | (1) Firefox·WebKit lab 수치: Chromium만 돌렸다. (2) 실제 CDN·HTTP/2 호스트: loopback + CDP 에뮬레이션만이다. (3) field 수치: 입력이 없다. (4) loadavg 5 미만에서의 lab: 측정 내내 부하가 8 이상이었다. 15-01의 실패가 부하 때문이 아니라는 근거는 같은 부하에서 번갈아 잰 `d99301b`의 통과다. (5) CI 러너 시간·코어 수: Gitea 실행 기록을 보지 않았다. (6) 기능 N개일 때 플랫폼 구성 화면의 상호작용 시간: 재지 않았다(15-01 남은 가정). (7) 생성 기능의 타입 검사·테스트: 빌드와 번들만 쟀다. (8) `test:coverage`·e2e 시간: 재지 않았다(e2e는 영역 11) |
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 `docs/reviews/2026-11-01-maturity-review/15-performance.md`(기준 `d99301b`)와 그 README 13~14절. 지난 수치는 비교에만 쓰고 증거로 쓰지 않았다. 바이트는 결정적이라 비교할 수 있다. 시간은 부하가 달라 직접 비교하지 않았다. lab만 `d99301b`를 같은 세션에서 다시 재서 비교했다 |
## 2. 지난 발견 재판정
| 지난 ID | 지난 내용 | 판정 | 이번 근거 |
|---|---|---|---|
| 1101/15-01 | 초기 JS 여유 1,293 B. 넘었는지 보는 검사는 release 단계에서만 | **고쳐짐**(검사 위치·기능당 비용) / **남음**(여유가 작다) | FE-GATE-012가 merge stage에 있다(`config/ci/gates.json:2232-2247`). 기능당 첫 복사본 +3,906 → +984 B. 여유는 2,952 B로 참조 모양 3개분이다(5.1). 다만 같은 수정이 lab 게이트를 깼다(이번 15-01) |
| 1101/15-02 | `performance-evidence.md` 기준선이 현재 빌드와 다름 | **고쳐졌다가 재발** → 15-02 | `8c7bcda`에서 손으로 고쳤다. 그 뒤 08-08(파일 16 → 25)·V2 삭제(−1,716 B)로 숫자가 다시 어긋났다. 문서를 읽는 검사는 여전히 없다 |
| 1101/15-03 | 예산이 CSS를 빼고, lazy는 파일 단위 | **남음** | `scripts/check-bundle.ts:34-41`이 JS만 센다. CSS는 8,766 B gzip(지난 8,592). lab 화면 진입은 이제 파일 7개·두 차례 요청(10,914 B)인데 라우트 합을 보는 검사가 없다 |
| 1101/15-04 | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | **남음(커짐)** | unit에서 자식 프로세스를 띄우는 파일 21개가 테스트 시간 합의 61%(80.8 / 133.4초). 지난 16개·54%(세는 방법이 조금 다르다). `tests/setup.ts:1-2`는 여전히 모든 파일에 RTL·jest-dom을 싣는다. `service-worker-runtime.test.ts:1907-1923`은 여전히 실제 5,008ms를 기다린다. FE-GATE-005는 여전히 `test-unit`과 `test-coverage`를 둘 다 돈다 |
| 1101/15-05 | `npx vitest`로 돌리면 unit 79건 실패 | **고쳐짐** | `vitest.config.ts:10-16`이 npm scope 변수를 지운다. `npx vitest run tests/unit/ci-workflow-generation.test.ts` 423/423 통과 |
| 1101 O1 · 0929/13-03 | build id가 react-dom 청크를 release마다 바꾼다(96,186 B) | **남음** → 15-06 | 99,784 B(초기 JS의 49.4%). 결정 기록이 없다 |
| 0925 FOLLOW-UP P2 · 1101 2.5 | 레시피 예산 여유 77·14·9 B | **고쳐짐(규칙)** | 1101 14.1의 "측정값 + 3%" 규칙. 여유 file-transfer 1,747, offline-indexeddb 1,077, realtime 1,343, service-worker-pwa 384 B(`check:optional-recipes` PASS) |
| 0929/11-04 | lab 판정이 호스트 부하로 뒤집힌다 | **코드 남음** / 15-01의 원인은 아님 | 부하 가드는 여전히 없다(`scripts/test-performance.ts:175`는 기록만 한다). 이번 실패는 부하 10~20에서 매번 났다. 같은 부하에서 `d99301b`는 매번 통과했다 |
| 0929/11-05 | 기능 규모 기준선에 소스 커밋 없음 | **고쳐짐(필드)** / 값은 낡음 → 15-02 | `config/scale/feature-shape-growth.json:16`에 `373b27b`가 있다. 그 값(203,816 B)은 지금(201,848 B)과 다르다 |
| 1101 README 14.4 "초기 청크 25개. HTTP/1.1 호스팅이면 다시 본다" | 미측정 위험 | **바뀜** → 15-05 | `3f9c087`이 재고 HTTP/2 전제로 결정했다. 이번 재측정도 HTTP/1.1이 Fast 3G +1.0초, Fast 4G +0.4초다. 전제를 확인하는 장치는 없다 |
| 1101 T1·T2·T4 (테스트 최적화 후보) | setup 경량화, SW fake timer, unit 중복 실행 제거 | **남음** | 위 1101/15-04 행과 같다 |
## 3. 이번 발견 (36.3)
### 15-01 lab 게이트(FE-GATE-026)가 1101/15-01 수정 뒤로 계속 실패한다 — 측정하는 화면이 모든 기능의 실행부를 받은 뒤 그린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 14, 21, 18, 13, 5, 10 |
| 근거 | `node scripts/test-performance.ts --runs=5`(FE-GATE-026의 명령)를 `d99301b`와 `e40684b`에서 번갈아 돌렸다. `d99301b`: 상호작용 중앙값 118·117ms, PASS(부하 13.9·11.6). `e40684b`: 232·227ms, FAIL(부하 12.5·10.1). 다른 묶음에서도 `ec7435c` 249·263ms, `e40684b` 271·256ms·230ms로 모두 FAIL이다(부하 13~29). 예산은 200ms다(`config/performance/budgets.json:10`). LCP는 2,012~2,140ms로 예산 안이다. bisect: `298201f`(1101/15-01 첫 커밋)에서 이미 226ms다. 측정 대상은 `ROUTE_REGISTRY.EXAMPLES_PLATFORM`이다(`scripts/test-performance.ts:46`). 이 화면의 route module은 그리기 전에 `loadInstalledFeatureRuntimeRegistries()`를 기다린다(`src/presentation/examples/platform-overview-page.tsx:596-606`). 그 함수는 설치된 모든 기능의 실행부를 dynamic import한다(`src/features/installed-feature-runtime-registries.ts:17-31`, 주석 "The platform overview route calls it before it renders"). 요청 추적(같은 throttle): `d99301b`는 클릭 뒤 파일 2개(5,019 B)를 한 번에 받는다. `e40684b`는 파일 5개(7,942 B)를 받고, 약 100ms 뒤 `feature-runtime`(2,196 B)·`reference-schemas`(776 B)를 다시 받는다. 한 번 더 왕복하고, 그 뒤 레지스트리를 조립하고 그린다. FE-GATE-026은 release stage에만 있다(`config/ci/gates.json:2253-2261`). 1101 README 13.8·14.5의 마지막 게이트 목록과 오케스트레이터 이번 게이트 기록에 `test:performance`가 없다 |
| 발생 조건 | 템플릿을 고치지 않고 release 단계 게이트를 돌릴 때(tag `v*` push 또는 release 이상의 수동 실행). 기능을 더한 다운스트림에서는 이 화면이 받는 실행부가 기능 수만큼 늘어난다(N개일 때 시간은 미측정) |
| 영향 | `RELEASE_READY`를 얻을 수 없다. production stage는 release를 `needs`로 둔다(`config/ci/gates.json` stages). 템플릿을 받은 프로젝트는 첫 release에서 이 실패를 만난다. 원인이 템플릿 예제 화면이라는 것을 알기 어렵다. 그러면 예산을 근거 없이 올리기 쉽다. 사용자 화면 영향은 예제 화면 진입이 약 110ms 늦어지는 정도다 |
| 심각도·우선순위 | High · P1 — 지원하는 배포 경로(release 단계)가 템플릿 그대로에서 실패한다. 두 라운드 사이 147 커밋 동안 아무 게이트도 이것을 알리지 않았다. 고치는 비용은 작다 |
| 통제·증거 | 목표 M3(merge 전에 검출) / 확인 M3(release 단계에서만), merge 단계 M0 · E3(같은 세션 A/B 4회, 커밋 6개 bisect, 요청 추적) + E1(라우트 모듈·게이트 설정) |
| 확실성과 남은 가정 | 판정 뒤집힘(0929/11-04)은 아니다. 같은 부하에서 번갈아 잰 `d99301b`가 매번 통과했고 `e40684b`는 매번 실패했다. 늘어난 시간의 일부는 CDP가 에뮬레이션하는 왕복·대역폭이라 CPU 부하와 무관하다. 부하 5 미만에서는 재지 않았다. 실제 CI 러너에서는 돌리지 않았다. 늘어난 110ms를 왕복·다운로드·조립·렌더로 나누지는 않았다 |
| 결정의 근거 | 5.3절. 기록된 의도: `298201f` 본문의 "위험·한계"가 이 위험을 적었다. "플랫폼 구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가 재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다." 같은 본문의 "미실행"에 FE-GATE-026이 있다. 확인한 사실: LCP는 예산 안이고, 넘은 것은 상호작용이다. 적어 둔 미측정 위험이 이후 어느 단계에서도 다시 재지 않은 채 남았다 |
| 이해 비용 | release 담당자가 lab 실패를 보면 부하(11-04)를 먼저 의심한다. 원인이 예제 화면의 route module이라는 것은 요청 추적을 해야 보인다 |
| 최소 개선 방향 | 플랫폼 구성 화면이 제목과 선언에서 얻는 정보는 바로 그리고, 실행부 레지스트리(스키마·API 행·계약 기여) 부분만 Suspense 경계 뒤에서 채운다. route module이 레지스트리를 기다리지 않게 한다. 그다음 같은 A/B로 다시 잰다 |
| 대안 비교 | (a) 상호작용 예산을 300ms로 올림: 즉시 녹색. 회귀를 숨기고 예산이 다시 "직전 측정값"이 된다. (b) lab 대상 라우트를 다른 예제로 바꿈: 같은 이유로 회귀를 숨긴다. (c) 먼저 그리고 나중에 채움(권장): 측정 방법·예산 그대로, diff가 화면 한 파일이다. (d) 내비게이션 hover 때 실행부 프리페치: 코드가 늘고 hover 없는 진입(키보드·직접 클릭)에는 효과가 작다. (e) FE-GATE-026을 merge에도 둠: 다음 회귀를 PR에서 잡는다. 브라우저 설치와 16초 이상이 필요하고 11-04 흔들림이 merge로 온다. (c)와 별개로, release 전 수동 확인 목록에 `test:performance`를 넣는 것은 비용이 거의 없다 |
| 단순화의 보존 조건 | 화면이 실행부 중복(스키마·operation·계약 패키지)을 브라우저에서 계속 드러낸다(1101/15-01이 부팅에서 옮긴 검사). `CONTRACT_PACKAGE` 선언과 실제 기여의 일치 검사(`installed-feature-runtime-registries.ts:47-63`). lab 측정 방법(페이지 시계, 클릭 → 대상 heading) |
| 비용·부작용 | 화면 안에 로딩 상태 하나가 생긴다. component 테스트가 레지스트리 표를 기다리도록 바뀔 수 있다 |
| 재검토 조건 | 측정 대상을 바꾸거나 field INP 데이터가 생기면 lab 상호작용 예산의 근거를 다시 본다 |
| 완료 기준 | 같은 호스트에서 `d99301b`가 통과하는 조건으로 번갈아 2회 이상 잰 `test:performance`가 PASS다. 플랫폼 구성 화면의 제목이 실행부 요청을 기다리지 않는다(요청 추적에서 제목 표시가 두 번째 요청 묶음보다 먼저다) |
| 검증 방법 | 6절 "lab A/B" 방법. `scratchpad/r15/lab-ab2.sh`와 `nav-trace.mjs`가 그 절차다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 15-02 성능 기준선 숫자가 다시 현재 빌드와 다르고, 같은 파일 안에서도 서로 다르다 (1101/15-02 재발)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 14, 20, 24, 5, 21 |
| 근거 | `docs/operations/performance-evidence.md`: "98.9%"(`:17`), "202,509~202,522 gzip bytes, 16개 파일"(`:23`), "약 2,280 bytes"(`:24`), "약 +650~750 bytes"(`:25`), lazy "17개, 합계 28,204 bytes"(`:26`), "`design-system` 청크(48.2 KB)에는 react-router가 들어 있다"(`:29-30`), 같은 문서 HTTP/1.1 절 "지금 26개 202,782"(`:110`). `docs/architecture/static-delivery.md:43` "about 26". `config/scale/feature-shape-ceilings.json:24` "Baseline: 203,816 B ... about 610-630 B", `:26` "leaves 2,291 B over the baseline's 202,509 B ... about 610 B each". `config/scale/feature-shape-growth.json:41` 203,816 B(`373b27b`). 이번 측정: 201,848 B, 98.6%, 25개, 여유 2,952 B, 첫 복사본 +984 B·둘째부터 +716~758 B, lazy 22개 35,367 B. `design-system` 청크는 없다. react-router는 `chunk-KS7C4IRE` 청크(30,767 B)다. `tests`·`scripts`에서 `performance-evidence`를 읽는 파일은 0개다 |
| 발생 조건 | 다운스트림이 "첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다"(`performance-evidence.md:17-18`)를 따를 때 |
| 영향 | 기능당 비용을 실제보다 약 30~40% 작게 본다. 파일 수는 같은 문서에서 16과 26으로 다르다. 청크 이름으로 줄일 곳을 찾으면 없는 청크를 찾는다. "세 개 더 들어간다"는 결론은 우연히 맞지만 근거 숫자가 틀렸다 |
| 심각도·우선순위 | Low · P2 — 문서 불일치다. 다만 예산을 정할 때 쓰는 유일한 자료이고 두 번째로 어긋났다 |
| 통제·증거 | 목표 M3(어긋나면 검사가 알림) / 확인 M1(손으로 적은 기록) · E3(빌드 측정과 대조) |
| 확실성과 남은 가정 | 숫자는 결정적이라 1회 측정했다. 어긋난 커밋은 08-08(`51941a5`, 파일 16 → 25), 09-03(`ca16187`), V2 삭제(`048f490`·`12f3bb7`)로 보인다(바이트 bisect 결과, 6절) |
| 결정의 근거 | 1101/15-02의 최소 개선 방향(생성물로 바꾸거나 검사가 비교)이 반영되지 않고 손 수정만 됐다(확인한 사실: `8c7bcda` diff는 문서 한 파일) |
| 이해 비용 | 문서를 믿은 사람이 직접 빌드해 다시 재야 한다 |
| 최소 개선 방향 | 숫자를 한 곳(`config/scale/feature-shape-ceilings.json`에 기계가 읽는 칸 하나, 예: `baselineInitialJsGzipBytes`)에 두고 문서는 그 파일을 가리킨다. `tests/unit/feature-shape-growth.test.ts`가 이미 0개·1개 복사 빌드를 재므로(`:140-141`), 그 값과 기록값이 ±1% 안인지 같은 테스트에서 본다. 청크 이름 문장은 지운다 |
| 대안 비교 | (a) 다시 손으로 고침: 다음 구조 변경에서 또 낡는다. (b) 문서에서 숫자를 지우고 `bundle.json`만 가리킴: 낡지 않지만 "예산을 정할 숫자"를 보려면 빌드해야 한다. (c) 기록값 + 기존 테스트의 대조(권장): 빌드를 더하지 않고 어긋나면 merge에서 실패한다 |
| 단순화의 보존 조건 | 측정 조건 설명(분류 규칙, gzip 수준, CSS 제외)은 남긴다. `feature-shape-growth.json`의 측정 기록(환경·부하·커밋)은 그대로 둔다 |
| 비용·부작용 | 구조를 바꿀 때마다 기록값을 같이 고쳐야 한다. 그게 목적이다 |
| 재검토 조건 | 예산 근거가 field 데이터로 바뀌면 기록 위치를 다시 정한다 |
| 완료 기준 | 기록값과 현재 빌드가 1%보다 다르면 `test:unit`이 실패한다. 문서·JSON에 서로 다른 기준선이 없다 |
| 검증 방법 | 기록값을 2% 바꾸는 변이로 테스트가 실패하는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1101/15-02 재발) |
### 15-03 예산을 넘으면 `check:bundle`이 무엇이 얼마나 넘었는지 출력하지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 8, 20, 21 |
| 근거 | `scripts/check-bundle.ts:98-104`는 실패할 때 `missingImports`와 `missingOutputs`만 이어 붙인다. 예산 초과만 있으면 둘 다 비어 있다. 재현: `create:feature` 기능 9개를 더한 빌드(204,822 B)에서 stderr는 `Bundle budget or manifest integrity failed: ` 한 줄이고 종료 코드 1이다. 측정값과 한도는 `artifacts/performance/bundle.json`의 `results`에만 있다 |
| 발생 조건 | 초기 JS나 lazy 청크 하나가 예산을 넘을 때. 참조 모양 기능 4개째, 생성 기능 9개째에 생긴다 |
| 영향 | 모든 다운스트림이 처음 만나는 예산 실패에서 "manifest integrity"인지 "예산"인지, 몇 바이트 넘었는지 알 수 없다. CI에서는 artifact를 내려받아야 한다 |
| 심각도·우선순위 | Low · P2 — 기능 피해는 없다. 템플릿 사용자가 거의 확실히 만나는 첫 게이트 실패다 |
| 통제·증거 | 목표 M2(실패가 원인과 수치를 말함) / 확인 M1 · E3(재현) |
| 확실성과 남은 가정 | lazy 초과도 같은 코드 경로라 같은 빈 메시지일 것이다(실행 안 함) |
| 결정의 근거 | 적용 제외 — 출력 누락이다 |
| 이해 비용 | 개발자가 `bundle.json` 구조를 알아야 한다 |
| 최소 개선 방향 | 실패 메시지에 초기 JS 측정값·한도·초과 바이트, 넘은 lazy 청크 목록을 넣고, 예산 실패와 manifest 무결성 실패를 다른 문장으로 쓴다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | `bundle.json` 스키마와 fixture 자가 검사(`:48-76`)는 그대로 둔다 |
| 비용·부작용 | 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 예산 + 1 B 빌드에서 stderr에 측정값·한도·초과량이 보인다 |
| 검증 방법 | `scripts/check-bundle.ts`를 부르는 단위 테스트 또는 fixture 빌드 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 15-04 기능당 1 KiB 상한의 여유가 40 B이고, 잰 값에 새 context 비용이 섞여 있다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 13, 21, 24 |
| 근거 | 테스트가 쓰는 함수(`measureInitialJavascriptGzipBytes`)로 0개·1개 복사를 쟀다. `e40684b` +984 B(여유 40 B). bisect: `298201f` +740, `e4ace51` +805, `51941a5`(08-08) +949, `ca16187`(09-03) **+1,025**, `ec7435c` +979, 첫 부모 +977, 둘째 부모 +990. `ca16187`의 값은 상한(1,024)을 넘는다. 둘째 복사본은 +636 → +788 B로 덜 늘었다. 복사본 1개 측정은 새 context(`shape-context-0`)도 만든다(`scripts/scale/measure-feature-shape-growth.ts:116-128`). 테스트 주석은 여전히 "741 B when 15-01 landed"다(`tests/unit/feature-shape-growth.test.ts:134-135`) |
| 발생 조건 | 참조 기능에 문구·라우트를 조금 더하거나, context 선언·레이아웃 비용이 늘 때 |
| 영향 | 다음 작은 변경이 `test:unit`을 깨고, 메시지는 "기능당 비용 상한 초과"다. 플랫폼의 기능당 고정 비용이 늘었는지, 참조 샘플이 커졌는지, context가 비싸졌는지 구분되지 않는다. 쉬운 대응은 상한을 올리는 것이다 |
| 심각도·우선순위 | Low · P3 — 검사가 동작하는 방향의 위험이다. 다만 원인을 좁혀 주지 못한다 |
| 통제·증거 | 목표 M3(무엇이 늘었는지 구분해 검출) / 확인 M3(합계만 검출) · E3(bisect) |
| 확실성과 남은 가정 | `ca16187`에서 이 테스트가 실제로 실패했는지는 실행 기록을 보지 않았다. 늘어난 바이트를 모듈별로 나누지 않았다. 08-08이 기능 선언에 primitive를 더 묶은 것으로 보인다(추론) |
| 결정의 근거 | 리뷰어 추론. 1 KiB는 15-01 당시 741 B에 여유를 둔 값으로 보인다. 그 사이 늘어난 243 B는 어디에도 기록되지 않았다 |
| 이해 비용 | 실패를 본 사람이 bisect를 직접 해야 한다 |
| 최소 개선 방향 | 테스트가 1개와 2개 복사를 재서 "기능 하나(같은 context)"를 따로 보고, 첫 복사의 차이를 "context 하나"로 따로 기록한다. 측정값을 실패 메시지와 기준선 파일에 남겨 증가가 이력에 보이게 한다 |
| 대안 비교 | (a) 현상 유지: 다음 증가에서 실패하고 원인을 다시 찾는다. (b) 상한을 1.5 KiB로 올림: 당장 여유가 생기지만 같은 구분 문제가 남는다. (c) 두 값으로 나눔(권장): 빌드가 한 번 늘어난다(약 3초) |
| 단순화의 보존 조건 | "기능 하나 더할 때 초기 JS 증가 상한"이라는 계약과 merge 단계 실행 |
| 비용·부작용 | unit 시간 약 +3초(이 테스트는 이미 7.5초, unit에서 다섯째로 느리다) |
| 재검토 조건 | 기능 선언에 문구 카탈로그를 계속 싣는 구조가 바뀌면(1101 O7 i18n 분할) 상한을 다시 정한다 |
| 완료 기준 | 기능 하나·context 하나의 비용이 따로 보이고, 둘 중 넘은 쪽이 실패 메시지에 나온다 |
| 검증 방법 | 참조 기능 문구 하나를 늘리는 변이와 context 선언을 늘리는 변이로 서로 다른 메시지가 나오는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 15-05 초기 JS 파일 수에 상한이 없고, HTTP/2 서빙 전제를 확인하는 장치가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 14, 18, 21, 5, 13 |
| 근거 | 초기 파일 25개. entry가 앱 그래프를 dynamic import하며 의존 24개를 한 번에 preload한다(`dist/assets/index-*.js`의 `__vite__mapDeps`, `src/bootstrap/main.tsx:14-17`). 첫 화면까지 JS 요청 26개. 같은 서버 코드(TLS, gzip)를 HTTP/1.1과 HTTP/2로 띄워 번갈아 5회: Fast 3G 6,022ms(5,998~6,037) vs 5,009ms(4,802~5,023), Fast 4G 1,900ms(1,882~1,925) vs 1,502ms(1,495~1,532). 전제는 `docs/architecture/static-delivery.md:43-51`과 `performance-evidence.md:157-159`에만 있다. `scripts`·`config`에서 HTTP 버전·ALPN을 보는 코드는 0곳이다. `budgets.json`에 파일 수 칸이 없다. lab 게이트는 `vite preview`(HTTP/1.1)와 지연 40ms로 잰다(`scripts/test-performance.ts:89-98`). 08-08처럼 파일을 16 → 25로 늘리는 변경도 모든 게이트를 통과했다 |
| 발생 조건 | 다운스트림이 HTTP/1.1만 되는 호스트(일부 정적 웹사이트 엔드포인트, `http2`를 켜지 않은 nginx 등)로 서빙할 때. 또는 템플릿 변경이 초기 파일 수를 더 늘릴 때 |
| 영향 | 느린 모바일 회선에서 첫 화면이 약 1초(20%) 늦다. 어느 게이트도 알리지 않는다 |
| 심각도·우선순위 | Low · P3 — `3f9c087`이 재고 결정했고 문서에 적혔다. 남은 것은 확인 수단이다 |
| 통제·증거 | 목표 M3(전제가 깨지면 검출) / 확인 M1(문서) · E3(재측정) |
| 확실성과 남은 가정 | loopback과 CDP 에뮬레이션이다. CDP 지연은 요청마다 붙고 TCP·TLS 연결 수립 비용은 따로 재지 않았다. 실제 CDN에서는 재지 않았다. 부하 15 → 7.5 구간에서 쟀다 |
| 결정의 근거 | 5.2절 |
| 이해 비용 | 호스팅을 고르는 사람이 `static-delivery.md` 끝 단락을 읽어야 안다 |
| 최소 개선 방향 | (1) `budgets.json`에 `initialJsFiles` 상한(지금 25)을 두고 `check:bundle`이 센다. 파일을 늘리는 변경이 결정으로 드러난다. (2) 운영 probe(FE-GATE-019)가 응답의 HTTP 버전을 기록하고 HTTP/1.1이면 경고한다 |
| 대안 비교 | 5.2절 |
| 단순화의 보존 조건 | 08-08의 primitive 분리와 부트 실패 화면 청크 분리(09-03) |
| 비용·부작용 | 숫자 하나와 probe 기록 한 칸 |
| 재검토 조건 | 5.2절 |
| 완료 기준 | 초기 파일이 상한 + 1이면 `check:bundle`이 실패한다. probe 결과에 프로토콜이 남는다 |
| 검증 방법 | 초기 청크를 하나 더 만드는 변이. HTTP/1.1 서버를 대상으로 probe 실행 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 15-06 build id 하나만 바뀌어도 초기 JS의 49.4%가 캐시에서 버려진다 (1101 O1·0929/13-03 그대로)
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 14, 18, 23 |
| 근거 | `VITE_BUILD_ID`만 다른 두 빌드(`gitea-101-1`, `gitea-102-1`)에서 `boot`(39,103 B), `index`(1,019 B), `render-boot-failure`(59,662 B)의 파일명이 바뀌었다. 합계 99,784 B, 초기 JS의 49.4%. lazy 파일은 0 B 바뀌었다. `render-boot-failure` 청크의 대부분은 react-dom이다. 해시 자산은 1년 `immutable`로 캐시된다(`config/hosting/cache-policy.json`). `vite.config.ts:178-203`의 그룹에 react-dom 분리는 없다 |
| 발생 조건 | release마다. CI는 실행마다 다른 build id를 쓴다 |
| 영향 | 재방문 사용자가 코드가 같아도 release마다 약 100 KB gzip을 다시 받는다. 자주 출시할수록 커진다 |
| 심각도·우선순위 | Low · P3 — 합의된 재방문 목표가 없다. 지난 두 라운드도 결함으로 세지 않았다 |
| 통제·증거 | 목표 없음(미정) / 확인 M0 · E3 |
| 확실성과 남은 가정 | 1101 O1의 변이(react-dom 분리 한 줄 → 40,929 B, 초기 −381 B)는 이번에 다시 하지 않았다. 이번 청크 구성에서 효과는 미확인이다 |
| 결정의 근거 | 지난 라운드 O1 "채택 권고(P3)" 뒤 결정 기록이 없다(1101 README 14.1 결정표에 없음) |
| 이해 비용 | 낮다 |
| 최소 개선 방향 | 결정만 기록한다(채택 또는 기각과 이유). 채택하면 `codeSplitting.groups`에 react-dom·scheduler 그룹을 더하고 부트 실패 화면이 계속 그 청크만으로 그려지는지 본다 |
| 대안 비교 | (a) 현상 유지. (b) react-dom 그룹(1101 실측 −55 KB 변동). (c) build id를 런타임 JSON(`release-manifest.json`)에서만 읽어 JS에 넣지 않음: 변동이 가장 작지만 부트 실패 화면이 build id를 보여 주는 계약을 바꿔야 한다 |
| 단순화의 보존 조건 | 부트 실패 화면이 앱 그래프 평가 실패에도 그려진다(09-03). build id는 config·manifest 대조에 계속 쓰인다 |
| 비용·부작용 | (b)는 초기 파일 +1(15-05와 맞물림) |
| 재검토 조건 | 재방문 성능 목표나 field 데이터가 생길 때 |
| 완료 기준 | 결정이 기록되고, 채택했다면 build id만 바뀐 두 빌드의 바뀐 바이트가 기록된다 |
| 검증 방법 | 이 문서 6절의 빌드 ID 비교 |
| 담당·기한·상태 | 미정 · 미정 · 이월 |
### 15-07 react-router 개발 빌드가 운영 번들에 들어간다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 16, 14 |
| 근거 | `src`는 `react-router-dom`(17곳)을 import한다. react-router 7.18.1의 `package.json` exports는 모든 조건에서 `./dist/development/*`를 가리킨다. 그 파일은 `ENABLE_DEV_WARNINGS = true`다(`dist/production/*`는 `false`). 지금 번들의 초기 청크 하나에 개발 경고 문구("You rendered descendant …")가 있다. 실험: `vite.config.ts`에 `react-router`·`react-router/dom`을 `dist/production`으로 보내는 alias 두 줄을 넣었다. 초기 JS 201,848 → 201,244 B(−604 B), react-router 청크 30,767 → 30,157 B, 경고 문구가 있는 파일 0개. `check:bundle` 통과. 테스트는 돌리지 않았다 |
| 발생 조건 | 모든 운영 빌드 |
| 영향 | 초기 JS 약 0.6 KB(기능 하나에 가까운 크기)와 운영 콘솔의 라우터 개발 경고 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 미정 / 확인 M0 · E3(번들 실험) |
| 확실성과 남은 가정 | 운영 빌드로 바꿨을 때 동작 차이(경고 외)는 확인하지 않았다. e2e·component를 돌리지 않았다. alias는 exports 밖 경로를 가리키므로 react-router 업그레이드 때 깨질 수 있다 |
| 결정의 근거 | 리뷰어 확인: exports에 `production` 조건이 없다. 라이브러리 쪽 선택이라 템플릿이 고르는 문제다 |
| 이해 비용 | alias 이유를 주석으로 남겨야 한다 |
| 최소 개선 방향 | 효과(−604 B)와 업그레이드 위험을 비교해 결정한다. 채택하면 alias를 `require.resolve` 기반으로 만들고, 운영 번들에 개발 경고 문구가 없음을 보는 테스트를 둔다 |
| 대안 비교 | (a) 현상 유지: 0.6 KB와 경고를 받아들인다. (b) alias(실험): −604 B, 업그레이드 때 경로 확인 필요. (c) react-router 쪽에 production 조건 요청: 비용은 작지만 시점을 정할 수 없다 |
| 단순화의 보존 조건 | 라우터 동작과 `useBlocker` 등 사용 API |
| 비용·부작용 | 설정 몇 줄과 테스트 하나 |
| 재검토 조건 | react-router가 exports에 production 조건을 넣으면 alias를 지운다 |
| 완료 기준 | 결정이 기록된다. 채택 시 운영 번들에 개발 경고 문구가 없고 e2e가 통과한다 |
| 검증 방법 | `grep -l 'You rendered descendant' dist/assets/*.js`가 0개 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
판정: 충족 / 부분 충족 / 미충족 / 미검증 / 적용 제외 / 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 일부 적용(성능 스크립트) | M2 / M2 | E1 | 부분 충족 — 판정기·분류기는 순수 함수와 얇은 CLI로 나뉜다. `check-bundle.ts` 실패 출력이 비어 있다(15-03) |
| 2 | 구조적 성숙도 | 일부 적용(청크 구성) | M3 / M3 | E3 | 충족 — 기능 9개를 더해도 초기 파일 25개 그대로다(`feature-declarations` 그룹) |
| 3 | 변경 용이성 | 적용 | — / — | E3 | 부분 충족 — 참조 모양 3개·생성 기능 8개까지는 예산 수정 없이 더한다. 그 뒤는 예산 결정이 필요하다(5.1) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E3 | 부분 충족 — 청크 이름이 내용과 다르다(`render-boot-failure`=react-dom, `chunk-KS7C4IRE`=react-router). 문서 숫자가 어긋났다(15-02) |
| 5 | 위험 가시성 | 적용 | M3 / M1 | E3 | 미충족 — lab 실패가 release 단계에서만 드러나 147 커밋 동안 안 보였다(15-01). HTTP/2 전제는 문서에만 있다(15-05) |
| 6 | 실패 성숙도 | 다른 영역(03·06·09) | — | — | 부트 실패 화면 청크 분리가 build id 변동의 원인 중 하나다(15-06) |
| 7 | 운영 성숙도 | 일부 적용 | M2 / M2 | E3 | 부분 충족 — `lab.json`에 러너·부하·표본이 남는다. field는 설계대로 `FAIL_UNVERIFIED` |
| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E3 | 부분 충족 — 예산 초과 수치가 콘솔에 없다(15-03). lab 실패 원인은 요청 추적을 해야 보인다(15-01) |
| 9 | 유지보수 성숙도 | 적용 | M3 / M1 | E3 | 부분 충족 — 손으로 적은 기준선이 두 번째로 어긋났다(15-02) |
| 10 | 테스트 성숙도 (깊게) | 적용 | M3 / M3 | E3 | 부분 충족 — 기능당 상한이 merge에서 돈다. 여유 40 B이고 원인을 나누지 않는다(15-04). unit 시간 합의 61%가 프로세스 생성 테스트다(1101/15-04 남음) |
| 11 | 데이터 성숙도 | 적용 제외 | — | — | 이 영역에 저장 데이터가 없다 |
| 12 | 동시성 성숙도 | 다른 영역(03·05) | — | — | — |
| 13 | 확장성 (깊게) | 적용 | M3 / M3(초기 JS) | E3 | 부분 충족 — 기능당 초기 +716~984 B, 파일 증가 0. 예산 기준 참조 모양 3개. 플랫폼 구성 화면은 기능 수만큼 실행부를 받는다(15-01, N개 미측정) |
| 14 | 성능 성숙도 (깊게) | 적용 | M3 / 번들 M3(merge), lab M3(release만) | E3 | 미충족 — lab 상호작용 227~271ms > 200ms(15-01). 초기 JS 98.6%. CSS·라우트 합은 미측정(1101/15-03 남음). field 미검증 |
| 15 | 보안 성숙도 | 다른 영역(13) | — | — | — |
| 16 | 의존성 성숙도 | 일부 적용 | — / M0 | E3 | 부분 충족 — react-router 개발 빌드가 운영 번들에 있다(15-07). 라이브러리 비중(지난 라운드 출처별 추정 약 57%)은 이번에 다시 재지 않았다 |
| 17 | API / Contract 성숙도 | 다른 영역(07) | — | — | — |
| 18 | 배포 성숙도 | 적용 | M3 / M1 | E3 | 부분 충족 — release 게이트가 실패한다(15-01). release마다 초기 JS 49.4%가 바뀐다(15-06). HTTP/2 전제 미검사(15-05) |
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | 충족 — 예산은 JSON 한 곳, lab 포트는 환경변수 + `--strictPort`. 파일 수 칸은 없다(15-05) |
| 20 | 개발자 경험 (깊게) | 적용 | M2 / M1 | E3 | 부분 충족 — unit 22.7초(부하 18~24). 예산 초과 메시지가 비어 있다(15-03). `npx vitest`는 고쳐졌다 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(번들 merge), lab은 release만 | E3 | 부분 충족 — 번들 검사는 merge로 옮겨졌다. lab 실패는 쌓였다(15-01). 파일 수·CSS 검사 없음 |
| 22 | 추상화 성숙도 | 다른 영역(16) | — | — | — |
| 23 | 일관성 | 일부 적용 | — | E1 | 부분 충족 — SW 테스트 한 건만 실제 5초를 기다린다(1101/15-04). build id 연쇄를 막는 그룹은 preload-helper에만 있다(15-06) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | — | E3 | 부분 충족 — rolldown 자동 청크 이름. 기능당 상한 실패 메시지가 무엇이 늘었는지 말하지 않는다(15-04) |
| 25 | 조직 확장성 | 다른 영역(12) | — | — | — |
| 26 | Ownership 성숙도 | 다른 영역(14) | — | — | 예산 결정은 다운스트림 몫이라고 문서에 있다(`performance-evidence.md:17-18`) |
| 27 | 삭제 가능성 | 다른 영역(14) | — | — | 예제 화면을 지우면 lab 대상 라우트도 바꿔야 한다(미확인) |
| 28 | 회복 가능성 | 다른 영역(06) | — | — | 부트 실패 화면이 앱 그래프와 다른 청크에 있다(09-03 유지 확인) |
## 5. 설계 선택 검토 (41절)
### 5.1 고정 200 KiB 예산과 기능당 1 KiB 상한 — 기능을 몇 개까지 넣을 수 있는가
1. **무엇이 필요한가.** 템플릿으로 서비스를 빨리 출시하고, 기능이 늘어도 첫 화면 비용이 예산 안에 머물러야 한다.
2. **지킬 성질.** 첫 화면 바이트가 합의한 상한을 넘는 변경은 merge 전에 드러난다. 기능 하나가 더하는 초기 비용은 작고 일정하다.
3. **현재 보장.** `check:bundle`(FE-GATE-012, merge)이 합계를 막는다. `feature-shape-growth` 테스트(unit, merge)가 기능당 증가를 1 KiB로 막는다. 실측: 여유 2,952 B. 참조 모양은 3개까지(204,306 B), 생성 기능은 8개까지 들어간다. 초기 파일 수는 늘지 않는다. **보장하지 않는 것:** 예산 숫자 자체의 근거(200 KiB 관례 외 기록 없음), 기능당 비용의 구성(15-04), lab 상호작용(15-01).
4. **대안.** (a) 현상 유지. 다운스트림이 첫 기능 전에 예산을 정한다(문서의 원칙). (b) 템플릿 예산을 "기준선 + 기능 N개분"으로 정의한다(예: N=20이면 약 +16 KB). (c) 고정 합계 대신 base 대비 PR당 증가량 상한. (d) 기능 선언에서 두 언어 문구 카탈로그를 빼 lazy로 옮긴다(1101 O7).
5. **비교.** (a)는 단순하다. 그러나 템플릿 자체가 98.6%를 써서 "예산을 정하라"가 사실상 "첫 주에 예산을 올려라"다. (b)는 숫자에 근거가 생기고 15-02의 기준선 대조와 맞물린다. (c)는 기능 추가를 막지 않지만 base 빌드가 하나 더 필요하다. (d)는 기능당 비용을 줄일 수 있다(얼마인지 미측정). 문구 키 충돌 부팅 검사(`check:i18n`)를 다시 설계해야 한다.
6. **판단(리뷰어 추론).** 확인한 조건에서는 (a)를 유지하되, 문서가 "기능 3개(참조 모양)"라는 실측 여유를 정확히 적어야 한다(15-02). 기능 수 목표가 생기면 (b)가 가장 작은 변경이다.
7. **재검토 조건.** 다운스트림이 기능 10개 이상을 한 앱에 넣을 계획이 생기면 (b)와 (d)를 측정과 함께 본다. field p75 LCP가 생기면 예산 근거를 field에서 거꾸로 정한다.
### 5.2 초기 청크를 나눠 두고 HTTP/2 서빙을 전제한다 (`3f9c087`)
1. **무엇이 필요한가.** 초기 JS 바이트를 줄인다(08-08, −2,718 B). 동시에 첫 화면 요청 수 비용을 감당해야 한다.
2. **지킬 성질.** 지원하는 서빙 방식에서 첫 화면이 늦어지지 않는다. 셸이 바뀌어도 청크 구성이 손으로 맞춰야 하는 목록에 묶이지 않는다.
3. **현재 보장.** entry가 24개를 한 번에 preload한다. HTTP/2에서는 묶은 빌드와의 차이가 100ms 미만이라고 `3f9c087`이 쟀다. 이번 재측정: 같은 빌드에서 HTTP/1.1이 HTTP/2보다 Fast 3G +1,013ms, Fast 4G +398ms다. **보장하지 않는 것:** 호스트가 실제로 HTTP/2인지, 다음 변경이 파일을 더 늘리지 않는지(15-05).
4. **대안.** (a) 현상 유지 + 문서 전제(지금). (b) `3f9c087`의 (나)처럼 고정 목록으로 묶기. (c) 파일 수 상한만 두기. (d) 운영 probe가 프로토콜을 기록.
5. **비교.** (b)는 HTTP/1.1에서 0.96초 빠르다(`3f9c087` 측정). 고정 목록이 낡아도 실패하는 검사가 없다는 기각 이유는 이번에도 맞다. (c)는 숫자 하나로 "파일을 늘리는 변경"을 결정으로 드러낸다. 목록 유지비가 없다. (d)는 다운스트림 호스트의 전제 위반을 배포 뒤에 알린다.
6. **판단.** 묶지 않는 결정은 유지할 근거가 있다. 다만 전제가 문서에만 있다. (c)+(d)가 가장 싼 보완이다.
7. **재검토 조건.** 다운스트림이 HTTP/1.1 호스트를 써야 하거나, field 데이터에서 느린 회선 비율이 높으면 (b)를 그 제품에서 다시 잰다. 초기 파일이 30개를 넘으면 HTTP/2에서도 다시 잰다.
### 5.3 플랫폼 구성 화면이 설치된 모든 기능의 실행부를 받은 뒤 그린다 (15-01의 원인)
1. **무엇이 필요한가.** 1101/15-01로 부팅이 기능 실행부를 싣지 않게 됐다. 그 대신 실행부끼리의 중복(스키마·operation·계약 패키지)을 브라우저 어딘가에서 드러내야 한다. 플랫폼 구성 화면은 조립된 레지스트리를 보여 주는 예제다.
2. **지킬 성질.** 실행부 중복이 있으면 보인다. 측정 대상 화면의 진입이 예산(200ms) 안이다.
3. **현재 보장.** route module이 `loadInstalledFeatureRuntimeRegistries()`를 기다린 뒤 컴포넌트를 돌려준다(`platform-overview-page.tsx:596-606`). 중복은 화면 진입 때 드러난다. **보장하지 않는 것:** 진입 시간. 두 번째 요청 묶음이 생겨 상호작용이 117 → 227ms 이상이 됐다. 기능이 늘면 두 번째 묶음도 늘어난다.
4. **대안.** (a) 현상 유지 + 예산 상향. (b) 제목·선언 정보는 바로 그리고 레지스트리 부분만 Suspense로 나중에 채움. (c) 실행부 중복 검사를 화면에서 빼고 단위 테스트·`check:registries`만 믿음. (d) lab 대상을 다른 화면으로.
5. **비교.** (a)·(d)는 회귀를 숨긴다. (b)는 검사와 표시를 유지하고 측정 시간을 되돌릴 것으로 보인다(미측정). (c)는 화면이 가벼워지지만 런타임 feature override처럼 빌드 검사를 거치지 않는 조합의 중복이 브라우저에서 안 보인다.
6. **판단(리뷰어 추론).** (b)가 보호하는 성질을 잃지 않는 가장 작은 변경이다.
7. **재검토 조건.** 이 화면이 예제가 아니라 운영 진단 화면이 되면, 실행부를 미리 받는 프리페치나 서버 쪽 사전 조립을 다시 비교한다.
## 6. 측정 기록
모든 바이트는 `check:bundle`과 같은 계산(`classifyViteJavascript` + Node `gzipSync` 기본 수준)이다. 부하는 1분 loadavg다(시작 → 끝). 스크립트는 리뷰어 scratchpad `r15/`에 있다(커밋하지 않음).
| 명령·실험 | 부하 | 결과 |
|---|---|---|
| `corepack pnpm build && corepack pnpm check:bundle` | 15.8 → 15.0 | 둘 다 rc=0. 빌드 1.9초. **초기 JS 25개 646,090 B raw / 201,848 B gzip / 204,800**, 여유 2,952 B. lazy 22개 35,367 B(최대 `use-reference-feature` 8,524). CSS 1개 40,559 B raw / 8,766 B gzip |
| 초기 청크 구성(위 빌드) | — | `render-boot-failure` 59,652(react-dom 포함), `boot` 39,104, `feature-platform` 37,805(zod·HTTP 실행기·계약 런타임), `chunk-KS7C4IRE` 30,767(react-router 개발 빌드), `i18n` 8,102, `server-state-scope-provider` 6,171, `react` 3,157, `feature-declarations` 2,868, 그 밖 17개 14,222 |
| 커밋별 귀속(같은 빌드 ID `local-build`) | 17.2 → 22.8 | `ec7435c` 202,774 B·26개 / 첫 부모 `93c81df` 201,058·25 / 둘째 부모 `8c39e77` 203,590·26 / `e40684b` 201,850·25 |
| build id 비교(`gitea-101-1` vs `gitea-102-1`) | 13.4 → 12.7 | 바뀐 초기 파일 3개 99,784 B(49.4%), lazy 0 B |
| `node scripts/scale/measure-feature-shape-growth.ts --sizes=0,1,2,3,5,10 --repeats=1` | 25.2 → 22.4 | 초기 201,848 → 202,832(+1) → 203,590(+2) → 204,306(+3) → 205,722(+5) → 209,257(+10). 초기 파일 25개 고정. lazy 35,367 → 120,477(+10). tsc 인스턴스화 792,080 → 1,940,423 |
| `create:feature` 실험(빌드 + `check:bundle`) | 8.7 → 8.8 | +invoice(새 context) 202,445 / +payment(새 context) 202,812 / +order 203,100 / +refund 203,430 / +5개 더(같은 context) 204,822 **FAIL**(22 B 초과, 메시지 빈칸). 초기 파일 25개 고정, lazy +3개/기능 |
| 기능당 비용 bisect(`measureInitialJavascriptGzipBytes` 0·1·2) | 13.1 → 12.6 | `298201f` +740/+636, `e4ace51` +805/+655, `51941a5` +949/+758, `ca16187` +1,025/+775, `ec7435c` +979/+788. 귀속 실행: 첫 부모 +977, 둘째 부모 +990, `e40684b` +984 |
| HTTP/1.1 vs HTTP/2(자체 `https`·`http2` 서버, 같은 handler, TLS, gzip, CDP Fast 3G 562.5ms·180,000 B/s / Fast 4G 165ms·1,012,500 B/s, 새 context, 첫 화면 = 부팅 셸 사라짐 + `#main-content h1[data-route-heading]`, 번갈아 5회) | 15.5 → 7.5 | Fast 3G: h1 6,022(5,998~6,037), h2 5,009(4,802~5,023). Fast 4G: h1 1,900(1,882~1,925), h2 1,502(1,495~1,532). 응답 30개, JS 26개. 첫 시도(부하 70)는 60초 시간 초과로 버렸다 |
| `test:performance` A/B 1(`ec7435c`↔`e40684b` 2회) | 13.5~20.6 | 상호작용 중앙값 249·263 / 271·256ms, 모두 FAIL. LCP 2,092~2,140 |
| `test:performance` A/B 2(`d99301b`↔`e40684b` 2회 + bisect) | 13.9 → 36.2 | `d99301b` 118·117ms **PASS**, `e40684b` 232·227ms FAIL, `298201f` 226, `e4ace51` 371, `6dd4bc1` 412, `51941a5` 378, `ca16187` 292(뒤 넷은 부하 17~37이라 참고만) |
| `test:performance`(`final-base`, `e40684b`) | 28.9 → 23.7 | FAIL. LCP 2,064, CLS 0, 상호작용 230(228~280) |
| lab 화면 진입 요청 추적(같은 throttle, `vite preview`) | 19.5~19.7 | `d99301b`: 한 번에 2개 5,019 B. `e40684b`: 한 번에 5개 7,942 B, 약 100ms 뒤 `feature-runtime` 2,196 + `reference-schemas` 776 |
| react-router `dist/production` alias(`vite.config.ts` 임시 수정) | — | 초기 201,848 → 201,244 B(−604), 개발 경고 문구 파일 1 → 0. 되돌렸다 |
| `corepack pnpm check:optional-recipes` | 30.7 | PASS. file-transfer 56,053/57,800, offline-indexeddb 37,423/38,500, realtime 40,857/42,200, service-worker-pwa 9,716/10,100 |
| `node scripts/run-vitest.ts run tests/unit --reporter=json` | 18.1 → 24.5 | 176파일 2,580건 통과, 22.7초. 파일별 시간 p50 94ms·p90 2.2초·최대 12.3초. 5초 이상 9개. 자식 프로세스 파일 21개가 시간 합의 61%(80.8 / 133.4초) |
| 같은 방법 `tests/component` | 24.5 → 24.4 | 39파일 263건, 11.6초. p50 0.93초, 최대 5.8초(`form-foundation`). 프로세스 생성 0 |
| 같은 방법 `tests/integration` | 24.4 → 21.7 | 10파일 117건, 14.7초. `security-followup-archive` 12.5초(release candidate 빌드)가 시간 합의 58% |
| `npx vitest run tests/unit/ci-workflow-generation.test.ts` | 21.7 | 423/423 통과(1101/15-05 고쳐짐) |
| 오케스트레이터 게이트 기록(같은 커밋, 부하 미기록) | — | `test:unit` 19초, `test:component` 9초, `test:integration` 16초, `check:bundle` 201,848 B. `test:performance`는 목록에 없다 |
**unit에서 가장 느린 파일.** `documentation-readiness` 12.3초(SPAWN), `security-promotion-staging` 8.8초(SPAWN, 한 테스트 7.1초), `risk-coverage` 8.5초(실제 소스 트리 전체), `ci-workflow-generation` 8.2초(423건, SPAWN), `feature-shape-growth` 7.6초(빌드 2회), `fixture-node-modules` 6.8초(실제 pnpm install), `build-environment-bundle` 5.9초, `service-worker-runtime` 5.6초(실제 5초 대기 1건), `product-feature-selection-build` 5.2초, `two-feature-install-typecheck` 5.0초.
@@ -0,0 +1,457 @@
# 16 폴더 구조·리팩토링·기능 개발 패턴 — 성숙도 리뷰
> 검토일: 2026-11-03 · 기준: `review/2026-11-03-merged` / `e40684b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: repo 구조 전체, `src/features/reference-feature/`, `scripts/create-feature.ts`, `docs/manual/`, `docs/architecture/`
> 깊게 본 관점: 2, 3, 4, 9, 22, 23, 24, 27
> 렌즈: `docs/manual/`만 보고 짝 백엔드 모양의 공지 기능(목록 GET, 상세 GET, 작성 POST — KEYED, Envelope)을 `corepack pnpm create:feature`로 시작해 추가했다. "API는 contract contribution 한 곳에만 적는다", `<base>-schema-metadata.ts`, Envelope 선언이 실제로 한 번만 적기가 되는지 봤다. Envelope를 선언하지 않는 참조 기능이 완성된 예시로 맞는지 판단했다.
> 영역 판정(35.8): **조건부 사용 가능.** 생성 명령과 매뉴얼만으로 3라우트·3operation 기능을 추적 파일 수정 0건으로 넣었고, merge 게이트 10개와 기존 테스트 3,201건이 그대로 통과했다. 조건은 넷이다. (1) operation을 손으로 더할 때마다 `responseEnvelope` 줄을 넣고, 그 operation의 실제 백엔드 본문을 손으로 적은 테스트를 둔다(16-01). MSW 시나리오 테스트는 이 실수를 잡지 못한다. (2) 제품 기능의 제거 확인(`test:sample-removal -- --feature=<id>`)은 지금 쓸 수 없다(16-02). 매뉴얼 03의 "기능을 지울 때" 손 목록으로 대신한다. (3) KEYED 쓰기는 6.2절 B1~B4의 값(호출 문맥의 `intent`, `retryBudget`, `classifyStatus`)을 사람이 정한다(16-07). (4) 접근성 e2e가 생성 기능의 본문을 검사한다고 믿지 않는다(16-03). 릴리스 전 사람 서명이 그 공백을 메운다.
## 0. 결론
- **실험.** `create:feature notice-feature`에서 시작해 공지 기능을 짝 백엔드 모양으로 완성했다. 에이전트 기준 약 8분 걸렸다. 막힌 곳은 6번이었다. 그중 4번은 매뉴얼에 없는 값을 코드에서 찾아 정했다(B1~B4). 2번은 예제로 풀린 작은 혼동이었다(B5·B6). 지난 라운드 복사 실험은 12번, 지난 매뉴얼 재실험은 5번 막혔다. 추적 파일은 하나도 고치지 않았다. 새 파일만 생겼다: 기능 폴더 20개, 기능 테스트 3개, context 선언 1개(생성), a11y 기록 3개(1개 생성, 2개 손 복사).
- **게이트.** 기능이 들어간 상태에서 `check:types`, `lint`, `check:architecture`, `check:registries`(additive), `check:i18n`, `check:design-system`, `check:diagnostics`, `verify:documentation`, `check:adapter-inventory`, `check:ci`가 모두 rc=0이다. 기능 테스트 17건, 그 밖의 빠른 계층 3,201건(262파일)이 통과했다. 기능 하나가 무관한 테스트를 깨던 문제(1101/16-02)는 다시 나오지 않았다. `build` 통과, `check:bundle` 202,769 / 204,800 B로 통과했다(6.3절).
- **제거 확인은 막혔다(16-02).** `test:sample-removal -- --feature=notice-feature`가 3초 만에 `config/ci/contract-baseline.json invalid: reason: leading/trailing whitespace is forbidden`으로 끝났다. 기능 전용 CI 스크립트가 없는 기능이면 항상 이렇다. 참조 기능 말고는 모든 제품 기능이 여기에 해당한다. 원인 한 줄을 실험으로 고친 결과는 6.3절에 적었다.
- **"한 번만 적기"는 operation에서는 성립한다.** method·path·status·재시도·인증·한도는 descriptor 한 곳에만 썼다. FE-REG-API 행은 거기서 뽑혔다. 기준선은 바뀌지 않았다(additive). 그러나 같은 사실을 손으로 다시 적는 칸이 넷 남았다. Envelope는 operation마다 적는다(16-01). 스키마 메타 행은 zod와 descriptor에서 알 수 있는 사실을 다시 적고, 틀려도 아무도 잡지 않는다(16-04). 뮤테이션 정책의 operation ID는 자유 문자열이다(16-05). 쿼리의 `operationId`·`owner`, 라우트 계약의 `title`·`navigationLabel`은 필수 칸이지만 화면과 실행이 읽지 않는다(16-06).
- **가장 큰 위험은 16-01이다.** 둘째 operation에서 `responseEnvelope` 줄을 빼도 타입·레지스트리·라우터 페이지 테스트가 모두 통과했다. MSW 시나리오 핸들러가 descriptor를 그대로 따라 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 `SCHEMA_MISMATCH`로 깨진다. 손으로 백엔드 본문을 적은 테스트만 잡았다.
- **참조 기능 판단.** 완성된 예시이긴 하다. 다만 "짝 백엔드가 아닌 백엔드"용 예시다. 사용자 목표의 기본 경로(Envelope)에서는 KEYED 작성·폼·결과 불명 화면의 완성 예시가 없다. 실험에서 작성 경로 약 400줄을 참조 기능을 보며 손으로 옮겼다. 결함 자체는 09-06과 같으므로 다시 세지 않았다. 이 영역의 판단과 권고는 5.3절에 적었다(생성 명령에 쓰기 slice 선택을 더하는 쪽).
- **지난 16 발견 7건.** 고쳐짐 4(16-01·02·03·04), 바뀜 1(16-07, 문서로 충족), 남음 2(16-05 일부, 16-06).
- **이번 발견.** High 0 · Medium 3 · Low 5. P2 6 · P3 2. 다른 영역 발견과 같은 사실은 2.3절에 증거만 붙였다(09-06, 09-10, 14-05, 14-06, 1101/07-07, 12-03).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `e40684b`(`claude/happy-easley-233d07` + `fix/ui-design-audit-2026-11-01` 병합). 격리 worktree `agent-ae89fbafcc2d11556`에서 `git checkout --detach e40684b`, `corepack pnpm install --frozen-lockfile`(4.7초). 2026-11-03 22:57~23:55 확인. 실험 뒤 `git checkout -- . && git clean -fd`로 되돌렸다. 커밋하지 않았다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template`, 읽기만)와 함께 서비스를 빨리, 실수 없이 출시. 기능 수 증가 외 정량 목표 없음 |
| 읽은 코드·구성 범위 | `docs/manual/` 전체(README, 01~03, `reference/` 4개), 생성된 기능 파일 전체, `scripts/create-feature.ts`의 해당 템플릿, `src/features/reference-feature/`의 contribution·schema-metadata·schemas·gateway·application·hooks·form·form page·detail page·route codecs·routes·context-routes, `src/contracts/external-contract-runtime.ts`(descriptor 타입과 조립 검사), `src/contracts/server-state.ts`, `src/contracts/schema-registry.ts`, `src/contracts/mutation-intent.ts`, `src/adapters/http/http-execution-v3.ts`(intent 검증·재시도 상한), `src/adapters/http/feature-http-binding.ts`, `src/presentation/adapters/query/application-query.ts`의 mutation 부분, `tests/mocks/handlers/http-scenarios.ts`, `tests/mocks/scenarios/catalog.ts`, `tests/e2e/accessibility.spec.ts`, `scripts/check-registries.ts:355-380`, `scripts/test-sample-removal.ts:100-130, 355-385`, `scripts/lib/removal-fixture.ts:354-472`, `config/contracts/registry-governance.json`의 FE-REG-SCHEMA, `docs/architecture/starter-experience.md` "Adding a feature", 백엔드 `docs/web/http-contract.md` |
| 수행한 테스트·실험 | 6절. 기능 추가 실험(B1~B6), 변이 9개(E-1~E-9), 빠른 계층 실행, 게이트 10개, `build`·`check:bundle`, 제거 드릴 2회(그대로 1회, 원인 한 줄 고친 뒤 1회). 전체 게이트는 다시 돌리지 않고 오케스트레이터 결과(`scratchpad/review-gates/summary.txt`, 같은 커밋, 15개 rc=0, `check:bundle` 201,848 / 204,800 B)를 인용했다. 무거운 실행은 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock`으로 감쌌다 |
| 확인하지 못한 범위·이유 | Playwright(`test:a11y`, `test:e2e`) — 공유 잠금 대기열이 길어 돌리지 않았다. 16-03은 vitest 탐침(E-8)과 코드로 판단했다. `test:coverage`의 커버리지 계측과 `check-risk-coverage` — 잠금 대기 중 취소하고 같은 테스트 묶음을 계측 없이 돌렸다. 릴리스 승인(`check:release-admission`), 다운스트림(tech-log·memento) 이식, 짝 백엔드 실제 실행은 하지 않았다 |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md`의 16-01~16-07, 2.1·2.2절 항목, R-1~R-9, README 13~14절의 이 영역 조치. 지난 실행 결과는 증거로 쓰지 않았다. 모두 현재 코드와 새 실행으로 다시 판정했다(2절) |
| 실행 중 부하 | 다른 리뷰어와 함께 돌았다. 테스트 실행 직전 부하 평균 42~91, `build` 직전 8.3. 이 영역 결론은 실행 시간에 기대지 않는다 |
## 2. 지난 발견 재판정
### 2.1 지난 16 영역 발견과 R 목록
| ID | 지난 내용 | 판정 | 근거(이번 커밋·실행) |
|---|---|---|---|
| 1101/16-01 | 기능 추가 문서가 폴더 밖 수정을 4행으로 적지만 실제는 7묶음과 결정 2가지 | **고쳐짐** | `create:feature`와 FE-GATE-020(`test:feature-scaffold`)이 있다. 실험에서 3라우트 기능을 넣는 동안 추적 파일 수정 0건. 폴더 밖 새 파일은 context 선언(생성)과 a11y 기록뿐이다. `starter-experience.md:179-192` 표가 지금 목록이다. 남은 것: 표의 오류 문구(14-05), 접근성 spec 수정 행(16-03) |
| 1101/16-02 | 기능 하나를 더하면 무관한 테스트 3개가 깨지고 MSW 카탈로그가 참조 operation에 묶임 | **고쳐짐** | 공지 기능을 넣고 `tests/features tests/component tests/architecture tests/runtime-schema tests/contract`(76파일 504건), `tests/unit tests/integration`(186파일 2,697건) 모두 통과. `createHttpScenarioHandler(<계약>)`로 `tests/mocks`를 고치지 않고 시나리오를 썼다(`tests/mocks/handlers/http-scenarios.ts:35`). 남은 것: `--context reference-context`는 참조 테스트를 깬다(매뉴얼 01:120, `reference/create-feature.md:137`에 적힘) |
| 1101/16-03 | 인증 프로필 이름이 샘플 이름이고 오류가 operation을 말하지 않음 | **고쳐짐(이름)**, 진단은 14-06으로 | `EXTERNAL_BEARER`, 옛 이름은 `src/contracts/rest-profiles.ts:67` 별칭 한 줄. 조립 오류 `reason`은 `notice-feature/NOTICE_GET: unknown authProfileId EXTERNAL_BEARR`처럼 operation을 말한다(E-3). 다만 `check:registries`는 그 `reason`을 출력하지 않는다(14-06과 같은 사실, 2.3절) |
| 1101/16-04 | 샘플 페이지가 경로를 문자열로 적고 route 입력을 cast | **고쳐짐** | `src/features/reference-feature/presentation`에 `"/examples/` 0건, route 입력 cast 0건. `reference-routes.ts:54-77`의 `buildRouteUrl` + codec 패턴을 공지 기능에 그대로 옮겼고 타입이 통과했다 |
| 1101/16-05 | 같은 개념이 두 폴더에 비슷한 이름으로 | **일부 남음** | ① 기능 오류 경계 두 벌이 그대로다(`src/presentation/boundaries/render-error-boundary.tsx:89`, `src/platform/errors/feature-error-boundary.tsx:12`). ② `TelemetryPort` 두 타입이 그대로다. 매뉴얼이 "쓰지 않는다"고 적는다(01:304, `reference/patterns.md:128`) — M1. ③ `adapters` 두 뜻 그대로. ④ `src/application/result.ts`(폐기 재수출)가 남았다. 샘플은 이제 `ApiFailure`를 쓰지 않는다 |
| 1101/16-06 | 기능 `contracts/`가 와이어 계약·문구·뷰 모델을 함께 담고 규칙이 없음 | **남음** | 참조 기능 `contracts/` 660줄(지난 891줄)에 문구 catalog·뷰 타입이 여전히 있다. 생성 뼈대도 `contracts/<base>-message-catalog.ts`, `contracts/<base>-mapper.ts`(뷰 타입)로 같은 배치를 퍼뜨린다. E-6: `presentation → contracts/notice-reexport-http.ts → src/adapters/http`와 `presentation → hooks/use-raw-http.ts → src/adapters/http`가 `check:architecture` rc=0, eslint rc=0. 매뉴얼은 "못 잡음"으로 적고(01:357) "다섯 폴더만 둔다"고 안내한다 — M1 |
| 1101/16-07 | 자주 쓰는 패턴 7개의 예제가 없음 | **바뀜(문서로 충족)** | `docs/manual/reference/patterns.md`가 패턴마다 예제 위치나 "없음"을 적는다. 지난 완료 기준("빠진 패턴에 예제 위치나 의도적 비지원 표시")은 충족했다. 패턴 자체(페이지 넘김, 낙관적 갱신, 수정·삭제, 기능 간 협력, 권한 힌트)는 여전히 예제가 없다 |
| R-1 | 기능 라우트가 context 루트 밑인지 조립 때 검사 | **고쳐짐** | E-5: 상세 경로를 `/notices/items/:noticeId`로 바꾸자 앱 모듈이 적재 때 `Route NOTICE_DETAIL (...) is not under the route root of its context notice-context (notice/*)`로 거부했다. 앱을 부팅하는 테스트(component 6파일, 라우터 페이지 테스트)가 실패했다. 다만 매뉴얼이 이름을 든 `tests/architecture/context-route-roots.test.ts`는 fixture만 써서 통과했다(16-08) |
| R-2 | 기능 로컬 route 헬퍼 | **고쳐짐** | 생성 뼈대 `presentation/<base>-routes.ts`, 참조 `reference-routes.ts` |
| R-3 | V2 선언을 V3에서 생성 | **고쳐짐(다른 방법)** | V2 행 자체를 지웠다(`12f3bb7`). FE-REG-API는 descriptor에서 뽑는다(`src/contracts/api-operations.ts:40-60`) |
| R-4 | MSW 카탈로그 일반화 | **고쳐짐** | 1101/16-02 행과 같다 |
| R-5 | 전역 상태 단정 테스트 3개 | **고쳐짐** | 1101/16-02 행과 같다 |
| R-6 | feature 수준 오류 경계 하나로 | **남음** | 1101/16-05 ① |
| R-7 | `src/application/result.ts` 삭제 | **남음** | 1101/16-05 ④ |
| R-8 | 기능 `contracts/`에서 뷰 모델·문구 분리 + 폴더 규칙 | **남음** | 1101/16-06 |
| R-9 | 인증 프로필 이름 변경 + 오류에 operation ID | **고쳐짐(조립 오류)** | 1101/16-03 행 |
### 2.2 지난 16 문서 2.1·2.2절 항목
| 항목 | 판정 | 근거 |
|---|---|---|
| 0929/07-03 라우트 하나에 governance allowlist 수정 | **고쳐짐** | 공지 기능의 새 params 스키마(`NoticeParams`)와 로딩 화면 3개로 `check:registries`가 governance 수정 없이 `PASS; compatibility=additive` |
| 0929/07-02 추가 변경을 breaking으로 분류 | **고쳐짐** | 라우트 3·operation 3·스키마 5·topic·namespace·edge 추가가 additive. 기준선 갱신 없음 |
| 12-03 기능 안 layer 폴더 밖에 규칙 없음 | **남음** | E-6. 1101/16-06 행 |
| 0929/08-06 라우트 제목이 세 곳 | **바뀜 → 16-06** | 화면은 catalog `route.<ID>.title`·`.navigation`만 읽는다(`src/presentation/routes/app-router.tsx:92, 183`, `src/presentation/layouts/app-shell.tsx:216`). 계약의 `title`·`navigationLabel`은 화면이 읽지 않는 칸으로 남았다 |
| 0929/10-02 플랫폼 테스트가 제품 콘텐츠를 대상으로 씀 | **고쳐짐** | 두 기능 설치 상태에서 `tests/component` 전부 통과 |
| FOLLOW-UP 초기 JS 여유 | **바뀜** | 6.3절. 3라우트 기능 하나가 +921 B, 남은 여유 2,031 B |
| 09-06 기능 라우트와 context 루트 관계 | **고쳐짐** | R-1 행 |
| 07-04 `TEMPLATE_FIXTURE`를 아무 기능이나 씀 | **고쳐짐** | 조립기가 참조 기능 밖에서 거부한다(`src/contracts/external-contract-runtime.ts:846-867`). 정적 확인만 했다(E1) |
| 07-03 zod 어댑터가 참조 기능 안에만 | **고쳐짐** | `src/contracts/zod-validator.ts`. 생성 뼈대와 공지 기능이 그대로 쓴다 |
| 14-06(1101) 문서 검사가 누락 route ID를 말하지 않음 | **고쳐짐** | E-7: `NOTICE_CREATE.md`를 빼자 `artifacts/tests/a11y-manual/ has no record for route IDs: NOTICE_CREATE`, FE-GATE-009는 `artifacts/tests/a11y-manual/NOTICE_CREATE.md: missing record` |
| 14-03·14-04(1101) 입구 문서·예제 제거 | 이 영역에서 다시 보지 않음 | 14 영역 소관 |
| 09-09(1101) 경계가 진단을 남기지 않음 | 이 영역에서 다시 보지 않음 | 09 영역 소관 |
### 2.3 다른 영역 발견에 이 영역 실험이 더한 증거
같은 결함을 다시 세지 않는다.
| 발견 | 이 영역이 더한 증거 |
|---|---|
| 09-06 참조 기능이 짝 백엔드 응답 모양이 아니다 | 실험에서 상세 GET·KEYED POST·폼·결과 불명 화면의 유일한 예제가 참조 기능이었다. 참조 문제 스키마(`type`·`title`·`status` 필수, `reference-schemas.ts:39-58`)를 공지 기능에 옮기자(E-8 b) 손으로 백엔드 본문을 적은 테스트 4건이 실패했고, MSW 시나리오로 쓴 "같은 키 재전송" 폼 테스트는 통과했다. 문제 본문 검증이 실패하면 모든 실패가 `MAYBE_APPLIED`가 되어 결과 불명 화면이 대신 나오기 때문이다. 판단과 권고는 5.3절 |
| 14-05 정본 표·결정표 5절이 지운 메시지를 적는다 | E-3에서 같은 문구(`REST security profiles are incoherent for ...`)를 매뉴얼에서 찾았고 코드에는 없었다 |
| 14-06 `check:registries`가 조립 실패의 `reason`을 버린다 | E-3: 인증 프로필 오타 하나로 `check:registries` 출력 13줄 중 원인은 0줄이고 `breaking change missing evidence: FE-REG-API:*:*:removed`가 나온다. `reason`은 vitest 출력에만 보였다. 원인은 `scripts/check-registries.ts:372-375`가 `error.message` 첫 줄만 붙이고 `ContractContributionError.reason`(`src/contracts/external-contract-runtime.ts:266`)을 버리는 것이다. 지금은 기능 실행부가 지연 로드라 `check:i18n`·`check:diagnostics`·`check:design-system`·`check:architecture`·`verify:documentation`은 통과한다. 매뉴얼 01:267의 "operation을 적재하는 모든 게이트가 실패한다"보다 범위가 좁다(16-08) |
| 09-10 V2 삭제 뒤 실행부 모양 설명이 남음 | 실험 중 `starter-experience.md:136-137`("runtime schemas, mappers")을 읽고 `defineFeatureRuntime`에 그 칸이 없음을 확인했다(`src/features/feature-module.ts:51-65`) |
| 1101/07-07 `commandRecovery`를 실행기가 읽지 않는다 | 16-07 B2. 매뉴얼은 `operationIdentityField`를 필수라고만 적고 무슨 값을 넣는지 말하지 않는다. 실험에서 참조 값 `"idempotencyKey"`를 그대로 복사했다 |
## 3. 이번 발견 (36.3)
| ID | 제목 | 성격 | 심각도·우선순위 | 관련 관점 |
|---|---|---|---|---|
| 16-01 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다 | 구조적 위험 | Medium · P2 | 3, 17, 21, 10, 5, 22, 4 |
| 16-02 | 제품 기능의 제거 드릴(`test:sample-removal -- --feature=<id>`)이 시작 3초 만에 무관한 오류로 끝난다 | 확인된 결함 | Medium · P2 | 27, 21, 10, 20, 8 |
| 16-03 | 공유 접근성 e2e spec이 기능마다 템플릿 파일 수정을 요구하고, Envelope 기능에는 오류 화면만 검사한다 | 확인된 결함 | Medium · P2 | 10, 21, 25, 27, 9, 20 |
| 16-04 | 스키마 메타 행이 zod·descriptor에서 알 수 있는 사실을 손으로 다시 적고, 틀려도 아무 검사가 잡지 않는다 | 구조적 위험 | Low · P2 | 3, 17, 22, 21, 4, 23 |
| 16-05 | 뮤테이션 정책의 `operationId`가 자유 문자열이라 오타가 타입·레지스트리를 통과하고, 작성 화면이 요청도 보내지 않고 멈춘다 | 확인된 결함 | Low · P2 | 21, 3, 8, 24, 22 |
| 16-06 | 기능 작성자가 반드시 채우는 칸 중 화면·실행이 읽지 않는 칸이 있다 | 개선 제안 | Low · P3 | 4, 22, 23, 24, 9 |
| 16-07 | 짝 백엔드에 KEYED 쓰기를 붙이는 값 넷을 매뉴얼이 정해 주지 않는다 | 개선 제안 | Low · P2 | 4, 20, 3, 17, 19 |
| 16-08 | 기능 추가 경로 문서의 낡은 문장(09-10·14-05 밖) | 확인된 결함 | Low · P3 | 9, 20, 24, 10 |
### 16-01 Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다 — 짝 백엔드에서 그 화면만 `SCHEMA_MISMATCH`로 깨진다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 3, 17, 21, 10, 5, 22, 4 |
| 근거 | ① 선언: `responseEnvelope`는 descriptor마다 있는 선택 칸이고, 없으면 `"NONE"`(DTO·problem details)이다(`src/contracts/external-contract-runtime.ts:198-208`, FE-REG-API 투영 `src/contracts/api-operations.ts:49`). 생성 뼈대는 GET 하나에만 이 줄을 쓴다(`scripts/create-feature.ts:668`). ② 매뉴얼: "이 모양을 읽게 하는 것은 V3 descriptor의 한 줄 ... 뼈대에 들어 있다"(01:196). 손으로 더하는 operation에도 넣으라는 문장이 없고, 01:243-261의 공지 예시는 "입력에 관한 칸만" 보여 이 줄이 없다. 상세 GET·KEYED POST의 유일한 예제인 참조 기능도 이 줄이 없다. ③ 테스트 하네스: `createHttpScenarioHandler`는 descriptor를 보고 Envelope로 답할지 정한다(`tests/mocks/handlers/http-scenarios.ts:67-72`). 그래서 시나리오로 쓴 테스트는 선언이 무엇이든 그 선언과 맞는 본문을 받는다. 생성된 손글씨 본문 테스트(`tests/features/<id>/<base>-http-gateway.test.ts`)는 생성된 GET 하나만 다룬다. ④ 실행(E-1): 완성한 공지 기능에서 `NOTICE_GET`의 `responseEnvelope` 줄만 지웠다. `check:types` rc=0, `check:registries` rc=0(additive), 라우터를 거치는 페이지 테스트 6건 통과("목록에서 공지를 연다" 포함). 실패는 백엔드 본문을 손으로 적은 gateway 테스트 1건뿐이었고 결과는 `kind: SCHEMA_MISMATCH`, `code: SUCCESS_SCHEMA_INVALID`였다 |
| 발생 조건 | 생성 뼈대에 operation을 손으로 더할 때(목록·상세·작성처럼 기능 대부분). 참조 기능 descriptor를 보고 옮길 때 |
| 영향 | 짝 백엔드에 붙이면 그 화면은 항상 오류 화면이다. 쓰기 operation에서 빠지면 실패 본문의 문제 검증이 실패해 모든 실패가 결과 불명으로 간다(추론. GET만 실행으로 확인). 기능 테스트가 초록이라 실제 백엔드에 처음 붙일 때까지 모른다. 기능마다, operation마다 같은 실수 자리가 생긴다 |
| 심각도·우선순위 | Medium · P2 — 데이터 손상은 없고 실제 백엔드를 붙이면 바로 드러난다. 다만 템플릿 테스트가 거짓 안심을 주고, 사용자 목표(두 템플릿을 짝으로 쓰기)의 기본 경로에서 기능마다 반복된다 |
| 통제·증거 | 목표 M4(빠뜨리면 컴파일 실패) 또는 M3(머지 전 검출). 확인 M1(뼈대 주석, 매뉴얼 한 줄) · E3(E-1) |
| 확실성과 남은 가정 | GET 누락은 실행으로 확인했다. POST 누락의 결과는 실행기 코드에서 추론했다. 한 기능이 일부러 두 모양의 백엔드를 섞는 경우가 있는지는 확인하지 못했다(설계 기록 14.6은 "한 앱이 두 모양의 API를 같이 쓸 수 있어야 한다"를 이유로 든다) |
| 결정의 근거 | 확인한 사실: operation 단위 선언은 1101 README 14.6에서 provider 단위(앱 전체)를 버리고 고른 것이다. 그때 비교한 것은 "앱 전체 한 값" 대 "operation마다"였다. 기록된 의도: 값이 없는 descriptor를 그대로 두어 참조 기능·테스트 계약·recipe를 건드리지 않는다. 리뷰어 추론: 계약 패키지 하나는 백엔드 하나에서 오므로 그 안의 operation은 대부분 같은 모양이다. "기여(패키지) 단위 기본값"이나 "값 생략 금지"는 비교되지 않았다 |
| 이해 비용 | 기능 작성자가 operation을 더할 때마다 이 줄을 기억해야 한다. 잊어도 신호가 없다. 리뷰어는 descriptor 셋을 나란히 놓고 줄을 세야 한다 |
| 최소 개선 방향 | `responseEnvelope`를 필수 칸으로 바꾼다(`"NONE"`도 명시). 빠뜨리면 `satisfies InstalledHttpContract<...>`에서 tsc가 실패한다. 함께 매뉴얼 01 3단계에 "operation마다 이 줄"을 적고 01:243-261 예시에 넣는다 |
| 대안 비교 | (a) 현상 유지: 손글씨 본문 테스트에 기댄다. (b) 필수 칸: 가장 작은 M4. descriptor 약 20곳(참조 3, `tests/` 약 15, `scripts/drill-runbook.ts`, 예제 화면)에 `"NONE"`을 적는 비용. 한 앱에 두 모양을 섞는 능력은 그대로다. (c) 기여 단위 기본값 + operation 덮어쓰기: 반복이 가장 적다. 대신 "기본값이 어디서 오는가"라는 규칙이 하나 는다. (d) 조립기가 한 `EXTERNAL_PACKAGE` 기여 안에서 값이 섞이면 거부: 섞는 경우를 막는다. 전부 빠뜨린 경우는 못 막는다. (e) 생성된 gateway 테스트를 descriptor마다 도는 표 형태로: M3지만 기능 작성자가 표에 행을 더해야 한다. (b) 권장. (c)는 기능이 operation 열 개를 넘는 일이 흔해질 때 다시 본다 |
| 단순화의 보존 조건 | 한 앱이 Envelope와 DTO 모양 API를 함께 쓸 수 있다. 값이 `"NONE"`인 descriptor의 동작(참조 기능·테스트 계약)은 바뀌지 않는다. FE-REG-API 행의 `responseEnvelope` 값이 지금과 같다(기준선 무변경) |
| 비용·부작용 | (b)는 descriptor 약 20곳 한 줄씩. 다운스트림의 손으로 쓴 descriptor도 컴파일 오류가 나므로 CHANGELOG에 이행 안내가 필요하다 |
| 재검토 조건 | 짝 백엔드 외의 백엔드를 쓰는 다운스트림이 생기거나, 기능당 operation 수가 크게 늘 때 (c)를 다시 비교한다 |
| 완료 기준 | descriptor에서 `responseEnvelope` 줄을 지우면 `check:types`가 실패한다. 매뉴얼 3단계와 예시에 이 줄이 있다 |
| 검증 방법 | E-1을 다시 한다: 공지 기능 `NOTICE_GET`에서 줄을 지우고 `check:types` 실패를 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
### 16-02 제품 기능의 제거 드릴(`test:sample-removal -- --feature=<id>`)이 시작 3초 만에 무관한 오류로 끝난다 — 기능 전용 CI 스크립트가 없으면 CI 기준선 사유가 공백으로 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 27, 21, 10, 20, 8 |
| 근거 | ① 매뉴얼 11단계(01:583), 03:137, `starter-experience.md:176`이 기능마다 이 명령을 돌리라고 한다. ② 참조 기능이 아닌 기능의 extras는 `ciScripts: []`다(`scripts/test-sample-removal.ts:110-112`). 그 빈 집합이 `pruneRemovalFixtureCiContract`로 가고(`:360, 367-371`), CI 기준선 사유를 `` `removal fixture pruned ${[...options.removedScripts].join(", ")}` ``로 만든다(`scripts/lib/removal-fixture.ts:468-471`). 집합이 비면 사유는 `"removal fixture pruned "`(끝 공백)다. 바로 뒤 `regenerateRemovalFixtureWorkflow`(`:354-356`)가 기준선을 읽고 `assertCiContractBaseline`(`scripts/contracts/ci-gates.ts:526-536`)이 거부한다. ③ 실행(`flock` 아래, 23:37): `corepack pnpm test:sample-removal -- --feature=notice-feature` → 레지스트리 기준선 갱신까지 간 뒤 `TypeError: config/ci/contract-baseline.json invalid: reason: leading/trailing whitespace is forbidden`, rc=1, 3초. 게이트·잔여 검사는 하나도 돌지 않았다. ④ 실험으로 사유 한 줄만 고친 결과는 6.3절 |
| 발생 조건 | 참조 기능 말고 어떤 기능이든 `--feature=<id>`로 드릴을 돌릴 때. `create:feature`로 만든 기능은 전부 해당한다 |
| 영향 | 문서가 약속한 "기능을 지워도 제품이 빌드되고 게이트를 통과한다"는 확인을 제품 기능에는 할 수 없다. 오류 문구는 CI 기준선 파일을 가리켜 기능 작성자가 원인을 찾기 어렵다 |
| 심각도·우선순위 | Medium · P2 — 실행 중인 제품에는 영향이 없다. 문서화된 검증 단계가 모든 제품 기능에서 막히고, 고치는 비용은 한 줄이다 |
| 통제·증거 | 목표 M3(제품 기능 제거를 게이트가 확인). 확인 M0(제품 기능 경로를 실행하는 검사 없음: `--feature=`를 쓰는 테스트는 없는 ID 거부뿐, `tests/unit/feature-removal-argument.test.ts:12`) · E3(실행) |
| 확실성과 남은 가정 | 원인 줄과 실패는 실행으로 확인했다. 그 줄만 고치면 같은 드릴이 13개 검사로 통과한다(6.3절). 참조 기능 기본 드릴(FE-GATE-020)은 `ciScripts`가 10개라 이 길을 타지 않는다. 그래서 게이트가 통과한다 |
| 결정의 근거 | 적용 제외 — 빈 목록을 다루지 못한 단순 결함이다 |
| 이해 비용 | 기능 작성자가 `scripts/lib/removal-fixture.ts`와 CI 기준선 스키마를 읽어야 원인을 안다 |
| 최소 개선 방향 | 사유를 빈 목록에서도 공백 없이 만든다(예: `... || "no feature-owned scripts"`). `test:feature-scaffold`가 생성한 기능에 `--feature=<생성 ID>` 드릴을 한 번 돌리게 해서 이 길을 게이트에 넣는다 |
| 대안 비교 | 적용 제외 — 단순 결함 수정. 게이트에 넣는 범위만 고른다: 생성 기능 드릴을 FE-GATE-020에 더하면 실행 시간이 드릴 한 번만큼 는다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 한 줄. 게이트에 넣으면 merge 단계가 드릴 한 번(이 환경에서 약 4분)만큼 길어진다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | `create:feature`로 만든 기능에서 `test:sample-removal -- --feature=<id>`가 rc=0이고, 이 경로를 머지 게이트가 돈다 |
| 검증 방법 | 6.3절 실험을 다시 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-03 공유 접근성 e2e spec이 기능마다 템플릿 파일 수정을 요구하고, Envelope 기능에는 오류 화면만 검사한다 — 생성 명령 참조 문서는 빈 상태를 그린다고 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 동작이 반대) + 검사 공백 |
| 관련 관점 | 10, 21, 25, 27, 9, 20 |
| 근거 | ① `tests/e2e/accessibility.spec.ts:24-38`은 등록된 모든 라우트를 열고, 경로 파라미터는 `:resourceId`만 바꾸며, 보호 라우트의 모든 API에 맨 배열 `[]`로 답한다. ② 매뉴얼은 `:resourceId`가 아닌 파라미터마다 이 템플릿 파일에 `.replace(...)`를 이으라고 한다(01:392-405, 03:104, `starter-experience.md:188`). 기능을 지울 때 그 줄은 손으로 지우고 제거 드릴이 잡지 못한다(03:144-145, 01:608). ③ Envelope operation은 맨 배열을 `ENVELOPE_MISMATCH`로 거부한다. 생성된 gateway 테스트가 이것을 단정한다("refuses a bare DTO"). E-8 a: 공지 목록 페이지에 맨 `[]`를 주자 화면은 `data-message-key="error.envelope_mismatch"` 오류이고 빈 상태 heading이 없었다. 그래서 생성한 기능은 목록·상세 모두 오류 화면이 axe 대상이다. ④ `docs/manual/reference/create-feature.md:76`은 "빈 배열 응답은 공유 빈 상태 화면으로 그린다. `accessibility.spec.ts`가 모든 API에 `[]`를 답하기 때문이다"라고 적는다. 01:403은 상세 페이지만 실패 상태라고 적는다. 1101 README 14.6 "남은 것"이 이 사실을 적었고 고치지 않았다 |
| 발생 조건 | `create:feature`로 만든 기능(모두 Envelope)이 하나라도 있을 때. 경로 파라미터 이름이 `:resourceId`가 아닌 기능을 더할 때 |
| 영향 | 자동 접근성 검사가 생성 기능의 실제 내용(목록 항목, 상세 본문, 폼)을 한 번도 보지 않는다. 오류 화면이 통과하면 그 라우트는 "검사됨"으로 남는다. 템플릿 소유 spec이 기능마다 고쳐져 동기화 충돌 자리가 되고, 지운 기능의 치환 줄이 남는다. 릴리스 전 사람 서명(FE-GATE-028)이 마지막 방어선이다 |
| 심각도·우선순위 | Medium · P2 — 사람 검토가 남아 있어 차단 항목은 아니다. 자동 검사의 범위를 문서가 반대로 설명하고, 생성 기능 전부에 걸린다 |
| 통제·증거 | 목표 M3(생성 기능의 성공 화면을 axe가 검사). 확인 M1(01:403의 한 줄) · E2(vitest 탐침 E-8 a와 생성 gateway 테스트). Playwright는 돌리지 않았다 |
| 확실성과 남은 가정 | spec이 보내는 본문(맨 `[]`)과 페이지의 반응은 같은 실행기·같은 화면으로 vitest에서 확인했다. 실제 브라우저에서 같은 화면이 나오는지는 미확인이다. 11 영역(브라우저 테스트)과 겹칠 수 있다 |
| 결정의 근거 | 확인한 사실: spec은 "기능 데이터는 이 spec의 대상이 아니다"는 의도로 썼다(`accessibility.spec.ts:35` 주석). 그때는 기능이 DTO 모양이라 `[]`가 빈 상태였다. Envelope 도입(`7db32e1`) 뒤 전제가 깨졌다. 리뷰어 추론: 파라미터 치환과 응답을 descriptor·라우트 표에서 만들면 기능별 수정이 사라진다 |
| 이해 비용 | 기능 작성자가 이 spec의 치환 규칙과 응답 규칙을 알아야 하고, 지울 때도 기억해야 한다 |
| 최소 개선 방향 | (1) spec이 API 응답을 설치된 HTTP 계약에서 만든다: Envelope operation에는 `{ success: true, data: [] }`. (2) 경로 파라미터는 모든 `:name`을 같은 고정 값으로 바꾼다(`replace(/:([A-Za-z]+)/g, "a11y-1")`). (3) `create-feature.md:76`을 고친다 |
| 대안 비교 | (a) 문서만 고친다: 싸다. 검사 공백은 남는다. (b) 위 (1)(2): 기능별 수정이 없어지고 목록의 빈 상태를 검사한다. 상세는 `[]`가 객체 스키마에 맞지 않아 여전히 실패 화면이다 — 상세용 고정 본문은 스키마에서 만들 수 없으므로 h1만 보는 지금 동작을 유지한다. (c) 기능 테스트(jsdom)에 axe를 넣는다: 브라우저 렌더와 다르다. (b) 권장 |
| 단순화의 보존 조건 | 보호 라우트는 로그인 뒤 검사한다. 지금 통과하는 라우트(플랫폼·참조)의 검사 결과가 같다 |
| 비용·부작용 | spec 수십 줄. e2e 시간은 같다 |
| 재검토 조건 | 기능 데이터가 없으면 그릴 수 없는 보호 페이지가 늘어날 때. 백엔드가 Envelope 밖 모양을 다시 허용할 때 |
| 완료 기준 | 생성 기능을 더해도 spec 파일이 바뀌지 않는다. 생성 기능 목록 라우트에서 axe가 빈 상태 화면을 본다. `create-feature.md:76`이 동작과 맞다 |
| 검증 방법 | `create:feature` 뒤 `test:a11y`를 돌리고 목록 라우트의 스냅샷에 빈 상태 heading이 있는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1101 README 14.6 "남은 것"에서 이어짐) |
| 재검증 결과 | 해당 없음 |
### 16-04 스키마 메타 행(`<base>-schema-metadata.ts`)이 zod·descriptor에서 알 수 있는 사실을 손으로 다시 적고, 틀려도 아무 검사가 잡지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 3, 17, 22, 21, 4, 23 |
| 근거 | ① 행 모양: `SchemaDefinition`은 `schemaId`, `boundary`, `owner`, `runtime`, `schemaVersion?`, `direction?`, `unknownFieldPolicy?`다(`src/contracts/schema-registry.ts:4-17`). 생성 뼈대는 스키마마다 7칸을 쓴다. 공지 기능은 스키마 5개에 46줄이었다. ② 거버넌스: FE-REG-SCHEMA는 `schemaId`·`boundary`·`owner`·`runtime`만 요구하고, `boundary`를 breaking 칸으로 본다(`config/contracts/registry-governance.json`의 FE-REG-SCHEMA). 그 값이 실제 쓰임과 맞는지는 보지 않는다. ③ 실행(E-4): `NoticeCreateCommand`에 `unknownFieldPolicy: "STRIP_UNKNOWN"`(zod는 `.strict()`), `NoticeListPayload`에 `direction: "REQUEST"`, 응답 스키마 둘에 `boundary: "api-request"`를 적었다. `check:types` rc=0, `check:registries` `PASS; compatibility=additive`, 기능 테스트 17/17. ④ 같은 스키마 ID `NoticeParams`를 여섯 곳에 적었다: `zodValidator` 첫 인자, 메타 키, 메타 `schemaId`, 라우트 `paramsSchema`, `routeRuntimeContracts.paramsCodec`, codec 표 키. 참조 관계는 검사된다(없는 ID면 `check:registries`, codec 표 누락은 실행 때 `Unregistered route codec`). 설명 칸은 검사되지 않는다 |
| 발생 조건 | 스키마를 더하거나, 요청 스키마를 strict↔strip으로 바꾸거나, 스키마를 다른 자리(입력→응답)로 옮길 때 |
| 영향 | 승인된 기준선의 FE-REG-SCHEMA 행이 실제 검증과 반대를 말할 수 있다. 리뷰어가 기준선 diff로 계약을 판단하면 틀린 사실을 승인한다. 런타임 동작은 zod가 정하므로 사용자 피해는 없다 |
| 심각도·우선순위 | Low · P2 — 런타임 결함은 아니다. 기능마다 반복되는 수동 칸이고 자동으로 만들 수 있다 |
| 통제·증거 | 목표 M4(행을 실제 쓰임에서 만든다) 또는 M3. 확인 M2(참조 관계만 검사) · E3(E-4) |
| 확실성과 남은 가정 | 기준선·거버넌스 밖에서 `direction`·`unknownFieldPolicy`를 읽는 코드는 찾지 못했다(`git grep`). 다운스트림이 이 행을 문서로 쓰는지는 보지 않았다. 07 영역(계약)과 겹칠 수 있다 |
| 결정의 근거 | 확인한 사실: operation은 `projectApiOperationRows`로 descriptor에서 뽑는다(`src/contracts/api-operations.ts:40-60`). 스키마 행은 같은 정리를 받지 않았다. 39.5 표 기준으로 `direction`·`unknownFieldPolicy`는 "어느 도구도 실제와 대조하지 않고 개발자가 맞추는" 칸, `boundary`는 "검사가 선언값만 다시 읽는" 칸이다. 리뷰어 추론: `boundary`는 검증기가 어느 자리(입력·응답·라우트 params·search)에 쓰였는지로 정해지고, `direction`은 `boundary`에서, `owner`는 기능 ID에서 나온다 |
| 이해 비용 | 기능 작성자가 스키마마다 다섯 boundary 값의 뜻을 배우고 고른다(매뉴얼 01:233-239). 틀려도 신호가 없다 |
| 최소 개선 방향 | FE-REG-SCHEMA 행을 descriptor·라우트 계약에서 뽑는 투영 함수를 둔다: `boundary`는 쓰인 자리, `direction`은 `boundary`, `owner`는 기능 ID. 기능은 `schemaVersion`처럼 따로 정할 값만 덮어쓴다. `unknownFieldPolicy`는 zod 객체 모드에서 읽거나 칸을 지운다 |
| 대안 비교 | (a) 현상 유지. (b) 투영 + 덮어쓰기: 메타 파일 대부분이 사라진다. 한 스키마가 두 자리(라우트 search와 GET 입력)에 쓰이는 경우의 규칙(`route-search-api-request`)을 투영이 알아야 한다. (c) 메타는 두고 단위 테스트가 쓰임과 대조: 칸은 남고 불일치만 잡는다. 비용이 가장 작다. (b) 권장, 빠르게 막으려면 (c) 먼저 |
| 단순화의 보존 조건 | FE-REG-SCHEMA 행의 `schemaId`·`boundary`·`owner`·`runtime` 값이 지금 기준선과 같다(참조 기능 기준). 라우트 스키마 참조 검사(`paramsSchema references unknown FE-REG-SCHEMA`)는 남는다 |
| 비용·부작용 | (b)는 투영 함수와 생성 뼈대·참조 기능 수정. 기준선의 `owner` 문자열이 바뀌면 재승인이 필요하다 |
| 재검토 조건 | 스키마가 zod 밖(protobuf 등)에서 오거나, 한 스키마를 여러 기능이 공유할 때 |
| 완료 기준 | E-4의 세 변이가 각각 검사 실패를 낸다(또는 변이할 칸이 없다) |
| 검증 방법 | E-4를 다시 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-05 뮤테이션 정책의 `operationId`가 자유 문자열이라 오타가 타입·레지스트리를 통과하고, 작성 화면이 요청도 보내지 않고 "요청을 처리할 수 없습니다"로 멈춘다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(검사 공백) |
| 관련 관점 | 21, 3, 8, 24, 22 |
| 근거 | `BoundMutation.operationId`는 `string`이다(`src/contracts/server-state.ts:261-264`). 조정자는 이 값으로 intent를 만든다(`src/presentation/adapters/query/application-query.ts:350-351, 582-587`). 실행기는 `intent.operationId`가 descriptor의 operation ID와 다르면 보내기 전에 `MISSING_IDEMPOTENCY_KEY` 위반으로 거부한다(`src/adapters/http/http-execution-v3.ts:475-481, 739-742`). 실행(E-2): `"NOTICE_CREATE"`를 `"NOTICE_CREAT"`로 바꾸자 `check:types` rc=0, `check:registries` rc=0, gateway 테스트(직접 intent를 만든다) 통과. 라우터를 거치는 폼 테스트 2건만 실패했고 화면은 `error.unknown_client_failure`("요청을 처리할 수 없습니다")였다. 요청은 나가지 않았다. 매뉴얼 7단계는 정책 칸을 나열하지만 이 값이 descriptor와 같아야 한다고 적지 않는다. "못 잡음"에는 쿼리 쪽만 있다(01:454) |
| 발생 조건 | 작성·수정 뮤테이션을 손으로 더할 때. 참조 기능 정책을 복사해 이름을 바꿀 때 |
| 영향 | 작성 화면이 항상 실패한다. 오류 문구와 위반 이름(`MISSING_IDEMPOTENCY_KEY`)이 진짜 원인(operation ID 불일치)을 가리키지 않는다. 안전하게 실패한다(요청 0건) |
| 심각도·우선순위 | Low · P2 — 데이터 위험이 없고 첫 수동 실행에서 드러난다. 고치는 비용이 작다 |
| 통제·증거 | 목표 M4(descriptor에서 값을 받는다). 확인 M2(실행 때 거부) · E3(E-2) |
| 확실성과 남은 가정 | 실행으로 확인했다. 위반 이름이 진단 기록에 어떻게 남는지는 보지 않았다 |
| 결정의 근거 | 적용 제외 — 값을 상수에서 받는 단순 수정이다 |
| 이해 비용 | 화면 오류에서 원인을 찾으려면 실행기의 intent 검증 코드를 읽어야 한다 |
| 최소 개선 방향 | 정책에 `operationId: NOTICE_CREATE_CONTRACT.contract.operationId`처럼 descriptor 상수를 쓰게 한다(참조 기능 `use-reference-feature.ts:56`, 매뉴얼 7단계 예시). 더 나아가 뮤테이션을 묶는 함수가 `FeatureHttpBinding`의 operation 키 타입을 받게 한다. 위반 이름을 `INTENT_OPERATION_MISMATCH`처럼 원인대로 나눈다 |
| 대안 비교 | 적용 제외 — 단순 결함 수정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 참조 기능·매뉴얼 한 줄씩. 위반 이름을 나누면 진단 키가 하나 는다 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | E-2의 오타가 `check:types`에서 실패하거나, 실패 문구가 operation ID 불일치를 말한다 |
| 검증 방법 | E-2를 다시 한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-06 기능 작성자가 반드시 채우는 칸 중 화면·실행이 읽지 않는 칸이 있다 — 쿼리의 `operationId`·`owner`, 뮤테이션의 `owner`, 라우트 계약의 `title`·`navigationLabel`
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 4, 22, 23, 24, 9 |
| 근거 | ① `QueryDefinition`은 `operationId`·`owner`를 필수로 받지만(`src/contracts/server-state.ts:173-189`) `bindQuery`가 돌려주는 객체에 둘 다 없다(`:212-230`). 이 값을 읽는 곳을 `src`에서 찾지 못했다(`git grep`). 매뉴얼은 이 칸을 "오타를 못 잡는다"는 위험으로 적는데(01:454, `reference/patterns.md:95`), 실제로는 값이 아무 효과도 없다. ② `BoundMutation.owner`도 조정자가 읽지 않는다(`application-query.ts`에서 `owner`는 QueryClient 소유자 뜻으로만 쓰인다). ③ 라우트 계약의 `title`·`navigationLabel`: 화면은 catalog `route.<ID>.title`·`.navigation`만 읽는다(`app-router.tsx:92, 183`, `app-shell.tsx:216`). 계약 값은 FE-REG-ROUTE 기준선 행과 `scripts/test-performance.ts:47`에만 간다. 생성 뼈대는 이 두 칸을 영어 제목으로 채운다(`scripts/create-feature.ts:493`). 실험에서 계약에는 "Notice", 화면에는 catalog의 "공지"가 나왔다. 참조 기능 계약의 `title`을 바꾸면 `check:registries`가 `compatibility=behavior-change`로 분류한다(E-7) |
| 발생 조건 | 기능 작성자가 쿼리·뮤테이션·라우트를 더할 때마다 |
| 영향 | 라우트 하나에 이름을 여섯 곳(계약 2, locale마다 catalog 2)에 쓴다. 화면에 나오지 않는 값을 고치면 레지스트리 변경으로 분류된다. 쿼리·뮤테이션 정책에 효과 없는 칸 셋이 있어 "이 칸이 무엇을 바꾸는가"를 묻게 한다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 해당 없음(불필요 칸) · E1(정적), E3(라우트 제목 분류) |
| 확실성과 남은 가정 | 읽는 곳이 없다는 것은 `src`·`scripts` 검색 결과다. 다운스트림이 이 값을 진단에 쓰는지는 보지 않았다 |
| 결정의 근거 | 확인한 사실: 0929/08-06 뒤 화면 문구는 catalog로 모였고 계약 칸은 그대로 남았다. 리뷰어 추론: 쿼리의 `operationId`는 "쿼리는 operation을 가리킨다"는 의도로 보이나 연결이 없다. 칸을 연결하거나 지우는 둘 중 하나가 일관된 상태다 |
| 이해 비용 | 기능 작성자가 칸 넷의 효과를 코드에서 확인해야 한다. 매뉴얼은 위험으로 설명해 오히려 신경 쓰게 한다 |
| 최소 개선 방향 | ① 쿼리 `operationId`는 descriptor 상수로 받고 진단 이름표로 실제로 싣거나, 칸을 지운다. ② `owner` 두 칸은 지우거나 진단에 싣는다. ③ 라우트 계약 `title`·`navigationLabel`은 기준선 행을 ko-KR catalog에서 만들고 계약 칸은 지운다. 메뉴 노출은 이미 `navigationOrder`가 정한다(`src/features/installed-feature-contracts.ts:105`) |
| 대안 비교 | (a) 현상 유지 + 매뉴얼에 "효과 없음" 표시: 가장 싸다. (b) 지우기: 칸이 줄고 기준선 재승인이 한 번 필요하다. (c) 연결하기(진단 이름표): 칸이 의미를 얻는다. 쿼리 `operationId`는 (c), `owner`·라우트 제목은 (b) 권장 |
| 단순화의 보존 조건 | 메뉴 순서·노출, 문서 제목(`route.documentTitle`), 기준선의 라우트 행 키가 지금과 같다 |
| 비용·부작용 | (b)는 기준선 재승인과 다운스트림 이행. 생성 뼈대 수정 |
| 재검토 조건 | 진단에 쿼리 단위 operation 이름표가 필요해질 때 |
| 완료 기준 | 기능 작성자가 채우는 칸 중 효과 없는 칸이 0이다 |
| 검증 방법 | 칸마다 값을 바꿔 화면·진단·레지스트리 중 하나가 바뀌는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-07 짝 백엔드에 KEYED 쓰기를 붙이는 값 넷을 매뉴얼이 정해 주지 않는다 — 호출 문맥의 `intent`, `retryBudget`, `classifyStatus`, `operationIdentityField`
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 4, 20, 3, 17, 19 |
| 근거 | 실험 B1~B4(6.2절). ① `intent`: 생성 뼈대의 호출 문맥은 `{ signal? }`뿐이다(`scripts/create-feature.ts:746`). KEYED 쓰기는 input → gateway → binding까지 `intent?: MutationIntent`를 넘겨야 한다(`src/adapters/http/feature-http-binding.ts:71`). 매뉴얼 4·5·7단계에 이 말이 없다. 빠뜨리면 실행기가 보내기 전에 거부한다(`http-execution-v3.ts:458-461`) — 안전하지만 타입은 잡지 않는다. ② `retryBudget`: 02:90은 짝 백엔드의 503 `IDEMPOTENCY_UNAVAILABLE`을 "`retryBudget` 안에서 같은 키로 다시 보낸다"고 하고, 02:91은 "참조 기능은 `retryBudget: 0`"이라고 한다. 0이면 백엔드가 요구하는 같은 키 재전송이 자동으로 일어나지 않고 결과 불명 화면으로 간다. 실제 상한은 min(`retryBudget`, 앱 `MAX_RETRY_ATTEMPTS`, 하드 상한)이다(`http-execution-v3.ts:895-899`). 생성 테스트 하네스는 `maxRetryAttempts: 0`, 페이지 테스트 설정은 `MAX_RETRY_ATTEMPTS: 0`이다(`scripts/create-feature.ts:1192, 1045`). 실험에서 `retryBudget: 1`로 적은 재전송 테스트가 하네스 값 때문에 실패했고, 2로 바꾸자 통과했다. ③ `classifyStatus`(401·403·429): 02 §4는 "서버가 보장하면 `NOT_APPLIED`"라고 하지만 짝 백엔드가 무엇을 보장하는지는 어느 문서에도 없다(백엔드 `http-contract.md`에 해당 표 없음). ④ `operationIdentityField`: 필수라고만 적혀 있고(02:91) 실행기는 읽지 않는다(1101/07-07 남음) |
| 발생 조건 | 짝 백엔드 KEYED 쓰기를 처음 만드는 기능마다 |
| 영향 | 기능 작성자가 참조 기능(짝 백엔드가 아닌 모양)과 실행기 코드를 읽고 값을 정한다. 참조 값을 그대로 쓰면(`retryBudget: 0`) 503 실행 전 거절이 결과 불명 화면이 된다. 같은 키로 다시 보내므로 정확성은 지켜진다 |
| 심각도·우선순위 | Low · P2 — 정확성 위험은 없다. 사용자 목표의 기본 경로에서 매번 드는 판단 비용이다 |
| 통제·증거 | 목표 M1(값과 이유가 매뉴얼에 있다) 또는 생성 뼈대. 확인 M0(해당 문장 없음) · E3(실험 B1~B4) |
| 확실성과 남은 가정 | 짝 백엔드가 401·403·429를 실행 전에 거절하는지는 백엔드 코드를 보지 않아 미확인이다. 07 영역(1101/07-07)과 ④가 겹친다 |
| 결정의 근거 | 리뷰어 추론: 이 넷은 기능마다 다른 결정이 아니라 "짝 백엔드 KEYED 쓰기"라는 한 경우의 고정값이다. 그래서 표 한 줄이나 생성 뼈대로 끝난다 |
| 이해 비용 | 실험에서 약 7분(B1~B4). 사람이라면 실행기 코드를 읽는 시간이 더 든다 |
| 최소 개선 방향 | (1) 02 §3에 "짝 백엔드 KEYED 쓰기 descriptor" 표: `retryBudget: 1`(이유: 503 `IDEMPOTENCY_UNAVAILABLE` 한 번 재전송), `classifyStatus`의 판단(백엔드 확인 전에는 생략 = `MAYBE_APPLIED`), `operationIdentityField`의 뜻(또는 칸 삭제, 07 영역). (2) 01 4단계에 "KEYED 쓰기는 호출 문맥에 `intent`를 넘긴다". (3) 생성 하네스의 `maxRetryAttempts`를 앱 기본값(2, `config/runtime/*.json`)과 맞춘다. (4) 5.3절의 쓰기 slice 생성이 생기면 (1)(2)는 뼈대가 대신한다 |
| 대안 비교 | (a) 문서만: 싸다. 값은 여전히 손으로 옮긴다. (b) 생성 명령 쓰기 slice: 값이 테스트와 함께 생성된다. 5.3절에서 비교 |
| 단순화의 보존 조건 | KEYED 쓰기의 "응답 잃은 뒤 자동 재전송 금지"(02:90)와 "결과 불명이면 같은 키"는 그대로다 |
| 비용·부작용 | 문서 몇 줄, 하네스 숫자 하나 |
| 재검토 조건 | 백엔드가 멱등성 응답 표를 바꿀 때(`http-contract.md` §2) |
| 완료 기준 | 매뉴얼만 보고 KEYED 쓰기를 만들 때 실행기 코드를 열지 않는다 |
| 검증 방법 | 6절 실험의 3단계를 다른 사람이 다시 하고 B1~B4가 나오는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-08 기능 추가 경로 문서의 낡은 문장 (09-10·14-05에 없는 것)
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(설명이 코드와 다름) |
| 관련 관점 | 9, 20, 24, 10 |
| 근거 | ① "테스트 2개"(01:35, `reference/create-feature.md:60-63`) — 생성 명령은 3개를 만든다(`<base>-http-gateway.test.ts` 포함, 실험 출력). ② "폼이면 서버 422 오류를 받을 필드"(01:469) — 짝 백엔드의 필드 검증은 400 `VALIDATION_FAILED`다(02:143). 공유 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`(`VALIDATION_REJECTED` code)만 있고(`tests/mocks/handlers/http-scenarios.ts:118-121`), Envelope 모드에서 그것은 결과 불명이다. 실험 E-9에서 400 필드 오류는 필드에 붙고 저장 버튼이 다시 켜졌다 — 동작은 맞고 문장만 낡았다. ③ "`tests/architecture/context-route-roots.test.ts`가 이것을 실행한다"(01:71) — 이 테스트는 fixture만 쓴다(`context-route-roots.test.ts:3-6`). E-5에서 설치된 기능의 루트 밖 라우트에도 23건 통과했고, 잡은 것은 앱을 부팅하는 테스트였다. ④ "operation을 적재하는 모든 게이트가 실패한다"(01:267) — E-3에서 실패한 것은 `check:registries`와 테스트뿐이다. ⑤ "`NoRequest` already belongs to the sample"(`starter-experience.md:210`) — `src`에 `NoRequest`가 없다 |
| 발생 조건 | 매뉴얼·정본 표로 기능을 만들거나 실패 원인을 찾을 때 |
| 영향 | 작다. ②는 폼 작성자가 422 시나리오로 테스트를 써서 짝 백엔드에 없는 경우를 검사하게 한다. ③④는 실패를 기다리는 위치를 틀리게 알려 준다 |
| 심각도·우선순위 | Low · P3 |
| 통제·증거 | 목표 M1 / 확인 M0(해당 문장) · E3(실험·변이) |
| 확실성과 남은 가정 | 매뉴얼 전체를 대조하지는 않았다. 실험에서 지나간 문장만 봤다 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다 |
| 이해 비용 | 작다 |
| 최소 개선 방향 | 다섯 문장을 고친다. ②는 "짝 백엔드는 400 `VALIDATION_FAILED` + 필드 목록"으로 쓰고, 공유 시나리오에 그 경우(`validation-400`)를 더하는 것을 검토한다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문장 5개. 시나리오 추가는 `tests/integration/http-scenario-catalog.test.ts`와 함께 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 다섯 문장이 코드와 맞다 |
| 검증 방법 | 문장마다 해당 변이(E-3, E-5)나 생성 출력과 대조 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
## 4. 28개 관점 판정 (36.2)
판정: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 07·09. 공지 기능은 도메인 규칙이 없어 `domain/`을 만들지 않았다(매뉴얼 2단계) | — | E1 | > — 참조 도메인 불변식은 생성 함수에 있다 |
| **2** | **구조적 성숙도** | 적용(깊게) | M4 / M3 | E3 | **P** — 기능 경계 규칙 5개가 생성 기능에도 그대로 동작했다. `contracts/`와 다섯 폴더 밖 폴더를 거친 어댑터 접근은 여전히 통과한다(E-6, 1101/16-06·12-03 남음) |
| **3** | **변경 용이성** | 적용(깊게) | M3 / M2 | E3 | **P** — 3라우트 기능을 추적 파일 수정 0건으로 넣었다. 같은 사실을 손으로 다시 적는 칸이 남았다(16-01, 16-04, 16-05, 16-06) |
| **4** | **인지 부하** | 적용(깊게) | M1 / M1 | E3 | **P** — 막힘 6(지난 12 → 5 → 6). 매뉴얼 링크가 예제로 바로 데려간다. KEYED 쓰기 값 넷은 실행기 코드를 읽어야 정한다(16-07). 효과 없는 칸이 넷(16-06) |
| 5 | 위험 가시성 | 적용 | M2 / M2 | E3 | P — 위험한 실수는 대부분 안전하게 멈춘다(intent 없는 KEYED는 요청 0건). Envelope 누락은 아무 신호가 없다(16-01) |
| 6 | 실패 성숙도 | > 03·07. 이 영역은 기능 쪽 연결만 확인 | — | E3 | > — 409 처리 중 → 같은 키 재전송, 400 필드 오류 → 필드 표시·재저장, 503 실행 전 거절 → 같은 키 1회 재전송이 공지 기능에서 동작했다 |
| 7 | 운영 성숙도 | - 이 영역 밖 | — | — | - |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E3 | P — 루트 밖 라우트·a11y 기록 누락·인증 프로필 오타는 ID를 말한다(테스트 출력). `check:registries`는 조립 원인을 버린다(14-06). 뮤테이션 ID 오타는 원인 없는 화면 문구로 끝난다(16-05). 제거 드릴 실패는 CI 기준선을 가리킨다(16-02) |
| **9** | **유지보수 성숙도** | 적용(깊게) | M1 / M1 | E1 | **P** — 갈라진 사본(경계 두 벌, `TelemetryPort` 둘, `application/result.ts`)이 남았다(1101/16-05). 생성 명령 템플릿 1,468줄과 참조 기능이 기능 모양의 두 원본이다. FE-GATE-020이 컴파일 drift는 잡고, 뜻의 drift(Envelope 여부, 재시도 값)는 잡지 않는다. 낡은 문장(16-08, 09-10, 14-05) |
| 10 | 테스트 성숙도 | 적용 | M3 / M2 | E3 | P — 생성 뼈대가 손글씨 백엔드 본문 테스트를 준다(좋음). MSW 시나리오가 descriptor를 따라 답해 선언 실수를 못 잡는다(16-01). 접근성 e2e가 생성 기능의 오류 화면만 본다(16-03). 제품 기능 제거 경로를 도는 테스트가 없다(16-02). 무관한 테스트 3,201건이 깨지지 않았다 |
| 11 | 데이터 성숙도 | > 05 | — | — | > |
| 12 | 동시성 성숙도 | > 03 | — | — | > — 생성 뮤테이션 정책은 `REJECT_WHILE_ACTIVE` |
| 13 | 확장성 | 적용(기능 수 축) | M3 / M3 | E3 | P — 3라우트 기능 하나가 초기 JS +921 B(1 KiB 안). 남은 여유 2,031 B는 같은 모양 기능 약 두 개분이다(6.3절, 예산 판단은 13·15 영역). context당 기능 예산 20 |
| 14 | 성능 성숙도 | 적용(번들) | M3 / M3 | E3 | P — `check:bundle` PASS 202,769 / 204,800 B. 기능 페이지는 지연 청크이고 초기 증가는 선언·문구분이다 |
| 15 | 보안 성숙도 | > 03·13 | — | E3 | > — 없는 인증 프로필은 조립이 거부한다(E-3) |
| 16 | 의존성 성숙도 | > 12·13 | — | — | > |
| 17 | API / Contract | 적용 | M4 / M3 | E3 | P — operation은 descriptor 한 곳, FE-REG-API는 투영, 추가는 additive. Envelope는 operation마다(16-01). 스키마 메타 설명 칸은 검사 없음(16-04) |
| 18 | 배포 성숙도 | > 13. 자리표시자 계약 신원의 승인 거절은 실행하지 않았다 | — | E0 | > |
| 19 | 설정 성숙도 | 적용(일부) | M1 / M0 | E3 | P — 앱 `MAX_RETRY_ATTEMPTS`가 descriptor `retryBudget`을 덮는다는 사실이 기능 문서에 없다(16-07) |
| 20 | 개발자 경험 | 적용 | M3 / M2 | E3 | P — `create:feature` + 매뉴얼로 약 8분에 완성. 매뉴얼 밖 판단 4건(16-07). 문서화된 제거 확인 명령이 제품 기능에서 동작하지 않는다(16-02) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 전역 ID 중복·루트 밖 라우트·a11y 기록·인증 프로필은 잡는다. Envelope 누락(16-01), 메타 설명 칸(16-04), 뮤테이션 operation ID(16-05), `contracts/` 우회(12-03)는 통과한다 |
| **22** | **추상화 성숙도** | 적용(깊게) | M3 / M2 | E3 | **P** — descriptor + binding은 깊다: 작성자는 표를 쓰고 재시도·멱등 키·Envelope 해석을 얻는다. 메타·정책 칸은 얕다: 다른 곳에서 알 수 있는 값을 다시 받고(16-04) 읽지 않는 칸이 있다(16-06) |
| **23** | **일관성** | 적용(깊게) | M1 / M1 | E1 | **P** — 기능 모양의 두 원본이 응답 모양에서 갈린다(참조 problem details, 생성 Envelope, 5.3). 라우트 이름이 계약·catalog 두 곳(16-06). 뷰 타입·문구가 `contracts/`에 있는 배치를 생성 뼈대가 그대로 퍼뜨린다(1101/16-06) |
| **24** | **네이밍 / 의미** | 적용(깊게) | M1 / M1 | E3 | **P** — `MISSING_IDEMPOTENCY_KEY`가 operation ID 불일치에도 쓰인다(16-05). `operationIdentityField`의 뜻이 없다(16-07). `FeatureBoundary`/`FeatureErrorBoundary`, `TelemetryPort` 둘(1101/16-05) |
| 25 | 조직 확장성 | 적용(구조 준비, 팀 1개) | M3 / M3 | E3 | P — 기능 추가에 템플릿 소유 파일 수정이 없다. 예외는 경로 파라미터가 `:resourceId`가 아닐 때의 접근성 spec(16-03) |
| 26 | Ownership | > 14 | — | — | > |
| **27** | **삭제 가능성** | 적용(깊게) | M3 / M0(제품 기능) | E3 | **X(제품 기능)** — 제품 기능의 제거 드릴이 시작 직후 실패한다(16-02). 참조 기능 드릴(FE-GATE-020)은 오케스트레이터 게이트에서 통과한다. 폴더 밖 잔여(a11y 기록, 접근성 spec 치환 줄)는 드릴이 잡지 않고 매뉴얼에 손 목록으로 있다(03:135-148). 원인 한 줄을 고친 실험 결과는 6.3절 |
| 28 | 회복 가능성 | > 06·02 | — | — | > |
집계(이 영역): P 17 · X 1 · > 9 · - 1 · O 0 · ? 0.
## 5. 설계 선택 검토 (41절)
### 5.1 API는 descriptor 한 곳에 적고 FE-REG-API를 투영하되, 스키마 메타는 따로 손으로 적는다
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 기능 작성자가 API 하나를 한 번만 적는다. 레지스트리 게이트는 그 API를 계속 거버넌스한다. 추가는 기준선 승인 없이 통과한다 |
| 2. 지킬 성질 | 실행되는 계약과 승인된 레지스트리 행이 갈라지지 않는다 |
| 3. 현재 보장 | operation: `projectApiOperationRows`(`src/contracts/api-operations.ts:40-60`)가 descriptor에서 행을 뽑으므로 갈라질 수 없다. 실험에서 3 operation이 additive로 들어갔다. 스키마: 메타 행은 손으로 쓰고, 참조 관계(`requestSchema references unknown FE-REG-SCHEMA`)만 검사된다. 설명 칸(`boundary`·`direction`·`unknownFieldPolicy`)은 실행과 갈라질 수 있다(E-4, 16-04) |
| 4. 대안 | (a) 지금. (b) 스키마 행도 투영(쓰임에서 `boundary`, 기능 ID에서 `owner`). (c) 메타 행을 지우고 FE-REG-SCHEMA를 descriptor 행의 일부로. (d) V2처럼 둘 다 손으로 + 일치 테스트 |
| 5. 득실 | (a) 기능마다 스키마당 7칸. (b) 메타 파일이 거의 사라지고, 투영 함수가 `route-search-api-request` 같은 겹친 쓰임 규칙을 알아야 한다. (c) 라우트 전용 스키마(params·search)의 자리가 없다. (d)는 지운 방식이다 |
| 6. 선택 이유 | operation 쪽 선택은 타당하고 효과가 실험으로 보였다. 스키마 쪽은 같은 이유(갈라지지 않음)가 적용되는데 같은 정리를 받지 않았다. 확인한 조건에서는 (b)가 일관된다 |
| 7. 재검토 조건 | 스키마가 zod 밖에서 오거나 기능끼리 스키마를 공유할 때. 외부 계약 패키지가 메타까지 생성하게 될 때 |
### 5.2 Envelope를 operation 단위 선택 칸으로 선언한다 (1101 README 14.6)
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 생성 기능이 짝 백엔드 Envelope를 그대로 읽는다. 참조 기능·테스트 계약·recipe(DTO 모양)를 흔들지 않는다. 한 앱이 두 모양의 API를 같이 쓸 수 있다 |
| 2. 지킬 성질 | 각 operation이 실제 서버 응답 모양으로 읽힌다. 틀리면 출시 전에 안다 |
| 3. 현재 보장 | 값이 있으면 정확히 읽는다(공지 기능 gateway 테스트 7건, 페이지 테스트 6건). 값이 없으면 DTO로 읽고, 그 사실을 아무 검사도 의심하지 않는다(E-1). MSW 시나리오는 선언을 따라 답한다 |
| 4. 대안 | (a) operation 선택 칸(지금). (b) operation 필수 칸. (c) 기여 단위 기본값 + operation 덮어쓰기. (d) 앱 전체 한 값(14.6에서 버림). (e) 조립기가 한 기여 안 혼합 거부 |
| 5. 득실 | (a) 기존 코드 무변경, 누락 무신호. (b) tsc가 누락을 잡고, descriptor 약 20곳에 한 줄. (c) 반복 최소, 기본값 출처라는 규칙 하나 추가. (d) 두 모양 혼용 불가, 참조·테스트 fixture 붕괴. (e) 혼합은 막지만 "전부 빠뜨림"은 못 막는다 |
| 6. 선택 이유 | 14.6이 (d)를 버린 이유는 맞다. 그러나 (a)를 고른 이유("기존 descriptor를 건드리지 않는다")는 일회성 이행 비용이고, 감수한 비용(기능마다 무신호 실수 자리)은 계속 남는다. 확인한 조건에서는 (b)가 더 싸다 |
| 7. 재검토 조건 | 짝 백엔드가 아닌 백엔드를 주로 쓰는 다운스트림이 생기면 기본값 논의(c)를 다시 한다 |
### 5.3 참조 기능은 problem details 모양으로 두고, 생성 뼈대만 Envelope로 만든다 — 완성된 예시로 맞는가
09 영역 5.3절이 같은 선택을 검토했다(결함은 09-06). 이 영역은 기능 개발 실험에서 본 사실로 답한다.
| 질문 | 답 |
|---|---|
| 1. 무엇이 필요한가 | 기능 작성자가 사용자 목표의 기본 경로(짝 백엔드)에서 흔한 기능 모양(목록·상세·작성)을 예제를 보며 실수 없이 만든다 |
| 2. 지킬 성질 | 예제를 옮긴 코드가 기본 경로에서 그대로 맞다. 맞지 않는 부분은 옮기기 전에 드러난다 |
| 3. 현재 보장 | 생성 뼈대는 Envelope GET 목록 하나다. 상세 GET·KEYED POST·폼·결과 불명 화면·실패 행동·상태 페이지의 예제는 참조 기능뿐이고 참조 기능은 problem details 모양이다. 옮길 때 모양에 따라 다른 부분: 문제 스키마(옮기면 Envelope 실패 검증이 깨진다, E-8 b), `classifyProblem`의 400·422·409 분기(Envelope에서는 실행기 표가 덮어 죽은 분기가 된다, 02:142), `mapProblem`의 `problem.issues`(Envelope는 `details`), `retryBudget: 0`(16-07), `responseEnvelope` 줄 없음(16-01). 모양과 무관한 부분(폼 페이지 구조, `AsyncSurface` 결과 불명 처리, route codec, 뮤테이션 정책)은 그대로 맞았다. 실험에서 작성 경로 약 400줄(폼 페이지 117줄, 폼 스키마 20줄, 정책·hook, 테스트)을 참조 기능을 보며 손으로 옮겼다 |
| 4. 대안 | (a) 현상 유지 + 매뉴얼의 "짝 백엔드가 아닌 백엔드" 절(01:211-219). (b) 참조 기능을 Envelope로 옮긴다. (c) `create:feature`에 쓰기 slice 선택(예: `--with-create`)을 더해 Envelope 상세 GET·KEYED POST·`FormPage`·결과 불명 화면·같은 키 재전송 테스트를 생성한다. 참조 기능은 problem details 예시로 남긴다 |
| 5. 득실 | (a) 비용 0. 모양별 차이를 사람이 매번 걸러야 한다(이번 실험 B1~B4·E-8 b). (b) 기본 경로의 완성 예시가 생긴다. 참조 기능 테스트 파일들의 MSW 본문, 문제 스키마, `mapProblem`, e2e를 바꾼다. problem details 경로는 예시가 없어진다. 여전히 "복사하지 말라"는 예시라 값을 옮기는 일은 남는다. (c) 값이 생성되고 FE-GATE-020이 생성 결과를 매번 게이트로 돌린다. 생성 템플릿이 커진다(지금 1,468줄). 16-07의 값 넷과 16-01의 누락 자리가 생성 코드로 사라진다 |
| 6. 선택 이유 | 참조 기능은 자기 모양(problem details)에서는 완성된 예시다. 사용자 목표의 기본 경로에서는 "모양과 무관한 화면 패턴"의 예시일 뿐이다. 확인한 조건에서는 (c)가 가장 싸게 기본 경로의 완성 예시를 만들고, 그 예시가 게이트로 지켜진다. 이 영역의 권고는 (c)다 |
| 7. 재검토 조건 | 다운스트림 대부분이 짝 백엔드가 아닌 백엔드를 쓰게 되면 (a)로 충분하다. 생성 템플릿이 2,000줄을 넘거나 slice 선택이 셋 이상으로 늘면 템플릿을 파일로 나누는 일을 먼저 한다 |
## 6. 기능 추가 실험 기록
### 6.1 조건
- worktree `agent-ae89fbafcc2d11556`, `e40684b`. `docs/manual/`과 매뉴얼이 링크한 예제·정본 파일만 보고 진행했다. 매뉴얼이 가리키지 않은 코드를 연 곳은 "막힘"으로 셌다.
- 기능: `notice-feature`(새 context `notice-context`, 루트 `notice/*`). 라우트 `NOTICE_LIST`(`/notice`), `NOTICE_DETAIL`(`/notice/items/:noticeId`), `NOTICE_CREATE`(`/notice/new`). operation `NOTICE_LIST`(GET `/api/notices`), `NOTICE_GET`(GET `/api/notices/{noticeId}`), `NOTICE_CREATE`(POST `/api/notices`, KEYED, `retryBudget: 1`). 셋 다 `responseEnvelope: "ENVELOPE_V1"`, `EXTERNAL_BEARER`, 자리표시자 계약 신원.
- 시간은 에이전트 실행 기준이다. 사람이 하면 코드 읽기 시간이 더 든다.
### 6.2 단계별 기록
| 시각 | 단계(매뉴얼) | 한 일 | 막힘 | 게이트·테스트 |
|---|---|---|---|---|
| 22:57:51 | 1 `create:feature notice-feature` | 파일 20개(기능 16, context 1, 테스트 3)와 a11y 기록 1개 생성, 자리표시자 경고 | 없음. 출력 `Next:`가 정확했다 | 생성 직후 `check:types` rc=0, 기능 테스트 11/11 |
| 22:58 | 3 API 계약 | descriptor 2개 추가, 스키마 4개, 메타 행 4개, `zodValidator` 표 | **B2** `operationIdentityField`에 무엇을 넣는지 없다(02:91). 참조 값 `"idempotencyKey"` 복사(~1분). **B3** KEYED `retryBudget` — 02:90의 "retryBudget 안에서 재전송"과 02:91의 "참조는 0"이 부딪힌다. 1로 정함(~1분, 실행 상한은 아래 10단계에서 다시 막힘). **B4** `classifyStatus` — 짝 백엔드의 401·403·429 보장을 찾을 문서가 없다. 생략(= `MAYBE_APPLIED`)으로 정함(~1분) | — |
| 23:00 | 6 라우트 | 라우트 2개, runtime 계약 2개, 지연 페이지 표, `context-routes.ts`에 `codecs`, codec 표, `useNoticeId` | **B5** codec ID가 스키마 ID와 같아야 하고 codec 표 값이 zod 스키마라는 것은 예제(`reference-route-codecs.ts`)를 보고 알았다(~1분, 매뉴얼이 예제를 가리키므로 작은 막힘) | — |
| 23:00 | 4·5 application·어댑터 | input 메서드 3개, gateway 3개, mapper 2개 | **B1** KEYED 쓰기는 호출 문맥에 `intent`를 넘겨야 한다. 생성 뼈대 문맥은 `{ signal? }`뿐이고 매뉴얼 4·5·7단계에 없다. 참조 `reference-feature-api.ts`와 `feature-http-binding.ts:71`을 읽고 알았다(~2분) | — |
| 23:01 | 7·8 쿼리·뮤테이션·페이지 | 상세 쿼리, 작성 뮤테이션 정책, 목록·상세·작성 페이지, 폼 스키마(서버 한도 상수 공유), 문구 20키×2 | **B6** 매뉴얼 8단계는 "서버 422"를 말하지만 짝 백엔드 필드 검증은 400. 공유 시나리오에 400 필드 오류가 없어 손으로 본문을 적었다(~2분, 16-08 ②) | — |
| 23:02 | 6 a11y 기록 | `NOTICE_DETAIL.md`, `NOTICE_CREATE.md`를 생성 기록에서 복사 | 없음(`global-ids.md:53`에 있음) | `check:types` — 앱 소스 통과, 생성 테스트 7건이 옛 이름으로 실패(예상) |
| 23:03 | 10 테스트 | input 4건, gateway 7건(손글씨 Envelope 본문: 목록·상세·작성 201·intent 없음 거부·409 처리 중·400 필드·503 재전송), 페이지 6건(목록·빈 목록·재시도·상세 열기·409 뒤 같은 키 재전송·400 필드 오류) | **B3(계속)** 503 같은 키 재전송 테스트가 실패했다. 실행 상한이 min(`retryBudget`, `maxRetryAttempts`, 하드 상한)이고 생성 하네스가 `maxRetryAttempts: 0`이다. 실행기 코드를 읽고 하네스를 2로 바꿨다(~2분) | `check:types` rc=0. 기능 테스트 16/17 → 하네스 수정 뒤 17/17 |
| 23:04~23:06 | merge 게이트 | 출력 `Next:` 2번 목록 중 10개 | 없음 | 아래 표 |
| 23:19~23:22 | 회귀 | 기능을 설치한 채 빠른 계층 | 없음 | 76파일 504건, 186파일 2,697건 통과 |
| 23:37 | 11 제거 확인, merge 전 `check:bundle` | `flock` 아래 `build`, `check:bundle`, `test:sample-removal -- --feature=notice-feature` | **막힘(B7, 셈 밖)** 제거 드릴이 CI 기준선 오류로 끝났다(16-02). 매뉴얼로는 풀 수 없다 | `build` rc=0, `check:bundle` PASS 202,769 B, 드릴 rc=1 |
막힘 합계: 기능을 만드는 동안 6건(B1~B6). 매뉴얼에 없는 값을 정한 것 4건(B1~B4), 예제로 풀린 작은 혼동 2건(B5·B6). 막힌 시간 합계 약 10분. 제거 확인 단계의 B7은 매뉴얼 문제가 아니라 도구 결함이라 따로 적었다.
매뉴얼 01 6단계의 접근성 spec 치환 줄(`.replace(":noticeId", ...)`)은 넣지 않았다. 공지 params 스키마가 `":noticeId"` 글자도 받아들여 결과가 같기 때문이다(16-03: 어느 쪽이든 오류 화면을 검사한다).
**게이트 결과(공지 기능 설치, 23:04~23:06)**
| 게이트 | rc | 비고 |
|---|---|---|
| `check:types` | 0 | |
| `lint` | 0 | |
| `check:architecture` | 0 | |
| `check:registries` | 0 | `11 registries PASS; compatibility=additive` |
| `check:i18n` | 0 | |
| `check:design-system` | 0 | |
| `check:diagnostics` | 0 | |
| `verify:documentation` | 0 | `PASS_SCOPED` |
| `check:adapter-inventory` | 0 | |
| `check:ci` | 0 | |
| 기능 테스트 `node scripts/run-vitest.ts run tests/features/notice-feature` | 0 | 3파일 17건 |
**"한 번만 적기" 집계(공지 기능)**
| 사실 | 적은 곳 | 갈라지면 잡는 것 |
|---|---|---|
| method·path·status·재시도·인증·한도 | descriptor 1곳 | 해당 없음(사본 없음) |
| 응답 모양(Envelope) | descriptor마다 1줄 × 3 | 없음(16-01) |
| operation ID `NOTICE_CREATE` | descriptor, binding 표 키, `http.execute` 인자, 뮤테이션 정책 | binding·execute는 tsc, 정책은 실행 때 거부만(16-05) |
| operation ID `NOTICE_LIST`(쿼리) | descriptor, binding, execute, `bindQuery.operationId` | `bindQuery` 값은 아무도 읽지 않는다(16-06) |
| 스키마 ID `NoticeParams` | 6곳 | 참조는 `check:registries`·실행 때 codec 조회. 설명 칸은 없음(16-04) |
| 라우트 경로 | 계약 1곳 | 링크는 `buildRouteUrl` |
| 라우트 이름 | 계약 `title`·`navigationLabel` + catalog 2키 × 2 locale | 계약 값은 화면에 안 나온다(16-06) |
| 서버 길이 한도 | `notice-schemas.ts` 상수 1곳(요청·폼 공유) | 해당 없음 |
### 6.3 번들과 제거 드릴
모두 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock` 아래, 공지 기능이 설치된 이 worktree에서 실행했다.
| 실행 | 결과 |
|---|---|
| `corepack pnpm build` (23:37, 부하 8.3) | rc=0 |
| `corepack pnpm check:bundle` | `Bundle budget: PASS (initial JS 202769 / 204800 gzip bytes)`. 공급망 `LOCAL PASS`, `promotion=FAIL_UNVERIFIED`(로컬) |
| 비교 기준 | 오케스트레이터가 같은 커밋·다른 worktree에서 잰 참조 기능만의 값 201,848 B. 차이 +921 B(3라우트·3operation·문구 40개). `tests/unit/feature-shape-growth.test.ts`의 기능당 1 KiB 안이다. 남은 여유 2,031 B. 이 worktree에서 기준값을 따로 재지는 않았다 |
| `test:sample-removal -- --feature=notice-feature` (그대로) | rc=1, 3초. `TypeError: config/ci/contract-baseline.json invalid: reason: leading/trailing whitespace is forbidden`(16-02) |
| 같은 명령, `scripts/lib/removal-fixture.ts:470` 사유만 빈 목록 대체값으로 고친 실험 | rc=0, 23:42:23~23:46:17(약 4분, 부하 17.9). `notice-feature removal: PASS (13 checks, no fixture IDs)`. 원인은 그 한 줄뿐이고, 사유만 고치면 제품 기능도 제거 드릴을 통과한다. 고친 줄은 실험 뒤 되돌렸다 |
### 6.4 변이 실험
모두 완성한 공지 기능에서 한 군데만 바꾸고 되돌렸다.
| ID | 바꾼 것 | 결과 | 발견 |
|---|---|---|---|
| E-1 | `NOTICE_GET`의 `responseEnvelope` 줄 삭제 | types 0, registries 0, 페이지 테스트 6/6 통과. 손글씨 gateway 테스트 1건만 `SCHEMA_MISMATCH` | 16-01 |
| E-2 | 뮤테이션 정책 `operationId` → `"NOTICE_CREAT"` | types 0, registries 0, 라우터 폼 테스트 2건 실패, 화면 `error.unknown_client_failure`, 요청 0건 | 16-05 |
| E-3 | `NOTICE_GET`의 `authProfileId` → `"EXTERNAL_BEARR"` | `check:registries` 실패(원인 없음, `...removed` 연쇄), 테스트 출력에 `reason: 'notice-feature/NOTICE_GET: unknown authProfileId EXTERNAL_BEARR'`. `check:i18n`·`check:diagnostics`·`verify:documentation`·`check:design-system`·`check:architecture`·`check:types`는 통과 | 14-06, 16-08 ④ |
| E-4 | 메타 `unknownFieldPolicy`·`direction`·`boundary`를 실제와 반대로 | types 0, registries `PASS additive`, 테스트 17/17 | 16-04 |
| E-5 | `NOTICE_DETAIL` 경로를 `/notices/items/:noticeId`(루트 밖)로 | types 0, registries 0, `tests/architecture/context-route-roots.test.ts` 23/23 통과. 앱 모듈이 적재 때 거부해 페이지 테스트·component 6파일 실패 | R-1 고쳐짐, 16-08 ③ |
| E-6 | `presentation → hooks/use-raw-http.ts → src/adapters/http`, `presentation → contracts/notice-reexport-http.ts → 같은 어댑터` | `check:architecture` rc=0, eslint rc=0 | 1101/16-06·12-03 남음 |
| E-7 | a11y 기록 `NOTICE_CREATE.md` 제거 / 참조 계약 `title` 변경 | `verify:documentation`이 route ID를 말하며 실패, FE-GATE-009 `missing record` / `check:registries` `PASS; compatibility=behavior-change` | 1101/14-06 고쳐짐 / 16-06 |
| E-8 | (a) 목록 API가 맨 `[]`(접근성 spec과 같은 본문) (b) 참조 문제 스키마 모양을 공지에 복사 | (a) 화면 `error.envelope_mismatch`, 빈 상태 없음 (b) 손글씨 본문 테스트 4건 실패, MSW 시나리오 폼 테스트는 통과 | 16-03 / 09-06 증거 |
| E-9 | (탐침) 작성 POST에 백엔드 400 `VALIDATION_FAILED` + `details[{field:"title",code:"SIZE"}]` | 제목 필드 `aria-invalid=true`, 문구 "길이나 개수가 허용 범위를 벗어났습니다", 저장 버튼 다시 켜짐, 재전송 버튼 없음 | 강점. 16-08 ② |
### 6.5 실험에서 확인한 강점
- 기능 하나가 템플릿 소유 파일을 건드리지 않는다. 지난 라운드 복사 실험의 폴더 밖 7묶음(governance, 기준선, README route ID, a11y, 인증 프로필, 계약 출처, MSW 카탈로그)이 모두 사라졌다.
- 실수 대부분이 안전하게 멈춘다. intent 없는 KEYED 쓰기와 operation ID가 틀린 intent는 보내기 전에 거부된다. 루트 밖 라우트는 앱 적재 때 거부된다.
- 생성 뼈대의 손글씨 백엔드 본문 테스트가 Envelope 실수를 잡는 유일한 장치이고, 실제로 E-1·E-8 b를 잡았다.
- 짝 백엔드의 멱등성 응답(409 처리 중, 400 필드 검증, 503 실행 전 거절)이 매뉴얼 02 §4 표대로 동작했다.
@@ -0,0 +1,369 @@
# 성숙도 리뷰 — 2026-11-03
> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 대상: `e40684b`. 이 커밋은 두 작업 브랜치를 병합했다. 하나는 V3 Envelope 읽기와 V2 HTTP 경로 삭제를 담은 `claude/happy-easley-233d07` `93c81df`이고, 다른 하나는 지난 리뷰 조치를 담은 `fix/ui-design-audit-2026-11-01`이다. 영역은 지난 리뷰(2026-11-01)의 16개를 그대로 썼다. 영역 에이전트가 격리 worktree에서 병렬로 읽고 실험했다. 이 문서는 오케스트레이터가 결과를 모은 것이다. High 이상과 P1 일부는 코드와 실행으로 다시 확인했다. 리뷰 중 코드는 고치지 않았다.
>
> 계기: 사용자 질문 "V2에만 있던 동작이 없어지면 안 되는 것 아닌가"에 대한 판단과, 그 뒤의 프론트 전체 재리뷰. 그 판단을 이 리뷰로 다시 확인한 결과는 3절에 있다.
## 1. 사용 결정 (36.5-1)
| 용도 | 결정 | 막는 항목 |
|---|---|---|
| 짝 백엔드에 붙는 쓰기 폼(생성 기능의 POST 포함) | **사용 보류** | 03-01: 업무 규칙 거절이 모두 "결과 불명"이 되어 고친 값을 다시 저장할 수 없다. 0929/03-03: 키 없는 쓰기의 결과 불명 화면이 같은 요청을 무방비로 다시 보낸다 |
| 짝 백엔드와 함께 파일 업로드 출시 | **사용 보류** | 01-01: 프론트 업로드 프로토콜(`PRESIGNED_MULTIPART_V1`)이 짝 백엔드에 없다. 짝 백엔드 Fileserver를 부를 프론트 client도 없다 |
| `create:feature`로 기능을 더하고 템플릿 CI로 머지 | **사용 보류** | 12-01: 기능 하나만 더해도 `test:visual`이 실패한다. 02-06: FE-GATE-020의 제거 드릴 3개가 기능과 무관하게 항상 실패한다. 11-01: 생성 기능 라우트를 접근성 e2e가 오류 화면으로 검사하고 통과시킨다. 16-02: 제품 기능의 제거 드릴이 시작하자마자 끝난다 |
| 이 미출시 묶음을 다운스트림(tech-log·memento)에 전파 | **사용 보류** | 14-01: CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다. 14-02: BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 |
| 템플릿 그대로 release 단계(`RELEASE_READY`)까지 가기 | **사용 보류** | 15-01: lab 게이트 FE-GATE-026이 1101/15-01 수정(`298201f`) 뒤로 계속 실패한다. 측정 화면이 모든 기능의 실행부를 받은 뒤 그린다 |
| 배포 슬롯을 채워 desktop 서버로 자동 배포 | 사용 보류 | 13-01: FE-GATE-019가 같은 run에서 다시 빌드한 release를 통과시킨다. 13-03: lockfile이 템플릿 자신의 취약점 정책을 어기는데 merge·release에서 알 수 없다 |
| 빌드 → 공개 대상 승인 → 손으로 배포 | 사용 가능 | 지난 라운드의 거짓 PASS(이전 release를 보고 통과)는 막혔다(13 영역) |
| 짝 백엔드 Envelope를 읽는 조회 화면 | 조건부 사용 가능 | 03-02: 목록의 `meta.page`를 버린다. 16-01: operation마다 `responseEnvelope`를 손으로 적어야 하고, 빠뜨려도 게이트가 통과한다 |
| 짝 백엔드 인증에 세션 붙이기 | 조건부 사용 가능 | 09-03: 짝 백엔드 인증 방식에 맞는 세션 owner가 없어 제품이 처음부터 쓴다. 09-01: 자격증명을 싣지 않은 요청의 401도 세션을 로그아웃시킨다 |
| OPFS 런타임으로 개인 파일 저장 | 조건부 사용 가능 | 05-01: LOGOUT·ACCOUNT_DELETION purge가 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다 |
| opt-in realtime(SSE·WS)·bounded polling | 조건부 사용 가능 | 04-01: polling 선언이 V3 실행기 재시도를 막지 못해 poll 1회가 요청 3회가 된다. 04-02: 짝 백엔드 실시간 출구와 전송 규약이 맞지 않는다 |
| SW `ACTIVE`·Web Push | 조건부 사용 가능 | 06 영역 0절. 지난 High(0929/06-01)는 고쳐졌다 |
| 셸·디자인 시스템·읽기 화면, 필드 검증 400을 받는 폼 | 사용 가능 | 08 영역 |
## 2. 차단 항목 — High와 P1 (36.5-3)
같은 결함을 여러 영역이 적은 것은 하나로 합쳤다(10.3절). 재확인 칸의 "오케스트레이터 확인"은 이 문서 작성자가 해당 줄을 직접 읽었거나 직접 실행했다는 뜻이다.
### 2.1 High
| ID | 내용 | 재확인 |
|---|---|---|
| [03-01](03-adapters-http-state.md) (= [08-01](08-presentation.md)) | 짝 백엔드의 업무 규칙 거절(표 밖 400·409·422)이 모든 쓰기에서 `MAYBE_APPLIED`가 된다. 폼은 거절 이유를 보이지 못하고 다음 제출을 막는다. 짝 백엔드 생성 기능의 create는 빈 이름 하나로 400 `<FEATURE>_INVALID`를 준다. 이 거절은 트랜잭션 전에 난다 | 오케스트레이터 확인. ① 표 밖 400·409·422를 `MAYBE_APPLIED`로 고정한다(`src/adapters/http/backend-envelope.ts:163-174`). ② 표가 판정하면 패키지 분류기를 부르지 않는다(`http-execution-v3.ts:1722-1731`). ③ 폼이 `MAYBE_APPLIED`를 `CONFLICT`보다 먼저 보고(`use-app-form.ts:221` vs `:229`), 결과 불명이면 제출을 막는다(`:307`). ④ 백엔드 생성기: `build(command)`가 `tx.inWrite` 전에 돈다(`Create__Feature__UseCase.java.tmpl:52-53`). `__FEATURE___INVALID(VALIDATION, 400)`이다. 요청 DTO에 Bean Validation이 없다(`Create__Feature__HttpRequest.java.tmpl:3-8`). 공백 이름에 400이 나온다(`__Feature__ControllerTest.java.tmpl:62-69`). 에이전트 실험 X-A·X-B(jsdom). **이 판정 표는 오케스트레이터가 `3261208`에서 만들었다(10.5절)** |
| 0929/03-03 ([03](03-adapters-http-state.md) 2절, **상향 Medium·P2 → High·P1**) | 결과 불명 화면의 "같은 요청으로 다시 보내기"가 키 없는 쓰기(`NEVER`)에도 열려 있다. 응답을 정말 잃은 경우에 누르면 같은 항목이 두 번 생긴다. 짝 백엔드 생성 기능의 create가 `NOT_IDEMPOTENT`이고 매뉴얼이 "모르면 `NEVER`"를 권하므로 이 조합이 짝 사용의 기본 경로다. 03-01 때문에 이 화면도 자주 뜬다 | 오케스트레이터 확인. `resendUnknownEffect`는 head가 `UNKNOWN`이고 intent가 있는지만 본다(`src/presentation/adapters/query/application-query.ts:792-803`). 키 유무를 보지 않는다. 화면은 콜백이 있으면 버튼을 그린다(`async-surface.tsx:221-225`). 에이전트 실험 X-D: fetch 2회, 키 `[null, null]`. 상향 이유: 가이드 35.2의 High 예시 "결과 불명 작업의 무방비 재실행"에 그대로 해당한다. 지원하는 기본 구성에서 닿는다 |
| [01-01](01-adapters-browser-transfer.md) | 두 템플릿을 짝으로 쓰면 파일 업로드가 연결되지 않는다. 프론트 업로드 runtime은 `PRESIGNED_MULTIPART_V1` 하나만 안다. 짝 백엔드는 presigned·multipart 코드를 지웠고, Fileserver가 바이트를 직접 받는다(multipart 한 번, raw, tus). 프론트 문서는 아직 "서버 구현 대기"라고 적는다 | 오케스트레이터 확인. 프론트: `resumable-upload.ts:9-12`, `server-file-capability-infrastructure.md:3-5`, `src`의 `FormData` 0건. 백엔드(`bbe944bd`에서 다시 확인): `docs/storage-capability-boundary.md:21-23`, `docs/fileserver/http-contract.md:8-24`. 심각도는 지난 라운드의 같은 성격 결함(1101 README 14.3, 생성 기능이 짝 백엔드 응답을 못 읽음, High·P1)과 맞췄다 |
### 2.2 P1 (High 제외)
| ID | 심각도 | 내용 | 재확인 |
|---|---|---|---|
| [02-06](02-adapters-browser-files-cache.md) (= [06-05](06-adapters-service-worker-push.md), + `test:optional-recipe-removal`) | Medium (조정, 2.3절) | merge 게이트 FE-GATE-020의 제거 드릴 4개 중 3개가 제거 대상과 무관하게 항상 실패한다. fixture 복사 목록에 `README.md`·`CHANGELOG.md`가 없다. 그래서 두 문서 테스트(`documentation-readiness`, `changelog-review-ids`)가 `ENOENT`로 떨어진다. sample-removal 드릴만 두 테스트를 빼 둔다(`scripts/test-sample-removal.ts:204-215`) | **오케스트레이터 실행**(`corepack pnpm`, heavy lock, 00:03~). `test:browser-file-storage-removal`·`test:realtime-removal`·`test:optional-recipe-removal` 모두 exit 1. 세 드릴 모두 `test` 검사 하나만 실패했고 원인이 같다(`ENOENT lstat 'README.md'` 12건, `open 'CHANGELOG.md'` 1건). typecheck·lint·architecture·build·ci-contract는 통과했다 |
| [12-01](12-guardrails-ci.md) | Medium (조정, 2.3절) | `create:feature`로 기능 하나를 더하면 merge 게이트 `test:visual`(FE-GATE-008)이 실패한다. 셸 전체 페이지·좁은 서랍·플랫폼 구성 스크린샷이 설치된 기능의 링크와 목록을 담는다. 통과시키려면 템플릿 소유 골든 PNG 3장을 고정 글꼴 환경에서 다시 찍어야 한다. 그러면 동기화 때마다 바이너리 충돌이 난다 | 오케스트레이터 확인(`tests/visual/platform.visual.spec.ts:13-32`, `:55-65`가 `fullPage`·`main`을 찍는다. 허용치는 `maxDiffPixels: 50`). 실행은 에이전트 E3(기능 0·1·4개) |
| [09-02](09-app-core.md) | Medium | 제품 확장 지점의 타입 검사 경로가 막힌다. 문서 위치에 둔 capability 보강이 node 검사에서 보이지 않는다. 기본값이 있는 제품 설정 키는 템플릿 테스트 7개 파일의 타입을 깬다 | 에이전트 실험 |
| [09-03](09-app-core.md) | Medium | 짝 백엔드 인증 방식에 맞는 세션 owner가 없다. 제품마다 첫 연동 전에 owner를 처음부터 쓴다 | 에이전트 정적 확인 |
| [11-02](11-tests-browser-release-scale.md) (1101/11-02 남은 절반) | Medium | CI merge job이 시각 테스트 글꼴 패키지를 설치하지 않는다. 빈 러너에서는 FE-GATE-008이 코드와 무관하게 `visual-fonts` 단계에서 실패한다 | 에이전트 정적 확인 |
| [13-01](13-build-release-supply-chain.md) | Medium | FE-GATE-019가 run 이름만 대조한다. `config.json` 내용과 슬롯이 후보를 쓰는지는 보지 않는다. 그래서 같은 run에서 다시 빌드한 release를 통과시킨다 | 에이전트 실험 E-2c |
| [13-03](13-build-release-supply-chain.md) | Medium | 의존성 취약점 판정이 운영 승격 provider에만 있다. 지금 lockfile이 템플릿 자신의 정책을 어기는데, merge·release 단계에서는 알 수 없다 | 에이전트 실행 |
| [14-01](14-template-product-docs.md) (+ [04-05](04-adapters-realtime.md)) | Medium | CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다. 한 브랜치의 16커밋이 빠졌다. "알려진 제한" 13줄 중 9줄은 이미 사실이 아니다. handoff 결과 kind 변경(`17fa8d1`)의 [계약] 행도 없다 | 에이전트 `git log` 대조 |
| [14-02](14-template-product-docs.md) | Medium | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다. memento-web의 V2 행은 0개다. 실제 작업은 스키마 행 약 42개와 zod 전용 칸이다. tech-log의 직접 조립 경로에는 안내가 없다. **"memento-web이 V2 행을 쓴다"는 문장은 오케스트레이터가 썼다(10.5절)** | 에이전트가 `memento-frontend` `d3810a0` 실제 파일을 대조 |
| [15-01](15-performance.md) | Medium (조정, 2.3절) | lab 게이트 FE-GATE-026(release 단계)이 1101/15-01 수정(`298201f`) 뒤로 계속 실패한다. 측정 대상인 플랫폼 구성 화면의 route module이 그리기 전에 모든 기능의 실행부를 기다린다. 그래서 클릭 뒤 요청 묶음이 하나 더 생긴다. `298201f` 본문이 이 위험을 적었지만 재지 않았다. 147커밋 동안 아무 게이트도 알리지 않았다 | **오케스트레이터 확인 + 실행.** `loadPlatformOverviewPage`가 `await loadInstalledFeatureRuntimeRegistries()`를 한다(`src/presentation/examples/platform-overview-page.tsx:596-606`). 그 함수는 모든 기능 실행부를 dynamic import한다(`src/features/installed-feature-runtime-registries.ts:17-31`). `e40684b`에서 `corepack pnpm test:performance -- --runs=5`(부하 15): **FAIL**, 상호작용 중앙값 227 ms(표본 223·224·227·438·526) > 예산 200 ms. LCP 2,000 ms, CLS 0. `d99301b` 대조 A/B는 15 영역이 했다(117~118 ms PASS). 오케스트레이터는 다시 하지 않았다 |
### 2.3 심각도 조정
| ID | 영역 제안 | 최종 | 이유 |
|---|---|---|---|
| 02-06 | High·P1(02 영역), Medium·P1(06 영역) | Medium·P1 | 사용자 피해가 없는 "게이트가 항상 실패" 결함이다. 지난 라운드에서 같은 모양(1101/11-01, `test:system` 항상 실패)을 Medium·P1로 매겼다. 가이드 35.2의 High는 런타임에서 중요한 기능이 실패하거나 큰 피해가 나는 경우다. P1이라 첫 조치 묶음에 그대로 들어간다 |
| 12-01 | High·P1 | Medium·P1 | 02-06과 같은 이유다. 다만 "생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다"는 이 템플릿의 핵심 약속을 깬다. 그래서 개선 순서 2에 넣었다 |
| 15-01 | High·P1 | Medium·P1 | 게이트는 실제 회귀(예제 화면 진입 약 110 ms 지연)를 맞게 잡고 있다. 사용자 화면 영향은 예제 화면 하나다. 지난 라운드의 같은 모양(1101/15-01, 예산 회귀를 release 단계 검사만 봄)을 Medium·P1로 매겼다. release를 막으므로 P1은 그대로다 |
| 0929/03-03 | Medium·P2(0929), 상향 제안 High·P1(03 영역) | High·P1 | 2.1절. 지난 두 라운드는 이 경로가 짝 사용의 기본 경로라는 사실(백엔드 create `NOT_IDEMPOTENT` + 매뉴얼 "모르면 `NEVER`")을 보지 않았다 |
## 3. V2 삭제 판단의 재확인 (사용자 질문)
지난 README 14.7은 V2에만 있던 동작 셋을 판정했다. 401 재전송은 없어져도 된다. KEYED 재시도는 일부 되살렸다(`c05f41a`). 쿠키 쓰기 CSRF 요구도 되살렸다(`365d8c3`). 이번 리뷰가 이 판단을 다시 확인했다. 셋의 판정은 맞았다. 그러나 **V2가 하던 일이 셋보다 많았고, 빠뜨린 것이 있다.**
| V2가 하던 일 | 지금 | 발견 |
|---|---|---|
| FE-REG-API 기준선이 V2 행 27칸을 모두 담았다. parity 테스트가 V3 `acceptedStatuses`·`responseByteLimit`·`retrySemantics`를 V2 행에 묶었다 | 행은 descriptor에서 12칸만 뽑는다. status 목록·바이트 상한·마감·재시도 예산·`commandEffect`를 바꿔도 `check:registries`가 통과한다. 생성 API를 `[200, 201]`→`[201]`로 줄여도 모든 게이트가 통과한다(실험 X2) | [07-01](07-contracts.md) Medium·P2 |
| Envelope `meta.traceId`를 `AppFailure.traceId`에 채웠다(V2 `client.ts`) | `createFailure`에 `traceId`를 넘기는 곳이 0곳이다 | [03-06](03-adapters-http-state.md) Low·P3 |
| 지워진 테스트 3건이 V3 동작도 지켰다: `MAX_RETRY_ATTEMPTS` 전달, 호출자 signal listener 정리, realtime snapshot의 GET 조건 | 세 곳 모두 변이가 머지 게이트를 통과한다. 코드는 지금 맞다 | [10-04](10-tests-fast-layers.md) Low·P2 |
| V2 `defineRestOperation`이 조회(QUERY)에 `SAFE`·`IDEMPOTENT`만 허용했다 | 쓰기 operation을 `SAFE`로 설치할 수 있다. 그러면 보낸 뒤 응답을 잃은 POST를 자동으로 다시 보낸다 | [03-03](03-adapters-http-state.md) Medium·P2 |
| — (남긴 것) `BoundedPollOperationContract`의 `contractVersion: 2`를 "V2 HTTP 경로가 아니다"로 판정해 그대로 뒀다 | 판정이 틀렸다. 이 선언은 지운 V2 행 어휘로 된 자기 선언이다. V3 실행기 재시도를 막지 못해 poll 3회가 요청 9회가 된다(실험 P) | [04-01](04-adapters-realtime.md) Medium·P2 |
| 되살린 검사 두 개(쿠키 쓰기 CSRF, realtime snapshot GET 조건) | 한 사례씩만 테스트한다. `!isRead`를 `method === "POST"`로 바꾼 변이와 `x-csrf-token` 허용을 지운 변이가 살아남는다 | [07-02](07-contracts.md) Low·P3 |
| 삭제 뒤 정리하지 않은 문장 | VD-23의 "401 recovery 한 번"(정본 8.4와 반대), 기능 실행부 모양 설명 네 곳, 지운 검사 메시지, memento-web 이행 안내 | [14-03](14-template-product-docs.md), [09-10](09-app-core.md), [14-05](14-template-product-docs.md), [16-08](16-structure-patterns.md), [14-02](14-template-product-docs.md) |
결론: V2 코드를 지운 결정은 유지한다. 실행 경로는 V3 하나로 맞다. 다만 V2 행이 하던 "wire 칸 변경을 레지스트리가 보는 일"(07-01)은 되살려야 한다. 쓰기 `SAFE` 금지(03-03)와 polling 재시도 차단(04-01)도 V3 쪽에 다시 둬야 한다. 셋 다 P2다. 짝 백엔드에 붙여 출시하기 전에 고칠 묶음에 넣었다(8절).
## 4. 확인된 강점 (36.5-2)
- **빠른 게이트가 모두 녹색이다.** `e40684b`에서 `check:architecture`, `check:types`, `lint`가 통과했다. unit 2,580건, component 263건, integration 117건, contract 23건, runtime-schema 56건도 통과했다. 레지스트리·i18n·디자인 시스템·진단 검사와 번들 예산(201,848 / 204,800 B)도 통과했다(10.1절).
- **지난 High 4건이 고쳐진 것을 현재 코드에서 다시 확인했다.** 0929/03-01(처리 중 409 뒤 키 보호), 0929/04-01(SSE 끊김 뒤 멈춤), 0929/06-01(SW 빌드가 설정을 덮어씀), 1101/09-01(`ANONYMOUS` 요청 미전송)이다(03·04·06·09 영역). 1101 README 14.3의 High(생성 기능이 짝 백엔드 Envelope를 못 읽음)도 고쳐졌다. 지금 Envelope 읽기는 한 모듈(`backend-envelope.ts`)에 모였다(03 영역).
- **V2 삭제 뒤 게이트 입력이 모두 현재 파일을 가리킨다.** 지운 경로를 다시 넣으면 각 검사가 실패한다. 진단 생산자, risk-coverage, 아키텍처 fixture, adapter INVENTORY, 레지스트리 소비자가 여기에 해당한다(12 영역 6.1절).
- **기능 추가 경로가 실제로 짧아졌다.** 생성 명령과 매뉴얼만으로 3라우트·3operation 기능을 넣었다. 추적 파일 수정은 0건이었다. merge 게이트 10개와 기존 테스트 3,201건이 그대로 통과했다(16 영역). 남은 틈은 시각 게이트(12-01)와 제거 드릴(16-02)이다.
- **브라우저 3엔진이 안정적이다.** e2e 187건 통과(quarantine skip 3), visual 6/6, storybook 1/1. capability는 61/63이고, 실패 2건은 부하 타이밍 문제다(11-05). webkit 구 탭 청크 테스트는 loadavg 38~71에서 20/20 통과했다(11 영역).
- **빠른 계층이 V3 핵심 규칙 대부분을 지킨다.** V3·계약 변이 40종 중 28종을 빠른 계층이 잡았다. 1종은 `check:registries`가 잡았다(10 영역). 남은 틈은 Envelope 판정 경계(10-02)다.
- **지난 라운드 문서 결함 7건 중 6건이 고쳐졌다.** 가드레일 발견 5건 중 4건도 고쳐졌다(14·12 영역).
- **초기 JS 예산 안에 기능을 더할 자리가 생겼다.** 초기 JS는 201,848 / 204,800 B다(여유 2,952 B, 파일 25개). 두 브랜치의 공통 조상(202,774 B)과 비교하면 V2 삭제 쪽이 −1,716 B, 다른 브랜치가 +816 B다. 참조 모양 기능은 3개, `create:feature` 기능은 8개까지 들어간다. 기능을 늘려도 초기 파일 수는 25개 그대로다. 번들 검사는 merge 단계로 옮겨졌다(1101/15-01 고쳐짐, 15 영역).
## 5. 반복되는 원인 (36.5-4)
1. **두 템플릿 사이 계약을 한쪽 문서 문장으로만 맞춘다.** 짝 백엔드와의 기준 커밋은 문서 문장뿐이다. 어긋남을 알리는 검사가 없다(12-06). 같은 원인으로 01-01(업로드), 03-01(업무 거절 단계), 03-07(두 생성기가 만드는 operation 불일치), 04-02(실시간 전송 규약), 09-03(세션 owner), 09-06(참조 기능 응답 모양)이 생겼다. 리뷰 도중에도 실제로 일어났다. 짝 백엔드가 `7ef8d0b4` → `bbe944bd`로 바뀌면서 새 code 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(결과 불명, 같은 키로 재전송)을 더했다. 프론트 6.1절 표에는 이 code가 없다. 지금은 패키지 분류기 하나에 달렸다(03-04에 추가, 10.6절).
2. **게이트가 템플릿 원래 상태만 본다.** 기능을 더하거나 지운 상태에서 게이트를 돌리지 않는다. 12-01(시각), 11-01(접근성 e2e가 오류 화면을 통과시킴), 12-02(생성 드릴이 15개 명령만 돌림), 16-02(제품 기능 제거 드릴), 14-04(참조 기능 제거 뒤 문서 게이트), 02-06(제거 드릴 fixture)이 모두 이 모양이다. 15-01은 반대쪽 틈이다. release 단계에만 있는 게이트를 147커밋 동안 아무도 돌리지 않았다. 원인 커밋(`298201f`)은 "측정하지 않았다"고 적었지만, 그 뒤 마지막 게이트 목록(1101 README 13.8·14.5, 이번 10.1절 첫 목록)에도 없었다. 지난 라운드의 원인 2(결함을 막는 테스트가 없음)와 함께, 사용자 목표인 "생성 명령으로 빠른 출시"를 직접 막는다.
3. **V2 삭제가 남긴 틈.** 3절의 표 그대로다. 실행 코드는 V3 하나로 맞다. V2 행이 하던 검사와 테스트가 같이 사라졌고, 문장은 남았다.
4. **같은 사실을 손으로 다시 적는다.** 지난 라운드 원인 3이 모양을 바꿔 남았다. 스키마 메타 행이 zod·descriptor에서 알 수 있는 사실을 다시 적는다(16-04, 07-03). FE-REG-ENV 행 5개가 실제 스키마와 다르다(13-04). mutation 정책의 `operationId`는 자유 문자열이다(16-05, 1101/03-03). 화면이 읽지 않는 필수 칸도 있다(16-06).
5. **판정 규칙에 변이가 살아남는다.** Envelope 판정 경계 다섯 곳(10-02 = 03-08), 되살린 검사 두 개(07-02), `Retry-After` 규칙(01-03), 손상 데이터 보호 규칙(02-03)이 그렇다. 커버리지는 100%인 곳도 있다(10-02). 줄을 지나가는 테스트는 있지만, 경계를 고정하는 테스트가 없다.
## 6. 결정이 필요한 것
| 번호 | 결정 | 선택지 | 관련 | 결정할 사람 |
|---|---|---|---|---|
| D1 | 짝 업로드를 어느 쪽이 맞출 것인가 | (가) 백엔드에 `PRESIGNED_MULTIPART_V1` BFF를 다시 들인다 (나-1) 프론트에 Fileserver multipart 한 번 업로드 adapter (나-2) 프론트에 tus wire adapter (다) 두 매뉴얼에 "짝 아님"만 적는다 | 01-01 5절 D1 | 두 repo 소유자 |
| D2 | 업무 거절을 "적용 안 됨"으로 적을 자리 | ① operation 단위 `refusedBeforeWrite` code 목록(영역 권고, 가장 좁다) ② 백엔드 실패 Envelope에 단계 신호(`error.applied: false`) — 두 repo 계약 변경 ③ 현상 유지 | 03-01 5절 A, 08 5.1절 | 프론트 소유자(①), 두 repo 소유자(②) |
| D3 | 시각 계약을 설치된 기능과 떼는 방법 | (a) 기능 링크·목록 영역을 `mask` (b) 시각 테스트만 고정 fixture 제품으로 빌드 (c) 골든을 제품 소유로 선언 | 12-01 | 프론트 소유자 |
| D4 | 접근성 e2e가 기능 API에 무엇을 답할 것인가 | 기능이 자기 빈 상태 응답을 내보내기 / spec이 Envelope 모드를 알기 / 기능별 spec | 11-01 5.1절, 16-03 | 프론트 소유자 |
| D5 | CHANGELOG 미출시 절의 범위 | 병합 브랜치 전체의 누적 기록 / 브랜치별 기록 뒤 병합 때 합치기 | 14-01 5.1절 | 프론트 소유자 |
| D6 | 짝 백엔드 계약 기준점을 무엇으로 고정할 것인가 | 백엔드 `error-codes.yaml`과 `http-contract.md` 다이제스트를 프론트에 기록하고 검사 / 문서 문장 유지 | 12-06, 10.6절 | 두 repo 소유자 |
## 7. 미검증 (36.5-5)
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
|---|---|---|
| CI 러너에서의 실제 결과 | Gitea Actions가 꺼져 있다(1101 U-1). 11-02·02-06·12-01은 로컬 실행과 정적 근거다 | runner 1대와 PR 1건 |
| 짝 백엔드를 실제로 띄운 연동 | 백엔드는 읽기만 했다. 03-01·01-01의 백엔드 쪽은 생성기 템플릿과 문서로 확인했다 | 백엔드 생성 기능 + 프론트 생성 기능을 띄워 쓰기·업로드 한 번 |
| 리뷰 중 바뀐 백엔드(`bbe944bd`) | 영역 에이전트는 `7ef8d0b4`를 읽었다. 오케스트레이터는 바뀐 파일 목록과 새 code 하나(`IDEMPOTENCY_COMPLETION_UNKNOWN`)만 대조했다 | 다음 라운드에서 짝 계약 대조 |
| 다운스트림(tech-log·memento)이 03-01·0929/03-03·업로드 경로를 쓰는지 | 두 제품 코드는 14-02에 필요한 부분만 읽었다 | 두 제품의 descriptor `retrySemantics`·`responseEnvelope`와 재전송 버튼 grep |
| `test:system` 전체 | 이번 오케스트레이터 게이트 목록에 없다. 11 영역이 worktree 조건의 실패(11-04)와 시간 초과(11-03)를 보고했다 | 일반 checkout에서 한 번 |
| lab 측정의 낮은 부하·CI 러너 결과 | 측정 내내 부하가 8~40이었다. 15 영역은 같은 부하에서 `d99301b`와 번갈아 재서 부하 탓이 아님을 보였다. 부하 5 미만과 러너에서는 재지 않았다. 늘어난 약 110 ms를 왕복·다운로드·조립·렌더로 나누지 않았다 | 조용한 호스트에서 `d99301b`/`e40684b` A/B 2회 |
| 기능 N개일 때 플랫폼 구성 화면 진입 시간 | 15-01은 기능 1개(참조 기능)로만 쟀다 | 생성 기능 4·8개 상태에서 lab |
## 8. 개선 순서 (36.5-6)
| 순서 | 항목 | 최소 변경 | 비용 | 완료 기준 |
|---|---|---|---|---|
| 1 | 0929/03-03 | 키가 없는 intent면 `resendUnknownEffect`가 `null`을 돌려준다. 훅이 재전송 가능 여부를 내고, 화면은 그때만 버튼을 그린다 | 수십 줄 | `NEVER` 쓰기의 결과 불명 화면에 재전송 버튼이 없다. KEYED는 그대로 같은 키로 재전송한다 |
| 1 | 03-01 (= 08-01) | D2 ①: `commandEffect`에 `refusedBeforeWrite` code 목록을 둔다. 매뉴얼 02 4절과 생성기 쓰기 예시에 `<FEATURE>_INVALID`를 적는다 | 공개 타입 칸 1개, 조립 검사, 판정 한 줄, 문서 | X-B에서 선언한 code는 결과 불명이 아니고 저장 버튼이 켜진다. 처리 중 409를 목록에 넣으면 조립이 실패한다 |
| 2 | 02-06 | 제외 목록을 `scripts/lib/removal-fixture.ts`의 상수 하나로 올리고 네 드릴이 같이 쓴다 | 몇 줄 | 세 드릴 exit 0 |
| 2 | 15-01 | 플랫폼 구성 화면이 제목과 선언 정보는 바로 그리고, 실행부 레지스트리 부분만 Suspense 뒤에서 채운다. release 전 수동 확인 목록에 `test:performance`를 넣는다 | 화면 한 파일 | 같은 호스트에서 `d99301b`가 통과하는 조건으로 A/B 2회 이상 PASS |
| 2 | 12-01, 11-01, 16-02 | D3 (a) mask. D4 결정. 제품 기능 제거 드릴의 시작 오류 | spec 수십 줄, 골든 3장 1회 | 기능 1·4개 상태에서 `test:visual`·`test:a11y`가 골든 변경 없이 통과한다 |
| 3 | 14-01, 14-02 | 미출시 절을 기준 커밋과 맞추고, 두 다운스트림의 실제 이행 작업을 적는다 | 문서 | 다운스트림 동기화 전에 끝낸다 |
| 4 | 01-01 1단계, 09-03, 12-06 + `IDEMPOTENCY_COMPLETION_UNKNOWN` | 두 매뉴얼에 "업로드는 짝 아님"을 적는다. 6.1절 표에 새 code를 더한다. 짝 계약 기준점을 검사로 만든다(D6) | 문서 + 표 1행 + 검사 | 짝 백엔드 code가 바뀌면 프론트 게이트가 알린다 |
| 5 | 07-01, 03-03, 04-01, 10-02, 07-02 | V2 삭제가 남긴 틈(3절)을 메운다. FE-REG-API 행에 wire 칸을 더한다. 쓰기 `SAFE`를 조립에서 거절한다. poll 선언을 실행기 재시도 0으로 묶는다. 판정 경계 테스트를 고정한다 | 각 수십 줄 | 3절 표의 각 실험이 게이트에서 실패한다 |
| 6 | 13-01, 13-03 | 자동 배포 전에 | 영역 문서 | 영역 문서 완료 기준 |
## 9. 재검토 조건 (36.5-7)
- 짝 백엔드가 오류 code·Envelope 필드·멱등 규칙을 바꿀 때. D6을 검사로 만들기 전까지는 사람이 본다.
- 짝 백엔드가 presigned·direct 전송을 다시 들이거나, 프론트가 Fileserver client를 들일 때(01-01).
- 이 미출시 묶음을 tech-log·memento에 동기화할 때(14-01, 14-02).
- Gitea Actions를 켤 때. 2.2절 게이트 결함들이 실제 러너에서 어떻게 나오는지 본다.
- 제품이 OPFS·realtime·SW·업로드를 켤 때(1절 조건부 항목).
## 10. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 읽기만 했다 |
| 커밋·작업 상태·확인 시점 | 브랜치 `review/2026-11-03-merged` / `e40684b`(2026-11-03 22:49). `claude/happy-easley-233d07` `93c81df`과 `fix/ui-design-audit-2026-11-01`의 병합이다. 병합 충돌은 문서(`backend-api-and-server-state-contract.md` 6.1절 등)에서만 났다. 영역 에이전트는 이 커밋을 격리 worktree에 detach해 읽었다. 짝 백엔드는 영역 에이전트가 `7ef8d0b4`, 오케스트레이터 재확인이 `bbe944bd`다(10.6절) |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드와 함께 써서 desktop 서버에 빠르게 출시하는 것이 사용자 목표다(PRODUCT.md) |
| 필수 요구와 규모·운영 목표 | 기능 수 증가 축만 목표가 있다. 초기 JS 예산 204,800 B(gzip) |
| 읽은 코드·구성 범위 | `src/` 전체, `tests/` 전체(일부 표본), `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정. 짝 백엔드의 HTTP 계약·생성기 템플릿·Fileserver·멱등 문서. memento-frontend `d3810a0`의 memento-web 일부(14 영역) |
| 수행한 테스트·실험 | 10.1절 게이트(오케스트레이터). 각 영역의 대상 테스트, 격리 worktree의 변이·결함 주입, 3엔진 Playwright(01·02·06·08·11·12), 빌드 실험(06·13·15·16), 생성 명령으로 기능 추가(12·16), 시각 회귀(12). 무거운 실행은 `flock /tmp/claude-1000/review-2026-11-03-heavy.lock`으로 직렬화했다 |
| 확인하지 못한 범위·이유 | 7절 |
| 이전 리뷰와 비교 가능한 범위 | `2026-11-01-maturity-review`의 발견과 README 13·14절 조치, `2026-09-29-maturity-review`의 이월 항목을 현재 코드에서 다시 확인했다. 이전 실행 결과는 증거로 쓰지 않았다 |
### 10.1 게이트 실행 결과 (오케스트레이터, `e40684b`)
| 게이트 | 결과 | 시간 |
|---|---|---|
| `check:architecture` | 통과 | 11초 |
| `check:types` | 통과 | 6초 |
| `lint` | 통과 | 13초 |
| `test:unit` | 통과 — 2,580개 | 19초 |
| `test:component` | 통과 — 263개 | 9초 |
| `test:integration` | 통과 — 117개 | 16초 |
| `test:contract` | 통과 — 23개 | 2초 |
| `test:runtime-schema` | 통과 — 56개 | 3초 |
| `verify:documentation` | 통과 | 2초 |
| `check:adapter-inventory` | 통과 | 1초 |
| `check:ci` | 통과 | 4초 |
| `check:registries` | 통과 | 2초 |
| `check:i18n` | 통과 | 2초 |
| `check:design-system` | 통과 | 2초 |
| `check:diagnostics` | 통과 | 2초 |
| `check:bundle` | 통과 — 초기 JS 201,848 / 204,800 B | — |
| `test:browser-file-storage-removal` | **실패** — `test` 검사만 실패(02-06) | — |
| `test:realtime-removal` | **실패** — 같은 원인(02-06) | — |
| `test:optional-recipe-removal` | **실패** — 같은 원인(02-06) | — |
| `test:sample-removal` | 통과 — 23 checks(FE-GATE-020의 나머지 드릴) | — |
| `test:feature-scaffold` | 통과 — 16 checks | — |
| `test:performance` (FE-GATE-026, release 단계) | **실패** — 상호작용 중앙값 227 ms > 200 ms(15-01). LCP 2,000 ms, CLS 0. 부하 15 | — |
### 10.2 영역 분할 (지난 리뷰 9.2절 재사용)
| 번호 | 영역 | 문서 |
|---|---|---|
| 01 | adapters: browser-transfer | [01-adapters-browser-transfer.md](01-adapters-browser-transfer.md) |
| 02 | adapters: browser-files·cache·cross-context | [02-adapters-browser-files-cache.md](02-adapters-browser-files-cache.md) |
| 03 | adapters: http·state | [03-adapters-http-state.md](03-adapters-http-state.md) |
| 04 | adapters: realtime | [04-adapters-realtime.md](04-adapters-realtime.md) |
| 05 | adapters: storage·kernel | [05-adapters-storage-kernel.md](05-adapters-storage-kernel.md) |
| 06 | adapters: service worker·push | [06-adapters-service-worker-push.md](06-adapters-service-worker-push.md) |
| 07 | contracts | [07-contracts.md](07-contracts.md) |
| 08 | presentation | [08-presentation.md](08-presentation.md) |
| 09 | app core·bootstrap·features | [09-app-core.md](09-app-core.md) |
| 10 | tests: 빠른 계층 | [10-tests-fast-layers.md](10-tests-fast-layers.md) |
| 11 | tests: 브라우저·릴리스·규모 | [11-tests-browser-release-scale.md](11-tests-browser-release-scale.md) |
| 12 | guardrails·CI | [12-guardrails-ci.md](12-guardrails-ci.md) |
| 13 | build·release·supply chain | [13-build-release-supply-chain.md](13-build-release-supply-chain.md) |
| 14 | 템플릿·제품 문서 | [14-template-product-docs.md](14-template-product-docs.md) |
| 15 | 성능 실측·최적화 | [15-performance.md](15-performance.md) |
| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | [16-structure-patterns.md](16-structure-patterns.md) |
### 10.3 합친 중복
| 대표 | 같은 결함 | 이유 |
|---|---|---|
| 03-01 | 08-01 | 같은 판정 표(`backend-envelope.ts:163-174`)와 같은 화면 결과. 03은 판정, 08은 폼 쪽을 봤다 |
| 02-06 | 06-05, `test:optional-recipe-removal` 실패(오케스트레이터 실행) | 같은 fixture 복사 목록(`removal-fixture.ts:25-39`) |
| 11-01 | 12-03, 16-03 뒷부분(Envelope 기능에 오류 화면만 검사) | 같은 a11y spec과 같은 MSW 응답. 16-03 앞부분(기능마다 템플릿 spec 수정)은 16-03으로 남겼다 |
| 07-02 | 10-03(CSRF), 04-03(realtime snapshot) | 되살린 검사 두 개를 한 사례씩만 테스트한다는 같은 결함 |
| 10-02 | 03-08 | Envelope 판정 경계 테스트 공백. 03-08의 변이 M6은 10-02의 H14와 같다. M7(`invitesKeyedResend` 409)은 10-02 경계 목록에 더한다 |
| 09-10 | 07-05 | 09-10이 같은 `starter-experience.md:136-137` 문장을 포함한다 |
| 14-01 | 04-05 | CHANGELOG 미출시 절이 커밋과 맞지 않는다는 같은 결함. 04-05는 그 한 사례다 |
| 14-03 | 03-06 앞부분(VD-23 401 문장) | 같은 문장. 03-06은 `traceId` 부분만 센다 |
### 10.4 리뷰 중 안전 사항
- 영역 에이전트는 격리 worktree에서 일했다. 이 worktree에 직접 쓸 수 없어 자기 worktree나 scratchpad에 썼고, 오케스트레이터가 문서만 이 폴더로 옮겼다.
- 무거운 실행(브라우저·드릴·빌드)은 공유 잠금으로 한 번에 하나씩 돌렸다. 부하가 높은 시간대(loadavg 16~71)의 실패는 영역 문서가 따로 표시했다. 예: 02 영역의 첫 browser spec 실행은 `ENOSPC`로 무효였다.
- 오케스트레이터가 제거 드릴을 처음에 `npm run`으로 돌렸다. 드릴은 `npm_execpath`를 pnpm으로 가정하므로 모든 검사가 `Unknown command`로 실패했다. 이 결과는 버렸다. `corepack pnpm`으로 다시 돌린 결과만 10.1절에 적었다.
### 10.5 오케스트레이터 자신의 실수
이 리뷰 대상의 일부는 이 문서 작성자가 같은 날 만든 변경(V3 Envelope 읽기 `3261208` 등, V2 삭제 `048f490`·`12f3bb7`)이다. 영역 에이전트에게는 결론을 주지 않고 코드만 주었다. 그 결과 다음이 작성자의 실수로 확인됐다.
| 발견 | 실수 | 원인 |
|---|---|---|
| 03-01 | 표 밖 400·409·422를 `MAYBE_APPLIED`로 고정했다(`3261208`). 버린 대안 "분류기에 맡기기"의 위험(400 전체를 `NOT_APPLIED`로 보는 패키지가 키 보호를 푼다)만 봤다. 짝 백엔드 생성 기능의 업무 거절이 트랜잭션 전에 난다는 사실과 폼이 막힌다는 결과는 보지 않았다 | 판정 표를 백엔드 계약 문서만으로 정했다. 백엔드 생성기 코드와 프론트 폼까지 끝까지 따라가지 않았다 |
| 14-02 | CHANGELOG·커밋 `12f3bb7`에 "memento-web이 V2 API 행을 쓴다"고 적었다. memento-web의 `apiOperations`는 `{}`다 | 다운스트림 파일을 열지 않고 이름으로 추정했다 |
| 04-01 | `BoundedPollOperationContract`를 "V2 HTTP 경로가 아니다"로 판정해 남겼다 | 선언이 실제 요청을 통제하는지 실행으로 보지 않았다 |
| 07-01, 10-04, 03-06(`traceId`) | V2 삭제 때 "V2에만 있던 동작"을 셋만 찾았다. 행·parity 테스트가 하던 검사, 지운 테스트가 지키던 V3 동작, Envelope `traceId` 채우기를 놓쳤다 | 지운 코드의 "실행 동작"만 찾았다. 지운 검사·테스트가 무엇을 지키고 있었는지는 보지 않았다 |
### 10.6 리뷰 중 바뀐 짝 백엔드
영역 에이전트가 읽은 뒤 짝 백엔드에 `bbe944bd`(2026-11-03 23:29)가 들어왔다. 오케스트레이터는 이 커밋의 바뀐 파일과 본문을 확인했다.
- 새 오류 code 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(`retryable=true`)이 생겼다. 뜻은 "실행 뒤 결과 기록 실패, 적용됐을 수 있음, 같은 키로 나중에 재전송, 새 키 금지"다(백엔드 `docs/web/http-contract.md:105`, `docs/manual/05-idempotency.md:53`). 백엔드는 "짝 프론트 인계 문서에 더했다"고 적는다(백엔드 `docs/reviews/2026-11-03-rereview/README.md:110`).
- 프론트 `REFUSED_BEFORE_WRITE` 표와 `envelopeFailureEffect`에는 이 code가 없다. 503이면서 `IDEMPOTENCY_UNAVAILABLE`이 아니므로 `undefined`를 돌려주고, 패키지 분류기가 판정한다(`backend-envelope.ts:163-174`, `http-execution-v3.ts:1722-1731`). 참조 분류기는 503을 `MAYBE_APPLIED`로 보므로 지금은 안전하다. 그러나 5xx를 `NOT_APPLIED`로 보는 패키지는 새 키를 쓴다. 03-04(표 밖 멱등성 실패가 패키지 분류기에 달림, Low·P2)의 한 사례로 더한다. 12-06(짝 계약 어긋남을 알리는 검사가 없음)이 실제로 일어난 예다.
- 업로드(01-01) 쪽 문서 변경은 Fileserver 설정 몇 줄이다. 01-01 판정은 그대로다.
## 11. 28개 관점 판정 (36.2)
영역별 판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 한 영역이라도 X면 X다(35.7절). 각 영역의 목표·확인 통제와 증거는 영역 문서의 36.2 표에 있다.
| 번호 | 관점 | 영역 01~16 | 종합 | 종합 판정의 근거·잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | `OPPOPPPPP>>->>P>` | P | 판정 규칙이 한 모듈에 모였다(03). 03-01 판정 표, 02-04 `inspect`·`release` 경쟁, 05-01 purge 보고 |
| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>OP` | P | 기능 폴더 규칙(1101/16-06)과 스키마 메타 행 손 사본(16-04)이 남았다 |
| 3 | 변경 용이성 | `OPPPPPPPPPPPPPPP` | P | 09-02 제품 확장 지점 타입 경로, 12-07 배포 슬롯·제품 게이트가 템플릿 `gates.json` 수정을 요구, 16-05 |
| 4 | 인지 부하 | `PPPPPPPPPPPPPPPP` | P | 짝 백엔드 KEYED 쓰기 값 넷을 매뉴얼이 정하지 않는다(16-07). 03-01은 매뉴얼 한 문장에서만 알 수 있다 |
| 5 | 위험 가시성 | `PPPPPPPPPPPPPPXP` | **X** | 15 영역: lab 실패가 release 단계에서만 드러나 147커밋 동안 보이지 않았다(15-01). 03-05 결과 불명 진단에 원인이 없다. 01-01 문서가 "서버 구현 대기"라고 적는다 |
| 6 | 실패 성숙도 | `PPPPPPOXPPO-O>>>` | **X** | 08 영역: 업무 거절과 결과 불명을 가를 수단이 없어 저장이 멈춘다(03-01) |
| 7 | 운영 성숙도 | `OPPPPP>>P-P>P>P-` | P | 13-01 배포 확인, 03-05 결과 불명 텔레메트리 |
| 8 | 디버깅 가능성 | `PPPPPPPPPPPPPPPP` | P | 03-06 `traceId` 미채움, 14-06 `check:registries`가 원인을 버림, 09-07 원인 없는 메시지 |
| 9 | 유지보수 성숙도 | `PPPPPPPPPPPPPPPP` | P | V2 삭제가 남긴 문장·검사(3절) |
| 10 | 테스트 성숙도 | `PPPPPPPPPPPPPPPP` | P | 변이가 살아남는 판정 경계(10-02, 07-02, 01-03, 02-03), 부하에 떨어지는 테스트(10-01, 11-03, 11-05) |
| 11 | 데이터 성숙도 | `PP-OPO>-P>-->-->` | P | 05-01 OPFS purge, 02-04, 05-03 손상 journal 행 |
| 12 | 동시성 성숙도 | `PPPOPP-O>PP->->>` | P | 0929/03-03 키 없는 재전송, 05-02 lock 대기 abort 무시, 03-03 `SAFE` 쓰기 재전송 |
| 13 | 확장성 | `PO>P?PP>P>P>>>PP` | P | 기능당 초기 +716~984 B, 참조 모양 3개·생성 기능 8개까지(15). 플랫폼 구성 화면이 기능 수만큼 실행부를 받는다(15-01) |
| 14 | 성능 성숙도 | `PPOP?POO>PP?P>XP` | **X** | 15 영역: lab 상호작용 227~271 ms > 200 ms(15-01). 초기 JS 예산 98.6% |
| 15 | 보안 성숙도 | `OPOOPPPPPP>OP>>>` | P | 06-02 Web Push 경로 `..`, 13-05 슬롯 secrets 노출 범위, 09-01 401 범위, 07-04 |
| 16 | 의존성 성숙도 | `O->O-P>>->PPPPP>` | P | 13-03 lockfile이 취약점 정책을 어김, 15-07 react-router 개발 빌드 |
| 17 | API / Contract 성숙도 | `PPPPPPPPPP>PPP>P` | P | 03-01, 03-02 `meta.page` 버림, 07-01 wire 칸 미감시, 16-01 Envelope 선언 누락 통과, 12-06 짝 계약 기준점 |
| 18 | 배포 성숙도 | `OP>PPP>O>>P>P>P>` | P | 13-01 같은 run 재빌드 통과, 13-02 HTTP/2·압축 전제 |
| 19 | 설정 성숙도 | `PPPPPPPPPPPPPPOP` | P | 13-04 FE-REG-ENV 행 불일치, 07-04 금지 이름 검사가 부팅 때만 |
| 20 | 개발자 경험 | `X>PP>PPPPPPPPPPP` | **X** | 01 영역: 짝 백엔드로 파일 업로드를 붙이는 경로가 어느 문서에도 없다(01-01) |
| 21 | Guardrail 성숙도 | `PPPPPPPPPPPPPPPP` | **X** | **오케스트레이터 판정.** 영역은 모두 P다. 그러나 merge 게이트 FE-GATE-020의 드릴 4개 중 3개가 항상 실패하는 것을 직접 재현했다(02-06). 지난 라운드에 같은 모양(1101/11-01 `test:system` 항상 실패)으로 X를 줬다. 12-01·11-01·15-01도 템플릿 그대로 또는 기능 하나로 게이트가 틀린 답을 낸다 |
| 22 | 추상화 성숙도 | `OPPPPOPPPPPP>>>P` | P | 04-01 polling 선언이 실행기를 통제하지 못함, 08 5.3 폼·코디네이터 상태 분리 |
| 23 | 일관성 | `PPPPPPPPPPPPPPPP` | P | 01-02 같은 429에 단계마다 다른 `retryable`, 04-04 서버 끊김 실패 이름 |
| 24 | 네이밍 / 의미 성숙도 | `PPPPPPPPPPPPPPPP` | P | 0929/03-03 "같은 요청으로 다시 보내기"가 키 없는 명령에도 동작, 09-09 `NOT_INSTALLED` 다의 |
| 25 | 조직 확장성 | `-->-?-OPP->P-P>P` | P | 12-07, 12-01 템플릿 소유 파일 수정이 기능 추가마다 필요 |
| 26 | Ownership 성숙도 | `X>P-?PP?>PPPPP>>` | **X** | 01 영역: `PRESIGNED_MULTIPART_V1` 서버 쪽 주인이 비었다(01-01) |
| 27 | 삭제 가능성 | `PPO?PPP>PPPP>P>X` | **X** | 16 영역: 제품 기능의 제거 드릴이 시작 직후 실패한다(16-02). 02-06도 같은 관점 |
| 28 | 회복 가능성 | `PPPPPP-XP-P-P>>>` | **X** | 08 영역: 업무 거절 뒤 화면 안에서 정상으로 돌아갈 길이 거짓 성공 버튼뿐이다(03-01) |
## 12. 발견 색인
영역 문서에 36.3 양식으로 적힌 발견은 96건이다. 같은 결함 8건을 대표 항목에 합쳐(10.3절) 색인은 88건이다: High 2 · Medium 34 · Low 52, P1 12 · P2 38 · P3 38, 확인된 결함 55 · 구조적 위험 23 · 개선 제안 10. 각 영역 문서 2절의 "지난 발견 재확인" 표에만 있는 이월 항목(0929/03-03 등)은 여기 세지 않았다. 2절 차단 항목에는 포함했다. 심각도 조정은 2.3절이다.
| ID | 심각도·우선순위 | 성격 | 내용 | 관련 관점 | 합친 것·조정 |
|---|---|---|---|---|---|
| [01-01](01-adapters-browser-transfer.md) | High·P1 | 확인된 결함 | 파일 업로드는 두 템플릿을 짝으로 쓰면 연결되지 않는다 | 17, 26, 20, 5, 23 | |
| [03-01](03-adapters-http-state.md) | High·P1 | 확인된 결함 | 짝 백엔드의 업무 규칙 거절이 모든 쓰기에서 결과 불명이 되어, 폼이 거절 이유를 못 보이고 고친 값을 다시 저장하지 못한다 | 6, 17, 22, 20, 28, 5, 23 | 08-01 |
| [02-06](02-adapters-browser-files-cache.md) | Medium·P1 | 확인된 결함 | 제거 드릴 `test:browser-file-storage-removal`(merge 게이트 FE-GATE-020)이 문서 테스트 2파일 때문에 항상 실패한다 | 21, 27, 18, 10 | 06-05, optional-recipe 드릴(오케스트레이터 실행); 조정 High·P1 → Medium·P1 |
| [09-02](09-app-core.md) | Medium·P1 | 확인된 결함 | 제품 확장 지점의 타입 검사 경로가 막힌다: 문서 위치의 capability 보강은 node 검사에서 안 보이고, 기본값 있는 제품 설정 키는 템플릿 테스트 7개 파일의 타입을 깬다 | 3, 21, 25, 4, 8, 10, 19, 20 | |
| [09-03](09-app-core.md) | Medium·P1 | 구조적 위험 | 짝 백엔드의 인증 방식에 맞는 세션 owner가 없어, 제품마다 첫 연동 전에 owner를 처음부터 써야 한다 | 3, 15, 20, 22, 25, 13 | |
| [11-02](11-tests-browser-release-scale.md) | Medium·P1 | 확인된 결함 | CI merge job이 시각 테스트 글꼴 패키지를 설치하지 않아, 빈 러너에서는 FE-GATE-008이 코드와 무관하게 `visual-fonts` 단계에서 실패한다 (1101/11-02 남은 절반) | 21, 10, 19, 20, 16, 5 | |
| [12-01](12-guardrails-ci.md) | Medium·P1 | 확인된 결함 | `create:feature`로 기능 하나를 더하면 merge 게이트 `test:visual`이 실패하고, 통과시키려면 템플릿 소유 골든 PNG 3장을 다시 찍어야 한다 | 10, 25, 3, 21, 20, 26 | 조정 High·P1 → Medium·P1 |
| [13-01](13-build-release-supply-chain.md) | Medium·P1 | 확인된 결함 | FE-GATE-019가 run 이름만 대조하고 `config.json` 내용과 슬롯의 후보 사용을 보지 않아, 같은 run에서 다시 빌드한 release를 통과시킨다 | 18, 21, 15, 19, 5, 28 | |
| [13-03](13-build-release-supply-chain.md) | Medium·P1 | 확인된 결함 | 의존성 취약점 판정이 운영 승격 provider에만 있고, 지금 lockfile이 템플릿 자신의 정책을 어기는데 merge·release에서 알 수 없다 | 16, 15, 26, 21, 5 | |
| [14-01](14-template-product-docs.md) | Medium·P1 | 확인된 결함 | CHANGELOG 미출시 절이 리뷰 기준 커밋과 맞지 않는다 | 30.4, 9, 17, 26, 5, 24 | 04-05 |
| [14-02](14-template-product-docs.md) | Medium·P1 | 확인된 결함 | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 | 30.4, 30.3, 17, 20, 24, 25 | |
| [15-01](15-performance.md) | Medium·P1 | 확인된 결함 | lab 게이트(FE-GATE-026)가 1101/15-01 수정 뒤로 계속 실패한다 | 14, 21, 18, 13, 5, 10 | 조정 High·P1 → Medium·P1 |
| [01-02](01-adapters-browser-transfer.md) | Medium·P2 | 확인된 결함 | `Retry-After`가 상한을 넘으면 part 단계는 앱에 `retryable:true`를 준다 | 6, 17, 23, 19, 14 | |
| [02-01](02-adapters-browser-files-cache.md) | Medium·P2 | 구조적 위험 | browser-files runtime을 로그아웃·계정 전환에 맞춰 닫는 공식 연결점이 없다 | 15, 5, 3, 17, 9 | |
| [03-02](03-adapters-http-state.md) | Medium·P2 | 확인된 결함 | Envelope 읽기가 `data`만 꺼내 백엔드 목록의 `meta.page`를 버리고 bulk `results`를 거절한다 | 17, 22, 20 | |
| [03-03](03-adapters-http-state.md) | Medium·P2 | 확인된 결함 | 쓰기 operation을 `SAFE`로 설치할 수 있고, 그러면 보낸 뒤 응답을 잃은 POST를 자동으로 다시 보낸다 | 6, 21, 17, 12 | |
| [04-01](04-adapters-realtime.md) | Medium·P2 | 구조적 위험 | bounded polling 계약이 지운 V2 행 어휘로 된 자기 선언이라, V3 실행기의 재시도를 막지 못한다 | 17, 6, 14, 13, 24, 5, 10, 22 | |
| [04-02](04-adapters-realtime.md) | Medium·P2 | 구조적 위험 | 짝 백엔드의 실시간 출구와 프론트 realtime의 전송 규약이 맞지 않고, 어디에도 적혀 있지 않다 | 17, 3, 20, 5, 18 | |
| [05-01](05-adapters-storage-kernel.md) | Medium·P2 | 확인된 결함 | 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다 | 11, 15, 28, 12, 17, 5, 24, 23, 10 | |
| [07-01](07-contracts.md) | Medium·P2 | 확인된 결함 | V2 행과 V2/V3 일치 테스트를 지우면서 V3 descriptor에 간접으로 걸리던 검사 3개가 사라졌고, 새 `problemSchema` 칸은 반만 잠겼다 | 17, 21, 3, 5, 10, 13, 20, 22 | |
| [09-01](09-app-core.md) | Medium·P2 | 확인된 결함 | 세션 자격증명을 싣지 않은 요청의 401도 템플릿 세션을 로그아웃시킨다 | 6, 5, 7, 8, 15, 17, 28, 10 | |
| [09-04](09-app-core.md) | Medium·P2 | 구조적 위험 | 플랫폼 예제 화면 4개를 제품이 끌 자리가 없고, 릴리스 게이트가 그 화면의 접근성 서명을 요구한다 | 27, 3, 23, 25, 18 | |
| [09-05](09-app-core.md) | Medium·P2 | 구조적 위험 | Service Worker 등 선택 런타임을 켜고 연결하는 일이 제품 확장 지점 밖에 있고, 매뉴얼은 그 파일을 고치지 말라고 한다 (흡수: 1101/09-05) | 3, 25, 23, 4, 20, 22 | |
| [09-06](09-app-core.md) | Medium·P2 | 구조적 위험 | 참조 기능이 짝 백엔드의 응답 모양이 아니어서, 쓰기 경로 예제가 짝 백엔드에서 쓰이지 않는 분기를 보여 준다 | 17, 4, 9, 20, 23 | |
| [10-01](10-tests-fast-layers.md) | Medium·P2 | 확인된 결함 | 자식 프로세스 EOF 테스트가 자식 Node의 기동 시간까지 1초 안에 넣는다 | 10, 12, 20, 21, 8, 23 | |
| [10-02](10-tests-fast-layers.md) | Medium·P2 | 구조적 위험 | Envelope 실패 판정의 경계 다섯 곳을 어떤 테스트도 고정하지 않는다 | 10, 17, 6, 11, 21, 24 | 03-08 |
| [11-01](11-tests-browser-release-scale.md) | Medium·P2 | 확인된 결함 | 생성한 기능의 라우트는 접근성 e2e에서 빈 목록이 아니라 Envelope 불일치 오류 화면으로 검사되고, 릴리스 증거는 그 라우트를 "passed"로 적는다 | 10, 21, 5, 24, 20, 17 | 12-03 |
| [12-02](12-guardrails-ci.md) | Medium·P2 | 확인된 결함 | `create:feature`의 "모든 merge 게이트 통과"를 드릴은 15개 명령으로만 확인한다 | 10, 21, 20, 5, 25 | |
| [12-06](12-guardrails-ci.md) | Medium·P2 | 구조적 위험 | 짝 백엔드 계약의 기준 커밋이 문서 문장뿐이고 어긋남을 알리는 검사가 없다 | 17, 21, 16, 25, 26 | |
| [12-07](12-guardrails-ci.md) | Medium·P2 | 구조적 위험 | 배포 슬롯과 제품 전용 게이트를 붙이려면 템플릿 소유 `gates.json`을 고쳐야 한다 | 25, 26, 3, 19, 18 | |
| [13-02](13-build-release-supply-chain.md) | Medium·P2 | 확인된 결함 | HTTP/2·압축 전제가 호스팅 계약과 probe에 없고, 템플릿의 nginx 예시가 둘 다 켜지 않는다 | 14, 18, 19, 20, 21, 5 | 15-05 뒷부분(HTTP/2 전제) |
| [14-03](14-template-product-docs.md) | Medium·P2 | 확인된 결함 | 목표 설계 문서의 상태 값과 결정이 V2 삭제를 반영하지 않는다 | 9, 5, 17, 24, 4, 15 | |
| [14-04](14-template-product-docs.md) | Medium·P2 | 확인된 결함 | 참조 기능을 지우면 매뉴얼·입구 문서 8개가 merge 게이트 FE-GATE-017을 실패시킨다. 제거 드릴은 문서를 복사하지 않고 그 게이트를 돌리지 않는다 | 27, 30.5, 30.3, 20, 10, 21 | |
| [16-01](16-structure-patterns.md) | Medium·P2 | 구조적 위험 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다 | 3, 17, 21, 10, 5, 22, 4 | |
| [16-02](16-structure-patterns.md) | Medium·P2 | 확인된 결함 | 제품 기능의 제거 드릴(`test:sample-removal -- --feature=<id>`)이 시작 3초 만에 무관한 오류로 끝난다 | 27, 21, 10, 20, 8 | |
| [16-03](16-structure-patterns.md) | Medium·P2 | 확인된 결함 | 공유 접근성 e2e spec이 기능마다 템플릿 파일 수정을 요구하고, Envelope 기능에는 오류 화면만 검사한다 | 10, 21, 25, 27, 9, 20 | (뒷부분 → 11-01) |
| [03-04](03-adapters-http-state.md) | Low·P2 | 구조적 위험 | 백엔드의 다른 멱등성 실패와 503 `REQUEST_TIMEOUT`이 표 밖이라 패키지 분류기 하나에 달려 있다 | 6, 17, 12, 9 | |
| [05-04](05-adapters-storage-kernel.md) | Low·P2 | 확인된 결함 | recipe fake의 reconcile이 FILES_READY에서 멈춘 put을 되돌리지만 런타임은 commit한다 | 10, 17, 22, 5 | |
| [08-02](08-presentation.md) | Low·P2 | 확인된 결함 | 키보드로 저장했다가 필드 오류가 아닌 실패(결과 불명, 429 등)를 받으면 포커스가 `body`로 떨어진다 | 1, 6, 10 | |
| [09-07](09-app-core.md) | Low·P2 | 확인된 결함 | 제품 인증 프로필 id를 잘못 적으면 게이트가 원인 없는 메시지만 보이고, 문서는 사라진 메시지를 약속한다 | 8, 20, 4, 9, 24 | |
| [10-04](10-tests-fast-layers.md) | Low·P2 | 구조적 위험 | V2 삭제 과정에서 V3 동작 세 가지가 머지 게이트 테스트의 보호를 잃었다 | 10, 21, 19, 12, 14, 27 | |
| [11-03](11-tests-browser-release-scale.md) | Low·P2 | 확인된 결함 | `test:system`의 provider 테스트 10개(선언 8개)가 10초 상한에 묶여 부하에서 시간 초과하고, 하나만 골라 돌리면 첫 테스트가 기반 fixture 빌드를 떠안아 항상 실패한다 | 10, 21, 20, 8 | |
| [11-05](11-tests-browser-release-scale.md) | Low·P2 | 구조적 위험 | IndexedDB 차단 업그레이드 capability 테스트가 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려 해서, 전체 실행에서 두 엔진이 실패했다 | 10, 12, 21, 8 | |
| [12-04](12-guardrails-ci.md) | Low·P2 | 확인된 결함 | 아키텍처 금지 fixture가 fixture 전용 ESLint 규칙을 시험해, 운영 규칙을 지워도 통과한다 | 21, 10, 2, 5, 23 | |
| [14-05](14-template-product-docs.md) | Low·P2 | 확인된 결함 | 기능 폴더 밖 정본 표와 결정표 5절이 지운 검사의 메시지와 틀린 게이트 기대를 적는다 | 20, 8, 9, 19, 21 | |
| [15-02](15-performance.md) | Low·P2 | 확인된 결함 | 성능 기준선 숫자가 다시 현재 빌드와 다르고, 같은 파일 안에서도 서로 다르다 (1101/15-02 재발) | 9, 14, 20, 24, 5, 21 | |
| [15-03](15-performance.md) | Low·P2 | 확인된 결함 | 예산을 넘으면 `check:bundle`이 무엇이 얼마나 넘었는지 출력하지 않는다 | 8, 20, 21 | |
| [16-04](16-structure-patterns.md) | Low·P2 | 구조적 위험 | 스키마 메타 행(`<base>-schema-metadata.ts`)이 zod·descriptor에서 알 수 있는 사실을 손으로 다시 적고, 틀려도 아무 검사가 잡지 않는다 | 3, 17, 22, 21, 4, 23 | |
| [16-05](16-structure-patterns.md) | Low·P2 | 확인된 결함 | 뮤테이션 정책의 `operationId`가 자유 문자열이라 오타가 타입·레지스트리를 통과하고, 작성 화면이 요청도 보내지 않고 "요청을 처리할 수 없습니다"로 멈춘다 | 21, 3, 8, 24, 22 | |
| [16-07](16-structure-patterns.md) | Low·P2 | 개선 제안 | 짝 백엔드에 KEYED 쓰기를 붙이는 값 넷을 매뉴얼이 정해 주지 않는다 | 4, 20, 3, 17, 19 | |
| [01-03](01-adapters-browser-transfer.md) | Low·P3 | 확인된 결함 | `Retry-After`·멱등 키 규칙 세 개를 테스트가 고정하지 않는다 | 10, 6, 21 | |
| [02-02](02-adapters-browser-files-cache.md) | Low·P3 | 확인된 결함 | 활성화 재검증이 캐시 본문 읽기의 일시 오류를 무결성 실패로 보고한다 | 6, 8, 23, 24 | |
| [02-03](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | 손상 데이터·로그아웃 경로의 보호 규칙 5개를 테스트가 잡지 못한다 | 10, 28, 6, 15 | |
| [02-04](02-adapters-browser-files-cache.md) | Low·P3 | 확인된 결함 | `inspect()`와 `release()`가 겹치면 놓은 ref에 receipt가 발급되고 File이 vault에 남는다 | 12, 1, 11, 15 | |
| [02-05](02-adapters-browser-files-cache.md) | Low·P3 | 확인된 결함 | pointer가 손상되면 `inspect()`가 아무 상태도 보여 주지 않고 실패한다 | 8, 28, 5 | |
| [03-05](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 결과 불명으로 끝난 쓰기의 진단·텔레메트리에 effect와 원인이 없다 | 8, 7 | |
| [03-06](03-adapters-http-state.md) | Low·P3 | 확인된 결함 | V2 삭제 뒤 정리 누락: `AppFailure.traceId`를 채우는 곳이 없고, VD-23에 정본과 반대인 401 재전송 문장이 남았다 | 27, 9, 24 | (VD-23 부분 → 14-03) |
| [03-07](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 프론트 `create:feature`와 백엔드 `new-feature.sh`가 만드는 operation이 서로 맞지 않는다 | 20, 17 | |
| [04-04](04-adapters-realtime.md) | Low·P3 | 확인된 결함 | 서버만 끊긴 실패의 이름이 transport마다 다르고, 13.1 표가 바뀐 재시도 규칙과 맞지 않는다 | 24, 23, 17, 7, 8, 9 | |
| [04-06](04-adapters-realtime.md) | Low·P3 | 개선 제안 | V2 삭제 뒤 realtime 레지스트리의 codec·mapper 바인딩을 기능이 채울 자리가 없다 | 3, 20, 22, 17 | |
| [05-02](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | partition lock을 기다리는 put·delete가 자기 abort signal을 무시하고, 그 기다림에 상한이 없다 | 12, 6, 19, 5 | |
| [05-03](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행을 지우지 못해, `DEGRADED`가 영원히 남는다 | 28, 7, 5, 11 | |
| [06-01](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함 | 운영 문서가 "`verify:hosting-headers`는 워커 스크립트 헤더를 보지 않는다"고 적지만, 지금은 본다 | 26, 5, 28, 21 | |
| [06-02](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함 | Web Push registry `path`의 `..` 또는 `%2e%2e`가 router base path 밖을 연다 | 15, 19, 17, 1 | |
| [06-03](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | 워커 install은 7가지 확장자의 Content-Type을 정확히 요구하지만, 호스팅 정책과 probe는 JavaScript만 본다 | 18, 19, 21, 7, 8 | |
| [06-04](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | waiting 워커가 바뀔 때마다 밀려난 후보 캐시가 남아, 활성화가 일어날 때까지 쌓인다 | 13, 14, 11, 28 | |
| [07-02](07-contracts.md) | Low·P3 | 확인된 결함 | V2에서 옮긴 검사 두 개(쿠키 쓰기 CSRF, realtime snapshot operation)가 한 사례만 테스트된다 | 10, 15, 21 | 10-03, 04-03 |
| [07-03](07-contracts.md) | Low·P3 | 구조적 위험 | FE-REG-SCHEMA 행의 `unknownFieldPolicy`·`direction`이 검증기와 묶이지 않은 손 사본이다 | 17, 23, 24, 10, 9 | |
| [07-04](07-contracts.md) | Low·P3 | 구조적 위험 | 제품 런타임 설정 키의 금지 이름 검사가 부팅 때만 돈다 | 19, 8, 15, 20 | |
| [08-03](08-presentation.md) | Low·P3 | 확인된 결함 | 폼 문구 표를 `Object.prototype` 이름까지 찾아, `constructor` 같은 code가 "요청한 문구를 표시할 수 없습니다."가 된다 | 23, 1 | |
| [08-04](08-presentation.md) | Low·P3 | 확인된 결함 | 기능 라우트 경로 중복 검사가 대소문자·끝 슬래시만 다른 두 경로를 놓쳐, 라우터가 그중 하나만 그린다 | 21, 23, 1 | |
| [08-05](08-presentation.md) | Low·P3 | 확인된 결함 | 422 `IDEMPOTENT_REQUEST_MISMATCH`(같은 키, 다른 본문)를 입력 오류로 보여 "입력값을 다시 확인해 주세요."라고 한다 | 24, 8, 23 | |
| [09-08](09-app-core.md) | Low·P3 | 개선 제안 | 기능이 선언한 capability만 받는다는 설명은 여전히 타입에서만 지켜지고, 이제 생성 뼈대마다 그 주석이 복제된다 (이월: 1101/09-08) | 22, 5, 2 | |
| [09-09](09-app-core.md) | Low·P3 | 구조적 위험 | `NOT_INSTALLED` 표시가 여러 뜻이고, 표시와 `feature-module.ts`가 함께 있어도 조용히 설치된다 (이월: 1101/09-04) | 24, 21, 27, 4 | |
| [09-10](09-app-core.md) | Low·P3 | 확인된 결함 | V2 삭제 뒤 기능 실행부의 모양 설명이 네 곳에 남았다 | 9, 4, 24, 20 | 07-05 |
| [09-11](09-app-core.md) | Low·P3 | 개선 제안 | 세션 복구 버튼이 `recover()` 결과를 버리고, owner의 상태 전이 계약이 적혀 있지 않다 | 28, 22, 5 | |
| [11-04](11-tests-browser-release-scale.md) | Low·P3 | 확인된 결함 | `test:system`은 git worktree에서 provider 테스트 16개가 `.git` 때문에 실패하는데, 사전 점검은 PASS라고 한다 | 20, 8, 10, 26 | |
| [12-05](12-guardrails-ci.md) | Low·P3 | 확인된 결함 | `verify:documentation`이 명령 안 경로·저장소 밖 링크·지운 심볼·1절 밖 문서를 보지 않는다 | 21, 9, 27, 26 | |
| [12-08](12-guardrails-ci.md) | Low·P3 | 확인된 결함 | merge 게이트 `check:scale:pr`가 커밋된 로그 파일을 다시 쓴다 | 9, 20, 27 | |
| [13-04](13-build-release-supply-chain.md) | Low·P3 | 확인된 결함 | FE-REG-ENV 런타임 행 13개 중 5개의 `required`·`defaultValue`가 실제 스키마와 다르고, 대조 검사가 없다 | 19, 17, 23, 9 | |
| [13-05](13-build-release-supply-chain.md) | Low·P3 | 개선 제안 | 채운 배포 슬롯의 `secrets.*`가 job 전체 env로 렌더링돼 다른 단계에도 보인다 | 15, 18, 26 | |
| [14-06](14-template-product-docs.md) | Low·P3 | 확인된 결함 | `check:registries`가 계약 조립 실패의 원인(`reason`)을 버리고, 레지스트리가 통째로 지워진 것처럼 breaking 증거 누락을 연쇄로 적는다 | 8, 20 | |
| [15-04](15-performance.md) | Low·P3 | 구조적 위험 | 기능당 1 KiB 상한의 여유가 40 B이고, 잰 값에 새 context 비용이 섞여 있다 | 10, 13, 21, 24 | |
| [15-05](15-performance.md) | Low·P3 | 구조적 위험 | 초기 JS 파일 수에 상한이 없고, HTTP/2 서빙 전제를 확인하는 장치가 없다 | 14, 18, 21, 5, 13 | (HTTP/2 부분 → 13-02) |
| [15-06](15-performance.md) | Low·P3 | 개선 제안 | build id 하나만 바뀌어도 초기 JS의 49.4%가 캐시에서 버려진다 (1101 O1·0929/13-03 그대로) | 14, 18, 23 | |
| [15-07](15-performance.md) | Low·P3 | 개선 제안 | react-router 개발 빌드가 운영 번들에 들어간다 | 16, 14 | |
| [16-06](16-structure-patterns.md) | Low·P3 | 개선 제안 | 기능 작성자가 반드시 채우는 칸 중 화면·실행이 읽지 않는 칸이 있다 | 4, 22, 23, 24, 9 | |
| [16-08](16-structure-patterns.md) | Low·P3 | 확인된 결함 | 기능 추가 경로 문서의 낡은 문장 (09-10·14-05에 없는 것) | 9, 20, 24, 10 | |