docs(review): 2026-11-06 5라운드 성숙도 리뷰 결과를 기록한다

문제: PR B(`bbde570`)가 2026-11-05 리뷰의 조치를 모두 담았다. 멈춤
기준(새 High 0, 새 P1 0, merge 게이트 14개 통과)을 판정하려면 그 커밋을
다시 리뷰해야 한다.

고른 방법:
- 지난 라운드의 영역 16개를 그대로 쓰고, 영역마다 리뷰어 하나가 코드를
  읽었다.
- merge stage는 같은 커밋에서 메인 세션이 돌린 실행(2026-11-06
  03:24~03:56)을 게이트 증거로 썼다. merge stage 밖의 명령과 리뷰어가 읽을
  산출물은 잠금 안에서 한 번 돌려 공유했다.
- 리뷰어 요청 65건과 12-04 완료 드릴은 desktop에서 한 항목씩 묶어 돌렸다.
- 지난 발견은 ID별로 다시 판정했다. 지난 README 16절의 "고침"을 그대로
  쓰지 않았다. 새 High·P1 후보 둘(03-01, 08-01)은 코드에서 다시 읽었다.
버린 대안: 리뷰어마다 desktop에서 따로 실행. 지난 라운드에 잠금 줄이
30건까지 쌓였다.

위험·한계: FE-GATE-013의 tests/system 18건, release run 산출물, 실제 짝
백엔드 연동은 이 환경에서 확인하지 못했다(README 8절). 리뷰 중 배치
runner를 둘 띄워 한 항목을 다시 돌렸다(README 11.5절).

검증: 새 발견 25건(High 0, P1 0, Medium 1, Low 24). 지난 발견 140건을
다시 판정했다. 배치 67항목 모두 restore=clean이었고, desktop checkout은
원래 상태(`fix/maturity-review-2026-11-03` `8a44226`, git status 비어 있음)로
끝났다.

Refs: docs/reviews/2026-11-06-maturity-review/README.md
This commit is contained in:
DongHyeonka
2026-11-06 05:06:05 +09:00
parent bbde570796
commit 302d3a5359
17 changed files with 3900 additions and 0 deletions
@@ -0,0 +1,189 @@
# 영역 01 — adapters: browser-transfer
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝, 브랜치 `docs/maturity-review-2026-11-06`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/browser-transfer/`(배럴 `index.ts`, `presigned/`, `resumable-upload/`, `image-cdn/`), 포트 `src/application/ports/browser-transfer/`, Fileserver 업로드 client `src/adapters/http/fileserver-upload.ts`와 그 통합 테스트
> 짝 백엔드: `clean-architecture-backend-template` `45d2a478`(읽기만, `git show 45d2a478:<path>`. `config/contracts/backend-contract-pin.json:5`의 pin. 지난 라운드와 같은 커밋)
> 깊게 본 관점: 6, 10, 17, 21, 23, 26, 28
> 영역 판정(35.8): presigned 실행기·vault는 **지정 범위에서 사용 가능**. resumable upload runtime은 **조건부 사용 가능**(제품 backend가 `PRESIGNED_MULTIPART_V1` BFF를 직접 만들 때). 짝 백엔드와 함께 파일 업로드를 출시하는 용도는 **조건부 사용 가능**(Fileserver client. 조건: 재개 없음, 파일 전체를 메모리에 읽음, `MAYBE_APPLIED` 뒤 다시 보내면 파일이 둘 생길 수 있음(백엔드가 키를 읽지 않음. 504 `TRANSFER_TIMEOUT`도 여기 든다), Fileserver 자신의 code 표는 pin 대조 밖, 실제 짝 백엔드로 올려 본 적 없음). image CDN runtime은 **지정 범위에서 사용 가능**(reference runtime 범위).
ID 표기: 이번 라운드 새 발견은 `01-01`부터 쓴다. 라운드 밖에서는 `1106/01-01`이다. 지난 라운드는 `1105/01-01`(2026-11-05), 그 전은 `1103/…`, `1101/…`, `0929/…`다.
## 0. 결론
- **1105 네 건 중 셋은 고쳐졌다.** 1105/01-01(202 `REJECTED`, 빈 파일)과 1105/01-03(`traceId`)은 완료 기준을 코드와 `bbde570` 게이트 실행으로 확인했다. 1105/01-04는 변이 셋(FS4'·FS5·FS8)이 각각 기대한 테스트에서 기대한 이유로 실패했다(배치 01-R1·01-R3·01-R4, 6절).
- **1105/01-02는 일부다(§16.4는 "고침").** 위험한 줄(504 `TRANSFER_TIMEOUT` → `NOT_APPLIED`)은 빠졌다. 되넣으면 테스트 2건이 실패한다(01-R2). 멱등성·web 공통 code는 V3 표 하나로 판정하고 pin 답 표 9행으로 대조한다. 남은 것: Fileserver 자신의 code 표와 Fileserver 계약은 여전히 pin 대조 밖이다(수정이 07-01로 미뤘고 07-01은 넣지 않았다). 커밋 `471b001` 본문의 백엔드 요청 (b)는 "interrupt 확인"이라는 방법으로는 그 보장을 주지 못한다.
- **1103/01-01은 일부 그대로다.** 프론트 몫은 끝났다. 백엔드에 넘긴 두 가지(백엔드 매뉴얼의 짝 안내, `docs/fileserver/http-contract.md:10`의 202 state 목록)는 백엔드 `45d2a478` 코드와 맞게 적혀 있다. 실제 짝 백엔드로 올려 보지 않았다.
- **수정을 백엔드 코드와 다시 대조했다.** 202 `REJECTED` 본문의 `size`·`sha256`·`etag`는 검증 전에 레코드에 적히고 거절 전이가 지우지 않는다. 그래서 client schema를 통과해 `FILE_REJECTED`에 닿는다(2.1절). 503 `RATE_LIMIT_*`가 `NOT_APPLIED`로 바뀐 것도 백엔드 interceptor 위치와 맞다.
- **새 발견 1건, Low·P3 개선 제안(01-01).** 수정이 만든 실패 `FILE_REJECTED`에는 서버 기록과 이을 값이 없다. 성공 Envelope의 `meta.traceId`를 읽지 않고, 백엔드 답에는 거절 이유가 없다.
- **이 영역 수정이 검사를 약하게 만든 곳은 없다.** 테스트 diff는 추가 20건과 기대값 재정의 1행(503 `IDEMPOTENCY_UNAVAILABLE`, 더 보수적인 쪽)이다. 코드에서 손 목록 `MAYBE_APPLIED_CODES`를 V3 판정으로 바꿨지만, 전에 `MAYBE_APPLIED`였던 code는 모두 그대로다(2.2절).
- **오래된 이월 4건(1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05)과 FOLLOW-UP은 남음이다.** `src/adapters/browser-transfer/`와 포트는 `8a44226..bbde570`에서 한 줄도 바뀌지 않았다. README §16.6에는 이 영역 이월이 없다.
- 실행: 내가 직접 돌린 것은 없다. 증거는 `bbde570` CI env 게이트 로그와 snapshot, 그리고 오케스트레이터가 돌린 배치 4건(01-R1~R4)이다. 넷 모두 rc=1이고, 실패한 테스트와 이유가 요청한 기대와 같다. 넷 모두 `restore=clean`이다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. `src/adapters/browser-transfer/` 27파일 12,919줄, 포트 `src/application/ports/browser-transfer/` 5파일 821줄(둘 다 `8a44226`과 같다). client `src/adapters/http/fileserver-upload.ts` 802줄(지난 735줄), 통합 테스트 `tests/integration/fileserver-upload.test.ts` 752줄(지난 557줄) |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree에서 읽기만 했다. `8a44226..bbde570`의 이 영역 커밋: `6608fef`(1105/01-01, 1103/01-01), `471b001`(1105/01-02), `8b92f45`(1105/01-03), `f2f7dc4`(1105/01-04). 합친 뒤 영향: `c6c37f3`(1105/03-02)가 V3 표에 503 `RATE_LIMIT_*`를 더해 client 판정에도 들어왔다. browser-transfer 어댑터·포트·단위 테스트·브라우저 spec 변경 0 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `productionComposition: false`. Fileserver client는 http adapter 배럴 export이고 제품이 capability로 넘긴다(`docs/manual/02-decision-tables.md:338-395`) |
| 필수 요구와 규모·운영 목표 | 사용자 목표: 짝 백엔드 템플릿과 함께 서비스를 빨리 출시한다. 업로드 크기·실패율 목표는 없다. 백엔드 기본 상한과 프론트 기본 정책값을 사실상의 목표로 보았다(지난 라운드와 같다) |
| 읽은 코드·구성 범위 | 전부: `fileserver-upload.ts`, 그 통합 테스트, `git diff 8a44226..bbde570`의 client·테스트·매뉴얼·계약 문서 diff, 커밋 본문 4개. 필요한 부분: `backend-envelope.ts:97-390`, `src/contracts/errors.ts:176-216`, `src/adapters/platform/abortable-operation.ts:90-160`, `config/contracts/backend-contract-pin.json`, `config/contracts/backend-idempotency-answers.json`, `scripts/check-backend-contract-drift.ts`(Fileserver 언급 0), 매뉴얼 `:278-410`, 계약 문서 `:325`, `:360-375`, CHANGELOG `:63`, `:89-103`. 이월 항목 자리(`runtime-policy.ts`, `resumable-upload-runtime.ts:239-246`, `:1045-1049`, `fetch-json-transport.ts:155-168`, `scripts/check-adapter-inventory.ts:135-146`, 포트 `resumable-upload.ts:101-133`). **짝 백엔드**(`45d2a478`, `git show`): `FileUploadController.java:185`, `:196`, `UploadedFileResponse.java:11-29`, `FileView.java`, `FileDescriptor.java`, `FileRecord.java:21-77`, `FileRecordMutation.java:9-40`, `:97-105`, `FinalizeUploadApplicationUseCase.java:129-344`, `:383-423`, 검증기 넷(`LengthVerifier.java:30-37`, `Sha256Verifier`, `FilenamePolicyVerifier`, `MediaTypeVerifier`), `FileserverVerificationConfiguration.java:44-57`, `BlockingTransferExecutor.java` 전체, `FileserverErrorCode.java:45-56`, `UploadFileApplicationUseCase.java:27-79`, `AtomicMoveContentPublisher.java:45-120`, `EnvelopeBodyAdvice.java:88`, `RateLimitWebConfig.java:61-62`, `docs/fileserver/http-contract.md:1-30`, `docs/manual/`(Fileserver 언급 검색) |
| 읽은 문서(주장) | 지난 영역 문서 전체, README §15·§16, 커밋 본문 4개, CHANGELOG 알려진 제한(`:89-103`) |
| 수행한 테스트·실험 | **실행 환경 = desktop 로그와 snapshot + 배치 요청.** 내가 돌린 것은 없다. 쓴 증거(모두 `bbde570`, CI env, 2026-11-06 03:24~03:56): `desktop:/tmp/claude-gates/bbde570-ci/gate-artifacts/FE-GATE-007.txt:9`(`fileserver-upload.test.ts` 68건 통과), `FE-GATE-005.txt`(이 영역 단위 15파일 통과, `:93`~`:290`), `FE-GATE-010` architecture PASS, `FE-GATE-012.txt:88`(file-transfer 레시피 56,130/57,800 gzip B), `FE-GATE-020` removability PASS, junit `r5/snap/merge/artifacts/tests/integration.xml`(03:48, fileserver 68건·실패 0·skip 0). 배치 4건(오케스트레이터, local env, 2026-11-06 04:23, `desktop:/tmp/claude-gates/r5/batch/out/R5-01-R1.log`~`R4.log`): 변이 하나씩, `node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts`, 끝마다 checkout 복원(6절) |
| 실험 조건 | 게이트는 node vitest + MSW다. 출하 client를 그대로 만들고 백엔드 응답은 흉내 냈다. 실제 백엔드·브라우저·네트워크는 쓰지 않았다 |
| 확인하지 못한 범위·이유 | 짝 백엔드를 띄운 업로드(백엔드는 읽기만). 배포 구성에서 성공 본문이 Envelope로 감싸지는지(정적 확인만). `TRANSFER_TIMEOUT` 뒤 늦게 `READY`가 되는 경쟁(재현 안 함). 실제 브라우저에서 Fileserver client(spec 없음). resumable 경로의 실패 뒤 재개·두 탭 경쟁을 브라우저에서(spec은 정상 경로뿐) |
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드의 XA~XF, 변이 14건, 330건 실행은 증거로 쓰지 않았다. README §16.1의 "133개 항목 기대와 일치"도 주장으로만 읽었다. 01-R1·R3·R4는 지난 FS4·FS5·FS8과 같은 자리다. FS4는 `TRANSFER_TIMEOUT`이 목록에서 빠져 `ATOMIC_PUBLISH_UNSUPPORTED`만 뺀다(FS4'). 되넣는 쪽은 01-R2(FS4r)다 |
## 2. 지난 발견 재확인
센 대상은 ID가 있는 발견 9건이다: 1105/01-01~01-04(README §15), 1103/01-01(§16.5), 지난 영역 문서 2절의 남음 4건(§16.6에는 없다). 결과: **고쳐짐 3 · 일부 2 · 남음 4 · 재발 0 · 틀린 발견 0.** FOLLOW-UP과 함께 볼 것은 따로 적었다. 지난 라운드에 고쳐진 5건은 재발 여부만 보았다.
| 지난 ID | 내용 | 상태 | 근거 |
| --- | --- | --- | --- |
| 1105/01-01 (Medium·P2) | 202 `REJECTED`를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "검사 중"으로 적는다 | **고쳐짐** | 완료 기준 셋을 확인했다. ① schema가 `REJECTED`를 받고(`fileserver-upload.ts:236`) 202 `REJECTED`는 `VALIDATION_REJECTED`·`FILE_REJECTED`·`NOT_APPLIED` 실패다(`:681-689`). 빈 파일은 보내지 않고 `FILE_EMPTY`·`NOT_STARTED`다(선언 0 `:475`, 읽은 뒤 0 `:535`). ② 테스트가 202 `VERIFYING`(`fileserver-upload.test.ts:198`), `QUARANTINED`(`:206`), `REJECTED`(`:215-238`)를 각각 본다. 201 `REJECTED`는 여전히 `SCHEMA_MISMATCH`(`:313`), 빈 파일 두 행(`:679-680`). FE-GATE-007과 junit에서 모두 통과했다. ③ 매뉴얼이 `QUARANTINED`의 뜻과 끝나지 않는 대기를 적는다(`02-decision-tables.md:315-319`, `:407`). 백엔드 대조는 2.1절. 실제 백엔드로 올려 보지 않았다(1103/01-01에 남김). 남은 진단 빈틈은 새 01-01 |
| 1105/01-02 (Medium·P2) | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주고, 효과 표가 V3 표·계약 문서와 갈라졌고 pin 밖이다 | **일부 · 백엔드로 넘김**(§16.4는 "고침 · 백엔드로 넘김") | **고친 것.** `TRANSFER_TIMEOUT`이 `NOT_APPLIED_5XX_CODES`에서 빠졌다(`fileserver-upload.ts:194-199`, 이유 `:188-192`). 5xx 기본값 `MAYBE_APPLIED`이고 `createFailure`가 `retryable:false`·`contact-support`로 만든다(`errors.ts:186-189`, `:209-214`). 멱등성 접두 code와 V3 표 행은 `envelopeFailureEffect`로 판정한다(`sharedAnswerEffect` `:207-221`, 호출 `:767`). 테스트: 표 행(`fileserver-upload.test.ts:385`), 전용 테스트(`:456-476`), pin 답 표 9행이 client와 V3가 같은지 본다(`:508-537`, junit 9건 통과). Fileserver 4xx를 `NOT_APPLIED`로 보는 이유는 계약 문서 6.1 한 곳에 있고(`backend-api-and-server-state-contract.md:360-375`), client 주석(`:184-186`)과 매뉴얼(`:409`)이 그곳을 가리킨다. SHA 표기는 pin으로 맞췄다(`:38-42`, `:117-121`, 매뉴얼 `:331`). 완료 기준 ①②는 맞다. ③ "FS4가 실패를 만든다"도 맞다: `TRANSFER_TIMEOUT`을 목록에 되넣은 01-R2에서 504 표 행(effect `NOT_APPLIED`, retryable `true`)과 전용 테스트(action `retry`)가 실패했다(`R5-01-R2.log`, 2건 실패·66건 통과). **남은 것.** (가) pin 밖: 지난 최소 개선 ④의 "pin 대조 대상에 `docs/fileserver/http-contract.md` 추가"를 커밋 `471b001`이 07-01로 미뤘다. 07-01(`daf3474`, `f600e6b`)은 web 계약 §2·§4만 옮겼다. `scripts/check-backend-contract-drift.ts`에 Fileserver 언급이 0이고, pin의 `frontend.readers`는 `backend-envelope.ts` 하나다(`backend-contract-pin.json:44`). 그래서 `NOT_APPLIED_5XX_CODES`(`:194-199`)와 202 state 해석은 사람이 읽은 표 그대로다. CHANGELOG도 이 부분을 "일부"로 적는다(`CHANGELOG.md:103`). (나) 백엔드 요청의 정확성: repo 안 문구는 목표로 적혀 정확하다("`ambiguous` 표시를 주거나 504가 'READY 없음'을 보장", `CHANGELOG.md:100`, README §16.4). 커밋 `471b001` 본문의 방법 (b) "작업 스레드가 게시 rename과 READY 커밋 전에 interrupt를 확인"은 그 보장을 주지 못한다. 대기 스레드는 작업 단계를 보지 않고 시간이 되면 `cancel(true)` 뒤 504를 낸다(백엔드 `BlockingTransferExecutor.java:72-79`). 작업 스레드가 확인을 지난 직후에 시간이 끝나면 504 뒤 `READY`가 그대로 생긴다. 보장하려면 대기 스레드가 "게시 단계에 들어갔다"는 표시를 보고 그때는 모호한 결과로 답하거나 끝까지 기다려야 한다. 이 본문의 재검토 조건("백엔드가 (b)를 고르면 이 줄을 되돌린다")을 글자대로 따르면 좁아진 창으로 원래 결함이 돌아온다. (다) 백엔드 몫: `ambiguous` 표시 또는 보장, `Idempotency-Key`(백엔드 `UploadFileApplicationUseCase.java:40` `NOT_IDEMPOTENT`) |
| 1105/01-03 (Low·P3) | 실패 Envelope의 `traceId`를 버린다 | **고쳐짐** | `envelopeFailure`가 Envelope 전체를 받아 `traceId`를 싣는다(`fileserver-upload.ts:701-708`, `:735-737`). 테스트: Envelope 실패 표 18행 모두 `traceId: "trace-1"`을 본다(`fileserver-upload.test.ts:403`). 없을 때는 키가 없다(`:409-420`). 매뉴얼 `:327`. 완료 기준("Envelope 실패 결과에 `traceId`가 있다")을 맞춘다. 성공 Envelope에서 만든 실패는 범위 밖이었다(새 01-01) |
| 1105/01-04 (Low·P3) | 5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절을 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 셋이 더해졌다: 503 `ATOMIC_PUBLISH_UNSUPPORTED` → `NOT_APPLIED` 행(`fileserver-upload.test.ts:376`), 가짜 `setTimeout`과 `monotonicNow: () => 0`으로 1.5초 뒤 답이 성공하고 credential deadline이 `1_000 + 18 × 1_000`인지 본다(`:580-625`), 선언 크기 초과에서 `stream()`이 불리지 않는다(`:693-705`). deadline은 전역 `setTimeout`을 부를 때 읽으므로 가짜 timer가 실제 경로를 탄다(`abortable-operation.ts:98-100`). 완료 기준("FS4·FS5·FS8이 각각 한 건 이상 실패를 만든다")을 배치로 확인했다. FS4'(01-R1)는 503 `ATOMIC_PUBLISH_UNSUPPORTED` 행이 effect `MAYBE_APPLIED`를 받아 실패했다. FS5(01-R3)는 deadline 테스트가 `{ ok: true }` 대신 `REQUEST_TIMEOUT`·`TIMEOUT`을 받아 실패했다. FS8(01-R4)은 "without reading a byte"가 code `FILE_NOT_READABLE`을 받아 실패했다. 각각 1건 실패·67건 통과이고 다른 테스트는 흔들리지 않았다(6절). FS8의 표 행 "a declared size above maxFileBytes"는 읽는 중 상한 검사로 여전히 통과한다. 그래서 새 전용 테스트가 이 규칙을 지키는 유일한 테스트다 |
| 1103/01-01 (High·P1) | 두 템플릿을 짝으로 쓰면 파일 업로드가 연결되지 않는다 | **일부 · 백엔드로 넘김**(§16.5와 같다) | 프론트 몫: client와 문서 넷은 지난 라운드 그대로다. 이번에 202 state 해석이 백엔드 코드와 맞게 됐다(1105/01-01). MSW 설명도 문서가 아니라 백엔드 코드 기준이다(`fileserver-upload.test.ts:17-35`). 완료 기준의 "두 매뉴얼" 중 백엔드 쪽이 없다: 백엔드 `docs/manual/`의 Fileserver 언급은 모듈 목록 한 칸뿐이다(`45d2a478:docs/manual/03-placement.md:30`). 백엔드 계약은 여전히 `202 VERIFYING`만 적는다(`45d2a478:docs/fileserver/http-contract.md:10`). 넘긴 요청(`CHANGELOG.md:101`, README §16.5)은 이 두 파일을 정확히 가리킨다. 덧붙이면 좋은 것: 추가할 state(`QUARANTINED`·`REJECTED`), 같은 문제가 있는 `POST /v1/files:raw` 행(`:11` "`201`, `202`"), 202 `REJECTED`에 이유가 없다는 점(새 01-01). 검증 방법 2단계(짝 백엔드를 띄운 업로드)는 하지 않았다 |
| 1101/01-03 (Low·P3) | 메모리 상한 식의 copyFactor가 설정값이다 | 남음 | `runtime-policy.ts:12`, `:68`, `:101-107`. 바뀌지 않았다 |
| 0929/01-03 (Low·P3) | 느린 업링크 기본값이 runtime 정책과 실행기에 따로 있다 | 남음 | `resumable-upload-runtime.ts:1045-1049`, `presigned-transfer-executor.ts:141-142`. client도 같은 값을 글자로 복사한다(`fileserver-upload.ts:164-165`) |
| 0929/01-04 (Low·P3) | file-transfer 어댑터만 지우면 게이트가 실패한다 | 남음(정적) | `scripts/check-adapter-inventory.ts:139-144`가 이 영역 4파일을 이름으로 고정한다. 바뀌지 않았다 |
| 0929/01-05 (Low·P3) | `abort()` 실패 recovery에는 행동 표가 없다 | 남음 | 표는 `upload()`에만 있다(`src/application/ports/browser-transfer/resumable-upload.ts:105-127`). 닫힌 runtime의 `abort()`는 `RESUME`이다(`resumable-upload-runtime.ts:241-245`) |
| FOLLOW-UP: `maxPartCount` 바이트 검사가 transport에 넘길 때만 | — | 남음 | `fetch-json-transport.ts:157-167` |
| FOLLOW-UP: 업로드 PUT에 idle 제한 없음 | — | 남음(문서화된 선택) | 바뀌지 않았다 |
| FOLLOW-UP: probe 재사용 테스트가 공개 이미지만 씀 | — | 남음 | `tests/unit/image-cdn-runtime.test.ts:196`, `:311`, `:383`이 `publicAsset()` |
| 1103/01-02 함께 볼 것: object store CORS의 `Retry-After` expose가 handoff 문서에 없다 | — | 남음 | `server-file-capability-infrastructure.md:1666-1673`은 receipt 헤더만 적는다 |
| 1103 D3: `issuePartCapability` 포트 주석 한 줄 | — | 안 함(결정 권고, 발견 아님) | `resumable-upload.ts:212-217`에 없다 |
| 재발 확인: 1103/01-02, 1103/01-03, 1101/01-02, 0929/01-02, spec `PAGE_ORIGIN` | 지난 라운드 고쳐짐 | 고쳐짐 유지 | 코드·테스트 diff 0. 관련 테스트(`resumable-upload-runtime-recovery.test.ts` 46건, `resumable-upload-fetch-transport.test.ts` 34건)가 FE-GATE-005에서 통과했다(`FE-GATE-005.txt:117`, `:164`). 지난 변이 재실행은 하지 않았다. `PAGE_ORIGIN`은 설정에서 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:8-10`) |
### 2.1 1105 수정을 짝 백엔드 `45d2a478` 코드와 대조
| 항목 | 짝 백엔드(코드) | 프론트 client(`bbde570`) | 판정 |
| --- | --- | --- | --- |
| 202 `REJECTED` 본문 | 업로드는 동기 검증이다(`FileUploadController.java:185`). `READY`가 아니면 202(`:196`). 검증 전에 `uploaded(committedOffset, serverDigest)`로 크기·digest를 적는다(`FinalizeUploadApplicationUseCase.java:258`). 거절 전이는 `failure(verdict.code())`라 code만 쓴다(`:322`). mutation은 "적힌 칸만 쓴다"(`FileRecordMutation.java:12`). 본문은 `size=actualSize`, `sha256`, `etag="\"<sha256>\""`, 확인 전 `mediaType=application/octet-stream`(`FileRecord.java:66-77`, `UploadedFileResponse.java:20-29`) | schema가 64자리 hex `sha256`, 1자 이상 `etag`, `size == 보낸 바이트`를 본 뒤 `REJECTED`를 실패로 바꾼다(`fileserver-upload.ts:233-244`, `:672-689`) | 맞다. 비어 있지 않은 거절(예: `LengthVerifier`의 `FILE_TOO_LARGE`, `Sha256Verifier`의 `DIGEST_MALFORMED`, 제품 검증기)이 `FILE_REJECTED`에 닿는다. `sha256`이 비면(`orElse("")`, `FileRecord.java:74`) schema가 막지만 이 경로에서는 늘 채워진다 |
| 빈 파일 | 기본 사슬 첫 검증기가 0바이트를 `REJECT("EMPTY_CONTENT")`(`LengthVerifier.java:35-36`, 사슬 `FileserverVerificationConfiguration.java:48-56`) | 보내기 전 `FILE_EMPTY`(`:474-475`, `:535`) | 맞다. 제품이 사슬을 바꿔 빈 파일을 받게 하면 client를 바꿔야 한다(커밋 `6608fef` 위험 칸. 끄는 설정은 없다) |
| 504 `TRANSFER_TIMEOUT` | 대기 스레드가 `await-seconds` 뒤 `cancel(true)`·504·retryable(`BlockingTransferExecutor.java:62-79`, `FileserverErrorCode.java:55`). READY 커밋 실패는 `AMBIGUOUS_COMPLETION`(`FinalizeUploadApplicationUseCase.java:411-420`) | `MAYBE_APPLIED`, `retryable:false`, `contact-support`. `retryAfterMs: 5000`은 실패에 남는다(`:731`, `errors.ts:198-200`) | 효과는 맞다. 남는 `retryAfterMs`는 매뉴얼이 "자동으로 다시 부르지 않는다"로 정리한다(`02-decision-tables.md:329`). 관점 23에 남김 |
| 남은 `NOT_APPLIED` 5xx 넷 | `PARTIAL_WRITE`(`:49`)는 길이 검사, `ATOMIC_PUBLISH_UNSUPPORTED`(`:53`)는 move 거절(`AtomicMoveContentPublisher.java:51-56`), 게시 뒤 실패는 `AmbiguousCompletionException`(`:89-95`, `:113-120`) | `:194-199` | 맞다(지난 라운드 대조와 같은 커밋) |
| 503 `RATE_LIMIT_*` | interceptor가 모든 경로에 걸리고(`RateLimitWebConfig.java:61-62`) `preHandle`에서 답한다 | V3 표 행이라 `NOT_APPLIED`(`sharedAnswerEffect`, pin 답 표 행 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE` 통과) | 맞다. 이 판정 변화는 `471b001`이 아니라 합친 뒤 `c6c37f3`(1105/03-02)에서 들어왔다. 매뉴얼 `:324`와 계약 문서 `:367-369`는 "V3 표에 있는 답"이라고만 적고, 예로 든 code에 이 둘은 없다 |
| 성공 Envelope `meta` | `Envelope.ok(body, ResponseMetaFactory.fromMdc())`(`EnvelopeBodyAdvice.java:88`). `traceId`는 성공·실패 공통(`docs/web/http-contract.md:53`) | `readSuccessEnvelope`가 `data`·`page`만 돌려준다(`backend-envelope.ts:97-117`) | `FILE_REJECTED`에 `traceId`가 없다(새 01-01) |
### 2.2 수정이 검사를 약하게 만들었는가
`git diff 8a44226..bbde570 -- src/adapters/http/fileserver-upload.ts tests/integration/fileserver-upload.test.ts`를 읽었다.
- 테스트는 +201/−6이다. 지운 6줄은 머리 주석 5줄과 표 1행이다. 지운 단언, 넓힌 허용 목록·정규식, 새 skip, 늘린 시간 제한은 없다. 새 deadline 테스트는 가짜 timer를 쓴다. 실제 시간에 기대는 테스트를 대신한 것이 아니라 더한 것이다(기존 시간 초과 테스트는 그대로다).
- 바뀐 기대값 1행: 503 `IDEMPOTENCY_UNAVAILABLE`이 `NOT_APPLIED`·`retryable:true`에서 `MAYBE_APPLIED`·`retryable:false`로 바뀌었다(`fileserver-upload.test.ts:379`). 지난 01-02 개선 ②(V3 판정을 그대로 쓴다)와 매뉴얼 4절에 맞춘 재정의다. 더 보수적인 쪽이다. 약화가 아니다.
- 코드: 손 목록 `MAYBE_APPLIED_CODES`(넷)를 `AMBIGUOUS_COMPLETION` 비교 하나와 `sharedAnswerEffect`로 바꿨다(`fileserver-upload.ts:207-221`, `:766-767`). 전에 status와 상관없이 `MAYBE_APPLIED`였던 `IDEMPOTENT_IN_FLIGHT`·`IDEMPOTENCY_COMPLETION_UNKNOWN`·`IDEMPOTENCY_RECOVERY_REQUIRED`는 지금도 어떤 status에서나 `MAYBE_APPLIED`다. 표의 status와 맞으면 V3 표가, 아니면 400·409·422 규칙이나 `?? "MAYBE_APPLIED"`(`:220`)가 그렇게 준다. `NOT_APPLIED`로 바뀐 것은 503 `RATE_LIMIT_*` 둘이고 근거는 2.1절이다.
- pin 답 표 테스트(`:508-537`)는 client 결과를 client가 부르는 같은 함수(`envelopeFailureEffect`)와 비교한다. 그래서 V3 표 자체의 옳음은 보지 않는다. 그것은 `tests/unit/backend-contract-pin.test.ts`가 본다(영역 07). 이 테스트가 보는 것은 행마다 client가 V3 판정을 쓰는가이다. 그 목적에는 맞다.
- `?? "MAYBE_APPLIED"` 기본값(`:220`)을 지나는 테스트 행은 없다. pin 표의 9행은 모두 V3 표가 판정한다. 판정을 바꾸지 않는 안전 기본값이라 발견으로 세지 않았다(관점 10에 남김).
## 3. 이번 발견 (36.3)
새 발견 1건: Low 1 / P3 1 / 개선 제안 1. High 이상 0, P1 0.
### 01-01 202 `REJECTED` 실패(`FILE_REJECTED`)에 서버 기록과 이을 값이 없다 — 성공 Envelope의 `meta.traceId`를 읽지 않고, 백엔드 답에는 거절 이유가 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 개선 제안(적힌 계약 위반은 없다. 1103/03-06·1105/01-03 규칙은 실패 Envelope만 말한다). 1105/01-01 수정이 새 실패 종류를 만들면서 생겼다 |
| 관련 관점 | 8, 7, 23, 17, 26 |
| 근거 | **프론트.** 202 `REJECTED`는 `failure("VALIDATION_REJECTED", "FILE_REJECTED", { httpStatus, effect })`로 끝난다(`src/adapters/http/fileserver-upload.ts:681-689`). `failure()`에는 `traceId`가 없다(`:787-800`). `readSuccessEnvelope`는 `data`와 `page`만 돌려주고 `meta.traceId`를 버린다(`src/adapters/http/backend-envelope.ts:97-117`). 같은 client의 Envelope 실패는 싣는다(`fileserver-upload.ts:737`). `fileId`는 1105/01-01 권고대로 싣지 않는다. 테스트는 `traceId`를 보지 않는다(`tests/integration/fileserver-upload.test.ts:215-238`, MSW는 `meta.traceId: "trace-1"`을 보낸다 `:40`, `:89`). 커밋 `8b92f45` 본문이 이 한계를 "V3도 같다"며 적었다. 매뉴얼은 실패 Envelope만 말한다(`docs/manual/02-decision-tables.md:327`). **백엔드.** 성공 Envelope `meta`에도 `traceId`가 있다(`45d2a478:EnvelopeBodyAdvice.java:88`, `docs/web/http-contract.md:53`). 거절 이유는 레코드의 `lastErrorCode`에만 쓰고(`FinalizeUploadApplicationUseCase.java:322`) 응답 7필드에는 없다(`UploadedFileResponse.java:11-29`) |
| 발생 조건 | 빈 파일은 이제 보내기 전에 막힌다. 남은 경우: 제품 검증기가 악성 아닌 이유로 REJECT, servlet 상한을 Fileserver 상한보다 크게 둔 배포의 `FILE_TOO_LARGE`, `DIGEST_MALFORMED` |
| 영향 | 사용자는 "파일이 거절됐다"만 본다. 이유별 문구를 고를 수 없다. 지원 담당은 그 실패를 서버 로그나 `REJECTED` 레코드와 잇지 못한다. 동작·데이터 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 진단 편의. 1105/01-03(Low·P3)과 같은 급이다 |
| 통제·증거 | 이 경로의 trace 전달: M0(경로를 확인했고 싣는 코드가 없다) · E1(두 repo 코드) |
| 확실성과 남은 가정 | 코드로 확정했다. 실제 배포 응답에 `meta.traceId`가 들어 있는지는 백엔드 문서·코드로만 확인했다 |
| 결정의 근거 | [확인한 사실] V3 실행기에는 정상 성공 Envelope을 업무 실패로 바꾸는 경로가 없다. 성공 Envelope에서 나는 실패는 schema 불일치뿐이다. Fileserver client만 정상 답(202 `REJECTED`)을 실패로 바꾼다. [기록된 의도] `8b92f45` "Envelope 실패에만 싣는다". [리뷰어 추론] "V3도 같다"는 schema 불일치에는 맞지만 이 경우에는 맞지 않는다. 서버가 정상으로 답했고 trace 값이 손에 있다 |
| 이해 비용 | 지원 담당이 "왜 거절됐나"에 답하려면 업로드 시각·사용자로 서버 로그를 뒤져야 한다 |
| 최소 개선 방향 | ① `readSuccessEnvelope`가 `readFailureEnvelope`처럼 `traceId`를 함께 돌려주고, `FILE_REJECTED` 실패가 싣는다 ② 백엔드 요청 목록(`CHANGELOG.md:100-101` 줄)에 "202 `REJECTED` 응답에 검증 code를 싣거나 422로 답한다"를 더한다 |
| 대안 비교 | (가) ①만 — 프론트만으로 끝나고 지원 연결이 생긴다. (나) ①+② — 사용자 문구도 이유별로 고를 수 있다. (다) 현상 유지 + 매뉴얼에 "`FILE_REJECTED`는 서버 로그와 잇지 못한다"를 적는다. (나)를 권한다. 프론트 몫은 ①이다 |
| 단순화의 보존 조건 | 적용 제외 — 값을 더하는 변경이다 |
| 비용·부작용 | `readSuccessEnvelope` 반환에 선택 칸 하나, 테스트 단언 하나. V3 호출자는 새 칸을 무시해도 된다 |
| 재검토 조건 | 백엔드가 REJECT를 실패 Envelope로 답하게 바꾸면 ①은 01-03 경로가 덮는다 |
| 완료 기준 | 202 `REJECTED` 결과에 응답의 `traceId`가 있다. 테스트가 본다. 백엔드 요청 목록에 이유 code가 있다 |
| 검증 방법 | 통합 테스트 202 `REJECTED` 행에 `traceId` 단언 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1105/01-01 수정이 만든 빈틈) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 깊게 본 관점이다. 통제는 "목표 / 확인"이다.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | O | M3 / M3 | E2(FE-GATE-005·007) | checkpoint 상태 전이·CAS는 그대로다. client는 입력 검사, 바이트 상한, 빈 파일 거절, deadline 하나, 고정된 결과 객체를 갖는다(`fileserver-upload.ts:410-556`) |
| 2 | 구조적 성숙도 | O | M4 / M4 | E1, FE-GATE-010 PASS | client의 새 import는 같은 http adapter의 `backend-envelope.ts`뿐이다(`fileserver-upload.ts:17-26`). adapter 사이 새 예외 없음 |
| 3 | 변경 용이성 | O | M3 / M3 | E2 | 공통 code 판정이 V3 표 하나로 모였다. 백엔드가 공통 code를 더하면 V3 표 한 곳을 고치면 된다 |
| 4 | 인지 부하 | P | M2 / M2 | E1 | 나아졌다: 공통 code는 한 표다. 남은 것: Fileserver 판정은 client 표·계약 문서 6.1 설명·매뉴얼 세 곳을 함께 읽어야 한다. `maxRetryAfterMs`가 factory 셋에 있다 |
| **5** | 위험 가시성 | P | M2 / M2 | E1 | 504 근거, 빈 파일 가정, 멱등 키, pin 밖 상태가 client 주석·매뉴얼·CHANGELOG에 적혔다(`fileserver-upload.ts:177-192`, `02-decision-tables.md:319`, `:331-335`, `CHANGELOG.md:100-103`). 남은 것: 커밋 본문의 백엔드 방법 (b)가 보장을 주지 못한다(1105/01-02) |
| **6** | 실패 성숙도 | P | M3 / M3 | E2 | 202 `REJECTED`와 `TRANSFER_TIMEOUT`이 고쳐졌다. 남은 것: 헤더 없는 part 단계 429는 `retryable:true`, control plane은 `false`(지난 라운드와 같다). 504 뒤 늦은 `READY`는 백엔드 결정 |
| 7 | 운영 성숙도 | P | M2 / M2 | E1 | client에는 관측 지점이 없고 실패 값만 돌려준다. Envelope 실패는 `traceId`를 싣는다. `FILE_REJECTED`는 싣지 않는다(01-01) |
| 8 | 디버깅 가능성 | P | M2 / M2 | E2 | 1105/01-03 고쳐짐. 남은 것: `FILE_REJECTED`의 trace·이유(01-01), `abort()` recovery의 뜻(0929/01-05) |
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | 갈라진 사본은 늘지 않았다. 같은 사본: `isAbortSignal` 둘, media type 정규식 셋, 업링크 기본값 셋(0929/01-03). 새로 같은 정규식 `/^IDEMPOTEN(?:T\|CY)_/` 두 벌(`fileserver-upload.ts:214`, `backend-envelope.ts:335`, 지금은 같다) |
| **10** | 테스트 성숙도 | P | M3 / M3 | E2(68건, 변이 4/4 검출) | 202 state 셋, 빈 파일, 504, `traceId`, pin 답 표 9행, deadline, 읽기 전 거절을 본다. 변이 FS4'·FS4r·FS5·FS8이 모두 기대한 테스트에서 실패했다(01-R1~R4). 지난 라운드의 생존 셋(FS4·FS5·FS8)이 이번에 모두 잡혔다. 남은 것: `?? "MAYBE_APPLIED"` 기본값을 지나는 행 없음. MSW는 백엔드 코드에서 읽었지만 실제 백엔드가 아니다. client의 브라우저 실행 없음 |
| 11 | 데이터 성숙도 | O | M3 / M3 | E2 | 바뀌지 않았다. 계정 partition, checkpoint allowlist, 재조정 resourceId 유지 |
| 12 | 동시성 성숙도 | P | M3 / M3(탭 하나) | E2 | 바뀌지 않았다. 두 탭 같은 uploadKey 경쟁은 단위 테스트(메모리 lock)뿐이다 |
| 13 | 확장성 | P | M2 / M2 | E1 | 바뀌지 않았다. 발급 요청 `2N+4`, `maxPartCount` 검사는 transport에 넘길 때만. client는 요청 하나에 파일 전체 |
| 14 | 성능 성숙도 | P | M3 / M2 | E2 | copyFactor 설정값(1101/01-03). client는 크기 선언이 없으면 파일의 약 2배를 쓴다(문서화). file-transfer 레시피 56,130/57,800 gzip B(`FE-GATE-012.txt:88`, 지난 라운드 미검증이 닫힘) |
| 15 | 보안 성숙도 | O | M4 / M3 | E2 | 전송 규칙(`credentials`, 증명 헤더 허용, `redirect:"error"`, `no-referrer`, `no-store`, 응답 상한, 이름 escape)은 바뀌지 않았고 테스트가 통과했다 |
| 16 | 의존성 성숙도 | O | M2 / M2 | E1 | 새 패키지 없음. 테스트가 `zod`를 직접 import한다(`fileserver-upload.test.ts:7`). lint 통과 |
| **17** | API / Contract 성숙도 | P | M3 / M2~M3 | E1, E2 | 공통 code는 pin 답 표로 M3이 됐다. 남은 것: Fileserver code 표·202 state 해석은 pin 대조 밖 M2(1105/01-02), 백엔드 계약 문서는 202 `VERIFYING`만 적는다(1103/01-01, 백엔드 몫), `abort()` 표 없음(0929/01-05) |
| 18 | 배포 성숙도 | O | M3 / M3 | E2 | 바뀌지 않았다 |
| 19 | 설정 성숙도 | P | M2 / M2 | E1 | 남은 것: 업링크 기본값 세 곳, copyFactor. 빈 파일 거절은 백엔드 기본 사슬을 가정하고 끄는 설정이 없다(문서화) |
| 20 | 개발자 경험 | P | M2 / M2 | E1 | 매뉴얼 7절이 202 state 셋, `FILE_EMPTY`, 504, 공통 code, `traceId`를 적는다(`02-decision-tables.md:313-335`). 남은 것: 백엔드 매뉴얼 안내 없음, tus client 없음 |
| **21** | Guardrail 성숙도 | P | M3 / M2~M3 | E2 | pin 답 표 행마다 client와 V3를 대조한다(M3). 남은 것: Fileserver 계약은 drift 검사 밖(`check-backend-contract-drift.ts` Fileserver 0, pin `readers` 하나), 게이트가 이 영역 파일 이름을 고정(0929/01-04) |
| 22 | 추상화 성숙도 | O | M3 / M3 | E1 | client는 의존성을 받는 factory다. 새 포트 없음. FE-GATE-020 PASS |
| **23** | 일관성 | P | M2 / M2 | E1, E2 | 공통 code는 client와 V3가 같다. 남은 것: 헤더 없는 429(part `true` / control plane `false`), 닫힌 runtime의 `upload()` `NONE` / `abort()` `RESUME`, `TRANSFER_TIMEOUT` 실패에 `retryable:false`와 `retryAfterMs:5000`이 함께 남음(409 `IDEMPOTENT_IN_FLIGHT`에서는 같은 칸이 "같은 키로 기다렸다 다시"의 뜻이다. 매뉴얼 `:329`가 구분한다), `traceId`가 Envelope 실패에만(01-01) |
| 24 | 네이밍 / 의미 성숙도 | P | M2 / M2 | E1 | `REJECTED`가 이제 `FILE_REJECTED`로 나온다. 남은 것: 같은 이름 `maxRetryAfterMs` 셋, `abort()`의 `RESUME` 뜻 |
| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 |
| **26** | Ownership 성숙도 | P | M1 / M1 | E1 | 백엔드 요청이 CHANGELOG 알려진 제한 두 줄로 남았다(`CHANGELOG.md:100-101`). 남은 것: 백엔드 쪽 담당·기록 자리가 없다. Fileserver 계약 대조의 주인이 없다(pin은 web 계약만). 커밋 본문의 방법 (b)가 부정확하다 |
| 27 | 삭제 가능성 | P | M3 / 레시피 단위 M0 | E2(FE-GATE-020 PASS) | client는 browser-file-storage·file-transfer 레시피 제거 드릴 뒤에도 남는다. 어댑터만 지우면 게이트가 실패한다(0929/01-04) |
| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | 504 뒤 자동 재전송 권고가 없어졌다. 남은 것: 재개 없음(문서화), `MAYBE_APPLIED` 뒤 재전송은 백엔드가 키를 읽지 않아 중복 가능(문서화), 504 뒤 늦은 `READY`는 백엔드 결정 |
충족 O 8 · 부분 충족 P 19 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1. 지난 라운드와 같은 분포다. 10은 변이 검출이 4/4가 됐지만, 실제 백엔드·브라우저 실행이 없어 P로 둔다.
## 5. 미검증
| 범위 | 이유 | 확인 방법 |
| --- | --- | --- |
| 짝 백엔드를 띄운 업로드(201, 202 `QUARANTINED`·`REJECTED`, 413 두 code, 실패 Envelope, 성공 `meta.traceId`) | 백엔드는 읽기만 한다 | 백엔드 기본 구성 + 프론트 client로 파일 넷(정상, 이름·타입 불일치, 상한 초과, 제품 검증기 거절)을 올린다 |
| 배포 구성에서 Fileserver 성공 본문이 Envelope로 감싸지는지 | 정적 확인뿐(`EnvelopeBodyAdvice.java:88`) | 위 실행에서 응답 원문 |
| `TRANSFER_TIMEOUT` 뒤 작업이 늦게 `READY`가 되는 경쟁 | 재현 안 함 | 백엔드 `await-seconds`를 1초로, 검증기에 지연을 넣고 업로드 |
| client를 실제 브라우저에서(`Uint8Array` 본문, 비ASCII 파일 이름, CORS preflight) | spec 없음 | capability spec 하나 |
| resumable 경로의 실패 뒤 재개·두 탭 경쟁을 실제 브라우저에서 | 브라우저 spec은 정상 경로뿐 | 실패 주입 spec |
## 6. 실행 기록
내가 직접 돌린 명령은 없다. 노트북에서는 읽기만 했다(`git show`, `git diff`, `git grep`, `git apply --check`). desktop에서는 `/tmp/claude-gates/` 아래 파일만 읽었다. 변이 실행은 오케스트레이터가 배치로 돌렸다(아래).
쓴 게이트 출력(`bbde570`, CI env, 2026-11-06 03:24~03:56, `desktop:/tmp/claude-gates/bbde570-ci/`):
| 출처 | 결과 | 쓰인 곳 |
| --- | --- | --- |
| `FE-GATE-007.log`, `gate-artifacts/FE-GATE-007.txt:9` | integration PASS. `tests/integration/fileserver-upload.test.ts` 68건 ✓ | 1105/01-01·01-02·01-03 고쳐진 동작 |
| `r5/snap/merge/artifacts/tests/integration.xml`(03:48) | fileserver 스위트 68건, 실패 0, skip 0. 새 테스트 이름(202 `QUARANTINED`·`REJECTED`, 201 `REJECTED`, `ATOMIC_PUBLISH_UNSUPPORTED`, `TRANSFER_TIMEOUT` 둘, `traceId` 없음, pin 답 표 9행, deadline, 빈 파일 둘, 읽기 전 거절) 모두 있다 | 2절 |
| `gate-artifacts/FE-GATE-005.txt` | unit PASS. 이 영역 단위 15파일 ✓(`:93`~`:290`) | 재발 확인 |
| `FE-GATE-010.log` | architecture PASS | 관점 2 |
| `gate-artifacts/FE-GATE-012.txt:88` | file-transfer 56,130/57,800 gzip B | 관점 14 |
| `FE-GATE-020.log` | removability PASS | 관점 22, 27 |
배치 요청은 `scratchpad/r5/requests/01.md`에 있다. 패치는 `requests/01-R1.patch`~`01-R4.patch`이고, 모두 `git apply --check`를 통과했다.
- 실행: 오케스트레이터가 `bbde570`에서 한 항목씩 돌렸다. 2026-11-06 04:23, local env, 부하 2.66~2.88.
- 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-01-R1.log`~`R5-01-R4.log`(읽기만). 네 로그 모두 머리에 `head bbde570796b0…`, 끝에 `rc=1 restore=clean`이 있다.
- 명령: 넷 모두 `node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts`다.
- 변이 없는 실행은 따로 돌리지 않았다. FE-GATE-007(CI env, 68건 통과)로 대신한다.
| ID | 변이 | 기대 | rc | 결과 |
| --- | --- | --- | --- | --- |
| 01-R1 | FS4': `NOT_APPLIED_5XX_CODES`에서 `ATOMIC_PUBLISH_UNSUPPORTED` 줄 삭제(`fileserver-upload.ts:196`) | 1건 실패: 503 `ATOMIC_PUBLISH_UNSUPPORTED` 행이 `MAYBE_APPLIED`를 받음 | 1 | **기대대로.** 1 failed · 67 passed. "503 'ATOMIC_PUBLISH_UNSUPPORTED' → 'SERVER_FAILURE', 'NOT_APPLIED', retryable false"에서 기대 `effect: "NOT_APPLIED"`, 받은 값 `"MAYBE_APPLIED"`(`fileserver-upload.test.ts:393`) |
| 01-R2 | FS4r: 같은 목록에 `TRANSFER_TIMEOUT` 되넣음 | 2건 실패: 504 표 행과 전용 테스트가 `NOT_APPLIED`를 받음 | 1 | **기대대로.** 2 failed · 66 passed. 표 행 "504 'TRANSFER_TIMEOUT' → …"에서 받은 값 `effect: "NOT_APPLIED"`, `retryable: true`(`:393`). 전용 테스트 "504 TRANSFER_TIMEOUT is an unknown result …"에서 받은 값 `action: "retry"`, `effect: "NOT_APPLIED"`, `retryable: true`(`:466`) |
| 01-R3 | FS5: deadline 식의 바이트 비례 몫에 0을 곱함(`:253-257`) | 1건 실패: deadline 테스트가 `REQUEST_TIMEOUT` 또는 `deadlineAtMonotonicMs` 1000을 받음 | 1 | **기대대로.** 1 failed · 67 passed. "adds the file's transfer allowance to the base deadline"이 `{ ok: true, value: … }` 대신 `{ ok: false, kind: "REQUEST_TIMEOUT", code: "TIMEOUT", effect: "MAYBE_APPLIED" }`를 받았다(`:615`). 첫 단언에서 멈춰 credential deadline 단언까지는 가지 않았다 |
| 01-R4 | FS8: `declared > maxFileBytes` 읽기 전 거절 블록 삭제(`:467-470`) | 1건 실패: "without reading a byte"가 `FILE_NOT_READABLE`·`stream` 호출을 받음 | 1 | **기대대로.** 1 failed · 67 passed. "refuses a declared size above maxFileBytes without reading a byte"에서 기대 code `FILE_TOO_LARGE`, 받은 값 `FILE_NOT_READABLE`(`:700`). 표 행 "a declared size above maxFileBytes"는 통과했다(요청의 예상대로) |
변이마다 실패한 테스트는 요청이 이름 댄 것뿐이었고, 나머지 66~67건은 통과했다. 그래서 네 변이 모두 검사가 동작한다는 증거다(BRIEF 2.4 기준).
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
| --- | --- | --- | --- | --- |
| 01-01 | Low·P3 | 개선 제안 | 202 `REJECTED` 실패(`FILE_REJECTED`)에 성공 Envelope의 `traceId`가 없고, 백엔드 답에는 거절 이유가 없어 서버 기록과 잇지 못한다 | `src/adapters/http/fileserver-upload.ts:681-689`, `:787-800`; `src/adapters/http/backend-envelope.ts:97-117`; 백엔드 `UploadedFileResponse.java:11-29` |
@@ -0,0 +1,177 @@
# 영역 02 — adapters: browser-files · cache-storage · cross-context-invalidation
> 검토일 2026-11-06 · 기준 `bbde570` · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로 `src/adapters/browser-files/`, `src/adapters/cache-storage/`, `src/adapters/cross-context-invalidation/`. 함께 본 것: 포트 `src/application/ports/browser-file-storage/cache-storage-ports.ts`, 레시피 `recipes/frontend-capabilities/browser-file-session-capability.ts`, 조립 `src/bootstrap/runtime-adapters.ts`·`product-composition-contract.ts`, scope `src/adapters/query-cache/server-state-scope-runtime.ts`, 진단 계약 `src/contracts/diagnostics.ts`·`scripts/check-diagnostics.ts`
> 깊게 본 관점 6, 8, 10, 11, 17, 18, 24, 28
> 이번 라운드 렌즈: 1105 수정 4건과 이월 수정 2건이 완료 기준까지 갔는가. 수정이 검사를 약하게 하거나 새 결함을 만들었는가
> 영역 판정(35.8): cross-context-invalidation **지정 범위에서 사용 가능** · cache-storage **조건부 사용 가능** · browser-files **조건부 사용 가능** · 이 영역 제거 드릴(FE-GATE-020) **통과**(0절)
ID 표기: 이번 라운드 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-11-05) 발견은 `1105/02-01`, 그 전은 `1103/…`, `1101/…`, `0929/…`로 쓴다.
실행 증거의 출처: 리뷰어는 laptop과 desktop 어디에서도 아무것도 돌리지 않았다(BRIEF 2절). 게이트 결과는 오케스트레이터의 CI env 실행(`desktop:/tmp/claude-gates/bbde570-ci/`, 2026-11-06 03:24~03:56)과 그 snapshot(`desktop:/tmp/claude-gates/r5/snap/merge/`)을 인용한다. 변이 8개와 실험 1개는 요청 `02-R1`~`02-R9`로 넘겼다. 오케스트레이터가 2026-11-06 04:32에 `bbde570`에서 하나씩 돌렸고, 항목마다 checkout을 깨끗하게 되돌렸다(로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-02-R1.log`~`R5-02-R9.log`). 9개 모두 기대와 맞았다(6.2절).
## 0. 결론
- **1105 새 발견 4건 중 3건은 고쳐졌고 1건은 일부다.** 02-01(`f738348`)·02-03(`d31c7d6`)·02-04(`56c0bd0`)는 완료 기준의 코드와 테스트가 있다. 그 테스트가 `bbde570`에서 통과한다(FE-GATE-005·007). 고친 규칙을 바꾼 변이 6개가 모두 그 테스트에서 기대한 이유로 실패했다(02-R2~R5, 02-R8, 02-R9).
- **1105/02-02는 일부다.** asset entry는 이제 같은 manifest stage가 다시 쓴다. 완료 기준 시나리오(E-1a·E-1c) 테스트가 통과한다(`tests/unit/public-response-cache-repair.test.ts:482-509`, `:634-654`). 그런데 같은 후보 cache의 **release marker** 본문이 계속 읽히지 않으면 여전히 돌아올 길이 없다. stage가 marker 읽기 실패에서 멈추기 때문이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:463-468`). rollback 대상은 되돌릴 수 없고, 활성 release는 모든 asset 조회가 실패한다. 설계 문서와 포트 주석은 "rollback 대상과 서비스 중 release도 다시 stage로 돌아온다"고 넓게 적는다. 실험 02-R1 X1·X2가 확인했다. rollback 대상은 activate, 같은 manifest stage(fetch 0), cleanup(삭제 0), 다시 activate가 모두 `UNAVAILABLE`/`RETRY`이고 marker는 한 번도 다시 쓰이지 않는다. 활성 release는 두 asset 조회와 재stage가 모두 실패하고, 새 release를 배포해야 조회가 돌아온다.
- **02-04의 "`INTEGRITY_FAILED` 제거는 동등 변이" 주장은 맞다.** 판정을 쓰는 곳은 셋이다(stage `:482-507`, activation `:682-712`, inspect `:913-925`). `INTEGRITY_FAILED`가 목록 밖으로 가면 판정이 `UNREADABLE`이 된다. stage는 둘 다 다시 쓴다. activation은 둘 다 `{INTEGRITY_FAILED, CACHE_ACTIVATE, retryable:false, REHYDRATE}`를 준다. inspect는 둘 다 `verified:false`다. 다른 것은 바깥 결과 객체의 freeze 여부 하나다. 포트로는 보이지 않는다(2절).
- **02-01이 계약에 더한 진단 키 `scope_participant`는 맞게 들어갔다.** 분류는 `topology`이고 값 정책 `isScopeParticipantLabel`이 붙었다. `operation_id`와 같은 방식이다(`src/contracts/diagnostics.ts:77`, `:96`, `:114`, `:125`). 제품 label은 조립이 `TypeError`로 거르고(`src/bootstrap/runtime-adapters.ts:713-722`), runtime이 기록 전에 한 번 더 거른다(`server-state-scope-runtime.ts:308`). telemetry 허용 목록에는 없다. 그래서 진단 밖으로 나가지 않는다. `check:diagnostics`가 키마다 분류를 요구한다(`scripts/check-diagnostics.ts:54-58`). 남은 것은 작다. label이 겹쳐도 막지 않는다. 값 정책만 지우는 변이는 잡는 테스트가 없지만, 호출부가 먼저 거르므로 동작은 같다.
- **이월 5건:** 1101/02-04는 고쳐졌다(N38 변이가 새 테스트에서 실패한다, 02-R7). 0929/02-02는 일부다(M05 변이가 새 테스트에서 실패한다, 02-R6. `signal`과 판정 불가 칸은 결정 대기). 1101/02-02는 일부 그대로다(코드 변화 0줄, 결정 대기). 0929/02-06은 남음이다(결정 대기). 0929/02-03(CHANGELOG 0.2.0 행)은 남음이다. 이 항목은 README 16.6절 목록에서 빠졌다.
- **새 발견 1건(Low·P3):** 02-01. control cache의 active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈춘다. adapter API 안에서는 돌아올 길이 없다. 0929/02-01은 손상 pointer(`CORRUPT_DATA`)만 풀었고, 1105/02-02는 asset entry만 풀었다. 수정이 만든 결함은 아니다. 이전 라운드가 보고하지 않았다. 실험 02-R1 X3이 확인했다. 새 release stage만 성공하고, 그 activate·cleanup·inspect·조회·현재 release activate는 모두 `UNAVAILABLE`/`RETRY`이며 pointer는 한 번도 다시 쓰이지 않는다.
- **검사를 약하게 한 수정은 찾지 못했다.** `git diff 8a44226..bbde570`에서 이 영역 테스트의 지운 단언은 1103/02-02 테스트의 "다시 stage는 fetch 0으로 실패" 하나다(`public-response-cache-repair.test.ts:180-242`). 1105/02-02가 바꾸기로 한 동작이다. 반대 방향 단언(fetch 2, 다음 activate 성공)으로 바뀌었다. 추가된 skip·only·timeout은 0건이다. 번들 예산은 그대로다(`config/recipes/frontend-capability-recipes.json:149`, `:198` 변경 없음).
| ID | 심각도·우선순위 | 한 줄 |
| --- | --- | --- |
| 02-01 | Low · P3 | active pointer 본문이 계속 읽히지 않으면 Cache Storage 관리가 모두 멈추고 API 안에서 돌아올 길이 없다 |
**영역 판정 (35.8)**
- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** `8a44226` 뒤 소스 변경이 없다(`git diff --stat` 0줄). 세 라운드 살아남은 N38(host `storageArea` 비교)에 테스트가 생겼다(`tests/unit/cross-tab-invalidation.test.ts:392`). 실제 BroadcastChannel·localStorage 경로가 3엔진에서 통과한다(snapshot `browser-capabilities/results.xml`, `cross-context-invalidation.spec.ts` 2건 × 3, 실패 0).
- cache-storage(service-worker-pwa 레시피, 미조립): **조건부 사용 가능.** 지난 조건 하나가 풀렸다. 계속 읽히지 않는 asset entry는 이제 같은 manifest stage 한 번으로 돌아온다. 남은 조건은 둘이다. 정적 release 조합에만 쓴다. release marker나 active pointer의 본문이 계속 `UNAVAILABLE`/`NOT_READABLE`이면 그 cache(marker면 그 release cache, pointer면 control cache)를 지우고 다시 배포하는 절차를 제품이 정한다(1105/02-02 남은 부분, 02-01).
- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 지난 조건 "제품 closer는 던지지 않게 쓴다"가 풀렸다. 던지면 이제 그 label로 진단이 남는다. 새 조건은 label을 소문자 kebab-case 토큰으로 쓰는 것이다(어기면 부팅에서 `TypeError`, 문서에 있음). 남은 조건은 download 정책의 media type과 확장자 짝을 제품이 직접 검토하는 것이다(`1101/02-02`).
- 템플릿 CI의 FE-GATE-020: **통과.** CI env 실행 rc=0, 1,237초(`bbde570-ci/summary.txt`). junit `browser-file-storage-runtime-removal.xml` 7/7(03:43), `optional-recipe-removal.xml` 6/6(03:41), 모두 `failures="0"`. 실제 Gitea 러너에서는 돌리지 않았다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 02: `src/adapters/browser-files/` 10파일 4,840줄, `src/adapters/cache-storage/` 5파일 2,365줄, `src/adapters/cross-context-invalidation/` 3파일 1,062줄. 그리고 scope participant 경로(조립·scope runtime)와 그것이 더한 진단 계약 키 |
| 커밋·작업 상태·확인 시점 | `bbde570`(laptop worktree, HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`). 2026-11-06. 지난 기준 `8a44226` 뒤 이 영역을 바꾼 커밋: `f738348`(1105/02-01), `8e9fb1f`(1105/02-02), `d31c7d6`(1105/02-03), `56c0bd0`(1105/02-04), `11a0fd0`(1101/02-04), `f2a4f32`(0929/02-02). `src/adapters/browser-files/`·`cross-context-invalidation/`의 소스 변경은 0줄이다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker, SSR 없음. cross-context는 기본 조립이다. cache-storage는 service-worker-pwa, browser-files는 file-transfer 레시피의 `AVAILABLE_NOT_COMPOSED` runtime이다. 공개 경계는 배럴 세 개다 |
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 본다(지난 라운드와 같다) |
| 읽은 코드·구성 범위 | 이 영역의 `8a44226..bbde570` 차이 전체. cache adapter의 조회·stage·activation·cleanup·inspect·`verifyReleaseCandidate`·`readMarker`·`readActivePointer` 전체, `public-cache-response-validation.ts`·`public-cache-codec.ts`의 실패 변환, `browser-file-storage/result.ts:17-96`. `server-state-scope-runtime.ts` 전체, `runtime-adapters.ts:430-460`·`:700-740`, `diagnostics.ts` 전체, `scripts/check-diagnostics.ts` 전체, 바뀐 테스트 5파일 |
| 읽은 설정·문서(주장) | `docs/architecture/browser-file-and-origin-storage.md:370-384`·`:450-457`·`:966-985`·`:996-1017`, `docs/manual/03-outside-feature-folder.md:117-124`, 포트 주석 `cache-storage-ports.ts:42-74`, `CHANGELOG.md:29`·`:68`·`:418`, 각 수정 커밋 본문, 2026-11-05 README 15·16절과 영역 문서 |
| 수행한 테스트·실험 | ① 오케스트레이터 CI env 실행(`bbde570`): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(host user namespace, 이 영역과 무관). ② snapshot junit(03:24 뒤 파일만): `coverage.xml`·`unit.xml`·`optional-recipes.xml`·`browser-capabilities/results.xml`·제거 드릴 2개. ③ 배치 `02-R1`(실험 3건, rc=0, 3건 모두 예측과 같음), `02-R2`~`02-R9`(변이 8개, 모두 rc=1, 기대한 테스트에서 기대한 이유로 실패). 오케스트레이터 실행, local env, 2026-11-06 04:32 |
| 확인하지 못한 범위·이유 | 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지. 레시피를 조립한 실제 화면. 실제 Gitea 러너. 02-01의 초기 JS +251 B(측정은 수정 세션 몫, 5절) |
| 이전 리뷰와 비교 가능한 범위 | 변이 F0202-cor·-pol·-lim·-notreadable, M05, N38은 지난 라운드와 같은 규칙을 같은 방식으로 바꾼다. 지난 라운드 실행 결과(02-R1, E-1~E-3)는 현재 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
| 지난 ID | 내용 | 상태 | 근거 |
| --- | --- | --- | --- |
| `1105/02-01` | 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | **고쳐짐** | 완료 기준 ① "던지는 제품 closer 뒤 그 `label`이 담긴 기록 하나": 실제 `createRuntimeAdapters`와 실제 진단 adapter로 `{operation:"SCOPE_RESET", reason:"PARTICIPANT_FAILED", error_kind:"ERROR", scope_participant:"broken-closer"}` 한 건을 `toEqual`로 고정한다. 재시도마다 한 건 더 남는 것도 본다(`tests/unit/runtime-adapters-product-scope-participants.test.ts:160-197`). ② "template participant 실패도 기록": 같은 기록 함수가 모든 participant에 쓰인다(`src/adapters/query-cache/server-state-scope-runtime.ts:176-183`, `:294-314`). template participant도 같은 목록에 있다(`runtime-adapters.ts:440-446`, `:453-461`). scope runtime 테스트가 participant 실패·cache reset 실패·세대 활성화 실패를 각각 고정한다(`server-state-scope-runtime.test.ts:132`, `:171`, `:239`). 두 파일이 `bbde570`에서 통과한다(FE-GATE-005 `:91`, `:126`). 형식 밖 label은 부팅에서 거절된다(`runtime-adapters.ts:713-722`, 테스트 `:199`). 문서: 설계 `browser-file-and-origin-storage.md:379-382`, 매뉴얼 `03-outside-feature-folder.md:122-123`, CHANGELOG 먼저 할 일 6단계(`CHANGELOG.md:29`)와 [계약] 행(`:68`). 진단 키 판단은 0절. 1103/02-01의 "하나가 실패해도 나머지를 부르고 READY로 가지 않는다"는 그대로다(`runtime-adapters-product-scope-participants.test.ts:137-158`). 남은 작은 것: label 중복을 막지 않는다(제품이 `conditional-validators`를 써도 통과). CHANGELOG [계약] 행에 BREAKING 표시가 없다(먼저 할 일에는 있다. 영역 14에 넘긴다). 변이 02-R9(진단에서 `scope_participant`를 지움)가 두 테스트에서 그 칸이 빠져 실패했다(`runtime-adapters-product-scope-participants.test.ts:183`, `server-state-scope-runtime.test.ts:166`) |
| `1105/02-02` | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | **일부** | 고쳐진 것: 판정 `UNREADABLE`이 생겼다. stage는 이것도 모든 asset을 다시 받아 덮어쓴다(`public-response-cache-adapter.ts:1099-1104`, `:1167-1170`, `:500-507`). activation은 code를 그대로 두고 recovery만 `REHYDRATE`로 준다(`:695-705`). 완료 기준 "E-1a·E-1c에서 같은 manifest stage가 후보를 고치고 다음 activate(rollback 포함)가 성공": 테스트가 있다(`public-response-cache-repair.test.ts:482-509` E-1a·E-1b, `:634-654` E-1c, `:656-686` E-1d). 25건 통과(FE-GATE-005 `:118`). **남은 것: release marker.** marker는 같은 후보 cache 안의 entry다. stage는 이미 있는 후보의 marker 읽기가 `CORRUPT_DATA` 밖의 실패면 바로 실패를 돌려준다(`:463-468`, STO-RR-04). 그래서 marker 본문이 계속 읽히지 않으면 다시 stage해도 marker를 다시 쓰지 않는다. activation도 marker 실패를 `RETRY`로 돌려준다(`:666-668`). 조회는 활성 release의 모든 asset에서 marker를 읽다 실패한다(`:286-297`). cleanup은 pointer가 가리키는 cache를 지우지 않는다(`:826-845`). 결과는 지난 E-1과 같은 모양이다. 새 후보는 cleanup 뒤 다시 stage해야 하고, rollback 대상은 되돌릴 수 없고, 활성 release는 새 release를 배포해야 돌아온다. STO-RR-04 주석이 막으려던 것은 삭제다(`:464-466`). 이미 있는 후보는 실패해도 지우지 않는다(`:585-587`). 그래서 1105/02-02의 "덮어쓰기는 삭제가 아니다" 논리가 marker에도 그대로 맞는데 적용하지 않았다. 문서가 범위를 넓게 적는다. 설계 문서는 "rollback 대상 release와 서비스 중인 release도 같다"고 적는다(`browser-file-and-origin-storage.md:979-982`). 포트 주석은 "a failed body read or lookup"을 "staging the same manifest again rewrites either"로 적는다(`cache-storage-ports.ts:66-69`). 그런데 `cache.match` 자체의 실패는 stage가 다시 쓰지 않는다(`:492-499`, 설계 문서 `:983-984`는 이것을 맞게 적는다). 실험 02-R1 X1(rollback 대상 marker)·X2(활성 release marker)가 이 경로를 그대로 보였다(6.2절). 심각도는 원래대로 Low·P3다 |
| `1105/02-03` | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | **고쳐짐** | 완료 기준 ① 주석이 매뉴얼과 같은 파일을 가리킨다: `recipes/frontend-capabilities/browser-file-session-capability.ts:21-33`이 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`를 예로 들고 `declare module`을 쓰지 말라고 적는다. 매뉴얼 `03-outside-feature-folder.md:118-119`와 같다. ② 레시피 테스트가 capability를 기능까지 넘긴다: 조립이 `capabilities: { files }`를 돌려주고(`tests/recipes/browser-file-session-capability.test.ts:149`), 템플릿이 기능 loader에 넘긴 객체를 기록해(`:156-171`) 그 객체의 `files.current()`로 모든 동작을 돈다(`:230-239`, `:258-309`). FE-GATE-007 `:103` 통과. `needs`로 고르는 마지막 단계는 기존 테스트가 본다(`tests/contract/reusable-capability/feature-adapter-composition.test.ts:166`). 변이 02-R8(조립에서 `...product.capabilities`를 지움)이 `Features did not receive the files capability`로 실패했다(`:238`) |
| `1105/02-04` | 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다 | **고쳐짐** | 표 테스트 6행이 생겼다(`public-response-cache-repair.test.ts:541-597`). 행마다 activate의 code와 `REHYDRATE`, 다음 stage의 fetch 2, 그 뒤 activate 성공을 본다. 정적 대조: `CORRUPT_DATA`를 빼면 `DataError` 행의 activate code가 `CORRUPT_DATA`가 된다. `POLICY_REJECTED`·`LIMIT_EXCEEDED`도 같다(`UNREADABLE`이 원래 code를 돌려준다, `:695-705`). `NOT_READABLE`을 더하면 그 행과 E-1b 행이 `INTEGRITY_FAILED`를 받는다. 완료 기준의 F0202-int는 이제 동등 변이다. 근거: `INTEGRITY_FAILED`는 `failureForCode`가 `{INTEGRITY_FAILED, retryable:false, REHYDRATE}`로 만든다(`public-cache-codec.ts:592-595`). 목록 밖이면 판정이 `UNREADABLE`이고 activation이 그것을 `CACHE_ACTIVATE`로 옮긴다(`:698-704`, `:1213-1221`). 목록 안이면 `browserDataFailure("INTEGRITY_FAILED","CACHE_ACTIVATE",{recovery:"REHYDRATE"})`다(`:706-711`, `result.ts:17-31`). 두 결과의 칸과 값이 같다. stage(`:489-507`)와 inspect(`:923`)는 두 판정을 같게 다룬다. 다른 것은 바깥 결과 객체의 freeze 여부뿐이다. 이 동등은 1105/02-02의 `UNREADABLE` 다시 쓰기에 기대고 있다. 그 동작이 바뀌면 표의 첫 행이 다시 이 경계를 잡는다. 변이 검출: 02-R2·R3·R4는 해당 행이 activate code `CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 받아 실패했다(`:586`). 02-R5는 `NotReadableError` 두 행(E-1b와 표)이 `INTEGRITY_FAILED`를 받아 실패했다(`:502`, `:586`). 완료 기준의 다섯 변이 중 동등 변이 하나를 뺀 넷이 모두 검출된다 |
| `1101/02-04` | 보호 규칙 7개가 변이에서 살아남는다(남은 것 ② N38 host `storageArea` 비교) | **고쳐짐** | 테스트 "takes a storage pulse only from the localStorage object it captured"(`tests/unit/cross-tab-invalidation.test.ts:392-481`)가 BroadcastChannel 없는 host 둘로 storage pulse만 쓴다. sessionStorage 이벤트와 모양만 같은 다른 객체의 이벤트는 받지 않고, 캡처한 localStorage 이벤트는 한 번 받는다. 비교 코드는 그대로다(`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:289-295`). N38(항상 `EXPECTED_LOCAL_STORAGE`)이면 sessionStorage 이벤트가 전달되어 `not.toHaveBeenCalled()`가 실패해야 한다. 19건 통과(FE-GATE-005 `:228`). 변이 02-R7이 이 테스트에서 실패했다. sessionStorage 이벤트와 모양만 같은 객체의 이벤트, 2건이 전달됐다(`:471`). 같은 파일의 core 단위 테스트 "rejects storage pulses from another or unknown storage area"는 변이에서도 통과했다. 그래서 N38을 잡는 것은 이 host 테스트 하나다. 나머지 ①·③~⑦은 지난 라운드에 검출됐고 이번 diff에서 그 코드가 바뀌지 않았다 |
| `0929/02-02` | `inspect()`의 비용·취소·판정 불가가 포트 계약에 없다 | **일부** | 고쳐진 것: 포트 주석이 비용(cache 수 × entry 수, cursor·deadline·signal 없음)과 `verified`의 뜻을 적는다(`cache-storage-ports.ts:55-70`). 테스트가 본문을 못 읽는 후보와 `cache.match`가 던지는 후보를 `verified:false`로 고정한다(`public-response-cache-repair.test.ts:599-632`). M05(판정 불가를 `verified:true`로)가 이 테스트에서 실패했다. r2·r3가 `true`로 나왔다(`:631`, 02-R6). 남은 것: `inspect()`에 signal이 없다(`cache-storage-ports.ts:107`, adapter가 `undefined`를 넘긴다 `:913-919`). 판정 불가와 손상은 여전히 같은 `false`다. README 16.6절도 이 둘을 결정 대기로 적는다. 포트 주석 한 문장이 다시 stage 범위를 넓게 적는 것은 1105/02-02 행에 적었다 |
| `1101/02-02` | download 정책 `safeExtension`이 금지 목록·media type을 보지 않는다 | **일부** (변화 없음, 결정 대기) | `src/adapters/browser-files/`의 변경이 0줄이다. 금지 확장자 거절은 그대로다(`browser-file-policy-registry.ts:448-456`). media type과 확장자 짝은 여전히 보지 않는다. 설계 문서가 한계로 적는다(`browser-file-and-origin-storage.md:453-457`). README 16.6절 "결정 대기"와 같다 |
| `0929/02-06` | cross-context kernel 예외가 쓰임보다 넓다 | **남음** (결정 대기) | 예외가 배럴 전체를 연다(`.dependency-cruiser.json:261`). adapter 쪽 사용은 여전히 query-cache의 `import type` 하나다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:18-21`). repo `CLAUDE.md`가 이 예외를 kernel로 열거한다. 새 파일 단위 예외는 제안하지 않는다 |
| `0929/02-03` | CHANGELOG 0.2.0 browser-files [계약] 행의 경로·대상이 틀렸다 | **남음** | 행이 `CHANGELOG.md:418`로 옮겨졌을 뿐 내용이 같다. browser-files 포트의 영향 경로가 `src/adapters/browser-file-storage/`다. 실제 adapter는 `src/adapters/browser-files/`다. Cache Storage를 "browser-files recipe"로 적는다. 지난 영역 문서 2절은 이것을 "남음"으로 적었는데 README 16.6절 목록에는 없다(색인 누락) |
지난 라운드에 고쳐짐으로 닫은 1103 발견 6건은 다시 열리지 않았다.
- 1103/02-01: 순서·나머지 호출·READY 막음 테스트가 그대로다(`runtime-adapters-product-scope-participants.test.ts:117-158`). 레시피 테스트가 통과한다(FE-GATE-007 `:103`).
- 1103/02-02: activation은 본문 읽기 실패를 손상으로 보고하지 않는다(`public-response-cache-adapter.ts:695-705`). 테스트가 code `UNAVAILABLE`을 본다(`public-response-cache-repair.test.ts:216-222`). 바뀐 것은 recovery(`RETRY` → `REHYDRATE`)와 stage 동작이다. 1105/02-02가 정한 변경이다.
- 1103/02-03: L6·L7 테스트가 그대로다(`public-response-cache-repair.test.ts:869`, `:891`). L1·L4·L5 쪽은 소스와 테스트 모두 바뀌지 않았다.
- 1103/02-04·02-05: 그 코드가 바뀌지 않았다(`browser-files/` 0줄, `public-response-cache-adapter.ts:928-940`).
- 1103/02-06: FE-GATE-020 rc=0(0절).
## 3. 이번 발견 (36.3)
새 발견 1건. 심각도 Low 1. 우선순위 P3 1. 성격 구조적 위험 1. 수정이 만든 결함은 아니다. 지난 라운드들이 보고하지 않은 기존 경로다.
### 02-01 active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고, adapter API 안에서는 돌아올 길이 없다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험(회복 공백) |
| 관련 관점 | 28, 6, 18, 24, 11 |
| 근거 | ① active pointer를 쓰는 곳은 activation 하나다(`src/adapters/cache-storage/public-response-cache-adapter.ts:757-763`). ② activation은 이전 pointer를 먼저 읽고, `CORRUPT_DATA` 밖의 실패면 멈춘다(`:714-730`). 주석이 이것을 의도로 적는다. "A transient read failure still stops activation"(`:718-721`). ③ pointer 본문 읽기 실패는 `CORRUPT_DATA`가 아니다. `readActivePointer`가 예외를 `exceptionFailure`로 바꾼다(`:1041-1064`). `TypeError`는 `UNAVAILABLE`/`RETRY`, `NotReadableError`는 `NOT_READABLE`/`REOPEN`이다(`public-cache-codec.ts:566-583`, `src/adapters/browser-file-storage/result.ts:49-96`). ④ 같은 실패에서 cleanup(`:813-819`), inspect(`:885-893`), 조회(`:246-254`)도 멈춘다. stage만 pointer를 읽지 않는다. ⑤ 설계 문서는 이 경우를 "일시 오류"로만 적는다(`docs/architecture/browser-file-and-origin-storage.md:1013-1017`). 테스트도 일시 오류만 본다. 오류를 걸었다가 원래 `match`로 되돌린다(`tests/unit/public-response-cache-repair.test.ts:953-975`). ⑥ 0929/02-01은 손상 pointer(`CORRUPT_DATA`)만 다음 activation이 덮어쓰게 했다(`:722-733`). 1105/02-02는 같은 "일시와 지속을 가를 수 없음" 문제를 asset entry에서 "다시 stage가 덮어쓴다"로 풀었다. pointer는 stage가 쓰지 않으므로 그 수정 밖이다. ⑦ 실험 02-R1 X3(rc=0, 예측과 같음): pointer 본문이 다시 쓰기 전까지 읽히지 않게 한 뒤 새 adapter로 본다. 조회 `UNAVAILABLE`/`RETRY`. 새 release r2 stage `ok fetched=2`. r2 activate 두 번, cleanup, inspect, 현재 release r1 activate 모두 `UNAVAILABLE`/`RETRY`. pointer 다시 쓰기 0회, 끝까지 읽히지 않음 |
| 발생 조건 | control cache(`<prefix>control`)의 active pointer entry 본문이 다시 쓰기 전까지 계속 읽히지 않는다(디스크의 blob 손실 등). entry 자체는 있고 `cache.match`는 응답을 준다 |
| 영향 | 그 origin의 Cache Storage 관리가 멈춘다. 새 release는 stage되지만 activate되지 않는다. cleanup이 멈춰 owned cache가 쌓인다. inspect도 같은 실패라 운영자가 상태를 볼 수 없다. 조회는 모두 `UNAVAILABLE`/`RETRY`다. 제품 SW가 네트워크로 넘기면 사용자 피해는 오프라인 사용을 잃는 것이다. 돌아오는 길은 adapter 밖에서 control cache를 지우는 것(사이트 데이터 삭제, devtools, 제품 코드의 `caches.delete`)뿐이다. 안내 `RETRY`는 지켜지지 않는다. 데이터 노출과 삭제는 없다 |
| 심각도·우선순위 | Low · P3 — 1105/02-02와 같은 등급이다. 데이터는 지켜지고 온라인 경로는 산다. 지속되는 본문 읽기 실패가 실제 브라우저에서 생기는지 모른다. 레시피가 미조립이다. 영향 범위는 asset 하나보다 넓다(관리 전체). 그래도 사용자 데이터 손실이 없어 Medium으로 올리지 않는다 |
| 통제·증거 | 일시 오류에서 멈추는 규칙 M3(`public-response-cache-repair.test.ts:953-975`) · 지속 실패 회복 M0(pointer를 다시 쓸 길이 없음) · E1, E2(02-R1 X3, 메모리 fake에 오류 주입) |
| 확실성과 남은 가정 | 코드 경로는 정적으로 확인했고 실험 X3이 같은 결과를 냈다. 실제 Chrome·Firefox·Safari에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지는 확인하지 못했다. 일시 오류만 있다면 이 항목은 결함이 아니다(1105/02-02와 같은 가정) |
| 결정의 근거 | 확인한 사실: 일시 오류에서 activation을 멈추는 것은 기록된 의도다(`:718-721`, 설계 문서 `:1013-1014`). 그 의도는 일시 오류 하나로 rollback 목록을 잃지 않는 것이다. 리뷰어 추론: 일시와 지속을 가를 수 없을 때 "멈춤"만 있으면 지속 실패에서 끝나지 않는다. entry에서는 다시 쓰기가 같은 바이트라 비용이 없었다. pointer는 다시 쓰면 rollback 목록을 잃는다. 그래서 1105/02-02의 답을 그대로 옮길 수 없고 선택이 필요하다 |
| 이해 비용 | 운영자는 `UNAVAILABLE`/`RETRY`만 본다. 다시 해도 같고, inspect도 같은 실패다. 원인이 pointer라는 것을 알려면 adapter 코드를 읽어야 한다 |
| 최소 개선 방향 | (가)와 (나) 중 하나. (가) 설계 문서와 포트 주석에 "pointer 읽기가 계속 실패하면 control cache를 지우고 다시 activate한다. rollback 목록은 잃는다"를 적는다. (나) 운영자가 고르는 길을 둔다. activation에 선택 옵션(예: 읽을 수 없는 pointer를 손상처럼 덮어씀)을 더한다. 0929/02-01의 `CORRUPT_DATA` 경로를 그대로 쓴다 |
| 대안 비교 | (가) 문서만: 0줄 코드. 제품이 adapter 밖 코드로 control cache를 지워야 한다. (나) 명시 옵션: 분기 하나와 테스트 1~2개. 기본 동작은 그대로라 일시 오류 테스트가 지켜진다. 운영자가 rollback 목록 손실을 알고 고른다. (다) 연속 N회 실패를 손상으로 본다: 실패 횟수를 저장해야 해서 크다. 일시 오류가 길게 이어지면 rollback 목록을 잃는다. (나)가 가장 작은 코드 해결이다. 1105/02-02 남은 부분(marker)과 같이 고치면 "control record를 다시 쓰는 길"을 한 번에 정할 수 있다 |
| 단순화의 보존 조건 | 일시 오류 하나로 rollback 목록을 지우지 않는다(`:953-975`). 검증한 후보만 활성화한다. 손상 pointer는 지금처럼 다음 activation이 덮어쓴다(`public-response-cache-repair.test.ts:779`) |
| 비용·부작용 | (나)는 수십 줄. service-worker-pwa 번들 여유가 306 B다(FE-GATE-012 `:88`, 9,794 / 10,100 gzip B). 포트에 선택 칸이 하나 생기면 [계약] CHANGELOG 행이 필요하다 |
| 재검토 조건 | 실제 브라우저에서 지속되는 본문 읽기 실패가 관찰되지 않으면 (가)로 닫는다. Service Worker drain 조합을 조립할 때 rollback 정책과 같이 본다 |
| 완료 기준 | X3 시나리오에서 문서에 적힌 절차나 API로 pointer를 되살리고, 다음 activate가 성공한다. 일시 오류 테스트(`:953-975`)는 그대로 통과한다 |
| 검증 방법 | 02-R1의 X3 테스트(배치 패치 `scratchpad/r5/requests/02-R1-control-unreadable.diff`가 만든 `tests/unit/zz-r5-02-control-unreadable.test.ts`)를 `public-response-cache-repair.test.ts`의 0929/02-01 묶음으로 옮겨 기대를 바꾼다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 적용 — "검증 뒤에만 성공", 판정 분류 | M2 / M2 | E1, E2(FE-GATE-005) | P — asset entry의 지속 실패가 다시 stage로 풀렸다(1105/02-02). release marker(1105/02-02 남은 부분)와 active pointer(02-01)는 같은 실패에서 다시 쓰지 않는다 |
| 2 | 구조적 성숙도 | 적용 — 배럴 경계, kernel 예외 | M3 / M3 | E2(FE-GATE-010 PASS) | P — 레시피는 배럴과 조립 계약만 import한다(`browser-file-session-capability.ts:1-2`). cross-context 예외가 배럴 전체를 연다(`0929/02-06`, 결정 대기) |
| 3 | 변경 용이성 | 적용 — 수명 연결, 정책 추가 | M2 / M2 | E1, E2 | O — 제품 파일만 고쳐 file runtime을 세션에 묶는다. label 형식이 문서에 적혀 있다(`03-outside-feature-folder.md:122`) |
| 4 | 인지 부하 | 적용 — 큰 파일, 판정 종류 | — / — | E1 | P — `public-response-cache-adapter.ts`가 1,241줄이다. 판정이 넷이 됐다(`:1095-1106`). `REPAIRABLE`과 `UNREADABLE`은 이제 activation code 하나만 다르다. 그 차이의 이유는 주석을 읽어야 안다. 레시피 주석은 매뉴얼과 맞다(1105/02-03) |
| **5** | 위험 가시성 | 적용 — 실패 의미, 세션 수명 | M1~M2 / M2 | E1, E2 | P — 제품 closer 실패가 label과 함께 보인다(1105/02-01). pointer가 계속 읽히지 않으면 inspect도 실패해 상태가 보이지 않는다(02-01) |
| **6** | 실패 성숙도 | 적용 — 손상·일시·지속 실패 구분 | M2 / M2 | E1, E2(02-R1) | P — entry는 일시·지속 모두 다시 stage로 끝난다. marker·pointer는 지속 실패가 일시 오류로 분류돼 끝나지 않는다(1105/02-02 남은 부분, 02-01). 중단 분기(`:1168`)는 테스트가 없다. 바뀌어도 activation의 recovery 칸만 달라진다 |
| 7 | 운영 성숙도 | 적용 — 관측 연결 | M2 / M3 | E1, E2 | P — scope reset 실패가 단계마다 진단에 남고 테스트가 고정한다(1105/02-01). file·cache observer는 여전히 레시피 조립 몫이다 |
| **8** | 디버깅 가능성 | 적용 — reason·operation·label | M2 / M2 | E1, E2 | P — 실패한 participant의 label이 남는다(고쳐짐). inspect 실패 operation이 여전히 `CACHE_LOOKUP`이다(`:942`). pointer 지속 실패는 원인을 가리키는 신호가 없다(02-01) |
| 9 | 유지보수 성숙도 | 적용 — 문서·CHANGELOG 정합 | M1 / M1 | E1 | P — 레시피 주석이 고쳐졌다. 설계 문서·포트 주석이 다시 stage 범위를 넓게 적는다(1105/02-02 남은 부분). CHANGELOG 0.2.0 행이 그대로 틀렸다(`0929/02-03`) |
| **10** | 테스트 성숙도 | 적용 — 수정 테스트, 변이 | M3 / M3 | E2(이 영역 unit 13파일·recipe 1파일 통과), E2(변이 8개 모두 검출, 02-R2~R9) | P — 지난 생존 변이(F0202-cor·-pol·-lim·-notreadable, M05, N38)마다 그것을 겨냥한 테스트가 생겼고, 그 변이가 모두 그 테스트에서 실패한다. 수정 커밋의 테스트도 같다(capability 전달, scope label). F0202-int는 동등 변이다(2절). marker·pointer 지속 실패는 테스트가 없다. `scope_participant` 값 정책만 지우는 변이는 잡히지 않지만 호출부가 먼저 걸러 동작이 같다 |
| **11** | 데이터 성숙도 | 적용 — pointer·marker·캐시 entry | M2 / M2 | E1, E2 | P — 손상 marker는 다시 stage로 고친다(`:891`). 계속 읽히지 않는 marker와 pointer는 고칠 길이 adapter 밖뿐이다(1105/02-02 남은 부분, 02-01) |
| 12 | 동시성 성숙도 | 적용 — async 경쟁, 탭 간 순서 | M3 / M3 | E1, E2 | O — 이 영역의 경쟁 코드는 바뀌지 않았다. 재시도마다 scope 진단이 남는 것도 순서대로 고정됐다(`runtime-adapters-product-scope-participants.test.ts:190-196`) |
| 13 | 확장성 | 적용 — 상한 값 | M2 / M2 | E1 | O — 상한 값 변경 없음. 부하 목표 없음 |
| 14 | 성능 성숙도 | 적용 — 레시피 번들, 초기 JS | M2 / M2 | E2(FE-GATE-012 `:76`, `:88`) | P — service-worker-pwa 9,794 / 10,100(여유 306 B, 지난 342 B에서 36 B 줄었다), file-transfer 56,130 / 57,800 gzip B. 초기 JS 204,158 / 206,848(D7로 올린 예산, 오케스트레이터 결정). 02-01이 초기 JS에 +251 B를 더했다는 것은 수정 세션의 측정이다(5절). `inspect()`·`cleanupOwned()`에 cursor·deadline이 없다(`0929/02-02`) |
| **15** | 보안 성숙도 | 적용 — 세션 경계, 위험 확장자, 저장 영역 | M2~M3 / M2~M3 | E1, E2 | P — 진단 label은 소스가 정한 형식 토큰만 실리고 telemetry로 나가지 않는다. host `storageArea` 비교에 테스트가 생겼다(1101/02-04). media type 짝은 보지 않는다(`1101/02-02`) |
| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더의 외부 패키지 import 0건(grep) | — | E1 | - |
| **17** | API / Contract 성숙도 | 적용 — 포트·진단·제품 확장 계약 | M2 / M2 | E1, E2 | P — `scope_participant` 키가 분류·값 정책·CHANGELOG 행과 함께 생겼다(0절). label 형식 축소가 먼저 할 일에 있다(`CHANGELOG.md:29`). 포트 `verified`의 뜻이 적혔다. 포트 주석이 lookup 실패도 다시 stage가 고친다고 적는다(`cache-storage-ports.ts:66-69`, 1105/02-02 남은 부분). label 중복은 계약에 없다 |
| **18** | 배포 성숙도 | 적용 — 배포·rollback, 게이트 | M2 / M2 | E2(FE-GATE-020 rc=0) | P — 제거 드릴 게이트가 통과한다. 계속 읽히지 않는 marker가 있는 rollback 대상은 되돌릴 수 없다(1105/02-02 남은 부분). pointer가 계속 읽히지 않으면 어떤 release도 activate되지 않는다(02-01) |
| 19 | 설정 성숙도 | 적용 — 정책 조합 검증 | M3 / M3 | E1, E2 | P — 위험 `safeExtension`과 형식 밖 scope label이 조립 때 `TypeError`다. media type 짝은 통과한다(`1101/02-02`) |
| 20 | 개발자 경험 | > 영역 14 — 레시피 주석 수정(1105/02-03)은 이 영역에서 확인했다 | — | — | > |
| 21 | Guardrail 성숙도 | 적용 — 제거 드릴, kernel 예외, 진단 분류 | M3 / M3 | E2(FE-GATE-020, FE-GATE-010) | P — 제거 드릴이 통과한다. 새 진단 키가 분류 없이 들어오면 `check:diagnostics`와 `observability-cardinality.test.ts:15-18`이 막는다. 문서를 읽는 테스트 제외 목록은 손으로 관리한다(`scripts/lib/removal-fixture.ts`, 지난 라운드와 같다) |
| 22 | 추상화 성숙도 | 적용 — participant 목록, 세션 getter | — / — | E1 | P — `participants`가 배열과 함수를 둘 다 받는다(`server-state-scope-runtime.ts:51-57`). 제품 closer가 나중에 들어오는 것을 wrapper 없이 푼다. 판정 union이 넷이다(4번) |
| 23 | 일관성 | 적용 — 실패 분류 | — / — | E1 | P — stage가 entry 본문 읽기 실패는 다시 쓰고 marker 본문 읽기 실패는 멈춘다(`:463-468` 대 `:500-507`). `QUOTA_EXCEEDED`의 recovery가 `READ_ONLY`와 `ONLINE_ONLY`로 갈린다(`result.ts:80-85`, `public-cache-codec.ts:597-603`, 지난 라운드와 같다) |
| **24** | 네이밍 / 의미 성숙도 | 적용 — 실패 이름이 약속하는 것 | M2 / M2 | E1 | P — entry 실패의 `REHYDRATE`는 이제 지켜진다. marker·pointer 지속 실패의 `RETRY`는 지켜지지 않는다. `verified:false`가 판정 불가를 합친다(`0929/02-02`). "kebab-case"라는 이름에 비해 정규식이 `a-`·`a--b`도 받는다(`diagnostics.ts:147-149`, 영향 없음) |
| 25 | 조직 확장성 | 적용 제외 — 1인 관리 | — | — | - |
| 26 | Ownership 성숙도 | > 영역 12 | — | — | > |
| 27 | 삭제 가능성 | 적용 — 제거 드릴 | M3 / M3 | E2(FE-GATE-020 rc=0, junit 2개 failures 0) | O — browser-files·cache-storage·포트·레시피를 지운 fixture에서 검사가 모두 통과한다. 실제 Gitea 러너는 미실행 |
| **28** | 회복 가능성 | 적용 — 손상·지속 실패 회복 | M2 / M2 | E1, E2(02-R1) | P — 계속 읽히지 않는 asset entry는 다시 stage로 돌아온다(1105/02-02 완료 기준). release marker와 active pointer는 돌아오지 못한다(1105/02-02 남은 부분, 02-01) |
집계(이 영역에서 판정한 24개): O 4(3, 12, 13, 27) · P 20 · X 0 · ? 0. 적용 제외 2(16, 25) · 다른 영역 2(20, 26). 지난 라운드 대비: 판정 기호는 같다. 7번 확인 통제가 M1 → M3로 올라갔다(1105/02-01). 5·8번의 원인이 02-01(1105)에서 02-01(1106)로 바뀌었다. 6·11·18·28번의 원인이 "asset entry"에서 "marker·pointer"로 좁아졌다.
## 5. 미검증
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
| --- | --- | --- |
| 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지(1105/02-02 남은 부분과 02-01의 발생 가능성) | 실기에서 blob 손실을 만들지 않았다. 02-R1은 메모리 fake에 오류를 주입했다 | 브라우저별 프로필에서 cache entry의 blob 파일을 지운 뒤 `response.body` 읽기 결과를 본다 |
| 02-01(1105)이 초기 JS에 더한 +251 B | 수정 세션의 커밋별 측정이다(README 16.2절 D7). 리뷰어는 커밋별로 재지 않았다. `bbde570` 전체는 204,158 B로 예산 안이다(FE-GATE-012 `:76`) | 부모 커밋과 `f738348`의 `--initial-baseline` 비교 |
| `FAILED` scope가 화면에서 어떻게 보이는지 | 영역 08·09 몫 | `FAILED` 주입 뒤 화면 상태 확인 |
| 레시피를 조립한 실제 화면에서 로그아웃 뒤 파일·download가 닫히는지 | 조립 코드가 없다. 레시피 테스트는 jsdom이다 | file-transfer 레시피를 조립한 제품 E2E |
| FE-GATE-020이 실제 Gitea 러너에서 같은 결과인지 | 러너가 없다 | 러너의 merge job |
## 6. 실행 기록
### 6.1 오케스트레이터 게이트 결과(인용, `bbde570`, CI env)
| 출처 | 결과 |
| --- | --- |
| `bbde570-ci/summary.txt` | FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(host). FE-GATE-020 1,237초 |
| `gate-artifacts/FE-GATE-005.txt` | `:91` `server-state-scope-runtime.test.ts` 18건, `:118` `public-response-cache-repair.test.ts` 25건, `:126` `runtime-adapters-product-scope-participants.test.ts` 4건, `:228` `cross-tab-invalidation.test.ts` 19건 통과. 전체 `:312` 208파일, `:781` 332파일 통과 |
| `gate-artifacts/FE-GATE-007.txt` | `:103` `tests/recipes/browser-file-session-capability.test.ts` 1건 통과 |
| `gate-artifacts/FE-GATE-012.txt` | `:76` 초기 JS 204,158 / 206,848 gzip B, 27 / 32 파일. `:88` file-transfer 56,130 / 57,800, service-worker-pwa 9,794 / 10,100 |
| snapshot junit(03:24 뒤) | `coverage.xml` 4,085건 실패 0(이 영역 unit 13파일 포함), `optional-recipes.xml`(03:48), `browser-capabilities/results.xml` 69건 실패 0(이 영역 spec 7건 × 3엔진), `browser-file-storage-runtime-removal.xml` 7/7, `optional-recipe-removal.xml` 6/6 |
### 6.2 배치 02-R1~R9 (오케스트레이터 실행)
요청 파일: `scratchpad/r5/requests/02.md`. 패치는 `scratchpad/r5/requests/02-R*.diff`이고, 모두 laptop에서 `git apply --check`로 `bbde570`에 적용되는 것을 확인했다. 변이 없는 대조 실행은 6.1절의 게이트 로그로 대신한다. 실행: 2026-11-06 04:32, `bbde570`, env local, 항목마다 checkout 복원(`restore=clean`). 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-02-R<n>.log`.
| ID | 명령 | 변이 | 기대 | rc · 결과 |
| --- | --- | --- | --- | --- |
| 02-R1 | `node scripts/run-vitest.ts run tests/unit/zz-r5-02-control-unreadable.test.ts` | 테스트 파일 추가(소스 그대로) | X1·X2·X3 pass(예측이 맞음) | rc=0, 3/3 pass. 출력 `R5-02-OBS`: X1 `{activate1:UNAVAILABLE/RETRY, stage:"UNAVAILABLE/RETRY fetched=0", cleanup:"ok deleted=0", activate2:UNAVAILABLE/RETRY, stillUnreadable:true, markerRewrites:0}`. X2 `{lookupFirst·lookupSecond:UNAVAILABLE/RETRY, restage:"UNAVAILABLE/RETRY fetched=0", lookupAfterRestage:UNAVAILABLE/RETRY, stageNext:"ok fetched=2", activateNext:ok, lookupAfterNext:hit}`. X3 `{lookup:UNAVAILABLE/RETRY, stageNext:"ok fetched=2", activateNext1·cleanup·inspect·activateNext2·activateCurrent:UNAVAILABLE/RETRY, stillUnreadable:true, pointerRewrites:0}` |
| 02-R2 | `… run tests/unit/public-response-cache-repair.test.ts` | `REPAIRABLE_READ_CODES`에서 `CORRUPT_DATA` 뺌 | `DataError` 행 FAIL | rc=1, 1/25 FAIL. "… a body that fails as corrupt data …" code `CORRUPT_DATA` ≠ `INTEGRITY_FAILED`(`:586`). 기대와 같음 |
| 02-R3 | 같음 | `POLICY_REJECTED` 뺌 | 정책 밖 헤더 행 FAIL | rc=1, 1/25 FAIL. "… a header outside the policy …" code `POLICY_REJECTED`(`:586`). 기대와 같음 |
| 02-R4 | 같음 | `LIMIT_EXCEEDED` 뺌 | 길이 초과 행 FAIL | rc=1, 1/25 FAIL. "… a declared length over the entry limit …" code `LIMIT_EXCEEDED`(`:586`). 기대와 같음 |
| 02-R5 | 같음 | `NOT_READABLE` 더함 | `NotReadableError` 행 2건 FAIL | rc=1, 2/25 FAIL. E-1b 행(`:502`)과 표 행(`:586`)이 `NOT_READABLE` 대신 `INTEGRITY_FAILED`. 기대와 같음 |
| 02-R6 | 같음 | inspect `verified`를 `kind !== "REPAIRABLE"`로(M05) | "lists a candidate it could not read as unverified" FAIL | rc=1, 1/25 FAIL. `{r1:true, r2:true, r3:true}` ≠ `{r1:true, r2:false, r3:false}`(`:631`). 기대와 같음 |
| 02-R7 | `… run tests/unit/cross-tab-invalidation.test.ts` | host가 늘 `EXPECTED_LOCAL_STORAGE`(N38) | "takes a storage pulse only from the localStorage object it captured" FAIL | rc=1, 1/19 FAIL. 구독자가 2회 불렸다(`:471`). core 테스트 "rejects storage pulses from another or unknown storage area"는 통과. 기대와 같음 |
| 02-R8 | `… run tests/recipes/browser-file-session-capability.test.ts` | 조립에서 `...product.capabilities` 지움 | `Features did not receive the files capability` FAIL | rc=1, 1/1 FAIL, 그 메시지(`:238`). 기대와 같음 |
| 02-R9 | `… run tests/unit/runtime-adapters-product-scope-participants.test.ts tests/unit/server-state-scope-runtime.test.ts` | 진단에서 `scope_participant` 지움 | 2건 FAIL | rc=1, 2/22 FAIL. 두 기록에서 `scope_participant` 칸이 빠짐(`runtime-adapters-product-scope-participants.test.ts:183`, `server-state-scope-runtime.test.ts:166`). 기대와 같음 |
F0202-int(`INTEGRITY_FAILED` 뺌)는 요청하지 않았다. 동등 변이라 살아남는 것이 맞고, 살아남는 결과는 동등을 증명하지 않는다. 동등은 2절에서 코드로 보였다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
| --- | --- | --- | --- | --- |
| 02-01 | Low · P3 | 구조적 위험 | active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고 API 안에서 돌아올 길이 없다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:714-730`, `:813-819`, `:885-893`, `:246-254`, `:1041-1064` |
@@ -0,0 +1,209 @@
# 영역 03 — HTTP·서버 상태·인증·진단
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로 `src/adapters/http/`(`fileserver-upload.ts`는 01 영역), `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`. 흐름 확인: `src/contracts/external-contract-runtime.ts`, `src/contracts/server-state.ts`, `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx`, `src/application/view-models/async-state.ts`, `scripts/create-feature-write-slice.ts`, `config/contracts/`, 계약 문서 4.1·6·6.1, 런북 6.3, CHANGELOG 미출시 절. 짝 백엔드 `45d2a478`(pin)의 `docs/web/http-contract.md` §2·§4, `RateLimitInterceptor.java`, `RateLimitTransportError.java`, `OperationalError.java`, `FileserverErrorCode.java`, `WebAdvancedError.java`
> 깊게 본 관점 5, 6, 10, 12, 17, 21, 23, 28
> 렌즈: BREAKING 1105/03-01(커밋 footer와 CHANGELOG 안내를 코드와 대조), 1105/03-02와 합친 커밋 `45c9c4d`의 통합 수정, 0929/03-03, 1103/03-01 남은 부분. 1105/03-02가 `NOT_APPLIED`로 바꾼 답이 결과 불명 재전송 경로에서 무엇을 하는지
> **영역 판정(35.8): 조건부 사용 가능.** 짝 백엔드 쓰기 폼은 쓸 수 있다. 조건은 셋이다. (1) KEYED 쓰기에서 rate limit을 켜면, 결과 불명 뒤 같은 키 재전송이 429나 503 `RATE_LIMIT_*`로 거절될 때 화면의 "다시 시도"가 새 키로 보낸다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다(새 03-01, 03-R1에서 재현). (2) `refusedBeforeWrite`에는 쓰기 전에만 나온다고 확인한 업무 code만 적는다(플랫폼 code는 이제 조립이 막는다). (3) IDEMPOTENT 쓰기는 결과 불명 뒤 NEVER처럼 "변경됨으로 확인"만 남는다(새 03-03). bulk 응답은 지원하지 않는다(1103/03-02).
ID 표기: `03-NN`은 이번(2026-11-06) 라운드 발견이다. 지난 라운드는 `1105/03-NN`, 그 전은 `1103/03-NN`, `1101/03-NN`, `0929/03-NN`이다. 다른 영역의 이번 라운드 발견은 `1106/NN-MM`으로 적는다.
**실행 상태.** 이 영역은 아무것도 돌리지 않았다. 증거는 메인 세션이 `bbde570`에서 CI env로 돌린 게이트 로그(`desktop:/tmp/claude-gates/bbde570-ci/`)다. FE-GATE-005(test:unit 208 files / 3,056 tests, coverage 332 / 4,085), FE-GATE-006(component 41 / 278), FE-GATE-007(integration 11 / 212), FE-GATE-020(생성 기능 드릴 포함)이 모두 rc=0이다. 변이와 실험은 요청 파일 `scratchpad/r5/requests/03.md`의 03-R1~R7로 냈다. 오케스트레이터가 `bbde570`에서 하나씩 돌렸고 항목마다 checkout이 깨끗하게 돌아왔다(`restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-03-R1.log`~`R5-03-R7.log`다. 실험 1건은 결함을 재현했다. 변이 6건은 모두 기대한 테스트에서 실패했다(6절).
## 0. 결론
- **BREAKING 1105/03-01은 커밋 footer대로 동작한다(고쳐짐).** 조립이 6.1절의 "쓰기 뒤 가능" 플랫폼 code 20개 선언을 거절한다(`src/contracts/external-contract-runtime.ts:638-663`, `:691-695`). 이 검사는 `composeContractContributions` → `assertHttpContract` → `assertRefusedBeforeWrite` 순으로 모든 쓰기에 닿는다(`:1084`, `:571`). 조립 없이 부른 실행기도 그 code를 무시한다(`src/adapters/http/backend-envelope.ts:328-339`). 목록은 계약 문서 6.1절 표와 양방향으로 대조된다(`tests/unit/backend-contract-pin.test.ts:263-302`). CHANGELOG "먼저 할 일" 3단계와 [계약] 행(`CHANGELOG.md:26`, `:60`)의 문장이 코드와 같다. 조립 검사, 실행기 fail-close, 6.1절 대조를 하나씩 깨는 변이 셋이 모두 검출됐다(03-R4 4건, R5 5건, R6 1건 실패).
- **1105/03-02와 합친 커밋 `45c9c4d`의 통합 수정은 맞다(고쳐짐).** 네 곳이 같은 사실을 적는다. 답 표의 §4 503 세 행(`config/contracts/backend-idempotency-answers.json:51-71`), pin의 빈 `notCopied`(`config/contracts/backend-contract-pin.json:50`), 프론트 거절 표의 두 행(`backend-envelope.ts:177-181`), 계약 문서 4.1(`docs/architecture/backend-api-and-server-state-contract.md:168-183`)이다. 백엔드 `45d2a478`의 §4 표와 `RateLimitInterceptor.preHandle`(`:31-65`)이 두 code를 컨트롤러 전에 503으로 낸다. 프론트 표의 두 행을 지운 변이를 단위·pin·통합 테스트 7건이 잡았다(03-R7).
- **0929/03-03은 고쳐졌다.** 훅이 키 없는 결과 불명과 같은 입력의 `submit`을 보내지 않는다(`application-query.ts:569-583`). 화면은 `unknownEffectResendable === true`일 때만 재전송 버튼을 그린다(`async-surface.tsx:227-229`). 두 가드를 하나씩 되돌린 변이가 각각 1건씩 검출됐다(03-R2, R3).
- **나머지 이월:** 1103/03-01 일부(거절 문구 자리는 생겼다. 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼은 결정 대기). 1103/03-02·1103/03-07 일부(결정 대기). 1101/03-04·0929/03-02 남음. 이 둘은 지난 README §16.6에 행이 없다.
- **새 발견 3건: Medium·P2 1, Low·P3 2.** 03-01: KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 생성 KEYED 폼은 그때 "다시 시도"로 새 키를 보낸다. 1105/03-02가 503 `RATE_LIMIT_*`를 이 길에 더했다(429·401은 전부터). 실험 03-R1이 훅과 실제 실행기·폼 모두에서 `keys=["key-1","key-1","key-2"]`를 보였다. 03-02: 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 03-03: 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다.
- **고친 커밋이 이 영역의 검사를 약하게 만든 곳은 찾지 못했다.** 지운 단언, 새 skip, 시간 상한 상향이 없다(2절 끝). 제거 fixture의 문서 테스트 목록에 pin 테스트가 들어간 것은 12 영역이 1106/12-01로 셌다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 `git show 45d2a478:<path>`로 읽기만 했다 |
| 커밋·작업 상태·확인 시점 | 프론트 `bbde570`(laptop worktree, HEAD = 기준, 추적 파일 변경 없음). 백엔드 pin `45d2a478`. 백엔드 HEAD는 pin 뒤 두 커밋(`3d73b6f1`, `6e992970`)이다. 그 두 커밋은 6.1절이 인용한 파일 중 `GlobalExceptionHandler.java`의 로그 줄과 `IdempotencyExecutor.java`의 주석만 바꿨다(`git diff 45d2a478 HEAD`). 단계 판정은 바뀌지 않는다. 2026-11-06 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 두 템플릿을 짝으로 써서 빨리 출시하는 것이 목표다 |
| 필수 요구와 규모·운영 목표 | 짝 백엔드 `http-contract.md` §2(멱등성 응답: 결과 불명은 "새 키 금지", `:89`, `:112`)·§4(web 전용 code), 프론트 계약 문서 4.1·6·6.1, 런북 6.3(`docs/operations/api-contract-and-server-state-recovery.md:248-271`), 매뉴얼 `02-decision-tables.md` 3·4절. 수치 운영 목표는 없다 |
| 읽은 코드·구성 범위 | 줄 단위: `backend-envelope.ts` 전부, `external-contract-runtime.ts` 155~175·455~700·840~1090, `http-execution-v3.ts` 900~920·1040~1160·1620~1800, `http-retry-lifecycle.ts` 1~75, `application-query.ts` 360~370·520~900, `use-app-form.ts` 전부, `async-surface.tsx` 120~235, `server-state.ts` 290~320, `create-feature-write-slice.ts` 225~320·640~745, 계약 문서 161~230·269~412, CHANGELOG 14~108, 매뉴얼 02 80~200, 런북 6.3, `config/contracts/` 세 JSON, `scripts/lib/backend-contract-excerpt.ts`, `scripts/lib/removal-fixture.ts` 40~90. 테스트: `backend-contract-pin.test.ts` 전부, `backend-envelope.test.ts`·`external-contract-runtime.test.ts`·`http-execution-v3-envelope.test.ts`·`form-foundation.test.tsx`·`application-mutation-admission.test.tsx`·`async-surface.test.tsx`의 바뀐 부분. 커밋: `5c0b37e`, `c6c37f3`, `683ccfb`, `12d97d7`, 합친 커밋 `45c9c4d`(두 부모와의 diff). `git diff 8a44226..bbde570`의 영역·흐름 16파일(+630/−96). `browser-rpc`·`auth`·`diagnostics`·`telemetry`는 `8a44226` 뒤 변경이 없다. `query-cache`는 1105/02-01의 `server-state-scope-runtime.ts` 변경뿐이다(02 영역) |
| 수행한 테스트·실험 | 실행 환경 = desktop. 이 영역이 직접 돌린 것은 없다. 인용한 게이트: FE-GATE-005·006·007·020(CI env, rc=0, `bbde570-ci/summary.txt`). 배치 03-R1(실험), 03-R2~R7(변이). 오케스트레이터가 local env로 하나씩 돌렸고 7건 모두 `restore=clean`(`r5/batch/out/R5-03-R*.log`). 결과는 6절 |
| 확인하지 못한 범위·이유 | 5절 |
| 이전 리뷰와 비교 가능한 범위 | `8a44226..bbde570`의 영역 커밋(`git log --oneline 8a44226..bbde570 -- <경로>`). 지난 실행 결과는 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
대상: 지난 README §15의 03 행 둘(1105/03-01, 03-02), §16.5의 03 행 넷(1103/03-01, 03-02, 03-07, 0929/03-03), 지난 03 문서 2절이 "남음"으로 둔 이월 둘(1101/03-04, 0929/03-02). §16.6에는 03 행이 없다. §16.4·§16.5의 "고침"은 주장으로만 보고 지난 03 문서 3절의 완료 기준으로 다시 판정했다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/03-01 Low·P3 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code도 받는다 | **고쳐짐** (변이 3개 검출: 03-R4 4건, R5 5건, R6 1건) | 완료 기준 "X2의 계약이 조립에서 6.1절을 이유로 거절된다"를 코드와 테스트로 확인했다. ① 목록: `PLATFORM_CODES_POSSIBLY_AFTER_WRITE` 20개(`external-contract-runtime.ts:627-663`). 6.1절 표의 "쓰기 뒤 가능" 행(`backend-api-and-server-state-contract.md:319-325`)에서 참조 도메인 6개와 web-advanced patch 2개를 뺀 것과 같다. 백엔드 `45d2a478`의 400·409·422 플랫폼 code를 enum에서 모두 셌다(`OperationalError.java:15-85`, `WebTransportError.java:18-24`, `FileserverErrorCode.java:26-44`, `WebAdvancedError.java:23-41`). 400·409·422인 플랫폼 code 중 6.1절에 없는 것은 없다. ② 조립 거절: `assertRefusedBeforeWrite`가 멱등성 접두사 다음에 그 목록을 본다(`:665-699`, 문구 `:693`). 모든 쓰기 operation에서 불린다(`:571`). 스냅숏한 목록을 검사하고 설치한다(`:846`, `:867-895`, `:1084`). ③ 실행기 fail-close: `declaredBeforeWrite`가 그 목록을 뺀다(`backend-envelope.ts:328-339`). ④ 테스트: X2의 네 code가 6.1절 이유로 거절된다(`tests/unit/external-contract-runtime.test.ts:286-296`). 선언해도 다섯 code가 `MAYBE_APPLIED`다(`tests/unit/backend-envelope.test.ts:117-129`). 목록과 6.1절 표를 양방향 대조한다(`backend-contract-pin.test.ts:263-302`). 세 파일 모두 FE-GATE-005에서 통과(47·37·15건). **BREAKING 안내:** 커밋 footer는 "`composeContractContributions`가 거절한다. 그 code를 목록에서 지운다. 그 실패는 결과 불명으로 남는다"이다(`5c0b37e`). 코드가 그렇다. CHANGELOG 3단계(`CHANGELOG.md:26`)와 [계약] 행(`:60`)도 같은 목록과 같은 결과를 적는다. 매뉴얼 02 4절(`docs/manual/02-decision-tables.md:185`)과 오류 표(`docs/manual/reference/errors.md:106`)가 같은 거절 문구를 적는다. 남은 것: 업무 code의 잘못된 선언은 설계상 기능 작성자의 판단이다(커밋 "위험·한계") |
| 1105/03-02 Low·P3 | 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | **고쳐짐** (변이 검출 03-R7: 7건). 이 수정이 새 03-01의 길을 넓히고 새 03-02를 만들었다 | 완료 기준 "503 `RATE_LIMIT_UNAVAILABLE`이 분류기와 상관없이 `NOT_APPLIED`/retry-later"를 확인했다. 분류기가 `MAYBE_APPLIED`인 create에서 두 code가 `SERVER_FAILURE`·`NOT_APPLIED`다(`tests/integration/http-execution-v3-envelope.test.ts:707-726`, FE-GATE-007 통과). kind `SERVER_FAILURE`는 action `retry`라(`src/contracts/errors.ts:85`) 폼은 `retry-later`다(`use-app-form.ts:305-314`). **합친 커밋 `45c9c4d` 확인:** 07-01 브랜치 부모(`45c9c4d^2`)의 pin은 두 code를 `notCopied`에 두었다. 합친 트리에서는 비었다(`backend-contract-pin.json:50`). 답 표는 두 행을 `refusedBeforeWrite: true`, `sameKeyResend: false`로 둔다(`backend-idempotency-answers.json:58-71`). 프론트 표는 status 503과 함께 둔다(`backend-envelope.ts:177-181`). 계약 4.1은 "§4의 503 셋을 옮겼다", "`notCopied`는 지금은 없다"로 고쳐졌다(`backend-api-and-server-state-contract.md:168-183`). 매뉴얼 02는 두 code를 `NOT_APPLIED` 줄에 적는다(`02-decision-tables.md:176`). 사본 §4 네 행(`config/contracts/backend-http-contract-excerpt.json:28-33`)이 백엔드 `45d2a478:docs/web/http-contract.md:188-193`과 같다. `answerTableProblems`가 사본 행마다 답 표나 `notCopied` 중 정확히 한 곳을 요구한다(`scripts/lib/backend-contract-excerpt.ts:116-160`, 테스트 `backend-contract-pin.test.ts:165-179`). 백엔드 사실: `preHandle`이 `false`를 돌려주며 쓰고(`RateLimitInterceptor.java:55-65`), status는 둘 다 503이다(`RateLimitTransportError.java:29-32`). main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다. 비동기 재디스패치 위험은 계약 6.1에 적었고 백엔드로 넘겼다(`backend-api-and-server-state-contract.md:342-346`). 작은 잔여: pin 테스트 머리 주석이 아직 "§4's async timeout"만 적는다(`backend-contract-pin.test.ts:20`). 결함으로 세지 않는다 |
| 1103/03-01 (= 1103/08-01) High·P1 → 남은 부분 Medium·P2 | 업무 규칙 거절이 결과 불명이 된다. 남은 부분: 거절 이유가 안 보인다, KEYED에서 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼이 남는다 | **일부** (결정 대기) | 고쳐진 것: 폼이 `refusalMessages`로 `NOT_APPLIED` 실패의 code에 기능 문구와 필드를 붙인다(`use-app-form.ts:30-38`, `:50-59`, `:251-271`, `:472-487`). 결과 불명은 code와 상관없이 그대로다(`:482`). 테스트 `form-foundation.test.tsx:1005-1101`(FE-GATE-006 통과, 34건). 남은 것: 같은 키 재전송이 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받으면 `MAYBE_APPLIED`라 결과 불명이 다시 서고 버튼이 남는다(`backend-envelope.ts:271-276`, `application-query.ts:684-698`). 백엔드 §2가 그 답에 "같은 키 재전송은 안전하다"고 적어(`45d2a478:docs/web/http-contract.md:113`) 거두는 것도 선택지 하나다. 고르는 사람은 프론트 템플릿 담당이다(`12d97d7` 본문, `CHANGELOG.md:94`). 폼 쪽 판정은 08 영역이 본다 |
| 1103/03-02 Medium·P2 | Envelope 읽기가 `meta.page`를 버리고 bulk `results`를 거절한다 | **일부** (bulk 지원 여부 결정 대기) | `meta.page`는 지난 라운드대로다(`backend-envelope.ts:22-36`, `:49`). bulk는 계약 4.1이 "지원하지 않는다"로 적는다(`backend-api-and-server-state-contract.md:205-207`). 그 문장의 "`responseEnvelope`를 빼고" 안내가 1103/16-01 BREAKING 뒤 맞지 않는 것은 07 영역의 1106/07-01이다 |
| 1103/03-07 Low·P3 | 두 생성기가 만드는 operation이 맞지 않는다 | **일부** (결정 대기 D3) | 백엔드 생성기 컨트롤러는 pin과 HEAD 모두 `POST`와 `GET /{id}`만 만든다(`45d2a478`·`HEAD`의 `__Feature__Controller.java.tmpl:49`, `:63`). 프론트 생성 목록이 405를 받는다고 주석이 적는다(`scripts/create-feature.ts:766-771`) |
| 0929/03-03 High·P1 → 남은 부분 Medium·P2 | 키 없는 결과 불명 쓰기를 같은 입력으로 다시 보낸다(훅 직접 호출), 손으로 만든 상태가 버튼을 그린다 | **고쳐짐** (변이 2개 검출: 03-R2, R3 각 1건) | 지난 문서의 최소 개선 둘이 들어왔다. ① 훅의 `submit`이 같은 입력의 결과 불명 admission에 키가 없으면 보내지 않고 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)를 돌려준다(`application-query.ts:564-583`). admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다. 테스트: 같은 입력은 `execute` 1회, 상태는 결과 불명 그대로(`tests/component/application-mutation-admission.test.tsx:563-583`). 다른 입력은 보낸다(`:585-594`). ② 화면은 `=== true`일 때만 버튼을 그린다(`async-surface.tsx:227-229`). 플래그 없는 상태는 버튼이 없다(`tests/component/async-surface.test.tsx:128-143`). 기존 테스트 하나는 입력에 `isUnknownEffectResendable: true`를 더했고 단언은 그대로다(`:63-75`). 두 파일 모두 FE-GATE-006 통과(19·35건). 런북 6.3-4가 키 없는 재저장을 적는다(`api-contract-and-server-state-recovery.md:259-264`). 생성 NEVER 페이지 테스트 "keeps a create whose response was lost unknown and offers no resend"는 FE-GATE-020에서 통과했다(`gate-artifacts/FE-GATE-020.txt` 2188행). 가드가 키 유무로만 가르는 데서 생긴 IDEMPOTENT 쪽 부작용은 새 03-03이다 |
| 1101/03-04 Low·P3 | 효과 판정과 화면 분류가 두 함수로 나뉜다 | **남음** (문서화) | `envelopeFailureEffect`(`backend-envelope.ts:352-363`)와 `envelopeFailureReading`(`:390-410`)이 그대로다. 지난 README §16.6에 이 행이 없다 |
| 0929/03-02 Medium·P2 | `x-correlation-id` CORS 허용이 문서 통제뿐이다 | **남음** | 계약 §5의 문장뿐이다(`backend-api-and-server-state-contract.md:257-267`). `8a44226` 뒤 바뀐 것이 없다. 지난 README §16.6에 이 행이 없다 |
지난 라운드에 고쳐짐으로 판정한 03 항목(1103/03-03·03-04·03-05·03-06·03-08, 1101/03-03·03-06, 0929/03-06)은 이번 범위에서 다시 열리지 않았다. 쓰기 `SAFE` 거절(`external-contract-runtime.ts:575-582`), 5xx 넷의 `MAYBE_APPLIED`(`backend-envelope.ts:256-281`), `effect_certainty`(`src/bootstrap/runtime-adapters.ts:213`), 실패 `traceId`(`http-execution-v3.ts:1716-1721`), descriptor에서 받는 operation ID(`server-state.ts:294-313`, 1103/16-05로 brand 타입), UNKNOWN 동안 identity lease(`application-query.ts:689-693`)가 그대로 있고 해당 테스트가 게이트에서 통과했다.
**고친 커밋이 검사를 약하게 만들었는가(관점 10·21).** `git diff 8a44226..bbde570`의 영역 테스트 11파일을 봤다(+835/−21). 지운 줄 21개는 셋이다. ① operation ID 문자열 → `testMutationOperationId(...)`(1103/16-05의 brand 타입). 값은 같다. ② `form-foundation.test.tsx`의 선언 목록 `["WORKLOG_INVALID"]` → `["WORKLOG_INVALID", "POSTER_ALREADY_EXISTS"]`(넓힌 것). ③ pin 스키마의 `tables`에 `backendExcerpt`가 더해졌다(1105/07-01). 새 `.skip`·`.todo`·`skipIf`·시간 상한 상향은 없다(`git diff ... | grep`). `async-surface.test.tsx:63-75`의 입력 변경은 의도한 동작 변경에 맞춘 것이고 버튼 단언은 그대로다. 제거 fixture가 문서를 읽는 테스트를 파일째 빼는 목록에 pin 테스트가 들어간 것(`scripts/lib/removal-fixture.ts:70-82`)은 검사 범위를 줄였다. 12 영역이 1106/12-01로 셌다. 여기서는 세지 않는다. **이 영역에서 약해진 검사는 찾지 못했다.**
## 3. 이번 발견 (36.3)
새 발견 3건: Medium 1 · Low 2 / P2 1 · P3 2 / 확인된 결함 2 · 개선 제안 1. High 이상과 P1은 없다.
| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 03-01 | Medium | P2 | 확인된 결함 | 6, 12, 28, 17, 10, 5 | KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절(429·503 `RATE_LIMIT_*`)이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 다음 저장은 새 키다 |
| 03-02 | Low | P3 | 확인된 결함 | 17, 23, 10, 5 | 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 그 경로의 테스트가 없다 |
| 03-03 | Low | P3 | 개선 제안 | 28, 23, 22, 24, 12 | 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송 버튼과 같은 입력 재제출이 막힌다 |
### 03-01 KEYED 결과 불명의 같은 키 재전송이 쓰기 전 거절이나 보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(코드 확인 + 실험 03-R1 재현) |
| 관련 관점 | 6, 12, 28, 17, 10, 5 |
| 근거 | **훅.** 같은 키 재전송(`resendUnknownEffect`)과 같은 입력 재저장은 같은 `submit`으로 간다(`application-query.ts:822-826`). `submit`은 결과 불명 admission을 찾으면 보내기 전에 그것을 정리한다(`:564-567`, `:599-604`). 새 admission이 그 intent와 키를 그대로 쓴다(`:613-615`). 결과가 `MAYBE_APPLIED`면 새 admission이 다시 UNKNOWN이 되어 키가 남는다(`:684-698`). 그러나 `NOT_APPLIED`나 `NOT_STARTED`면 그냥 정리한다(`:667-672`). 이번 시도의 판정을 그 논리 요청 전체의 판정으로 쓴다. 실행기는 한 실행 안의 시도들에 대해서는 "앞 시도보다 낮게 보고하지 않는다"를 지킨다(`http-execution-v3.ts:589-618`, `:1143-1155`). 훅의 재전송은 새 실행이라 그 규칙 밖이다. **쓰기 전 거절이 재전송에 오는 길.** (a) 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`: 1105/03-02 뒤 표가 `NOT_APPLIED`로 정한다(`backend-envelope.ts:177-181`, `:357`). KEYED는 이 답에 자동 재전송이 없다(`tests/integration/http-execution-v3-envelope.test.ts:956-970`). 백엔드는 이 503을 멱등성 executor보다 앞인 interceptor에서 낸다(`RateLimitInterceptor.java:31-42`, 모든 경로 `RateLimitWebConfig.java:61-62`). 그래서 첫 요청이 적용됐어도 같은 키 재전송이 이 답을 받을 수 있다. (b) 429·401·403: 생성 쓰기의 `classifyStatus`가 `NOT_APPLIED`다(`scripts/create-feature-write-slice.ts:305-309`). 1105/03-02 전부터 있던 길이다. 401은 세션이 만료된 뒤 재전송할 때 온다. (c) 보내기 전 거절(`NOT_STARTED`). 실행기에서 이 값은 보내기 전 검사에서만 나온다. scope fence, intent·입력 검사, 자격 증명 확인 실패다(`http-execution-v3.ts:752-869`). 오프라인 검사는 없다. **폼과 생성 페이지.** 폼은 `action: "retry"`인 실패에서 보관한 제출을 지우고 `retry-later`가 된다(`use-app-form.ts:305-314`). 그 뒤에는 저장이 열린다(`:386`). 생성 페이지는 `retry-later`의 실패 상태에 "다시 시도"를 달고 그것이 `form.submitForm()`이다(`create-feature-write-slice.ts:716-719`). 결과 불명이 풀렸으므로 훅은 새 intent와 새 키를 만든다(`application-query.ts:613-619`). **계약.** 백엔드 §2는 처리 중 409와 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`에 "새 키 금지"를 적는다(`45d2a478:docs/web/http-contract.md:89`, `:112`). 런북 6.3-4도 "`UNKNOWN` effect에 새 key를 생성해 retry하지 않는다"고 적는다(`api-contract-and-server-state-recovery.md:254`). 이 길을 보는 테스트는 없다. 재전송 테스트는 모두 `MAYBE_APPLIED`나 성공으로 끝난다(`application-mutation-admission.test.tsx:451-650`, `tests/component/application-query.test.tsx`에도 없음). **실험 03-R1**(`R5-03-R1.log`, 5/5 통과). 훅에서 첫 요청을 결과 불명으로 만들고, 같은 키로 재전송한 뒤, 같은 입력으로 다시 저장했다. 재전송 결과가 503 `RATE_LIMIT_UNAVAILABLE`(X1), 429(X2), `NOT_STARTED`(X3)이면 셋 다 재전송 뒤 `indicator=null`, `canResend=false`이고 `keys=["key-1","key-1","key-2"]`다. 대조 X4(재전송도 `MAYBE_APPLIED`)는 `indicator="mutation-effect-unknown"`이고 `keys=["key-1","key-1","key-1"]`다. X5는 실제 실행기·바인딩·폼을 쓴 KEYED Envelope create다. 첫 저장의 답을 잃으면 `effect-unknown`이다. 재전송이 503 `RATE_LIMIT_UNAVAILABLE`을 받으면 `retry-later`가 되고 결과 불명 표시가 사라진다. 다시 저장하면 `success`로 끝난다. fetch는 3회, 키는 `["key-1","key-1","key-2"]`다 |
| 발생 조건 | KEYED 쓰기(`create:feature --with-create --keyed`, 백엔드 create도 KEYED). 첫 요청의 답이 사라지거나 결과 불명 답(503 `IDEMPOTENCY_COMPLETION_UNKNOWN` 등)이 온다. 사용자가 재전송했는데 그 시점에 rate limit이 429를 주거나, rate-limit 저장소가 응답하지 않거나(503), 세션이 만료돼 401이 온다. 사용자가 "다시 시도"나 저장을 누른다. rate limit은 백엔드 기본이 꺼져 있다(`45d2a478:src/sample-portfolio/src/main/resources/application.yml:176`). 멱등성 저장소와 rate limit을 모두 Redis로 쓰는 구성(`RedisIdempotencyStoreAdapter.java`)에서는 Redis 장애 하나가 `COMPLETION_UNKNOWN`(첫 요청은 실행됐다)과 재전송의 503 `RATE_LIMIT_UNAVAILABLE`을 함께 만든다(추론, 실행 확인 안 함) |
| 영향 | 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 화면은 결과 불명 대신 "잠시 뒤 다시 시도"를 보이므로 사용자는 확인 없이 다시 보낸다. 가이드 35.2의 High 예시(결과 불명 작업의 무방비 재실행)와 같은 모양이다 |
| 심각도·우선순위 | Medium · P2 — 피해는 중복 생성이지만 조건이 겹쳐야 한다. 현실적인 계기는 opt-in rate limit(429, 503 `RATE_LIMIT_*`)이나 만료된 세션(401)이다. KEYED도 opt-in이다. 답을 잃은 뒤 재전송하는 그 시점에 이 거절이 와야 한다. 0929/03-03(High)은 저장을 한 번 더 누르는 것만으로 닿았다. 그보다 훨씬 드물다. 템플릿 기본(NEVER, rate limit 꺼짐)은 닿지 않는다. 다만 템플릿 자신의 생성 KEYED 페이지가 이 길을 연다. 오케스트레이터도 코드를 다시 읽고 같은 등급으로 봤다. 03-R1에서 다른 길은 나오지 않았다 |
| 통제·증거 | 재전송 결과를 그 논리 요청의 앞선 결과와 합치는 통제: M0(훅 `:667-672`에 없음, 경로 확인) · E1(코드), E2(실험 03-R1) |
| 확실성과 남은 가정 | 훅·폼의 분기는 코드와 실험으로 확정이다. 생성 페이지의 "다시 시도" 연결은 코드로 확인했다(실험 X5는 그 버튼 대신 Submit을 눌렀다). 실제 백엔드에서 재전송이 rate-limit 거절을 받는 빈도는 확인하지 않았다. 0929/03-03의 같은 입력 가드는 키 없는 intent만 막으므로 이 길과 상관없다 |
| 결정의 근거 | `[사실]` 훅 주석은 재전송이 "이제 결과를 갖는다"고 적는다(`application-query.ts:600-601`). `[사실]` 런북 6.3-6은 "`NOT_APPLIED`가 증명된 경우만 retry"라고 적는다(`api-contract-and-server-state-recovery.md:267-268`). 재전송의 `NOT_APPLIED`는 그 시도만 증명한다. `[추론]` 1105/03-02의 최소 개선(지난 03 문서 3절)과 그 커밋은 KEYED 자동 재전송만 봤고, 사용자가 일으키는 재전송의 결과는 보지 않았다 |
| 이해 비용 | KEYED 화면을 만드는 사람은 "재전송이 적용 안 됨으로 끝나면 결과 불명이 풀린다"를 코드에서만 알 수 있다. 매뉴얼과 런북은 반대로 적는다("결과를 모를 때 새 키로 다시 보내면 안 된다", `docs/manual/02-decision-tables.md:95`, 런북 6.3-4) |
| 최소 개선 방향 | 훅에서, 결과 불명 intent를 다시 쓴 시도가 `NOT_APPLIED`나 `NOT_STARTED`로 끝나면 admission을 UNKNOWN으로 되돌리고 그 intent를 남긴다. 실패는 그대로 돌려준다. 그러면 폼은 `retry-later`를 보이더라도 다음 저장이 같은 키로 간다. 폼은 `unknownSubmissionRef`를 지우지 않거나, 훅 상태(`mutation-effect-unknown`)를 보고 저장을 막는다 |
| 대안 비교 | (a) 훅에서 되돌리기(위): 한 곳, 모든 화면에 적용. (b) 표에서 rate-limit 503을 다시 `MAYBE_APPLIED`로: 503의 길만 막고 429·401·`NOT_STARTED`는 남는다. 1105/03-02의 이득(NEVER 생성 쓰기의 거짓 결과 불명 제거)도 잃는다. (c) 생성 페이지의 "다시 시도"를 결과 불명 뒤에는 `resendUnknown`으로 잇기: 생성 기능만 고친다. (a)는 한 곳만 고치고 모든 화면을 덮는다 |
| 단순화의 보존 조건 | 처음 보내는 요청의 `NOT_APPLIED`는 지금처럼 정리된다(다음 저장은 새 키, 1103/03-01). 재전송이 성공·`APPLIED_CONFIRMED`면 지금처럼 정리된다. KEYED 503 `IDEMPOTENCY_UNAVAILABLE` 자동 재전송은 그대로다 |
| 비용·부작용 | 훅 분기 몇 줄과 테스트 둘(훅, 폼). 재전송이 429로 막힌 동안 결과 불명 화면이 남는다. 그때 화면에 "잠시 뒤 같은 요청으로 다시 보내기"를 보여야 한다(문구 하나) |
| 재검토 조건 | 백엔드가 rate limit을 멱등성 판정 뒤로 옮기거나, 같은 키 요청을 rate limit에서 빼면 (a)의 503 부분은 필요 없다. 429·`NOT_STARTED`는 남는다 |
| 완료 기준 | 03-R1 X1~X3에서 재전송 뒤 상태가 `mutation-effect-unknown`이고 `keys`가 `["key-1","key-1","key-1"]`이다. X5에서 세 번째 요청의 키가 `key-1`이거나 세 번째 요청이 나가지 않는다 |
| 검증 방법 | `application-mutation-admission.test.tsx`의 "unknown-effect replay (D-1)" 묶음에 `it.each` 1건(재전송 결과 `NOT_APPLIED`·`NOT_STARTED`). `form-foundation.test.tsx`의 KEYED Envelope 폼에 1건(답 유실 → 재전송 503 `RATE_LIMIT_UNAVAILABLE` → 저장 → 키) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | `bbde570`, 03-R1: X1~X3·X5에서 결함이 재현됐다(위 근거). 수정 뒤 같은 실험의 X1~X3·X5 키가 모두 `key-1`이어야 한다 |
### 03-02 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(문서와 코드 불일치) |
| 관련 관점 | 17, 23, 10, 5 |
| 근거 | 계약 6.1절: "자동 재전송은 없다(KEYED도 같다)"(`backend-api-and-server-state-contract.md:342`). 코드: 표가 `NOT_APPLIED`로 정하면(`backend-envelope.ts:177-181`) `retryHint`는 503의 재시도 status 여부다(`http-execution-v3.ts:1786`, `http-retry-lifecycle.ts:4-6`). 실행기는 `NOT_APPLIED`이고 `SAFE`·`IDEMPOTENT`면 `retryBudget` 안에서 다시 보낸다(`http-execution-v3.ts:1116-1138`, `http-retry-lifecycle.ts:32-34`). 쓰기의 `IDEMPOTENT`는 조립이 받고 `retryBudget > 0`도 막지 않는다(`external-contract-runtime.ts:575-582`, `:610-615`). CHANGELOG와 커밋은 코드와 같다. "IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다"(`CHANGELOG.md:61`, `c6c37f3` 본문 "위험·한계"). 503 `RATE_LIMIT_INCOMPATIBLE`은 백엔드가 `retryable: false`로 보내지만(`RateLimitTransportError.java:9`) 실행기는 status로 판단해 다시 보낸다(같은 본문). 이 경로를 보는 테스트가 없다. 통합 테스트는 KEYED의 무재전송만 본다(`http-execution-v3-envelope.test.ts:956-970`) |
| 발생 조건 | 손으로 쓴 IDEMPOTENT Envelope 쓰기(PUT·DELETE)에 `retryBudget`을 1 이상 준다. 템플릿 안에는 IDEMPOTENT 쓰기가 없다(생성 쓰기는 NEVER·KEYED, `create-feature-write-slice.ts:25`) |
| 영향 | 6.1절을 읽은 작성자는 이 503에서 요청이 한 번만 나간다고 본다. 실제로는 `Retry-After`(5초 이하, `http-retry-lifecycle.ts:54-67`) 뒤 한 번 더 나간다. 쓰기 전 거절이라 중복은 없다. `INCOMPATIBLE`은 같은 답을 한 번 더 받는다 |
| 심각도·우선순위 | Low · P3 — 문서 한 줄의 불일치. 데이터 피해 없음 |
| 통제·증거 | 6.1절 문장과 실행기 동작을 맞추는 통제: M0(문서와 코드를 대조하는 검사 없음, 테스트 없음) · E1(코드·문서 대조) |
| 확실성과 남은 가정 | 코드 경로는 확정이다. 실행으로 재현하지 않았다(E1) |
| 결정의 근거 | 적용 제외 — 문서가 코드와 CHANGELOG를 따라가면 되는 문제다 |
| 이해 비용 | IDEMPOTENT 쓰기 작성자가 계약 문서, CHANGELOG, 실행기 셋을 맞춰 읽어야 안다 |
| 최소 개선 방향 | 6.1절 문장을 "KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 `Retry-After` 뒤 다시 보낸다"로 고친다. `INCOMPATIBLE`을 다시 보내지 않으려면 표에 "재시도 안 함"을 싣는다(선택) |
| 대안 비교 | 적용 제외 — 문서 정정이다. `INCOMPATIBLE` 재시도를 막는 것은 별도 선택이다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 1줄, 통합 테스트 1건(IDEMPOTENT PUT, `retryBudget: 1`, 503 → 200, fetch 2회) |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 6.1절과 `CHANGELOG.md:61`이 같은 동작을 적고, 그 동작을 테스트 하나가 고정한다 |
| 검증 방법 | `http-execution-v3-envelope.test.ts`에 IDEMPOTENT 1건 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 03-03 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다
| 필드 | 내용 |
|---|---|
| 성격 | 개선 제안 |
| 관련 관점 | 28, 23, 22, 24, 12 |
| 근거 | 뮤테이션 정책은 키 여부만 받는다. `commandMutationIdentity`가 `requiresIdempotencyKey: retrySemantics === "KEYED"`를 준다(`src/contracts/server-state.ts:309-312`). IDEMPOTENT 쓰기의 intent에는 키가 없다(`src/adapters/platform/browser-mutation-intent-factory.ts:38`). 재전송 버튼은 키가 있을 때만이다(`application-query.ts:853-867`, `async-surface.tsx:227-229`). 0929/03-03 수정(`683ccfb`)으로 같은 입력 재제출도 키가 없으면 거절된다(`application-query.ts:574-583`). 그 테스트가 쓰는 `keyed: false`가 IDEMPOTENT 정책과 같은 입력이다(`application-mutation-admission.test.tsx:563-583`, FE-GATE-006 통과). 그러나 매뉴얼은 IDEMPOTENT를 "같은 요청을 여러 번 적용해도 결과가 같다", 자동 재시도 "된다"로 적는다(`docs/manual/02-decision-tables.md:87-90`). 실행기도 IDEMPOTENT 쓰기를 보낸 뒤에도 다시 보낸다(`http-retry-lifecycle.ts:32-34`). 문서는 가드를 NEVER로만 설명한다(`docs/manual/01-add-a-feature.md:515`, 런북 `api-contract-and-server-state-recovery.md:259`, `CHANGELOG.md:66` "키 없는(`NEVER`)") |
| 발생 조건 | IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)의 답이 사라지거나 `MAYBE_APPLIED` 답이 와서 재시도 예산이 끝난다 |
| 영향 | 다시 보내도 안전한 요청인데 화면에 재전송이 없고, 같은 입력 저장은 `UNKNOWN_EFFECT_PENDING`으로 거절된다. 출구는 "변경됨으로 확인"(사실을 모르는 확인)이나 새로고침이다. 확인은 캐시를 새로 읽으므로 데이터 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 회복 경로가 불편하고 문구가 사실과 다르다. 안전 쪽으로 실패한다. 템플릿 안에는 소비자가 없다(다운스트림 확장 지점) |
| 통제·증거 | 키 기준 가드: M3(테스트가 고정, 03-R2·R3에서 검출) / "재전송이 안전한가"로 가르는 규칙: M0(정책에 그 값이 없다) · E1(코드), E2(FE-GATE-006의 `keyed: false` 테스트가 IDEMPOTENT 정책과 같은 입력으로 통과) |
| 확실성과 남은 가정 | 코드로 확정이다. 다운스트림에 IDEMPOTENT 쓰기가 있는지는 보지 않았다 |
| 결정의 근거 | `[사실]` 가드의 이유는 "키 없이는 서버가 두 번째 요청을 가려내지 못한다"이다(`application-query.ts:569-573`). IDEMPOTENT는 가려낼 필요가 없는 경우다. `[추론]` 정책이 `retrySemantics`를 싣지 않아 훅이 NEVER와 IDEMPOTENT를 가를 수 없다 |
| 이해 비용 | IDEMPOTENT를 고른 작성자는 결과 불명 화면이 NEVER와 같다는 것을 코드에서만 안다 |
| 최소 개선 방향 | `commandMutationIdentity`가 "같은 요청 재전송이 안전함"(KEYED 또는 IDEMPOTENT)을 함께 준다. 가드 둘(`canResend`, 같은 입력 거절)이 키 대신 그 값을 본다. 또는 현상을 유지하고 문서 셋에 "IDEMPOTENT도 NEVER처럼 다룬다"를 적는다 |
| 대안 비교 | (a) 정책에 재전송 안전 여부 추가: 정책 타입 칸 하나, 가드 두 줄. (b) 문서만: 비용 0, 회복 경로는 그대로 불편. (c) IDEMPOTENT에도 키를 붙인다: 백엔드가 키를 읽지 않으면 의미가 없다 |
| 단순화의 보존 조건 | NEVER의 재전송 금지와 같은 입력 거절은 그대로다 |
| 비용·부작용 | (a)면 `BoundMutation`에 선택 칸 하나(추가만) |
| 재검토 조건 | 템플릿이나 다운스트림에 IDEMPOTENT 쓰기가 생길 때 |
| 완료 기준 | IDEMPOTENT 정책의 결과 불명에서 재전송 버튼이 그려지고, 같은 입력 저장이 보내진다. NEVER는 지금처럼 막힌다 |
| 검증 방법 | `application-mutation-admission.test.tsx`에 IDEMPOTENT 정책 1건 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
**다른 영역에 넘기는 관찰(세지 않음).**
- 14 영역: CHANGELOG의 0929/03-03 행은 "손으로 만든 결과 불명 상태를 넘기던 화면은 버튼이 사라진다"고 적지만(`CHANGELOG.md:66`) BREAKING 표시와 "먼저 할 일" 단계가 없다. 그런 화면은 타입 오류도 테스트 실패도 없이 버튼을 잃는다. 고치는 법은 코디네이터의 `state`를 넘기는 것이다(`683ccfb` 본문).
- 01 영역: Fileserver client도 V3 표로 503 `RATE_LIMIT_*`를 `NOT_APPLIED`로 읽는다(01 문서). 03-01과 같은 재전송 정리 문제가 업로드 재시도 경로에 있는지는 01이 본다.
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1 | P — 백엔드 판정은 `backend-envelope.ts` 한 곳, 플랫폼 code 목록은 조립 검사가 쓰는 `external-contract-runtime.ts`에 있다(`:627-663`). 둘을 테스트가 묶는다. 훅이 재전송 결과를 논리 요청의 결과로 쓴다(03-01) |
| 2 | 구조적 성숙도 | 다른 영역 | — | 게이트 | > 12·16 영역. FE-GATE-010 rc=0 |
| 3 | 변경 용이성 | 적용 | M3 / M3 | E2(03-R6) | P — 6.1절 표에 플랫폼 행을 더하면 목록도 고쳐야 하고 pin 테스트가 알린다(`backend-contract-pin.test.ts:293-302`, 03-R6에서 `DB_R05_PROBE` 행을 잡음) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 판정 순서(표 → 선언 → 분류기 → 폼)와 재전송 결과 처리(03-01)를 알아야 한다 |
| **5** | 위험 가시성 | 적용 | M3 / M3 | E1 | P — 플랫폼 code를 선언하면 6.1절을 이유로 부팅이 멈춘다(1105/03-01). 재전송이 거절되면 결과 불명이 조용히 풀린다(03-01) |
| **6** | 실패 성숙도 | 적용 | M4 / M3 | E2(게이트, 변이 6개 검출, 실험 03-R1) | P — 플랫폼 code 선언 거절, rate-limit 503 판정, 키 없는 재제출 거절이 들어왔다. 남은 것: KEYED 재전송의 쓰기 전 거절 뒤 새 키(03-01) |
| 7 | 운영 성숙도 | 적용 | M2 / M2 | E2 | P — `effect_certainty`·`reason` 진단은 그대로다. 진단 sink는 메모리 버퍼뿐이다 |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2 | O — 조립 거절 문구가 code와 6.1절을 적는다(`external-contract-runtime.ts:693`) |
| 9 | 유지보수 성숙도 | 적용 | M3 / M3 | E2 | P — 답 표 9행이 사본·프론트 표와 양방향으로 묶인다. 백엔드 HEAD가 pin보다 두 커밋 앞이지만 6.1절 판정은 같다(1절). 사본과 백엔드 문서의 일치는 게이트 밖이다(07 영역) |
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(03-R2~R7) | P — 수정마다 테스트가 있고 게이트에서 통과한다. 규칙을 깨는 변이 6개가 모두 기대한 테스트에서 실패했다(03-R2~R7, 합 19건). 빈틈: 재전송이 `NOT_APPLIED`·`NOT_STARTED`로 끝나는 경우(03-01, 실험 03-R1이 그 동작을 보였다), IDEMPOTENT 쓰기의 rate-limit 503 재시도(03-02) |
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - 영속 데이터 없음. 메모리 캐시와 intent뿐이다 |
| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2 | P — 키 없는 같은 입력 재제출은 훅이 막는다(0929/03-03 고쳐짐). 한 논리 요청의 여러 시도 사이에서 확실성을 합치지 않는다(03-01) |
| 13 | 확장성 | 다른 영역 | — | — | > 11·15 영역 |
| 14 | 성능 성숙도 | 다른 영역 | — | — | > 15 영역. 1105/03-01 검사가 초기 JS를 327 B 늘렸다(지난 README §16.2 D7) |
| 15 | 보안 성숙도 | 적용 | M4 / M3 | E2 | O — 쿠키 쓰기 CSRF 조립 검사, `redirect: "error"` 등 그대로. 0929/03-02는 19번 |
| 16 | 의존성 성숙도 | 다른 영역 | — | — | > 13 영역 |
| **17** | API / Contract | 적용 | M3 / M3 | E2 | P — §2 답 전부와 §4 503 셋을 읽는다. 6.1절 문장 하나가 코드와 다르다(03-02). 03-01의 길에서 §2 "새 키 금지"를 어긴다. bulk 미지원(1103/03-02) |
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 13 영역 |
| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 교차 origin 헤더 허용은 문서뿐이다(0929/03-02) |
| 20 | 개발자 경험 | 적용 | M3 / M2 | E2 | P — 조립 거절 문구가 고치는 법을 적는다(오류 표 `errors.md:106`). 백엔드 목록 GET이 없다(1103/03-07) |
| **21** | Guardrail 성숙도 | 적용 | M4 / M4 | E2(03-R4~R6) | O — 조립이 쓰기 `SAFE`, 읽기 `KEYED`·`NEVER`, 멱등성 code, 6.1절 "쓰기 뒤 가능" 플랫폼 code, Envelope 없는 목록을 거절한다. 업무 code 선언은 설계상 작성자 판단이다 |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P — kind와 effect가 두 함수에서 정해진다(1101/03-04). 정책이 키 여부만 실어 훅이 NEVER와 IDEMPOTENT를 가를 수 없다(03-03) |
| **23** | 일관성 | 적용 | M2 / M2 | E1 | P — 실행기는 IDEMPOTENT 쓰기를 다시 보내지만 훅은 NEVER처럼 막는다(03-03). 6.1절과 CHANGELOG가 rate-limit 503 재시도를 다르게 적는다(03-02) |
| 24 | 네이밍 / 의미 | 적용 | M1 / M1 | E1 | P — NEVER·IDEMPOTENT 결과 불명의 출구가 "변경됨으로 확인" 하나다(03-03) |
| 25 | 조직 확장성 | 다른 영역 | — | — | > 14 영역 |
| 26 | Ownership | 적용 | M2 / M2 | E1 | P — pin이 담당과 대조 날짜를 적는다(`backend-contract-pin.json:51-52`). 백엔드로 넘긴 rate-limit 비동기 재디스패치 요청은 백엔드 담당 몫이다 |
| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | O — 소비자 0인 `projectCertaintyToUi`는 배럴 밖이다(결함 아님, 지난 판정 그대로) |
| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 선언한 업무 거절 뒤 고쳐서 저장한다. KEYED 결과 불명의 재전송이 쓰기 전 거절로 끝나면 회복 경로가 새 키로 바뀐다(03-01). IDEMPOTENT 결과 불명은 확인이나 새로고침뿐이다(03-03) |
X(미충족)는 없다.
## 5. 미검증
| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 03-01에서 생성 KEYED 페이지의 "다시 시도" 버튼을 실제로 눌렀을 때 | 03-R1 X5는 손으로 만든 폼에서 Submit을 눌렀다. 생성 페이지의 버튼 연결(`create-feature-write-slice.ts:716-719`)은 코드로만 봤다 | `create:feature x --with-create --keyed` 뒤 생성 페이지 테스트에 같은 시나리오 1건 |
| 03-02의 IDEMPOTENT 재시도 | 실행으로 재현하지 않았다(E1) | IDEMPOTENT PUT 통합 테스트 1건 |
| 짝 백엔드와의 실제 통합(rate limit 켠 상태에서 재전송) | 백엔드는 읽기만 했다 | 백엔드를 rate limit·KEYED create로 띄우고 Redis를 멈춰 재전송 |
| Spring MVC가 ASYNC 재디스패치에서 `preHandle`을 다시 부르는지 | 코드 실행 없이 문서·추론만 있다(계약 6.1 `:342-346`) | 백엔드 비동기 쓰기 컨트롤러로 실험(백엔드 몫) |
| 다운스트림(tech-log·memento)에 KEYED·IDEMPOTENT 쓰기나 손으로 만든 `AsyncState`가 있는지 | 다운스트림 repo를 읽지 않았다 | 두 repo에서 `retrySemantics`, `AsyncSurface` grep |
| `browser-rpc`·`auth`·`diagnostics`·`telemetry`의 세부 동작 | `8a44226` 뒤 변경이 없다. 게이트 통과만 확인했다 | 지난 라운드 변이를 다시 돌리기 |
## 6. 실행 기록
| 이름 | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 게이트(인용, 대조군) | FE-GATE-005·006·007·020, CI env, 메인 세션 2026-11-06 03:24~03:56 | — | 0 | `bbde570-ci/summary.txt`. 대상 파일 통과: `external-contract-runtime` 47, `backend-envelope` 37, `backend-contract-pin` 15, `create-feature` 46, `backend-contract-drift` 9(FE-GATE-005), `application-mutation-admission` 19, `async-surface` 35, `form-foundation` 34, `application-query` 28(FE-GATE-006), `http-execution-v3-envelope` 60, `http-execution-v3-observability` 11(FE-GATE-007). FE-GATE-020의 생성 기능 테스트 "shows the backend's refusal of the name on the field and saves again", "keeps a create whose response was lost unknown and offers no resend" 통과(`gate-artifacts/FE-GATE-020.txt` 1993행, 2187~2188행) |
| 03-R1 | `node scripts/run-vitest.ts run tests/component/r05-03-experiments.test.tsx` · local | `03-patches/03-R1-experiments.diff`(실험 파일 추가만) | vitest-rc=0 | 5/5 통과. X1 503 `RATE_LIMIT_UNAVAILABLE`, X2 429, X3 `NOT_STARTED`: 재전송 뒤 `indicator=null`, `canResend=false`, `keys=["key-1","key-1","key-2"]`. X4(대조, 재전송 `MAYBE_APPLIED`): `indicator="mutation-effect-unknown"`, `keys=["key-1","key-1","key-1"]`. X5(폼·실제 실행기): `effect-unknown`(fetch 1) → `retry-later`, 결과 불명 표시 없음(fetch 2) → `success`(fetch 3), `keys=["key-1","key-1","key-2"]`. 기대와 같다. 결함 재현 |
| 03-R2 | `... run tests/component/application-mutation-admission.test.tsx` · local | `03-patches/03-R2.diff`(키 없는 재제출 가드 삭제) | vitest-rc=1 | 1 failed / 18 passed: "refuses to send a keyless unknown request again for the same input"(`expected { ok: true, value: 'keyless-input' } to match object { ok: false, ... }`). 기대와 같다 |
| 03-R3 | `... run tests/component/async-surface.test.tsx` · local | `03-patches/03-R3.diff`(`=== true` → `!== false`) | vitest-rc=1 | 1 failed / 34 passed: "draws no resend for an unknown state that does not say it can be resent". 기대와 같다 |
| 03-R4 | `... run tests/unit/external-contract-runtime.test.ts` · local | `03-patches/03-R4.diff`(조립의 플랫폼 code 검사 삭제) | vitest-rc=1 | 4 failed / 43 passed: "refuses to declare the platform code `BAD_PARAMETER`·`MAPPING_FAILED`·`DB_UNIQUE_VIOLATION`·`LOCK_ACQUISITION_TIMEOUT` ..."(`Expected contract composition to fail.`). 기대와 같다 |
| 03-R5 | `... run tests/unit/backend-envelope.test.ts` · local | `03-patches/03-R5.diff`(실행기 fail-close 줄 삭제) | vitest-rc=1 | 5 failed / 32 passed: "keeps a declared platform code 400 `BAD_PARAMETER` / 400 `MAPPING_FAILED` / 409 `DB_UNIQUE_VIOLATION` / 409 `LOCK_ACQUISITION_TIMEOUT` / 422 `INTEGRITY_MISMATCH` maybe applied"(`expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'`). 기대와 같다 |
| 03-R6 | `... run tests/unit/backend-contract-pin.test.ts` · local | `03-patches/03-R6.diff`(6.1절 표에 "쓰기 뒤 가능" 플랫폼 행 추가) | vitest-rc=1 | 1 failed / 14 passed: "are the 6.1 table's possibly-after-write codes outside the feature-decided rows", diff `- "DB_R05_PROBE"`. 기대와 같다 |
| 03-R7 | `... run tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts tests/integration/http-execution-v3-envelope.test.ts` · local | `03-patches/03-R7.diff`(거절 표의 rate-limit 두 행 삭제) | vitest-rc=1 | 7 failed / 105 passed (112): 단위 "reads the edge's 503 %s as refused before the write" 2, pin "reads the backend's 503 `RATE_LIMIT_UNAVAILABLE`/`RATE_LIMIT_INCOMPATIBLE` as its table says" 2, 통합 "reads the edge's 503 %s as not applied, whatever the package says" 2, 통합 KEYED "does not resend the edge's 503 `RATE_LIMIT_UNAVAILABLE` on its own" 1(`effect` `MAYBE_APPLIED`). 요청서는 6건을 기대했다. 마지막 1건은 요청서가 그 묶음의 분류기를 `NOT_APPLIED`로 잘못 읽은 것이다. 실제로는 `CREATE_CONTRACT`를 쓰고 그 분류기는 `MAYBE_APPLIED`다(`http-execution-v3-envelope.test.ts:142`, `:860-863`). 그래서 더 많이 잡혔다. 같은 규칙을 보는 테스트다 |
패치 경로의 앞부분은 `/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template--claude-worktrees-happy-easley-233d07/5b935f37-0052-476e-bf8e-dcb9a2640c1a/scratchpad/r5/requests/`다. 모두 노트북에서 `git apply --check`로 `bbde570`에 적용됨을 확인했다. 배치는 오케스트레이터가 local env로 하나씩 돌렸다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-03-R1.log`~`R5-03-R7.log`다. 명령 끝의 `echo`로 항목 rc는 모두 0이다. 판정은 로그의 `vitest-rc=` 줄로 했다. 7건 모두 `restore=clean`. 변이 6개는 모두 검출됐다(합 19건 실패). 대조군(변이 없는 실행)은 위 게이트 로그로 갈음했다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 03-01 | Medium·P2 | 확인된 결함 | KEYED 결과 불명의 같은 키 재전송이 429·503 `RATE_LIMIT_*`·보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버리고, 생성 폼의 "다시 시도"가 새 키로 보낸다 | `src/presentation/adapters/query/application-query.ts:599-604`, `:667-672`; `src/presentation/forms/use-app-form.ts:305-314`; `scripts/create-feature-write-slice.ts:716-719`; `src/adapters/http/backend-envelope.ts:177-181` |
| 03-02 | Low·P3 | 확인된 결함 | 계약 6.1절은 rate-limit 503에 "자동 재전송 없음"이라 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 테스트 없음 | `docs/architecture/backend-api-and-server-state-contract.md:342`; `src/adapters/http/http-execution-v3.ts:1116-1138`, `:1786`; `CHANGELOG.md:61` |
| 03-03 | Low·P3 | 개선 제안 | 키 유무로만 가르는 가드 둘 때문에 IDEMPOTENT 쓰기도 결과 불명 뒤 재전송·같은 입력 재제출이 막힌다 | `src/presentation/adapters/query/application-query.ts:574-583`, `:853-867`; `src/contracts/server-state.ts:309-312` |
이월로 남은 것: 1103/03-01 일부(결정 대기), 1103/03-02 일부(결정 대기), 1103/03-07 일부(결정 대기), 1101/03-04 남음, 0929/03-02 남음.
@@ -0,0 +1,194 @@
# 04 realtime 어댑터 성숙도 리뷰
> 검토일: 2026-11-06 · 기준: `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/realtime/`, `src/contracts/realtime-streams.ts`, `src/application/policies/bounded-polling.ts`, 설계 `docs/architecture/realtime-events-web-push-and-bounded-polling.md`, `VD-28`. 짝 백엔드 pin `45d2a478`(이 범위에서 바뀌지 않음, 읽기만)
> 깊게 본 관점: 6, 8, 10, 17, 21, 23
> 렌즈: ① 1105 조치(`bde7fa4`, `05330e3`, `27e3dec`, `05880d1`, `1e576ef`)가 완료 기준까지 갔나 ② BREAKING `05330e3`의 코드가 커밋 footer와 CHANGELOG 안내(11-03 절 행 포함)와 맞나 ③ 조치가 검사를 약하게 하거나 새 결함을 만들었나
ID 표기: 이번 라운드 발견은 `04-01`부터 쓴다. 라운드 밖에서는 `1106/04-NN`이다. 지난 라운드는 `1105/04-NN`, 그 전은 `1103/04-NN`, `1101/04-NN`, `0929/04-NN`이다.
**이 문서의 실행 증거.** 이 리뷰어는 아무것도 실행하지 않았다. 실행 증거는 오케스트레이터의 `bbde570` 게이트 로그(CI env)와 snapshot이다. 실험 두 건(04-R1, 04-R2)을 요청했다. 오케스트레이터가 desktop에서 하나씩 돌렸다(2026-11-06 04:32, env local, 부하 4.05·4.21, 항목마다 `bbde570`으로 되돌림 `restore=clean`). 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-04-R1.log`, `R5-04-R2.log`.
**영역 판정 (35.8)**
| 범위 | 판정 | 이유 |
| --- | --- | --- |
| codec·stream coordinator·WebSocket 연결·live↔Poll handoff·reconnect coordinator | 지정 범위에서 사용 가능 | 이 범위 src는 `8a44226..bbde570`에서 바뀌지 않았다. realtime 단위 테스트 14파일 272건이 게이트에서 통과했다(FE-GATE-005). 0929/04-01 규칙을 다시 막는 테스트 둘이 생겼고, 변이 MR1을 그 둘이 잡는다(1105/04-01, 04-R1) |
| reconnect coordinator + SSE | 조건부 사용 가능 | 조합 코드가 SSE session bridge와 EOF 분류를 직접 정해야 한다(0929/04-02). `retry:` 상한 규칙은 결정 대기다(0929/04-03). bridge가 던지면(설정 오류 포함) 서버 장애로 재시도된다(새 04-01, 04-R2) |
| bounded polling + V3 HTTP 실행기 | 조건부 사용 가능 | coordinator가 생성 때 검사한 descriptor를 `execute`에 넘긴다(1103/04-01). 던지는 `execute`는 이제 `PROTOCOL_MISMATCH`로 바로 끝난다(1105/04-02). 조건 둘: `execute`가 `input.operation`을 실행기에 넘기고, V3 결과 9종을 poll 결과로 직접 바꾼다. 대응표는 없다(새 04-02) |
| 짝 백엔드 템플릿과 realtime push를 그대로 연결 | 해당 용도의 사용 보류 | 바뀐 것이 없다. pin `45d2a478`이 그대로라 설계 0.1절 대응표가 유효하다. 길 선택은 제품 결정이다 |
## 0. 결론
- 1105 새 발견 셋이 완료 기준까지 고쳐졌다. **1105/04-02**: 던지는 `execute`는 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 끝난다(`bounded-poll-coordinator.ts:336-347`, `:395-399`). 정확 비교 테스트 셋이 게이트에서 통과했다(`bounded-poll-coordinator.test.ts:911-987`). **1105/04-03**: VD-28과 설계 3절이 V3 descriptor 규칙을 적는다. V2 칸 `git grep`은 0건이다. **1105/04-01**: 조합 transport의 `OFFLINE` 테스트 둘이 생겼다(`realtime-reconnect-coordinator.test.ts:2206`, `:2246`). 완료 기준인 변이 MR1을 다시 돌렸다. 그 두 건만 "expected 1 to be 3"으로 실패하고 나머지 270건은 통과했다(04-R1).
- **1103/04-01은 고쳐짐으로 본다.** README §16.6은 "일부"라 적는다. `27e3dec`가 생성 때 검사한 바로 그 객체를 `input.operation`으로 넘긴다(`bounded-poll-coordinator.ts:149-150`, `:322-328`). 그 객체가 매번 간다는 테스트가 통과했다(`:1208`). 원래 완료 기준("`retryBudget > 0` 거절, 같은 조합에서 poll 3회 = 요청 3회")은 지난 라운드부터 충족이다. 조합 코드가 `input.operation`을 무시하는 틈은 완료 기준 밖의 잔여 위험이다. 타입 주석·설계 9.2·CHANGELOG 알려진 제한이 적는다.
- **BREAKING `05330e3`의 코드는 footer와 CHANGELOG 안내와 맞는다.** 1105 절 "먼저 할 일" 4단계(`CHANGELOG.md:27`)와 [계약] 행(`:67`), 11-03 절 행(`:298`, `1e576ef`)이 같은 규칙을 적는다. 더 정확히 하면 던진 뒤에도 lease 상태 검사가 먼저 돈다(`bounded-poll-coordinator.ts:368-393`). 그사이 offline·hidden·scope 변경·close·시간 예산 소진이 있었으면 그 kind로 끝난다. footer의 "abort로 생긴 것 제외"와 같은 방향이라 불일치는 아니다.
- 검사를 약하게 한 조치는 없다(2.1절). `05330e3`이 지운 테스트는 동작 변경을 따른 것이고, 새 기대값은 호출 횟수·결과·관측 전체를 정확 비교한다.
- 새 발견 2건. **04-01**: reconnect coordinator는 던지는 `attempt`를 서버 장애(`PROVIDER_UNAVAILABLE`)로 재시도한다(`reconnect-coordinator.ts:766-774`). `05330e3` 뒤 poll은 같은 던짐을 조합 결함으로 끝낸다. repo의 SSE bridge 예는 `attempt` 안에서 연결을 만든다. 그래서 endpoint 설정 오류가 서버 장애와 예산 소진으로 보인다. 실험 04-R2에서 `http://` endpoint는 fetch 0회, attempt 3회, `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝났다. **04-02**: 권하는 `input.operation`은 `InstalledHttpContract<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표도 없다. repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다.
- 이월 둘(0929/04-02 SSE bridge·EOF, 0929/04-03 `retry:` 범위)은 남음이다. 결정 대기이고 코드 diff가 0줄이다.
- 이번 새 발견: **Low 2**, 모두 P3. High 이상·P1은 없다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 pin `45d2a478`(`config/contracts/backend-contract-pin.json:5`)이고 이 범위에서 그 줄은 바뀌지 않았다. 백엔드는 읽지 않았다(대응표 결론이 바뀔 입력이 없음) |
| 커밋·작업 상태·확인 시점 | `bbde570`. laptop worktree(HEAD = 기준)에서 읽기만 했다. 2026-11-06 04:00~ |
| 목적과 지원 실행 구성 | 템플릿. realtime은 `RECIPE_AVAILABLE`·`AVAILABLE_NOT_COMPOSED`다(snapshot `optional-recipes.json`의 `productionComposition: false`). 조합 코드(bridge, 환경 신호, poll `execute`)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개 |
| 필수 요구와 규모·운영 목표 | 합의된 SLO 없음. 설계 11절 상한표와 13.1 실패 어휘를 기준으로 봤다 |
| 읽은 코드·구성 범위 | `8a44226..bbde570`에서 영역을 바꾼 커밋 전부: `bde7fa4`(조합 transport `OFFLINE` 테스트), `05330e3`(던지는 execute), `27e3dec`(`input.operation`), `05880d1`(VD-28·설계 3절), `1e576ef`(CHANGELOG 11-03 절 행), 합친 커밋 `57c34ea`. 전부 읽음: `bounded-poll-coordinator.ts`, `bounded-polling.ts`, 위 커밋의 diff와 테스트 변경. 필요한 부분: `reconnect-coordinator.ts`(`attempt`·`waitClosed`·`classifyClosed` 던짐 처리, `requireOnline`, 두 retry 분기), `result.ts`(`raceRealtimeTask`), `http-execution-v3.ts`(`execute` 시그니처, 결과 union, 재시도 상한, 바깥 catch, 입력 거절), `external-contract-runtime.ts`(`InstalledHttpContract`), `fetch-sse-connection.ts`(생성 검사, 거절 결과, `readSseForReconnect`), `websocket-connection.ts`(생성 검사), `sse-parser.ts`(`retry:`) |
| 읽은 문서(주장) | 설계 0.1·3·5.3·6.3·9.2·13.1절, VD-28 1절·poll 절, CHANGELOG 1105 절("먼저 할 일" 4단계, [계약] 행, 알려진 제한)과 11-03 절("먼저 할 일" 6단계, realtime 행 둘), 커밋 본문 다섯, 지난 라운드 영역 문서와 README §13·§15·§16 |
| 수행한 테스트·실험 | 직접 실행 없음. 배치 요청 둘을 오케스트레이터가 desktop에서 돌렸다(6절). 04-R1(변이 MR1, 1105/04-01 완료 기준) rc=1, 기대대로 검출. 04-R2(던지는 reconnect `attempt` 실험, 새 04-01) rc=0, 기대 값 그대로. 인용한 게이트(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56): `summary.txt` FE-GATE-001~012·020 rc=0, 013 rc=1(영역 밖). `gate-artifacts/FE-GATE-005.txt` test:unit 208파일 3,056건 통과, 그중 realtime 14파일 272건. `FE-GATE-010.txt` check:realtime-boundaries PASS, fixture PASS(2 forbidden rules), optional recipes realtime 40,826 / 42,200 gzip B. `FE-GATE-020.txt` "Realtime runtime removal: PASS (7 base checks, 24 runtime-dependent tests removed by import graph)". snapshot(`r5/snap/merge/`, `MTIMES.txt`로 이번 실행 파일만): `artifacts/quality/realtime-boundaries.json` violations 0(03:53), `artifacts/tests/realtime-runtime-removal.xml` tests 7 failures 0(03:45). `r5/snap/verify-documentation.{local,no-sibling}.txt` 둘 다 `PASS_SCOPED` |
| 확인하지 못한 범위·이유 | 실제 브라우저·SSE/WS 서버·프록시(환경 없음). 짝 백엔드 실행(읽기만). 04-02 ①의 타입 추론은 `tsc`를 돌리지 않고 시그니처로 판단했다(실행 금지). `05330e3`·`27e3dec`를 되돌리는 변이는 요청하지 않았다. 새 테스트가 호출 횟수·결과를 정확 비교하므로 정적 근거로 충분하다고 봤다(최소 요청). 0929/04-03은 코드가 그대로라 실험하지 않았다 |
| 이전 리뷰와 비교 가능한 범위 | 1105 새 발견 3건, README §16.6의 이 영역 이월 3건을 지금 코드로 다시 판정했다(2절). 지난 라운드에 고쳐짐으로 닫은 7건은 이 범위 diff가 건드렸는지만 봤다. 지난 라운드와 조치 라운드의 실행 결과(04-R1~R4, 커밋 본문의 RED·변이)는 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
| 지난 ID | 내용 | 상태 | 근거 |
| --- | --- | --- | --- |
| 1105/04-01 (Low·P3) | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다 | **고쳐짐** | `bde7fa4`. 환경은 계속 online이고 조합 transport가 `OFFLINE`을 내는 테스트 둘이 생겼다. attempt가 `OFFLINE`/`CONNECT`/retryable로 실패 → 3회, backoff `[50, 100]`, `OFFLINE` retryable로 끝, 관측 순서 고정(`realtime-reconnect-coordinator.test.ts:2206-2244`). 세션이 `OFFLINE`/`RECEIVE`로 닫힘 → 3회, `RETRY_SCHEDULED:OFFLINE` 2번(`:2246-2286`). 두 테스트 모두 `expect(attempts).toBe(3)`이다. MR1(두 retry 분기 뒤 `requireOnline()`, `reconnect-coordinator.ts:800-807`, `:995-1002`)을 넣으면 첫 attempt 뒤 online 이벤트를 기다린다. `advanceUntil`은 10초 뒤 끝난다(`:1805-1814`). 변이 없이 게이트에서 통과했다(FE-GATE-005, reconnect 46건 = 지난 44 + 2). **04-R1(MR1):** realtime 14파일 중 1파일, 272건 중 2건 실패, 270건 통과. 실패는 새 두 테스트뿐이고 둘 다 `AssertionError: expected 1 to be 3`(`:2230`, `:2278`)이다. 완료 기준("변이 MR1이 realtime 테스트에서 실패")을 충족한다 |
| 1105/04-02 (Low·P3) | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | **고쳐짐** | `05330e3`(BREAKING), `1e576ef`. 리뷰 선택지 (b)를 골랐다. `REJECTED`이면 lease가 abort된 경우만 `ABORTED` 결과, 아니면 `null`이다(`bounded-poll-coordinator.ts:336-347`). `null`은 모양이 틀린 결과와 같은 길로 `PROTOCOL_MISMATCH`(`retryable` 기본 false, `:855-860`)가 된다(`:395-399`). 타입 주석(`:105-110`), 설계 9.2(`realtime-events-…md:1674-1675`)와 13.1 두 행(`:1966`, `:1967`)이 같은 규칙을 적는다. 테스트: 비동기 거절·동기 던짐 둘 다 execute 1회, 결과 `PROTOCOL_MISMATCH`/`POLL`/false, 관측 `[LEASE_STARTED, LEASE_STOPPED:PROTOCOL_MISMATCH]`, 상태 `IDLE`(`bounded-poll-coordinator.test.ts:911-960`). 호출자 abort로 생긴 거절은 `ABORTED`(`:962-987`). 게이트 통과(bounded-poll-coordinator 24건). 옛 동작(3회 재시도, `POLL_BUDGET_EXHAUSTED`)이면 `toHaveBeenCalledTimes(1)`과 결과 비교가 실패한다(정적). V3 실행기는 바깥 catch로 모든 내부 실패를 `NETWORK_FAILURE` 결과로 돌려준다(`http-execution-v3.ts:1169-1173`). 그래서 권하는 조합에서 던짐은 조합 코드 결함이다. 완료 기준("던지는 execute의 결과로 조합 결함과 서버 장애를 구분")을 충족한다. 남은 것: 원인 예외는 여전히 남지 않는다(닫힌 관측 어휘). 조합 코드가 `execute` 안에서 기록해야 한다 |
| 1105/04-03 (Low·P3) | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | **고쳐짐** | `05880d1`. VD-28 1절 끝이 "V3 contract executor가 실행하는 V3 REST descriptor 하나다(GET·HEAD, SAFE·IDEMPOTENT, `frontend.retryBudget: 0`, 상세 설계 9.2)"다(`VD-28-…md:117-120`). poll 절이 descriptor 조건과 `retryBudget` 0 거절을 적는다(`:442-446`). 설계 3절도 같은 말이고 ETag가 V3 실행기에 아직 없다고 적는다(`realtime-events-…md:365-372`). 완료 기준 `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" bbde570 -- docs/architecture/decisions/VD-28*` 0건. `REST \`QUERY\``·`replay-safe`도 두 문서에서 0건이다 |
| 1103/04-01 (Medium·P2) | bounded polling 계약이 V2 자기 선언이라 V3 실행기 재시도를 막지 못한다 | **고쳐짐** (README §16.6은 "일부") | 완료 기준("`retryBudget > 0` descriptor는 조립 때 거절, 실험 P 조합에서 poll 3회 = 요청 3회")은 `a65df74`부터 충족이고 지금도 같다. 생성 검사 `frontend.retryBudget !== 0`(`bounded-polling.ts:129`), 실행기 재시도 상한 `min(policy.retryBudget, maxRetryAttempts, 2)`(`http-execution-v3.ts:911-915`). 테스트 "refuses the default read descriptor"(`bounded-poll-coordinator.test.ts:1171`), "sends one request per poll attempt"(`:1178`, 요청 수 = `maxAttempts`)가 게이트에서 통과했다. **`27e3dec`가 지난 라운드의 남은 틈을 좁혔다.** coordinator가 생성 때 한 번 잡은 객체(`:149-150`)를 모든 `execute`에 `input.operation`으로 넘긴다(`:322-328`). 테스트의 V3 조합도 클로저 대신 그것을 쓴다(`bounded-poll-coordinator.test.ts:1147-1152`). 매 호출이 같은 객체라는 테스트가 있다(`:1208-1248`, `toBe(pollOnly)`). **잔여 위험:** 조합 코드가 `input.operation`을 무시하고 다른 행을 넘기면 attempt마다 요청이 최대 3번이다. 타입 주석(`bounded-poll-coordinator.ts:113-118`), 설계 9.2(`realtime-events-…md:1671-1674`), CHANGELOG 알려진 제한(`CHANGELOG.md:103`)이 적는다. 실행기 타입이 `adapters/http`에 있어 coordinator가 직접 부를 수 없다는 커밋의 판단(adapter 사이 import 금지)은 맞다. 이 잔여는 원래 완료 기준 밖이라 "일부"가 아니라 고쳐짐 + 잔여 위험으로 둔다. `input.operation`의 타입 문제는 따로 새 04-02로 적었다 |
| 0929/04-02 (Medium·P2) | SSE↔reconnect 세션 bridge 부재, EOF 분류 미정 | **남음** (결정 대기, README §16.6) | `git diff 8a44226..bbde570 -- src/adapters/realtime/sse src/adapters/realtime/reconnect-coordinator.ts` 0줄. 도구는 여전히 `readSseForReconnect` 하나다(`fetch-sse-connection.ts:498-513`). 테스트 안의 bridge가 `200` 뒤 EOF를 `PROTOCOL_MISMATCH`/`RECEIVE`/false로 끝낸다(`realtime-reconnect-coordinator.test.ts:1791-1798`). 두 SSE 묶음은 여전히 "Only connect failures are exercised here"다(`:2001`, `:2065`). 설계 6.3 상태표는 `204`만 정한다(`realtime-events-…md:1087-1088`) |
| 0929/04-03 (Low·P3) | SSE `retry:` 처리 규칙이 설계 5.3·6.3과 코드에서 다르다 | **남음** (결정 대기, README §16.6) | `sse-parser.ts:330-341` 그대로다(`maxRetryMs`를 넘는 값은 버림). 5.3은 not-before이고 상한을 넘으면 종료라 적는다(`realtime-events-…md:803-807`). 6.3은 "ceiling을 통과한 경우 다음 delay hint로만"이다(`:1079-1080`). 두 절과 코드가 여전히 다른 말을 한다 |
| 1103/04-02·04-03·04-04·04-05·04-06, 0929/04-04, 1101/04-03 | 지난 라운드에 고쳐짐 | 유지 | 이 범위 src diff는 `bounded-poll-coordinator.ts`, `bounded-polling.ts` 둘뿐이고 테스트 diff는 추가와 poll 기대값 변경뿐이다(2.1절). snapshot 바인딩 표(`realtime-stream-registry.test.ts`, 30건), WS 초당 상한(`websocket-connection.test.ts`, 24건)이 게이트에서 통과했다. 1103/04-02 대응표의 입력인 pin commit이 그대로다. 다시 판정하지 않았다 |
### 2.1 조치가 검사를 약하게 만들었는가 (`git diff 8a44226..bbde570`)
| 커밋 | 테스트·검사 변경 | 판정 |
| --- | --- | --- |
| `bde7fa4` | `realtime-reconnect-coordinator.test.ts`에 87줄, 테스트 2건만 더했다 | 강해짐. 정확 비교(`toBe(3)`, `toEqual`)다. 변이 MR1을 두 건이 잡는다(04-R1) |
| `05330e3` | "retries a throwing executor as PROVIDER_UNAVAILABLE"(옛 `:906-948`)을 지우고 `it.each` 2건 + abort 보존 1건을 더했다 | 약해지지 않음. 지운 기대값은 바뀐 동작이었다. 새 기대값은 호출 횟수·결과·관측 전체·상태를 본다. 결과로 온 `PROVIDER_UNAVAILABLE`의 재시도는 다른 두 테스트가 계속 본다(`:1178`, `:1208`, 둘 다 호출·요청 수 = `maxAttempts`) |
| `27e3dec` | V3 조합 테스트가 클로저 descriptor 대신 `input.operation`을 쓴다. 테스트 1건 추가 | 약해지지 않음. 실행기가 `retryBudget`을 읽는 경로는 같은 객체(`retryBudget: 0`)로 계속 지난다 |
| `05880d1`, `1e576ef` | 문서만 | 해당 없음 |
skip·only·시간 상한·허용 목록 변경은 영역 diff에 없다(`git diff … | grep` 0건).
한 가지 기록(결함 아님): `bounded-poll-coordinator.ts:344-346`의 `controller.signal.aborted ? realtimeFailure("ABORTED", …) : null`에서 `ABORTED` 갈래는 결과에 닿지 않는다. lease의 controller를 abort하는 곳은 `stop()`(먼저 `stopKind`를 정함, `:209-213`)과 `close()`(상태 `CLOSED`, `:584-589`), `CLOCK_FAILED` 분기(그 자리에서 반환)뿐이다. 그래서 abort된 뒤에는 `:368-381`의 `currentFailure`가 항상 먼저 반환한다. 동등 분기다. 테스트 "keeps ABORTED"(`:962`)는 그 갈래를 지우는 변이를 잡지 못하지만, 동작이 같으므로 문제가 아니다(정적, E1).
### 2.2 BREAKING `05330e3` — 코드와 안내 대조
| 주장(출처) | 코드 | 판정 |
| --- | --- | --- |
| footer: "`execute`가 던지면(abort로 생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가 끝난다" | `:336-347` → `:395-399` → `pollFailure("PROTOCOL_MISMATCH")`, retryable 기본 false(`:855-860`). abort된 경우는 `:368-381`이 abort 이유(`ABORTED`·`OFFLINE`·`POLL_BUDGET_EXHAUSTED`·`CLOSED`)로 끝낸다 | 맞음. 덧붙이면 abort가 없어도 던진 사이 환경이 바뀌면(hidden·offline·scope) 그 kind, 시계가 깨지면 `PROVIDER_UNAVAILABLE`, 시간 예산이 끝나면 `POLL_BUDGET_EXHAUSTED`다(`:368-393`). 모두 lease 검사가 결과 해석보다 먼저라는 기존 규칙이다 |
| footer: "전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다" | `git show 8a44226:src/adapters/realtime/polling/bounded-poll-coordinator.ts`의 `REJECTED` 분기(`:322-328`) | 맞음 |
| footer·CHANGELOG 4단계: "네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다" | 그 결과는 `parseAttemptResult`를 지나(`:640-678`) 재시도된다(`:405-432`, 재시도 kind `:135-139`) | 맞음. 테스트 `:1208`이 정확히 그 결과로 `maxAttempts`번 부른다 |
| CHANGELOG 1105 절 4단계(`CHANGELOG.md:27`)·[계약] 행(`:67`): "lease 자신의 abort 제외", "`input.operation`이 실린다(추가만)" | `execute` 입력에 칸을 더했을 뿐 기존 `execute`는 그대로 돈다. check:types 통과(FE-GATE-003) | 맞음 |
| CHANGELOG 11-03 절 행(`:298`, `1e576ef`): "poll은 이 범위 끝에서 던지는 execute를 lease 안에서 다시 시도했다. 위 절에서 다시 바뀌어 … `PROTOCOL_MISMATCH`로 끝난다(1105/04-02)" | 위와 같음 | 맞음. 절마다 범위 끝 사실을 적는 규칙(`:7`)과도 맞다. 11-03 절 "먼저 할 일" 6단계(`:202`)의 "SSE·poll이 서버에 닿지 못한 실패는 `PROVIDER_UNAVAILABLE`"은 주석이 없다. 그러나 1105 절 머리가 "아래 절의 먼저 할 일을 마친 뒤"라 적고(`:20`) 4단계가 덮는다. 권하는 V3 조합에서는 그 문장이 지금도 사실이다(`NETWORK_FAILURE` 결과 → `PROVIDER_UNAVAILABLE`, 13.1 `:1966`) |
| `changelog-review-ids` 테스트 | FE-GATE-005에서 2건 통과 | 맞음 |
## 3. 이번 발견 (36.3)
이번 발견 2건: **Low 2** · **P3 2** · 구조적 위험 1, 개선 제안 1.
### 04-01 reconnect coordinator는 던지는 `attempt`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 조합 결함으로 끝내, 두 coordinator가 반대로 읽는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험(진단 의미 불일치. `05330e3`이 poll만 바꿔 생김) |
| 관련 관점 | 23, 8, 24, 5, 6 |
| 근거 | ① reconnect: `attempt`가 던지면 `providerRetry`로 `PROVIDER_UNAVAILABLE`/`CONNECT`/retryable을 만들고 다시 시도한다(`reconnect-coordinator.ts:766-774`, `:1569-1584`). 열린 세션의 `waitClosed`가 던져도 같다(`:954-961`). `classifyClosed`가 던지면 `PROTOCOL_MISMATCH`로 끝낸다(`:963-978`). ② poll: 같은 던짐을 재시도 없이 `PROTOCOL_MISMATCH`로 끝낸다(`bounded-poll-coordinator.ts:336-347`, `:395-399`). 13.1 `PROTOCOL_MISMATCH` 행이 이것을 "조합 코드 결함"이라 적는다(`realtime-events-…md:1967`). ③ reconnect `attempt` 타입(`reconnect-coordinator.ts:167-176`)과 13.1 `PROVIDER_UNAVAILABLE` 행(`:1966`)은 던진 `attempt`가 어떻게 되는지 말하지 않는다. 5.3은 `waitClosed` throw가 예산 초기화 경로에 든다고만 적는다(`:811-813`). 차이는 커밋 `05330e3` 본문의 "위험·한계"에만 있다("이번 범위 밖"). ④ 템플릿 transport는 연결 실패를 던지지 않고 결과로 돌려준다(SSE fetch 거절 `fetch-sse-connection.ts:217-225`, reader 거절 `:402-407`, WS `error` `websocket-connection.ts:443`). 던지는 곳은 생성 때 설정 검사다. SSE endpoint가 same-origin HTTPS가 아니면(`fetch-sse-connection.ts:112-118`, `:515-536`), WS endpoint·barrier가 틀리면(`websocket-connection.ts:260-275`) `TypeError`다. ⑤ repo의 SSE bridge 예("The smallest SSE bridge design 6.3 leaves to composition", `realtime-reconnect-coordinator.test.ts:1758-1803`)는 `attempt` 안에서 연결을 만든다(`:1764-1770`). 그 모양에서 endpoint 설정 오류는 attempt마다 던진다. ⑥ **실험 04-R2**(rc=0): 같은 모양(`attempt` 안에서 `createFetchSseConnection` → `readSseForReconnect`)에 `http://app.example.test/events`를 넣고 환경은 계속 online. 결과: fetch 0회, attempt 3회, 세 번 모두 `TypeError: SSE endpoint must be fixed same-origin HTTPS.`, backoff `[50, 100]`, 결과 `PROVIDER_UNAVAILABLE`/`CONNECT`/retryable true, 관측 `ATTEMPT_STARTED`, `RETRY_SCHEDULED:PROVIDER_UNAVAILABLE` × 2, `RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED`. 요청을 한 번도 보내지 않은 설정 오류가 서버 장애·예산 소진으로 끝났다. 같은 던짐은 poll에서 execute 1회, `PROTOCOL_MISMATCH`다(`bounded-poll-coordinator.test.ts:911-960`, 게이트 통과) |
| 발생 조건 | 조합 코드의 `attempt`(SSE bridge, 직접 쓴 STOMP transport 등)가 결과를 만들다 던질 때. 설정 오류, 매핑 오류, 잘못된 필드 접근 |
| 영향 | 결함이 바로 드러나지 않는다. reconnect 예산(`maxAttempts`·`maxElapsedMs`) 동안 backoff로 다시 시도하고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다. 화면과 관측은 "서비스 이용 불가"로 본다. 원인 예외는 남지 않는다. 같은 조합자가 poll에서는 같은 종류의 결함을 `PROTOCOL_MISMATCH`로 본다. 데이터 손상은 없고 요청 수는 예산 안이다. 설정 오류면 네트워크 요청도 없다 |
| 심각도·우선순위 | Low · P3. 진단을 늦추는 문제이고 상한이 있다. 1105/04-02와 같은 등급이다 |
| 통제·증거 | 규칙 M2(구현) · 명시 없음(타입 주석·13.1에 없음) · E1 + E2(04-R2) |
| 확실성과 남은 가정 | 분기는 코드로, 설정 오류의 결과는 04-R2로 확인했다. 매핑 오류 같은 다른 던짐도 같은 분기를 지난다(정적). 조합 transport가 브라우저·라이브러리 API의 던짐을 그대로 올리는 경우(예: STOMP client가 연결 실패를 던짐)에는 지금 동작이 회복에 유리하다. 그래서 동작 자체가 틀렸다고 보지 않는다. 문제는 규칙이 적혀 있지 않고 poll과 반대라는 것이다 |
| 결정의 근거 | 확인한 사실: 두 coordinator 모두 조합 코드가 준 함수를 감싼다. poll의 `execute`는 던지지 않는 V3 실행기를 감싸고, reconnect의 `attempt`는 던질 수 있는 연결 API를 감쌀 수 있다. 기록된 의도: `05330e3` 본문 "그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번 범위 밖". 리뷰어 추론: 템플릿 transport는 연결 실패를 결과로 돌려주므로, 템플릿 transport만 쓰는 bridge에서 던짐은 조합 결함이다. 41절: (a) 현상 유지 (b) reconnect도 던짐을 `PROTOCOL_MISMATCH`로 끝냄 (c) 동작은 두고 `attempt`·`waitClosed` 타입 주석과 13.1에 "던짐은 transport 실패로 재시도된다. 연결 생성(설정 검사)은 `attempt` 밖에서 한다"를 적고, 테스트 bridge도 연결을 밖에서 만들게 바꿈 |
| 이해 비용 | 조합자가 run이 끝난 이유를 보려면 coordinator 코드를 읽어야 던짐이 섞였는지 안다. poll을 먼저 쓴 사람은 반대를 기대한다 |
| 최소 개선 방향 | (c). 주석 두 곳 + 13.1 한 구절 + 테스트 bridge에서 연결 생성을 `attempt` 밖으로 |
| 대안 비교 | (a) 비용 0, 진단이 늦고 두 경계가 다르게 읽힌다. (b) 조합 결함이 첫 attempt에서 드러난다. 던지는 라이브러리를 감싼 transport는 첫 연결 실패에서 run이 끝나므로, 조합 코드가 던짐을 결과로 바꿔야 한다([계약] BREAKING). (c) 동작이 같고 설정 오류는 생성 때 한 번 드러난다. 매핑 오류 같은 나머지 던짐은 여전히 재시도된다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아님 |
| 비용·부작용 | (c) 문서·테스트만. (b)는 공개 동작 변경 |
| 재검토 조건 | 템플릿이 SSE bridge(0929/04-02)나 STOMP transport를 제공하게 되면, 그 transport가 던지는지에 따라 (b)를 다시 본다 |
| 완료 기준 | 조합자가 타입 주석이나 13.1만 보고 던지는 `attempt`·`waitClosed`가 어떻게 끝나는지 안다. repo의 bridge 예에서 endpoint 설정 오류가 run 시작 전에 드러난다 |
| 검증 방법 | 문서 리뷰. 04-R2 실험 파일을 고친 bridge 모양으로 다시 돌려 attempt 0회(생성 때 throw)를 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 신규 — 해당 없음 |
### 04-02 poll `execute`를 V3 실행기에 잇는 자리에 타입과 결과 대응이 없다. 권하는 `input.operation` 경로는 입력·출력 타입을 잃는다
| 필드 | 내용 |
| --- | --- |
| 성격 | 개선 제안 |
| 관련 관점 | 20, 22, 17, 3 |
| 근거 | ① `input.operation`의 타입은 `BoundedPollOperation` = `InstalledHttpContract<unknown, unknown, unknown>`이다(`bounded-polling.ts:41-45`, `bounded-poll-coordinator.ts:119`). coordinator는 `Value`만 제네릭이다(`:97`, `:145-147`). 실행기는 `execute<Input, WireOutput, Problem>(operation: InstalledHttpContract<Input, WireOutput, Problem>, input: Input, …)`이다(`http-execution-v3.ts:551-555`). 그래서 `executor.execute(input.operation, x, …)`에서 `Input`은 `unknown`이 되어 `x`는 무엇이든 통과하고, `outcome.value`도 `unknown`이다(시그니처로 한 정적 판단, `tsc` 미실행). 클로저에 둔 기능 descriptor는 두 타입을 지킨다. 타입을 지키려는 조합 코드는 1103/04-01 잔여 위험인 클로저 경로를 쓸 이유가 생긴다. 테스트도 `{ limit: 20 }`을 타입 검사 없이 넘긴다(`bounded-poll-coordinator.test.ts:1148-1152`). 입력이 틀리면 실행기는 런타임에 `CONTRACT_VIOLATION`(`INPUT_INVALID`)을 돌려준다(`http-execution-v3.ts:774-777`, `:1839-1851`). ② `05330e3` 뒤 `execute`는 모든 결과를 poll 결과로 바꿔야 한다(`bounded-poll-coordinator.ts:105-110`). V3 결과는 9종이다(`http-execution-v3.ts:165-235`: `SUCCESS`, `PROBLEM`, `UNAUTHENTICATED`, `FORBIDDEN`, `RATE_LIMITED`, `CONTRACT_VIOLATION`, `TRANSPORT_FAILURE`, `CANCELLED`, `AUTH_INTEGRATION_FAILURE`). poll이 재시도하는 kind는 `CONNECT_TIMEOUT`·`RATE_LIMITED`·`PROVIDER_UNAVAILABLE`이고 `retryAfterMs`는 뒤 둘만 읽는다(`bounded-poll-coordinator.ts:135-143`). 대응을 적은 곳은 13.1의 한 구절(`NETWORK_FAILURE` → `PROVIDER_UNAVAILABLE`, `realtime-events-…md:1966`)뿐이다. VD-28은 "`304`, auth, cursor reset, `429/503 Retry-After`를 closed mapping"이라 적는다(`VD-28-…md:450`). 설계 9.2는 "authorization required/forbidden"에서 lease가 끝난다고 적는다(`realtime-events-…md:1690`). ③ repo의 유일한 V3 조합 예는 SUCCESS가 아닌 모든 결과를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다(`bounded-poll-coordinator.test.ts:1153-1165`). 503 재시도를 세는 테스트에는 맞지만, 이 예를 옮기면 401·403·입력 거절도 서버 장애로 `maxAttempts`번 다시 요청된다 |
| 발생 조건 | 조합 코드가 설계 9.2와 테스트 예를 보고 poll `execute`를 쓸 때 |
| 영향 | 입력 모양 오류가 `check:types`를 지나 런타임 `CONTRACT_VIOLATION`이 된다. 대응을 예대로 쓰면 그 결과와 401·403이 lease 안에서 재시도되고 `POLL_BUDGET_EXHAUSTED`로 끝난다. 설계 9.2의 "auth에서 종료"와 다르다. 요청 수는 lease 상한 안이다. 데이터 손상은 없다 |
| 심각도·우선순위 | Low · P3. 조합 코드 작성 편의와 진단 문제이고 상한이 있다 |
| 통제·증거 | 대응 규칙 M1 일부(13.1 한 구절, VD-28 목표) · 타입 연결 M0(입력·출력 타입을 잇는 수단 없음) · E1 |
| 확실성과 남은 가정 | 시그니처와 테스트 코드로 확인했다. TypeScript 추론 결과는 컴파일로 확인하지 않았다. 조합 코드가 실제로 테스트 예를 옮길지는 추론이다 |
| 결정의 근거 | 확인한 사실: realtime 어댑터는 `adapters/http`의 실행기·결과 타입을 import할 수 없다(adapter 사이 import 금지, `27e3dec` 본문). 그래서 대응 함수를 realtime 안에 둘 수 없다. 기록된 의도: 조합 코드가 `execute`를 쓴다(설계 9.2). 리뷰어 추론: 타입은 realtime 안에서 제네릭 하나로 이을 수 있고, 대응은 문서 표로 줄 수 있다. 41절: (a) 현상 유지 (b) `createBoundedPollCoordinator<Value, Operation extends BoundedPollOperation = BoundedPollOperation>`로 `operation`과 `input.operation`을 `Operation`으로 둔다 (c) 9.2에 V3 결과 9종 → poll 결과(kind·retryable·`retryAfterMs`) 표를 둔다 (d) 대응 함수를 bootstrap이나 recipe에 둔다 |
| 이해 비용 | 조합자가 V3 결과 union과 poll 재시도 kind를 둘 다 읽고 맞춰야 한다. 타입을 지킬지 `input.operation`을 쓸지 골라야 한다 |
| 최소 개선 방향 | (b) + (c). 타입 매개변수 하나와 표 하나 |
| 대안 비교 | (a) 비용 0, 클로저 경로가 계속 유리하다. (b) 런타임 동작이 같고 기본값이 있어 기존 호출이 그대로다. (c) 문서만, 테스트 예와 함께 고치면 옮겨 쓰는 실수가 준다. (d) 대응을 한 곳에 묶지만 레시피 번들과 제거 드릴의 범위가 바뀐다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아님 |
| 비용·부작용 | (b) 타입만, 공개 타입이 넓어진다(호환). (c) 문서 표 1개 |
| 재검토 조건 | 템플릿이 poll `execute` 기본 구현(V3 실행기 래퍼)을 제공하게 되면 그 구현이 표를 대신한다 |
| 완료 기준 | `input.operation`을 실행기에 넘긴 호출에서 입력이 기능 descriptor의 `Input`으로 검사된다. 9.2나 13.1에서 V3 결과마다 poll 결과를 찾을 수 있다 |
| 검증 방법 | check:types에 걸리는 타입 테스트(틀린 입력에 `@ts-expect-error`). 문서 리뷰 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 신규 — 해당 없음 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역 판정을 따름
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-005 realtime 14파일 272건 통과 | O. 바뀐 코드는 poll `REJECTED` 분기와 입력 칸 하나다. 상태 기계·terminal close는 그대로다. `ABORTED` 갈래는 동등 분기다(2.1절) |
| 2 | 구조적 성숙도 | 적용 | M4 / M4 일부 | E2 FE-GATE-010(check:architecture 419 modules, check:realtime-boundaries PASS, fixture 2 forbidden rules), snapshot `realtime-boundaries.json` violations 0 | O. `27e3dec`가 adapter 사이 import를 만들지 않으려 실행기를 받지 않았다 |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P. poll 조립은 descriptor 하나다. `execute` 대응과 SSE bridge는 직접 쓴다(04-02, 0929/04-02) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P. VD-28·설계 3절이 지금 규칙과 맞다(1105/04-03). `runLoop` 크기는 그대로다. 같은 종류의 던짐을 두 coordinator가 반대로 읽는다(04-01) |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. poll 잔여 틈은 타입 주석·9.2·CHANGELOG 알려진 제한에 있다. reconnect 던짐 규칙은 커밋 본문에만 있다(04-01) |
| 6 | 실패 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2(게이트, 04-R1, 04-R2) | P. poll 던짐이 조합 결함으로 분류된다(1105/04-02). reconnect 던짐 분류(04-01), EOF 미정(0929/04-02), `retry:` 규칙(0929/04-03) |
| 7 | 운영 성숙도 | 적용 | M2 / M2 | E1 | P. poll 결과로 조합 결함과 서버 장애를 구분한다. reconnect는 못 한다(04-01) |
| 8 | 디버깅 가능성 | 적용(깊게) | M2 / M1 | E1·E2 | P. 던짐의 원인 예외는 두 coordinator 모두 남기지 않는다(닫힌 관측 어휘, 조합 코드가 기록). 04-01 |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. VD-28 옛 어휘가 사라졌다. CHANGELOG 두 절이 같은 규칙을 적는다(2.2절). 설계 5.3의 코드 줄 번호가 조금 어긋난다(예: `fetch-sse-connection.ts:488-506` → 지금 `:498-513`, `realtime-events-…md:847`) |
| 10 | 테스트 성숙도 | 적용(깊게) | M3 / M3 일부 | E2 게이트, 변이 1건(MR1 검출, 04-R1) | P. 1105/04-01 공백에 테스트가 생겼고 MR1을 잡는다. 1105/04-02·1103/04-01 테스트는 정확 비교다. 던지는 reconnect `attempt`를 서버 장애로 보는 동작을 고정한 테스트는 없다(04-R2는 실험) |
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1 | O. cursor는 effect 성공 뒤에만 전진한다. 이번 커밋이 바꾸지 않았다 |
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. run 1개, `DRAINING`·generation fence 그대로. `27e3dec`는 생성 때 객체를 잡아 나중 변경에 흔들리지 않는다(`:149`) |
| 13 | 확장성 | 적용 | M3 / M3 | E1·E2 | P. 같은 descriptor면 poll 1 attempt = 요청 1번이다. 조합 코드가 다른 행을 넘기면 3배(1103/04-01 잔여) |
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-010 optional recipes realtime 40,826 / 42,200 gzip B(여유 1,374, 지난 라운드 40,811) | P. 예산 안이다. production 번들에는 들어가지 않는다. 브라우저 실행 성능은 미측정 |
| 15 | 보안 성숙도 | 적용 | M4 / M4 | E1 | O. 고정 same-origin endpoint(`fetch-sse-connection.ts:515-536`), URL credential 없음. 바뀐 곳 없음 |
| 16 | 의존성 성숙도 | 적용 | M3 / M3 | E1 | O. 외부 패키지 없음 |
| 17 | API / Contract 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2 | P. BREAKING 안내가 코드와 맞는다(2.2절). `input.operation`은 타입을 잃고 V3 결과 대응표가 없다(04-02) |
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P. 백엔드 배포의 SSE EOF를 재연결할지 미정(0929/04-02) |
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P. `MAX_RETRY_ATTEMPTS`가 poll에 걸리지 않는다(`http-execution-v3.ts:911-915`). 파서 `maxRetryMs`와 정책 `maxDelayMs`는 따로 논다(0929/04-03). SSE·WS 설정 오류가 `attempt` 안에서 나면 서버 장애로 보인다(04-01) |
| 20 | 개발자 경험 | 적용 | M2 / M2 | E1 | P. V3 결과 → poll 결과 표가 없다(04-02). SSE bridge 예는 테스트 안에만 있다 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 일부 | E2 FE-GATE-010·020, 04-R1 | P. poll 생성 검사는 경계에서 거절한다. 0929/04-01 규칙 회귀를 다시 검출한다(04-R1, M3). 던지는 reconnect `attempt` 규칙은 검사도 명시도 없다(04-01) |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P. poll 계약·실행기가 같은 descriptor로 이어지고 그 객체가 `execute`에 온다. 타입은 이어지지 않는다(04-02) |
| 23 | 일관성 | 적용(깊게) | M2 / M2 | E1 | P. 조합 함수의 던짐을 poll은 `PROTOCOL_MISMATCH`, reconnect는 `PROVIDER_UNAVAILABLE` 재시도로 읽는다(04-01). `APPLY_FAILED`의 `retryable`이 handoff는 true, stream은 false인 것은 그대로다 |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P. poll의 `PROVIDER_UNAVAILABLE`에서 조합 결함이 빠졌다. reconnect의 `PROVIDER_UNAVAILABLE`에는 남는다(04-01) |
| 25 | 조직 확장성 | 적용 제외 — 작성자 1인 | - | - | - |
| 26 | Ownership 성숙도 | 적용 제외 — 제품 조합 없음 | - | - | -. 짝 백엔드 push 경로와 0929/04-02·04-03의 결정자는 사용자다 |
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2 FE-GATE-020(CI env) "Realtime runtime removal: PASS (7 base checks …)", snapshot `realtime-runtime-removal.xml` tests 7 failures 0 | O |
| 28 | 회복 가능성 | 적용 | M3 / M3 일부 | E1·E2 | P. 서버 끊김 뒤 재연결로 회복한다. 조합 transport `OFFLINE` 경로에 테스트가 생겼다. EOF 뒤 회복은 조합 코드 몫(0929/04-02) |
## 5. 미검증
| 항목 | 왜 확인하지 못했나 | 확인하려면 |
| --- | --- | --- |
| 04-02 ①의 TypeScript 추론 | `tsc` 실행 금지. 시그니처로 판단 | `@ts-expect-error`를 붙인 타입 테스트 한 파일로 check:types |
| `05330e3`·`27e3dec`를 되돌리는 변이 | 새 기대값이 호출 횟수·결과를 정확 비교해 정적 근거로 충분하다고 봤다(최소 요청) | 필요하면 다음 라운드에서 한 번씩 |
| 실제 브라우저·SSE/WS 서버·프록시, 짝 백엔드 실행 | 환경 없음, 백엔드는 읽기만 | 설계 15.3의 로컬 서버 + 브라우저 실행 |
| 0929/04-03의 현재 동작 | 코드가 그대로라 실험하지 않았다 | 0929 실험 E9 재실행 |
| 브라우저에서의 realtime 실행 성능 | 측정 환경 없음. 번들 크기만 게이트에서 봤다 | lab 측정 |
## 6. 실행 기록
이 리뷰어는 아무것도 실행하지 않았다. 배치 항목은 요청 파일 `scratchpad/r5/requests/04.md`에 있다. 패치는 laptop worktree(`bbde570`)에서 `git apply --check`만 했다. 오케스트레이터가 desktop `/home/donghyeon/workspace/clean-architecture-frontend-template`에서 한 번씩 돌렸다(2026-11-06 04:32, env local, head `bbde570`, 항목마다 `restore=clean`). 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-04-R1.log`, `R5-04-R2.log`.
| 이름 | 명령 | 변이 | rc | 결과 | 부하 |
| --- | --- | --- | --- | --- | --- |
| 04-R1 (MR1) | `node scripts/run-vitest.ts run tests/unit/realtime/ --reporter=default` | `scratchpad/r5/requests/04-R1-mr1.patch`: `reconnect-coordinator.ts:806`, `:1001` 뒤에 `if (… .kind === "OFFLINE") requireOnline();` | 1 | **검출.** 14파일 중 1파일, 272건 중 2건 실패, 270건 통과. 실패: "retries a composer transport's OFFLINE attempt failure while the browser stays online"(`realtime-reconnect-coordinator.test.ts:2230`), "reconnects after a composer session closes with OFFLINE while the browser stays online"(`:2278`), 둘 다 `AssertionError: expected 1 to be 3`. 기대와 같다. 변이 없는 대조: FE-GATE-005 realtime 14파일 272건 통과 | 4.05 |
| 04-R2 | `node scripts/run-vitest.ts run tests/unit/zz-review04/ --reporter=default` | `scratchpad/r5/requests/04-R2-reconnect-throw.patch`: 실험 파일 `tests/unit/zz-review04/zz-review04-1106.test.ts` 추가만(src 변경 없음) | 0 | 1건 통과. 출력 `{"attempts":3,"fetchCalls":0,"thrown":["TypeError: SSE endpoint must be fixed same-origin HTTPS." × 3],"sleepCalls":[50,100],"result":{"ok":false,"error":{"kind":"PROVIDER_UNAVAILABLE","operation":"CONNECT","retryable":true}},"observed":["ATTEMPT_STARTED","RETRY_SCHEDULED:PROVIDER_UNAVAILABLE","ATTEMPT_STARTED","RETRY_SCHEDULED:PROVIDER_UNAVAILABLE","ATTEMPT_STARTED","RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED"]}`. 기대와 같다 | 4.21 |
인용한 오케스트레이터 결과(직접 실행 아님, `desktop:/tmp/claude-gates/bbde570-ci/`, CI env): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(user namespace 전제, 영역 밖). FE-GATE-005 test:unit 208파일 3,056건(realtime 14파일 272건: bounded-poll-coordinator 24, realtime-reconnect-coordinator 46, bounded-polling-policy 11, realtime-stream-registry 30, websocket-connection 24, fetch-sse-connection 27, stream-coordinator 38, live-poll-handoff-coordinator 16, sse-parser 14, result 12, event-codec 8, websocket-protocol 8, event-consumer 7, realtime-reconnect-policy 7), `changelog-review-ids` 2건. FE-GATE-010 check:realtime-boundaries PASS, `:fixture` PASS, optional recipes realtime 40,826 / 42,200 gzip B. FE-GATE-020 realtime removal PASS. snapshot `realtime-boundaries.json` violations 0, `realtime-runtime-removal.xml` 7 checks 0 failures. `r5/snap/verify-documentation.local.txt`·`.no-sibling.txt` `PASS_SCOPED`.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
| --- | --- | --- | --- | --- |
| 04-01 | Low·P3 | 구조적 위험 | reconnect coordinator는 던지는 `attempt`·`waitClosed`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 `PROTOCOL_MISMATCH`로 끝내고, 규칙은 어디에도 적혀 있지 않다. repo bridge 모양에서 endpoint 설정 오류가 fetch 0회로 3번 재시도되고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다(04-R2) | `src/adapters/realtime/reconnect-coordinator.ts:766-774`, `:954-961`; `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:1764-1770` |
| 04-02 | Low·P3 | 개선 제안 | 권하는 `input.operation`은 `InstalledHttpContract<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표가 없고, 유일한 예는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다 | `src/application/policies/bounded-polling.ts:41-45`, `src/adapters/realtime/polling/bounded-poll-coordinator.ts:119`; `tests/unit/realtime/bounded-poll-coordinator.test.ts:1153-1165` |
@@ -0,0 +1,241 @@
# 영역 05 — 저장소·adapter kernel
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝. 노트북 worktree에서 읽기만 했다. 작업 트리에는 무시하기로 한 미추적 `AGENTS.md`만 있다) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`, `src/contracts/storage-keys.ts`. 판정에 필요해서 함께 읽은 것: `src/application/ports/browser-file-storage/opfs-ports.ts`·`shared.ts`, `recipes/frontend-capabilities/browser-file-storage-fakes.ts`(OPFS fake), `recipes/session-owners/oidc-pkce-session-owner.ts`, `config/contracts/registry-governance.json` FE-REG-STORAGE, `scripts/check-registries.ts`(orphan 검사), `scripts/test-optional-recipe-removal.ts`, `tests/unit/opfs-worker-runtime.test.ts`·`storage-registry.test.ts`·`second-api-feature-registries.test.ts`, `tests/recipes/oidc-pkce-session-owner.test.ts`·`browser-file-storage-contracts.test.ts`, `tests/browser-capabilities/opfs-runtime.spec.ts`, `docs/operations/browser-file-storage-recovery.md` §0·§7, `docs/architecture/client-cache-and-storage.md` 0절, `CHANGELOG.md` 미출시 절
> 깊게 본 관점: 11, 12, 10, 21, 17, 28
> 이번 렌즈: 1103/05-01 잔여와 1105/05-01 수정이 완료 기준을 채웠는가, 수정이 검사를 약하게 했는가(특히 `orphanExemptRows`), 수정이 새 결함을 만들었는가
> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 기본 구성에서 쓸 수 있다. **OPFS 개인 파일 저장은 지난 라운드 "사용 보류"에서 "조건부 사용 가능"으로 올린다.** 승인된 LOGOUT·ACCOUNT_DELETION이 객체를 끝까지 돌면 이제 늘 partition을 지운다. 그래서 다른 탭이 저장 중인 새 파일과 키를 잃은 멈춘 put의 bytes가 남지 않는다. 메모리 런타임 50/50, 실제 Chromium·Firefox 24/24에서 그 직후 파일 0·`NOT_FOUND`였다(05-R1·05-R2). 다른 탭의 reconcile과 partition 삭제가 겹쳐도 bytes가 남지 않았다(05-R1 Y3, 2/2). 조건: 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(상한 10분, 넘으면 retryable `BLOCKED`). WebKit에서는 기본 정책이 OPFS 런타임을 거절한다. 손상 chunk reference 행 하나가 reconcile을 멈추는 것(0929/05-01 ③)은 그대로다.
ID 표기: 이번 라운드 새 발견은 `05-NN`(밖에서는 `1106/05-NN`). 지난 라운드(2026-11-05)는 `1105/05-NN`, 그 전은 `1103/05-NN`, `1101/05-NN`, `0929/05-NN`이다. 배치 요청은 `05-R1`~`05-R4`다(요청 파일 `scratchpad/r5/requests/05.md`).
## 0. 결론
- **이 영역은 `8a44226..bbde570` 사이 수정 커밋 2개로 바뀌었다.** `23662fb`(1103/05-01 잔여)와 `dc7c95b`(1105/05-01)다. src 쪽 영역 diff는 4파일 +81/−59줄이다(`opfs-byte-store-adapter.ts`, `opfs-ports.ts`, `storage-keys.ts`, 영역 02의 `cache-storage-ports.ts`). kernel(`src/adapters/platform/`), `browser-file-storage/`, Web Storage 어댑터·codec, IndexedDB 런타임, OPFS journal·worker는 한 줄도 바뀌지 않았다(`git diff --stat` 출력 없음).
- **1103/05-01은 고쳐졌다(완료 기준 확인).** 객체를 끝까지 돈 purge는 chunk sweep을 하지 않고 늘 partition 삭제로 끝난다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 그 삭제는 exclusive partition lock을 쥐고 진행 중인 put을 기다린 뒤 디렉터리(staging 포함)와 행을 지운다(`:931-946`). 지난 라운드 실험 Y1a·Y1b·Y2가 저장소 테스트가 되었고 `bbde570`에서 통과한다(FE-GATE-005, `opfs-worker-runtime.test.ts` 89건). 완료 기준의 반복 조건도 확인했다:
- 05-R1(메모리): Y1b 객체 0·1·2·3·8개 각 10회 → **50/50** `partitionDeleted: true`, `chunkSweep: null`, 파일 0, `NOT_FOUND`. 다음 reconcile 뒤에도 50/50 파일 0·`NOT_FOUND`. Y1a도 같다.
- 05-R2(실제 Chromium·Firefox): 객체 0·1·3·8개 × 3회 × 2엔진 → **24/24** `partitionDeleted: true`, 파일 0, `NOT_FOUND`. 지난 라운드는 객체 3·8개에서 6/6 `OPENED`였다.
- 05-R3: 수정을 되돌리면 이 수정이 더하거나 바꾼 테스트 8건이 실패한다(객체 3·8개 Y1b, Y1a, Y2 포함). 새 테스트 중 되돌린 코드에서도 통과하는 것은 객체 1개 Y1b와 예산 호출 테스트뿐이다. 이 둘은 2026-11-03 수정으로도 통과하는 순서다.
- **reconcile과 partition 삭제의 겹침(2026-11-03부터 미검증)도 bytes를 남기지 않았다(05-R1 Y3).** reconcile은 partition lock을 쥐지 않는다(`opfs-byte-store-adapter.ts:637-690`). 그래서 다른 탭의 roll-forward 중간에 삭제가 끼었다. `commitPut` 전에 끼면 reconcile이 `failedTransactions: 1`로 끝났다. 뒤에 끼면 `committedTransactions: 1`로 끝났다. 두 경우 모두 파일 0, 객체 `NOT_FOUND`, journal 행 없음이었다. 뒤의 경우 reconcile report는 "commit 1"이라 적지만 그 객체는 이미 지워졌다. 그 순간에는 사실이라 결함으로 세지 않는다.
- **1105/05-01은 고쳐졌다.** recipe 키가 registry 행 `AUTH_REDIRECT_TRANSACTION`의 `physicalKey`다(`oidc-pkce-session-owner.ts:51-52`, `storage-keys.ts:146-157`). 그래서 `APP_NAMESPACE`를 바꾸면 이 키도 바뀐다(`storage-keys.ts:1`, `:205`). 다만 이 키를 다시 글자로 적는 회귀는 테스트가 잡지 못한다. 지금 namespace에서는 두 문자열이 같기 때문이다(`oidc-pkce-session-owner.test.ts:197-204`).
- **`orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`을 더한 것은 템플릿 게이트를 약하게 하지 않는다(05-R4로 확인).** orphan 검사는 `src`와 `tests`의 글자를 찾는다(`check-registries.ts:621-658`, `registry-governance.json:375`). `tests` 두 파일이 이 이름을 쓴다(`storage-registry.test.ts:208`, `oidc-pkce-session-owner.test.ts:200`). 예외를 빼고 돌려도 템플릿의 `check:registries`는 `11 registries PASS`였다. 예외가 실제로 바꾸는 것은 `src`만 복사해 검사하는 테스트 하나다(`second-api-feature-registries.test.ts:201-212`). 예외를 빼면 그 테스트만 `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer`로 실패했다. **다만 커밋이 적은 이유는 반만 맞다.** `QUERY_PERSISTENCE`(`disabled`)·`AUTH_TOKEN`(`forbidden`)은 "쓰는 곳이 없어야 하는" 선언 행이다. 이 행은 recipe가 실제로 쓰는 `external` 키다. 비교할 행은 `CACHE_INVALIDATION_PULSE`이고, 그 행은 src에 사용처가 있어 예외가 아니다. 버린 대안의 이유("레시피를 지운 사본에서 사용처가 사라진다")도 맞지 않는다. 그 사본에도 `tests/unit/storage-registry.test.ts`가 남는다(`test-optional-recipe-removal.ts:38-41`). 피해가 없어 새 발견으로 세지 않는다(2절, 4절 21번).
- **수정이 검사를 약하게 한 곳은 없다.** 테스트에서 지운 단언은 모두 더 강한 형태로 바뀌었다. 객체 1개 X1 → 1·3·8개(`opfs-worker-runtime.test.ts:2320`), `chunkSweep: "COMPLETED"` 기대 → `partitionDeleted: true` + `chunkSweep` 없음 + 파일 0(`:2256-2268`, `:2301-2308`, `:2679-2685`). 브라우저 X1은 0개 → 0·3개다(`opfs-runtime.spec.ts:337`). skip·timeout·임계값 변경은 없다.
- **새 발견은 1건이다. Low 1. High 이상과 P1은 없다.** 05-01: 저장소 설계 문서가 registry 행을 8개 중 4개만 "현재 등록되어 있다"고 적는다(`docs/architecture/client-cache-and-storage.md:50-52`).
- **kernel 경계는 그대로다.** `src/adapters` 안에서 바뀐 import는 `contracts` 두 줄뿐이다(영역 02·03 파일). `.dependency-cruiser.json`의 kernel 규칙은 바뀌지 않았다(바뀐 것은 `feature-and-app-roots-do-not-reach-adapters` 하나). FE-GATE-010의 `check:architecture`·`check:adapter-inventory`·boundaries(34건 거절) PASS.
- **README §16.6은 이 영역의 열린 이월 6건(0929/05-01·05-05·05-06·05-07·05-10, 1101/05-06)을 적지 않았다.** 이번 조치에서 손대지 않았고 코드도 그대로다(2절).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 05 |
| 커밋·작업 상태·확인 시점 | `bbde570`, 2026-11-06. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop(같은 커밋)에서 오케스트레이터 배치로만 했다(04:32~04:33, 항목마다 checkout 복원 clean) |
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행. SSR 없음 |
| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터와 kernel의 mutation intent factory·lifecycle runtime이다(지난 라운드와 같음, `runtime-adapters.ts`의 영역 관련 줄은 바뀌지 않음). IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED` 레시피다. OIDC PKCE session owner도 레시피다 |
| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다(13·14번 미검증). 데이터 요구: OPFS 정책 예시가 `PERSONAL`·`PURGE_PARTITION`이다. port 계약 "For these two reasons the partition's bytes are gone exactly when this is set"(`opfs-ports.ts:171-183`)을 이 영역의 필수 계약으로 본다. Web Storage 키는 registry가 만든다는 규칙(`docs/contracts/compatibility.md:31`)도 본다 |
| 읽은 코드·구성 범위 | `8a44226..bbde570`의 영역 diff 전부(`23662fb`, `dc7c95b`). `enforcePolicies` 전체(`opfs-byte-store-adapter.ts:730-966`), put 흐름의 lock 순서(`:177-240`, `:1109-1183`), reconcile의 lock과 FILES_READY 경로(`:637-690`, `:1250-1305`), worker `finalizePut`(`opfs-worker-runtime.ts:951-998`), journal `begin`의 세대 검사(`indexeddb-opfs-journal.ts:385-405`), 정책 검사(`shared.ts:222-296`), `check-registries.ts` orphan 검사(`:361-393`, `:621-658`), recipe 제거 드릴(`test-optional-recipe-removal.ts:29-90`), 지난 발견이 가리킨 위치 전부 |
| 주장으로만 읽은 것 | 커밋 본문 2개, README §16.3·§16.4·§16.5·§16.6, `CHANGELOG.md:30`, `:72-73`, runbook §0·§7, `docs/architecture/client-cache-and-storage.md`, 매뉴얼 `04-paired-backend-session.md:47` |
| 수행한 테스트·실험 | 노트북: 정적 읽기, `git diff`·`git grep`. 게이트 증거는 desktop에 이미 있는 것을 읽었다: `bbde570-ci/summary.txt`와 gate 로그 FE-GATE-005·007·008·010·012·020(모두 2026-11-06 03:24~03:56, CI env). 오케스트레이터 배치(local env): 05-R1 실험(메모리, Y1a·Y1b 50회·Y3 2경우), 05-R2 실험(Chromium·Firefox, 24회), 05-R3 변이(수정 되돌림), 05-R4 변이(orphan 예외 제거). 6.3절 |
| 확인하지 못한 범위·이유 | N-1 탭(`23662fb` 전 adapter) 공존, WebKit의 OPFS 런타임(기본 정책이 지원을 거절해 spec이 일찍 끝남, `opfs-runtime.spec.ts:352`), 0929/05-05·05-06·05-07·05-10·1101/05-06의 재현(파일이 바뀌지 않아 정적 확인만) |
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 영역 문서의 발견 14건(2절 13건 + 새 05-01)을 이 커밋의 코드와 이 커밋의 gate 로그로 다시 판정했다. 지난 라운드의 실행 결과(Y1·Y2, 05-R2, 변이 15개)와 조치 라운드의 RED 실행은 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
상태: **고쳐짐**(완료 기준을 코드와 실행으로 확인) / **일부**(남은 것을 적음) / **남음** / **재발** / **틀린 발견**. 심각도는 지난 판정이다. 완료 기준은 2026-11-05 영역 문서 2.1절·3절이다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/05-01 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 (Low·P3) | 고쳐짐 | 완료 기준 세 조건: ① recipe 키가 registry 행에서 온다. `OIDC_PKCE_TRANSACTION_KEY = STORAGE_REGISTRY.AUTH_REDIRECT_TRANSACTION.physicalKey`(`oidc-pkce-session-owner.ts:51-52`). 쓰기·읽기·지우기가 모두 이 상수다(`:191`, `:474`, `:551`, `:571`). ② registry에 `external` 행이 있다(`storage-keys.ts:146-157`). `defineStorageKey`가 `buildPhysicalKey`로 키를 만든다(`:191-197`). StoragePort는 거절한다(`:218-220`, 테스트 `storage-registry.test.ts:203-239`). ③ `APP_NAMESPACE`를 바꾸면 같이 바뀐다(`storage-keys.ts:1`, `:205`, 코드 읽기). 테스트 `oidc-pkce-session-owner.test.ts:197-204`가 저장된 키 = registry 키를 본다. FE-GATE-007(32건)·FE-GATE-005 통과. 매뉴얼 복사 규칙(`../../src/` → `../`)이 새 import에도 맞는다(`04-paired-backend-session.md:47`). CHANGELOG [계약] 행이 있다(`CHANGELOG.md:72`). **남는 약점(결함으로 세지 않음)**: recipe를 다시 `"ca-frontend:auth:v1:oidc-pkce-transaction"`로 되돌려도 이 테스트는 통과한다. 지금 namespace에서 두 문자열이 같다. 지난 라운드 문서의 검증 방법이 이 약점을 가졌다. `orphanExemptRows` 판정은 아래 2.1절 |
| 1103/05-01 | 승인된 LOGOUT·ACCOUNT_DELETION이 journal 행을 한 순간만 세서, 세기 전에 끝난 새 객체 put(①)과 키를 잃은 행(②)의 bytes를 남긴 채 `COMPLETED`를 보고한다 (Medium·P2, OPFS 개인 파일 제품 P1) | **고쳐짐** (완료 기준을 코드·게이트·05-R1·05-R2로 확인, 통제는 05-R3으로 M3) | **코드**: `walkFinished = !moreObjectsAvailable && !deadlineReached`(`opfs-byte-store-adapter.ts:900`). 끝까지 돈 purge는 journal을 세지 않고(`:908`) 바로 partition 삭제로 간다(`:926-929`). chunk sweep 경로는 지워졌다(`git show 23662fb`). 삭제는 exclusive partition lock 안에서 디렉터리와 행을 지운다(`:931-946`). put·delete는 `begin`부터 끝까지 같은 lock을 shared로 쥔다(`:1127`). 그래서 ①의 put은 삭제 전에 끝나고 삭제가 그 결과를 지운다. ②의 staging은 partition 디렉터리 안에 있어 함께 지워진다. 끝까지 못 돈 호출(예산·CONFLICT)은 전과 같이 세고, 행이 있으면 바로 삭제하고, 없으면 `moreObjectsAvailable: true`다(`:908-916`, `:950-955`). port 문장이 코드와 맞다(`opfs-ports.ts:171-183`). `chunkSweep`은 `@deprecated`이고 아무도 채우지 않는다(`:154-165`, `git grep chunkSweep`에 src 생산 코드 0). fake도 늘 `partitionDeleted`다(`browser-file-storage-fakes.ts:1927-1942`). runbook이 새 동작을 적는다(`browser-file-storage-recovery.md:454-473`, `:510-518`). CHANGELOG [계약] 행(`CHANGELOG.md:73`).<br>**실행(`bbde570`, 게이트)**: 완료 기준의 시나리오가 저장소 테스트가 되었다. Y1b 객체 1·3·8개(`opfs-worker-runtime.test.ts:2320-2357`, 파일 0 `:2354`, `NOT_FOUND` `:2355`), Y1a(`:2362-2409`), Y2(`:2559-2626`, purge 두 번과 reconcile 사이마다 파일 0), 예산에 걸린 호출(`:2414-2474`). FE-GATE-005에서 89건 모두 통과(`FE-GATE-005.txt:80`, `:436`). 브라우저 X1이 객체 0·3개로 늘었다(`opfs-runtime.spec.ts:337-447`). FE-GATE-008에서 Chromium·Firefox 통과(`FE-GATE-008.txt:261`, `:265`, `:284`, `:292`). WebKit은 지원 판정에서 `return`한다(`:352`).<br>**완료 기준과의 차이**: 기준은 "Y1b 각 10회, 05-R2 Chromium 객체 0·1·3·8개"와 "그 직후와 다음 reconcile 뒤 파일 0·`NOT_FOUND`"(1103 기준)다. 저장소 테스트는 Y1b를 1회씩, reconcile 없이 돈다. 브라우저 spec은 객체 1·8개가 없고 파일 수를 보지 않는다. 새 코드에서는 끝까지 돈 purge의 결과가 put이 언제 끝났는지에 따라 갈리지 않는다(늘 삭제). 그래서 반복의 의미는 작다. 그래도 기준대로 배치로 돌렸다.<br>**배치(6.3절)**: 05-R1 Y1b 객체 0·1·2·3·8개 각 10회 → 50/50 `{partitionDeleted: true, chunkSweep: null, more: false, late: "NOT_FOUND", files: 0}`, reconcile 뒤에도 50/50 `NOT_FOUND`·0. Y1a → report `{inspectedObjects: 1, removedObjects: 1, moreObjectsAvailable: false, partitionDeleted: true}`, 파일 `[]`, reconcile 뒤에도 `[]`·`NOT_FOUND`. 05-R2 Chromium·Firefox 객체 0·1·3·8개 × 3회 → 24/24 `partitionDeleted: true`, `files: 0`, `opened: "NOT_FOUND"`(지난 라운드 객체 3·8개 6/6 `OPENED`). 05-R3 수정을 되돌리면 `opfs-worker-runtime.test.ts` 8건 실패, 모두 report에 `partitionDeleted: true`가 없다는 이유다.<br>**README §16.5 "고침"과 같은 판정이다** |
| 0929/05-01 | journal·staging 손상 한 건이 계정 삭제 purge와 reconcile·GC를 멈춘다 (Medium·P2) | **일부** (README §16.6에 없음) | ①·②는 지난 라운드와 같다. **③은 그대로다**: 손상 chunk reference 행은 `isChunkReferenced`가 `CORRUPT_DATA`로 실패한다(`indexeddb-opfs-journal.ts:855-862`). GC가 그 실패를 그대로 돌려준다(`opfs-byte-store-adapter.ts:1396-1401`). reconcile은 앞에서 처리한 결과를 버리고 실패한다(`:702`). 바뀐 것: purge는 이제 sweep을 하지 않으므로 ③이 purge를 건드리지 않는다. 지난 라운드에도 purge 쪽은 partition 삭제로 빠져나갔다 |
| 1101/05-06 | Web Storage 어댑터·codec 분기 5개를 테스트가 잡지 못한다 (Low·P3) | **일부** (README §16.6에 없음) | W2(TTL 모양 검사, `browser-storage-adapter.ts:123`), W5(`__proto__` 등 키 거절, `browser-storage-codec.ts:204`), W6(accessor 거절, `:205-206`)를 보는 테스트가 여전히 없다. codec을 직접 부르는 테스트 0개(`git grep browser-storage-codec -- tests` 출력 없음). 두 파일과 Web Storage 테스트는 `8a44226` 뒤 바뀌지 않았다. `storage-registry.test.ts`에 더해진 테스트는 1105/05-01의 것이다. 정적 판단(E1). 지난 라운드 변이 결과는 다시 쓰지 않았다 |
| 0929/05-05 | IndexedDB 전체 삭제 경로가 롤백 중 계정 삭제에 쓰이지 않는다 (Low·P3) | 남음 (README §16.6에 없음) | 전체 삭제 조건이 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`). N-1 탭은 `VersionError`를 `INCOMPATIBLE`로 바꾼다(`:663-672`). 파일 변경 없음 |
| 0929/05-06 | 두 런타임이 삭제 승인 계약을 다르게 요구 (Low·P3) | 남음 (README §16.6에 없음) | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1930`) |
| 0929/05-07 | canonical JSON 3벌, `sameScope` 2벌 (Low·P3) | 남음 (README §16.6에 없음) | `stableJson` `opfs-prepared-object.ts:138`, `public-cache-codec.ts:637`, `canonicalJson` `realtime/event-codec.ts:414`. `sameScope` `indexeddb-opfs-journal.ts:1428`, `opfs-worker-runtime.ts:1690`. `hasPartitionKey`(`indexeddb-opfs-journal.ts:980`)도 그대로 |
| 0929/05-10 | OPFS journal DB 접두사를 바꿀 수 없다 (Low·P3) | 남음 (README §16.6에 없음) | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` |
| 1103/05-02 | partition lock 기다림이 abort를 무시하고 상한이 없다 (Low·P3) | 고쳐짐 유지 | put·remove가 signal을 넘긴다(`opfs-byte-store-adapter.ts:225`, `:500`). `withPartitionLock`의 abort·상한(`:1148-1183`) 그대로. 테스트 `opfs-worker-runtime.test.ts:3101`, `:3149` 통과(FE-GATE-005) |
| 1103/05-03 | 키 없는 손상 행이 `DEGRADED`를 영원히 남긴다 (Low·P3) | 고쳐짐 유지 | `DEGRADED`는 지울 수 있는 손상 행이 있을 때만(`opfs-byte-store-adapter.ts:715-717`). runbook이 새 동작에 맞게 고쳐졌다: 그 행의 staging은 이제 partition 삭제가 지운다(`browser-file-storage-recovery.md:45-55`). 테스트 `opfs-worker-runtime.test.ts:2823` 통과 |
| 1103/05-04 | recipe fake의 reconcile이 런타임과 다르다 (Low·P2) | 고쳐짐 유지 | parity 테스트가 그대로이고 purge 기대값도 런타임과 같다(`browser-file-storage-contracts.test.ts:941-958`). FE-GATE-007 13건 통과 |
| 1101/05-04 | kernel 폴더의 bootstrap 전용 파일 2개가 폴더 예외를 받는다 (Low·P3) | 고쳐짐 유지 | `layers.md`의 kernel 절은 바뀌지 않았다(바뀐 줄은 다른 규칙 행 하나, `git diff`). 남는 위험은 4절 22번 |
| 0929/05-08 | kernel 범위 설명이 실제보다 좁다 (Low·P3) | 고쳐짐 유지 | `ls src/adapters/platform` 10개 파일 그대로, 문서 그대로 |
| 0929/05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 (Low·P3) | 고쳐짐 유지 | `opfs-policy.ts:112` 그대로(파일 변경 없음) |
README §16.6에 없는 6건(0929/05-01·05-05·05-06·05-07·05-10, 1101/05-06)은 지난 영역 문서 2절에서 "일부"·"남음"이었다. §16.6은 "영역 문서 2절 '남음'"을 모은다고 적지만 이 영역 것은 빠졌다. 상태 판정이 갈린 것은 아니다. 조치 대상 목록에서 빠진 것이다.
### 2.1 `orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`을 더한 것 (`dc7c95b`, README §16.3)
| 질문 | 판정 | 근거 |
|---|---|---|
| 검사를 약하게 했나 | **템플릿 게이트 결과는 바꾸지 않는다(05-R4로 확인).** 새 발견으로 세지 않는다 | orphan 검사는 행의 `logicalName`이 `consumerDirectories`(`src`, `tests`) 파일 글자 안에 있는지만 본다(`check-registries.ts:621-658`, `registry-governance.json:375`). 주석과 테스트도 사용처로 센다. 이 이름은 `tests/unit/storage-registry.test.ts:208`, `:224-237`과 `tests/recipes/oidc-pkce-session-owner.test.ts:200-203`에 있다. 05-R4: 예외를 빼도 `check:registries`는 `Registry governance: 11 registries PASS; compatibility=additive`, rc=0이었다. 예외가 실제로 바꾸는 실행은 `src`만 복사하는 `second-api-feature-registries.test.ts`다(`:201-212`가 `src`, `config/contracts`, `schemas/artifacts`, 스크립트 하나만 복사). 예외를 빼면 그 테스트 1건만 stderr `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer for logicalName=AUTH_REDIRECT_TRANSACTION`로 실패했다(`:246`). 같은 파일의 다른 1건은 통과했다. 이 행은 `dc7c95b` 전에는 없었으므로, 전에 검사받던 행이 검사를 잃은 것도 아니다 |
| 예외 이유가 맞나 | **반만 맞다** | 커밋 본문: "`AUTH_TOKEN`처럼 사용처 없이 선언만 하는 행이다". 그러나 기존 예외 둘은 `sensitive-forbidden` 행이다. `QUERY_PERSISTENCE`는 `backend: "disabled"`(`storage-keys.ts:95-106`), `AUTH_TOKEN`은 `backend: "forbidden"`(`:124-135`)이다. "이 저장은 하지 않는다"는 선언이라 쓰는 곳이 없는 것이 맞는 상태다. `AUTH_REDIRECT_TRANSACTION`은 `external`·`opaque-cache` 행이고 recipe가 실제로 쓴다(`oidc-pkce-session-owner.ts:551`). 같은 모양의 행은 `CACHE_INVALIDATION_PULSE`(`:112-123`)이고, 그 행은 src 사용처(`browser-cross-context-host.ts:37`)가 있어 예외가 아니다. 즉 이 예외는 "쓰는 곳이 검사 폴더 밖(`recipes/`)에 있다"는 새 종류다. 버린 대안(consumer 폴더에 `recipes` 추가)의 이유 "레시피를 지운 사본(FE-GATE-020)에서 다시 사용처가 사라진다"도 맞지 않는다. 그 드릴은 `recipes`와 `tests/recipes`만 지운다(`test-optional-recipe-removal.ts:38-41`). `tests/unit/storage-registry.test.ts`가 남아 이름을 계속 쓴다. 막힌 것은 `src`만 복사하는 테스트 하나다. CHANGELOG의 이유("사용처가 지울 수 있는 레시피뿐이라", `CHANGELOG.md:72`)는 사실이다 |
| 남는 위험 | 작다 | 예외는 이유 칸 없이 영구다(JSON에 이유를 둘 자리가 없다). 레시피와 그 registry 테스트 줄까지 지운 다운스트림에서는 쓰이지 않는 행이 신호 없이 남는다. StoragePort가 이 키를 거절하고 아무도 쓰지 않으므로 데이터 피해는 없다. orphan 검사의 약한 곳은 이 예외가 아니라 검사 방식(글자 찾기, 테스트·주석 포함)이다. 이것은 registry 검사 전체의 성질이라 영역 07·12에서 본다(4절 21번) |
## 3. 이번 발견 (36.3)
새 발견 1건: Low 1 · P3 1 · 확인된 결함 1. Critical·High·Medium 0, P0·P1·P2 0. 구조적 위험·미검증·개선 제안은 새로 세지 않았다(미검증은 5절). 05-R1 Y3(reconcile과 partition 삭제의 겹침)은 bytes를 남기지 않아 새 발견이 아니다.
| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 |
|---|---|---|---|---|---|
| 05-01 | Low | P3 | 확인된 결함 | 9, 4, 15, 23, 5 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 |
### 05-01 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서와 코드 불일치, 정적 확인). 영역 14(문서)와 겹칠 수 있다. 같은 결함이면 하나로 합친다 |
| 관련 관점 | 9, 4, 15, 23, 5 |
| 근거 | ① 문서: "현재 `src/contracts/storage-keys.ts`에는 `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`, 금지된 `AUTH_TOKEN`과 비활성 `QUERY_PERSISTENCE`가 등록되어 있다"(`docs/architecture/client-cache-and-storage.md:50-52`). 기본 조립 표도 Web Storage를 그 둘만 적는다(`:1406-1407`). 결정 기록 VD-13도 "`COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`만"이라 적는다(`docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md:66`).<br>② 코드: registry는 8행이다. `COLOR_SCHEME`, `LOCALE`, `CHUNK_RELOAD_GUARD`, `RELEASE_MISMATCH_RECOVERY`, `QUERY_PERSISTENCE`, `CACHE_INVALIDATION_PULSE`, `AUTH_TOKEN`, `AUTH_REDIRECT_TRANSACTION`(`storage-keys.ts:41-157`). `LOCALE`·`RELEASE_MISMATCH_RECOVERY`는 기본 조립에서 쓰인다(`create-application.ts:54-60`, `boot-release-recovery.ts:16`).<br>③ 이 문서는 그 뒤로도 고쳐졌다. `e98a980d`(1101/05-01 pulse 키)가 같은 문서의 `:82-85`만 고쳤다. `dc7c95b`(1105/05-01)는 행을 더했지만 이 문서를 고치지 않았다. 문서 머리의 기준일은 2026-07-28이다(`:12`). 그러나 "현재"라는 문장과 이후의 부분 수정이 섞여, 읽는 사람은 지금 목록으로 읽는다.<br>④ `verify:documentation`은 이 문장을 보지 않는다(줄 번호 참조가 아님) |
| 발생 조건 | 다운스트림이 이 문서로 앱의 Web Storage 키 목록을 정할 때. 예: 개인정보 점검, 로그아웃 때 지울 키 목록, 새 키 이름 충돌 확인 |
| 영향 | 목록이 절반이다. 기본 조립에서 쓰는 `LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 키 둘(`pulse`, PKCE transaction)이 빠진다. 1105/05-01이 "registry가 앱의 Web Storage 키 목록"이 되게 고쳤는데, 그 목록을 설명하는 문서는 따라오지 않았다. 코드 동작에는 영향이 없다 |
| 심각도·우선순위 | Low · P3. 문서 불일치다. 정본은 `storage-keys.ts`이고 계약 표가 그쪽을 가리킨다(`docs/contracts/compatibility.md:31`) |
| 통제·증거 | "문서의 registry 목록이 코드와 같다" 규칙: **M0 확인**(이 문장을 보는 검사 없음) · E1 |
| 확실성과 남은 가정 | 문장과 코드는 파일로 확인했다. 다운스트림이 이 문서를 목록으로 쓰는지는 모른다 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 단순 수정이다 |
| 이해 비용 | 문서를 읽는 사람은 Web Storage 키가 넷이라고 믿는다. 실제 목록을 알려면 `storage-keys.ts`를 열어야 한다 |
| 최소 개선 방향 | `:50-52`의 목록을 지우고 "등록된 키는 `src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`가 정본이다"로 바꾼다. 목록을 문서에 두지 않으면 다시 갈라지지 않는다. `:1406-1407` 표와 VD-13 `:66`에는 기준일을 붙이거나 같은 문장으로 바꾼다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 세 곳 몇 줄 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 저장소 설계 문서와 VD-13에 registry 행을 나열한 "현재" 문장이 없거나, 있으면 8행 모두를 적는다 |
| 검증 방법 | `git grep -n 'COLOR_SCHEME' -- docs/architecture`로 남은 목록 문장을 찾는다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 적용 제외 — 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005 89건, 05-R1·05-R3) | P — purge 완료 판단이 "끝까지 돌았으면 삭제"로 단순해졌다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 손상 chunk reference 행이 reconcile을 멈춘다(0929/05-01 ③) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-010) | O — kernel 규칙 그대로. `src/adapters` 안 새 import는 `contracts`뿐. `check:architecture`·`check:adapter-inventory`·boundaries 34건 거절 PASS |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1, E2(FE-GATE-012) | P — `chunkSweep`을 지우지 않고 `@deprecated`로 남겨 읽는 코드가 깨지지 않는다(`opfs-ports.ts:154-165`). offline-indexeddb 레시피 37,644 / 38,500 gzip B(지난 37,714, −70 B) |
| 4 | 인지 부하 | 적용 | — | E1 | P — sweep 경로가 빠져 purge가 짧아졌다(−21줄). 판단 플래그는 여섯 개다(`walkFinished` 추가, `chunkSweep` 제거). 큰 파일 넷(1,880~2,641줄) 그대로. 설계 문서의 registry 목록이 절반이다(05-01) |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P — port·runbook이 새 동작과 한계(모든 승인 purge가 다른 탭 put을 기다림)를 적는다(`browser-file-storage-recovery.md:510-518`). README §16.6이 이 영역의 열린 이월 6건을 빠뜨렸다 |
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — lock 기다림 취소·상한 유지(1103/05-02). 손상 chunk reference 행(0929/05-01 ③) |
| 7 | 운영 성숙도 | 적용 | M1 / M1 | E1 | P — 키 없는 행의 bytes는 이제 partition 삭제가 지운다. 행 자체는 count로만 남는다(05-03 설계). 선택형 런타임은 조합이 없어 경보 경로가 없다 |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | O — purge report가 `partitionDeleted`와 `moreObjectsAvailable` 중 정확히 하나를 갖는다(`:950-955`). `removedObjects`가 삭제 전에 지운 객체만 센다는 것을 runbook이 적는다(`:492`) |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — canonical JSON 3벌·`sameScope` 2벌(0929/05-07), 설계 문서 목록(05-01) |
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005·007·008, 05-R3·05-R4) | P — 지난 실험 Y1a·Y1b·Y2와 예산 호출이 저장소 테스트가 됐다. 브라우저 X1이 객체 0·3개. 수정을 되돌리면 8건이 실패한다(05-R3). 실패는 모두 report 단언에서 난다. 파일 0 단언은 그 뒤에 있어 이번 변이로는 따로 확인되지 않았다. Web Storage W2·W5·W6 테스트 없음(1101/05-06). recipe 키 테스트는 글자 회귀를 못 잡는다(1105/05-01 덧붙임). WebKit OPFS spec은 지원 판정에서 `return`해 통과로 센다(`opfs-runtime.spec.ts:352`) |
| **11** | 데이터 성숙도 | 적용 | M3 / M3 | E2(05-R1 50/50), E3(05-R2 Chromium·Firefox 24/24, FE-GATE-008) | P — **"승인된 계정 삭제가 완료를 보고하면 partition bytes 0" 규칙을 이제 지킨다**(1103/05-01). 다른 탭의 reconcile과 겹쳐도 지킨다(05-R1 Y3 2/2). IndexedDB 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05) |
| **12** | 동시성 성숙도 | 적용 | M3 / M3 | E2(05-R1), E3(05-R2) | P — 끝까지 돈 purge가 exclusive partition lock으로 진행 중 put을 기다린 뒤 지운다(Y1b 50/50, 브라우저 24/24). reconcile은 partition lock을 쥐지 않는다(`:637-690`). 그래서 삭제와 겹친다. 그래도 bytes는 남지 않았다(Y3 `commitPut` 전·후 2/2. 지워진 행에 `commitPut`이 실패하고, `finalizePut`은 없는 디렉터리를 만들지 않는다 `opfs-worker-runtime.ts:965-995`). 저장소 테스트에 Y3 순서는 없다. N-1 탭 공존 미검증 |
| 13 | 확장성 | 적용 | — | E1 | ? — 규모 목표가 없다. partition 삭제는 예산이 없고, 이제 모든 완료 purge가 거친다 |
| 14 | 성능 성숙도 | 적용 | — | E2(FE-GATE-012) | ? — 목표가 없다. 승인 purge가 다른 탭의 진행 중 put을 최대 `mutationLockWaitTimeoutMs`(기본 10분)까지 기다린다(runbook `:517-518`) |
| 15 | 보안 성숙도 | 적용 | M2 / M2 | E2, E3 | P — 기본 구성은 Web Storage에 개인 데이터를 두지 않는다. PKCE transaction 키는 registry 행이 되었고 StoragePort가 거절한다. OPFS 계정 삭제 뒤 개인 파일이 남던 경로가 닫혔다. 승인 정규식 두 벌(0929/05-06) |
| 16 | 의존성 성숙도 | 적용 제외 | — | — | - — 외부 패키지 없이 브라우저 API만 쓴다 |
| **17** | API / Contract 성숙도 | 적용 | M2 / M2 | E2 | P — port 문장이 코드와 맞다(`opfs-ports.ts:171-183`). CHANGELOG [계약] 두 행(`:72-73`). 관찰(결함으로 세지 않음): recipe fake의 purge는 `budgetMs`·`maxObjects`를 흉내 내지 않고 늘 한 번에 끝난다(`browser-file-storage-fakes.ts:1906-1942`). fake로 테스트하는 다운스트림은 "`moreObjectsAvailable`이면 다시 부른다" 경로를 보지 못한다. 0929/05-06 |
| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P — `23662fb` 전 release 탭은 여전히 sweep으로 끝난다. 롤아웃 중 그 탭이 purge하면 이번에 닫은 틈이 그 탭에서 열린다(미검증). IndexedDB N-1 계정 삭제 실패(0929/05-05) |
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E1 | P — timeout 관계 검사 유지(0929/05-09). 접두사 고정(0929/05-10) |
| 20 | 개발자 경험 | 다른 영역 | — | — | > — 영역 14 |
| **21** | Guardrail 성숙도 | 적용 | M3 / M2 | E2(FE-GATE-010·012·020, 05-R4) | P — 수정이 검사를 약하게 한 곳은 없다(0절). `orphanExemptRows` 추가는 템플릿 게이트 결과를 바꾸지 않는다(2.1절, 05-R4: 예외를 빼도 `check:registries` PASS). registry orphan 검사는 글자 찾기라 테스트·주석도 사용처로 센다(`check-registries.ts:621-658`, `AUTH_TOKEN`은 src 주석 `product-composition-contract.ts:54`에서 걸림) — registry 검사 전체의 성질이라 영역 07·12 몫. recipe 키가 registry에서 오는지 보는 검사는 테스트 하나이고 글자 회귀를 못 잡는다 |
| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E1, E2 | P — kernel 문서가 실제와 맞다. 남은 위험: 폴더 예외라 adapter가 bootstrap 전용 kernel 파일 둘을 import해도 규칙이 막지 않는다(1101/05-04 잔여). 중복 helper(0929/05-07) |
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 승인 정규식 두 벌(0929/05-06). `orphanExemptRows`에 성격이 다른 행이 섞였다(2.1절). 문서 목록(05-01) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2 | O — 완료 신호가 `partitionDeleted` 하나가 되었다. `chunkSweep`은 늘 비어 있는 호환용 칸이라고 port가 적는다(`opfs-ports.ts:154-165`) |
| 25 | 조직 확장성 | 적용 | — | E0 | ? — 팀이 하나다 |
| 26 | Ownership 성숙도 | 적용 | — | E0 | ? — 선택형 런타임 조합이 없어 runbook 담당을 확인할 대상이 없다 |
| **27** | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020) | P — 레시피 제거·browser-file-storage 제거 드릴 PASS(`FE-GATE-020.txt:10400`, `:11291`). 기기 데이터 삭제는 OPFS 정상 경로의 틈이 닫혔다(05-R1·R2). 키 없는 journal 행은 남는다(05-03 설계, bytes 없음) |
| **28** | 회복 가능성 | 적용 | M2 / M2 | E2 | P — 키가 읽히는 손상 행과 키 없는 행의 bytes를 승인 purge가 partition째 지운다(Y2 테스트 `:2559`). 손상 chunk reference가 reconcile을 막는다(0929/05-01 ③) |
적용 항목 26개(16 제외, 20은 영역 14): 충족 3(2, 8, 24), 부분 충족 19, 미충족 0, 미검증 4(13, 14, 25, 26). 지난 라운드의 11번 미충족 세부 규칙("계정 삭제 뒤 bytes 0")은 충족으로 바꿨다(05-R1·05-R2).
## 5. 미검증
| 항목 | 이유 | 확인에 필요한 것 |
|---|---|---|
| reconcile과 partition 삭제의 겹침, `commitPut` 앞·뒤 말고 다른 지점 | 05-R1 Y3는 `commitPut` 앞·뒤 두 지점만 멈췄다. `verifyObject`·`finalizePut` 도중(worker origin lease 안)은 돌리지 않았다. 저장소 테스트에도 이 순서가 없다 | Y3 블록을 `tests/unit/opfs-worker-runtime.test.ts`로 옮기고 worker 단계 hook을 더함 |
| 05-R2의 파일 수 0의 뜻 | 세는 함수는 partition 디렉터리가 없으면 0을 돌려준다. 파일이 있을 때 세는지 대조 실행이 없다. report `partitionDeleted`와 `NOT_FOUND`가 같은 결론이다 | 삭제 전에 한 번 세는 대조 |
| N-1 탭(`23662fb` 전 adapter)과의 공존 | 실행하지 않음. 옛 탭은 sweep으로 끝나 이번 틈이 그 탭에서 남는다 | 이전 커밋 adapter와 현재 adapter를 같은 메모리 루트로 묶은 테스트 |
| WebKit의 OPFS 런타임 동작 | 기본 정책에서 지원 판정이 거절해 spec이 일찍 끝난다(`opfs-runtime.spec.ts:352`) | 정책을 바꾼 WebKit 실행 또는 지원 범위 문서화 |
| 0929/05-05·05-06·05-07·05-10, 1101/05-06 | 파일이 바뀌지 않아 정적 확인만 함 | 지난 라운드 재현·변이를 테스트로 옮김 |
## 6. 실행 기록
### 6.1 노트북 정적 확인
| 명령 | 결과 |
|---|---|
| `git diff --stat 8a44226..bbde570 -- src/adapters/storage src/adapters/platform src/adapters/browser-file-storage src/contracts/storage-keys.ts src/application/ports/browser-file-storage` | 4파일 +81/−59. `opfs-byte-store-adapter.ts`(73줄), `opfs-ports.ts`(31), `storage-keys.ts`(22), `cache-storage-ports.ts`(14, 영역 02) |
| `git diff 8a44226..bbde570 -- src/adapters \| grep import` | 바뀐 import는 `contracts/external-contract-runtime.ts`, `contracts/diagnostics.ts` 두 곳(영역 02·03 파일). adapter 간 import 변화 0 |
| `git diff 8a44226..bbde570 -- .dependency-cruiser.json` | `feature-and-app-roots-do-not-reach-adapters` 하나만 바뀜. kernel 규칙 그대로 |
| `git diff 8a44226..bbde570 -- <영역 테스트 7파일> \| grep '^-'` | 지운 단언은 모두 더 강한 형태로 다시 있음(0절). skip·timeout 변경 0 |
| `git grep chunkSweep` | src 생산 코드에서 값을 채우는 곳 0. port 타입(`opfs-ports.ts:165`)과 테스트의 "없음" 단언만 |
| `git grep -n 'AUTH_REDIRECT_TRANSACTION' -- src tests` | src에는 registry 정의뿐. tests 두 파일에 있음(2.1절) |
### 6.2 desktop 게이트 로그(같은 커밋, CI env, 인용)
| 출처 | 결과 |
|---|---|
| `bbde570-ci/summary.txt` | FE-GATE-001~012, 020 rc=0. FE-GATE-013 rc=1(user namespace 없음, 이 영역과 무관) |
| `gate-artifacts/FE-GATE-005.txt` | unit 208파일 3,056건 통과(`:312-313`). 이 영역: `opfs-worker-runtime` 89(`:80`), `indexeddb-opfs-journal` 18, `opfs-byte-store` 24, `storage-registry` 27, `browser-storage-policy` 8, `indexeddb-runtime` 31, `second-api-feature-registries` 2 모두 ✓ |
| `gate-artifacts/FE-GATE-007.txt` | `oidc-pkce-session-owner` 32(`:99`), `browser-file-storage-contracts` 13(`:101`) ✓ |
| `gate-artifacts/FE-GATE-008.txt` | capability 69건 통과(`:315`). `opfs-runtime.spec.ts` 05-01 객체 0·3개가 Chromium(`:261`, `:265`)·Firefox(`:284`, `:292`)·WebKit(`:304`, `:310`, 지원 판정에서 `return`) 통과. `Browser capability evidence: PASS (23 cases x 3 engines, zero skipped)`(`:322`) |
| `gate-artifacts/FE-GATE-010.txt` | `check:architecture` PASS(`:2-6`), boundaries 34건 거절 PASS(`:76`), `check:registries` `11 registries PASS; compatibility=additive`(`:106`), `check:adapter-inventory` PASS(`:153`) |
| `gate-artifacts/FE-GATE-012.txt` | `offline-indexeddb:37644/38500` PASS(`:88`) |
| `gate-artifacts/FE-GATE-020.txt` | optional recipe removal PASS(`:10400`), browser file/storage runtime removal PASS(`:11291`) |
### 6.3 desktop 배치 (오케스트레이터, `bbde570`, local env)
요청 파일: `scratchpad/r5/requests/05.md`. 패치는 같은 폴더의 `05-R1.patch`~`05-R4.patch`다. 로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-05-R1.log`~`R5-05-R4.log`. 항목마다 checkout을 복원했다(`restore=clean`). 대조 실행은 요청하지 않았다. 변이 없는 같은 파일이 `bbde570`에서 통과한 기록이 6.2절에 있다.
| ID | 명령 | 변이 | rc | 결과 | 시간·부하 |
|---|---|---|---|---|---|
| 05-R1 | `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts` | 테스트 끝에 실험 블록(Y1a + reconcile, Y1b 객체 0·1·2·3·8개 각 10회 + reconcile, Y3 reconcile을 `commitPut` 앞·뒤에 멈춤) | 0 | 97/97 통과(원래 89 + 실험 8). `R5OUT` 8줄. Y1a·Y1b 51회 모두 `partitionDeleted: true`, 파일 0, `NOT_FOUND`, reconcile 뒤에도 같음. Y3 두 경우 모두 purge `partitionDeleted: true`, reconcile 재개 뒤 파일 0·`NOT_FOUND`·행 없음 | 3.25초, 부하 4.21 |
| 05-R2 | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium --project=firefox -g "R5-05" --reporter=list` | spec 끝에 브라우저 Y1(객체 0·1·3·8개 × 3회, 파일 수 포함) | 0 | 2/2 통과(Chromium 6.6초, Firefox 20.8초). `R5OUT browserY1-run` 24줄 모두 `put: true`, `partitionDeleted: true`, `moreObjectsAvailable: false`, `files: 0`, `opened: "NOT_FOUND"`(객체 수마다 6줄) | 23.1초, 부하 3.95 |
| 05-R3 | `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts tests/recipes/browser-file-storage-contracts.test.ts` | adapter를 `8a44226` 내용으로 되돌림 | 1 | **검출.** `opfs-worker-runtime` 89건 중 8건 실패, recipe contracts 13건 통과(94/102). 실패: "removes the chunks of a LOGOUT-/ACCOUNT_DELETION-purged partition…" 2, "finishes a purge that walked more than one journal page", "waits for a put…(3 committed objects)"·"(8 committed objects)", "takes a new object another tab's put settles…", "leaves no bytes of a stopped put whose journal row lost its partition key", "reports a purge that skipped a changing object as unfinished". 이유는 모두 report에 `partitionDeleted: true`가 없음(`:2258`, `:2299`, `:2345`, `:2398`, `:2610`, `:2677`). "(1 committed objects)"와 "continues a purge the object budget stopped…"는 통과(기대대로) | 부하 3.57 |
| 05-R4 | `corepack pnpm check:registries; echo REGISTRIES_RC=$?; node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts; echo SECOND_API_RC=$?` | `orphanExemptRows`에서 `AUTH_REDIRECT_TRANSACTION` 제거 | 0(echo로 끝남) | `Registry governance: 11 registries PASS; compatibility=additive`, `REGISTRIES_RC=0`. `second-api-feature-registries` 2건 중 1건 실패: "passes check-registries without edits outside the feature and its context"가 stderr `FE-REG-STORAGE.AUTH_REDIRECT_TRANSACTION has no executable consumer for logicalName=AUTH_REDIRECT_TRANSACTION`(`:246`). `SECOND_API_RC=1` | 1.28초, 부하 3.57 |
**05-R1 `R5OUT` 줄** (`R5-05-R1.log`. 긴 칸은 줄였다. Y1b는 각 배열의 첫 원소이고, 10개 원소가 모두 같다):
```
R5OUT Y1a {"put":{"ok":true,"value":{"objectId":"object_late_0001","generation":1,"…":"…"}},"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"openedAfterPurge":"NOT_FOUND","filesAfterPurge":[],"reconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0,"corruptTransactions":0}},"openedAfterReconcile":"NOT_FOUND","filesAfterReconcile":[]} (긴 칸 줄임)
R5OUT Y1b n=0 [{"put":true,"removed":0,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음)
R5OUT Y1b n=1 [{"put":true,"removed":1,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음)
R5OUT Y1b n=2 [{"put":true,"removed":2,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음)
R5OUT Y1b n=3 [{"put":true,"removed":3,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음)
R5OUT Y1b n=8 [{"put":true,"removed":8,"partitionDeleted":true,"chunkSweep":null,"more":false,"late":"NOT_FOUND","files":0,"reconcileOk":true,"lateAfterReconcile":"NOT_FOUND","filesAfterReconcile":0}, …] (10개 원소, 모두 같음)
R5OUT Y3 {"pauseAt":"beforeCommit","putFailed":"UNAVAILABLE","rowPhaseBefore":"FILES_READY","reachedOrSettled":"PARKED","filesBeforePurge":"<5 files: staging receipt, chunk 2, manifest 2>","report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"filesAfterPurge":[],"reconciled":{"ok":true,"value":{"inspectedTransactions":1,"committedTransactions":0,"cleanedTransactions":0,"failedTransactions":1}},"filesAfterReconcile":[],"opened":"NOT_FOUND","rowAfter":null,"nextReconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0}},"filesAfterNextReconcile":[],"openedAfterNextReconcile":"NOT_FOUND"} (긴 칸 줄임)
R5OUT Y3 {"pauseAt":"afterCommit","putFailed":"UNAVAILABLE","rowPhaseBefore":"FILES_READY","reachedOrSettled":"PARKED","filesBeforePurge":"<5 files: staging receipt, chunk 2, manifest 2>","report":{"ok":true,"value":{"inspectedObjects":2,"removedObjects":1,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"filesAfterPurge":[],"reconciled":{"ok":true,"value":{"inspectedTransactions":1,"committedTransactions":1,"cleanedTransactions":1,"failedTransactions":0}},"filesAfterReconcile":[],"opened":"NOT_FOUND","rowAfter":null,"nextReconcile":{"ok":true,"value":{"inspectedTransactions":0,"failedTransactions":0}},"filesAfterNextReconcile":[],"openedAfterNextReconcile":"NOT_FOUND"} (긴 칸 줄임)
```
**05-R2 `R5OUT` 줄** (`R5-05-R2.log`, 두 엔진이 동시에 돌아 줄이 섞였다. 엔진 표시는 없다. 객체 수마다 6줄 = 2엔진 × 3회):
```
R5OUT browserY1-run {"count":0,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":0,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":0,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":0,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":0,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":0,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":0,"removedObjects":0,"releasedBytes":0,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":1,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":1,"removedObjects":1,"releasedBytes":1,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":3,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":3,"removedObjects":3,"releasedBytes":3,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":0,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":1,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
R5OUT browserY1-run {"count":8,"run":2,"put":true,"report":{"ok":true,"value":{"inspectedObjects":8,"removedObjects":8,"releasedBytes":8,"moreObjectsAvailable":false,"deadlineReached":false,"partitionDeleted":true}},"files":0,"opened":"NOT_FOUND"}
```
판정에 쓴 것:
- Y1a·Y1b·05-R2가 1103/05-01 완료 기준(2026-11-05 2.1절)을 채운다. 지난 라운드의 같은 실험은 객체 3·8개에서 메모리 20/20 `COMPLETED` + 파일 읽힘, Chromium 6/6 `OPENED`였다.
- Y3 `afterCommit`에서 purge의 `inspectedObjects`는 2, `removedObjects`는 1이다. [추론] reconcile이 commit한 객체의 remove가 아직 끝나지 않은 그 행 때문에 실패했고, 그래서 끝까지 못 돈 호출의 세기(2026-11-03 경로)가 partition 삭제로 보냈다. report의 `moreObjectsAvailable: false`·`partitionDeleted: true`와 맞는다. 그 뒤 재개된 reconcile은 `committedTransactions: 1, cleanedTransactions: 1`을 보고했지만 객체는 `NOT_FOUND`다. 그 commit은 삭제 전에 일어난 일이라 report가 틀린 것은 아니다.
- 05-R2의 `files: 0`은 partition 디렉터리가 없어서 나온 값일 수 있다(세는 함수가 그 경우 0을 돌려준다). 대조가 없으므로 판정은 `partitionDeleted`와 `NOT_FOUND`로 했다(5절).
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 05-01 | Low · P3 | 확인된 결함 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 | `docs/architecture/client-cache-and-storage.md:50-52`, `:1406-1407`; `docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md:66`; `src/contracts/storage-keys.ts:41-157` |
이월 중 열린 것: 0929/05-01 일부(③), 1101/05-06 일부(W2·W5·W6), 0929/05-05·05-06·05-07·05-10 남음. 1103/05-01·1105/05-01은 고쳐짐(05-R1·05-R2·05-R3·05-R4).
@@ -0,0 +1,200 @@
# 영역 06 — adapters: service worker, push
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `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`(SW 부분), `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`. 1103/09-05의 SW 쪽을 보려고 `src/bootstrap/{create-runtime-composition,optional-runtime-host,register-service-worker,product-composition-contract,runtime-adapters}.ts`도 읽었다
> 깊게 본 관점: 10, 18, 21, 28 (그다음 7, 20)
> 렌즈: 1105 수정 3건과 1103/09-05가 완료 기준을 채우는가 / 이 영역 경로를 건드린 수정이 검사를 약하게 했는가 / 호스팅 probe가 브라우저의 워커 조건을 따라가는가
> 영역 판정(35.8): 기본 구성(SW `null`) **지정 범위에서 사용 가능** · SW `ACTIVE` **조건부 사용 가능** · Web Push **조건부 사용 가능** (0절)
ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 라운드 밖에서는 `1106/06-NN`이다. 지난 라운드(2026-11-05)는 `1105/06-NN`, 그 전은 `1103/`, `1101/`, `0929/`, `0925/`다.
실행 방식: 이 리뷰는 아무것도 실행하지 않았다(BRIEF 2절). 근거는 이 커밋의 코드, desktop의 merge 단계 게이트 로그(`/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56), 그 실행의 산출물 snapshot(`/tmp/claude-gates/r5/snap/merge/`), 오케스트레이터 공유 실행(`/tmp/claude-gates/r5/snap/`)이다. 실험 4건은 요청 파일 `scratchpad/r5/requests/06.md`로 냈다(`06-R1`~`06-R4`). 오케스트레이터가 desktop에서 하나씩 돌렸다(2026-11-06 04:23~04:24, 항목마다 `bbde570`로 되돌림, 4건 모두 restore clean). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-06-Rk.log`다. 06-R1은 오케스트레이터 실수(중복 runner를 중간에 죽임)로 두 번 돌았고, 로그는 깨끗한 재실행 것이다. 4건 모두 기대와 같았다(6절).
## 0. 결론
| 구성 | 결정 | 조건·이유 |
| --- | --- | --- |
| 기본(SW `null`, Web Push 미선택) | 지정 범위에서 사용 가능 | 이 영역 런타임이 돌지 않는다. 빌드 로그가 `service worker mode null: skipping worker build`다(`r5/snap/build.txt:68`). 선택은 제품 소유 `src/features/product-capabilities.ts:34`의 `null`이다 |
| SW `ACTIVE` | 조건부 사용 가능 | (1) 활성화 화면(`onUpdateWaiting`·`requestActivation()`·`onReloadRequired`)을 잇는 제품 소유 자리가 없다. 붙이려면 템플릿 파일을 고친다(1103/09-05 일부, 0925/06-05 일부). (2) 업데이트 설치 실패는 신호가 없다(0925/06-05). (3) 호스팅이 `/service-worker.js`를 redirect하지 않는지 손으로 확인한다. probe는 같은 origin redirect를 통과시킨다(새 06-01). (4) `build.assetsDir`를 기본값으로 둔다(0925/06-08). (5) 하위 경로 호스팅 게이트는 13 영역 `0929/13-06`이다 |
| Web Push | 조건부 사용 가능 | 이 커밋에서 web-push 코드는 바뀌지 않았다. 서버의 짧은 TTL·send-time 인가 조건은 그대로다 |
- **1105 발견 3건: 고쳐짐 2, 일부 1.**
- 06-01 고쳐짐. 수집기가 `BUILD_ASSET_DIRECTORY` 아래만 본다. 새 테스트가 루트 아이콘을 넣은 dist에서 manifest를 `/assets/` 두 줄로 정확히 단언하고, FE-GATE-005에서 통과했다.
- 06-02 일부. redirect FAIL과 live 분기 함수 테스트는 들어왔다. live 분기 함수에서 자산 probe를 빼는 변이를 테스트 1건이 잡는다(06-R2). 워커 없는 빌드에서 probe 범위는 결정 대기다. 그 범위는 이제 redirect까지 넓어졌다.
- 06-03 고쳐짐. 옛 탭 route test가 FE-GATE-008(CI env)에서 chromium·webkit 모두 통과했다. 워커가 직전 캐시로 답하지 않게 바꾸면 두 엔진 모두 실패한다(06-R1). 실패 이유는 `sameDocument: false`와 허용 밖 fixture 줄이다.
- **1103/09-05(SW 쪽) 일부.** blockers·observe는 제품 소유 `composeProduct`에서 잇는다. 실제 조립을 돌리는 component 테스트가 통과한다. 활성화 화면 자리는 없다. e2e 도우미는 여전히 템플릿 파일 `register-service-worker.ts`를 사본에서 고쳐 host에 닿는다.
- **그 밖의 이월 10건**: 0925/06-05는 남음 → 일부(observe 자리가 생김). 1101 R4는 고쳐짐(그 test가 8 ms). 나머지 8건은 남음. 0925/06-08은 남음이지만 영향 범위가 넓어졌다. 06-01 수정으로 사전 캐시 수집기도 같은 하드코딩 상수를 읽는다.
- **새 발견 2건, 모두 Low·P3. High·P1은 없다.**
- 06-01: live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트의 redirect를 모두 거절한다. 그래서 FE-GATE-019 PASS인데 등록·업데이트·`REMOVE_REGISTRATION` kill switch가 실패할 수 있다.
- 06-02: 1101/10-07 수정(`ce191be`)이 marker 읽기 시간 상한 test의 실효 상한을 10초(실제 시간)에서 20초(가짜 시간)로 넓혔다. 상한을 15초로 올린 변이에서 64건이 모두 통과했다(06-R3, 생존). 10 영역과 같은 결함이면 한 건으로 합친다.
- **약해진 검사**: 06-02 하나다. 그 밖에 이 영역 경로의 `git diff 8a44226..bbde570`에서 단언 삭제, 정규식·허용 목록 완화, 상한 상향은 찾지 못했다. `hosting-probe.test.ts`의 `platform-examples-feature` → `fixture-feature`는 기능 ID 이름 바꿈이다(14-01). 06-03 수정이 Firefox skip 하나를 더했다(`service-worker-update.spec.ts:306`). 기존 격리와 같은 이유·만료일을 쓴다. skip을 지우자 그 test는 격리 주석이 적은 이유로 실패했다(06-R4: `requestActivation()` → `NO_WAITING_WORKER`). 그래서 이 skip은 제품 결함을 가리지 않는다.
- **Firefox 격리(`expires=2027-03-31`)**: Playwright는 그대로 `1.62.0`이다(`package.json:170`). FE-GATE-008에서 Firefox는 4건 skip이다(`FE-GATE-008.txt:144`, `:154-156`). 이번에 다시 돌린 것은 새 skip 1건(06-R4)이다. 나머지 3건은 지난 라운드 06-R11 뒤로 spec·워커·Playwright가 바뀌지 않았다. 그 결과는 현재 증거로 쓰지 않았다.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` (템플릿, reference implementation) |
| 커밋·작업 상태·확인 시점 | `bbde570`, laptop worktree(HEAD = 기준, 추적 파일 변경 없음, 무시한 untracked `AGENTS.md`), 2026-11-06 04시. `git log 8a44226..bbde570 -- <영역 경로와 SW 조립 파일>` 9커밋: `1c7c614`(1105/06-01), `4d6f254`(1105/06-02), `aaa782b`(1105/06-03), `fdc1db9`(1103/09-05), `ce191be`(1101/10-07), `f4d5761`(1105/12-04 실행 격리), `332bfee`(문서 검사), 합친 커밋 2개. 이 영역 런타임 코드에서 바뀐 곳은 `service-worker-static-assets.ts`(상수 import)와 `src/contracts/service-worker.ts`(상수 추가) 두 파일이다. web-push 코드는 바뀌지 않았다 |
| 목적과 지원 실행 구성 | 브라우저 SPA + 정적 호스팅 + Service Worker. SW 선택 기본값 `null`(`product-capabilities.ts:34`). 템플릿 `installed-runtime-capabilities.ts`는 검사·투영만 한다. Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts`) |
| 필수 요구와 규모·운영 목표 | 합의된 SLO·업데이트 전파 목표는 없다. 사전 캐시 상한 256개·5 MiB(`src/contracts/service-worker.ts:13-16`) |
| 읽은 코드·구성 범위 | 경로 머리의 파일 전부와 수정 커밋 9개의 diff. 연결: `src/contracts/{service-worker,service-worker-static-manifest}.ts`, `src/bootstrap/*`(위 다섯 파일), `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/support/browser/strict-browser-test.ts`, `tests/unit/{service-worker-runtime,service-worker-web-push-remediation,hosting-probe,service-worker-build-output}.test.ts`, `tests/component/runtime-composition-service-worker-product-wiring.test.ts` |
| 읽은 문서(주장) | `docs/operations/release-cache-rollback.md:60-99`, `:168-185`, `docs/operations/browser-file-storage-recovery.md:595-656`, `docs/architecture/optional-adapter-recipes.md:112`, `:127-174`, `docs/manual/03-outside-feature-folder.md:150-186`, 지난 라운드 README §15·§16, 수정 커밋 본문. 모두 주장으로 읽었다 |
| 실행 환경 | desktop 기존 증거만 읽었다. CI env merge 단계(`bbde570-ci/summary.txt`): FE-GATE-001~012·020 rc=0, 013 rc=1(이 영역 밖, 12-01). 이 영역이 쓴 것: FE-GATE-005(`gate-artifacts/FE-GATE-005.txt`, `test:unit` 208파일 3,056건 통과, `service-worker-runtime` 64·`hosting-probe` 39·`service-worker-web-push-remediation` 11·`service-worker-build-output` 7·`web-push-worker-runtime` 26, component `runtime-composition-service-worker-product-wiring` 1), FE-GATE-008(`gate-artifacts/FE-GATE-008.txt`, `test:e2e` 222 통과·4 skip, SW spec 줄 `:72-76`, `:86`, `:102`, `:120-121`, `:144-157`, `:206-231`), FE-GATE-020(`realtime-runtime-removal.xml` tests=7 failures=0, 2026-11-06 03:45). snapshot `merge/artifacts/tests/unit.xml`(03:46)의 test별 시간. 오케스트레이터 공유 실행: `verify-documentation.{local,no-sibling}.txt` 모두 `PASS_SCOPED`, `build.txt`. 요청 배치 06-R1~06-R4: local env, `r5/batch/out/R5-06-Rk.log`(6절). FE-GATE-019(release 단계)는 이번 실행에 없다. snapshot의 `hosting-headers.json`은 2026-11-05 20:09자라 쓰지 않았다 |
| 수행한 테스트·실험 | 이 리뷰는 직접 실행하지 않았다. 오케스트레이터 배치 4건(6절): e2e 워커 변이 1(06-R1), 단위 변이 2(06-R2, 06-R3), Firefox skip 해제 1(06-R4). 4건 모두 기대와 같았다 |
| 확인하지 못한 범위·이유 | 5절. 실제 CDN·푸시 서비스, live 모드 probe, 브라우저의 워커 스크립트 redirect 거절(일반 지식, 이 저장소에서 돌리지 않음), 하위 경로 브라우저 재확인 |
| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 문서(`docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md`)의 새 발견 3건, 2절 "남음" 이월 전부, README §16.5의 1103/09-05(SW 쪽)를 다시 봤다. §16.6에는 이 영역 행이 없다. 지난 실행 결과(06-R1~R11)는 현재 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
상태: **고쳐짐** = 완료 기준을 이 커밋에서 확인 · **일부** = 남은 것을 적음 · **남음** = 코드 그대로 · **재발** · **틀린 발견**.
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
| --- | --- | --- | --- |
| 1105/06-01 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)을 해시 자산으로 넣음 | **고쳐짐** | 수집기가 `BUILD_ASSET_DIRECTORY` 아래가 아닌 파일을 건너뛴다(`scripts/generate-service-worker-assets.ts:73-75`). 상수는 계약 모듈 한 곳이다(`src/contracts/service-worker.ts:118-126`). fallback(`service-worker-static-assets.ts:67-77`)과 probe(`scripts/lib/hosting-probe.ts:297`)도 같은 상수를 읽는다. 테스트(`tests/unit/service-worker-web-push-remediation.test.ts:133-157`)는 루트에 `apple-touch-icon.png`·`android-chrome-192x192.png`·`safari-pinned-tab.svg`·`icons/maskable-512x512.png`를 둔 dist에서 manifest URL이 `/assets/` 두 개와 **정확히 같다**고 단언한다. FE-GATE-005에서 그 파일 11건이 통과했다(`FE-GATE-005.txt:167`). 되돌리면 루트 아이콘이 목록에 들어가 `toEqual`이 깨진다(정적 확인). 레시피 문서도 맞다(`optional-adapter-recipes.md:166-171`). 완료 기준 충족. 남은 가정: `public/assets/`에 둔 파일은 Vite가 이름 그대로 `dist/assets/`에 복사하므로 여전히 이름만으로 해시 자산이 된다. 템플릿 `public/`에는 `config.json`·`release-manifest.json`뿐이라 지금은 해당이 없다(5절) |
| 1105/06-02 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돌고, live 호출 줄을 테스트가 지키지 않음 | **일부** | ① redirect: 기본 fetcher가 `redirect: "manual"`이다(`hosting-probe.ts:291`). `response.redirected`이거나 `opaqueredirect`이면 `observed: "redirected"`로 FAIL이다(`:312-317`, `:326-329`). 3xx는 `HTTP 3xx`로 FAIL이다. 테스트가 둘 다 단언하고(`tests/unit/hosting-probe.test.ts:381-400`) FE-GATE-005에서 통과했다(39건, `FE-GATE-005.txt:76`). ③ live 분기: 스크립트는 `probeLiveHosting` 하나만 부른다(`scripts/verify-hosting-headers.ts:113-118`). 그 함수가 release surface와 자산 probe를 묶는다(`hosting-probe.ts:342-357`). 테스트가 fetcher 대역으로 그 함수를 돌려 CSS `text/plain` 한 줄만 FAIL인지 본다(`hosting-probe.test.ts:414-451`). **06-R2**: 그 함수에서 자산 probe 결과 줄(`hosting-probe.ts:354`)을 지우자 이 테스트 1건만 실패했다(`expected [] to deeply equal [ 'hashedAsset.css content-type' ]`, `:443`). 나머지 38건은 통과했다. 지난 라운드 06-R2와 같은 자리의 변이가 이제 잡힌다. 완료 기준 둘째 충족. 스크립트 쪽 호출을 빼면 `responses`가 비어 cache-control 행이 모두 FAIL이라 실행 중에 드러난다(`verify-hosting-headers.ts:137-148`, 정적 확인). 스크립트가 `distFiles` 대신 빈 목록을 넘기는 실수는 아무 검사도 잡지 않는다. 자산 probe는 표본이 0개면 행을 하나도 내지 않는다(`hosting-probe.ts:293-302`). ② 워커 없는 빌드: 동작은 그대로이고 의도를 주석과 문서에 적었다(`hosting-probe.ts:283-287`, `release-cache-rollback.md:81-86`). 범위를 좁힐지는 결정 대기다(README §16.4). 수정 뒤 이 범위가 넓어졌다. 워커 없는 제품도 같은 origin redirect로 FAIL하고, 그 이유 문구는 "the worker's install fetch refuses a redirected asset"이다(`hosting-probe.ts:327`). 문서는 워커 없는 빌드의 이유로 `nosniff`만 적는다. §16.4와 같은 판정이다 |
| 1105/06-03 | SW 제어 아래에서 route chunk를 import하는 browser 검사가 없음 | **고쳐짐** | 새 test(`tests/e2e/service-worker-update.spec.ts:302-350`)는 B가 제어하는 A 탭에서 client navigation으로 지워진 route를 연다. 단언은 넷이다. not-found 화면(`:332-334`), 같은 문서(전역 표시와 entry script, `:335-343`), 그 chunk의 Resource Timing 항목(`:339-341`), navigation 뒤 서버 요청에 그 chunk가 없음(`:344-346`). strict fixture의 teardown 검사도 돈다. FE-GATE-008(CI env)에서 chromium·webkit 모두 통과했다(`FE-GATE-008.txt:120`, `:230`). Firefox는 skip이다(`:156`). 완료 기준 첫째("제어 아래 route import를 reload 없이 단언") 충족. **06-R1**(`service-worker-lifecycle.ts:296`의 직전 캐시 응답을 `return null`로): 새 test가 chromium·webkit 모두 실패했다. 두 엔진 모두 `{ sameDocument: false, chunkRequested: false }`였다(`:342`). chunk 복구가 페이지를 B로 reload했다는 뜻이다. strict fixture도 허용 밖 줄 셋을 냈다. chromium은 console 404, `requestfailed:GET:/assets/not-found-page-DIgPLsYZ.js:net::ERR_ABORTED`, "Failed to fetch dynamically imported module"이다. webkit은 console 404, 같은 chunk의 "Load request cancelled", "Importing a module script failed."다. 기존 "serves A's removed chunk" test도 두 엔진 모두 `status 404 ≠ 200`으로 실패했다. 완료 기준 둘째 충족. WebKit 경로도 같은 워커 분기를 지난다는 것이 확인됐다(수정 커밋 `aaa782b`이 남긴 미확인). 덧붙여: Resource Timing 단언은 navigation 전 항목과 뒤 항목을 나누지 않는다. 앱에 route prefetch가 없어서(`git grep -i prefetch -- src` 0건) 지금은 문제가 아니다. 실제 판별은 서버 요청 단언과 같은 문서 단언이 한다 |
| 1103/09-05 (SW 쪽, 09 영역과 공유) | SW를 켜고 잇는 일이 제품 확장 지점 밖에 있음 | **일부** | 고쳐진 것: `ProductComposition.serviceWorker?: { blockers?, observe? }`가 생겼다(`src/bootstrap/product-composition-contract.ts:127-139`, `:166`). `createRuntimeAdapters`가 이 칸을 싣고(`runtime-adapters.ts:779`) 템플릿 조립이 그대로 넘긴다(`create-runtime-composition.ts:34`, `:47`, `:61`, `:95-115`). 던지는 observe는 조립이 삼킨다(`:105-111`). component 테스트가 실제 `createRuntimeComposition`을 돌려 observe 기록과 `BLOCKED_DIRTY_CLIENT`를 단언하고(`tests/component/runtime-composition-service-worker-product-wiring.test.ts:133-161`) FE-GATE-005에서 통과했다(`FE-GATE-005.txt:682`). 매뉴얼이 예시를 준다(`docs/manual/03-outside-feature-folder.md:169-182`). 남은 것: 활성화 화면과 reload 안내를 이을 제품 소유 자리가 없다. `onUpdateWaiting`·`requestActivation`·`onReloadRequired`를 읽는 곳은 어댑터·계약·host 밖에 없다(`git grep`). `composition.optional`은 `runtime-application.tsx:22`의 `startAfterMount()`만 쓴다. e2e 도우미는 사본의 템플릿 파일 `register-service-worker.ts`를 감싸 host에 닿는다(`tests/e2e/support/service-worker-builds.ts:36-40`, `:89-109`). 레시피 표는 "update/rollback UX 없음"을 SW 금지 조건으로 둔다(`optional-adapter-recipes.md:112`). 그래서 규칙대로 SW를 켜는 제품은 템플릿 파일을 고친다. 레시피가 이를 적는다(`:127-129`). 완료 기준("제품 소유 파일만 고쳐 켜고 템플릿 파일 diff 0")은 blockers까지는 충족, 활성화 화면은 미충족. §16.5와 같은 판정이다 |
| 0925/06-05 | 업데이트 설치 실패·`observe`·`health()` 미연결 | **일부** (지난 라운드 남음) | 고쳐진 것: `observe`는 제품이 잇는다(위 1103/09-05). 남은 것: `watchForUpdates`는 `installed`만 알린다. 업데이트 워커가 `redundant`가 되거나 주기 검사가 실패해도 observe·telemetry가 없다(`service-worker-page-controller.ts:328-349`, `:359-361`의 `.catch(() => {})`). `OptionalRuntimeHost.health()`를 `src`에서 읽는 곳이 없다(`optional-runtime-host.ts:174`, `git grep`). 첫 시작 실패만 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:129-135`). 레시피가 이를 적는다(`optional-adapter-recipes.md:141-147`) |
| 0925/06-08 | 이전 빌드 fallback이 `assets/`를 하드코딩 | **남음** (영향 범위 넓어짐) | 하드코딩 자리가 상수 하나로 모였다(`src/contracts/service-worker.ts:126`). 그러나 Vite 설정의 `build.assetsDir`와 잇는 곳이 없다. `vite.config.ts`는 그 값을 정하지 않고, 상수와 같은지 보는 검사도 없다(`git grep assetsDir` 결과는 주석과 리뷰 문서뿐). 호스팅 정책 `/assets/*`(`config/hosting/cache-policy.json:26`)와 e2e 도우미의 `dist/assets` 읽기(`service-worker-update.spec.ts:102-106`)는 따로 적은 문자열이다. 1105/06-01 수정 뒤에는 수집기도 이 상수를 읽는다. 그래서 제품이 `assetsDir`를 바꾸면 fallback·probe에 더해 사전 캐시도 오류 없이 빈다. 빈 manifest는 decoder가 받는다(`service-worker-static-manifest.ts:136-142`, 최소 개수 없음). 수정 커밋이 이 한계를 적었다(`1c7c614` 본문 "0925/06-08은 그대로 남는다"). 원인과 고칠 곳이 같아서 새 발견으로 세지 않았다. 그런 제품에서는 FE-GATE-008의 SW spec이 `dist/assets` ENOENT나 `assets.length > 0` 단언(`service-worker-update.spec.ts:145-148`)으로 실패할 것이다(정적 추론, 원인 이름은 없다) |
| 0925 P3 | route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | **남음** | `service-worker-update.spec.ts:54-72` 그대로 |
| 1101/06-03 | PAGE_HELLO·UPDATE_READY·reload guard가 흔적만 남음 | **남음** | 파서가 두 kind를 받는다(`service-worker-protocol.ts:16`, `:18`). `reloadGuardBytes`·`reloadGuardTtlMs`(`src/contracts/service-worker.ts:27-28`)를 읽는 곳이 없다 |
| 1101/06-05 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | **남음** | `service-worker-static-assets.ts:279-284`. 이전 캐시 재사용 없음(`:220-262`) |
| 1101 R1 | `retainedPreviousCaches`를 `void`로만 참조 | **남음** | `service-worker-lifecycle.ts:169` |
| 1101 R2 | `validateActiveFence` 두 벌 | **남음** | `web-push/inbound/push-event-adapter.ts:196`, `notification-click-adapter.ts:356` |
| 1101 R3 | `SYNC_WAKE_OBSERVED`만 프로토콜 버전을 숫자로 씀 | **남음** | `service-worker-entry.ts:170`(`protocolVersion: 1`). 다른 메시지는 `SERVICE_WORKER_PROTOCOL_VERSION`을 쓴다(`service-worker-protocol.ts:108`, `:134`) |
| 1101 R4 | `bounds a stream that never produces a chunk`가 5초를 실제로 기다림 | **고쳐짐** | `ce191be`(1101/10-07)가 가짜 시계로 바꿨다(`service-worker-runtime.test.ts:2006-2041`). snapshot `unit.xml`(03:46)에서 그 test가 0.008초, 파일 64건이 0.32초다(지난 라운드 5,221 ms). 이 수정이 실효 상한을 넓힌 것은 새 **06-02**로 셌다 |
집계(13건): 고쳐짐 3(1105/06-01, 1105/06-03, 1101 R4) · 일부 3(1105/06-02, 1103/09-05, 0925/06-05) · 남음 7 · 재발 0 · 틀린 발견 0. README §16과 다른 판정: 0925/06-05를 "남음"에서 "일부"로 올렸다(§16.6에 행이 없음). 나머지는 §16.4·§16.5와 같다. 1105/06-03의 "고침"은 06-R1로 확인했다.
## 3. 이번 발견 (36.3)
새 발견 2건. 심각도: Critical 0 · High 0 · Medium 0 · Low 2. 우선순위: P0 0 · P1 0 · P2 0 · P3 2. 성격: 확인된 결함 1 · 구조적 위험 1 · 미검증 0 · 개선 제안 0.
### 06-01 live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 모두 거절한다
| 필드 | 내용 |
| --- | --- |
| 성격 | 구조적 위험 |
| 관련 관점 | 18, 21, 28, 5 |
| 근거 | 워커를 싣는 빌드에서 live 모드는 `serviceWorker` surface(`/service-worker.js`)를 요청한다(`config/hosting/cache-policy.json:41-47`, `scripts/verify-hosting-headers.ts:84-88`). 이 요청은 `probeLiveRelease`의 기본 fetcher `redirect: "follow"`로 간다(`scripts/lib/hosting-probe.ts:135`). `probeLiveHosting`은 `transport.fetcher`가 없으면 이 기본값을 쓴다(`:349`, 스크립트는 fetcher를 넘기지 않는다, `verify-hosting-headers.ts:114-116`). 행은 최종 응답의 `http-status`와 `final-origin`뿐이다(`hosting-probe.ts:142-157`). `response.redirected`는 보지 않는다. 그래서 같은 origin 안의 redirect 뒤 200·`no-cache`·JS MIME이면 모든 행이 PASS다. 운영 문서도 "Each required surface must return HTTP 200 without leaving that origin"이라고 적는다(`docs/operations/release-cache-rollback.md:66-67`). 한편 Service Worker 명세의 Update 알고리즘은 스크립트 요청의 redirect mode를 `"error"`로 둔다(일반 지식, 이 저장소에서 돌리지 않음). Chromium은 "The script resource is behind a redirect, which is disallowed"로 등록을 거절한다. 1105/06-02의 자산 probe는 같은 이유로 redirect를 FAIL로 바꿨는데(`hosting-probe.ts:312-329`), 워커 스크립트 surface에는 그 규칙이 없다. 테스트에도 워커 스크립트 redirect 사례가 없다(`tests/unit/hosting-probe.test.ts`의 `serviceWorker` 사례는 선택·`no-cache`만 본다) |
| 발생 조건 | SW `ACTIVE` 또는 `REMOVE_REGISTRATION` 제품. 호스트가 `/service-worker.js`를 같은 origin 안에서 redirect한다. 예: 버전 경로로 보내는 CDN 규칙, object storage 웹사이트의 redirect 규칙, 경로 정규화 규칙 |
| 영향 | FE-GATE-019가 PASS다. 그러나 첫 등록은 `register()` 거절로 `service-worker.start.failed`만 남는다. 이미 설치된 브라우저는 update 검사가 실패해 옛 워커에 머문다. 가장 나쁜 경우는 kill switch다. `REMOVE_REGISTRATION`은 브라우저 update 검사가 새 `service-worker.js`를 받는 것에 기댄다(`docs/operations/browser-file-storage-recovery.md:605-613`). redirect가 있으면 자기 해제 워커가 설치되지 않아, 부팅을 막는 워커를 걷어내지 못한다. 데이터 손상은 없다 |
| 심각도·우선순위 | Low · P3. 드문 호스팅 구성이고, 1105/06-02 ①과 같은 무게다. kill switch가 막히는 점은 28번에 적었다 |
| 통제·증거 | "probe PASS면 호스팅 때문에 워커 등록·업데이트가 실패하지 않는다" 규칙: `no-cache`는 M2(live 코드, 테스트는 fixture 쪽), redirect는 M0 · E1 |
| 확실성과 남은 가정 | probe가 redirect를 보지 않는 것은 코드로 확정된다. 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 일반 지식이다. 이 저장소에서 redirect 호스트로 등록을 돌려 보지 않았다. WebKit·Firefox 동작도 확인하지 않았다 |
| 결정의 근거 | 기록된 의도: 수정 커밋 `4d6f254`은 자산 probe만 고쳤다. 리뷰 1105/06-02도 자산만 다뤘고 "다른 surface는 `final-origin`을 본다"고 적었다. 리뷰어 추론: 다른 surface는 페이지가 받는 문서라 redirect가 허용되지만, 워커 스크립트는 브라우저가 redirect를 금지하는 유일한 surface다 |
| 이해 비용 | 운영자는 FE-GATE-019 PASS를 "kill switch가 동작한다"로 읽는다. 실제 범위는 probe의 fetch 옵션과 SW 명세를 같이 알아야 안다 |
| 최소 개선 방향 | `serviceWorker` surface에 redirect 행을 더한다. 자산 probe처럼 `response.redirected` 또는 `opaqueredirect`·3xx면 FAIL로 본다. 가장 작게는 `probe()`가 `response.redirected`를 결과에 싣고, `serviceWorker` surface에서만 그것을 FAIL로 판정한다. 운영 문서 `:66-67`에 "워커 스크립트는 redirect 없이"를 더한다 |
| 대안 비교 | (a) `serviceWorker` surface만 redirect FAIL. (b) 모든 surface에서 redirect FAIL. `index`·`appRoute`의 정상 redirect(예: 끝 슬래시 정규화)까지 막는다. (c) 문서에만 적음. (a)가 가장 작고 브라우저 규칙과 같다 |
| 단순화의 보존 조건 | 다른 surface의 `final-origin` 규칙, 자산 probe의 redirect 규칙(`hosting-probe.ts:312-329`)은 그대로 둔다 |
| 비용·부작용 | 수 줄과 테스트 1건. 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다. 그런 호스트는 지금도 워커가 동작하지 않는다 |
| 재검토 조건 | 브라우저가 워커 스크립트 redirect를 허용하게 바뀌면(명세 변경) 이 행을 지운다 |
| 완료 기준 | `/service-worker.js`에 `redirected: true`인 200을 주는 fetcher 대역에서 `probeLiveHosting`이 `serviceWorker` FAIL 행을 낸다 |
| 검증 방법 | `hosting-probe.test.ts`의 "live hosting probe" describe에 워커 스크립트 redirect 사례 1건. 브라우저 쪽은 e2e 도우미 서버가 `/service-worker.js`를 302로 주게 하고 `start()` 결과를 본다(선택) |
| 담당·기한·상태 | 템플릿 소유자(13 영역 호스팅 검사와 공동) · 미정 · 열림 |
| 재검증 결과 | 해당 없음(이번 라운드 발견) |
### 06-02 1101/10-07 수정이 marker 읽기 시간 상한 test의 실효 상한을 10초에서 20초로 넓혔다
| 필드 | 내용 |
| --- | --- |
| 성격 | 확인된 결함 (약해진 검사, 06-R3에서 변이 생존) |
| 관련 관점 | 10, 21 |
| 근거 | 런타임 상한은 `ACTIVATION_MARKER_READ_DEADLINE_MS = 5_000`이다(`src/adapters/service-worker/service-worker-lifecycle.ts:558`). 모듈 안 상수라 테스트가 import하지 못한다. 수정 전 test는 실제 시계로 `onActivate()`를 기다렸고 test 상한이 `10_000`이었다(`git show 8a44226:tests/unit/service-worker-runtime.test.ts`, 그 test 끝 `}, 10_000);`). 그래서 상한이 10초 이상이면 시간 초과로 실패했다. 수정 뒤 test는 가짜 시계로 5초씩 **최대 4번** 넘긴다(`tests/unit/service-worker-runtime.test.ts:2029-2034`). 그래서 상한이 20초 이하면 통과한다. 이 fixture에서 marker 읽기는 한 번뿐이다. 캐시 목록이 현재 캐시 하나라서(`:1951-1953`) `highestMarkedCache`는 읽지 않고(`service-worker-lifecycle.ts:207-208`), 현재 캐시 marker 하나만 읽는다(`:160`). 4번 반복은 이 test에 필요 없다. 같은 파일의 다른 가짜 시계 test는 계약 상수(`SERVICE_WORKER_BOUNDS.installDeadlineMs`, `clientDrainMs`)만큼 정확히 넘긴다(`service-worker-runtime.test.ts:984`, `:1615`). **06-R3**: 상한을 `15_000`으로 올린 변이에서 `service-worker-runtime.test.ts` 64건이 모두 통과했다(rc=0, 파일 104 ms). 변이가 살아남았다. 수정 전 test는 같은 변이에서 실제로 15초를 기다리므로 10초 test 상한에서 실패했을 것이다(정적 확인, 실행하지 않음) |
| 발생 조건 | 누군가 marker 읽기 상한을 10~20초로 올린다. 예: 느린 저장소를 이유로 30초 drain과 맞추려 할 때 |
| 영향 | `activate`가 marker 하나에 최대 20초 묶여도 단위 테스트가 통과한다. 그동안 새 워커의 활성화와 옛 캐시 정리가 늦어진다. 지금 코드에는 결함이 없다 |
| 심각도·우선순위 | Low · P3. 미래 회귀를 못 잡는 폭이 10초 넓어진 정도다 |
| 통제·증거 | "marker 읽기는 5초 안에 끝난다" 규칙: M2(코드) / 테스트는 "20초 안에 끝난다"만 검출 · E1 + E2(06-R3) |
| 확실성과 남은 가정 | 반복 횟수와 fixture의 읽기 횟수는 코드로 확정된다. 15초 변이 생존은 실행으로 확인했다. 수정 전 test가 그 변이를 잡았다는 것은 코드로 본 추론이다 |
| 결정의 근거 | 기록된 의도(`ce191be` 본문): 상한을 의존성으로 받게 하는 안은 "운영 코드에 테스트용 손잡이"라 버렸다. 리뷰어 추론: 손잡이 없이도 상수를 `SERVICE_WORKER_BOUNDS`로 옮기면 다른 test처럼 정확히 그만큼 넘길 수 있다. 이 상수만 계약 밖에 있다 |
| 이해 비용 | test를 읽는 사람은 "One read deadline per marker probe"를 보고 4번이 필요하다고 믿는다. 실제로는 한 번이다 |
| 최소 개선 방향 | (가) 반복 없이 `advanceTimersByTimeAsync(5_000)` 한 번 뒤 `settled`를 단언한다. (나) 상수를 `SERVICE_WORKER_BOUNDS`로 옮기고 그 값만큼 넘긴다. 상한을 1 ms만 올려도 test가 실패한다 |
| 대안 비교 | (가)는 한 줄이고 숫자가 test에 중복된다. (나)는 계약 상수 하나가 늘고 중복이 없다. 현상 유지는 10~20초 회귀를 못 잡는다. (나)가 같은 파일의 다른 test와 맞는다 |
| 단순화의 보존 조건 | 가짜 시계로 빠르게 도는 것(1101 R4 해결)과 `cancels >= 1` 단언을 유지한다 |
| 비용·부작용 | 수 줄. (나)는 계약 모듈 변경이라 워커·페이지 두 realm 타입 검사를 다시 돈다 |
| 재검토 조건 | fixture가 marker를 여러 번 읽게 바뀌면 그 횟수만큼 정확히 넘긴다 |
| 완료 기준 | 상한을 5,001 ms로 올리는 변이에서 이 test가 실패한다 |
| 검증 방법 | 06-R3와 같은 실행(상한 값만 5,001로 바꿈). 무변이에서는 통과한다 |
| 담당·기한·상태 | 템플릿 소유자(10 영역 1101/10-07과 공동. 같은 결함으로 세면 한 건으로 합친다) · 미정 · 열림 |
| 재검증 결과 | 해당 없음(이번 라운드 발견) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 통제는 "목표 / 확인"이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
| --- | --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | P. 사전 캐시가 `assets/`만 받는다(1105/06-01 고쳐짐). 자산 probe가 redirect를 거절한다. 워커 스크립트 surface만 redirect를 본다(06-01) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1·E2 | O. worker·page realm을 tsconfig로 나눈다. FE-GATE-003 PASS. FE-GATE-020의 제거 사본에서도 `tsc --project tsconfig.service-worker.json`이 돈다(`FE-GATE-020.txt:3098`) |
| 3 | 변경 용이성 | 적용 | M2 / M1~M2 | E1·E2 | P. SW 켜기·blockers·observe는 제품 소유 파일로 된다(1103/09-05 일부). 활성화 화면은 템플릿 파일을 고친다 |
| 4 | 인지 부하 | 적용 | - | E1 | P. 쓰지 않는 kind·상수가 남았다(1101/06-03). lifecycle 736줄, page controller 642줄, subscription adapter 1,203줄 그대로 |
| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 레시피·운영 문서가 사전 캐시 범위와 자산 redirect를 맞게 적는다(`optional-adapter-recipes.md:166-171`, `release-cache-rollback.md:81-86`). 워커 스크립트는 "origin을 떠나지 않으면 된다"로 적혀 있다(06-01) |
| 6 | 실패 성숙도 | 적용 | M2 / M2 | E1·E2 | P. install 거절 11종을 구분한다. 업데이트 설치 실패는 페이지에 오지 않는다(0925/06-05) |
| 7 | 운영 성숙도 | 적용 | M2 / M1~M2 | E1·E2 | P. 시작 실패는 telemetry로, page controller 관측은 제품 observe로 닿는다. 업데이트 실패·`health()`는 미연결(0925/06-05). probe PASS가 워커 등록 성공을 다 뜻하지 않는다(06-01) |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1·E2 | P. observe가 제품 파일에서 닿는다(`product-composition-contract.ts:134-138`, component 테스트 통과). registry 거절 메시지는 여전히 이유를 말하지 않는다(`notification-registry.ts:53`) |
| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. 읽히지 않는 상수·kind(1101/06-03), `validateActiveFence` 두 벌(R2), 폐기 예정 `inlineDynamicImports`(`vite.service-worker.config.ts:87`) |
| 10 | 테스트 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2(CI env)·E3(06-R1) | P. 새 테스트가 이 커밋에서 통과한다: 수집기 루트 아이콘, 자산 redirect, live 분기 함수, 옛 탭 route(chromium·webkit), 제품 SW 조립(component). 수정이 노린 변이를 잡는다: 워커 fallback 끊기는 두 엔진 4건 실패(06-R1), live 분기의 자산 probe 삭제는 1건 실패(06-R2). marker 상한 test는 15초 변이를 통과시킨다(06-02, 06-R3). 새 Firefox skip은 격리 이유로 실패한다(06-R4) |
| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다(`service-worker-static-assets.ts:279-284`). 이제 `assets/` 밖 파일은 들어가지 않는다. push fence에 계정 ID·endpoint가 없다. 코드 변경 없음 |
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. nonce·drain 테스트가 FE-GATE-005에서 통과한다. 이 영역 동시성 코드는 바뀌지 않았다. 지난 라운드 변이 결과는 다시 쓰지 않았다 |
| 13 | 확장성 | 적용 | M2 / M2 | E1 | P. 256개·5 MiB 상한을 빌드가 막는다. waiting 기간 캐시 누적은 문서화만 했다(1103/06-04) |
| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1·E2 | P. 릴리스마다 사전 캐시 전체를 다시 받는다(1101/06-05). 단위 테스트 파일은 5.2초에서 0.32초가 됐다(1101 R4) |
| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | O. registry 경로 정규화, install fetch의 `credentials`·`redirect` 테스트가 통과한다. 코드 변경 없음 |
| 16 | 의존성 성숙도 | 적용 | - | E1 | P. 런타임 외부 패키지 없음. `inlineDynamicImports` 그대로 |
| 17 | API / Contract 성숙도 | 적용 | M2 / M2 | E1·E2 | P. `ProductComposition.serviceWorker`는 선택 칸이라 기존 제품 파일이 그대로 통과한다. 처리하지 않는 kind를 받는다(1101/06-03) |
| 18 | 배포 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2 | P. 사전 캐시 범위가 호스팅 정책과 맞는다. 자산 redirect·live 분기가 테스트된다. 남은 것: 워커 스크립트 redirect(06-01), 워커 없는 빌드의 probe 범위(1105/06-02 결정 대기), `assetsDir` 상수(0925/06-08), 하위 경로 게이트(13 영역 0929/13-06). FE-GATE-019는 이번에 돌지 않았다 |
| 19 | 설정 성숙도 | 적용 | M3 / M2 | E1 | P. 선택은 제품 소유 파일 하나다. 자산 디렉터리는 Vite 설정과 이어지지 않은 상수다(0925/06-08) |
| 20 | 개발자 경험 | 적용 | M1 / M1 | E1 | P. 매뉴얼이 `composeProduct`의 `serviceWorker` 예시를 준다(`03-outside-feature-folder.md:169-182`). 활성화 화면은 템플릿 파일을 고친다고 적는다(`:184`) |
| 21 | Guardrail 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. live 분기가 함수 테스트를 얻었고 변이를 잡는다(1105/06-02 ③, 06-R2). 옛 탭 route를 결과로 단언하고 워커 결함을 두 엔진에서 잡는다(1105/06-03, 06-R1). preload 허용은 그대로지만 이제 이 test가 결과로 대신 본다. marker 상한 test가 약해졌다(06-02, 06-R3). 워커 스크립트 redirect는 게이트 밖이다(06-01) |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 구조적 facade로 워커 없이 테스트한다. 제품 SW 조립 테스트는 실제 조립 경로를 돈다 |
| 23 | 일관성 | 적용 | - | E1 | P. "사전 캐시 = `assets/`"가 코드 세 곳에서 한 상수다. 호스팅 정책 `/assets/*`(`cache-policy.json:26`)는 따로 적은 문자열이다. redirect 규칙이 자산(거절)과 워커 스크립트(통과)에서 다르다(06-01) |
| 24 | 네이밍 / 의미 | 적용 | - | E1 | P. `retainedPreviousCaches`는 읽히지 않는다(R1). test 주석 "One read deadline per marker probe"가 반복 4번을 설명하지만 이 fixture는 한 번 읽는다(06-02와 같은 결함, 따로 세지 않음) |
| 25 | 조직 확장성 | 적용 제외 | - | - | -. 1인 관리 전제(0.1) |
| 26 | Ownership 성숙도 | 적용 | M1 / M1 | E1 | O. 레시피가 템플릿이 가진 것과 제품이 붙일 것(4·5)을 나눠 적는다(`optional-adapter-recipes.md:127-129`). 지난 라운드의 틀린 문장(1105/06-01)이 고쳐졌다 |
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E3 | O. web-push·realtime을 지운 fixture에서 7 check가 모두 통과한다(`realtime-runtime-removal.xml` tests=7 failures=0, 2026-11-06 03:45, FE-GATE-020 CI env) |
| 28 | 회복 가능성 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2·E3 | P. kill switch와 자기 해제 워커, 제거 단계 유지 기간이 있다. 옛 탭 route test가 생겼고, 워커가 직전 캐시로 답하지 못하면 두 엔진에서 실패한다(1105/06-03, 06-R1). kill switch는 워커 스크립트가 redirect 없이 서빙된다는 전제를 probe가 보지 않는다(06-01). `null` 릴리스 뒤 옛 워커를 걷어내는 장치는 없고 문서로 운영한다 |
집계: 적용 27개 중 O 7(2, 11, 12, 15, 22, 26, 27) · P 20 · X 0 · ? 0, 적용 제외 1. 지난 라운드 대비 26번이 P에서 O로 올라왔다.
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
| --- | --- | --- |
| Firefox 격리 나머지 3건(update 2, recovery 1) | 이번 배치는 새 skip 1건만 풀었다(06-R4). 나머지는 지난 라운드 06-R11 뒤로 spec·워커·Playwright가 바뀌지 않았다 | Playwright를 올릴 때 06-R4처럼 skip을 풀고 firefox로 두 spec 실행 |
| 06-R1의 다른 워커 결함 종류 | 배치는 직전 캐시 응답 끊기 한 종류다 | MIME이 틀린 캐시 응답, 다른 build의 chunk 바이트를 주는 변이 |
| 06-01 브라우저의 워커 스크립트 redirect 거절 | 명세·Chromium 오류 문구에 기댄 일반 지식이다. 이 저장소에서 돌리지 않았다. WebKit·Firefox는 모른다 | e2e 도우미 서버가 `/service-worker.js`를 302로 주게 하고 첫 `start()` 결과와 `REMOVE_REGISTRATION` 해제를 본다 |
| live 모드 probe 전체(FE-GATE-019) | release 단계 게이트라 이번 실행에 없다. live 모드는 저장소 안에서 돌 수 없다 | staging 호스트로 `HOSTING_BASE_URL` live probe |
| `public/assets/` 파일의 사전 캐시(1105/06-01 남은 가정) | 템플릿 `public/`에 그런 파일이 없다 | 수집기 단위 테스트에 `public/assets/` 사례. 더 정확한 방법은 Vite manifest(`vite.config.ts:212` `manifest: true`)의 산출 목록을 쓰는 것이다 |
| `assetsDir`를 바꾼 제품의 증상(0925/06-08) | 정적 추론만 했다 | 사본에서 `build.assetsDir: "static"`으로 빌드하고 manifest·FE-GATE-008 결과 확인 |
| Web Push end-to-end(실제 푸시 서비스, VAPID) | 푸시 서버 없음. `WEB_PUSH`는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 |
| 하위 경로(`/app/`) 브라우저 설치 재확인 | 이 영역 SW 런타임 코드는 상수 하나만 바뀌었다. 다시 돌리지 않았다 | 지난 1103 L1과 같은 실험 |
| 얼어 있는 탭이 Web Lock을 쥔 경우, A 워커 아래 B 부팅 지연 | 재현 환경 없음 | `Page.setWebLifecycleState(frozen)`, resource timing 비교 |
## 6. 실행 기록
이 리뷰는 laptop·desktop 어디에서도 명령을 실행하지 않았다. 읽은 증거(모두 `bbde570`, CI env, 2026-11-06 03:24~03:56):
| 증거 | 위치 | 이 문서에서 쓴 내용 |
| --- | --- | --- |
| 게이트 요약 | `desktop:/tmp/claude-gates/bbde570-ci/summary.txt` | FE-GATE-001~012·020 rc=0, 013 rc=1 |
| FE-GATE-005 | `bbde570-ci/gate-artifacts/FE-GATE-005.txt` | 이 영역 단위 파일 통과 줄(`:28`, `:76`, `:119`, `:155`, `:167`), component `:682`, 전체 3,056건 통과(`:313`) |
| FE-GATE-008 | `bbde570-ci/gate-artifacts/FE-GATE-008.txt` | SW spec test별 결과(chromium `:72-121`, firefox `:144-157`, webkit `:206-231`), 222 통과·4 skip(`:233-234`) |
| FE-GATE-020 | `bbde570-ci/gate-artifacts/FE-GATE-020.txt`, `r5/snap/merge/artifacts/tests/realtime-runtime-removal.xml` | 7 check 통과, `tsc --project tsconfig.service-worker.json`(`:3098`) |
| unit junit | `r5/snap/merge/artifacts/tests/unit.xml`(03:46) | `bounds a stream …` 0.008초, `service-worker-runtime` 64건 0.32초, `hosting-probe` 39건 |
| 공유 실행 | `r5/snap/verify-documentation.{local,no-sibling}.txt`, `r5/snap/build.txt` | 둘 다 `PASS_SCOPED`, 기본 빌드는 워커 빌드를 건너뜀(`build.txt:68`) |
요청한 배치(요청 `scratchpad/r5/requests/06.md`, 패치 `06-Rk.diff`, 모두 laptop `bbde570`에서 `git apply --check` 통과). 오케스트레이터가 desktop checkout에서 항목마다 `bbde570`로 되돌린 뒤 패치를 적용해 돌렸다(local env, 2026-11-06 04:23~04:24, 부하 2.5~2.9). 4건 모두 restore clean. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-06-Rk.log`, 요약 `r5/batch/summary.txt`. 무변이 대조는 게이트가 대신한다: 06-R1·R4는 `FE-GATE-008.txt:102`, `:120`, `:156`, `:229-230`, 06-R2·R3는 `FE-GATE-005.txt:76`, `:119`. 06-R1은 오케스트레이터의 중복 runner 사고로 두 번 돌았고, 위 로그는 깨끗한 재실행 것이다.
| ID | 명령 | 변이 | rc · 시간 | 결과 |
| --- | --- | --- | --- | --- |
| 06-R1 | `corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=chromium --project=webkit --grep "removed"` | `service-worker-lifecycle.ts:296` 직전 캐시 응답을 `return null` | 1 · 30초 | **기대대로** 4건 FAIL. "serves A's removed chunk"는 두 엔진 모두 `status 404 ≠ 200`(`:279`)과 console 404. "opens A's removed route"는 두 엔진 모두 `{ sameDocument: false, chunkRequested: false }`(`:342`)와 허용 밖 fixture 줄 셋(console 404, chunk `requestfailed`, dynamic import 실패) |
| 06-R2 | `node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts` | `hosting-probe.ts:354` `probeLiveHosting`에서 자산 probe 결과 삭제 | 1 · 1초 | **기대대로** 1건 FAIL, 38건 통과. "live hosting probe (1105/06-02) > checks every built asset type besides the release surfaces"가 `expected [] to deeply equal [ 'hashedAsset.css content-type' ]`(`hosting-probe.test.ts:443`) |
| 06-R3 | `node scripts/run-vitest.ts run tests/unit/service-worker-runtime.test.ts` | `service-worker-lifecycle.ts:558` 상한 5_000 → 15_000 | 0 · 1초 | **기대대로** 64건 모두 통과(파일 104 ms). 변이 생존 → 06-02 확정 |
| 06-R4 | `corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=firefox --grep "opens A's removed route"` | 새 test의 Firefox skip 삭제(`:306`) | 1 · 13초 | **기대대로** 1건 FAIL. `updateFromAToB`에서 `requestActivation()`이 `{ kind: "NO_WAITING_WORKER" }`(`:214`). 격리 주석(`:174-181`)이 적은 Playwright Firefox의 워커 제어 문제다. skip 유지가 맞다 |
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
| --- | --- | --- | --- | --- |
| 06-01 | Low · P3 | 구조적 위험 | live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 거절해 등록·업데이트·`REMOVE_REGISTRATION`이 실패할 수 있다 | `scripts/lib/hosting-probe.ts:135`, `:142-157`; `docs/operations/release-cache-rollback.md:66-67` |
| 06-02 | Low · P3 | 확인된 결함 (약해진 검사, 06-R3 생존) | 1101/10-07 수정이 marker 읽기 상한 test의 실효 상한을 10초에서 20초로 넓혔다 | `tests/unit/service-worker-runtime.test.ts:2029-2034`; `src/adapters/service-worker/service-worker-lifecycle.ts:558` |
@@ -0,0 +1,163 @@
# 영역 07 — contracts (공유 어휘·외부 계약)
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/contracts/`(44파일, 9,329줄), `schemas/`(5파일), `config/contracts/`(7파일. 새 파일 `backend-http-contract-excerpt.json`). 함께 본 곳: `scripts/check-backend-contract-drift.ts`, `scripts/lib/backend-contract-excerpt.ts`, `scripts/lib/registry-compatibility.ts`, `scripts/check-registries.ts`, `scripts/lib/removal-fixture.ts`
> 깊게 본 관점: 17, 21, 10, 20, 23
> 렌즈: 1105/07-01·07-02·09-03, 1103/07-04, 1103/16-01(BREAKING `56272e8`), 통합 커밋 `45c9c4d`의 pin 수정, 1105/03-01 테스트가 들어간 문서 테스트 제외 목록
> 영역 판정(35.8): **조건부 사용 가능.** 외부 계약 조립기, FE-REG-API 투영, 응답 스키마 축소 등급, 짝 백엔드 답 표와 사본 대조는 그대로 써도 된다. 조건은 둘이다. (1) 짝 백엔드를 받을 때마다 `check:backend-contract-drift --backend <dir>`를 돌린다. 사본과 실제 백엔드 문서의 대조는 여전히 게이트 밖이다(1105/07-01의 설계 한계, D6). (2) 스키마 메타 행을 손으로 쓸 때 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 응답 DTO를 strict로 바꿔도 아무 검사도 보지 않는다(07-02).
ID 표기: 이 문서의 `07-NN`은 2026-11-06 라운드 ID다. 지난 라운드(2026-11-05)는 `1105/07-NN`, 그 전은 `1103/07-NN`이다. 다른 영역 ID도 같은 꼴로 적는다.
## 0. 결론
- **지난 라운드 영역 07 발견 3건(1105/07-01, 1105/07-02, 1103/07-04)과 지시로 다시 본 2건(1105/09-03, 1103/16-01)이 모두 고쳐졌다.** README §16과 판정이 같다. 1105/07-02의 완료 기준은 배치 07-R1로 확인했다. 지난 라운드와 같은 strict 패치에서 `check:registries`가 `response-reader-narrowed` 증거 누락 2줄로 실패했다(registries-rc=1).
- **1105/07-01:** 답 표가 이제 pin 커밋의 백엔드 표 사본과 행마다 대조된다(`tests/unit/backend-contract-pin.test.ts:165-179`). 사본 17줄이 백엔드 `45d2a478:docs/web/http-contract.md:86-91, 109-113, 188-193`과 글자까지 같다(리뷰어가 노트북에서 대조). drift 스크립트는 checkout이 없으면 rc=2로 끝나고(`scripts/check-backend-contract-drift.ts:96-110`), 매뉴얼에 있다(`docs/manual/01-add-a-feature.md:228`). desktop 옆 백엔드 checkout으로 돌린 drift는 rc=0이다. 백엔드 HEAD `3d73b6f`는 pin 뒤지만 문서와 scaffold 파일 6개가 그대로다(배치 07-R3). 지난 라운드의 "desktop에서 비교 불가(rc=2)"는 풀렸다. 사본과 실제 백엔드의 대조가 게이트 밖인 것은 D6의 설계 한계라 다시 세지 않는다.
- **통합 수정 `45c9c4d`는 맞다.** pin의 `notCopied`가 비었고(`config/contracts/backend-contract-pin.json:50`), 사본 §4의 네 행이 답 표에 모두 있다(`IDEMPOTENCY_KEY_INVALID`는 §2 행이 덮는다). 프론트 거절 표의 `RATE_LIMIT_*` 둘도 답 표가 받친다(`src/adapters/http/backend-envelope.ts:180-181`). `notCopied`가 비어도 옮기지 않은 행은 "neither in the answer table nor in the pin's notCopied"로 실패한다(`scripts/lib/backend-contract-excerpt.ts:135-151`). 배치 07-R2: 사본 §4에 429 행 하나를 더하자 "copies the answers from the backend table rows at the pin" 1건만 `§4 429 RATE_LIMIT_EXCEEDED is neither in the answer table nor in the pin's notCopied`로 실패했다(14건 통과, vitest-rc=1).
- **BREAKING 1103/16-01은 코드·CHANGELOG·생성기·repo 안 descriptor가 모두 맞는다.** `responseEnvelope`가 타입의 필수 칸이고(`src/contracts/external-contract-runtime.ts:239`), 생성기 세 descriptor와 참조 기능 셋이 값을 적는다. `@ts-expect-error`(`tests/unit/external-contract-runtime.test.ts:396`)가 FE-GATE-003에서 쓰였으니 타입이 줄을 요구한다. 다만 계약 문서 한 줄이 아직 "bulk는 `responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(새 07-01, Low).
- **1105/03-01 테스트를 문서 테스트 제외 목록에 넣은 것은 드릴에 필요한 검사를 빼지 않았다.** 빠진 곳은 문서를 복사하지 않는 capability 드릴 셋뿐이다. 그 드릴들이 지우는 파일은 pin 테스트가 보는 파일과 겹치지 않는다. pin 테스트는 `test:unit`과, 문서를 복사하는 참조 기능 제거·생성 기능 드릴에서 그대로 돈다(FE-GATE-020 로그에서 8번 통과). 파일 단위 제외라 문서를 읽지 않는 14건도 같이 빠지지만, 그 14건이 보는 것은 세 드릴이 건드리지 않는다.
- **새 발견 07-02:** FE-REG-SCHEMA 행의 `direction`·`unknownFieldPolicy`는 선택 칸이다. 적지 않은 행은 정책 테스트가 건너뛴다. 그래서 1105/07-02 수정(값이 좁혀지면 breaking)이 닿지 않는 경로가 남는다(Low).
- **이번 수정들이 영역 07의 검사를 약하게 만든 곳은 찾지 못했다.** `git diff 8a44226..bbde570`의 영역 파일에서 지운 단언은 없다. 넓어진 목록은 둘이다. 문서 테스트 제외 목록(위 판단)과 FE-REG-STORAGE `orphanExemptRows`의 `AUTH_REDIRECT_TRANSACTION`(`config/contracts/registry-governance.json:376`, 1105/05-01, 영역 05 몫. 행 하나만 더했고 이유가 1105 README §16.3에 있다)이다.
- High 이상과 P1은 없다. 새 발견 2건(Low 2, P3 2).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 07 |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`)에서 읽기만 했다. 미커밋 변경은 추적 안 되는 `AGENTS.md`뿐이다(무시). 2026-11-06 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 템플릿과 함께 빨리 출시하는 것이 목표 |
| 필수 요구와 규모·운영 목표 | 합의된 규모·운영 목표 없음. 짝 백엔드 응답 기준은 pin 커밋 `45d2a478`의 `docs/web/http-contract.md`(노트북 backend checkout에서 `git show`로만 읽음) |
| 읽은 코드·구성 범위 | 줄 단위: `config/contracts/backend-contract-pin.json`·`backend-idempotency-answers.json`·`backend-http-contract-excerpt.json` 전체, `scripts/lib/backend-contract-excerpt.ts` 전체, `scripts/check-backend-contract-drift.ts` 전체, `tests/unit/backend-contract-pin.test.ts` 전체, `tests/unit/backend-contract-drift.test.ts` 전체, `src/contracts/external-contract-runtime.ts:120-310, 510-530, 620-720`, `src/contracts/env.ts` diff, `src/bootstrap/load-runtime-config.ts:120-155`, `scripts/lib/registry-compatibility.ts:140-165, 300-390`, `scripts/check-registries.ts:150-170`, `tests/unit/schema-metadata-policy.test.ts` 전체, `scripts/lib/removal-fixture.ts:40-170`, 세 capability 제거 드릴 스크립트의 삭제 목록, `src/adapters/http/backend-envelope.ts:130-270`. `git diff 8a44226..bbde570 -- src/contracts config/contracts schemas` 전체와 영역 테스트 diff. 함께 읽은 곳: 생성기의 descriptor·스키마 메타 문자열(`scripts/create-feature.ts:700-840`, `scripts/create-feature-write-slice.ts:205-350`), 참조 기능 contribution |
| 읽은 문서(주장) | `CHANGELOG.md:14-77`(미출시 절의 먼저 할 일·계약 표), `docs/architecture/backend-api-and-server-state-contract.md:161-208`(4.1절), `docs/manual/01-add-a-feature.md:205-305, 535-552`, `docs/manual/reference/errors.md:104-110, 156`, `docs/contracts/compatibility.md:18-37`, `config/ci/ungated-scripts.json:4-7`, 커밋 본문 `daf3474`·`3b62ccd`·`bfd9d50`·`2e1acb1`·`56272e8`·`f600e6b`·`5c0b37e`·`c6c37f3`·`45c9c4d`, 지난 라운드 07 문서, README §15·§16 |
| 수행한 테스트·실험 | 리뷰어는 아무것도 실행하지 않았다(노트북 금지, desktop은 읽기만). 쓴 증거: `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`(CI env, 2026-11-06 03:24-03:56) FE-GATE-001~012·020 rc=0, 013 rc=1(영역 12 몫). 전체 로그 `gate-artifacts/FE-GATE-004.txt`(runtime-schema 60건), `FE-GATE-005.txt`(test:unit 208파일 3,056건, coverage 332파일 4,085건), `FE-GATE-010.txt`(`check:registries` `11 registries PASS; compatibility=additive`), `FE-GATE-020.txt`(제거·생성 드릴). FE-GATE-001~003은 한 줄 로그만 있다(`FE-GATE-003 typecheck: PASS`). 오케스트레이터 공유 실행 `desktop:/tmp/claude-gates/r5/snap/verify-documentation.local.txt`(PASS_SCOPED). 노트북에서 읽기 대조 둘: 사본 17줄 ↔ 백엔드 `45d2a478` 문서(diff 같음), 요청 패치 둘의 `git apply --check`. 오케스트레이터 배치 07-R1~R3(local env, 2026-11-06 04:23, load 2.92, 항목마다 restore clean, 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-07-R*.log`, 6절) |
| 확인하지 못한 범위·이유 | 짝 백엔드를 실제로 띄워 답을 받지 않았다. 다운스트림 두 repo의 descriptor가 `satisfies`인지 `as`인지 보지 않았다(BREAKING 1단계가 그들에게 실제로 실패를 내는지). `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 다시 읽지 않았다. 이번 diff가 없거나 영역 07 발견과 무관하다(`service-worker.ts`는 1105/06-01의 상수 하나, `diagnostics.ts`·`server-state.ts`·`storage-keys.ts`는 02-01·1103/16-05·05-01의 추가만, diff로 확인) |
| 이전 리뷰와 비교 가능한 범위 | 지난 07-R1 패치를 그대로 다시 돌렸다(07-R1. 지난 라운드는 PASS `behavior-change`, 이번은 rc=1 breaking). 지난 D6f(desktop drift rc=2)는 07-R3로 다시 돌렸다(rc=0). D6g는 수정 커밋의 drift 단위 테스트가 가짜 백엔드로 돈다(FE-GATE-005, 9건 통과). 지난 실행 결과는 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
지난 라운드 영역 07 발견은 1105 새 발견 2건(README §15)과 1103 이월 1건(§16.5)이다. §16.6에 영역 07 행은 없다. 지시로 다른 영역 발견 2건(1105/09-03, 1103/16-01)도 다시 봤다.
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|---|---|---|---|
| 1105/07-01 | 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 스크립트만 알린다(desktop rc=2, worktree skipped rc=0, 매뉴얼에 없음) | **고쳐짐** | 완료 기준 셋. (1) 답 표와 pin 문서의 어긋남, pin 문서에만 있는 행: drift가 pin 커밋 문서의 표로 `answerTableProblems`를 돌린다(`scripts/check-backend-contract-drift.ts:147-150`). 사본이 pin 문서와 다르면 줄 단위로 찍는다(`:144-146`). pin 뒤 표 행이 바뀌면 찍는다(`:153-168`). drift 단위 테스트가 status 오타, 사본 오타, 옮기지도 적지도 않은 행, D6g를 가짜 백엔드로 돈다(`tests/unit/backend-contract-drift.test.ts:235-286`, FE-GATE-005 9건 통과). (2) checkout이 없으면 rc=2 "not compared"(`:96-110`, 테스트 `:288-293`). 기본 경로는 main checkout 옆이라 linked worktree도 같은 백엔드를 찾는다(`:76-90`). (3) 매뉴얼 01에 언제 무엇을 돌리는지 있다(`docs/manual/01-add-a-feature.md:227-229`). 더해서 게이트 쪽: 답 표를 pin 커밋 표의 사본과 행마다 대조한다(`tests/unit/backend-contract-pin.test.ts:165-179`, FE-GATE-005). 사본 17줄은 `45d2a478:docs/web/http-contract.md:86-91, 109-113, 188-193`과 같다(리뷰어 대조, 1절). pin의 `sectionsCompared` §4 범위 문제는 §4 네 행을 모두 옮겨 풀렸다. 남은 것(다시 세지 않음): 사본 ↔ 실제 백엔드는 게이트 밖이다(D6, `config/ci/ungated-scripts.json:5-6`). §1은 사본에 없고 사람이 읽는다(아래 4절 24번). 실행: 07-R2(사본에만 있는 행 → pin 테스트 1건 실패), 07-R3(desktop drift rc=0, 백엔드 HEAD `3d73b6f`, "docs/web/http-contract.md and 6 scaffold sources unchanged") |
| 1105/07-02 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과한다 | **고쳐짐** | 분류기가 `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 `REJECT_UNKNOWN`으로 바뀌면 `response-reader-narrowed` breaking으로 본다(`scripts/lib/registry-compatibility.ts:149-161, 368-370`). 넓히는 쪽과 REQUEST 행은 behavior-change다. 단위 테스트 네 방향 + 증거 요구 1건(`tests/unit/registry-compatibility.test.ts:132-184`, FE-GATE-005 28건 통과). 기준선 응답 행에 `direction`이 있어 규칙이 실제 행에 닿는다(`config/contracts/registry-baseline.json:647-655`). 매뉴얼·호환 문서·CHANGELOG가 같다(`docs/manual/01-add-a-feature.md:550`, `docs/contracts/compatibility.md:33-36`, `CHANGELOG.md:37, 64`). 완료 기준(지난 07-R1 패치에서 실패)은 수정 커밋이 "실패해야 한다"로만 적었다. 배치 07-R1에서 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:response-reader-narrowed`와 `...:ReferenceResourcePayload:...` 2줄로 registries-rc=1이었다. 변이 없는 대조는 FE-GATE-010(`compatibility=additive` PASS)이다. 행이 두 칸을 적지 않는 경로는 이 수정 범위 밖이라 새 07-02로 적었다 |
| 1103/07-04 | 제품 설정 키의 금지 이름 검사가 부팅 때만 돈다(남은 것: 부팅 오류에 키 이름이 없다) | **고쳐짐** | `assertSafeConfigNames`가 `UnsafeConfigNameError`를 던지고 `key`에 점 경로를 싣는다(`src/contracts/env.ts:125-170`). 로더가 그 경로를 `SAFE_KEY_PATTERN`으로 거른 뒤 `invalidKeys`에 넣는다(`src/bootstrap/load-runtime-config.ts:126-137`). 오류 화면이 `invalidKeys`를 "잘못된 설정 키"로 보인다(`src/presentation/boundaries/boot-error-shell.tsx:65-68`). 테스트 4건: 최상위 키, `CAPABILITY_OVERRIDES.AUTH_TOKEN`, `FEATURE_OVERRIDES.alpha.CLIENT_SECRET`, 안전하지 않은 이름은 뺌, 값은 어디에도 없음(`tests/runtime-schema/runtime-config.test.ts:297-334`, FE-GATE-004 42건 통과). 매뉴얼이 같다(`docs/manual/03-outside-feature-folder.md:113`). 한계(결함 아님): 경로가 64자를 넘으면(긴 feature id) 키 이름이 빠지고 code만 남는다. 스키마 실패의 키와 같은 규칙이다(`load-runtime-config.ts:43, 153`) |
| 1105/09-03 (영역 09, 지시로 재판정) | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | **고쳐짐** | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다(`scripts/check-registries.ts:160-168`). 완료 기준("실제 오류 클래스로 원인이 한 번")대로 테스트가 진짜 `ContractContributionError`를 던지는 source로 `check:registries`를 돌리고 원인 문자열이 한 번만 나오는지 본다(`tests/unit/registry-governance.test.ts:656-711`, `:707`의 `toHaveLength(2)`, FE-GATE-005 통과). `errors.md`의 출력 형식 줄이 실제와 같다(`docs/manual/reference/errors.md:156`). 한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다(커밋 본문). 지금 reason은 한 줄이다 |
| 1103/16-01 (영역 16, 지시로 재판정) | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다(남은 것: 읽기만 있는 기여에서 줄을 모두 빼면 통과) | **고쳐짐** | 완료 기준("줄을 지우면 `check:types` 실패"). 타입이 필수 칸이다(`src/contracts/external-contract-runtime.ts:239`, 주석 `:230-238`). `@ts-expect-error`가 줄 없는 descriptor 선언에 있고(`tests/unit/external-contract-runtime.test.ts:394-405`), FE-GATE-003(check:types:test 포함)이 통과했으니 그 지시문이 쓰였다. 즉 타입이 줄을 요구한다. repo 안 descriptor: 생성기 셋(`scripts/create-feature.ts:800`, `scripts/create-feature-write-slice.ts:275, 329`, 모두 `satisfies InstalledHttpContract`), 참조 기능 셋(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:91, 146, 197`), 테스트 fixture와 `scripts/drill-runbook.ts:290`이 값을 적는다. HTTP descriptor가 있는 기능은 참조 기능뿐이다. 생성 테스트가 세 줄을 센다(`tests/unit/create-feature.test.ts:251`). BREAKING 꼬리말·CHANGELOG 먼저 할 일 1·계약 표가 코드와 같다(`CHANGELOG.md:24, 59`). 런타임은 빠진 값을 전처럼 `NONE`으로 읽는다(`external-contract-runtime.ts:520-524, 715-716`, `src/contracts/api-operations.ts:84`). 기준선 FE-REG-API 행은 그대로다. FE-GATE-010의 `compatibility=additive`에서 바뀐 것은 `FE-REG-STORAGE:AUTH_REDIRECT_TRANSACTION:*:added` 하나뿐이다(`desktop:/tmp/claude-gates/r5/snap/merge/artifacts/quality/registries.json:7-15`, 03:54 산출물). 남은 문서 한 줄은 새 07-01로 적었다 |
틀린 발견으로 판정한 것은 없다. README §16과 다르게 판정한 것도 없다.
## 3. 이번 발견 (36.3)
새 발견 2건. 심각도 Low 2. 우선순위 P3 2. 성격 확인된 결함 1, 구조적 위험 1. High 이상과 P1은 없다. 남은 지난 발견은 없다.
### 07-01 계약 문서가 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 계약 조립이 실패한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서와 코드가 다르다. 정적 확인) |
| 관련 관점 | 20, 9, 23, 17 |
| 근거 | 계약 문서 4.1절 끝 줄: "bulk 엔드포인트를 붙이려면 `responseEnvelope`를 빼고 기능 스키마가 본문 전체를 읽는다"(`docs/architecture/backend-api-and-server-state-contract.md:205-207`). 코드: 칸은 필수다(`src/contracts/external-contract-runtime.ts:239`). 같은 기여 안에서 값이 다르면 조립이 거절한다(`:709-720`). 같은 문서의 바로 위 줄은 "이 칸은 필수라 빠뜨리면 `check:types`가 실패한다"고 적는다(`:196-198`). 매뉴얼은 "줄은 빼지 않는다"(`docs/manual/01-add-a-feature.md:214`), errors.md는 빠진 줄의 tsc 오류를 적는다(`docs/manual/reference/errors.md:109`). 이력: 그 줄은 `49a0986`(2026-11-04 20:46)이 썼다. 같은 날 22:56 `3f7e10c`(기여 하나에 응답 모양 하나)부터 맞지 않았다. `56272e8`(BREAKING)은 같은 절의 위 줄을 고쳤지만 이 줄을 남겼다. `git grep`으로 `responseEnvelope`를 빼라는 문장은 이 줄 하나다 |
| 발생 조건 | 짝 백엔드의 bulk(`results`, `BATCH_PARTIAL_FAILURE`) 엔드포인트를 Envelope 기능(생성 기능)에 붙이려고 이 문서를 따를 때 |
| 영향 | 런타임 피해는 없다. 줄을 빼면 `check:types`가 그 descriptor에서 실패한다. `"NONE"`을 적으면 조립이 `responseEnvelope NONE, but ... reads ENVELOPE_V1; ... split the contribution per backend`로 거절해 부팅과 `check:registries`가 실패한다. 오류 메시지가 "기여를 나눈다"를 말해 길은 찾을 수 있다. 같은 백엔드인데 기여를 나눠야 한다는 것은 어느 문서에도 없다. 조립은 한 기능의 기여 둘을 받는다(`tests/unit/external-contract-runtime.test.ts:377-384`, `src/features/feature-module.ts:65`) |
| 심각도·우선순위 | Low · P3 — 문서 한 줄이다. 잘못 따르면 게이트가 바로 막는다 |
| 통제·증거 | 목표 M1(안내가 타입·조립 규칙과 같다) / 확인: 이 줄은 틀림. 잘못된 시도는 타입(M4)과 조립(M4)이 막는다 · E1 |
| 확실성과 남은 가정 | 문서 문장과 타입·조립 코드를 읽어 확정했다. bulk operation을 `"NONE"` 별도 기여로 붙여 실제로 돌려 보지는 않았다 |
| 결정의 근거 | 적용 제외 — BREAKING 수정이 문서 한 줄을 놓친 단순 불일치다 |
| 이해 비용 | bulk를 붙이는 사람이 실패 두 번을 겪고 조립 오류 문구에서 방법을 읽어야 한다 |
| 최소 개선 방향 | 그 줄을 "bulk operation은 `responseEnvelope: "NONE" as const`로 적고 별도 계약 기여에 둔다. 기능 스키마가 본문 전체를 읽고 `classifyProblem`이 적용 여부를 정한다"로 고친다 |
| 대안 비교 | 적용 제외 — 바른 방법은 이미 코드와 테스트(`:377-384`)가 정한다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 한 줄 |
| 재검토 조건 | 1103/03-02(bulk 지원 여부) 결정 대기가 "지원"으로 정해지면 이 줄을 그 방법으로 바꾼다 |
| 완료 기준 | 계약 문서에 `responseEnvelope`를 빼라는 문장이 없다(`git grep`). 문서가 말하는 방법이 타입 검사와 조립을 통과한다 |
| 검증 방법 | `git grep -n 'responseEnvelope.\{0,4\}를 빼' -- docs ':!docs/reviews'` 0건. 원하면 `tests/unit/external-contract-runtime.test.ts:377-384`과 같은 꼴로 bulk 기여 하나를 조립 |
| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/16-01 수정 뒤 남은 문서) |
| 재검증 결과 | 미실시 |
### 07-02 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 아무 검사도 보지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (정적 확인. 지금 템플릿 행과 생성기가 만드는 행은 두 칸을 모두 적는다) |
| 관련 관점 | 17, 21, 10, 20 |
| 근거 | 두 칸은 타입에서 선택이다(`src/contracts/schema-registry.ts:17-18`). FE-REG-SCHEMA 필수 칸은 `schemaId`·`boundary`·`owner`·`runtime`뿐이다(`config/contracts/registry-governance.json:263`). 1103/07-03 정책 테스트는 행이 값을 적지 않으면 그 자리를 건너뛴다: 방향 `declared === undefined`(`tests/unit/schema-metadata-policy.test.ts:130`), 정책 `if (declared === undefined) return []`(`:157`). 1105/07-02 수정은 행의 값이 `REJECT_UNKNOWN`으로 바뀔 때만 등급을 매긴다(`scripts/lib/registry-compatibility.ts:149-161`). 그래서 손으로 쓴 기능이 HTTP 응답 행에 두 칸 없이 들어오면(행 추가 = additive), 뒤에 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`에는 변화가 없고 정책 테스트는 건너뛴다. 이미 적힌 칸을 지우는 것은 `field-removed` breaking이라 잡힌다(`registry-compatibility.ts:342-344`). 생성기는 두 칸을 늘 쓴다(`scripts/create-feature.ts:723-742`, `scripts/create-feature-write-slice.ts:212-221`). 매뉴얼은 "손으로 적지만 test가 실제 쓰임과 대조한다"고만 적고, 적지 않은 경우를 말하지 않는다(`docs/manual/01-add-a-feature.md:267-271`) |
| 발생 조건 | 기능 작성자가 생성기 없이 스키마 메타 행을 쓰며 두 칸을 빼고, 나중에 응답 DTO를 strict로 바꿀 때 |
| 영향 | 1105/07-02와 같다. 백엔드가 응답에 필드 하나를 더하면 그 API가 `SCHEMA_MISMATCH`로 실패한다. 1105/07-02 때와 달리 스냅샷 diff에도 아무것도 남지 않는다 |
| 심각도·우선순위 | Low · P3 — 생성기와 참조 기능은 두 칸을 적는다. 손으로 쓴 행에서 두 칸을 빼야 생긴다. 피해는 백엔드가 필드를 더한 뒤에 난다 |
| 통제·증거 | 목표 M3(HTTP 응답 경계를 좁히는 변경은 breaking이거나 테스트가 실패) / 확인: 두 칸을 적은 행 M3(1105/07-02), 적지 않은 행 M0 · E1 |
| 확실성과 남은 가정 | 코드로 확정했다. 실행하지 않았다(두 칸 없는 행을 기준선에 넣어야 해서 변이가 크다). 다운스트림 두 repo의 스키마 메타 행이 두 칸을 적는지는 보지 않았다 |
| 결정의 근거 | 기록된 결정: 1103/07-03 테스트는 "행이 적은 값"을 검증기와 대조하도록 만들어졌다(테스트 주석 `:11-24`). 적지 않은 행을 어떻게 볼지는 적혀 있지 않다. 리뷰어 판단: route 전용 행(`none`, `NotFoundSplat`)은 두 칸이 없어도 된다. HTTP 자리에 쓰인 스키마는 두 칸이 있어야 1105/07-02 규칙이 닿는다 |
| 이해 비용 | 적음. 생성기를 쓰면 생기지 않는다 |
| 최소 개선 방향 | (A) 정책 테스트에서 HTTP 자리(`slots`)에 쓰인 스키마의 행이 두 칸을 적지 않으면 실패로 센다(`:130`, `:157`의 `undefined` 분기). (B) governance가 `api-*` 경계 행에 두 칸을 필수로 둔다 |
| 대안 비교 | (A) 테스트 두 줄. 템플릿 HTTP 행은 이미 두 칸을 적어 통과한다. 기준선·governance는 그대로다. (B) 경계별 필수 칸 규칙이 governance에 없어 분류기 변경과 기준선 재승인이 필요하다. (C) 현 상태: 생성기를 쓰는 한 생기지 않는다. 손으로 쓴 행만 위험 |
| 단순화의 보존 조건 | 적용 제외 — 검사 추가다 |
| 비용·부작용 | (A) 다운스트림이 두 칸 없는 HTTP 행을 가졌다면 동기화 때 `test:unit`이 실패한다. 행에 두 칸을 적으면 된다 |
| 재검토 조건 | 검증기가 정책을 스스로 보고하게 되면(지난 라운드 07-02의 재검토 조건) 행 칸 대신 그 값을 쓴다 |
| 완료 기준 | 참조 응답 행에서 `direction`·`unknownFieldPolicy`를 지운 트리에서 `tests/unit/schema-metadata-policy.test.ts`가 실패한다 |
| 검증 방법 | 위 변이로 정책 테스트 1파일 |
| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/07-03·1105/07-02 수정이 닿지 않는 경로) |
| 재검증 결과 | 미실시 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | 적용. 조립기가 계약 규칙의 유일한 입구다 | M4 / M4 | E2(FE-GATE-005 `external-contract-runtime.test.ts` 47건) | O — 읽기 `SAFE`·`IDEMPOTENT`, 쓰기 `SAFE` 금지, 기여당 응답 모양 하나에 더해 6.1절의 "쓰기 뒤 가능" 플랫폼 code 20개를 `refusedBeforeWrite`에 적지 못한다(`external-contract-runtime.ts:638-662, 691-695`). 목록은 6.1절 표와 양방향 대조된다(`backend-contract-pin.test.ts:293-302`) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-010 `check:architecture` 통과) | O — 6.1 목록을 adapters가 아니라 contracts에 둔 이유가 커밋에 있다(조립 검사는 adapters를 import할 수 없다, `5c0b37e`) |
| **3** | 변경 용이성 | 적용. API 하나 추가·변경, pin 올리기 | M3 / M3 | E2 | O — pin을 올리는 순서가 명령 하나(`--write-excerpt`)와 매뉴얼 두 줄로 정해졌다(`docs/manual/01-add-a-feature.md:228-229`). 백엔드 생성기 템플릿 파일도 pin에 있다(`backend-contract-pin.json:8-39`, 1105/16-02) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | O — pin·답 표·사본·drift의 역할이 한 주석에 있다(`scripts/lib/backend-contract-excerpt.ts:1-11`) |
| 5 | 위험 가시성 | 적용 | M2 / M3 | E2 | O — 응답 경계를 좁히는 변경이 breaking 증거를 요구한다(1105/07-02). drift의 "비교 못 함"이 rc=2로 드러난다 |
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | O — 조립 실패 원인이 `check:registries`에 한 번 나온다(1105/09-03) |
| 7 | 운영 성숙도 | 다른 영역 | - | - | > 영역 03·13 |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2(FE-GATE-004, 005) | O — 부팅 `CONFIG_SECRET_NAME_REJECTED`가 키 경로를 싣는다(1103/07-04). drift와 pin 테스트가 어긋난 행을 문장으로 말한다 |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — 통합 때 생긴 pin·문서 어긋남은 `45c9c4d`이 고쳤다. 계약 문서 bulk 줄이 BREAKING 뒤에도 남았다(07-01) |
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-005, 07-R1·R2 변이 둘 다 기대한 이유로 실패) | P — 새 테스트: drift 9건(가짜 백엔드 git repo), pin 15건, 분류기 5건, 조립 원인 1건, 부팅 키 4건. `answerTableProblems`의 "copied and notCopied"·"stale notCopied" 두 분기는 어느 테스트도 돌지 않는다(5절). 정책 테스트가 두 칸 없는 행을 건너뛴다(07-02) |
| 11 | 데이터 성숙도 | 다른 영역 | - | - | > 영역 05 |
| 12 | 동시성 성숙도 | 적용 제외. 계약은 순수 선언과 검사다 | - | - | - |
| 13 | 확장성 | 적용 | M2 / M2 | E2(FE-GATE-020 생성 드릴) | O — 생성 기능이 `responseEnvelope`와 스키마 메타 두 칸을 적고 게이트를 통과한다 |
| 14 | 성능 성숙도 | 다른 영역 | - | - | > 영역 15. 6.1 code 검사가 초기 JS +327 B(README §16.2 D7). 조립 때 한 번 돈다 |
| **15** | 보안 성숙도 | 적용 | M4 / M4 | E2(FE-GATE-005 `rest-profile-contract`·`env-registry-coverage`) | O — 이번 diff는 CSRF·zod facade·금지 설정 키 검사를 바꾸지 않았다. 부팅 오류가 키 이름만 싣고 값은 싣지 않는다(`runtime-config.test.ts:331`) |
| 16 | 의존성 성숙도 | 다른 영역 | - | - | > 영역 13 |
| **17** | API / Contract 성숙도 | 적용 | M3 / M3(부분) | E2(FE-GATE-005·010, 07-R1·R2), E3(07-R3 실제 백엔드 checkout), E1(사본 ↔ 백엔드 대조) | P — 답 표 ↔ 사본 ↔ 프론트 표가 게이트에서 잠겼다(1105/07-01, 07-R2). 응답 축소가 breaking이다(1105/07-02, 07-R1). 사본 ↔ 실제 백엔드는 게이트 밖이고(D6), desktop에서 돌리면 일치한다(07-R3). 두 칸 없는 응답 행은 빈틈이다(07-02). bulk 안내가 틀렸다(07-01) |
| 18 | 배포 성숙도 | 다른 영역 | - | - | > 영역 13 |
| **19** | 설정 성숙도 | 적용 | M3 / M3 | E2(FE-GATE-004·005) | O — 금지 키가 `test:unit`에서 잡히고 부팅 오류가 그 키를 말한다(1103/07-04 고쳐짐) |
| **20** | 개발자 경험 | 적용 | M2 / M2 | E1 | P — drift가 매뉴얼에 있고 worktree에서도 같은 백엔드를 찾는다. bulk 안내가 두 번 실패하는 길로 보낸다(07-01) |
| **21** | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E2 | P — breaking 칸, 참조, 조립 규칙, 새 `response-reader-narrowed`가 동작한다. 검사를 약하게 한 수정은 없다(0절). 백엔드 변경 검출은 게이트 밖이다(설계). 두 칸 없는 행(07-02) |
| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | O — 표 읽기가 한 파일(`backend-contract-excerpt.ts`)에서 테스트와 drift에 같이 쓰인다 |
| **23** | 일관성 | 적용 | M2 / M2 | E1 | P — FE-REG-API와 FE-REG-SCHEMA의 경계 축소 등급이 맞춰졌다(1105/07-02). 계약 문서 한 줄이 타입·조립과 다르다(07-01). Browser RPC는 여전히 `KEYED_COMMAND`·`NON_REPLAYABLE`이다(`src/contracts/browser-rpc.ts:51-52`, 지난 라운드와 같음, 세지 않음) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | P — pin의 `sectionsCompared`는 `["1","2","4"]`인데 사본은 §2·§4만 담는다(`backend-contract-pin.json:7`, 사본 `:8-35`). §1(Envelope 키 규칙)은 code·status 행이 없어 사람이 읽고, pin 뒤 변경은 문서 전체 diff가 알린다(`check-backend-contract-drift.ts:154-158`). 계약 문서 4.1이 §1을 정본으로 적어(`backend-api-and-server-state-contract.md:166-167`) 뜻은 맞다. 발견으로 세지 않는다 |
| 25 | 조직 확장성 | 적용 | M2 / M2 | E2(`second-api-feature-registries`, FE-GATE-005) | O — 기능 팀이 governance·기준선을 고치지 않고 API를 더한다 |
| 26 | Ownership 성숙도 | 적용 | M2 / M2 | E1 | O — pin에 `owner`·`comparedOn`이 있고, 매뉴얼이 "짝 백엔드를 새로 받을 때마다" 돌린다고 정했다(`docs/manual/01-add-a-feature.md:228`) |
| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0) | O — 문서 테스트 제외 목록(`scripts/lib/removal-fixture.ts:70-81`)의 pin 테스트는 capability 드릴 셋에서만 빠진다(`:84-90`). 세 드릴이 지우는 경로(`scripts/test-realtime-runtime-removal.ts:24-34`, `scripts/test-browser-file-storage-runtime-removal.ts:29-47`, `scripts/test-optional-recipe-removal.ts:38-42`)는 pin 테스트가 읽는 `backend-envelope.ts`·`external-contract-runtime.ts`·`config/contracts/*`와 겹치지 않는다. 문서를 복사하는 참조 기능 제거·생성 드릴에서는 pin 테스트가 돈다(FE-GATE-020 로그 8회 통과, 모두 capability 드릴 앞). 제외 목록이 그 파일이 문서를 읽는지 확인한다(`tests/unit/removal-fixture.test.ts:155-163`). 개선 여지(세지 않음): 6.1 대조 하나만 다른 파일로 떼면 나머지 14건도 capability 드릴에서 돈다 |
| 28 | 회복 가능성 | 적용 제외. 계약은 복구 절차를 소유하지 않는다 | - | - | - |
X(미충족)인 관점은 없다.
## 5. 미검증
- 07-R1 패치로는 `check:registries`만 돌렸다. 그 패치에서 vitest·component·e2e는 돌리지 않았다(지난 라운드에 돌렸고 모두 통과했다. 이번 판정에는 쓰지 않는다).
- 07-R2는 사본에 행을 더한 경우만 봤다. 답 표에서 행을 지운 경우는 같은 분기(`backend-contract-excerpt.ts:146-149`)라 따로 돌리지 않았다.
- `answerTableProblems`의 "both copied and listed in notCopied"(`backend-contract-excerpt.ts:142-145`)와 "notCopied ... is not a row"(`:152-158`) 분기는 어떤 테스트도 돌지 않는다. 앞 분기는 통합 때 실제로 실패를 냈다(`45c9c4d` 본문). 코드는 맞게 읽힌다.
- 07-02 경로는 실행하지 않았다(두 칸 없는 행을 기준선에 넣는 변이가 크다).
- BREAKING 1단계가 다운스트림 descriptor에서 실제로 `check:types` 실패를 내는지: descriptor를 `satisfies`·주석 타입이 아니라 `as`로 쓰면 줄이 없어도 통과한다(TypeScript `as`는 빠진 칸을 허용한다). 그래도 런타임은 전과 같이 `NONE`이라 피해는 없다. 두 다운스트림 코드는 읽지 않았다.
- 실제 짝 백엔드를 띄워 §2·§4 답을 받아 보지 않았다.
## 6. 실행 기록
리뷰어는 아무것도 실행하지 않았다. 게이트 결과는 오케스트레이터 로그(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env)를 읽었다. 배치 요청은 `scratchpad/r5/requests/07.md`에 있다. 오케스트레이터가 `bbde570`에서 항목마다 하나씩 돌렸다(local env, 2026-11-06 04:23:23~25, load 2.92). 세 항목 모두 끝난 뒤 `restore=clean`이다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-07-R1.log`~`R3.log`다. 명령 끝이 `echo`라 항목 rc는 0이고, 판정은 `*-rc=` 줄로 했다.
| 요청 | 발견 | 명령 · env | 변이 | rc | 결과 |
|---|---|---|---|---|---|
| 07-R1 | 1105/07-02 완료 기준 | `corepack pnpm -s check:registries` · local | `requests/07-R1-strict-response.diff`(응답 DTO `.strict()` + 응답 행 둘 `REJECT_UNKNOWN`, 지난 라운드와 같은 패치) | registries-rc=1 | **잡힘(기대대로).** `Registry governance failed:` 다음에 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:response-reader-narrowed`와 `...:ReferenceResourcePayload:unknownFieldPolicy:response-reader-narrowed` 2줄. 대조는 FE-GATE-010(`11 registries PASS; compatibility=additive`) |
| 07-R2 | 1105/07-01 · `45c9c4d` | `node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts` · local | `requests/07-R2-uncopied-row.diff`(사본 §4에 `RATE_LIMIT_EXCEEDED` 429 행 추가) | vitest-rc=1 | **잡힘(기대대로).** 15건 중 "copies the answers from the backend table rows at the pin" 1건만 실패, 14건 통과. 받은 값 `["§4 429 RATE_LIMIT_EXCEEDED is neither in the answer table nor in the pin's notCopied"]`(`backend-contract-pin.test.ts:178`). 대조는 FE-GATE-005(15건 통과) |
| 07-R3 | 1105/07-01 (b) | `corepack pnpm -s check:backend-contract-drift` · local | - | drift-rc=0 | `Backend contract drift: HEAD 3d73b6f1ba82 is past the pin 45d2a478b800, docs/web/http-contract.md and 6 scaffold sources unchanged; the excerpt and the answer table match it`. 옆 checkout HEAD `3d73b6f1ba82404eeed763cabd0e688c91a44c9b`(노트북 backend checkout과 같은 커밋) |
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 07-01 | Low · P3 | 확인된 결함 | 계약 문서가 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(1103/16-01 BREAKING 뒤 남은 줄) | `docs/architecture/backend-api-and-server-state-contract.md:205-207`, `src/contracts/external-contract-runtime.ts:239, 709-720` |
| 07-02 | Low · P3 | 구조적 위험 | 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 `check:registries`·`test:unit` 어느 쪽도 보지 않는다 | `tests/unit/schema-metadata-policy.test.ts:130, 157`, `config/contracts/registry-governance.json:263`, `src/contracts/schema-registry.ts:17-18` |
@@ -0,0 +1,237 @@
# 영역 08 — presentation
> 검토일 2026-11-06 · 기준 `bbde570`(PR B `fix/maturity-review-2026-11-05-b` 끝, PR #7) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로 `src/presentation/`. 연결 확인: 참조 기능 폼 페이지(`src/features/reference-feature/presentation/`), 생성기 쓰기 슬라이스 템플릿(`scripts/create-feature-write-slice.ts`), 시각 골든(`tests/visual/__snapshots__/`), 빌드 산출의 `navigation-policy` 청크
> 깊게 본 관점 1, 6, 10, 14, 23, 24, 28
> 렌즈: 1105 조치 다섯(08-01~08-04, 1103/03-01 폼 쪽)의 완료 기준, 08-03이 더한 초기 파일, 15-05 `scrollbar-gutter`의 화면 쪽 영향, 화면을 떠났다가 돌아온 폼
> **영역 판정(35.8): 조건부 사용 가능.** 셸, 디자인 시스템, 읽기 화면, 필드 검증 400을 받는 폼, `refusedBeforeWrite`를 선언한 쓰기 폼은 쓸 수 있다. 선언한 거절은 이제 기능 문구(`refusalMessages`)로 보일 수 있다. 조건은 지난 라운드와 같다. 기능이 업무 거절 code를 모두 선언해야 한다. 선언하지 않은 code는 지금도 막다른 길이다(2절 1103/03-01). 새로 본 것: 저장 중에 화면을 떠난 경우의 결과 표시가 비어 있다(08-01, 08-02). 일반 스크롤바 데스크톱에서 열린 drawer·모달 가림막이 오른쪽 15 px를 덮지 않는다(08-03).
## 0. 결론
- **1105 새 발견 4건(08-01~08-04)은 완료 기준까지 고쳐졌다.** 근거는 `bbde570` merge 단계 로그다. 08-01의 e2e 3건이 chromium·firefox·webkit에서 통과했다(FE-GATE-008). 08-02의 생성 기능 테스트가 NEVER·KEYED 두 드릴에서 통과했다(FE-GATE-020). 08-03·08-04의 테스트가 FE-GATE-005에서 통과했다. 08-01·08-03·08-04 수정을 되돌린 변이 셋은 모두 그 테스트에서 기대한 이유로 실패했다(08-R3~08-R5).
- **1103/03-01 폼 쪽은 일부다.** 고쳐진 것: 기능이 거절 code에 자기 문구와 필드를 붙일 자리(`refusalMessages`)가 생겼다(`use-app-form.ts:50-59`, `:251-271`). 그 장치를 끄는 변이는 테스트 두 행으로 잡혔다(08-R6). 남은 것 셋: (1) 선언하지 않은 code는 거절 문구 없이 결과 불명이고, "변경됨으로 확인"이 저장되지 않은 요청을 "저장했습니다."로 바꿀 수 있다. 1103 완료 기준의 둘째 문장이 그대로 미충족이다. (2) KEYED 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`를 받아도 재전송 버튼이 남는다(결정 대기). (3) 선언한 409를 필드 오류로 바꾸는 코드가 VD-04 결정 5("409는 validation으로 바꾸지 않는다")와 이제 직접 어긋난다. README §16.5는 (2)만 적었다.
- **08-03이 더한 `navigation-policy` 청크는 사용자에게 보이는 효과가 없고, 그 자체로 결함이 아니다.** 0.37 kB(gzip) 파일 하나다. boot 청크의 정적 import라 boot의 다른 의존 22개와 같은 병렬 묶음에서 받는다. 새 요청 단계(waterfall)를 만들지 않는다. 예산은 영역 15 소관이다.
- **15-05 `scrollbar-gutter: stable`: 빈 15 px 띠 자체는 받아들일 만하다. 하지만 열린 drawer·모달의 가림막이 그 띠를 덮지 않는다.** 새 compact 골든에서 가림막은 x 0~375 px에서 끝나고, 375~390 px가 어둡게 덮이지 않은 밝은 세로 띠로 남는다. 옛 골든은 390 px까지 덮었다. 넓은 골든에서는 header의 흰 띠가 1425 px에서 끝난다. 스크롤바를 보이게 띄운 Chromium에서도 스크롤되지 않는 홈(1440 px)의 header는 1425 px에서 끝났다(08-R2). 새 발견 08-03(Low·P3)이다.
- **새 발견 3건, 모두 Low·P3.** 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다(08-01). 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다(08-02). gutter 띠를 가림막과 header가 칠하지 않는다(08-03). 08-01은 jsdom probe(08-R1), 08-02의 라우터 동작은 최소 probe(08-R7)로 실행해 확인했다.
- **약해진 검사는 없다**(2.1절). 시각 골든 5장을 다시 찍은 것은 의도한 폭 변경 때문이다. 다만 새 골든이 08-03의 띠를 그대로 고정했다.
- 이 영역 이월: 0929/08-01(locale 목록)과 0929/08-08(로그인 복귀 주소)은 남음이다. README §16.6에는 두 항목이 없다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `bbde570`(PR B 끝, PR A `a793b83` 위, main `409d72e` 위). 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`)에서 읽기만 했다. 미추적 `AGENTS.md`는 무시했다. 2026-11-06 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 pin `45d2a478`(`config/contracts/backend-contract-pin.json`) |
| 필수 요구와 규모·운영 목표 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어. 짝 백엔드 Envelope 계약. 화면 규모 목표 없음 |
| 읽은 코드·구성 범위 | `src/presentation/forms/use-app-form.ts` 전부, `form-components.tsx`(31-128행), `templates/page-templates.tsx`(60-95행), `components/async-surface.tsx`(120-240행), `adapters/query/application-query.ts`(336-460, 560-900행), `pages/home-page.tsx`, `layouts/app-shell.tsx`(190-205행), `routes/navigation-policy.ts`, `examples/platform-overview-page.tsx`(60-80, 430-485행), `styles/theme/base.css`, `primitives.css`(400-445행), `shell.css`(40-60행), `design-system/primitives/dialog.tsx`·`drawer.tsx`, `i18n/message-contract.ts`·`catalog.ts` 일부. 연결: `reference-resource-form-page.tsx` 전부, `create-feature-write-slice.ts`(615-930행), `use-dirty-navigation-guard.tsx`, `backend-envelope.ts`(140-340행), `docs/manual/02-decision-tables.md`(115-190행), VD-04. 시각 골든 5장 중 2장(`app-shell-compact-pseudo-drawer`, `app-shell-wide-light`)과 그 부모 커밋 `e02f252^`의 같은 두 장을 이미지로 비교했다. `git diff 8a44226..bbde570 -- src/presentation src/features/reference-feature/presentation scripts/create-feature-write-slice.ts tests/component tests/features tests/e2e tests/visual tests/unit/create-feature.test.ts` |
| 수행한 테스트·실험 | 직접 실행 0건. 오케스트레이터 배치 7건(08-R1~08-R7, 6절, 2026-11-06 04:33~04:34, 모두 `restore=clean`): probe 3건(08-R1 jsdom, 08-R2 Playwright Chromium 스크롤바 보이게, 08-R7 jsdom), 변이 4건(08-R3~08-R6). 게이트와 산출은 desktop 기록을 읽었다(아래) |
| 확인하지 못한 범위·이유 | 5절 |
| 이전 리뷰와 비교 가능한 범위 | `2026-11-05-maturity-review/08-presentation.md`의 08-01~08-04와 그 문서 2절의 이월 항목, README §15·§16.4~§16.6. README §16은 주장으로만 읽었다. 지난 실행 결과는 증거로 쓰지 않았다 |
실행 환경 기록(모두 `bbde570`, desktop 읽기만):
- merge 단계, CI env(`desktop:/tmp/claude-gates/bbde570-ci/summary.txt`, 03:24~03:56): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(전제 조건, 영역 12·13 소관).
- 이 영역 근거로 쓴 줄:
- FE-GATE-008(`gate-artifacts/FE-GATE-008.txt`): e2e 222 통과, 4 skipped(firefox SW 4건, 영역 06·11). `reference-save.spec.ts` 8건 × 3엔진 통과. 그중 1105/08-01 새 3건은 `:136`, `:200`, `:216`. 시각 6건 통과(새 골든).
- FE-GATE-005(`gate-artifacts/FE-GATE-005.txt`): `reference-page.test.tsx` 27(`:409`), `form-foundation.test.tsx` 34(`:432`), `example-pages.test.tsx` 4(`:469`), `starter-pages` 2, `async-surface` 35, `product-feature-switch` 4, `application-mutation-admission` 19, `layout-landmarks` 4, `create-feature.test.ts` 46, `navigation-policy.test.ts` 4, `lab-performance.test.ts` 9 모두 ✓. 전체 332 files 통과.
- FE-GATE-020(`gate-artifacts/FE-GATE-020.txt`): 생성 기능 테스트 "opens the list after the user confirms a create whose response was lost"가 test:sample-removal(NEVER, `:2189`)과 test:feature-scaffold(KEYED, `:4917`)에서 통과.
- FE-GATE-012: 초기 JS 204,158 / 206,848 gzip B, 27 / 32 파일, PASS.
- 오케스트레이터 공유 실행(`desktop:/tmp/claude-gates/r5/snap/`): `build.txt`(청크 목록, `navigation-policy-BlaVRSY7.js` 0.56 kB / gzip 0.37 kB), `base/dist/`(`index.html`, `.vite/manifest.json`), `lab.txt`(PASS, LCP 2032 ms, `/` CLS 0, 상호작용 151 ms, 기능 라우트 402 ms), `verify-documentation.*.txt`(둘 다 PASS_SCOPED).
## 2. 지난 발견 재확인
줄 번호는 `bbde570` 기준이다. 08-Rk는 6절의 배치 요청 ID다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/08-01 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 포커스가 `body`로 떨어진다 | 고쳐짐 | 폼의 포커스 effect가 직전에 그린 결과를 기억한다(`use-app-form.ts:123-135`). 결과가 상태 결과나 `effect-unknown`에서 `success`로 바뀌었고 포커스를 잃었으면(`:489-493`) feedback 자리로 옮긴다. 완료 기준(1105 08-R2의 세 경우에서 일이 끝난 뒤 포커스가 feedback 자리 안)을 e2e가 본다: `reference-save.spec.ts:136`(다시 시도), `:200`(확인), `:216`(재전송, 같은 키). 셋 다 3엔진 통과(FE-GATE-008). jsdom 3행은 `reference-page.test.tsx:550`. 처음 저장이 그냥 성공할 때는 옮기지 않는다(`previous`가 `idle`). 되돌리는 변이(08-R3, `recovered` 항상 false)는 jsdom 세 행이 `toHaveFocus`로 실패했다(3 failed / 24 passed). 다시 마운트한 폼의 확인 경로는 결과가 `success`가 되지 않아 이 장치가 걸리지 않는다. 원인이 다르다(`settleApplied`가 다시 마운트를 모름). 그래서 새 발견 08-01로 적었다 |
| 1105/08-02 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | 고쳐짐 | 확인 뒤 `settleApplied` → 목록으로 이동한다(`create-feature-write-slice.ts:724-731`). 생성 기능 테스트 한 행(`:916`)이 목록 제목과 항목, POST 1회를 본다. 두 드릴에서 통과(FE-GATE-020 `:2189`, `:4917`). 완료 기준("확인 문구가 보이거나 목록 화면")을 충족한다. 남은 위험: 짝 백엔드 생성기에는 목록 GET이 아직 없다. 실제 짝 백엔드에서는 이동한 목록이 405를 받는다(커밋 `90c489c` 본문). 이것은 1103/03-07(결정 대기)에 속한다. 새로 세지 않는다 |
| 1105/08-03 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다 | 고쳐짐 | 셸과 홈이 같은 함수 `activeNavigationRoutes`를 쓴다(`navigation-policy.ts:14-21`, `app-shell.tsx:196`, `home-page.tsx:25-29`). 렌더 때 읽는다. 테스트가 기능을 끈 홈의 시작 링크에 그 기능 라우트가 없고, 셸 탐색 앞 3개와 같은지 본다(`example-pages.test.tsx:60`, FE-GATE-005 통과). 1103/09-04의 보존 조건(홈이 기능 라우트를 이름으로 부르지 않음)은 그대로다. 되돌리는 변이(08-R4, 홈만 기능 켜짐을 보지 않음)는 그 행이 `expected true to be false`로 실패했다(1 failed / 3 passed). 초기 파일 +1은 3.0절 |
| 1105/08-04 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다 | 고쳐짐 | `otherSaveRunning`(코디네이터는 `mutation-pending`, 이 폼은 저장 중 아님)일 때 저장 버튼을 끄고(`reference-resource-form-page.tsx:60-61`, `:134`) feedback에 "변경 사항을 저장하고 있습니다."를 그린다(`:188-191`). 생성기 템플릿도 같다(`create-feature-write-slice.ts:669`, `:708`, `:737-738`). 이 폼 자신의 저장 중에는 끄지 않는다(1103/08-02 보존). 완료 기준(다시 마운트한 폼이 진행 문구를 보이거나 버튼이 꺼짐)을 `reference-page.test.tsx:592`가 본다(FE-GATE-005 통과). 생성기는 문자열만 본다(`create-feature.test.ts`). 되돌리는 변이(08-R5, `\|\| otherSaveRunning` 제거)는 그 행이 `toBeDisabled`로 실패했다(1 failed / 26 passed). 그 저장이 끝난 **뒤** 아무것도 보이지 않는 것은 새 발견 08-01이다 |
| 1103/03-01 (= 1103/08-01, 폼 쪽) | 짝 백엔드의 업무 규칙 거절 뒤 거절 이유가 안 보이고 값을 고쳐 다시 저장할 수 없다 | **일부** | **고쳐진 것.** 선언한 code의 다시 저장은 지난 라운드에 고쳐졌다. 이번에 `refusalMessages`가 생겼다. code별로 기능 catalog 키와 필드를 적으면, 적용 안 됨(`NOT_APPLIED`)으로 끝난 실패를 필드 오류(필드가 없으면 오류 요약)와 `validation-error`로 보인다(`use-app-form.ts:50-59`, `:251-271`, `:477-487`). 키 타입 `ParameterlessMessageKey`는 설치된 기능 catalog를 포함한다(`catalog.ts:1`, `message-contract.ts:47-49`). 재로그인이 먼저이고, 자기 키만 읽는다(`Object.hasOwn`). 테스트 셋(`form-foundation.test.tsx:1008`, `:1046`, `:1079`) FE-GATE-005 통과. 매뉴얼 02 4절(`02-decision-tables.md:187`). 끄는 변이(08-R6)는 `:1008`, `:1046` 두 행이 실패했고 `:1079`는 통과했다(2 failed / 32 passed). **남은 것 (1) 선언하지 않은 code.** 1103 완료 기준은 "쓰기 전으로 확인되지 않은 code는 결과 불명이지만 거절 code의 문구가 보이고, 저장되지 않은 요청을 '저장했습니다'로 바꾸는 버튼이 없다"였다. 지금은 결과 불명이면 기능 문구를 보지 않는다(`refusalFor`의 `NOT_APPLIED` 조건, `:482`). 화면은 "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인"이다. 확인하면 `settleApplied`가 "저장했습니다."로 바꾼다(`reference-resource-form-page.tsx:162-166`, `:184-185`). 테스트도 이 동작을 고정한다(`form-foundation.test.tsx:1079`). 커밋 `12d97d7` 본문은 이것을 "완료 기준의 설계"라고 적었지만 1103 완료 기준 문장과 다르다. **(2) KEYED 재전송.** `canResend`는 응답 원인을 보지 않는다(`application-query.ts:858-867`). 백엔드 표 주석은 `IDEMPOTENCY_RECOVERY_REQUIRED`를 "스스로 다시 보내지 않는다, 사용자가 데이터를 확인한다"로 적는다(`backend-envelope.ts:271-276`). README §16.5의 결정 대기 항목이다. **(3) 문서.** VD-04 결정 5는 "409 conflict는 validation으로 바꾸지 않는다"다(`VD-04-native-form-facade.md:26`). `refusalMessages`는 선언한 409(kind `CONFLICT`)를 `validation-error`로 바꾼다(`form-foundation.test.tsx:1046`이 409 행). 지난 라운드의 "문서끼리 갈림"이 이제 코드와 결정 기록의 어긋남이다. VD-04는 `8a44226..bbde570`에서 바뀌지 않았다. 남은 부분의 심각도는 지난 라운드대로 Medium·P2다((1)이 저장되지 않은 입력을 "저장했습니다."로 보이게 할 수 있다). 판정 규칙(어떤 code가 결과 불명인가)은 영역 03 소관이다 |
| 0929/03-03 (화면 쪽, 판정은 영역 03) | 결과 불명 화면의 재전송이 키 없는 쓰기에도 열린다 | 고쳐짐(유지) | 화면은 이제 코디네이터가 `true`라고 할 때만 재전송을 그린다(`async-surface.tsx:229`, 지난 라운드는 `!== false`). 손으로 만든 상태에는 재전송이 없다(`async-surface.test.tsx:130`). 훅도 키 없는 같은 입력의 재제출을 보내지 않는다(`application-query.ts:569-583`, `application-mutation-admission.test.tsx:563`). KEYED 재전송은 그대로 보인다(FE-GATE-008 `reference-save.spec.ts:216` 3엔진, 같은 키) |
| 1103/08-02~08-05 | 저장 뒤 포커스, 문구 표 `Object.prototype`, 라우트 모양 키, 422 불일치 | 고쳐짐(재발 없음) | 08-02: `use-app-form.ts:112-116`, `:285-321`, `page-templates.tsx:73-82`, FE-GATE-008 "keeps keyboard focus in the failure status"·"…in the unknown-result status" 3엔진 통과. 08-03: `form-contracts.ts:77` `Object.hasOwn`. 08-04: `deployable-app-module.ts:120-121`. 08-05: `backend-envelope.ts:219-235`. `form-contracts.ts`·`deployable-app-module.ts`·`page-templates.tsx`는 `8a44226..bbde570`에서 바뀌지 않았다. `backend-envelope.ts`는 03-01·03-02 줄만, `use-app-form.ts`는 1105/08-01과 `refusalMessages` 코드만 더해졌다 |
| 0929/08-01 | 제품이 지원 locale을 선언할 곳이 없다 | 남음 | `message-contract.ts:8-13` 고정 목록, `app-shell.tsx:85-86` 선택지에 `en-XA`·`ar-EG`. 이 기간에 바뀌지 않았다. README §16.6 목록에 없다 |
| 0929/08-08 | 로그인 복귀 주소가 라우터 기준 경로다 | 남음 | `session-provider.tsx:99` `beginSignIn(pathname + search + hash)`, `use-reference-failure-action.ts:27`. basename은 `app-router.tsx:739`. `beginSignIn(returnTo?)`(`auth-session-port.ts:38`)은 기준을 적지 않는다. README §16.6 목록에 없다 |
| 0929/08-06, 0929/08-07 | 라우트 제목 세 곳, 제품 폰트 자리 | 판정 안 함 | 지난 라운드와 같이 렌즈 밖이다. 08-06은 1103/16-06(결정 대기, 영역 16)과 겹친다 |
| 1103 3.6절 관찰 셋 | 지원 참조가 재전송마다 바뀜, `role="status"` 안의 버튼, 레이아웃 `<main tabIndex>` 미검사 | 그대로(발견 아님) | `use-app-form.ts:453-456`, `async-surface.tsx:197-239`, `layout-landmarks.test.tsx`에 `tabIndex` 단언 0건 |
### 2.1 수정이 검사를 약하게 했는가
`git diff 8a44226..bbde570`로 이 영역에 닿은 수정 커밋(`4f3c10b`, `90c489c`, `f849d78`, `f2b8ba7`, `12d97d7`, `683ccfb`, `138c195`, `e02f252`, `48c1ab7`)과 대상 테스트의 삭제 줄(`^-`)을 모두 봤다. **약해진 검사는 없다.**
| 바뀐 검사 | 판단 |
|---|---|
| `reference-page.test.tsx`, `reference-save.spec.ts`, `create-feature.test.ts`, `starter-pages`, `product-feature-switch`, `navigation-policy.test.ts` | 더하기만 했다(삭제 줄 0) |
| `form-foundation.test.tsx` 선언 목록에 `POSTER_ALREADY_EXISTS`를 더함(`:117`) | 이 목록을 쓰는 기존 행 중 이 code를 쓰는 것은 없다. 선언하지 않은 code 행(`:1079` 등)은 선언 없는 operation을 쓴다. 약해지지 않았다. 삭제 줄 `operationId: "FORM_CREATE_ENTITY"`는 `48c1ab7`(operation ID 타입 검사)의 이름 바꿈이다 |
| `async-surface.test.tsx`의 재전송 행에 `isUnknownEffectResendable: true`를 더함 | 화면 조건이 `!== false` → `=== true`로 좁아져서 필요해졌다. 반대 경우는 새 행(`:130`)이 본다. 넓어졌다 |
| `starter-platform-overview-page.test.tsx` 실패 상태 단언: 화면 전체 문구 → "빌드" 칸의 "확인하지 못했습니다." | 같은 강도다. 대기 문구가 없다는 단언도 남았다. 문구 자체에 대한 관찰은 3.5절 |
| `example-pages.test.tsx` import 줄 | `within`을 더한 것뿐이다 |
| 시각 골든 5장 다시 찍음(`e02f252`) | 의도한 폭 변경(내용 1040 → 1025 px) 때문이다. 약해진 것은 아니다. 다만 새 compact 골든은 가림막이 덮지 않는 띠를 정답으로 고정했다(08-03) |
## 3. 이번 발견 (36.3)
**새 발견 3건.** 심각도: Low 3(Critical·High·Medium 0). 우선순위: P3 3. 성격: 확인된 결함 3. 08-01은 코드 + jsdom probe(08-R1), 08-02는 템플릿 코드 + 라우터 동작 probe(08-R7), 08-03은 게이트 산출(골든) + 스크롤바를 보이게 띄운 Chromium probe(08-R2)로 확인했다.
공통: 담당·기한·상태는 `미정 · 미정 · 신규`, 재검증 결과는 `없음(신규)`이다.
### 3.0 오케스트레이터가 물은 화면 쪽 두 가지
**(가) 08-03 수정이 더한 `navigation-policy` 청크.**
- 무엇인가. `activeNavigationRoutes`(`navigation-policy.ts:14-21`)를 boot 쪽(`app-shell.tsx:196`)과 홈 라우트 청크(`home-page.tsx:25`)가 함께 import한다. 그래서 Rollup이 그 모듈을 공유 청크로 뗐다. 크기는 0.56 kB, gzip 0.37 kB다(`r5/snap/build.txt`). 내용은 `installed-feature-contracts` 청크를 import하는 함수 세 개다.
- 언제 받는가. `index.html`은 entry `index-*.js`와 `preload-helper`만 부른다. boot는 entry의 dynamic import이고, manifest에서 boot의 정적 import 목록에 이 청크가 있다(`base/dist/.vite/manifest.json`의 `src/bootstrap/boot.tsx` → `_navigation-policy-BlaVRSY7.js`, 의존 23개 중 하나). Vite preload helper는 dynamic import의 의존을 한 번에 병렬로 받는다. 그래서 이 파일은 boot의 다른 의존과 같은 묶음에서 받는다. 홈 청크가 이 파일을 다시 import할 때는 이미 받아 둔 상태다.
- 사용자에게 보이는 효과. 새 요청 단계(waterfall)는 없다. 같은 묶음에 0.37 kB 요청 하나가 늘었다. HTTP/2 정적 호스팅에서 체감할 크기가 아니다. lab(`r5/snap/lab.txt`)은 `bbde570`에서 PASS이고 LCP 2032 ms다. 이 파일 하나의 몫은 따로 재지 않았다(5절).
- 판정. 그 자체로 결함이 아니다. 셸과 홈이 한 함수를 쓰게 한 것이 08-03 수정의 핵심이고, 공유 청크는 그 결과다. 남는 것은 바이트 비용(+293 B, README §16.2 D7)이다. 그것은 영역 15가 예산으로 본다.
**(나) 15-05 `scrollbar-gutter: stable`(`base.css:6-11`).**
- 빈 15 px 띠 자체. 이 띠는 root 배경(`base.css:4` `var(--color-surface)`)으로 칠해진다. 그래서 대부분의 화면에서 오른쪽 여백처럼 읽힌다. 내용은 7.5 px 왼쪽으로 치우친다. 첫 화면에서 header 오른쪽이 15 px 밀리던 것(1105/15-05)을 없애는 대가로는 받아들일 만하다. overlay 스크롤바(휴대폰, macOS 기본)에서는 띠가 없다.
- 다만 앱이 그리는 것 중 이 띠를 칠하는 것이 없다. 가장 눈에 띄는 것은 모달 가림막이다. 새 compact 골든(`app-shell-compact-pseudo-drawer-chromium-visual-linux.png`, 390 × 1377)에서 drawer가 열린 위쪽 844 px의 가림막은 x 375 px에서 끝난다. 375~390 px는 덮이지 않은 밝은 세로 띠다. 부모 커밋의 골든(`e02f252^`, 390 × 1297)은 390 px까지 덮었다. 넓은 골든(`app-shell-wide-light…png`, 1440 × 900)에서는 header의 흰 띠와 그림자가 약 1425 px에서 끝나고, 그 오른쪽은 회색이다. 옛 골든은 1440 px까지였다. 스크롤바를 보이게 띄운 Chromium에서도 같다. 스크롤되지 않는 홈의 header 끝이 1425 px, 404 화면(390 px)은 375 px였다(08-R2). 이것이 새 발견 08-03이다.
### 08-01 다시 마운트한 참조 폼은 자기가 시작하지 않은 저장이 끝난 것을 보이지 않는다. "변경됨으로 확인"을 눌러도 결과 문구가 없고 포커스가 `body`로 간다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(코드 + jsdom 실행 08-R1) |
| 관련 관점 | 28, 24, 1, 6, 10, 22 |
| 근거 | 1105/08-04 수정 뒤 템플릿은 "저장 중에 화면을 떠났다가 같은 세션에서 돌아온 폼"을 지원 경로로 다룬다(`reference-resource-form-page.tsx:56-61` 주석, 테스트 `reference-page.test.tsx:592`). 저장 결과는 폼 인스턴스가 들고 있다(`use-app-form.ts:108-111`의 `result`·`unknownSubmissionRef`). 다시 마운트한 폼에는 둘 다 없다. 경로 둘이 비어 있다. **(1) 그 저장이 결과 불명으로 끝나고 사용자가 확인한다.** 다시 마운트한 폼에도 코디네이터의 결과 불명 화면과 "변경됨으로 확인"이 보인다(`:157-170`). 누르면 `reconcileUnknownEffect(...).then(form.settleApplied)`다(`:162-166`). `settleApplied`는 제출한 값이 없으면 아무것도 하지 않는다(`use-app-form.ts:231-235`). 같은 훅의 재전송은 다시 마운트를 따로 처리한다("After a remount the form no longer holds the submitted values", `:407-408`). 확인은 그렇지 않다. 그래서 결과가 `idle`로 남고 feedback은 `null`이다(`reference-resource-form-page.tsx:147-193`). 확인하는 동안(`RECONCILING`)에는 1105/08-04의 가지가 "변경 사항을 저장하고 있습니다."를 보인다(`:188-191`). 확인 중인데 저장 중이라고 말한다. 눌렀던 버튼이 빠지므로 포커스는 `body`로 간다. 1105/08-01의 포커스 복구는 결과가 `success`일 때만 걸린다(`use-app-form.ts:127-130`). "목록 새로 보기" 링크도 함께 사라진다(`:171-182`). **(2) 그 저장이 성공하거나 적용 안 됨으로 끝난다.** 코디네이터 표시가 `mutation-pending` → 없음으로 바뀌면 진행 문구만 사라진다. 다시 마운트한 폼의 결과는 `idle`이라 어느 가지에도 들지 않는다(`:184-193`). 400·429 같은 실패도 같다. 그 실패를 받은 폼 인스턴스는 이미 없다. 테스트 `reference-page.test.tsx:592`는 진행 문구가 사라지는 것까지 단언하고, 그 뒤 아무것도 보이지 않는 것은 보지 않는다. 생성기 템플릿은 (1)에서 목록으로 이동하므로 해당 없다(`create-feature-write-slice.ts:724-731`). (2)는 08-02와 얽힌다. **실행(08-R1, 실제 `AppRouter`·코디네이터, `createResource`만 주입).** 저장을 걸어 둔 채 "목록으로 돌아가기" → 다시 작성 화면. A(그 저장이 결과 불명): 다시 마운트한 폼에 "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인" + "같은 요청으로 다시 보내기" + "목록을 새로 불러와 확인"이 보이고 저장은 꺼져 있다. 키보드로 확인한 뒤에는 feedback 자리가 없고(`(no feedback area)`), "저장했습니다."가 없고, 포커스는 `BODY`다. 같은 이름을 다시 입력해 저장하면 `createResource`가 두 번째로 불린다(`{"name":"First item"}` × 2). B(그 저장이 성공): 진행 중에는 "변경 사항을 저장하고 있습니다."와 꺼진 저장 버튼, 끝난 뒤에는 feedback 자리가 없고 "저장했습니다."도 없다 |
| 발생 조건 | 참조 폼에서 저장을 누르고 끝나기 전에 떠났다가(저장 중에는 이탈 확인이 꺼짐, `:62`) 같은 세션에서 돌아온다. (1)은 그 저장이 결과 불명이고 사용자가 확인할 때, (2)는 그 저장이 돌아온 화면에서 끝날 때 |
| 영향 | (1) 사용자는 확인이 받아들여졌는지 화면에서 알 수 없다. 키보드 사용자는 포커스를 잃는다. (2) 저장이 됐는지, 실패했는지 알 수 없다. 사용자가 같은 항목을 다시 입력해 저장하면 새 키의 새 생성이 나간다. 앞의 저장이 됐다면 중복이다. 목록에서 보이고 지울 수 있다 |
| 심각도·우선순위 | Low · P3 — 드문 경로다. 데이터는 잃지 않고, 중복은 사용자가 다시 입력할 때만 생긴다 |
| 확실성과 남은 가정 | jsdom 실행으로 확인했다(E2, 08-R1 2 passed). 브라우저 3엔진에서는 돌리지 않았다. 실패(400·429)로 끝나는 (2)는 코드 읽기다 |
| 결정의 근거 | 적용 제외 — 같은 훅의 재전송에 있는 다시 마운트 처리가 확인 쪽에 빠진 누락과, 결과를 폼 인스턴스만 들고 있는 데서 온 빈칸이다 |
| 이해 비용 | 페이지 작성자는 폼 결과(`useAppForm`)와 코디네이터 상태(`useApplicationMutation`)를 손으로 합쳐 feedback 가지를 만든다. 다시 마운트한 경우는 두 쪽 어느 문서에도 없다 |
| 최소 개선 방향 | (1) `settleApplied`가 제출한 값이 없을 때도 결과를 `success`로 둔다(값은 지금 값). 재전송과 같게 한다. 그러면 1105/08-01의 포커스 복구도 걸린다. (2) 코디네이터가 마지막으로 끝난 시도의 결과(성공·적용 안 됨)를 채널에 남기고, 다시 마운트한 폼이 그것을 보인다. 또는 진행 문구 자리에 "목록에서 저장 여부 확인" 링크를 둔다 |
| 대안 비교 | (2)는 선택이 있다. 채널에 결과를 남기면 정확하지만 코디네이터 계약이 넓어진다. 링크만 두면 작지만 결과를 말하지 않는다. 지난 라운드 3.5절의 (B)(`useAppForm`이 코디네이터 상태를 받아 결과를 하나로 낸다)가 두 경로를 함께 줄인다 |
| 단순화의 보존 조건 | 처음 저장이 그냥 성공할 때 포커스를 옮기지 않는다. 이 폼 자신의 저장 중에는 저장 버튼을 끄지 않는다(1103/08-02). 키 없는 결과 불명에 재전송 없음(0929/03-03) |
| 비용·부작용 | (1)은 몇 줄과 테스트 한 행. (2)는 코디네이터 상태 칸 하나와 페이지 가지 하나 |
| 재검토 조건 | 코디네이터가 시도 결과를 보존하는 계약을 갖게 될 때 |
| 완료 기준 | 08-R1의 A에서 확인 뒤 "저장했습니다."가 보이고 포커스가 feedback 자리 안이다. B에서 그 저장의 결과(또는 목록 확인 안내)가 보인다 |
| 검증 방법 | 08-R1 probe의 두 행을 `reference-page.test.tsx`에 넣는다 |
### 08-02 생성 기능 작성 폼은 사용자가 저장 중에 화면을 떠나도, 저장이 끝나면 앱을 그 항목의 상세 화면으로 옮긴다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(템플릿 코드 + 라우터 동작 실행 08-R7) |
| 관련 관점 | 1, 23, 28, 10, 20 |
| 근거 | 생성기 템플릿의 작성 폼은 `submit`이 저장을 기다린 뒤 `openSaved(outcome)`을 부른다(`create-feature-write-slice.ts:649-655`). `openSaved`는 성공이면 `navigate(상세)`다(`:636-647`). 그 사이에 화면이 남아 있는지 보지 않는다. 저장 중에는 이탈 확인이 꺼져 있어(`useDirtyNavigationGuard(form.dirty && !form.pending)`, `:670`) 사용자는 저장 중에 다른 화면으로 갈 수 있다. 1105/08-04 수정은 그렇게 떠났다가 돌아온 폼을 지원 경로로 다룬다(`:666-669` 주석). 참조 폼은 저장 성공 때 이동하지 않고 "저장했습니다."를 보인다(`reference-resource-form-page.tsx:184-185`). 그래서 이 문제는 생성기에만 있다. 생성 기능 테스트는 저장 중 이탈을 돌리지 않는다(`:749-930`의 행 목록). 이 앱은 데이터 라우터(`createBrowserRouter`, `app-router.tsx:749`)다. **실행(08-R7).** 같은 순서(저장을 기다린 뒤 `navigate(상세)`)의 최소 페이지를 이 repo의 react-router 7.18.1 데이터 라우터(`createMemoryRouter`)에 올렸다. 저장을 건 뒤 다른 라우트로 가고 저장을 끝내면, 위치가 `/items/created`가 된다(`08-R7 after=/items/created`). 언마운트된 화면의 `navigate`도 앱을 옮긴다 |
| 발생 조건 | 생성 기능에서 저장을 누르고 끝나기 전에 목록이나 다른 기능 화면으로 간다. 저장이 성공한다. 다시 돌아온 작성 폼(1105/08-04 경로)에 입력이 있으면 `useBlocker`(`use-dirty-navigation-guard.tsx:9`)가 이 이동을 막고 이탈 확인 창을 띄운다 |
| 영향 | 사용자가 요청하지 않은 화면 이동이 생긴다. 다른 기능에서 작업 중이면 그 화면을 떠난다. 다시 돌아온 작성 폼에서 입력 중이면 이유 없는 이탈 확인 창이 뜬다. 데이터는 잃지 않는다(이탈 확인이 입력을 지킨다) |
| 심각도·우선순위 | Low · P3 — 저장 중에 떠나는 드문 경로다. 이동한 화면은 방금 만든 항목이라 혼란은 짧다 |
| 확실성과 남은 가정 | 템플릿 문자열(E1)과 라우터 동작 실행(E2, 08-R7)으로 확인했다. 생성한 기능 자체로는 돌리지 않았다. `createBrowserRouter`와 `createMemoryRouter`는 같은 `useNavigate` 경로를 쓴다고 보았다(추론). 다시 돌아온 작성 폼에서 이탈 확인 창이 뜨는 것은 코드 읽기다. 파일이 `scripts/`라 영역 16과 겹칠 수 있다. 합칠 때 하나로 센다 |
| 결정의 근거 | 적용 제외 — 저장 뒤 이동이 "사용자가 아직 그 화면에 있다"는 전제를 확인하지 않은 누락이다 |
| 이해 비용 | 필요한 범위만 |
| 최소 개선 방향 | 이동 전에 이 화면이 아직 마운트되어 있는지(또는 현재 위치가 작성 라우트인지) 본다. 떠난 뒤 끝난 저장은 08-01 (2)처럼 결과를 남기는 쪽으로 보인다 |
| 대안 비교 | 적용 제외 |
| 단순화의 보존 조건 | 작성 폼에 남아 있는 사용자는 저장 뒤 상세로 간다. 확인 뒤 목록으로 간다(1105/08-02) |
| 비용·부작용 | 템플릿 몇 줄, 생성 기능 테스트 한 행 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 생성 기능 테스트에서 저장 중에 목록으로 간 뒤 저장이 끝나도 위치가 목록이다 |
| 검증 방법 | `renderCreatePageTest`(`create-feature-write-slice.ts:749-`)에 한 행. `test:feature-scaffold`·`test:sample-removal`이 생성 결과로 돈다 |
### 08-03 `scrollbar-gutter: stable`이 잡은 오른쪽 15 px 띠를 앱이 칠하지 않는다. 열린 drawer·모달의 가림막이 그 띠를 덮지 않고, 짧은 화면에서 header 띠가 15 px 앞에서 끝난다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(게이트 산출의 골든 + 스크롤바를 보이게 띄운 Chromium 실험 08-R2) |
| 관련 관점 | 1, 23, 10, 5 |
| 근거 | `:root`에 `scrollbar-gutter: stable`이 있다(`base.css:6-11`, 1105/15-05 수정 `e02f252`). 문서가 스크롤되지 않아도 오른쪽에 스크롤바 폭(15 px)이 늘 잡힌다. 그 자리는 root 배경(`base.css:4`)으로만 칠해진다. 고정 위치 요소와 top layer의 `::backdrop`은 viewport 기준이라 그 띠 안쪽에서 끝난다. drawer는 `showModal()` dialog이고(`dialog.tsx:61`, `drawer.tsx:22-33`) 가림막은 `.ui-dialog::backdrop`이다(`primitives.css:416-419`). header는 본문 안의 sticky 띠다(`shell.css:45-57`). **골든.** 새 compact 골든(390 px 창, drawer 열림)에서 가림막은 x 375 px에서 끝나고 375~390 px에 덮이지 않은 밝은 띠가 위에서 844 px까지 남는다. 부모 커밋 골든은 끝까지 덮었다. 넓은 골든(1440 px)에서는 header의 흰 띠가 약 1425 px에서 끝난다(3.0절 (나)). 이 골든을 찍는 Chromium은 `--hide-scrollbars`인데도 gutter를 잡는다(`e02f252` 본문). 그래서 골든 속 띠는 늘 비어 있다. **실험(08-R2, `--hide-scrollbars`를 뺀 Chromium).** 홈 1440 × 900: 스크롤되지 않고(`scrolls:false`) header 오른쪽 끝이 1425 px다(창 1440 px). 404 화면 390 × 844 + drawer: 스크롤되지 않고 header 끝이 375 px다. 띠 안(x 385)의 hit test는 dialog가 아니다(`null`). 홈 390 × 844 + drawer: 스크롤되므로 스크롤바가 띠를 채운다(`clientWidth` 375). x 370은 dialog, x 385는 스크롤바(`null`)다. 커밋 본문은 "열린 drawer의 가림막은 gutter를 덮지 않는다"를 위험으로 적었다. 제품이 읽는 문서(CHANGELOG `:81`, `performance-evidence.md:125-129`)에는 내용 폭 15 px만 있고 가림막·header 이야기는 없다 |
| 발생 조건 | 일반(overlay가 아닌) 스크롤바 브라우저(Windows·Linux의 Chrome·Edge 기본, macOS에서 마우스 연결 시)에서 문서가 창보다 짧을 때. 그때 띠는 비어 있다. 문서가 스크롤되면 그 자리에 스크롤바가 그려지고 가림막이 스크롤바를 덮지 않는 것은 전과 같다. 휴대폰(overlay)은 해당 없다. 오른쪽에 붙는 drawer(`ui-drawer--end`, `primitives.css:434-436`, RTL의 start 포함)는 창 끝과 drawer 사이에 15 px 틈이 생길 수 있다(미확인) |
| 영향 | 모달·drawer가 열렸을 때 오른쪽 끝에 흐리게 덮이지 않은 밝은 띠가 남는다. header 띠가 창 끝까지 가지 않는다. 기능 영향은 없다. 시각 계약(골든)이 이 모습을 정답으로 고정해서 다음 변경도 이 띠를 기준으로 잰다. compact 골든은 실제 휴대폰보다 15 px 좁은 배치를 그린다(`e02f252` 본문도 적음) |
| 심각도·우선순위 | Low · P3 — 보기 문제이고 짧은 화면·일반 스크롤바에서만 보인다 |
| 확실성과 남은 가정 | 빈 띠와 header가 앞에서 끝나는 것은 스크롤바를 보이게 띄운 Chromium 실험으로 확인했다(E3, 08-R2). 가림막이 띠를 칠하지 않는 것은 골든 이미지로 확인했다(E2, FE-GATE-008 시각 6건이 새 골든으로 통과). 08-R2의 hit test(`null`)는 이것과 맞지만, 띠 자리가 원래 hit test를 받지 않을 수 있어 칠함의 증거로는 쓰지 않는다. probe 스크린샷은 받지 못했다. Firefox·WebKit은 보지 않았다 |
| 결정의 근거 | 15-05의 선택(첫 화면 15 px shift 대신 상시 gutter)은 커밋 본문에 근거가 있다. 그 선택 자체는 유지할 만하다(3.0절). 이 항목은 그 선택이 만든 빈칸을 앱이 메우지 않은 것이다. 확인된 사실: 골든 두 장의 차이, CSS 위치. 리뷰어 추론: 일반 스크롤바 브라우저에서 골든과 같은 모습 |
| 이해 비용 | 제품 작성자는 CHANGELOG만 보면 폭 15 px 변화만 안다. 모달 가림막이 띠를 덮지 않는다는 것은 커밋 본문에만 있다 |
| 최소 개선 방향 | 가림막이 창 전체를 덮게 한다(예: `.ui-dialog::backdrop`의 폭을 창 폭으로). 일반 스크롤바 Chromium에서 확인한다. header 띠는 받아들이고 디자인 문서에 적거나, root 배경을 header와 맞추는 것을 검토한다 |
| 대안 비교 | (가) 지금대로 두고 문서에 적는다: 비용 0, 띠는 남는다. (나) 가림막만 넓힌다: 작고 가장 눈에 띄는 것을 없앤다. 스크롤되는 화면에서 가림막이 스크롤바 위로 그려지는지는 확인이 필요하다. (다) `scrollbar-gutter`를 거두고 첫 화면 shift를 다른 방법(로딩 화면 높이)으로 없앤다: 15-05를 다시 여는 큰 변경이다. (라) `html { overflow-y: scroll }`: 커밋이 버린 대안. 빈 스크롤바 트랙이 늘 그려지고 가림막 문제는 같다 |
| 단순화의 보존 조건 | 첫 화면 header shift 0(lab `/` CLS 0, `lab.txt`). `:root` `scrollbar-gutter` 단위 테스트(`lab-performance.test.ts:132`) |
| 비용·부작용 | (나)는 CSS 몇 줄과 골든 1장 다시 찍기 |
| 재검토 조건 | 브라우저 기본이 overlay 스크롤바로 바뀌거나, 시각 게이트가 스크롤바를 보이게 찍게 될 때 |
| 완료 기준 | drawer를 연 compact 골든에서 가림막이 390 px까지 덮는다. 스크롤바를 보이게 띄운 Chromium의 스크롤되지 않는 화면에서도 같다 |
| 검증 방법 | 시각 골든 다시 찍기. 08-R2 probe를 스크롤바가 보이는 시각 테스트(스크린샷 비교)로 남긴다. hit test는 띠 자리에서 늘 `null`일 수 있어 기준으로 쓰지 않는다 |
### 3.5 발견으로 올리지 않은 관찰
- **플랫폼 구성 화면의 실패 문구(15-01 수정의 화면 쪽).** 릴리스 정보를 읽지 못하면 전에는 "상태: 런타임 정보를 확인하지 못했습니다." 한 칸이었다. 지금은 "빌드: 확인하지 못했습니다."와 "릴리스: —", "설정 스키마: — / —", "계약 집합 다이제스트: — / —"다(`platform-overview-page.tsx:69-78`, `:475-482`). 칸 수를 맞춰 자리를 지키려는 수정(15-01)이다. 읽는 사람은 "빌드만 확인하지 못했다"로 읽을 수 있다. 예제 화면이고 정보를 숨기지 않아 결함으로 보지 않았다.
- **`refusalMessages`에 적고 `refusedBeforeWrite`에 적지 않은 code.** 그 문구는 보이지 않고 결과 불명이 된다(`use-app-form.ts:482`, 테스트 `form-foundation.test.tsx:1079`가 이것을 고정). 안전한 쪽으로 닫힌다. 둘을 맞추는 검사는 없다. 매뉴얼은 둘을 같은 절에 적었다(`02-decision-tables.md:180-187`).
- **오류 요약만으로 보이는 거절.** `refusalMessages`에 필드가 없으면 오류 요약(`role="alert"`)에만 보이고 포커스는 저장 버튼에 남는다(`use-app-form.ts:262-269`). 클라이언트 검증의 폼 오류와 같은 동작이다.
- **띠가 비어 있을 때 `documentElement.clientWidth`.** 08-R2에서 스크롤되지 않는 화면은 `clientWidth`가 창 폭(1440, 390)이었다. 실제 배치 폭은 1425, 375다(header 끝). 스크롤되는 화면은 375였다. `src/`에 `clientWidth`·`innerWidth`를 쓰는 코드는 없어 지금은 영향이 없다(`git grep` 0건). 이 때문에 08-R2의 "띠 왼쪽" hit test 지점이 띠 안에 떨어져 probe 3건 중 2건이 가설 단언에서 실패했다(6절).
- **포커스를 받는 feedback 자리에 역할·이름이 없다**(`page-templates.tsx:73-82`). 1105/08-01 수정으로 이 자리가 포커스를 받는 경우가 늘었다. 지난 라운드 관찰 그대로, 미검증(5절).
- **반복 원인.** 이번 08-01·08-02와 지난 라운드 08-01·08-02·08-04는 같은 자리에서 났다. 저장 결과는 폼 인스턴스(`useAppForm`)가 들고, 진행·결과 불명은 코디네이터가 든다. 페이지가 둘을 손으로 합치고, 참조 폼과 생성기가 그 합치기를 따로 복사한다. 이번 수정 넷은 각 가지를 메웠지만 이 구조는 그대로다(`12d97d7` 본문도 (B)를 미뤘다고 적음).
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| **1** | 코드 성숙도 | 적용 | M3 / M3 | E2 | P — 1105 08-01~08-04 고쳐짐(완료 기준, 게이트 통과). 새로: 다시 마운트한 폼의 결과 표시 빈칸(08-01), 떠난 뒤의 상세 이동(08-02), gutter 띠(08-03) |
| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-010 통과. 셸과 홈의 "켜진 탐색 라우트"가 한 함수다(`navigation-policy.ts:14-21`). presentation이 HTTP를 직접 모른다 |
| 3 | 변경 용이성 | 적용 | M3 / M1 | E1 | P — locale 목록이 셸에 박혀 있다(0929/08-01 남음) |
| 4 | 인지 부하 | 적용 | — | E1 | P — 거절 뒤 화면을 알려면 `refusedBeforeWrite` → status별 kind → `refusalMessages` → 폼 분기 → 페이지 feedback 가지를 읽는다. 매뉴얼 02 4절이 이제 `refusalMessages`까지 적는다(`:187`). 다시 마운트한 폼의 경로는 어디에도 없다(08-01) |
| 5 | 위험 가시성 | 적용 | M2 / M1 | E1 | P — gutter가 가림막을 덮지 않는다는 위험이 커밋 본문에만 있다(08-03). 선언하지 않은 code가 "저장했습니다."가 될 수 있다는 것은 매뉴얼에 있다(`02-decision-tables.md:180`) |
| **6** | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 거절은 기능 문구로 보이고 다시 저장된다(`form-foundation.test.tsx:1008`). 선언하지 않은 code와 `RECOVERY_REQUIRED` 뒤 재전송은 막다른 길이다(1103/03-01 남음). 떠난 사이 끝난 저장의 실패가 사라진다(08-01) |
| 7 | 운영 성숙도 | > | — | — | 영역 09·13 |
| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2 | P — 상태 실패와 결과 불명에 지원 참조가 있다. `refusalMessages`로 보인 거절은 `validation-error`라 지원 참조가 없다(`use-app-form.ts:453-456`). 고칠 수 있는 입력이라 문제로 보지 않는다 |
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P — `application-query.ts` 1,026줄(지난 1,004줄), `use-app-form.ts` 516줄. LEGACY 분기 그대로 |
| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 1105 수정 넷과 `refusalMessages`에 테스트가 붙었다. 되돌리는 변이 넷이 모두 기대한 테스트에서 기대한 이유로 실패했다(08-R3~08-R6). 다시 마운트한 폼의 끝(08-01), 저장 중 이탈(08-02)을 보는 테스트가 없다. 시각 게이트는 스크롤바를 숨긴 채 gutter 띠를 정답으로 고정했다(08-03) |
| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 |
| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O — 다른 저장이 진행 중이면 저장 버튼이 꺼지고 진행 문구가 보인다(1105/08-04). 키 없는 같은 입력 재제출은 훅이 막는다(`application-query.ts:569-583`). 중복 제출은 폼이 막는다(`use-app-form.ts:385-386`) |
| 13 | 확장성 | > | — | — | 영역 09·15·16 |
| **14** | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-012 PASS(204,158 / 206,848 B, 27 / 32 파일). lab PASS, `/` CLS 0(일반 스크롤바, `lab.txt`). 08-03 공유 청크는 같은 병렬 묶음이라 새 단계가 없다(3.0절). 예산 판단은 영역 15 |
| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | P — 백엔드 message를 그리지 않는다. `refusalMessages`는 기능 catalog 키만 받고 자기 키만 읽는다(`use-app-form.ts:484`). 로그인 복귀 주소(0929/08-08) 남음 |
| 16 | 의존성 성숙도 | > | — | — | 영역 13 |
| 17 | API / Contract 성숙도 | 적용 | M3 / M2 | E1 | P — `refusalMessages`가 선언한 409를 필드 오류로 바꿔 VD-04 결정 5와 어긋난다(1103/03-01 남음 (3)) |
| 18 | 배포 성숙도 | 적용 | M3 / M2 | E1 | O — 08-03 청크는 boot 의존이라 청크 복구 경계(라우트 쪽)와 상관없이 boot와 함께 받는다. SW 캐시 대상 목록은 영역 06 |
| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 0929/08-01 남음 |
| 20 | 개발자 경험 | 적용 | — | E2 | P — 기능 거절 문구 자리가 생겼다(`refusalMessages`, 매뉴얼). 생성기 작성 폼이 저장 중 이탈을 고려하지 않는다(08-02) |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | O — 키 없는 재전송을 화면(`=== true`)과 훅이 둘 다 막는다. `refusalMessages`는 결과 불명에 쓰이지 않는다(안전한 쪽). `refusalMessages`와 `refusedBeforeWrite`를 맞추는 검사는 없다(3.5절, 안전한 쪽으로 닫힘) |
| 22 | 추상화 성숙도 | 적용 | — | E1 | P — 저장 결과가 폼 인스턴스에만 있고 페이지가 코디네이터 상태와 손으로 합친다. 지난 라운드 08-01·08-02·08-04에 이어 이번 08-01·08-02도 같은 자리에서 났다(3.5절) |
| **23** | 일관성 | 적용 | — | E2 | P — 셸과 홈이 같은 탐색 목록을 쓴다(고쳐짐). 참조 폼은 저장 뒤 이동하지 않고 생성 폼은 떠난 뒤에도 이동한다(08-02). 재전송은 다시 마운트를 처리하고 확인은 하지 않는다(08-01) |
| **24** | 네이밍 / 의미 성숙도 | 적용 | — | E1 | P — 다시 마운트한 폼에서 확인 중에 "변경 사항을 저장하고 있습니다."(08-01). 선언하지 않은 거절이 "저장했습니다."가 될 수 있다(1103/03-01 남음). 플랫폼 구성 화면 실패가 "빌드" 칸 값으로 보인다(3.5절) |
| 25 | 조직 확장성 | 적용 | — | E1 | P — 기능 거절 문구는 이제 기능 catalog에 둔다. 필드 문구 표(`form-contracts.ts`)와 locale 목록은 여전히 템플릿 파일이다 |
| 26 | Ownership 성숙도 | 적용 | — | E1 | ? — 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`) |
| 27 | 삭제 가능성 | > | — | — | 영역 09·16. 홈 시작 링크 테스트는 예제 기능 테스트 폴더에 있어 기능과 함께 지워진다(`example-pages.test.tsx:57-60`) |
| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 복구 버튼 뒤 포커스가 feedback 자리로 간다(3엔진). 다시 마운트한 폼의 확인은 결과도 포커스도 남기지 않는다(08-01). 선언하지 않은 거절은 거짓 성공 버튼과 끝나지 않는 재전송이 남는다(1103/03-01 남음) |
## 5. 미검증
- **08-01·08-02의 브라우저 실행.** 08-01은 jsdom(08-R1), 08-02는 최소 페이지의 jsdom(08-R7)만 돌렸다. 생성한 기능으로 저장 중 이탈을 돌리지 않았다.
- **08-03의 가림막 칠함(스크롤바 보임).** 08-R2의 스크린샷을 받지 못했다. 가림막이 띠를 칠하지 않는 것은 `--hide-scrollbars` 골든으로만 봤다. 띠 자리의 hit test `null`은 칠함의 증거가 아니다.
- **실제 스크린 리더.** 포커스를 받는 feedback 자리(역할·이름 없음)와 그 안의 `role="status"`가 겹쳐 두 번 읽히는지 확인하지 않았다. 수동 접근성 기록 10건은 모두 `pending-manual-review`다.
- **일반 스크롤바의 Firefox·WebKit, RTL drawer.** 08-03은 Chromium 골든과 08-R2(Chromium)만 본다. RTL에서 오른쪽에 붙는 drawer와 창 끝 사이 틈은 확인하지 않았다.
- **생성기로 만든 기능.** 생성 명령을 직접 돌리지 않았다. FE-GATE-020 로그로 생성 테스트 통과만 읽었다. 08-02는 템플릿 문자열을 읽었다.
- **짝 백엔드.** 실제로 띄우지 않았다. 1105/08-02 뒤 목록 405(1103/03-07)는 커밋 본문의 주장이다.
- **08-03 청크의 시간 몫.** lab은 전체만 잰다. 이 파일 하나의 몫을 재지 않았다.
- **영역 밖 게이트 실패.** FE-GATE-013 rc=1(전제 조건). 이 영역 판정에 쓰지 않았다.
## 6. 실행 기록
리뷰어가 직접 돌린 실행은 0건이다. 노트북에서는 읽기와 `git show`·`git diff`·`git log`·`git grep`, 그리고 상태를 바꾸지 않는 `git apply --check`(요청 패치 확인)만 했다. 부모 커밋 골든 두 장은 `git show e02f252^:<경로>`로 scratchpad에 꺼내 이미지로 읽었다. desktop에서는 `/tmp/claude-gates/` 아래 파일을 `cat`·`grep`·`ls`·`sed`로 읽었다. **규칙에서 벗어난 것 하나:** `base/dist/.vite/manifest.json`에서 `navigation-policy` 청크를 import하는 항목을 찾으려고 desktop에서 `python3 -c`로 그 JSON을 읽기 전용으로 한 번 파싱했다. 파일을 쓰거나 checkout에 닿지 않았다.
요청 파일: `scratchpad/r5/requests/08.md`, 패치: 같은 폴더의 `08-R*.diff`. 모두 깨끗한 `bbde570`에 `git apply --check`로 붙는다. 아래는 오케스트레이터가 한 배치로 하나씩 돌린 결과다(`desktop:/tmp/claude-gates/r5/batch/out/R5-08-R*.log`, 2026-11-06 04:33~04:34, 부하 2.4~3.5, env local). 매 항목 뒤 checkout을 되돌렸고 모두 `restore=clean`이다.
| ID | 명령 | 변이 | rc·시간 | 결과 |
|---|---|---|---|---|
| 08-R1 | `node scripts/run-vitest.ts run tests/features/reference-feature/probe-08-r5-remount.test.tsx` | probe 파일 추가 | 0 · 3초 | 2 passed. 가설대로다. A2 `{"feedback":"(no feedback area)","saved":false,"active":"BODY"}`, A3 `creates=2`, B2 `{"feedback":"(no feedback area)","saved":false}`. 관찰은 08-01 근거 칸. stderr 한 줄은 probe가 `pushState`로 돌아올 때의 react-router 경고다(repo 테스트 `reference-page.test.tsx:592`와 같은 방식) |
| 08-R2 | `corepack pnpm exec playwright test tests/e2e/probe-08-r5-gutter.spec.ts --project=chromium --reporter=list` | probe spec 추가(`--hide-scrollbars` 뺌) | 1 · 8초(빌드 제외) | 1 passed / 2 failed. 측정값: wide-home `{"innerWidth":1440,"clientWidth":1440,"scrolls":false,"headerRight":1425,"hitInGutter":null,"hitLeftOfGutter":null}`; compact-drawer-not-found `{"innerWidth":390,"clientWidth":390,"scrolls":false,"headerRight":375,"hitInGutter":null,"hitLeftOfGutter":null}`; compact-drawer-home `{"clientWidth":375,"scrolls":true,"headerRight":375,"hitInGutter":null,"hitLeftOfGutter":"DIALOG.ui-dialog"}`. 실패 둘은 probe 설계 탓이다. 띠가 비어 있으면 `clientWidth`가 창 폭이라 `clientWidth < innerWidth` 단언과 "띠 왼쪽"(x = clientWidth − 5) 지점이 틀렸다. header 끝(1425, 375)이 띠를 보여 준다. 스크린샷은 복사되지 않았다 |
| 08-R3 | `node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx` | `use-app-form.ts:128` `recovered` 항상 false | 1 · 20초 | 기대대로. 3 failed / 24 passed: "keeps focus in the feedback after '변경됨으로 확인' / '같은 요청으로 다시 보내기' / '다시 시도' from the keyboard", `expect(element).toHaveFocus()` |
| 08-R4 | `node scripts/run-vitest.ts run tests/features/platform-examples-feature/example-pages.test.tsx` | `home-page.tsx:26` 기능 켜짐을 보지 않음 | 1 · 1초 | 기대대로. 1 failed / 3 passed: "leaves this feature's screens out of the home page's starter links when it is switched off", `expected true to be false` |
| 08-R5 | `node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx` | `reference-resource-form-page.tsx:134` `\|\| otherSaveRunning` 제거 | 1 · 5초 | 기대대로. 1 failed / 26 passed: "says a save is running and keeps the save off after coming back during a save", `expect(element).toBeDisabled()` |
| 08-R6 | `node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx` | `use-app-form.ts:484` 기능 문구를 찾지 않음 | 1 · 12초 | 기대대로. 2 failed / 32 passed: "shows the feature's words for a declared refusal on its field and saves again", "shows a declared refusal without a field in the error summary", `expect(element).toHaveTextContent()`(결과가 `validation-error`가 아님). "keeps an undeclared refusal unknown …"는 통과 |
| 08-R7 | `node scripts/run-vitest.ts run tests/component/probe-08-r5-navigate-after-unmount.test.tsx` | probe 파일 추가 | 0 · 1초 | 1 passed, `08-R7 after=/items/created`. 가설대로다 |
변이 없는 대조는 게이트 출력이다: `reference-page.test.tsx`·`form-foundation.test.tsx`·`example-pages.test.tsx`는 FE-GATE-005(`FE-GATE-005.txt:409`, `:432`, `:469`) 통과. 변이 넷 모두 변이 없는 실행은 통과, 변이 실행은 기대한 테스트가 기대한 이유로 실패했다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 08-01 | Low · P3 | 확인된 결함(jsdom 실행 08-R1) | 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다. "변경됨으로 확인" 뒤 결과 문구가 없고 포커스가 `body`다 | `src/presentation/forms/use-app-form.ts:231-235` vs `:402-408`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:147-193` |
| 08-02 | Low · P3 | 확인된 결함(템플릿 코드 + 라우터 동작 08-R7) | 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다 | `scripts/create-feature-write-slice.ts:636-655` |
| 08-03 | Low · P3 | 확인된 결함(골든 + 08-R2) | `scrollbar-gutter: stable`의 15 px 띠를 drawer·모달 가림막과 header가 칠하지 않는다. 새 골든이 이 띠를 고정했다 | `src/presentation/styles/theme/base.css:6-11`, `primitives.css:416-419`, `shell.css:45-57`; `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png` |
이월(새로 세지 않음): 1103/03-01(= 1103/08-01) 폼 쪽 일부(Medium·P2), 0929/08-01 남음, 0929/08-08 남음.
@@ -0,0 +1,162 @@
# 영역 09 — 애플리케이션 코어·기능·조립
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`. 판정에 필요한 만큼 `recipes/session-owners/`, `tests/unit/product-extension-typecheck.test.ts`, `scripts/check-registries.ts`, `src/contracts/server-state.ts`(1103/16-05), `src/adapters/query-cache/server-state-scope-runtime.ts`(1105/02-01 조립 쪽), `CHANGELOG.md` 첫 절, `docs/manual/{01,02,03,04}*.md`도 읽었다.
> 깊게 본 관점: 3, 10, 17, 20, 21, 25
> 렌즈: 1105 수정 셋(09-01·09-02·09-03)과 1103 이월 셋(09-03·09-04·09-05)이 완료 기준까지 갔는가. 그 수정이 검사를 약하게 하거나 다른 결함을 만들었는가. 1103/16-05 BREAKING(`48c1ab7`)의 코드가 커밋 꼬리말·CHANGELOG 안내와 같은가. 1105/02-01이 바꾼 제품 scope participant 조립이 맞는가.
> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드의 이 영역 결함 셋(09-01·09-02·09-03)은 코드와 테스트로 닫혔다. 1103/16-05도 닫혔다. 조건은 셋이다. (1) 짝 백엔드 실제 연동은 아무도 확인하지 않았다. realm public client와 Redis 모드 로그인 엔드포인트는 제품 몫이다(1103/09-03 일부, 백엔드로 넘김). (2) 플랫폼 구성 화면은 끌 수 없고, 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04, 결정 대기). SW 활성화 화면을 이을 제품 소유 자리가 없다(1103/09-05 일부). (3) 쿠키 세션 제품은 `onCredentialRejected` 한 줄을 직접 잇는다. 빠뜨리면 막는 검사가 없다(`CHANGELOG.md:107`).
## 0. 결론
- 지난 라운드 이 영역 발견: 1105 셋은 고쳐짐 3(09-01, 09-02, 09-03). 1103 이월 셋은 일부 3(09-03, 09-04, 09-05). 이 영역에 요청된 1103/16-05는 고쳐짐. 0925 이월 둘은 일부 1(FOLLOW-UP 09-07), 남음 1(FOLLOW-UP 09-08, 허용한 대안). 재발·틀린 발견은 없다. README §16과 다르게 본 것은 없다(1103/09-03의 §16.5 "백엔드로 넘김"은 남은 것이 백엔드 쪽이라는 뜻이라 "일부"로 적었다).
- 1105/09-01: 탐침이 제품 파일을 옆 이름으로 옮기고 그 위에 덧붙인다(`tests/unit/product-extension-typecheck.test.ts:267-281`). "제품 capability를 기능에 주는 다운스트림"을 먼저 만들고 탐침을 올리는 케이스가 생겼다(`:313-323`). FE-GATE-005(CI env)에서 2 tests 통과, FE-GATE-020의 제거·생성 드릴 사본 8번에서도 통과. 수정 전처럼 제품 capability를 버리게 하면 새 케이스만 `TS2741 … 'typecheckProbeDownstreamSettings' is missing`으로 실패한다(09-R1).
- 1105/09-02: `ProductCompositionContext.notifySessionUnauthenticated()`(`src/bootstrap/product-composition-contract.ts:100`, 조립 `src/bootstrap/runtime-adapters.ts:705`)와 recipe handler(`recipes/session-owners/cookie-session-owner.ts:217-225`)가 생겼다. 매뉴얼 04 4.3 연결 그대로 쿠키 읽기·쓰기 401 뒤 세션 `unauthenticated`, 이전 scope not current를 조립 루트 테스트가 본다(`tests/recipes/session-owners-runtime.test.ts:416-436`, FE-GATE-007 통과). 조립 루트의 알림을 빈 함수로 바꾸면 그 두 테스트가 `expected 'authenticated' to be 'unauthenticated'`로 실패한다(09-R2).
- 1103/16-05: `BoundMutation.operationId`가 brand 타입 `MutationOperationId`다(`src/contracts/server-state.ts:276-278`, `:319`). 손으로 적은 문자열은 `check:types:test`에서 실패한다(`tests/unit/command-mutation-identity.test.ts:49-52`의 `@ts-expect-error`, FE-GATE-003 PASS). 코드는 커밋 꼬리말·CHANGELOG 2단계와 같다.
- 새 발견 09-01: 16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 같은)과 테스트 fixture의 길을 말하지 않는다. 그 길은 매뉴얼이 "못 잡음"이라 적은 손 객체뿐이다. 매뉴얼 01 안에서도 두 줄이 서로 다르다(`:476` "저장할 때 실패" vs `:499` "check:types 실패"). Low·P3.
- 1105/02-01 조립: 제품 closer가 각자 order 10 participant가 되고, label이 형식에 맞지 않으면 조립이 `TypeError`로 멈춘다(`runtime-adapters.ts:713-722`). "하나가 실패해도 나머지를 닫는다"는 그대로다(`tests/unit/runtime-adapters-product-scope-participants.test.ts:139`). 발견 없음.
- 1103/09-05의 고친 부분(SW blockers·observe를 `composeProduct`로)도 변이로 지켜진다. 조립이 그 칸을 넘기지 않게 하면 연결 테스트가 실패한다(09-R3).
- 검사 약화: 영역 테스트 diff에 지운 단언·skip·시간 상한 증가는 없다(3절 머리). 약화로 센 것은 없다.
- 새 발견: Low 1. P3 1. 확인된 결함 1.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `bbde570796b0a648bae65c2c0568fca860a3ba4e`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 2026-11-06 04시 |
| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` pin `45d2a478`(`config/contracts/backend-contract-pin.json`, `git show <pin>:<path>`로 읽기만) |
| 필수 요구와 규모·운영 목표 | 두 템플릿을 짝으로 빨리 출시. 다운스트림(tech-log, memento)이 템플릿을 동기화한다. 정량 운영 목표 없음 |
| 읽은 코드·구성 범위 | `git log 8a44226..bbde570`의 영역 커밋 20개 본문(`397664e`, `0007699`, `bfd9d50`, `fdc1db9`, `f738348`, `48c1ab7`, `00b12b3`, `2e1acb1` 외 합친 커밋). `git diff 8a44226..bbde570`의 영역 소스 12파일 전부. `src/bootstrap/{runtime-adapters,product-composition-contract,product-composition,create-runtime-composition,optional-runtime-host,boot,render-boot-failure}.ts*`, `src/features/product-capabilities.ts`, `src/contracts/{product-contracts,server-state,diagnostics}.ts`, `src/adapters/query-cache/server-state-scope-runtime.ts`(02-01 부분), `src/presentation/adapters/query/application-query.ts:336-370`, `recipes/session-owners/cookie-session-owner.ts`, `scripts/check-registries.ts:155-168`. 테스트: `tests/unit/{product-extension-typecheck,command-mutation-identity,runtime-adapters-product-scope-participants,registry-governance}.test.ts`, `tests/recipes/{session-owners-runtime,cookie-session-owner}.test.ts`, `tests/component/runtime-composition-service-worker-product-wiring.test.ts`, `tests/helpers/mutation-operation-id.ts`. 문서: `CHANGELOG.md:14-108`, `docs/manual/01-add-a-feature.md:470-505`, `02-decision-tables.md:230-240`, `:280-400`, `03-outside-feature-folder.md:120-165`, `04-paired-backend-session.md:180-260`. 다운스트림 둘(`memento-frontend` `d3810a0`, `tech-log-frontend` `7a4e201a`, 둘 다 v0.2.0 동기화 브랜치)은 앱 id와 뮤테이션 정책 모양만 grep으로 봤다 |
| 수행한 테스트·실험 | 직접 실행 없음(노트북·desktop 모두). 증거는 desktop `bbde570` merge 단계 로그(`/tmp/claude-gates/bbde570-ci/`, CI env, 03:24~03:56): FE-GATE-003·005·006·007·020 rc=0. 공유 snapshot `r5/snap/`의 `verify-documentation.*.txt`. 변이 3개(09-R1, 09-R2, 09-R3)는 오케스트레이터 배치가 04:23에 돌렸다(`desktop:/tmp/claude-gates/r5/batch/out/R5-09-R*.log`, 6절) |
| 확인하지 못한 범위·이유 | 5절 |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/09-app-core.md` 2절·3절 전부, README §15의 09 행, §16.4·§16.5의 09 행과 1103/16-05. §16은 주장으로만 읽었다. 각 항목을 지난 영역 문서 3절의 완료 기준과 현재 코드·게이트 로그로 다시 판정했다(2절) |
## 2. 지난 발견 재확인
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/09-01 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | **고쳐짐** | 탐침이 `product-contracts.ts`·`product-composition.ts`를 `<name>-product-*.ts`로 옮긴다(`tests/unit/product-extension-typecheck.test.ts:267-271`). 새 파일은 옮긴 모듈을 `export *`로 다시 내보내고(`:98`, `:130`), 설정 필드·env 행·`composeProduct` 결과와 그 `capabilities`를 펼친 뒤 탐침 것만 더한다(`:100-113`, `:132-142`). 완료 기준 "09-probe-downstream 상태에서 탐침 통과 + 출하 상태에서 통과": "제품 capability를 기능에 주는 다운스트림"을 같은 함수로 먼저 만들고 탐침을 올리는 케이스(`:313-323`)와 출하 상태 케이스(`:305-311`)가 있다. FE-GATE-005(CI env) `product-extension-typecheck.test.ts (2 tests)` 통과(`gate-artifacts/FE-GATE-005.txt:172`, coverage 실행 `:374`). FE-GATE-020의 제거·생성 드릴 사본 8번에서도 2 tests 통과(`FE-GATE-020.txt:209`, `:578`, `:1740` 등). 예약 이름 검사는 기능·context 폴더와 옮길 파일 이름까지 본다(`:259-266`). **09-R1**: 탐침의 `...product.capabilities`를 지우면(수정 전 덮어쓰기와 같은 결과) 1 failed / 1 passed다. 실패는 "passes when a product feature needs a product capability"이고 `tsconfig.app.json` 출력이 `runtime-adapters.ts(736,5): error TS2741: Property 'typecheckProbeDownstreamSettings' is missing`이다(사본의 `createInstalledFeatureLoaders` 호출, 저장소 `src/bootstrap/runtime-adapters.ts:735-736`). 출하 상태 케이스는 통과했다. 새 케이스가 지난 결함을 잡는다. 남은 가정(완료 기준 밖): 탐침 context가 소유 앱을 `template-app`으로 고정한다(`:216`). 두 다운스트림 모두 `APP_MODULE_ID = "template-app"`이라(`memento-frontend/src/apps/template-app/app-module.ts:6`, tech-log 같은 줄) 지금은 해당 없다 |
| 1105/09-02 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다 | **고쳐짐** | 조립 루트가 제품 context에 `notifySessionUnauthenticated: () => authSession.onUnauthenticated()`를 준다(`src/bootstrap/runtime-adapters.ts:705`, 계약 `src/bootstrap/product-composition-contract.ts:91-100`). recipe의 `createSessionCookieRejectionHandler`는 `SESSION_COOKIE_*` 프로필의 401만 넘긴다(`recipes/session-owners/cookie-session-owner.ts:217-225`). 그래서 1103/09-01의 "세션과 무관한 provider 401은 로그아웃시키지 않는다"는 그대로다(`tests/recipes/cookie-session-owner.test.ts`의 `PARTNER_API_TOKEN` 케이스, 호출 2회). 완료 기준 "매뉴얼 04 4.3대로 이은 조립 루트에서 쿠키 읽기·쓰기 401 → 세션 `unauthenticated`, 이전 scope not current": `tests/recipes/session-owners-runtime.test.ts:416-436`이 그 연결(`:95`)로 본다. FE-GATE-007 `session-owners-runtime.test.ts (6 tests)` 통과(`FE-GATE-007.txt:104`). **09-R2**: 조립 루트의 `notifySessionUnauthenticated`(`runtime-adapters.ts:705`)를 빈 함수로 바꾸면 2 failed / 4 passed다. 실패는 "signs out when the server answers a cookie read with 401"과 "… write with 401"이고, 둘 다 `:434`에서 `expected 'authenticated' to be 'unauthenticated'`다. 템플릿 쪽 연결을 테스트가 지킨다. 매뉴얼 04 흐름도·예시·설명(`docs/manual/04-paired-backend-session.md:188`, `:191`, `:249`, `:256-257`), 매뉴얼 02 5절(`docs/manual/02-decision-tables.md:238`)과 7절 업로드 예시(`:375`), recipe 주석(`cookie-session-owner.ts:33-44`, `:181-187`)이 이제 같은 말을 한다. 남은 것(완료 기준 밖, 기록된 한계): 제품이 이 한 줄을 빼면 막는 검사가 없다(`CHANGELOG.md:107`) |
| 1105/09-03 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | **고쳐짐** | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다(`scripts/check-registries.ts:160-168`). 새 테스트가 실제 `ContractContributionError`를 던지는 source로 `check:registries`를 돌려 원인이 한 번(`split` 길이 2)이고 `(reason:`이 없음을 본다(`tests/unit/registry-governance.test.ts:656-711`). reason이 message에 없는 오류의 옛 테스트(`:546`)는 남았다. FE-GATE-005 "names a ContractContributionError's reason once" 통과(`FE-GATE-005.txt` registry-governance 12 tests). 매뉴얼 출력 형식 줄도 고쳤다(`docs/manual/reference/errors.md:156`) |
| 1103/09-03 | 짝 백엔드 인증 방식에 맞는 세션 owner가 없다 | **일부** (남은 것은 백엔드로 넘김) | ③ 쿠키 모드 401은 1105/09-02로 고쳐졌다. ① 실제 Keycloak 로그인·Redis 쓰기 1회는 이번에도 아무도 하지 않았다(README §16.5). ② pin 커밋 realm의 client는 여전히 confidential `ca-skeleton-api` 하나다(`git show 45d2a478:infra/keycloak/realms/ca-skeleton-realm.json`의 `"clientId": "ca-skeleton-api"`, `"publicClient": false`, 59·62행). Redis 모드 로그인·세션 조회 엔드포인트도 제품 몫으로 적혀 있다(`docs/manual/04-paired-backend-session.md:23`, `:195-201`) |
| 1103/09-04 | 플랫폼 예제 화면 4개를 끌 자리가 없다 | **일부** (결정 대기 D2, 이번 범위 변경 없음) | ① `EXAMPLES_PLATFORM`은 플랫폼 레지스트리에 그대로다(`src/contracts/routes.ts:33-45`). 수기 접근성 기록은 `Status: pending-manual-review`다(`artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md:3`). ② 지울 수 있는 예제 라우트(`/examples/{ui,states,auth}`)를 자기 페이지로 쓰는 브라우저 spec은 `8a44226`과 같은 8개다(`tests/e2e/{accessibility,design-system-interactions,old-tab-chunk-recovery,responsive,scroll-restoration,typography,ui-gallery}.spec.ts`, `tests/visual/platform.visual.spec.ts`, `git grep -lE "examples/(ui\|states\|auth)\|EXAMPLES_(UI\|STATES\|AUTH)"`). 바뀐 것은 문서뿐이다(`docs/architecture/starter-experience.md:104-118`, 1105/14-01) |
| 1103/09-05 | SW 등 선택 런타임을 켜는 일이 제품 확장 지점 밖에 있다 | **일부** | 고친 것: `ProductComposition.serviceWorker?: { blockers?, observe? }`(`product-composition-contract.ts:127-139`, `:166`)를 조립이 bundle에 싣고(`runtime-adapters.ts:779`) 템플릿 조립이 optional host에 넘긴다(`src/bootstrap/create-runtime-composition.ts:47`, `:61`, `:95-115`). 제품 `observe`의 throw는 조립이 삼킨다(`:104-110`). 던지는 blocker는 page controller가 막는 쪽으로 본다(`src/adapters/service-worker/service-worker-page-controller.ts:75-85`). 실제 조립을 지나는 테스트(`tests/component/runtime-composition-service-worker-product-wiring.test.ts:134-161`, FE-GATE-006 통과 `FE-GATE-006.txt:68`). **09-R3**: `create-runtime-composition.ts:61`(`...serviceWorkerWiring(productServiceWorker)`)을 지우면 그 1건이 `:147`에서 `expected [] to deeply equal [ { event: 'register', … } ]`로 실패한다. 매뉴얼 03·레시피가 새 자리를 가리킨다(`docs/architecture/optional-adapter-recipes.md:151`). 남은 것: ① 활성화 화면(`onUpdateWaiting`·`requestActivation()`, `src/contracts/service-worker.ts:177`, `:190`)을 쓰는 곳이 `src/` 어디에도 없다. 제품 소유 자리도 없다. ② realtime·Web Worker·오프라인 선택은 여전히 "Connect a runtime in src/bootstrap/optional-runtime-host.ts"로 거절된다(`src/bootstrap/optional-runtime-host.ts:55-65`) |
| (영역 16) 1103/16-05 — 이 영역 요청 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **고쳐짐** (이 수정이 새 09-01을 만들었다) | 완료 기준(1103 영역 16 문서) "E-2의 오타가 `check:types`에서 실패하거나, 실패 문구가 operation ID 불일치를 말한다"의 앞쪽을 채운다. `MutationOperationId = string & { readonly [MUTATION_OPERATION_ID]: true }`(`src/contracts/server-state.ts:268-278`). 이 값을 만드는 곳은 `commandMutationIdentity`뿐이다(`:294-313`). `BoundMutation.operationId`가 그 타입이다(`:319`). 공개 `useApplicationMutation` overload는 `BoundMutation`만 받는다(`src/presentation/adapters/query/application-query.ts:336-338`). `@ts-expect-error` 한 줄이 손 문자열 거절을 고정한다(`tests/unit/command-mutation-identity.test.ts:49-52`). `tsconfig.test.json`이 `tests/**/*.ts`를 포함하고 FE-GATE-003 typecheck PASS(`bbde570-ci/FE-GATE-003.log`)이므로 그 줄은 실제로 오류를 만난다. 커밋 꼬리말(`48c1ab7` "BREAKING CHANGE")과 CHANGELOG 2단계(`CHANGELOG.md:25`)·표 행(`:65`)이 말하는 코드 변경과 같다. 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)과 쓰기 slice 생성기(`scripts/create-feature-write-slice.ts:511`)는 이미 `commandMutationIdentity`를 펼친다. FE-GATE-020 생성 드릴 통과. 템플릿 테스트의 손 ID 20곳은 `testMutationOperationId`(`tests/helpers/mutation-operation-id.ts:11-15`)로 바꿨고 단언은 그대로다. 위반 이름(`MISSING_IDEMPOTENCY_KEY`)을 나누는 안은 버렸다(커밋 본문, 기준이 "또는"이라 남은 것으로 세지 않는다). 안내의 빈칸은 새 09-01 |
| (영역 02) 1105/02-01 — 조립 쪽만 | 제품 scope closer가 던지면 진단 없이 `FAILED`로 멈춘다 | **조립 쪽 발견 없음** (발견 자체의 판정은 영역 02) | 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로 넘긴다(`src/bootstrap/runtime-adapters.ts:440-464`). scope는 reset마다 목록 함수를 읽고 order로 정렬한다(`server-state-scope-runtime.ts:156-170`, `orderParticipants`). 정렬은 안정 정렬이라 제품 순서가 유지된다. 하나가 던져도 나머지를 부르고 `FAILED`에 둔다(테스트 `runtime-adapters-product-scope-participants.test.ts:139`, `closed = ["after"]`). 실패마다 `scope_participant: <label>` 진단 1건(`:160-197`). 형식에 맞지 않는 label은 `TypeError`(`runtime-adapters.ts:713-722`, 테스트 `:199-203`). 이 throw는 부팅을 `BOOT_UNEXPECTED_FAILURE`로 멈추고, 개발 빌드는 원래 오류를 console에 보고한다(`src/bootstrap/render-boot-failure.tsx:19-20`). 메시지가 어느 label인지 말하지 않는 것은 작아서 발견으로 세지 않았다. CHANGELOG 6단계(`CHANGELOG.md:29`)가 BREAKING으로 적는다. FE-GATE-005 `runtime-adapters-product-scope-participants.test.ts (4 tests)` 통과 |
| 0925 FOLLOW-UP 09-07 | 샘플 제거 드릴이 lint·`check:i18n`·e2e를 건너뜀 | **일부** (변경 없음) | lint, `verify:documentation`, `check:i18n`, `check:design-system`은 돈다(`scripts/test-sample-removal.ts:443-448`). 브라우저 테스트는 여전히 돌리지 않는다. 예제 기능 제거 드릴을 돌리는 게이트도 없다(`CHANGELOG.md:93`, 1105/14-01 일부). 위 1103/09-04 ②가 그 결과다 |
| 0925 FOLLOW-UP 09-08 | local-draft ABA를 주석으로 닫음 | **남음(허용한 대안)** | `src/features/local-draft-feature/domain/local-draft.ts:2-11` 그대로. 폴더에 `NOT_A_FEATURE` 표시가 있어 기능이 아니다 |
지난 라운드에 고쳐짐으로 닫은 1103/09-01·09-02·09-06~09-11은 다시 세지 않는다. 그 경로의 파일 중 `src/features/feature-adapter-contribution.ts`, `src/presentation/providers/session-provider.tsx`, `src/application/ports/auth-session-port.ts`, `src/adapters/auth/`, `src/bootstrap/{load-release-manifest,runtime-config-schema}.ts`, `src/contracts/contract-set.ts`는 `8a44226`과 같다(`git diff --stat` 0). `reportServerUnauthenticated`(`runtime-adapters.ts:605-621`)도 본문이 같다.
## 3. 이번 발견 (36.3)
요약: Low 1. P3 1. 확인된 결함 1.
검사 약화 점검(브리프 4절): `git diff 8a44226..bbde570`의 영역 테스트를 봤다.
- `product-extension-typecheck.test.ts`: 옛 케이스의 파일 내용·tsc 3종·생성기 검사가 그대로다. 예약 이름 검사는 저장소 쪽에서 사본 쪽으로 옮겼고(사본은 저장소와 같다) 대상이 넷으로 늘었다. 케이스가 하나 늘었고 케이스별 시간 상한 120초는 그대로다(`:310`, `:322`).
- 1103/16-05의 테스트 20곳: 지운 줄은 `operationId: "<ID>"` 뿐이고, 더한 줄은 같은 문자열을 `testMutationOperationId(...)`로 감싼 것이다(`48c1ab7`의 `tests/component` diff). helper는 `commandMutationIdentity`를 거쳐 런타임 값이 같다(`tests/helpers/mutation-operation-id.ts:11-15`). 단언은 바뀌지 않았다.
- `runtime-adapters-product-scope-participants.test.ts`, `registry-governance.test.ts`, `server-state-scope-runtime.test.ts`, `session-owners-runtime.test.ts`, `cookie-session-owner.test.ts`: 더하기만 했다.
- `runtime-adapters.test.ts`: 10-01 테스트를 더했고 지운 단언은 없다.
- 영역 경로에 새 skip·only·todo·`it.fails`·시간 상한 증가는 없다.
약화로 센 것은 없다.
### 09-01 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션과 테스트의 길을 말하지 않고, 매뉴얼 01 안에서 두 줄이 다르다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(이행 안내 빈칸·문서 불일치) |
| 관련 관점 | 20, 17, 4, 9, 5 (30.4 업데이트 전파) |
| 근거 | `MutationOperationId`를 만드는 곳은 `commandMutationIdentity` 하나다(`src/contracts/server-state.ts:268-278`, `:294-313`). 그 함수는 `{ contract: { operationId, method, retrySemantics } }` 모양만 받는다(`:295-301`). CHANGELOG 2단계는 "`operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾼다"만 적는다(`CHANGELOG.md:25`). 매뉴얼 01도 descriptor 상수 길만 적는다(`docs/manual/01-add-a-feature.md:475`, `:484`, `:498-499`). descriptor가 없는 뮤테이션은 손으로 만든 descriptor 모양 객체를 넘기는 수밖에 없다. 매뉴얼 01은 바로 그 길을 "**못 잡음**"으로 적는다(`:500`). 커밋 본문은 이 한계를 안다: "HTTP가 아닌 뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가 없다"(`48c1ab7`). 이 문장은 CHANGELOG에도 매뉴얼에도 없다(`git grep -n "descriptor 모양\|HTTP가 아닌 뮤테이션" -- CHANGELOG.md docs src` 0건). 템플릿이 지원하는 경로 중 V3 descriptor가 없는 쓰기가 있다. Fileserver 업로드 client는 `upload(request)`만 있고 V3 `InstalledHttpContract`가 아니다(`src/adapters/http/fileserver-upload.ts:125-129`). 매뉴얼 02는 그 업로드에 `idempotencyKey`를 넘기라고 적는다(`docs/manual/02-decision-tables.md:290`, `:393`). 화면에서 그 키와 결과 불명 처리를 받는 길은 `useApplicationMutation`(`BoundMutation`만 받음, `src/presentation/adapters/query/application-query.ts:336-338`)이다. 테스트도 같다. 템플릿은 자기 테스트의 손 ID 20곳을 `tests/helpers/mutation-operation-id.ts`의 helper로 바꿨다. 그 helper도 손 객체 길이다(`:11-15`). CHANGELOG는 이 helper도, 테스트 fixture가 `check:types:test`에서 실패한다는 것도 말하지 않는다(`git grep -n "testMutationOperationId\|mutation-operation-id" -- CHANGELOG.md docs` 0건). 매뉴얼 01 안의 불일치: `:476`은 "손으로 적은 ID에 오타가 있으면 저장이 항상 실패하고, 화면은 '요청을 처리할 수 없습니다'다"라고 아직 적는다. `:499`는 "문자열로 직접 적으면 `check:types`가 실패한다"고 적는다. `:476`은 이 BREAKING 전의 동작이다 |
| 발생 조건 | (가) 다운스트림이 이 절을 받는다. 그 제품에 V3 descriptor가 없는 `BoundMutation`(Fileserver 업로드, 로컬 쓰기, 자체 gateway 쓰기)이나 정책을 손으로 적은 테스트 fixture가 있다. (나) 기능 작성자가 매뉴얼 01 7단계를 읽는다 |
| 영향 | (가) `check:types`가 `Type 'string' is not assignable to type 'MutationOperationId'`로 실패한다. 고칠 길을 찾으면 그 길이 매뉴얼의 "못 잡음"이다. 제품마다 helper를 따로 만들거나 `as MutationOperationId`로 우회한다. 우회는 brand의 목적을 지운다. 런타임 피해는 없다. (나) `:476`을 읽은 사람은 오타가 런타임에만 드러난다고 믿는다. 동작 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 타입 검사가 먼저 실패하므로 잘못된 동작이 배포되지 않는다. 이행 비용과 문서 신뢰만 깎는다 |
| 통제·증거 | 목표 M1(이행 안내가 지원 경로를 모두 적는다) / 확인 M0(descriptor 없는 경로 안내 없음) · E1 |
| 확실성과 남은 가정 | 코드와 문서로 확인했다. 실행하지 않았다. 두 다운스트림의 현재 동기화 지점(v0.2.0)에는 손 ID 정책이 있다(`memento-frontend/src/features/memento-web/presentation/hooks/use-memento.ts:149-152` 등 8곳, `tech-log-frontend/.../studio-asset-server-state.ts:140-153`의 `operationId: string` 매개변수 helper). 그중 V3 descriptor로 옮길 수 없는 것이 몇 개인지는 모른다. 1103 절의 V2 삭제 이행 뒤에 descriptor가 생길 수 있다(추론) |
| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: 커밋 본문이 descriptor 없는 뮤테이션과 손 객체의 한계를 "위험·한계"에 적었다. 버린 대안 (2) "설치된 operation ID의 union 타입"은 늦게 적재되는 계약 때문에 버렸다. 리뷰어 추론: brand 선택 자체는 맞다. descriptor 없는 쓰기에 공식 길이 없어서, 그 길이 "못 잡음"으로만 남았다 |
| 이해 비용 | 업로드 화면을 만드는 기능 작성자와 동기화하는 다운스트림 담당이 커밋 본문까지 읽어야 길을 안다 |
| 최소 개선 방향 | CHANGELOG 2단계와 매뉴얼 01에 한 줄씩: "V3 descriptor가 없는 뮤테이션(Fileserver 업로드 등)은 `commandMutationIdentity({ contract: { operationId, method, retrySemantics } })`로 받는다. 이 경우 오타는 잡지 못한다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`를 쓴다." 매뉴얼 01 `:476`의 둘째 문장을 지우거나 "손 객체" 경우로 좁힌다. 더 나아가면 descriptor 없는 쓰기용 이름 있는 함수(`mutationIdentity({ operationId, method, retrySemantics })`)를 공개한다 |
| 대안 비교 | (A) 문서 두 줄: 가장 작다. 손 객체가 공식 길이 된다. (B) 이름 있는 함수 공개: 의도가 코드에 보인다. 공개 API가 하나 는다. (C) Fileserver 업로드 client가 descriptor 모양 상수(`FILESERVER_UPLOAD_MUTATION`)를 내보낸다: 템플릿이 아는 유일한 non-V3 쓰기에서 오타 문제가 사라진다. 다른 non-V3 쓰기는 남는다 |
| 단순화의 보존 조건 | 손 문자열은 계속 `check:types`에서 실패한다(`command-mutation-identity.test.ts:49-52`). GET descriptor는 계속 throw한다(`server-state.ts:303-307`) |
| 비용·부작용 | (A) 문서 두세 줄. (B)·(C) 함수 하나와 테스트 하나 |
| 재검토 조건 | 템플릿이 descriptor 없는 쓰기를 V3 descriptor로 모두 옮기거나, `BoundMutation`이 descriptor를 직접 받게 바뀌면 |
| 완료 기준 | CHANGELOG 2단계와 매뉴얼 01이 descriptor 없는 뮤테이션과 테스트 fixture의 길을 적는다. 매뉴얼 01에 "손 문자열은 저장 때 실패" 문장이 남지 않는다 |
| 검증 방법 | `git grep`으로 두 문서의 문장을 확인한다. (B)·(C)를 고르면 그 함수의 `@ts-expect-error` 한 줄과 런타임 값 테스트 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 | 조립 불변식 M3 / M3 | E2(FE-GATE-005·007) | O — 401 주인 판정, 쿠키 모드 세션 알림, 자격증명 순서, needs 좁히기, participant label이 throw·테스트로 지켜진다. 남은 것은 연결을 빠뜨린 제품을 막는 검사가 없다는 것(21) |
| 2 | 구조적 성숙도 | 적용 | 공개 경계 M3 / M3 | E1, FE-GATE-001~003 | P — 제품 소유 파일 셋에 SW 연결이 들어왔다(1103/09-05). SW 활성화 화면 자리와 realtime·worker·offline 런타임은 템플릿 파일이다(1103/09-05 일부). 플랫폼 구성 화면은 플랫폼 레지스트리다(1103/09-04 일부) |
| 3 | 변경 용이성 | 적용 | 제품 변경 = 제품 파일만 M2 / M2 | E2(FE-GATE-005 탐침 2 tests) | P — 제품 capability를 기능에 줘도 템플릿 탐침이 통과한다(1105/09-01 고쳐짐). SW blockers·observe도 제품 파일이다. 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 ②) |
| 4 | 인지 부하 | 적용 | 확장 위치 한 표 M1 / M1 | E1 | P — 쿠키 모드 401은 recipe·매뉴얼 04·02·CHANGELOG가 같은 말을 한다. 매뉴얼 01은 손 ID의 실패 시점을 두 가지로 말한다(09-01) |
| 5 | 위험 가시성 | 적용 | 판단 규칙이 호출부에서 보임 M2 / M2 | E1 | P — 401 판정이 함수 하나와 계약 주석에 있다(`runtime-adapters.ts:598-621`, `product-composition-contract.ts:91-100`, `:148-157`). hook 누락 위험은 매뉴얼 04 `:191`과 CHANGELOG `:107`에 있다. descriptor 없는 뮤테이션의 한계는 커밋 본문에만 있다(09-01) |
| 6 | 실패 성숙도 | 적용 | 안전한 기본 M2 / M2 | E2(FE-GATE-007) | P — 쿠키 세션 만료가 세션에 닿는다(1105/09-02). 제품이 hook을 빼면 만료를 모른다. 기본이 "알리지 않음"이라 fail-open 쪽이다(`CHANGELOG.md:107`, 기록된 선택) |
| 7 | 운영 성숙도 | 적용 | 경계 실패 진단 M2 / M2 | E2(FE-GATE-005) | P — scope reset 실패가 participant label과 함께 진단에 남는다(1105/02-01). 제품 hook이 없을 때 provider 401이 버려지는 것은 진단에 남지 않는다(`runtime-adapters.ts:612-618`) |
| 8 | 디버깅 가능성 | 적용 | 조립 오류가 원인을 말함 M3 / M3 | E2(`registry-governance.test.ts:656`) | O — 계약 조립 실패 원인이 한 번 나온다(1105/09-03). 탐침이 다운스트림에서 임시 경로 오류를 내지 않는다(1105/09-01). label `TypeError`가 어느 label인지 말하지 않는 것은 작다(2절) |
| 9 | 유지보수 성숙도 | 적용 | 낡은 설명 정리 M1 / M1 | E1 | P — recipe 주석이 401 동작을 따라갔다. 매뉴얼 01 `:476`이 16-05 전 동작을 적는다(09-01). `src/application/result.ts` 폐기 재수출 그대로(> 16 영역 1101/16-05) |
| 10 | 테스트 성숙도 | 적용 | 핵심 판단 M3 / M3 | E2(FE-GATE-003·005·006·007, CI env), E2(09-R1~R3 변이) | O — 1105 수정 셋과 1103/09-05·16-05에 각자 테스트가 있다. 다운스트림 상태(제품 capability)를 템플릿 테스트가 직접 만든다. 쿠키 모드 401을 조립 루트에서 본다. 수정 셋을 되돌린 변이 3개가 모두 기대한 테스트에서 기대한 이유로 실패했다(09-R1~R3). 테스트는 여전히 템플릿 출하 상태와 그 흉내만 본다(5절 다운스트림) |
| 11 | 데이터 성숙도 | 적용(샘플 범위) | — / M1 | E1 | P — local-draft ABA는 주석으로만(0925 FOLLOW-UP 09-08, 허용한 대안). 이 영역에 데이터 손상 경로는 없다 |
| 12 | 동시성 성숙도 | 적용(401·계정 전환) | 이전 scope의 401은 새 세션에 닿지 않음 M3 / M2 | E1(지난 라운드 09-R1은 이전 커밋 증거라 재사용하지 않는다) | P — 실행기의 admission 경쟁 처리 코드는 그대로다. 쿠키 경로도 같은 실행기 결과 뒤에 알린다(`runtime-adapters.ts:675-680`). 실행기 반환과 알림 사이 한 microtask의 전환은 여전히 아무도 재현하지 않았다(5절) |
| 13 | 확장성 | 적용 | 기능·제품 수 축 M3 / M3 | E2(탐침 다운스트림 케이스) | O — 제품 수 축의 1105/09-01이 닫혔다. 탐침 context의 앱 id 고정은 지금 두 다운스트림에 해당하지 않는다(2절) |
| 14 | 성능 성숙도 | > 15 영역 | — | — | > |
| 15 | 보안 성숙도 | 적용 | fail-closed M3 / M3 | E2(FE-GATE-007) | O — ANONYMOUS는 세션을 묻지 않는다. 쿠키 handler는 `SESSION_COOKIE_*`만 세션에 넘겨 외부 토큰 401이 로그아웃시키지 않는다. OIDC recipe의 ID token 서명 미확인은 문서화된 선택이다(OIDC Core 3.1.3.7(6), 매뉴얼 04 `:173`) |
| 16 | 의존성 성숙도 | 적용 제외 — 영역 고유 의존성 없음 | — | — | - |
| 17 | API / Contract 성숙도 | 적용 | 공개 계약과 이행 안내가 같음 M3 / M2 | E1, FE-GATE-003 | P — `notifySessionUnauthenticated`, `serviceWorker`, label 형식, `MutationOperationId`가 CHANGELOG에 [계약]·BREAKING으로 있다(`CHANGELOG.md:25`, `:29-31`, `:65`, `:68-70`). descriptor 없는 뮤테이션의 이행 길이 없다(09-01) |
| 18 | 배포 성숙도 | > 13 영역 | — | — | > — 플랫폼 구성 화면의 FE-GATE-028 서명 요구는 1103/09-04 일부 |
| 19 | 설정 성숙도 | 적용 | 제품 키 strict 검증 M3 / M3 | E2(FE-GATE-005 탐침) | O — 탐침이 제품 설정 키를 지우지 않고 더한다(`product-extension-typecheck.test.ts:100-113`) |
| 20 | 개발자 경험 | 적용 | 제품 파일 → 게이트 통과 M3 / M2 | E2(FE-GATE-005·020) | P — 제품 capability·SW 연결·쿠키 세션이 제품 파일만으로 된다. 16-05 이행에서 descriptor 없는 뮤테이션의 길이 없다(09-01). 쿠키 세션은 한 줄을 기억해야 한다 |
| 21 | Guardrail 성숙도 | 적용 | 조립 실수 차단 M3 / M2 | E2 | P — 손 문자열 ID(타입), 틀린 label(조립 throw), 표시+선언 동시 존재, needs 밖 capability를 막는다. 쿠키 provider를 두고 `onCredentialRejected`를 빠뜨린 제품은 막지 않는다(`CHANGELOG.md:107`) |
| 22 | 추상화 성숙도 | 적용 | 계약이 짧고 정확 M2 / M2 | E1 | O — `composeProduct`가 context로 세션에 알릴 수 있어 모듈 변수 연결이 사라졌다(1105/09-02). SW 연결은 선택 칸 하나다 |
| 23 | 일관성 | 적용 | 같은 선택은 같은 장치 M2 / M2 | E1 | P — 예제 화면 셋은 기능 선택으로 뺀다. 플랫폼 구성 화면만 예외다(1103/09-04 ①) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | — / M2 | E1 | P — `TEMPLATE_APP_MODULE`이 선택된 아무 앱을 가리키는 것은 그대로다(`src/apps/template-app.ts:10`) |
| 25 | 조직 확장성 | 적용 | 동기화 충돌 자리 분리 M2 / M2 | E2(탐침 다운스트림 케이스) | O — 템플릿 탐침이 다운스트림 제품 파일을 보존해 동기화 충돌 자리가 아니다(1105/09-01). SW를 켠 제품도 템플릿 파일을 되돌린다(`CHANGELOG.md:31`) |
| 26 | Ownership 성숙도 | > 14 영역 | — | — | > |
| 27 | 삭제 가능성 | 적용 | 기능·예제 제거 M3 / M2 | E1, FE-GATE-020 | P — 예제 셋은 기능으로 빠진다. 플랫폼 구성 화면은 빠지지 않는다. 브라우저 spec 8개를 제거 드릴이 보지 않고, 예제 제거 드릴은 게이트 밖이다(0925 FOLLOW-UP 09-07 일부, 1105/14-01) |
| 28 | 회복 가능성 | 적용 | 세션·부트 회복 M2 / M2 | E2(FE-GATE-006 `session-recovery` 4 tests, FE-GATE-007) | O — 쿠키 세션 만료 뒤 세션이 `unauthenticated`가 되어 로그인으로 돌아간다(1105/09-02). `no-session` 뒤 로그인 버튼(1103/09-11) 그대로 |
집계(판정한 24개): 충족 9(1, 8, 10, 13, 15, 19, 22, 25, 28) · 부분 충족 15 · 미충족 0 · 미검증 0. 10은 배치 변이 결과(09-R1~R3)로 확정했다. 적용 제외 1(16), 다른 영역 3(14, 18, 26). 지난 라운드(충족 1)보다 늘어난 것은 1105/09-01·09-02가 닫혔기 때문이다. 12는 지난 라운드 실험을 현재 증거로 쓰지 않아 증거를 E1로 낮췄다.
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 짝 백엔드에 실제로 붙인 로그인·401 | Keycloak·Redis·백엔드를 띄우지 않았다. pin realm에 public client가 없다 | 백엔드 local + Keycloak에 public client를 더하고 OIDC recipe로 `EXTERNAL_BEARER` 1회. Redis 모드에 세션 엔드포인트를 더하고 쿠키 owner로 쓰기 1회, 세션 삭제 뒤 401 1회 |
| 다운스트림(tech-log, memento)에 이 절을 넣은 결과 | 두 제품은 v0.2.0 동기화 지점이다. 이 절과 아래 1103 절을 적용해 보지 않았다(`CHANGELOG.md:20`) | 동기화 브랜치에서 `check:types`(16-05 손 ID), `test:unit`(탐침) |
| 실행기 반환과 401 알림 사이의 계정 전환 | 지난 라운드의 재현(admission 중 전환)은 이전 커밋 증거다. 반환 뒤 한 microtask 안의 전환은 아무도 만들지 않았다 | `contractHttp.execute`를 감싼 테스트에서 resolve 직전 subject를 바꾼다 |
| 예제 기능을 뺀 제품의 브라우저 게이트 | 무거운 실행이다(FE-GATE-008). 정적으로 spec 8개를 셌다 | `VITE_PRODUCT_FEATURES`에서 예제 기능을 빼고 `test:e2e`·`test:visual` |
| 앱 id를 바꾼 제품에서 탐침 | 해당 다운스트림이 없다 | 사본에서 `APP_MODULE_ID`를 바꾸고 `product-extension-typecheck.test.ts` |
## 6. 실행 기록
노트북과 desktop 어디서도 직접 실행하지 않았다. 아래 셋은 오케스트레이터 배치가 돌렸다. 요청 파일은 `scratchpad/r5/requests/09.md`, 변이 patch는 `09-R1.diff`~`09-R3.diff`다. 모두 `bbde570`에 `git apply --check`로 붙었다. 배치는 `bbde570`(`ref=bbde5707`, env local, 부하 2.8대)에서 한 항목씩 돌리고 항목마다 checkout을 되돌렸다(`restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-09-R{1,2,3}.log`다.
| ID | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 09-R1 | `node scripts/run-vitest.ts run tests/unit/product-extension-typecheck.test.ts` · local | 탐침 `composeProduct`가 `...product.capabilities`를 펼치지 않음(`tests/unit/product-extension-typecheck.test.ts:138` 삭제) | 1 | 1 failed / 1 passed, 6.34 s. 실패는 "1105/09-01 … passes when a product feature needs a product capability"(`:320` → `:299`의 `expect(…).toBe("")`)이다. 출력은 `…/src/bootstrap/runtime-adapters.ts(736,5): error TS2741: Property 'typecheckProbeDownstreamSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …; http: …; telemetry: TelemetryPipeline; }>' but required in type 'InstalledFeatureCapabilityContext'`다. "1103/09-02 … passes the app, node and test programs"는 통과했다. 기대와 같다. 대조군은 FE-GATE-005 `:172`(2 tests 통과) |
| 09-R2 | `node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts` · local | `src/bootstrap/runtime-adapters.ts:705`를 `notifySessionUnauthenticated: () => {}`로 | 1 | 2 failed / 4 passed, 3.14 s. "signs out when the server answers a cookie read with 401"과 "… cookie write with 401"이 `:434`에서 `AssertionError: expected 'authenticated' to be 'unauthenticated'`로 실패했다. OIDC 두 건과 쿠키 부팅·no-session 두 건은 통과했다. 기대와 같다. 대조군은 FE-GATE-007 `:104`(6 tests 통과) |
| 09-R3 | `node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts` · local | `src/bootstrap/create-runtime-composition.ts:61` 삭제 | 1 | 1 failed, 1.29 s. "passes the product's blockers and observer to the page controller"가 `:147`에서 `expected [] to deeply equal [ { event: 'register', …(1) } ]`로 실패했다(`register`는 1회 불렸다, `:146` 통과). 기대와 같다. 대조군은 FE-GATE-006 `:68`(1 test 통과) |
세 변이 모두 "변이 없는 명령은 통과(게이트 로그), 변이는 기대한 테스트에서 기대한 이유로 실패"를 채운다. 1105/09-01·09-02와 1103/09-05의 고친 부분은 현재 커밋의 테스트가 지킨다.
인용한 게이트 결과(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env, 2026-11-06 03:24~03:56):
- FE-GATE-003 typecheck PASS. 1103/16-05의 `@ts-expect-error`가 쓰였다는 증거다.
- FE-GATE-005 rc=0. `test:unit` 208 files / 3,056 tests. 이 영역의 `product-extension-typecheck`(2), `runtime-adapters-product-scope-participants`(4), `runtime-adapters-auth-profile`(16), `runtime-adapters-credential-order`(10), `runtime-adapters`(22), `product-composition-fixture`(13), `product-session-owner-context`(12), `command-mutation-identity`(5), `registry-governance`(12)가 들어 있다.
- FE-GATE-006 rc=0. `test:component` 41 files / 278 tests. `runtime-composition-service-worker-product-wiring`(1), `session-recovery`(4) 포함.
- FE-GATE-007 rc=0. `test:recipes` 7 files / 80 tests. `session-owners-runtime`(6), `cookie-session-owner`(17), `oidc-pkce-session-owner`(32) 포함.
- FE-GATE-020 rc=0(1,237 s). 제거·생성 드릴 사본에서 탐침 2 tests가 8번 통과.
- FE-GATE-013 rc=1은 user namespace 전제 때문이고 이 영역 테스트를 돌리는 게이트가 아니다.
- 모두 템플릿 출하 상태다. 다운스트림 상태는 탐침의 다운스트림 케이스와 recipe 런타임 테스트가 흉내 낸 범위까지만 본다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 09-01 | Low·P3 | 확인된 결함 | 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 등)과 테스트 fixture의 길을 말하지 않고, 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다 | `CHANGELOG.md:25`; `docs/manual/01-add-a-feature.md:476`, `:499-500`; `src/contracts/server-state.ts:294-313`; `tests/helpers/mutation-operation-id.ts:11-15` |
@@ -0,0 +1,248 @@
# 영역 10 — 테스트: 빠른 계층
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝) · 지난 문서: `docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md`(기준 `8a44226`)
> 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `tests/unit`, `tests/component`, `tests/integration`, `tests/contract`, `tests/runtime-schema`, `tests/features`, `tests/platform`, `tests/recipes`, `tests/helpers`, `tests/mocks`, `tests/support`(`tests/support/browser` 제외, 11 영역), `tests/scripts`. 설정: `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts`, `scripts/lib/no-skipped-tests-reporter.ts`, 제거 드릴이 테스트를 고르는 `scripts/lib/removal-fixture.ts`
> 깊게 본 관점: 10 테스트, 21 Guardrail, 27 삭제 가능성, 14 성능(테스트 비용)
> 렌즈: (1) 지난 발견의 완료 기준이 지금 코드에서 맞는가. (2) `8a44226..bbde570`의 테스트 변경, 특히 README §16.3의 통합 수정이 검사를 좁혔는가. (3) 커버리지 숫자가 지난 라운드와 어떻게 다른가.
> 영역 판정(35.8): **지정 범위에서 사용 가능** — 템플릿 상태의 머지 게이트로 쓴다. 새 발견 둘은 드릴 사본과 파일 이름 변경에서만 닿는 검출 공백이다.
## 0. 결론
- **지난 발견 13건(제안 1105/10-03 제외): 고쳐짐 4 · 일부 1 · 남음 8 · 재발 0 · 틀린 발견 0.** 남음 8건 중 셋(1101/10-05·10-06·10-08)은 §16.6의 결정 대기다. 다섯은 ID 없는 작은 이월이다.
- **네 라운드 살아남은 §10.8 마지막 검사(0929/10-04, 변이 L01)에 이제 테스트가 있다.** scope signal은 그대로 두고 `isCurrent`만 false로 바꾼다(`tests/unit/http-execution-v3.test.ts:574-620`). 그래서 앞 단계 abort가 먼저 답하지 않는다. 1105/10-02(interaction signal listener)와 1105/10-01(샘플 밖 플랫폼 규칙 테스트)도 고쳐졌다. 완료 기준의 변이 넷(H53, L02, R2b, L01)을 넣자 넷 모두 예상한 테스트가 예상한 이유로 실패했다(10-R1~10-R4, rc=1, restore clean). 무변이 통과는 FE-GATE-005 로그가 보인다.
- **1101/10-07은 "고침"이 아니라 일부다(§16.6과 다르게 판정).** SW 5초 대기는 8 ms가 됐다(`unit.xml`). RPC 쪽은 느린 4개 중 1개만 고쳤다. 수정은 이미 30 ms이던 3개에 시계를 넣었다. 1초를 실제로 자는 3개(`browser-rpc-remediation.test.ts:389`, `:412`, `:588`)는 지금도 1.03~1.07 s다.
- **README §16.3의 통합 수정 셋이 검사를 좁혔다.** 새 10-01: 두 테스트가 "대상 파일이 있으면"으로 검사를 정한다. browser-file-storage 드릴 사본에서 `playwright-run-isolation.test.ts`가 33개에서 25개로 줄었는데 skip 보고가 없다. 템플릿에서 파일 이름이 바뀌어도 같다. 새 10-02: 문서를 읽는 테스트 하나 때문에 `backend-contract-pin.test.ts`가 파일째 capability 드릴 셋에서 빠졌다. 문서와 무관한 14개(그중 10개는 `8a44226`에서 그 드릴들에서 돌았다)와 `feature-tracked-files.test.ts`의 1개가 그 드릴에서 돌지 않는다.
- **나머지 diff에서는 약하게 만든 검사를 찾지 못했다.** 새 `skip`·`todo`·`only`는 없다. 기존 테스트의 시간 한도는 오르지 않았다. 바뀐 기대값은 수정이 동작을 바꾼 자리다(3.0절).
- **새 발견 2건, 모두 Low·P3, 구조적 위험이다.**
- **커버리지는 네 지표 모두 0.2%p 올랐다.** lines 86.31 → 86.51%, branches 80.92 → 81.15%. 위험 하한 72개는 값이 그대로이고 모두 통과다(418/418 모듈). 줄어든 파일 7개는 모두 그 파일의 코드나 타입이 바뀐 곳이다(6.2절 C1).
- **비용 쪽 이월은 더 커졌다.** `tests/unit` 테스트 시간 합이 133.1 s → 175.7 s(CI env, +32%)다. `scripts`만 보는 파일과 import 없는 파일이 그중 76%다(지난 71%). 한 머지에 `tests/unit`이 13번 도는 것은 그대로다. FE-GATE-020은 1,156 s → 1,237 s다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 테스트 파일(unit.xml·coverage.xml 기준): `tests/unit` 208(지난 194), 커버리지 실행 332(316). 새 파일 15개는 모두 `tests/unit`이다(`git diff --name-status 8a44226 bbde570 -- tests`). 지운 테스트 파일은 없다 |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 오케스트레이터 배치가 desktop checkout에서 했다(2026-11-06 04:34, 항목마다 `head bbde5707…` 확인, 끝나면 `restore=clean`). 확인 2026-11-06 04:00~04:45 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.12(FE-GATE-005 로그 머리) |
| 필수 요구와 규모·운영 목표 | 빠른 계층은 머지 게이트다: FE-GATE-004(runtime-schema), 005(unit·contract·coverage·scale pr), 006(component), 007(integration·HTTP 시나리오·reference-feature·recipes), 020(제거·생성 드릴 안에서 다시). 러너 사양과 허용 실패율은 정해져 있지 않다(U-1) |
| 읽은 코드·구성 범위 | `git diff 8a44226 bbde570`의 영역 경로 68파일(+5,267 / −271), 영역 경로를 건드린 72커밋. 지난 발견의 수정 커밋 `00b12b3`, `dae44f5`, `c842bac`, `7ead8d3`, `ce191be` 전체. 통합 수정 `f4d5761`, `0e72c0c`, `c9aa73f`, `5c0b37e`·`6d084cf`의 영역 쪽. 제거 드릴: `scripts/lib/removal-fixture.ts`, `scripts/test-sample-removal.ts`, `scripts/test-browser-file-storage-runtime-removal.ts`, `scripts/lib/removable-template-features.ts`. 변이 대상: `src/bootstrap/runtime-adapters.ts:284-319`, `:538`, `src/presentation/routes/navigation-policy.ts:29-43`, `src/adapters/http/http-execution-v3.ts:620-667`, `:1493-1499`, `src/adapters/browser-rpc/browser-rpc-runtime.ts:895-916` |
| 읽은 문서(주장으로만) | 지난 영역 문서, 지난 README §15·§16, 0929·1101 영역 10 문서의 해당 발견, 수정 커밋 본문 |
| 수행한 테스트·실험 | 직접 실행 없음. 증거는 desktop 로그와 snapshot이다: `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`, `gate-artifacts/FE-GATE-004·005·006·007·020.txt`(merge 단계, CI env, 2026-11-06 03:24~03:56), `desktop:/tmp/claude-gates/r5/snap/merge/artifacts/tests/*.xml`·`coverage/coverage-summary.json`·`artifacts/quality/risk-coverage.json`(모두 03:46~03:48, MTIMES.txt 확인). 비교용 지난 값: `desktop:/tmp/claude-gates/r4/snap/artifacts/tests/{unit.xml,coverage.xml,coverage/coverage-summary.json}`, `artifacts/quality/risk-coverage.json`(2026-11-05 19:51~19:52, merge-48 FE-GATE-005). 변이 4건 **10-R1~10-R4**(`desktop:/tmp/claude-gates/r5/batch/out/R5-10-R1.log`~`R4.log`, local env, 모두 기대대로 실패). 노트북에서 로그 사본을 분류했다(6.2절) |
| 확인하지 못한 범위·이유 | 실제 Gitea 러너(U-1). 샘플을 지운 사본에서 조립 루트 `:538`을 바꾸는 변이(비용, 5절). 브라우저 계층(11 영역) |
| 이전 리뷰와 비교 가능한 범위 | 지난 실행 결과는 현재 증거로 쓰지 않았다. 숫자 비교(커버리지, 파일별 시간, 테스트 이름)는 같은 CI env의 merge 단계 산출물끼리 했다. 지난 문서의 J1(로컬 env)과는 env가 달라 J1을 지난 merge-48 unit.xml로 다시 셌다(6.2절) |
### 1.1 게이트 결과 (merge 단계, CI env, `bbde570`, 인용)
`summary.txt`: FE-GATE-004 rc=0(2 s), 005 rc=0(132 s), 006 rc=0(10 s), 007 rc=0(28 s), 020 rc=0(1,237 s).
- FE-GATE-004: `test:runtime-schema` 3파일 60개(`FE-GATE-004.txt`).
- FE-GATE-005: `test:unit` 208파일 3,056개, Duration 28.45 s(setup 50.73 s, tests 175.74 s)(`FE-GATE-005.txt:312-315`). `test:contract` 3파일 24개. `test:coverage` 332파일 통과(`:781`), `All files 84.23 | 81.15 | 90.63 | 86.51`(`:791`), `Risk coverage: PASS (418/418 production modules, 72 thresholds)`(`:1297`).
- FE-GATE-006: `test:component` 41파일 278개.
- FE-GATE-007: `test:integration` 11파일 212개, `test:reference-feature` 18파일 101개, `test:recipes` 7파일 80개.
- FE-GATE-020: 아래 드릴마다 `tests/unit`이 통과했다(파일 수): 샘플 제거 두 단계 204·204, 생성 기능 208, 생성 기능 제거 205, 선택 레시피 제거 201, browser-file-storage 제거 166, realtime 제거 180(`FE-GATE-020.txt:322`, `:1855`, `:4799`, `:6625`, `:10096`, `:10974`, `:11885`).
- 어느 junit에도 `skipped`가 1 이상인 suite가 없다.
## 2. 지난 발견 재확인
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/10-01 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라진다 | **고쳐짐** | `00b12b3`. ① 실행기를 만드는 부분을 `createRuntimeContractHttpExecutor`로 뺐다(`src/bootstrap/runtime-adapters.ts:284-319`). 조립 루트는 이 함수로만 만든다(`:538`, `src` 안 `createContractHttpExecutor(` 호출은 `:305` 하나). 완료 기준의 H53 자리(옛 `:502` `maxRetryAttempts: config.MAX_RETRY_ATTEMPTS`)는 지금 `:307`이다. 테스트 계약으로 0·1·2 → 1·2·3번을 단언한다(`tests/unit/runtime-adapters.test.ts:505-595`). 10-R1(`:307` → 상수 2): "honours MAX_RETRY_ATTEMPTS 0 / 1" 2건이 "expected to be called 1 / 2 times, but got 3 times"로 실패, 22개 중 20개 통과. ② L02 자리(`navigation-policy.ts:40`)는 fixture 기능의 보호 라우트로 본다(`tests/unit/session-route-access.test.ts:13-23`, `:32-41`). 10-R2(`:40` → `show-sign-in`): "answers a recovery-pending session with { allowed: false, action: 'wait-for-session' }" 1건 실패, 6개 중 5개 통과. ③ 두 파일은 샘플 제거 드릴의 공통 테스트 목록에 있다(`scripts/test-sample-removal.ts:133-140`). 샘플을 지운 사본의 `test:unit`에서 실제로 돌았다: `runtime-adapters.test.ts` 22개, `session-route-access.test.ts` 6개(`FE-GATE-020.txt:133`, `:311`; 그 실행의 junit 경로가 `.tmp/reference-feature-removal-*/`, `:327`). 남은 것: 조립 루트의 한 단계(`:538`이 `config`를 그대로 넘김)는 샘플 사본에서 지키는 테스트가 없다. 수정 커밋이 한계로 적었고 지난 문서 ⓐ안이 남긴 범위라 발견으로 세지 않는다(5절) |
| 1105/10-02 | interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다 | **고쳐짐** | `dae44f5`. 같은 테스트가 `createExecutionContext`로 만든 interaction을 넘기고 그 `cancellation.signal`도 감시한다(`tests/unit/http-execution-v3.test.ts:812-867`). 끝나는 경우에 "interaction cancel"을 더했다(`:816`, `:852`). 10-R3(R2b, `http-execution-v3.ts:663` 삭제): "removes the listeners … after an answer / a caller abort / an interaction cancel" 3건이 `expected [] to deeply equal [ [Function forwardCallerToLifetime] ]`(`:865`)로 실패, 72개 중 69개 통과. 완료 기준 충족 |
| 1105/10-03 | 판정 규칙의 변이 실험을 손으로 만든다(변이 도구 제안) | 제안 — 세지 않음 | BRIEF §7. 오케스트레이터가 기록한다 |
| 0929/10-04 | §10.8 마지막 검사(오래된 scope의 성공 응답 버림) 미고정 | **고쳐짐** | `c842bac`. fetch 안에서 `isCurrent`만 false로 바꾸고 signal은 abort하지 않는다(`tests/unit/http-execution-v3.test.ts:574-620`). JSON 성공 경로에서 dispatch 뒤 scope를 보는 곳은 `http-execution-v3.ts:1494` 하나다(다른 `isCurrent` 자리 `:1344`, `:1399`는 빈 본문 경로, `:932`·`:1009`는 dispatch 전). 10-R4(L01, `:1494` → `false`): "discards a valid read / command success that arrives after its scope stopped being current" 2건이 `expected { kind: 'SUCCESS', … } to match object { kind: 'CONTRACT_VIOLATION', … }`(`:614-618`)로 실패, 72개 중 70개 통과. 0929 완료 기준("변이 K를 넣으면 새 테스트가 실패한다") 충족. 네 라운드 만에 닫혔다 |
| 0929/10-05 | `test:all`이 CI 빠른 테스트 일부를 빠뜨림 | **고쳐짐** | `7ead8d3`. `test:all`이 `tests/features`, `tests/scripts`, `tests/scale/browser-soak.contract.test.ts`를 함께 돈다(`package.json:85`). `test:coverage`의 경로(`:83`) 중 `tests/release`·`tests/platform/release`는 `check:release-coherence`(`:153`)가, `tests/platform tests/architecture`는 `test:platform`(`:141`)이 돈다. `tests/unit/test-all-paths.test.ts:20-31`이 두 스크립트 그래프의 Vitest 경로를 비교한다. FE-GATE-005의 `test:unit`에서 통과했다 |
| 1101/10-07 | 프로덕션 시간 상수를 실제 시계로 기다림(5개 테스트) | **일부** (§16.6 "고침"과 다름) | `ce191be`. SW: "bounds a stream that never produces a chunk"가 5.03 s → 8.2 ms(`unit.xml`, 지난 merge-48 unit.xml과 비교). 파일 시간 5.21 s → 0.32 s. RPC: 1101 문서는 1초를 자는 4개를 말한다(예 `:579`는 `d99301b`에서 "admits a second stream once waitClosed fulfils" 안이다). `8a44226` junit에서 1 s를 넘는 RPC 테스트는 "cancels the physical stream exactly once after a timeout" 1.03 s, "refuses a second stream while the first has not confirmed closure" 1.08 s, "admits a second stream once waitClosed fulfils" 1.07 s, "keeps the operation DRAINING when waitClosed never settles" 1.03 s다. 수정은 "keeps the operation DRAINING when waitClosed …" 4개에 `cappedClock`을 넘겼다(`browser-rpc-remediation.test.ts:544-566`). 그중 3개(rejects, throws, non-promise)는 이미 28~34 ms였다. 지금 `bbde570` junit: never settles 59 ms로 내려갔다. 나머지 셋은 1,033 ms, 1,068 ms, 1,068 ms다(`:389`, `:412`, `:588`, 시계를 넘기지 않음). 완료 기준("5개 테스트가 각각 100 ms 아래") 중 2개만 충족했다. 남은 부분 Low·P3 |
| 1101/10-05 | `tests/unit`에 도구 테스트가 섞여 시간 대부분을 씀 | **남음(결정 대기)** — 커짐 | J1(6.2절, CI env): `scripts`만 59파일 100.1 s(57%), import 없음 17파일 32.5 s(19%). 합 76%(지난 merge-48: 51파일 54% + 14파일 17% = 71%). 늘어난 곳: `product-extension-typecheck.test.ts` 11.3 → 22.0 s(09-01이 두 번째 복사·tsc 테스트를 더함), `documentation-readiness.test.ts` 16.6 → 22.5 s, 새 파일 `template-feature-removal-documents.test.ts` 7.3 s, `run-output-root-build.test.ts` 6.9 s, `manual-paired-backend-settings.test.ts` 4.1 s. 저장소 사본을 만들고 tsc나 문서 검사를 도는 테스트가 셋 늘었다 |
| 1101/10-06 | 머지 단계가 빠른 계층을 여러 번 돌림 | **남음(결정 대기)** | 다시 셌다(6.2절 D2). FE-GATE-005에서 2번, FE-GATE-020에서 11번(샘플 제거 4, 생성 기능 2, 생성 기능 제거 2, capability 드릴 3). 합 13번으로 지난과 같다. 0929/10-05 수정으로 드릴 안의 `test:all` 6번이 이제 `tests/features`·`tests/scripts`도 돈다(`7ead8d3` 본문이 적은 대로). FE-GATE-020 1,156 s(merge-48) → 1,237 s |
| 1101/10-08 | `scopeSnapshot` 갈라진 복사본 | **남음(결정 대기)** | 공유 도우미 두 곳(`tests/helpers/traffic-test-kit.ts:13`, `tests/component/application-query-fixture.tsx:20`) 밖에 4개 파일이 각자 정의한다(`tests/features/reference-feature/reference-diagnostics.test.ts:7`, `tests/integration/http-execution-v3-auth-profile.test.ts:41`, `-live-authority.test.ts:23`, `-observability.test.ts:24`). `identities: Object.freeze({}) as never` 10곳. `deferred()` 7벌. 새 테스트는 공유 도우미를 썼다(`runtime-adapters.test.ts`의 `scopeSnapshot` import) |
| (지난 2절) `test:platform`만 `--no-file-parallelism`, 이유 없음 | | **남음** | `package.json:141` |
| (지난 2절) `--passWithNoTests` 3곳 | | **남음** | `package.json:50`, `:58`, `:81` |
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | | **남음** | `tests/setup.ts:1-2`. unit setup 누적 50.73 s(CI env, `FE-GATE-005.txt:315`) |
| (지난 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:25`. 파일이 바뀌지 않았다 |
1103 이월(§16.5)에는 이 영역 행이 없다. 1103/10-01~10-04는 지난 라운드에 모두 고쳐졌다. 틀린 발견으로 판정한 지난 항목은 없다. §16.4·§16.6과 다르게 판정한 것은 1101/10-07 하나다.
## 3. 이번 발견 (36.3)
새 발견 2건 — 심각도 Low 2 · 우선순위 P3 2 · 성격 구조적 위험 2. High 이상과 P1은 없다.
### 3.0 검사를 약하게 했는지 (`git diff 8a44226 bbde570 -- <영역 경로>`)
- 지운 테스트 파일은 없다.
- 더한 줄에 `it.skip`·`todo`·`only`·`skipIf`·`runIf`·`context.skip()`가 없다(`git diff` 추가 줄 검색 0건).
- `vitest.config.ts`(`:38` `allowOnly: false`, `:40` `restoreMocks`), `tests/setup.ts`, `scripts/run-vitest.ts:62-72`(skip reporter 추가), `scripts/lib/no-skipped-tests-reporter.ts`, `config/ci/ungated-tests.json`, `config/testing/risk-coverage.json`은 바뀌지 않았다(diff 비어 있음).
- 커버리지 실행의 테스트 이름 중 지난 merge-48에 있고 지금 없는 것은 7개다. 모두 같은 파일에서 이름이 바뀌었거나 같은 규칙의 새 행으로 바뀌었다(6.2절 T1).
- 조건부 정의·제외 목록을 찾으려고 더한 줄의 `existsSync`를 모두 봤다. 5파일이다. 셋(`manual-paired-backend-settings.test.ts`, `product-extension-typecheck.test.ts`, `template-feature-removal-documents.test.ts`)은 사본을 만들 때 없는 대상을 건너뛰는 데만 쓴다. 단언 대상은 줄지 않는다. 둘이 아래 10-01이다.
| 커밋 | 바뀐 것 | 판정 |
|---|---|---|
| `f4d5761`·`0e72c0c`(12-04에 접음) | capabilities 설정 검사 8개를 파일이 있을 때만 정의(`playwright-run-isolation.test.ts:27-44`, `:243-252`) | **약화 → 새 10-01** |
| `c9aa73f`(15-03에 접음) | 목록 하나 검사의 소비자를 `existsSync`로 거름(`vite-build-inputs.test.ts:19-22`) | **약화 → 새 10-01** |
| `5c0b37e`(03-01)·`6d084cf`(16-01)에 접음 | 문서 테스트 목록에 파일 둘을 통째로 더함(`removal-fixture.ts:73-76`). 목록 검사 정규식에 `docs\/`를 더함(`removal-fixture.test.ts:161`) | **약화 → 새 10-02** |
| 14-01·14-02 | 같은 목록에 `template-feature-removal-documents.test.ts`, `manual-paired-backend-settings.test.ts`를 더함(`removal-fixture.ts:77-80`) | 약화 아님. 두 파일의 모든 테스트가 문서를 읽는다 |
| `ce191be`(1101/10-07) | SW 테스트를 가짜 시계로. 5 s씩 최대 4번 넘긴다(`service-worker-runtime.test.ts:2006-2040`). 옛 테스트는 실제 시계와 10 s 제한이라 마감이 약 10 s를 넘으면 실패했다. 새 테스트는 마감 20 s까지 통과한다 | 약화로 세지 않음. 어느 쪽도 5,000 값을 고정하지 않았다. 10 s 상한은 테스트 제한에서 온 우연이다. "마감이 있다"는 규칙은 그대로 잡는다(마감이 없으면 `settled`가 false). 이 fixture는 마커를 한 번만 읽어서(현재 캐시 하나, `:1950-1953`) 반복 4는 필요 없다 |
| `ce191be` | RPC "keeps the operation DRAINING …" 4개에 모든 대기를 30 ms로 자르는 시계를 넘김(`browser-rpc-remediation.test.ts:544-566`) | 약화 아님. 작업 자체 마감 25 ms(`:386-387`)는 그 아래다. DRAINING 단언은 시간과 무관하다. 다만 대상을 잘못 골랐다(2절 1101/10-07 일부) |
| `46359a1`(15-02) | 기록 대조 허용 오차 1% → 256 B. 기대값: 201,500 B가 이제 실패(`feature-shape-growth.test.ts:168-199`) | 강화 |
| `287dc6f`(D7) | 초기 JS 예산 200 → 202 KiB(`config/performance/budgets.json`). 테스트는 주석만 바뀜(`feature-shape-growth.test.ts:131`) | > 15 영역 몫 |
| `6608fef`·`471b001`(01-01·01-02) | Fileserver 503 `IDEMPOTENCY_UNAVAILABLE` 기대: `NOT_APPLIED`·retryable true → `MAYBE_APPLIED`·false | 약화 아님. 수정이 판정을 더 조심스럽게 바꿨다 |
| `05330e3`(04-02) | 던지는 poll `execute`: `PROVIDER_UNAVAILABLE` 재시도 → 즉시 `PROTOCOL_MISMATCH`(`bounded-poll-coordinator.test.ts:911-960`) | 약화 아님. 동작 변경. 동기·비동기 던짐 두 행으로 늘었다 |
| `8e9fb1f`(02-02) | 읽히지 않는 캐시 본문: stage가 fetch 없이 실패 → 다시 받아 씀(`public-response-cache-repair.test.ts:180-233`) | 약화 아님. 동작 변경. 새 describe가 같은 규칙을 더 본다 |
| `23662fb`(1103/05-01) | 계정 삭제 purge 기대: `chunkSweep: "COMPLETED"` → `partitionDeleted: true` + `chunkSweep` 없음 | 약화 아님. 단언이 늘었다 |
| `92d5019`(13-02) | 템플릿 workflow 동일성 비교 전에 release `needs` 한 줄만 바꿔 비교(`product-ci-overlay.test.ts:148-152`) | 약화 아님. 바꾼 줄을 따로 단언하는 새 테스트가 있다 |
| `48c1ab7`(1103/16-05) | 테스트의 `operationId` 문자열 → `testMutationOperationId()`(`tests/helpers/mutation-operation-id.ts`) | 약화 아님. 형 변환이 아니라 운영 함수 `commandMutationIdentity`로 만든다 |
| `dc7c95b`(05-01) | FE-REG-STORAGE `orphanExemptRows`에 한 행 추가(`config/contracts/registry-governance.json:376`) | 판정 안 함. 05·07 영역 몫 |
| 새 테스트의 시간 제한 | 120 s(`manual-paired-backend-settings`, `product-extension-typecheck`의 두 번째), 180 s(`run-output-root-build`), 60 s·120 s(`template-feature-removal-documents`) | 새 테스트의 것이다. 기존 한도를 올린 곳은 없다 |
### 10-01 제거 드릴을 통과시키려고 새 테스트 둘이 검사 대상을 "파일이 있으면"으로 정했다. 템플릿에서 파일 이름이 바뀌어도 검사가 조용히 빠지고, skip 차단은 이를 보지 못한다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백) |
| 관련 관점 | 10, 21, 27, 23, 5, 24 |
| 근거 | ① `tests/unit/playwright-run-isolation.test.ts:27-28`이 `HAS_CAPABILITIES = existsSync("playwright.capabilities.config.ts")`를 둔다. `installed()`(`:41-43`)가 이 값으로 capabilities를 목록에서 뺀다. 그래서 파일이 없으면 결과 폴더 2개(`:135-157`), dev cache 1개(`:175-183`), 포트 3개(`:204-231`), strictPort 1개(`:234-241`), 공유 포트 1개(`:245-252`)가 정의되지 않는다. `:243-244` 주석은 "skip이 아니라 정의하지 않는다. test:unit이 skip을 실패시킨다"고 적는다. ② 실행: browser-file-storage 드릴은 이 설정 파일을 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:134`). 그 사본에서 이 파일은 25개로 통과했다(`FE-GATE-020.txt:10802`). 템플릿과 다른 드릴에서는 33개다(`:114`, `:9910`, `:11721`). 8개가 사라졌는데 skip 보고는 없다. 드릴 요약은 import 그래프로 지운 테스트만 센다(`:11291`, `test-browser-file-storage-runtime-removal.ts:200`). ③ `tests/unit/vite-build-inputs.test.ts:19-22`가 소비자 둘을 `existsSync`로 거른다. `:49-56`은 남은 소비자만 돈다. 개수 단언이 없어 둘 다 없으면 빈 반복으로 통과한다. 그중 측정 스크립트는 샘플과 함께 지우는 파일로 이미 등록돼 있다(`scripts/lib/removable-template-features.ts:37-39`). `tests/unit/product-feature-selection-build.test.ts`는 어느 제거 목록에도 없는 템플릿 파일인데 같은 조건을 받는다. ④ 같은 드릴들은 사본에서 돌 수 없는 테스트를 이름으로 지우는 방법을 이미 쓴다(`test-browser-file-storage-runtime-removal.ts:148-160`의 `ci-workflow-generation.test.ts`, `scripts/test-sample-removal.ts:218-225`). 두 테스트는 그 대신 템플릿에서도 도는 조건을 넣었다. ⑤ `:244`의 ID가 틀렸다. skip 차단은 1101/10-04다(`95e7d110`, `scripts/lib/no-skipped-tests-reporter.ts:8-17`). `0929/10-04`는 §10.8 마지막 검사 발견이다 |
| 발생 조건 | 템플릿이나 제품에서 `playwright.capabilities.config.ts` 또는 `product-feature-selection-build.test.ts`의 이름·위치를 바꿀 때. 다른 참조(`package.json:61`, `scripts/check-test-evidence.ts:384-392`, `scripts/lib/removal-fixture.ts:31`)는 고치고 테스트의 문자열 상수만 놓치면 드러난다. 파일을 아예 지우면 다른 검사가 잡는다(`check-test-evidence.ts:390`의 `readFile`, `test:browser-capabilities`) |
| 영향 | 12-04 수정의 완료 기준(한 checkout 두 실행)을 지키는 capability 서버 포트·출력 격리 검사 8개가 사라져도 `test:unit`이 rc=0이고 skip 보고도 없다. ③은 15-03의 "목록 하나" 검사가 이름이 바뀐 소비자를 보지 않아, 그 소비자에 사본 목록이 다시 생겨도 통과한다 |
| 심각도·우선순위 | Low · P3 — 지금 템플릿에서는 33개, 2개 소비자가 모두 돈다. 닿는 경로는 이름 바꾸기뿐이다. 그러나 이 저장소가 skip을 막는 이유("남은 skip으로 그 테스트가 지키던 규칙이 조용히 사라진다", `no-skipped-tests-reporter.ts:8-12`)와 같은 결과를 만든다 |
| 확실성과 남은 가정 | 사본에서 8개가 사라지는 것은 게이트 로그로 확인했다(E2). 이름 바꾸기 경로는 코드로 판단했다(E1). 이름을 바꾸는 실행은 하지 않았다 |
| 결정의 근거 | [확인한 사실] 세 통합 수정은 드릴 사본에서 난 타입 오류·ENOENT를 고치려고 들어갔다(README §16.3, `c9aa73f` 본문). [추론] 조건을 "파일이 있는가"로 둔 것은 드릴 사본과 템플릿을 구분할 정보를 테스트가 읽지 않아서다. 그 정보는 이미 저장소에 있다: 드릴이 지우는 파일(`test-browser-file-storage-runtime-removal.ts:134`), 샘플과 함께 지우는 파일(`removable-template-features.ts:37-39`) |
| 이해 비용 | 드릴 사본에서 실패하는 테스트를 맞추는 방법이 셋이다(드릴이 이름으로 지움, 문서 테스트 목록, 테스트 안의 `existsSync`). 고른 기준이 적혀 있지 않다. 테스트 수가 상태마다 다른 것은 로그 세 곳을 맞춰 봐야 안다 |
| 최소 개선 방향 | ⓐ 조건을 소유자 상태로 바꾼다. capabilities 검사를 별도 파일(예: `tests/unit/playwright-capabilities-run-isolation.test.ts`)로 옮겨 정적 import를 되살리고, browser-file-storage 드릴이 그 파일을 `ci-workflow-generation.test.ts`처럼 이름으로 지운다. `vite-build-inputs`는 `removable-template-features.ts`로 샘플 설치 여부를 읽어, 설치돼 있으면 측정 스크립트가 있다고 단언하고 템플릿 테스트는 거르지 않는다. ⓑ 지금 구조를 두고, 조건이 거짓이면 드릴 사본인지(드릴이 넘기는 표시)를 단언한다. ⓒ 현 상태를 두고 주석 ID만 1101/10-04로 고친다 |
| 대안 비교 | ⓐ 템플릿에서 이름을 바꾸면 import·ENOENT로 실패한다. 드릴은 지운 테스트를 자기 코드에 적는다. 파일 하나가 는다. ⓑ 파일은 그대로지만 드릴과 테스트 사이에 계약이 하나 는다. ⓒ 가장 싸지만 공백이 남는다. [추론] ⓐ를 고른다. 같은 드릴이 이미 쓰는 방식이라 방법이 하나로 준다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 파일 하나 이동, 드릴 `rm` 한 줄, 테스트 몇 줄 |
| 재검토 조건 | capability 설치 여부를 읽는 공용 함수(설치 manifest)가 생기면 그것을 조건으로 쓴다 |
| 완료 기준 | 템플릿 사본에서 `playwright.capabilities.config.ts`의 이름을 바꾸면(다른 참조는 고친 상태) `test:unit`이 실패한다. `product-feature-selection-build.test.ts`의 이름을 바꾸면 `vite-build-inputs.test.ts`가 실패한다. 세 capability 드릴과 샘플 제거 드릴은 그대로 통과한다 |
| 검증 방법 | 위 두 이름 바꾸기 변이 + `test:browser-file-storage-removal`, `test:sample-removal` |
| 담당·기한·상태 | 미정 · 미정 · 신규(1105 통합 수정 `f4d5761`·`0e72c0c`, `c9aa73f`에서 생김) |
### 10-02 문서를 읽는 테스트 하나 때문에 파일이 통째로 capability 드릴 셋에서 빠져, 문서와 무관한 테스트 15개도 그 드릴에서 돌지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검출 공백, 제거 상태) |
| 관련 관점 | 10, 21, 27, 17, 5 |
| 근거 | ① `scripts/lib/removal-fixture.ts:70-81`의 파일은 문서를 복사하지 않는 사본에서 지워진다(`:84-90`, `:160-162`). 단위가 파일이다. 03-01 통합 수정이 `tests/unit/backend-contract-pin.test.ts`(`:73-74`)를, 16-01이 `tests/unit/feature-tracked-files.test.ts`(`:75-76`)를 더했다. ② `backend-contract-pin.test.ts`의 15개 중 문서를 읽는 것은 `:293-303` 하나다(`codesPossiblyAfterWrite`, `:263-275`가 계약 문서를 읽는다). 나머지 14개(`:150-253`)는 pin·답 표 JSON(`:115-140`)과 운영 판정 함수(`envelopeFailureEffect`, `invitesKeyedResend`, `src/adapters/http/backend-envelope.ts`)를 본다. 그중 10개는 `8a44226`에도 있었다(`git show 8a44226:tests/unit/backend-contract-pin.test.ts`의 `:90-140`). 그때 목록은 2파일이라 이 10개가 capability 드릴 셋에서 돌았다. `feature-tracked-files.test.ts`는 3개 중 `:25-30` 하나가 문서를 읽지 않는다. ③ 실행: 샘플 제거와 생성 기능 드릴에서는 `backend-contract-pin.test.ts`가 15개로 돈다(`FE-GATE-020.txt:285`, `:1797`, `:4726`, `:6565`). 선택 레시피·browser-file-storage·realtime 드릴의 unit 실행(`:9815-10096`, `:10731-10974`, `:11626-11885`)에는 목록 6파일이 하나도 없다. ④ 목록을 지키는 검사는 각 파일 본문에 `README.md|CHANGELOG.md|docs/`가 있는지만 본다(`tests/unit/removal-fixture.test.ts:155-163`). 이번에 `docs\/`가 더해졌다(`:161`). `backend-contract-pin.test.ts`는 주석 한 줄(`:259`)로 이 검사를 통과한다. 실제 문서 경로는 JSON에 있다(`config/contracts/backend-contract-pin.json:42`) |
| 발생 조건 | capability를 지운 드릴이나 제품에서, 지운 코드가 Envelope 판정·pin이 쓰는 모듈에 닿을 때 |
| 영향 | capability 제거 드릴이 증명한다는 "지운 뒤에도 코드가 빌드되고 테스트가 돈다"(`removal-fixture.ts:49-55`)의 범위가 좁아진다. 지금 세 capability는 이 테스트들이 보는 모듈에 닿지 않는다. 그래서 이번에 놓친 결함은 찾지 못했다 |
| 심각도·우선순위 | Low · P3 — 템플릿의 `test:unit`과 샘플·생성 드릴은 15개를 모두 돈다. 빠진 범위는 capability 드릴 셋뿐이다 |
| 확실성과 남은 가정 | 목록·실행 여부는 코드와 게이트 로그로 확인했다(E1·E2). 빠진 테스트가 capability 제거 뒤에 무엇을 잡았을지는 추론이다 |
| 결정의 근거 | [확인한 사실] 목록 단위는 파일이다(`removal-fixture.ts:84-90`). §16.3은 "새 테스트 둘이 계약 문서와 매뉴얼을 읽는다"고만 적는다. [추론] 문서를 읽는 테스트를 기존 파일에 더한 것이 원인이다 |
| 이해 비용 | 목록에 파일을 넣는 사람은 그 파일의 나머지 테스트도 드릴에서 빠진다는 것을 목록 주석(`:62-69`)에서 알 수 없다 |
| 최소 개선 방향 | ⓐ 문서를 읽는 테스트를 따로 둔다. `backend-contract-pin.test.ts:255-303`을 새 파일(예: `backend-contract-pin-document.test.ts`)로 옮기고 목록에는 그 파일만 둔다. `feature-tracked-files.test.ts:25-30`은 목록 밖 파일로 옮긴다. ⓑ 목록 검사를 `readFile`·`readFileSync` 인자의 문서 경로로 좁혀 주석으로 통과하지 못하게 한다. ⓒ capability 드릴이 그 계약 문서 하나만 복사한다 |
| 대안 비교 | ⓐ 원인을 없앤다. 파일이 둘 는다. ⓑ 검사만 정확해지고 빠지는 범위는 그대로다. ⓒ capability 드릴이 문서를 복사하지 않는 이유(`removal-fixture.ts:49-55`)와 어긋난다. [추론] ⓐ를 고르고 ⓑ를 함께 한다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | 파일 분리 2건, 목록 2줄 교체, 정규식 하나 |
| 재검토 조건 | capability 드릴이 문서를 복사하게 바뀌면 목록 자체가 필요 없다 |
| 완료 기준 | 세 capability 드릴의 unit 실행에 문서를 읽지 않는 pin 테스트 14개가 나온다. 목록의 각 파일은 모든 테스트가 문서를 읽는다 |
| 검증 방법 | FE-GATE-020 로그에서 세 드릴의 unit 목록 확인 |
| 담당·기한·상태 | 미정 · 미정 · 신규(1105 통합 수정 `5c0b37e`(03-01), `6d084cf`(16-01)에서 생김) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 03·07 | — | — | 변이는 테스트 검출력을 보려는 것이다. `src/contracts/api-operations.ts:84`의 `?? "NONE"`가 1103/16-01 뒤 닿지 않는 분기가 된 것은 07 영역에 넘긴다(6.2절 C1) |
| 2 | 구조적 성숙도 | > 16 | — | — | — |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | **P** — 플랫폼 규칙을 샘플 없이 시험할 자리가 생겼다(`createRuntimeContractHttpExecutor`, fixture 기능 mock). 드릴에 맞추는 방법이 파일 존재 조건과 파일 단위 제외라, 이름 바꾸기와 테스트 추가가 검사를 함께 옮긴다(10-01, 10-02) |
| 4 | 인지 부하 | 적용 | M2 / M2 | E1 | **P** — 한 unit 파일이 한 머지에서 몇 번, 어느 사본에서 도는지 알려면 `gates.json`, 드릴 다섯, 제외 목록, 테스트 안 조건을 맞춰야 한다(13번, 1101/10-06, 10-01) |
| **5** | 위험 가시성 | 적용 | M2 / M2 | E2 | **P** — 드릴 요약은 import 그래프로 지운 테스트만 센다. 조건으로 사라진 8개와 목록으로 지운 6파일은 어디에도 안 나온다(10-01, 10-02) |
| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2(변이 10-R4) | **O** — §10.8 마지막 검사(0929/10-04)에 테스트가 생겨 L01이 2건으로 잡힌다. Envelope·scope 실패 경계가 모두 테스트에 걸린다 |
| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | — |
| 8 | 디버깅 가능성 | 적용 | M2 / M3 | E2 | **O** — 새 테스트 이름이 규칙을 그대로 말한다("discards a valid %s success that arrives after its scope stopped being current", "honours MAX_RETRY_ATTEMPTS %i …"). `vite-build-inputs`는 빠진 파일 이름과 고칠 곳을 메시지로 낸다(`:67-70`) |
| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | **P** — `scopeSnapshot` 4벌, `as never` scope 10곳, `deferred()` 7벌(1101/10-08). `--no-file-parallelism` 이유 없음 |
| **10** | **테스트 성숙도** | 적용 | 목표 M3 / 확인 M3 | E1·E2(게이트, 변이 4종 10-R1~R4) | **P** — 지난 생존 변이 L01·R2b가 이제 잡힌다. 샘플 밖으로 옮긴 H53·L02도 잡힌다(4종 모두 기대한 테스트, 기대한 이유). 커버리지 네 지표 +0.2%p, 하한 72개 그대로. 남은 것: 드릴 사본의 검출 공백 둘(10-01, 10-02), 1초를 자는 RPC 테스트 3개(1101/10-07 일부) |
| 11 | 데이터 성숙도 | > 05 | — | — | — |
| 12 | 동시성 성숙도 | 적용(테스트 격리) | M3 / M3 | E2 | **O** — 격리 설정은 그대로다(`vitest.config.ts:40`, `tests/setup.ts`). listener 정리 테스트가 interaction signal까지 본다. 새 run isolation 테스트는 빈 포트를 쓴다(12 영역 몫). 실제 러너 사양은 미확인(U-1) |
| 13 | 확장성 | > 11·15 | — | — | — |
| **14** | **성능 성숙도** | 적용(테스트 실행 비용) | M2 / M1 | E2 | **P** — `tests/unit` 시간 합 133.1 → 175.7 s(+32%). 도구·자식 실행 테스트 76%(1101/10-05 커짐). 한 머지에 `tests/unit` 13번. FE-GATE-020 1,237 s. 1초를 자는 RPC 테스트 3개(1101/10-07 일부). setup 누적 50.73 s |
| 15 | 보안 성숙도 | 적용(보안 규칙의 테스트) | M3 / M2 | E1·E2 | **O** — 쿠키 쓰기 CSRF 조립 행렬 테스트(`tests/unit/rest-profile-contract.test.ts`)는 바뀌지 않았고 통과한다. 이번 라운드에 변이로 다시 보지는 않았다 |
| 16 | 의존성 성숙도 | > 13 | — | — | — |
| 17 | API / Contract 성숙도 | 적용(계약 테스트) | M3 / M3 | E2 | **P** — pin 테스트가 15개로 늘었고 Envelope 판정을 답 표 행마다 본다. 그러나 capability 드릴 셋에서는 파일째 빠진다(10-02). FE-REG-API `authProfileId`(지난 H20)는 다시 보지 않았다(5절) |
| 18 | 배포 성숙도 | > 13 | — | — | — |
| 19 | 설정 성숙도 | 적용(러너·런타임 설정) | M3 / M3 | E1·E2(변이 10-R1) | **P** — `MAX_RETRY_ATTEMPTS`·`REQUEST_TIMEOUT_MS`가 샘플 없이 고정됐다(1105/10-01, H53 잡힘). `--passWithNoTests` 3곳 남음 |
| **20** | 개발자 경험 | 적용 | M2 / M3 | E2 | **P** — `test:all`이 `test:coverage`의 Vitest 경로를 모두 돌고 테스트가 그 관계를 지킨다(0929/10-05). FE-GATE-020이 1,237 s다 |
| **21** | **Guardrail 성숙도** | 적용 | M3 / M2 | E2 | **P** — skip·todo·only 차단은 그대로다. 통합 수정 셋이 검사를 skip 차단 밖에서 좁혔다: 조건부 정의(10-01), 파일 단위 제외와 주석으로 통과하는 목록 검사(10-02) |
| 22 | 추상화 성숙도 | 적용(테스트 도우미) | M2 / M2 | E1 | **P** — 새 공유 도우미(`tests/helpers/mutation-operation-id.ts`)가 운영 함수로 ID를 만든다. scope fixture 복사본은 그대로다 |
| 23 | 일관성 | 적용 | M2 / M2 | E1 | **P** — 드릴 사본에 테스트를 맞추는 방법이 셋으로 갈렸다(드릴이 이름으로 지움 `test-sample-removal.ts:218-225`, 문서 목록, 테스트 안 `existsSync`)(10-01). `deferred()` 7벌 |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | **P** — 테스트 이름은 범위를 맞게 말한다. 코드 주석의 근거 ID가 틀린 곳이 있다(`playwright-run-isolation.test.ts:244`의 `0929/10-04`, 10-01 ⑤). 1101/10-07 수정 커밋은 느린 테스트를 잘못 짚었다 |
| 25 | 조직 확장성 | - | 작성자 1인 | — | — |
| 26 | Ownership 성숙도 | 부분 적용 | M2 / M1 | E1 | **P** — `ungated-tests.json` 항목에 담당·재검토 시점이 없다(12 영역) |
| **27** | **삭제 가능성** | 적용 | M3 / M2 | E2 | **P** — 샘플을 지워도 플랫폼 규칙 테스트 둘이 남는다(1105/10-01, 로그로 확인). capability를 지우면 문서와 무관한 테스트 15개가 함께 빠지고(10-02), 조건부 8개가 말없이 사라진다(10-01) |
| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | — |
집계(적용 19개, `>`·`-` 제외): 충족 4(6, 8, 12, 15) · 부분 충족 15 · 미충족 0 · 미검증 0. 지난 라운드는 충족 4(8, 12, 15, 24) · 부분 충족 15였다. 6은 L01이 이제 잡혀 올렸다(10-R4). 24는 틀린 근거 ID 때문에 내렸다.
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 샘플을 지운 사본에서 조립 루트 `runtime-adapters.ts:538`을 바꾸는 변이 | 사본 드릴 실행이 비싸다. 정적으로는 그 사본에서 이 한 단계를 지키는 테스트가 없다(템플릿에서는 `reference-runtime-composition.test.ts`가 지킨다). 수정 커밋 `00b12b3`이 한계로 적었다 | `test:sample-removal` 사본에서 `:538`을 `{ ...config, MAX_RETRY_ATTEMPTS: 2 }`로 바꾸고 `test:unit` |
| 10-01의 이름 바꾸기 경로 | 실행하지 않았다(E1). 파일이 없는 상태의 결과는 드릴 로그로 봤다(E2) | 10-01 완료 기준의 실행 |
| 1101/10-07 남은 RPC 3개에 같은 시계를 넘겨도 테스트 뜻이 그대로인지 | 코드만 봤다. 세 테스트는 닫힘 확인 대기와 두 번째 스트림 허용을 본다(`:389`, `:412`, `:588`) | 시계를 넘긴 뒤 같은 단언과 junit 시간 |
| FE-REG-API `authProfileId`(지난 H20) | 이번에 다시 보지 않았다. 빠른 계층 fixture는 여전히 `ANONYMOUS`다(`tests/helpers/external-contract-fixture.ts`) | 다음 변이 묶음 |
| 실제 CI 러너 실패율 | CI 꺼짐(U-1) | U-1 뒤 FE-GATE-005·020을 반복 |
## 6. 실행 기록
이 영역의 리뷰어는 직접 아무것도 실행하지 않았다. 요청은 `/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template--claude-worktrees-happy-easley-233d07/5b935f37-0052-476e-bf8e-dcb9a2640c1a/scratchpad/r5/requests/10.md`, 패치는 같은 폴더 `10/`에 있다. 네 패치 모두 `bbde570` 작업 트리에 `git apply --check`로 맞는 것을 미리 확인했다(상태 변경 없음). 오케스트레이터 배치가 desktop checkout에서 한 항목씩 돌렸다(2026-11-06 04:34:30~04:34:35, local env, load 2.3). 각 로그 머리에 `head bbde570796b0…`, 끝에 `restore=clean`이 있다. 무변이 대조는 돌리지 않았다. 같은 명령의 무변이 통과는 `FE-GATE-005.txt`의 `test:unit`(208파일 3,056개, `runtime-adapters` 22개, `session-route-access` 6개, `http-execution-v3` 포함)이 보인다.
| ID | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 10-R1 | `node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts` | `runtime-adapters.ts:307` `maxRetryAttempts` → `2` | 1 | 22개 중 2 실패, 20 통과. 실패: "honours MAX_RETRY_ATTEMPTS 0 / 1 …" — `expected "vi.fn()" to be called 1 / 2 times, but got 3 times`. 기대와 같다 |
| 10-R2 | `node scripts/run-vitest.ts run tests/unit/session-route-access.test.ts` | `navigation-policy.ts:40` → `show-sign-in` | 1 | 6개 중 1 실패, 5 통과. 실패: "answers a recovery-pending session with { allowed: false, action: 'wait-for-session' }" — deep equal 불일치. 기대와 같다 |
| 10-R3 | `node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts` | `http-execution-v3.ts:663` 삭제(R2b) | 1 | 72개 중 3 실패, 69 통과. 실패: "removes the listeners … after an answer / a caller abort / an interaction cancel" — `expected [] to deeply equal [ [Function forwardCallerToLifetime] ]`. 기대와 같다 |
| 10-R4 | `node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts` | `http-execution-v3.ts:1494` → `if (false)`(L01) | 1 | 72개 중 2 실패, 70 통과. 실패: "discards a valid read / command success that arrives after its scope stopped being current" — `expected { kind: 'SUCCESS', … } to match object { kind: 'CONTRACT_VIOLATION', … }`. 기대와 같다 |
로그: `desktop:/tmp/claude-gates/r5/batch/out/R5-10-R1.log`~`R5-10-R4.log`.
### 6.1 변이
| ID | 지키는 규칙(지난 ID) | 바꾼 곳(`bbde570`) | 결과 | 잡은 테스트 |
|---|---|---|---|---|
| 10-R1 | `MAX_RETRY_ATTEMPTS`가 실행기에 닿는다(1105/10-01, H53) | `src/bootstrap/runtime-adapters.ts:307` | 잡힘(2) | `tests/unit/runtime-adapters.test.ts:515-550` "honours MAX_RETRY_ATTEMPTS 0/1" |
| 10-R2 | 복구 중 세션은 보호 라우트에서 기다린다(1105/10-01, L02) | `src/presentation/routes/navigation-policy.ts:40` | 잡힘(1) | `tests/unit/session-route-access.test.ts:32-41` "answers a recovery-pending session …" |
| 10-R3 | interaction signal listener 정리(1105/10-02, R2b) | `src/adapters/http/http-execution-v3.ts:663` | 잡힘(3) | `tests/unit/http-execution-v3.test.ts:816-867` "removes the listeners …" |
| 10-R4 | §10.8 오래된 scope의 성공 응답 버림(0929/10-04, L01) | `src/adapters/http/http-execution-v3.ts:1494` | 잡힘(2) | `tests/unit/http-execution-v3.test.ts:578-620` "discards a valid … success …" |
집계: 4종 모두 잡혔다. 지난 라운드에 살아남은 2종(L01, R2b)과 샘플 밖으로 옮긴 규칙 2종(H53, L02)이다. 1105/10-01의 두 테스트 파일은 샘플을 지운 사본에서도 돈다(`FE-GATE-020.txt:133`, `:311`). 테스트가 샘플 코드를 읽지 않으므로 그 사본에서도 같은 변이를 잡는다고 판단한다(사본에서 변이를 넣어 돌리지는 않았다, 5절).
### 6.2 그 밖의 분석 (노트북, desktop 산출물 사본)
| ID | 방법 | 결과 |
|---|---|---|
| J1 | `unit.xml`의 파일별 시간(208줄)을 파일의 import 대상(`src`/`scripts`/둘 다/없음)으로 분류해 합산. 같은 방법으로 지난 merge-48 `unit.xml`(194줄, `8a44226`의 파일 내용) | 지금 합 175.7 s: `src`만 117파일 19.7 s(11%), `scripts`만 59파일 100.1 s(57%), 둘 다 15파일 23.4 s(13%), 없음 17파일 32.5 s(19%). 지난 합 133.1 s: 117파일 18%, 51파일 54%, 12파일 11%, 14파일 17% |
| D1 | `git diff 8a44226 bbde570 -- <영역 경로>`의 지운 `expect`·`it` 줄, 더한 skip·`existsSync`·시간 한도를 파일별로 대조 | 3.0절 표 |
| D2 | `FE-GATE-005.txt`와 `FE-GATE-020.txt`에서 `tests/unit`을 포함한 Vitest 실행(파일 160개 이상)을 셈 | 13번(005: `:312`, `:781`. 020: `:322`, `:943`, `:1855`, `:2493`, `:4799`, `:5274`, `:6625`, `:7332`, `:10096`, `:10974`, `:11885`) |
| S1 | FE-GATE-020의 드릴별 unit 실행 구간에서 목록 6파일, `playwright-run-isolation`, `session-route-access`, `runtime-adapters` 줄을 셈 | 샘플·생성 드릴 4구간: 목록 6파일 있음, pw 33개, sra 6개, ra 22개. capability 드릴 3구간: 목록 0파일, pw 33·25·33개 |
| T1 | 커버리지 실행 junit의 테스트 이름(classname + name)을 지난 merge-48과 비교 | 지난 3,863개 → 지금 4,079개. 새 223개. 없어진 7개: `fileserver-upload` 503 `IDEMPOTENCY_UNAVAILABLE` 행(같은 행이 `MAYBE_APPLIED`로), `feature-shape-growth` "1% off"(→ "a few hundred bytes off"), `http-execution-v3` listener 2개(→ 3개), `opfs-worker-runtime` 늦은 put(→ 객체 수 1·3·8 세 행), `public-response-cache-repair` "retryable"(→ "unreadable"), `bounded-poll-coordinator` 던지는 executor(→ 두 행) |
| C1 | `coverage-summary.json`과 `risk-coverage.json`을 지난 merge-48 것과 비교 | 아래 표 |
C1 커버리지 비교(두 값 모두 merge 단계 FE-GATE-005, CI env):
| 지표 | `8a44226` (merge-48) | `bbde570` | 차이 |
|---|---|---|---|
| lines | 86.31% (18,466 / 21,394) | 86.51% (18,567 / 21,461) | +0.20%p |
| statements | 84.03% (19,303 / 22,971) | 84.23% (19,412 / 23,044) | +0.20%p |
| functions | 90.44% (3,709 / 4,101) | 90.63% (3,737 / 4,123) | +0.19%p |
| branches | 80.92% (15,291 / 18,896) | 81.15% (15,400 / 18,976) | +0.23%p |
| 커버리지 실행 | 316파일 3,869개 | 332파일 4,085개 | +16파일 |
| 위험 하한 | 418/418 모듈, 72개 PASS | 418/418 모듈, 72개 PASS | 하한 값 72개 모두 같음 |
- 합계 하한은 lines 75, statements 73, functions 80, branches 68이다(`risk-coverage.json` `results`). 여유는 모두 11%p 이상이다.
- `config/testing/risk-coverage.json`은 바뀌지 않았다. `src` 파일 추가는 없어 모듈 수가 같다.
- 얇은 여유는 지난과 같다: `src/adapters/storage/indexeddb/indexeddb-runtime.ts` lines 79.13(하한 79), branches 72.38(72).
- 파일별로 줄어든 곳 7개. 모두 그 파일의 코드나 타입이 이번 범위에서 바뀌었다: `server-state-scope-runtime.ts` lines 97.97 → 96.42%(02-01이 13줄 더하고 2줄 안 닿음, 하한 85), `runtime-adapters.ts` 92.9 → 92.4%, `external-contract-runtime.ts` branches 83.6 → 83.4%, `load-runtime-config.ts` branches 87.0 → 86.2%, `app-shell.tsx` branches 83.3 → 81.2%, `service-worker-static-assets.ts` lines 85.5 → 85.4%, `api-operations.ts` branches 10/10 → 9/10.
- `api-operations.ts`는 파일이 바뀌지 않았다. `:84` `contract.responseEnvelope ?? "NONE"`의 오른쪽이 지난 37번에서 0번이 됐다(lcov `BRDA:84,0,1`). 1103/16-01이 `responseEnvelope`를 필수로 만들어 닿지 않는 분기가 됐다. 테스트 약화가 아니다. 07 영역에 넘긴다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 10-01 | Low · P3 | 구조적 위험 | 통합 수정이 새 테스트 둘의 검사를 "대상 파일이 있으면"으로 정해, 드릴 사본에서 8개가 말없이 사라지고 템플릿에서 이름을 바꿔도 같다. skip 차단은 이를 보지 못하고 주석의 근거 ID도 틀렸다 | `tests/unit/playwright-run-isolation.test.ts:27-44`, `:243-252`; `tests/unit/vite-build-inputs.test.ts:19-22`, `:49-56` |
| 10-02 | Low · P3 | 구조적 위험 | 문서를 읽는 테스트 하나 때문에 `backend-contract-pin.test.ts`·`feature-tracked-files.test.ts`가 파일째 capability 드릴 셋에서 빠져 문서와 무관한 15개도 돌지 않고, 목록 검사는 주석으로 통과한다 | `scripts/lib/removal-fixture.ts:70-81`; `tests/unit/backend-contract-pin.test.ts:150-253`, `:259`; `tests/unit/removal-fixture.test.ts:155-163` |
이월(새 발견으로 세지 않음): 1101/10-07(일부, RPC 3개), 1101/10-05(커짐)·10-06·10-08(결정 대기), `--no-file-parallelism`, `--passWithNoTests`, R1, R6, `tsc-diagnostics-parser` 제외(12 영역). 모두 Low.
@@ -0,0 +1,236 @@
# 영역 11 — 테스트: 브라우저·릴리스·규모
> 검토일 2026-11-06 · 기준 `bbde570`(`bbde570796b0a648bae65c2c0568fca860a3ba4e`, PR B 끝, 브랜치 `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `tests/support/browser`, `playwright*.config.ts`. 판정에 필요해서 함께 읽은 것: `scripts/write-a11y-report.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/contracts/release-artifacts.ts:833-869`, `scripts/lib/ci-artifact-validator.ts:205`, `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `scripts/run-and-validate-provider.ts:254-293`, `scripts/check-test-evidence.ts:280-305`, `scripts/run-ci-gate.ts:210-235`, `scripts/lib/run-isolation.ts:127-145`, `eslint.config.ts:930-943`, `.gitea/workflows/quality-gates.yml`(merge job·글꼴 단계), `config/ci/gates.json`(FE-GATE-008·009), `CHANGELOG.md:20-60`, `tests/unit/a11y-report.test.ts`
> 깊게 본 관점: 10, 21, 5, 8, 18
> 이번 라운드 확인 지시: (1) 1105/11-01(strict fixture 증명)과 merge 때의 lint 이름 변경 `use` → `provide`. (2) 1103/11-01 BREAKING(`757d1c7`, `a11y.json` schemaVersion 2): 코드와 BREAKING CHANGE footer·CHANGELOG 안내, FE-GATE-009가 남긴 `a11y.json`. (3) FE-GATE-008·009 로그의 수와 skip을 지난 라운드와 비교. (4) 1103/11-02~11-04와 README §16.5·§16.6의 이월 항목
> 영역 판정(35.8): **조건부 사용 가능.** CI env merge 실행(`bbde570-ci`)에서 FE-GATE-008·009가 통과했다(e2e 222 통과·4 skip, capability 69, storybook 1, visual 6, a11y 60). 1105/11-01은 커밋된 test가 fixture의 실패 방향까지 고정한다(변이 셋이 세 엔진에서 모두 잡혔다, 11-R1). 1103/11-01은 `a11y.json`이 실패 화면 라우트를 `notChecked`로 적는다(CI env 산출물, 생성 기능 상태 11-R3). 다음은 그대로 믿지 않는다. (a) 그 분류를 지키는 test가 없고, 기록이 없는 라우트는 "검사함"으로 센다. 기록 호출 한 줄을 바꾸자 상세 라우트가 passed로 적혔고 명령은 모두 rc=0이었다(새 11-01, 11-R2). (b) `test:system`은 이 desktop에서 사전 점검이 이유와 함께 멈춘다. 그래서 1103/11-03·11-04의 완료 기준은 여전히 돌릴 수 없다. (c) CI 러너 위 실행은 없다(U-1)
ID 표기: 이번 라운드 새 발견은 `11-01`부터 쓴다. 라운드 밖에서는 `1106/11-01`이다. 지난 라운드는 `1105/11-NN`(2026-11-05), 그 전은 `1103/…`, `1101/…`, `0929/…`다. `11-Rk`는 `scratchpad/r5/requests/11.md`의 배치 실험이다(6절).
## 0. 결론
- **1105/11-01은 고쳐졌다.** fixture의 마지막 판정을 `browserFailureVerdict` fixture로 뺐다(`tests/support/browser/strict-browser-test.ts:27-33`, `:54-67`, `:95`). 증명 spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾸고, teardown에서 기록 줄을 정확히 대조한다(`tests/e2e/preload-use.spec.ts:180-202`). 지난 완료 기준 셋을 커밋된 test가 본다. 기록을 버리면 `:209-216`이 실패한다(기대 1줄). 무시 정규식을 넓히면 `:234-252`가 실패한다(기대 4줄). 지연시킬 청크가 없으면 `:146-149`가 실패한다. 기본 판정이 test를 실패시키는지는 `test.fail()` test가 본다(`:259-267`). CI env FE-GATE-008에서 이 spec 6건이 세 엔진 모두 기대대로 끝났다. 변이 셋(기록 버림, 정규식 `/.*/u`, 기본 판정 무력화)을 함께 넣자 세 엔진에서 정확히 그 세 test가 각자 다른 메시지로 실패했다(9 failed, 9 passed, 11-R1).
- **merge 때의 `use` → `provide` 이름 변경은 동작을 바꾸지 않는다.** `react-hooks/rules-of-hooks`는 `tests/support/browser/**`에서만 꺼져 있다(`eslint.config.ts:939-941`). 그래서 spec 파일의 fixture 콜백은 `use`라는 이름을 쓸 수 없다. 다른 spec 둘도 이미 `provide`다(`tests/e2e/boot-module-failure.spec.ts:47`, `tests/e2e/old-tab-chunk-recovery.spec.ts:153`). Playwright는 첫 인자의 구조 분해만 읽고 둘째 인자는 위치로 넘긴다. 실행 증거: 기록용 판정을 쓰는 `records a modulepreload the page never runs`가 세 엔진에서 통과했다. 이 test는 기본 판정이 돌면 자기 `preloadunused:` 한 줄로 실패한다. 그러니 바꾼 판정이 실제로 쓰였다. FE-GATE-002(lint)는 rc=0이다.
- **1103/11-01은 고쳐졌다.** FE-GATE-009(CI env, 03:53)가 쓴 `a11y.json`은 schemaVersion 2다. `scope`에 9개 라우트, `notChecked`에 `REFERENCE_RESOURCE_DETAIL`과 이유가 있다. 게이트 로그에도 그 한 줄이 찍혔다. 코드는 BREAKING CHANGE footer, `CHANGELOG.md:28`(먼저 할 일 5단계), `:53`(표 행)과 같다. 템플릿 안 소비자는 `ci-artifact-validator` 하나이고 같은 schema를 쓴다. `create:feature sample-feature --with-create` 뒤에는 `SAMPLE_DETAIL`도 `notChecked`로 갔고 `SAMPLE_LIST`·`SAMPLE_CREATE`는 `scope`에 남았다(11-R3). 매뉴얼 주장(`docs/manual/reference/create-feature.md:98`)과 같다.
- **새 11-01(Low·P3): `notChecked` 분류를 지키는 test가 없다.** 기록 파일이 없는 라우트는 "검사함"으로 센다(`scripts/lib/a11y-data-state.ts:50`, `:61`). unit test는 lib 함수만 보고, schema는 `scope`+`notChecked`=설치 라우트만 본다. `tests/e2e/accessibility.spec.ts:83`의 기록 호출 한 줄을 `null`로 바꾸자 라우트 test 10건이 통과하고 report도 rc=0이었다. `a11y.json`은 `REFERENCE_RESOURCE_DETAIL`을 포함한 10개 모두를 `scope`(passed)로, `notChecked: []`로 적었다(11-R2).
- **FE-GATE-008·009 수(지난 라운드 merge-48과 비교).** e2e 205 → 226(+21: preload-use +9, reference-save +9, SW update +3). skip 3 → 4: 새 test `service-worker-update.spec.ts:302`가 같은 firefox quarantine으로 빠진다. capability 66 → 69(OPFS purge test가 두 경우로 나뉨), "23 cases x 3 engines, zero skipped". storybook 1, visual 6 그대로(골든 5장은 15-05에서 다시 찍음). test evidence 416 → 433 파일. 사라진 test는 없다(파일·엔진별 수 비교). 재시도·flaky 없음. FE-GATE-009는 60건, 이름이 같다.
- **FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(1105/12-01, 1105/11-02를 합친 것).** 사전 점검을 건너뛴 `test:system`(013-parts)은 114건 중 96 통과, 18 실패다. 18건의 이름은 지난 라운드와 같다. 6건은 여전히 bwrap 원인을 보여 주지 않는다. 1103/11-03·11-04의 완료 기준은 이 호스트에서 돌릴 수 없다.
- **지난 발견 재판정(2절):** 고쳐짐 2(1105/11-01, 1103/11-01), 일부 4(1105/11-02는 영역 12의 12-01로 집계, 1103/11-02·11-03·11-04는 완료 기준 실행 남음), 남음 6(0929/11-02·11-04·11-05 잔여·11-07, FOLLOW-UP 2). 재발·틀린 발견 0. README §16.6은 이 영역 이월 중 0929/11-04만 적었고 0929/11-02·11-05·11-07과 FOLLOW-UP 둘은 빠졌다.
- **검사를 약하게 만든 수정:** 새 결함으로 셀 것은 없다. 판정 override 자리가 하나 늘었고(노출은 `allowedBrowserFailure: /.*/`와 같다), `a11y.json` schema가 어떤 분할이든 받게 됐고(11-01에 포함), firefox skip이 하나 늘었다(기록된 quarantine). 3.3절 표.
## 1. 범위 (36.1)
| 항목 | 기록 |
| --- | --- |
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 11. `8a44226..bbde570`에서 이 영역 test·설정 경로 18파일이 바뀌었다(+609/−150). 함께 읽은 script 둘(`write-a11y-report.ts`, `check-system-test-prerequisites.ts`)을 더하면 20파일 +759/−194다. 골든 5장 교체 |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree(브랜치 `docs/maturity-review-2026-11-06`, HEAD = 기준)에서 읽기만 했다. 이 영역 수정 커밋: `e0255299`(1105/11-01), `757d1c73`(1103/11-01). 영역 밖이 이 경로를 건드린 것: `9655958b`(1105/12-01 사전 점검), `f4d5761a`·`0e72c0c1`(1105/12-04 실행 격리), `e02f252d`(1105/15-05 골든), `4f3c10bc`(1105/08-01 reference-save), `aaa782ba`(1105/06-03 SW update), `23662fb2`(1103/05-01 OPFS), `a37ebba3`(0929/12-03 architecture test). 합친 커밋 7개(`19d10538`, `7af80859`, `57c34ea6`, `d5a70b42`, `1a29d4aa`, `703a3355`, `b8d53c9a`) |
| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음. 브라우저 테스트는 FE-GATE-008(e2e·capability·storybook·visual·test evidence)과 FE-GATE-009(`test:a11y`, 수동 기록 형식), 샌드박스 경계는 FE-GATE-013(`test:system`)이 merge 단계에서 돈다(`config/ci/gates.json:1893-1931`). CI에서는 gate마다 matrix job이 따로 돈다(`.gitea/workflows/quality-gates.yml:45-58`, `:75-82`) |
| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿을 짝으로 써서 서비스를 빨리 출시한다. merge 게이트는 1회 판정이라 코드와 무관한 실패가 없어야 한다. 규모·성능 목표는 영역 15 |
| 실행 환경 | 이 영역의 실행 없음. 근거로 쓴 출력은 모두 `bbde570`이다. (1) merge 단계 CI env 실행 `desktop:/tmp/claude-gates/bbde570-ci/`(03:24 시작, load 0.98): `summary.txt` FE-GATE-001~012·020 rc=0, 013 rc=1. 게이트 로그 `gate-artifacts/FE-GATE-008.txt`(sha256 `8b852193…`), `FE-GATE-009.txt`(`82693359…`), `FE-GATE-013.txt`(`789acdcb…`). 사본: `scratchpad/r5/a11/FE-GATE-00{8,9}.bbde570.txt`, `FE-GATE-013.bbde570.txt`(sha256 같음). (2) FE-GATE-013의 사전 점검 뒤 명령: `desktop:/tmp/claude-gates/bbde570-013-parts/`(`system-vitest.log`, 사본 `scratchpad/r5/a11/system-vitest.bbde570.log`). (3) 그 실행의 산출물 snapshot `desktop:/tmp/claude-gates/r5/snap/merge/`(`MTIMES.txt`로 03:24 뒤 파일만 썼다: `artifacts/tests/a11y.json` 03:53, `artifacts/tests/a11y-data-state/REFERENCE_RESOURCE_DETAIL.json` 03:52, `artifacts/tests/unit.xml` 03:46). (4) 비교용 지난 라운드 로그: `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-00{8,9}.txt`(merge-48, `8a44226`). 비교에만 쓰고 이번 판정 근거로 쓰지 않았다. (5) 배치 11-R1~R3: 오케스트레이터가 desktop checkout(`bbde570`)에서 local env로 하나씩 돌렸다(2026-11-06 04:34~04:36, load 2.2~3.7). 셋 모두 `restore=clean`. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-11-R{1,2,3}.log`(사본 `scratchpad/r5/a11/`) |
| 읽은 코드·구성 범위 | 전부: 위 커밋의 영역 diff, `strict-browser-test.ts`, `preload-use.spec.ts`, `accessibility.spec.ts`, `a11y-data-state.ts`, `write-a11y-report.ts`, `a11y-report.test.ts`, `check-system-test-prerequisites.ts`, `provider-sandbox-namespaces.ts`, `installed-api-answers.ts`. 필요한 부분: `release-artifacts.ts:833-869`, `ci-artifact-contract.test.ts:280-345`, `:459-465`, `run-and-validate-provider.ts:254-293`, `service-worker-update.spec.ts:40-80`, `:176-350`, `opfs-runtime.spec.ts:329-460`, `reference-save.spec.ts:80-237`, Playwright 설정 다섯 개, `check-test-evidence.ts:280-305`, `run-ci-gate.ts:210-235`, `CHANGELOG.md:20-60`, 매뉴얼·문서의 a11y 문장(`docs/manual/reference/create-feature.md:97-98`, `docs/manual/01-add-a-feature.md:433`, `docs/accessibility/manual-checklist.md:66-80`, `docs/testing/frontend-platform-testing-strategy.md:140-155`) |
| 수행한 테스트·실험 | 직접 돌린 것은 없다. 배치 3건(11-R1~R3, 6절). 패치 둘은 노트북에서 `git apply --check`로 `bbde570`에 붙는 것을 확인했다. 3건 모두 기대와 같은 결과였다 |
| 확인하지 못한 범위·이유 | `test:system` provider 묶음: desktop의 bwrap이 비특권 user namespace를 못 쓴다(FE-GATE-013 사전 점검 출력). 노트북은 실행 금지. 그래서 1103/11-03·11-04의 완료 기준과 `.git` 가림 변이를 확인할 길이 없다. 실제 Gitea 러너(U-1). 글꼴 없는 깨끗한 Ubuntu에서 FE-GATE-008(1103/11-02) |
| 이전 리뷰와 비교 가능한 범위 | 지난 README §15의 영역 11 행 1건(1105/11-01), §11.3에서 12-01에 합친 1105/11-02, §16.5의 1103/11-01~11-04, §16.6의 0929/11-04, 지난 영역 문서 2절의 "남음"(0929/11-02·11-05 잔여·11-07, FOLLOW-UP 2). §16.4·§16.5의 "고침"은 주장으로 보고 지난 영역 문서 3절의 완료 기준과 대조했다. 지난 라운드 실행 결과는 수 비교에만 썼다 |
## 2. 지난 발견 재확인
상태: 고쳐짐(완료 기준 확인) / 일부(남은 것) / 남음 / 재발 / 틀린 발견. "일부(검증 남음)"은 코드 변경은 들어왔고 완료 기준 실행만 남은 경우다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/11-01 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 결과를 버려도 커밋된 test가 실패하지 않는다. 3번 test는 청크가 없으면 평범한 방문이 된다 | **고쳐짐** | 3.2절 (1). 완료 기준 셋(지난 문서 3.1 11-01): ① fixture가 기록을 버리면 실패 — `preload-use.spec.ts:204-217`이 기록 `^preloadunused:/assets/[^/]+\.js$` 한 줄을 요구한다(`:195-200`). ② 무시 정규식을 `/.*/`로 넓히면 실패 — `:219-253`이 warning 셋과 error 하나, 모두 네 줄을 순서대로 요구한다. 정규식을 넓히면 warning 셋이 사라져 한 줄만 남는다. ③ `parent`가 없으면 실패 — `:146-149`. 기본 판정의 실패 방향은 `:259-267`(`strictTest.fail()`). 변이 없는 실행: CI env FE-GATE-008에서 6건 × 3엔진이 기대대로 끝났다(`:259`는 세 엔진 모두 기대된 실패, 222 passed에 포함). 문서 주장(`docs/testing/frontend-platform-testing-strategy.md:151-154`)과 같다. 판정을 바꾸는 spec은 하나뿐이다(`git grep browserFailureVerdict`). **변이(11-R1, local env, 세 엔진):** ①②와 기본 판정 무력화를 함께 넣자 `:209`가 "what the strict fixture recorded" 기대 길이 1·받은 0, `:234`가 기대 4·받은 1, `:259`가 "Expected to fail, but passed."로 세 엔진 모두 실패했다(9 failed). tracker test 둘과 3번 test는 통과했다(9 passed). 지난 완료 기준 ①②를 커밋된 test가 실행으로 잡는다. ③은 단언 한 줄이라 정적으로 본다 |
| 1105/11-02 | `test:system` 사전 점검이 bwrap을 시험하지 않아 PASS 뒤 18건 실패 | **일부**(README에서 1105/12-01로 합침, 집계는 영역 12) | 이 영역이 본 것: FE-GATE-013(CI env)이 사전 점검에서 bwrap 명령·stderr(`loopback: Failed RTM_NEWADDR`)·호스트 설정 셋·고치는 방법을 적고 멈춘다(`gate-artifacts/FE-GATE-013.txt`). 사전 점검은 provider와 같은 옵션 상수로 `/bin/true`를 띄운다(`scripts/check-system-test-prerequisites.ts:39-43`, `:90-95`, `scripts/lib/provider-sandbox-namespaces.ts:13-18`, `scripts/run-and-validate-provider.ts:257`). 완료 기준 앞 절반은 충족. 남은 것: 지원 호스트에서 PASS 뒤 114건 통과(이번에 확인할 호스트 없음). 지난 개선 방향의 "파일 대기 test가 provider stderr를 붙인다"는 들어오지 않았다. 사전 점검을 건너뛴 실행에서 6건은 여전히 `provider output did not reach expected content`(`tests/system/ci-runner/ci-artifact-contract.test.ts:1782`) 4건, `expected path did not appear`(`:1812`) 2건뿐이다(`system-vitest.bbde570.log`) |
| 1103/11-01 (+12-03, 16-03 뒷부분) | 생성 기능 라우트를 접근성 e2e가 실패 화면으로 검사하고 `a11y.json`은 "passed" | **고쳐짐** | 3.2절 (2). 지난 문서의 남은 것은 상세 라우트와 `a11y.json`이었다. 이제 실패 화면 분기가 이유를 기록하고(`tests/e2e/accessibility.spec.ts:77-84`), report가 그 라우트를 `scope`에서 빼 `notChecked`에 넣는다(`scripts/write-a11y-report.ts:14-26`, `scripts/lib/a11y-data-state.ts:81-97`). CI env FE-GATE-009 산출물: `notChecked: [{ routeId: "REFERENCE_RESOURCE_DETAIL", reason: "scanned on its failure state only: GET_REFERENCE_RESOURCE reads one resource" }]`, `scope` 9개. 생성 기능 상태(11-R3, chromium): `create:feature sample-feature --with-create` 뒤 라우트 test 13건 통과, `notChecked`는 `REFERENCE_RESOURCE_DETAIL`과 `SAMPLE_DETAIL`("… SAMPLE_GET_ITEM reads one resource"), `scope`는 `SAMPLE_LIST`·`SAMPLE_CREATE`를 포함한 11개. 목록 라우트 쪽 코드는 `8a44226` 뒤 기록 호출 말고 바뀌지 않았다(`git diff 8a44226..bbde570 -- tests/e2e/accessibility.spec.ts tests/e2e/support/installed-api-answers.ts`). 남은 한계(기록된 선택): 상세 라우트의 화면 내용은 자동 검사 밖이고 수동 검토가 맡는다(`docs/manual/reference/create-feature.md:98`, `757d1c7` 본문의 버린 대안). 분류를 지키는 test가 없는 것은 새 11-01 |
| 1103/11-02 | CI merge job이 시각 테스트 글꼴을 설치하지 않음 | **일부(검증 남음)** | workflow의 브라우저 단계 두 곳이 패키지 넷을 설치한다(`.gitea/workflows/quality-gates.yml:74`, `:113`). 목록은 한 곳이다(`scripts/lib/visual-test-fonts.ts:9-16`, `scripts/generate-ci-workflow.ts:290`, `tests/visual/fonts.setup.ts:23`). 글꼴이 있는 desktop에서 FE-GATE-008 `test:visual` 6/6(`visual fonts match the goldens` 포함). 남은 것: 글꼴 없는 깨끗한 Ubuntu 24.04에서 6/6(완료 기준 3번). root도 sudo도 없는 러너면 `$(command -v sudo || true) apt-get`이 실패한다. README §16.5 "실행 환경 대기"와 같은 뜻이다 |
| 1103/11-03 | provider 테스트 10초 상한, 하나만 고르면 기반 fixture 빌드를 떠안음 | **일부(검증 남음)** | 코드는 지난 라운드 그대로다(`tests/system` diff 없음). 묶음 30초(`ci-artifact-contract.test.ts:461`), 기반 fixture `beforeAll` 180초(`:65-69`, `:462-464`), 개별 상한은 `:539` 40초 하나. 완료 기준(`-t 'kills descendants'` 단독 통과, loadavg 20+에서 5회)은 이 호스트에서 돌 수 없다. 사전 점검을 건너뛰어도 `kills descendants …` 두 건은 provider가 시작하지 못해 실패한다(`system-vitest.bbde570.log`) |
| 1103/11-04 | worktree `.git` 파일 때문에 provider test 16개 실패 | **일부(검증 남음)** | 가림 코드 그대로(`scripts/run-and-validate-provider.ts:278-293`). 새 test 둘(`ci-artifact-contract.test.ts:771-802`)도 이 호스트에서 bwrap 오류로 실패한다(`hides repository metadata … directory / file`). 가림 삭제 변이는 아직 아무도 결론을 내지 못했다 |
| 0929/11-02 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없음 | 남음 | `scripts/drill-runbook.ts:245`, `:351`, `:393`, `:434`의 `providerVerificationRequired: true` 그대로. `main()`은 runbook ID와 `--release-root`만 받는다(`:519-526`). 이번 diff는 descriptor에 `responseEnvelope: "NONE"` 한 줄뿐이다(`:290`). README §16.6에 없다 |
| 0929/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(영역 15) | `scripts/test-performance.ts`는 기능 라우트·직접 진입 CLS·스크롤바 때문에 +168줄 바뀌었다(`81701ad`, `138c195`, `e02f252`). 같은 빌드의 판정이 뒤집히는지 막는 변경은 아니다. 이번 공유 실행은 1회(5 runs 중앙값, `r5/snap/lab.txt` PASS)라 뒤집힘을 볼 수 없다. README §16.6 "남김" |
| 0929/11-05 남은 것 | 규모 기준선이 지금 코드를 대표하는지 | 남음(미검증, 영역 15) | `config/scale/feature-shape-growth.json:3`, `:16`은 그대로 2026-11-01, 커밋 `373b27b` 측정이다. 이번에 다시 적은 것은 다른 파일(초기 JS 기록 `config/scale/feature-shape-ceilings.json:41-46`, `0fee3fe`)이다. README §16.6에 없다 |
| 0929/11-07 | 빌드 helper 두 벌 | 남음 | 제외 목록은 이제 같다. 1105/12-04가 `service-worker-builds.ts`에 `.tmp`를 손으로 더했다(`tests/e2e/support/service-worker-builds.ts:58-69`, 주석 "fixture-builds.ts skips it too"; `tests/e2e/support/fixture-builds.ts:19-28`). `run`(`fixture-builds.ts:55`, `service-worker-builds.ts:177`)과 한 번 치환(`editOnce` `fixture-builds.ts:43`, `replaceOnce` `service-worker-builds.ts:111`)은 두 벌이다. 이번 수정도 두 곳을 같이 고쳐야 했다. 지난 판단대로 결함으로 올리지 않는다(리팩토링 후보). README §16.6에 없다 |
| FOLLOW-UP | SW update spec의 route chunk 변경을 helper 옵션으로 | 남음(문서화된 전제) | 아직 spec의 `beforeBuild`에서 덧붙인다(`tests/e2e/service-worker-update.spec.ts:61-72`). 새 test(`:302`)도 이 변경에 기댄다(`removedRouteChunk` `:241-257`) |
| FOLLOW-UP | Firefox SW quarantine | 남음(만료 2027-03-31) | 주석 `service-worker-update.spec.ts:181`, `service-worker-recovery.spec.ts:84`. 빠지는 test가 3 → 4개다(`:223`, `:263`, `:306`, recovery `:85`) |
지난 라운드에 고쳐짐으로 본 1103/11-05~11-10은 다시 열지 않았다. 재발 여부만 봤다. CI env FE-GATE-008에서 차단 업그레이드 test(`indexeddb-runtime.spec.ts:982`), compact smoke(`compact-smoke.spec.ts:12`), 파일·다운로드 test(`browser-files.spec.ts:14`, `:225`), preload 허용 spec(boot·old-tab·production-csp)이 세 엔진(compact는 chromium-compact) 모두 통과했다. "Execution context was destroyed"는 0건이다. 재발 없음.
## 3. 이번 발견 (36.3)
심각도 분포: Critical 0 · High 0 · Medium 0 · Low 1. 우선순위: P3 1. 성격: 구조적 위험 1.
### 3.1 발견
#### 11-01 `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록이 없는 라우트를 "검사함"으로 세서, spec의 기록 호출 한 줄이 바뀌면 상세 라우트가 경고 없이 다시 passed로 세진다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 |
| 관련 관점 | 10, 21, 5 |
| 근거 | **분류 경로:** 라우트 test는 실패 화면 분기에서만 기록 파일을 쓴다(`tests/e2e/accessibility.spec.ts:77-84`). 다른 두 분기는 기록을 지운다(`:76`, `:89`). report는 기록 파일이 있는 라우트만 `notChecked`로 옮긴다. 파일이 없으면 "검사함"이다(`scripts/lib/a11y-data-state.ts:50` 주석 "A route with none was checked", `:61` ENOENT면 `continue`, `:88-92`). **지키는 검사:** unit test 5건은 lib 함수를 임시 디렉터리로만 부른다(`tests/unit/a11y-report.test.ts:42-100`). spec과 이어지지 않는다. schema는 `scope`+`notChecked`가 설치 라우트와 같은지만 본다(`scripts/contracts/release-artifacts.ts:853-868`). 어느 라우트가 `notChecked`여야 하는지는 보지 않는다. `notChecked: []`도 받는다(unit test `:86-92`가 그 값을 통과로 단언한다). 생성된 `a11y.json`이나 기록 파일을 읽는 다른 test·검사는 없다(`git grep -n "REFERENCE_RESOURCE_DETAIL\|readA11yNotCheckedRoutes\|a11y-data-state" -- tests scripts`: 소비자는 `write-a11y-report.ts` 하나). 커밋 본문의 검증도 "`notChecked`에 `REFERENCE_RESOURCE_DETAIL`이 있어야 한다"를 실행 뒤 눈으로 본 것이다(`757d1c7` 본문 "검증"). **변이 실행(11-R2, local env, chromium):** `:83`의 `recordA11yDataState(definition.routeId, reason)`을 `null`로 바꿨다. 라우트 test 10건이 모두 통과했다(`playwright rc=0`). `write-a11y-report.ts`도 rc=0이었고 "not checked" 줄을 찍지 않았다. `a11y.json`은 `scope`에 `REFERENCE_RESOURCE_DETAIL`을 포함한 10개 전부, `notChecked: []`를 적었다. 같은 명령의 변이 없는 짝은 FE-GATE-009(CI env)이고 `notChecked`에 그 라우트가 있었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. **기록이 실행을 넘어 남는다:** 같은 실행 뒤 기록 디렉터리에 `INVOICE_DETAIL.json`(04:31)이 남아 있었다. 템플릿에 없는 라우트라, 앞선 다른 배치 항목이 만들었다가 checkout 복원으로 지워진 기능의 기록으로 보인다(추론). `artifacts/`의 JSON은 git이 무시하므로(`.gitignore:11`) 복원해도 남는다. report는 설치된 라우트 ID만 읽으므로(`a11y-data-state.ts:56-59`) 이번에는 해가 없었다. 같은 ID의 라우트가 다시 설치되고 그 test가 돌지 않으면 지난 기록이 그대로 쓰인다(커밋 본문이 적은 "지난 기록이 남는다") |
| 발생 조건 | `accessibility.spec.ts`나 `a11y-data-state.ts`를 고치는 변경(분기 정리, 기록 호출 이동, 새 분기). 템플릿을 받은 제품이 자기 기능 응답에 맞게 spec을 고칠 때. 지금 코드에는 기록 없이 통과하는 분기가 없다(세 분기 모두 기록 호출이 있거나 test가 실패한다) |
| 영향 | 자동 접근성 증거가 실패 화면으로만 본 라우트를 통과로 적는다. 사용자 피해는 없다. 상세 라우트의 화면 내용은 원래 수동 검토(FE-GATE-028)가 맡으므로 release 쪽 뒷받침은 남는다(`docs/manual/reference/create-feature.md:98`) |
| 심각도·우선순위 | Low · P3 — 1105/11-01과 같은 종류(검사를 지키는 test가 없음)다. 그쪽은 모든 browser test가 쓰는 fixture라 P2였다. 이쪽은 증거 한 칸이고 수동 검토가 뒤를 받친다 |
| 통제·증거 | 목표 M3(실패 화면 라우트가 `scope`에 들어가면 커밋된 검사가 실패) / 확인 M2(분류는 구현됐고 지금 맞게 동작한다. 지키는 test는 없다) · E3(11-R2 변이 실행 + 변이 없는 CI env FE-GATE-009 산출물) + E1(검사 목록) |
| 확실성과 남은 가정 | 분류 경로와 검사 목록은 코드로 확정이다. `test:a11y` 경로(spec + report)가 변이를 놓친다는 것은 11-R2로 확정이다. 다른 게이트(unit의 `a11y-report.test.ts`, 증거 schema)도 놓친다는 것은 소비자 목록에서 온 추론이다(둘 다 spec을 읽지 않는다). 11-R2는 chromium 한 엔진이다. 분류는 엔진과 상관없는 코드다 |
| 결정의 근거 | 이미 정한 분류를 지키는 test 보강이다. 다만 "기록 없음 = 검사함" 기본값을 뒤집을지는 작은 설계 선택이라 대안 비교에 적는다 |
| 이해 비용 | spec을 고치는 사람은 기록 호출이 릴리스 증거를 정한다는 것을 `a11y-data-state.ts` 머리 주석(`:5-17`)에서만 알 수 있다. spec의 주석(`:78-80`)은 결과만 적는다 |
| 최소 개선 방향 | (1) 설치된 descriptor로 "한 자원을 읽는 라우트" 목록을 계산하는 test를 둔다(`tests/e2e/support/installed-api-answers.ts:33-63`과 같은 규칙). 그 목록이 `test:a11y` 뒤 `a11y.json`의 `notChecked`와 같아야 한다. 템플릿에서는 `REFERENCE_RESOURCE_DETAIL` 하나다. (2) 라우트 test가 두 상태 모두 기록을 남기고, report는 이번 실행의 기록이 없는 설치 라우트가 있으면 실패한다 |
| 대안 비교 | (가) 현상 유지: 비용 없음. 기록 호출 변경을 아무 검사도 못 본다. (나) (2)만: 기록 줄 삭제·skip·이른 return은 잡는다. reason을 `null`로 바꾸는 변경은 못 잡는다. 지난 실행의 "검사함" 기록을 실행마다 비워야 한다. (다) (1)만: 두 방향 변경을 모두 잡는다. 다만 test가 spec과 같은 규칙을 한 번 더 계산한다. (라) (1)+(2): 가장 넓다. 비용은 test 하나와 기록 형식 한 칸이다. 이 영역의 권고는 (다)부터다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | test 1개. (2)를 고르면 기록 파일이 라우트 수만큼 생기고, 실행 경계(`TEST_RUN_ID`, 1105/12-04)를 정해야 한다 |
| 재검토 조건 | 상세 라우트를 견본 응답으로 실제 검사하게 되면 `notChecked`가 빈다. 그때 이 test는 "`notChecked`가 비었다"로 바뀐다 |
| 완료 기준 | 11-R2 변이(`accessibility.spec.ts:83`의 reason → `null`)를 넣으면 커밋된 검사(`test:a11y` 또는 FE-GATE-009의 다른 명령, 또는 unit test)가 실패한다. 기록 호출을 지워도 실패한다 |
| 검증 방법 | 11-R2와 같은 변이, 기록 줄 삭제 변이로 `corepack pnpm test:a11y` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 3.2 영역 필수 확인
**(1) 1105/11-01 strict fixture 증명 (`e0255299`)과 `use` → `provide`**
구조(코드): page fixture는 기록을 모아 test 본문 뒤에 preload 결과를 더한다(`strict-browser-test.ts:68-91`). 그 목록을 `browserFailureVerdict.judge`에 넘긴다(`:95`). 기본 판정은 `allowedBrowserFailure`로 거른 뒤 빈 목록을 단언한다(`:54-67`). page fixture가 판정 fixture에 기대므로, 판정의 teardown은 page teardown 뒤에 돈다. 증명 spec의 `recordedTest`는 판정을 "받아 두기"로 바꾸고 teardown에서 대조한다(`preload-use.spec.ts:180-202`).
| 질문 | 판단 | 근거·상태 |
|---|---|---|
| (a) fixture가 preload 기록을 버리면 커밋된 test가 실패하는가 | 그렇다. 11-R1(M1): 세 엔진 모두 `:209`가 기대 길이 1·받은 0으로 실패 | `:204-217`이 `^preloadunused:\/assets\/[^/]+\.js$` 한 줄을 요구한다(`:195-200`의 `toHaveLength`와 `toMatch`). 기록을 버리면 0줄이다. 판정이 아예 불리지 않아도 `:194`의 `toBeDefined`가 잡는다 |
| (b) WebKit 무시 정규식을 넓히면 실패하는가 | 그렇다. 11-R1(M2): 세 엔진 모두 `:234`가 기대 4·받은 1로 실패 | `:219-253`이 Chromium 문구, 뒤에 글자 붙은 WebKit 문구, 같은 문구의 `console.error`, 다른 warning, 네 줄을 순서대로 요구한다. WebKit 문구 그대로는 기록되지 않아야 한다. 정규식이 `/.*/`면 warning 셋이 빠져 1줄만 남는다. 정규식을 좁혀 WebKit 문구가 기록되면 다섯 줄이 되어 역시 실패한다 |
| (c) 기본 판정이 test를 실패시키는지 고정하는가 | 그렇다. 11-R1(M3): 세 엔진 모두 `:259`가 "Expected to fail, but passed."로 실패 | `:259-267`은 `strictTest.fail()`로 console error 한 줄을 낸다. 기본 판정이 아무것도 실패시키지 않으면 "expected to fail"로 실패한다. 커밋 본문이 적은 한계: 이 test가 다른 이유로 실패해도 통과한다. 기록 쪽은 (a)(b)가 따로 본다 |
| (d) 3번 test가 지연시킬 청크를 못 찾으면 실패하는가 | 그렇다(정적) | `:146-149` `expect(parent, …).toBeDefined()`. 남은 작은 빈틈: 지연 route가 실제로 걸렸는지는 단언하지 않는다(`:153-159`). 지금은 `parent`가 boot의 정적 closure 밖이고(`:128-142`) 앱에 미리 받기 코드가 없다(`git grep -i "prefetch\|requestIdleCallback" -- src` 0건). FE-GATE-008의 시간(chromium 4.5 s, firefox 4.7 s, webkit 7.2 s, 같은 화면을 지연 없이 여는 `:100` test는 0.7~3.4 s)이 지연이 걸렸다는 간접 증거다. 5절 |
| (e) `use` → `provide` 이름 변경이 동작을 바꾸는가 | 바꾸지 않는다 | §16.3 "`e025529`에 접음"대로 최종 커밋에 이미 `provide`다(`git show e0255299:tests/e2e/preload-use.spec.ts`의 `:180-182`). lint 규칙은 `tests/support/browser/**`에서만 꺼져 있다(`eslint.config.ts:939-941`). 그래서 fixture 파일은 `use`(`strict-browser-test.ts:54`, `:68`), spec은 `provide`(`preload-use.spec.ts:182`, `boot-module-failure.spec.ts:47`, `old-tab-chunk-recovery.spec.ts:153`)다. Playwright는 fixture 함수의 첫 인자 구조 분해만 읽는다. 실행 증거: `recordedTest`의 preload test가 세 엔진에서 통과했다. 바꾼 판정이 쓰이지 않았다면 기본 판정이 그 `preloadunused:` 줄로 실패시켰을 것이다. FE-GATE-002(lint) rc=0 |
| (f) 새 override 자리 | 기록 | 다른 spec도 `browserFailureVerdict`를 바꿔 strict 검사를 끌 수 있다. 지금 바꾸는 spec은 하나다(`git grep browserFailureVerdict`). 막는 검사는 없다(커밋 본문 "위험·한계"). `allowedBrowserFailure: /.*/`와 같은 노출이고, 그쪽에도 막는 검사가 없다. 결함으로 세지 않는다 |
**(2) 1103/11-01 BREAKING (`757d1c7`, `a11y.json` schemaVersion 2)**
| 질문 | 판단 | 근거·상태 |
|---|---|---|
| 코드가 BREAKING CHANGE footer와 같은가 | 같다 | footer: schemaVersion 2, 실패 화면으로만 본 라우트는 `scope`에서 빠져 `notChecked`의 `{ routeId, reason }`으로, 옛 도구는 둘을 합쳐 읽는다. 코드: 값을 만드는 곳 `a11y-data-state.ts:81-97`(`schemaVersion: 2`, `scope`는 설치 라우트에서 `notChecked`를 뺀 것). schema `release-artifacts.ts:840-869`(`z.literal(2)`, `notChecked`는 strict 객체 배열, 중복 금지, 설치 라우트만, `scope`는 레지스트리 순서의 나머지) |
| CHANGELOG 안내와 같은가 | 같다 | 먼저 할 일 5단계(`CHANGELOG.md:28`)와 표 행(`:53`). 표 행의 "라우트 test가 자기 상태를 … 남긴다"는 정확히는 "실패 화면 라우트만 파일을 남기고 나머지는 지운다"다(`a11y-data-state.ts:38-41`). 틀린 말은 아니다 |
| 템플릿 안 소비자 | 하나, 같이 바뀌었다 | `ci-artifact-validator.ts:205`가 같은 schema를 쓴다. FE-GATE-009의 증거가 그 하나다(`config/ci/gates.json:1920-1931`, `:1152-1159`). `tests/system/ci-runner/ci-artifact-contract.test.ts:316`의 `{ schemaVersion: 1, … }`은 "거절되어야 할 값" 예시라 그대로 맞다(칸이 모자라 원래도 거절된다) |
| FE-GATE-009 산출물(CI env, `bbde570`) | 기대대로 | 게이트 로그: `60 passed (48.6s)`, `a11y: REFERENCE_RESOURCE_DETAIL not checked in its own state (scanned on its failure state only: GET_REFERENCE_RESOURCE reads one resource)`, 수동 기록 형식 `PASS (10 routes …)`. snapshot `artifacts/tests/a11y.json`(03:53, `generatedAt` `2026-11-05T18:53:04.086Z`): `scope` 9개(`APP_HOME` … `REFERENCE_RESOURCE_STATUS`), `notChecked` 1개, `automatedStatus: "passed"`. 기록 파일은 `REFERENCE_RESOURCE_DETAIL.json` 하나(03:52). `tests/unit/a11y-report.test.ts` 5건은 snapshot `unit.xml`(03:46)에서 통과 |
| 생성 기능의 상세 라우트 | 매뉴얼대로 `notChecked`로 간다 | 분류 규칙은 기능과 상관없다(`installed-api-answers.ts:46-55`: 빈 목록을 거절하고 경로 파라미터가 있으면 한 자원 읽기). 생성기의 상세 라우트는 `session-required`다(`scripts/create-feature-write-slice.ts:130`). 11-R3(chromium): 생성 명령이 `SAMPLE_LIST`·`SAMPLE_DETAIL`·`SAMPLE_CREATE`를 만들었다. 라우트 test 13건 통과. report가 두 줄(`REFERENCE_RESOURCE_DETAIL`, `SAMPLE_DETAIL … SAMPLE_GET_ITEM reads one resource`)을 찍고 rc=0. `scope` 11개, `notChecked` 2개. 매뉴얼 주장(`create-feature.md:98`)과 같다 |
| 문서 | 기록 | 매뉴얼 `create-feature.md:97-98`은 동작과 같다. `docs/accessibility/manual-checklist.md:74-76`과 `docs/manual/01-add-a-feature.md:433`은 annotation만 적고 `a11y.json`의 `notChecked`를 말하지 않는다. 틀리지는 않고 덜 적었다(영역 14 참고, 세지 않음) |
| 고정 경로와 실행 격리 | 기록 | 기록 디렉터리(`a11y-data-state.ts:18`)와 `a11y.json`(`write-a11y-report.ts:11-16`)은 `TEST_RUN_ID`와 상관없이 기본 경로다. 1105/12-04가 적은 한계 "게이트와 증거 검사는 기본 경로만 읽는다"(`CHANGELOG.md:38`, `:106`)와 같다. 두 실행이 같은 라우트에 같은 판단을 쓰므로, 기능 선택이 다른 두 실행(12-04의 알려진 한계)이 아니면 해가 없다 |
**(3) FE-GATE-008·009 수 비교 (CI env, 지난 라운드 merge-48 `8a44226` ↔ 이번 `bbde570`)**
파일·엔진별 test 수를 두 로그에서 세어 비교했다(각 94행). 줄어든 행은 없다.
| 명령 | 지난 라운드 | 이번 | 차이와 이유 |
|---|---|---|---|
| `test:e2e` | 205건: 202 passed, 3 skipped, 1.8 m | 226건: 222 passed, 4 skipped, 2.1 m | preload-use 3 → 6 test(× 3엔진 +9, 1105/11-01), reference-save 5 → 8(+9, 1105/08-01), SW update 5 → 6(+3, 1105/06-03). `preload-use.spec.ts:259` 세 건은 `test.fail()`의 기대된 실패라 목록에 ✘로 나오고 passed로 센다 |
| skip | firefox 3건 | firefox 4건 | `service-worker-recovery.spec.ts:79`, `service-worker-update.spec.ts:219`, `:259`, 새 `:302`. 모두 같은 quarantine(`:181`, 만료 2027-03-31) |
| `test:browser-capabilities` | 66 passed | 69 passed(43.4 s) | OPFS purge test가 기존 객체 0개·3개 두 경우로 나뉨(`opfs-runtime.spec.ts:338`, 1103/05-01). 증거 검사 "22 → 23 cases x 3 engines, zero skipped" |
| `test:storybook` | 1 | 1 | 같다 |
| `test:visual` | 6 | 6(11.1 s) | 골든 5장을 다시 찍었다(`e02f252d`, 1105/15-05). 허용치는 그대로다(3.3절) |
| `check:test-evidence:browser` | 416 파일 | 433 파일, baseline 5 | 금지 fixture 넷은 기대대로 실패(`EXPECTED_FAILURE`) |
| `test:a11y`(FE-GATE-009) | 60 passed | 60 passed(48.6 s) | test 이름이 같다(줄 번호만 +1·+3). 새로 `notChecked` 한 줄 |
| 재시도·flaky | 없음 | 없음 | "Execution context was destroyed" 0건 |
web server 포트는 실행마다 달랐다(e2e 36031, visual 44517, a11y 36037). 1105/12-04의 빈 포트 선택이 CI env에서 동작한다.
증거 읽기 주의: snapshot의 `artifacts/tests/e2e/results.xml`(03:53)은 `tests="60"`이다. FE-GATE-008의 226건이 아니라 뒤에 돈 FE-GATE-009(`test:a11y`, 같은 `playwright.config.ts` 출력 경로)의 결과다. 한 checkout에서 merge 단계를 차례로 돌리면 덮어쓴다. CI는 gate마다 job이 따로라 겹치지 않는다(`quality-gates.yml:45-58`, `:75-82`). `ci:gate`는 gate 직후 그 증거를 검증한다(`scripts/run-ci-gate.ts:216-225`). 그래서 결함으로 세지 않았다. 이 문서의 e2e 수는 게이트 로그에서 셌다.
**(4) FE-GATE-013**
- 게이트 로그(CI env, rc=1, 2 s): `test:system`의 사전 점검이 `this host does not allow unprivileged user and network namespaces …`로 멈춘다. bwrap 명령 전체, `exited 1`, stderr `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`, 호스트 설정 `kernel.apparmor_restrict_unprivileged_userns = 1, kernel.unprivileged_userns_clone = 1, user.max_user_namespaces = 113201`, 고치는 방법 셋, 러너 요구 문서를 적는다.
- 사전 점검 뒤 명령(`bbde570-013-parts/summary.txt`): `system-vitest` rc=1(81 s), 나머지 7개 rc=0. `system-vitest.log`: 3파일 중 1 실패, `ci-artifact-contract.test.ts`의 `candidate archive and provider upload boundaries` 18건 실패. 12건은 `sandboxed external provider failed: … bwrap: loopback: Failed RTM_NEWADDR`, 4건은 `:1782`, 2건은 `:1812`의 파일 대기 시간 초과다. 이름은 지난 라운드 분류표(지난 문서 3.2 (3))의 18건과 같다. 코드 결함으로 볼 실패는 없다.
- snapshot의 `artifacts/tests/system.xml`은 2026-11-05 20:00 파일이다. 이번 실행은 사전 점검에서 멈춰 junit을 쓰지 않았다. 쓰지 않았다.
### 3.3 수정이 검사를 약하게 했는가 (`git diff 8a44226..bbde570 -- <영역 경로>`)
| 변경 | 약해진 것 | 판단 |
|---|---|---|
| strict fixture의 마지막 판정을 `browserFailureVerdict`로 뺌(`e0255299`) | 어느 spec이든 판정을 바꿔 strict 검사를 끌 수 있다 | 바꾸는 spec은 증명 spec 하나다. 노출은 `allowedBrowserFailure: /.*/`와 같다. 커밋 본문이 적었다. 결함 아님(3.2 (1)(f)) |
| `a11y.json` schema v1 → v2(`757d1c7`) | v1은 `scope` = 설치 라우트 전체를 강제했다. v2는 합이 설치 라우트이기만 하면 어떤 분할이든 받는다(`release-artifacts.ts:853-868`) | v1 규칙은 거짓 주장을 강제한 것이다. 분할은 spec의 기록이 정한다. 그 기록을 지키는 test가 없는 것은 11-01에 넣었다 |
| SW update 새 test의 firefox skip(`aaa782ba`, `service-worker-update.spec.ts:306`) | 새 test가 firefox에서 돌지 않는다 | 다른 셋과 같은 이유·상수다(`:181-183`). 주인과 만료가 있다. 참고: `check-test-evidence.ts:292-304`는 파일 안에 quarantine 주석이 하나라도 있으면 그 파일의 모든 skip을 받는다. 그래서 새 skip은 새 기록 없이 들어왔다. 예전부터의 검사 동작이다(영역 12 몫, 세지 않음) |
| 시각 골든 5장 재촬영(`e02f252d`, 1105/15-05) | 골든이 스크롤바 자리 15 px를 담는다. compact 골든은 overlay 스크롤바 휴대폰보다 15 px 좁다(지난 README §16.3) | `toHaveScreenshot` 허용치·mask는 그대로다(`playwright.visual.config.ts` diff는 경로·포트뿐). 기록된 한계. 결함 아님 |
| Playwright 설정 다섯 개(1105/12-04) | — | 출력 경로·포트·`--strictPort`만 바뀌었다. dev 설정은 떠 있는 서버를 더는 쓰지 않는다(`reuseExistingServer: false`). 허용치·재시도·시간 상한 변경 없음. 더 엄격해졌다 |
| SW 빌드 복사가 `.tmp`를 건너뜀(`service-worker-builds.ts:65`) | 복사본에 `.tmp`가 없다 | `.tmp`는 다른 실행의 출력이다. `fixture-builds.ts`는 이미 건너뛰었다. 결함 아님 |
| OPFS purge test 두 경우로(`23662fb2`) | — | 단언이 늘었다(`removedObjects`). `waitForTimeout(250)`과 OPFS 없을 때 `return`(`opfs-runtime.spec.ts:352`, `:470`)은 예전부터다(5절). 결함 아님 |
| reference-save 새 test 셋(`4f3c10bc`) | — | describe에 있던 허용(`reference-save.spec.ts:84-88`, `:161`)을 그대로 쓴다. 넓히지 않았다 |
| 사전 점검 bwrap 시험(`9655958b`) | — | 더 엄격해졌다 |
| 3번 preload test의 `parent` 단언(`e0255299`) | — | 더 엄격해졌다 |
이 영역 경로에서 늘린 시간 상한·허용치·예산은 없다(`git diff … | grep -n 'timeout\|retries\|threshold\|maxDiff'`: 옮겨진 줄과 새 test의 30 s 보임 대기 하나).
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가.
| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > | — | — | src는 영역 01~09 |
| 2 | 구조적 성숙도 | > | — | — | 12·16 |
| 3 | 변경 용이성 | P | M3 / M2 | E1 | 기능을 더해도 접근성 spec은 descriptor로 응답 모양과 `notChecked`를 정한다. 시각 골든은 기능 수와 무관하다. 생성 기능 설치 상태의 브라우저 게이트는 결정 대기(1105/16-03) |
| 4 | 인지 부하 | P | M2 / M2 | E1 | fixture·증명 spec 주석이 판정 위치를 적는다(`strict-browser-test.ts:27-51`). `a11y.json` 분류 규칙은 `a11y-data-state.ts` 머리 주석에만 있다(11-01). 빌드 helper 두 벌(0929/11-07) |
| 5 | 위험 가시성 | P | M3 / M2 | E3(FE-GATE-009 산출물, 11-R2·R3) | 실패 화면 라우트가 `notChecked`로 드러난다(1103/11-01). 그 분류는 기록이 없으면 "검사함"으로 기운다. 기록 한 줄을 바꾸면 증거가 다시 passed로 적힌다(11-01, 11-R2) |
| 6 | 실패 성숙도 | O | M3 / M3 | E3(CI env 1회) | 부트 오류 화면, 구 탭 1회 reload, 429 재시도·불명 결과 저장과 포커스, 깨진 SW 해제, 이전 캐시 응답, 지워진 route를 B 워커 아래 같은 문서에서 열기가 FE-GATE-008에서 통과했다(SW 넷은 chromium·webkit, firefox quarantine) |
| 7 | 운영 성숙도 | P | M3 / M1 | E1 | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(0929/11-02) |
| 8 | 디버깅 가능성 (깊게) | P | M3 / M3(사전 점검), M2(provider test) | E3·E1 | `test:system`이 호스트 원인과 고치는 방법을 적고 멈춘다(1105/12-01). preload·console 실패는 줄 단위로 찍힌다. 사전 점검을 넘긴 뒤 provider가 못 뜨면 6건은 여전히 원인 없이 시간 초과로만 보인다(1105/11-02 잔여) |
| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | helper 제외 목록을 손으로 맞췄다(0929/11-07). 규모 기준선 재측정은 영역 15 |
| 10 | 테스트 성숙도 (깊게) | P | M3 / M3(fixture 증명), M2(a11y 분류) | E3(CI env 게이트, 배치 변이 3건)·E1 | 강점: strict fixture의 기록과 판정을 커밋된 test가 양쪽 방향으로 고정한다(1105/11-01, 11-R1에서 변이 셋 모두 잡힘). 실패 화면 라우트를 증거에서 뺀다(생성 기능 상태 포함, 11-R3). e2e·capability가 21·3건 늘었고 사라진 test가 없다. 약점: `notChecked` 분류를 지키는 test 없음(11-01). provider 묶음은 이 호스트에서 확인 불가(1103/11-03·11-04) |
| 11 | 데이터 성숙도 | - | — | — | 이 영역에 데이터 이관 경로가 없다 |
| 12 | 동시성 성숙도 | P | M3 / M2 | E1 | 세 엔진이 같은 a11y 기록을 쓰므로 임시 파일 뒤 rename한다(`a11y-data-state.ts:44-47`). OPFS purge test는 `waitForTimeout(250)`으로 경쟁 경로를 노린다(5절) |
| 13 | 확장성 | P | M3 / M2 | E3(11-R3)·E1 | 접근성 spec·시각 골든이 기능 추가에 손대지 않고 돈다. 생성 기능의 상세 라우트는 spec 수정 없이 `notChecked`로 간다(11-R3). 생성 기능 설치 상태의 게이트 실행은 결정 대기(1105/16-03) |
| 14 | 성능 성숙도 | > | — | — | 15. 이 영역 관련: strict fixture의 page.route가 모든 browser test의 HTTP cache를 끈다(5절, 지난 라운드부터) |
| 15 | 보안 성숙도 | > | — | — | 13. `.git` 가림의 실행 증거는 이 호스트에서 얻을 수 없다(1103/11-04) |
| 16 | 의존성 성숙도 | P | M3 / M2 | E1 | 시각 글꼴 패키지를 CI가 설치한다. 깨끗한 러너 실행은 없다(1103/11-02). `test:system`의 호스트 요구가 적혔다(1105/12-01) |
| 17 | API / Contract | > | — | — | 07. `a11y.json` schema 2는 CHANGELOG BREAKING으로 알렸다(3.2 (2)) |
| 18 | 배포 성숙도 (깊게) | P | M3 / M3(브라우저), M1(drill) | E3(CI env 1회) | 구 탭 청크 복구(세 엔진), SW A→B 업데이트와 지워진 route(chromium·webkit), CI 식별값 빌드의 compact smoke가 CI env로 통과했다. drill로 provider 전환을 기록할 수 없다(0929/11-02). 실제 러너 미실행(U-1) |
| 19 | 설정 성숙도 | P | M3 / M2 | E3·E1 | 포트를 실행마다 고르고 worker가 같은 값을 읽는다(`run-isolation.ts:127-145`, resumable spec 통과). a11y 증거는 기본 경로 고정(12-04 한계) |
| 20 | 개발자 경험 (깊게) | P | M3 / M2 | E3·E1 | 지원 안 되는 호스트에서 사전 점검이 이유를 말한다(1105/12-01). 한 checkout에서 merge 단계를 차례로 돌리면 FE-GATE-009가 FE-GATE-008의 e2e junit·report를 덮는다(3.2 (3) 주의, 결함 아님) |
| 21 | Guardrail 성숙도 (깊게) | P | M3 / M2 | E3(CI env) | merge 단계 CI env에서 FE-GATE-001~012·020 통과. 013은 사전 점검에서 호스트 원인으로 멈춘다. `forbidOnly`·quarantine 만료·mask 규칙 fixture가 기대대로 실패한다. strict fixture는 이제 자기 검사를 지키는 test가 있다. a11y 분류는 없다(11-01). quarantine 검사가 파일 단위다(3.3, 영역 12 몫) |
| 22 | 추상화 성숙도 | P | M2 / M2 | E1 | 판정을 fixture 하나로 빼서 증명 spec이 바꿀 수 있다. helper 두 벌(0929/11-07) |
| 23 | 일관성 | P | M2 / M2 | E1 | 모든 browser spec이 같은 strict fixture를 쓴다(`chunk-load-error.spec.ts` 하나만 맨 test). fixture 콜백 이름은 lint 범위 때문에 fixture 파일은 `use`, spec은 `provide`다 |
| 24 | 네이밍 / 의미 | P | M2 / M2 | E1 | `automatedStatus: "passed"`는 이제 `scope`만 뜻한다. schema 주석이 적는다(`release-artifacts.ts:833-839`). 값 이름만 보면 전체 통과로 읽힌다 |
| 25 | 조직 확장성 | > | — | — | 14 |
| 26 | Ownership 성숙도 | P | M2 / M2 | E1 | quarantine에 owner·만료가 있다. `test:system` 러너 요구가 문서·gate 정의에 적혔다(1105/12-01) |
| 27 | 삭제 가능성 | P | M2 / M2 | E1 | 참조 기능을 지우면 `REFERENCE_RESOURCE_DETAIL`도 레지스트리에서 빠지고 report는 설치 라우트만 읽는다(`write-a11y-report.ts:14`). 3번 preload test는 기능 실행부 모양이 바뀌면 이유를 적고 실패한다(커밋 본문의 알려진 비용) |
| 28 | 회복 가능성 | P | M3 / M3(브라우저), M1(drill) | E3(CI env 1회) | 깨진 SW 해제와 구 탭 청크 복구가 통과했다. provider 전환 뒤 smoke를 drill 증거로 넣을 방법이 없다(0929/11-02) |
집계(적용 21개): 충족 1(6) · 부분 충족 20 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6(1, 2, 14, 15, 17, 25).
지난 라운드와 달라진 곳: 판정 기호는 같다. 8은 사전 점검이 원인을 말하게 되어 확인 통제가 M3로 올랐다(잔여는 provider test 6건). 10은 fixture 증명이 M3로 올랐고 a11y 분류가 새 약점이다. 5는 근거가 1103/11-01 잔여에서 11-01로 바뀌었다.
## 5. 미검증
| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 |
|---|---|---|
| 11-01이 FE-GATE-009 전체(세 엔진)와 다른 게이트에서도 놓치는지 | 11-R2는 chromium 한 엔진의 `test:a11y` 경로만 돌렸다. unit test와 증거 schema가 spec을 읽지 않는다는 것은 코드로 봤다 | 같은 변이로 `ci:gate -- FE-GATE-009`와 `test:unit` |
| 지난 실행의 a11y 기록이 다음 실행에 쓰이는 경우 | 11-R2 뒤 다른 항목의 `INVOICE_DETAIL.json`이 남아 있었다. 이번에는 설치되지 않은 라우트라 읽히지 않았다 | 같은 ID 라우트를 다시 설치하고 그 test를 건너뛴 실행 |
| 1103/11-03·11-04의 완료 기준, `.git` 가림 변이 | desktop의 bwrap이 user namespace를 못 쓴다(FE-GATE-013 사전 점검). 노트북 실행 금지 | user namespace를 허용하는 호스트에서 `test:system`과 가림 삭제 변이 |
| 1103/11-02 깨끗한 러너의 글꼴 단계 | U-1 | 글꼴 없는 Ubuntu 24.04 컨테이너나 러너 1대 |
| 3번 preload test의 지연이 실제로 걸리는지 | 단언이 없다. 시간만 간접 증거다 | route handler가 불렸는지 flag로 단언 |
| page.route가 끄는 HTTP cache의 영향 | 근거가 Playwright 문서뿐이다(지난 라운드부터). HTTP cache 동작을 단언하는 test는 없다 | cache 동작을 보는 test를 만들 때 fixture 밖에서 돌거나 fixture에 적는다 |
| `opfs-runtime.spec.ts`의 OPFS 미지원 엔진 조용한 통과(`:352`, `:470` `return`) | 지난 라운드부터 있던 모양. FE-GATE-008에서 세 엔진 모두 2.6~6.2 s 걸려 실제로 돈 것으로 보인다(추론) | test가 지원 여부를 단언하거나 `test.skip`으로 이름을 남김 |
| 엔진마다 a11y 분류가 다를 때 | 지금 상세 페이지는 엔진과 상관없이 같은 GET을 보낸다. 다르면 마지막에 쓴 엔진이 정한다(`a11y-data-state.ts:44-47`) | 엔진별 기록 또는 불일치 시 실패 |
| 0929/11-04 lab 판정 뒤집힘 | 이번 공유 lab 실행은 1회다 | 같은 빌드 반복 실행(영역 15) |
| CI 러너 위 FE-GATE-008·009·013 | U-1 | 러너 1대와 PR 1건 |
## 6. 실행 기록
이 영역이 직접 돌린 실행은 없다. desktop에서는 `/tmp/claude-gates/` 아래 파일을 읽기만 했다(`cat`, `grep`, `ls`, `sha256sum`).
배치 실험(요청 `scratchpad/r5/requests/11.md`, 패치 `scratchpad/r5/requests/11-R1.diff`, `11-R2.diff`, 결과 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-11-R{1,2,3}.log`, 사본 `scratchpad/r5/a11/R5-11-R{1,2,3}.log`). 패치 둘은 노트북 worktree에서 `git apply --check`로 `bbde570`에 붙는 것을 확인했다. 오케스트레이터가 desktop checkout(`bbde570`)에서 local env로 하나씩 돌렸고, 셋 모두 `restore=clean`이다. 3건 모두 기대와 같은 결과였다. 11-R2만 기대와 한 곳이 달랐다(아래).
| ID | 명령(요약) | 변이 | rc · 시간 | 결과 |
|---|---|---|---|---|
| 11-R1 | `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 | `strict-browser-test.ts` M1 `:91` 기록 버림, M2 `:17` 정규식 `/.*/u`, M3 `:58-63` 기본 판정 expect 제거 | 1 · 27.2 s · 2.17 | 기대대로. 9 failed: 세 엔진 × `:209`("what the strict fixture recorded" Expected length 1, Received 0), `:234`(Expected 4, Received 1), `:259`("Expected to fail, but passed."). 9 passed: `:89`, `:100`, `:124` 세 엔진 |
| 11-R2 | `accessibility.spec.ts` chromium `--grep '@a11y /'` 뒤 `write-a11y-report.ts`, `a11y.json` 출력 | `accessibility.spec.ts:83` reason → `null` | 0(`playwright rc=0`, `report rc=0`) · 20.3 s · 3.65 | 기대대로(놓침). 10 passed, "not checked" 줄 없음. `a11y.json` `scope` 10개(`REFERENCE_RESOURCE_DETAIL` 포함), `notChecked: []`. 기대와 다른 한 곳: 기록 디렉터리가 비지 않고 다른 항목의 `INVOICE_DETAIL.json`(04:31)이 남아 있었다. 설치되지 않은 라우트라 report가 읽지 않았다 |
| 11-R3 | `create:feature sample-feature --with-create` 뒤 같은 명령 | 없음 | 0(`playwright rc=0`, `report rc=0`) · 25.5 s · 2.98 | 기대대로. 생성 명령 성공(라우트 `SAMPLE_LIST` `/sample`, `SAMPLE_DETAIL` `/sample/items/:sampleId`, `SAMPLE_CREATE` `/sample/new`). 13 passed. report 두 줄(`REFERENCE_RESOURCE_DETAIL`, `SAMPLE_DETAIL … SAMPLE_GET_ITEM reads one resource`). `scope` 11개(`SAMPLE_LIST`·`SAMPLE_CREATE` 포함), `notChecked` 2개 |
인용한 출력(이 영역이 돌린 것 아님):
| 출력 | 결과 |
|---|---|
| `bbde570-ci/summary.txt`(CI env, 03:24 시작, load 0.98) | FE-GATE-020 rc=0 1,237 s · 001 3 s · 002 18 s · 003 27 s · 004 2 s · 005 132 s · 006 10 s · 007 28 s · **008 rc=0 196 s** · **009 rc=0 51 s** · 010 63 s · 011 8 s · 012 6 s · **013 rc=1 2 s**. 끝에 checkout 복원 `clean=yes` |
| FE-GATE-008 게이트 로그(`8b852193…`) | e2e 226건: 222 passed, 4 skipped(firefox SW quarantine), 2.1 m, 6 workers. capability 69 passed(43.4 s), "Browser capability evidence: PASS (23 cases x 3 engines, zero skipped)". storybook 1 passed. visual 6 passed. "Test evidence: PASS (433 files, 5 baselines …)". 금지 fixture 넷 `EXPECTED_FAILURE`. 재시도·flaky 없음 |
| FE-GATE-009 게이트 로그(`82693359…`) | `test:a11y` 60 passed(48.6 s), `a11y: REFERENCE_RESOURCE_DETAIL not checked in its own state (…)`. `review:a11y-manual -- --format-only` PASS(10 routes) |
| FE-GATE-013 게이트 로그(`789acdcb…`) | 사전 점검에서 멈춤(3.2 (4)) |
| `bbde570-013-parts/summary.txt` | `system-vitest` rc=1 81 s(18 failed, 3.2 (4)), `verify:reproducible-build`·`build:release-candidate`·`verify:local-evidence`·`check:supply-chain:fixtures`·`check:supply-chain:provider-fixtures`·`check:security:fixtures`·`check:browser-security` rc=0 |
| snapshot `r5/snap/merge/` | `artifacts/tests/a11y.json`(03:53), `a11y-data-state/REFERENCE_RESOURCE_DETAIL.json`(03:52), `unit.xml`(03:46, `a11y-report.test.ts` 5건 통과). `e2e/results.xml`(03:53)은 FE-GATE-009의 60건이다(3.2 (3) 주의). `system.xml`(2026-11-05 20:00)은 지난 파일이라 쓰지 않았다 |
| 비교: `r4/snap/artifacts/quality/gates/FE-GATE-00{8,9}.txt`(merge-48, `8a44226`) | e2e 205(202 passed, 3 skipped), capability 66, storybook 1, visual 6, test evidence 416 파일, a11y 60 |
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 11-01 | Low·P3 | 구조적 위험 | `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록이 없는 라우트를 "검사함"으로 세서, spec의 기록 호출 한 줄을 바꾸면 상세 라우트가 다시 passed로 세지고 `test:a11y` 경로는 rc=0이다(11-R2) | `tests/e2e/accessibility.spec.ts:77-84`, `scripts/lib/a11y-data-state.ts:50`, `:61`, `scripts/contracts/release-artifacts.ts:853-868`, `tests/unit/a11y-report.test.ts:86-92` |
@@ -0,0 +1,197 @@
# 영역 12 — 가드레일·CI
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `scripts/check-*.ts`·`scripts/verify-*.ts`·`scripts/lib/`, `.gitea/workflows/`, `config/ci/`, `eslint.config.ts`, `tsconfig*.json`, `.dependency-cruiser.json`, `CLAUDE.md`. 함께 본 것: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-contract-pin.json`, `scripts/lib/run-isolation.ts`와 Playwright 설정 다섯, `scripts/lib/removal-fixture.ts`, `scripts/lib/vite-build-inputs.ts`, README merge 게이트 절
> 깊게 본 관점: 5, 10, 19, 21, 23
> 렌즈: 1105/12-01~12-04의 완료 기준 · `8a44226..bbde570`에서 약해진 검사 · D7(초기 JS 예산 상향) 뒤에도 예산 검사가 실패하는가 · 통합 때 고친 목록 셋(제거 fixture 문서 테스트, vite 빌드 입력, CI 기준선)
> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드 P1 하나(12-01)와 12-02는 고쳐졌다. 이 desktop에서 FE-GATE-013은 이제 첫 단계에서 이유와 고치는 법을 적고 멈춘다. 조건은 셋이다. (1) FE-GATE-013은 비특권 user namespace를 허용하는 호스트에서만 통과한다. 이 desktop은 허용하지 않는다. 어떻게 셀지는 사용자 결정이다. (2) `CLAUDE.md`의 리뷰 게이트 목록은 이 기준에서 그대로다(12-03, 고친 커밋은 PR #6에만 있다). (3) 게이트는 한 checkout에서 하나씩 돌린다. 실행 격리는 Playwright 실행까지다(12-04. 오케스트레이터 드릴에서 e2e 두 실행이 함께 통과했다).
ID 표기: 이 문서의 `12-NN`은 2026-11-06 라운드 ID다. 지난 라운드는 `1105/12-NN`, 그 전은 `1103/…`, `1101/…`, `0929/…`로 적는다.
## 0. 결론
- **1105/12-01은 고쳐졌다.** 사전 점검이 provider와 같은 namespace 옵션으로 `bwrap … /bin/true`를 띄운다(`scripts/check-system-test-prerequisites.ts:39-43`, `:90-95`). 이 desktop의 merge 실행에서 FE-GATE-013은 2초 만에 "this host does not allow unprivileged user and network namespaces"와 bwrap stderr, sysctl 값, 고치는 법 셋을 적고 멈췄다(`desktop:/tmp/claude-gates/bbde570-ci/gate-artifacts/FE-GATE-013.txt`). 러너 요구는 문서 셋, README, `gates.json`의 `hostRequirements`, workflow 주석에 있다. gate 모양 해시도 이 요구를 본다(`scripts/contracts/ci-gates.ts:508`, `:519`). 허용 호스트에서 PASS하는지는 가짜 호스트 단위 테스트뿐이다.
- **FE-GATE-013은 이 호스트에서 실패한다. 있는 그대로 적는다.** 사전 점검 뒤 명령을 따로 돌린 결과: `tests/system` 114건 중 96건 통과, 18건 실패. 18건은 모두 `ci-artifact-contract.test.ts`의 provider 경계 테스트이고 오류 원문은 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`다. 뒤 명령 7개는 모두 통과했다(`desktop:/tmp/claude-gates/bbde570-013-parts/summary.txt`). 어떻게 셀지는 사용자가 정한다.
- **1105/12-02는 고쳐졌다.** 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다(`scripts/verify-documentation-readiness.ts:245-285`). desktop 로컬 실행은 PASS_SCOPED이고 미확인 줄이 없다. 짝이 없는 실행은 PASS_SCOPED에 "17 reference(s) … not verified (… pinned at 45d2a478b800: no checkout …)"다. 세 경우(pin 뒤 HEAD, pin 없는 checkout, 저장소 이름 오타)는 stub git 저장소 단위 테스트가 본다.
- **1105/12-03은 이 기준에서 남음이다.** `CLAUDE.md:23`이 그대로 명령 11개를 손으로 적는다. 고친 커밋 `e9d9c36`은 PR #6 브랜치(`claude/mystifying-carson-f61c35`)에만 있고 `CLAUDE.md`만 바꾼다. README의 14개 반복문(`README.md:343`)은 그 커밋 밖이다.
- **D7 뒤에도 예산 검사는 예산을 넘는 빌드를 실패시킨다(12-R1).** entry를 약 3.5 KB 키운 빌드에서 `check:bundle`이 "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)"로 rc=1이었다. `check:bundle`은 예산을 실행 때 `budgets.json`에서 읽고(`scripts/check-bundle.ts:30-32`), 자가 fixture도 `예산+1`로 만든다(`:56-97`). 드릴 사본도 같은 파일을 읽는다: FE-GATE-020에서 "initial JS 205465 / 206848"(`FE-GATE-020.txt:6206`). 함께 움직인 다른 한도는 없다. `initialJsFiles` 32, lazy chunk 122,880 B, lab 셋은 그대로다. 새로 생긴 것은 `featureRouteInteractionMs` 500 ms 하나다.
- **새 발견 2건, 둘 다 Low·P3.** 12-01: 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건도 빠진다(검사 약화). 12-02: 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데, 빌드 뒤 검사(`generate-supply-chain.ts`, `check-bundle.ts`)는 루트를 읽는다. 그 변수를 셸에 두면 `check:bundle`이 이전 빌드로 판정한다. 12-R2에서 `.tmp/` 아래 빌드의 entry는 7,321 B, 루트는 1,065 B였는데 `check:bundle`은 루트 숫자 204,111 B로 PASS했다(같은 변이를 루트에 빌드하면 12-R1처럼 실패한다).
- **0929/12-03은 일부로 본다(§16.6은 고침).** `support/` → `src/adapters/` 직접 간선은 이제 막힌다. `support/` → 자기 기능 `adapters/` → `src/adapters/`의 두 단계 경로에는 규칙이 없다. 12-R3에서 presentation이 `support/`를 거쳐 `createReferenceHttpGateway`를 다시 내보내도 `check:architecture`(421 modules)와 ESLint가 둘 다 통과했다.
- **나머지 이월 6건은 남음이다.** 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03. 해당 파일이 바뀌지 않았다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 12 |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 미추적 `AGENTS.md`만)에서 읽었다. 2026-11-06 |
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 `config/ci/gates.json`에서 생성한 Gitea Actions workflow. merge job은 `runs-on: ubuntu-latest`(`.gitea/workflows/quality-gates.yml:39`) |
| 필수 요구와 규모·운영 목표 | 짝 백엔드 템플릿과 함께 빨리 출시한다. CI 시간·실패율 목표는 없다 |
| 읽은 코드·구성 범위 | 영역 커밋 전부: `9655958`, `67082cc`, `fc95672`, `a37ebba`, 12-04의 `ddbda4d`·`f4d5761`·`0e72c0c`·`510e2bb`, D7의 `0fee3fe`·`287dc6f`, 합친 커밋 `c3c595f`·`703a335`·`b8d53c9`. 전체로 읽은 파일: `check-system-test-prerequisites.ts`, `lib/provider-sandbox-namespaces.ts`, `lib/run-isolation.ts`, `lib/vite-build-inputs.ts`, `lib/feature-scaffold-drill.ts`, `check-bundle.ts`, `lib/performance-budgets.ts:1-80`, `playwright.config.ts`, `playwright.dev.config.ts`. 부분: `verify-documentation-readiness.ts:240-290`·`:370-530`, `lib/removal-fixture.ts:25-175`, `run-ci-gate.ts:30-70`·`:170-230`, `generate-supply-chain.ts:140-160`·`:300-330`, `build-frontend.ts:36-90`, `generate-build-manifest.ts:25-60`, `.dependency-cruiser.json` 전체 규칙, `contracts/ci-gates.ts:290-302`·`:500-522`, 단위 테스트 7파일(`system-test-prerequisites`, `ci-workflow-generation` 해당 절, `documentation-readiness:264-330`, `backend-contract-pin`, `removal-fixture:135-180`, `vite-build-inputs`, `playwright-run-isolation` 머리) |
| 읽은 문서(주장) | `CLAUDE.md:23`, `README.md:330-367`, `docs/operations/ci-quality-gates.md:15-32`·`:180-238`, `docs/security/supply-chain.md:183-194`, `docs/testing/taxonomy.md:15`·`:64-71`, `docs/testing/frontend-platform-testing-strategy.md:996-1060`(13.6), `docs/operations/performance-evidence.md:1-55`, `docs/README.md:43-53`, 지난 라운드 12번 문서, 지난 README 14~16절, 커밋 본문 |
| 게이트 결과 | **merge stage, CI env**(메인 세션, 2026-11-06 03:24~03:56, `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`): FE-GATE-001~012·020 rc=0(020 1,237초, 008 196초), **FE-GATE-013 rc=1**(2초, 사전 점검에서 멈춤). FE-GATE-013의 뒤 명령(`bbde570-013-parts/`): `test:system`의 vitest 81초 rc=1(96/114), 나머지 7개 rc=0. **공유 실행**(오케스트레이터, 로컬 env, `desktop:/tmp/claude-gates/r5/snap/`): `verify-documentation.local.txt` PASS_SCOPED(미확인 줄 없음), `verify-documentation.no-sibling.txt` PASS_SCOPED + 17개 미확인, `build.txt` 성공, `lab.txt` PASS |
| 수행한 테스트·실험 | **실행 환경 = desktop 로그와 snapshot.** 노트북에서는 읽기만 했다. 요청 3개를 오케스트레이터가 하나씩 돌렸다(`desktop:/tmp/claude-gates/r5/batch/out/R5-12-R1.log`~`R3.log`, 셋 다 `restore=clean`): `12-R1`(예산을 넘는 빌드에서 `check:bundle`), `12-R2`(`RUN_OUTPUT_ROOT`를 둔 `check:bundle`), `12-R3`(0929/12-03 두 단계 경로). 요청서 `scratchpad/r5/requests/12.md`. 12-04 완료 드릴은 오케스트레이터가 따로 돌렸다(`R5-01-1204-drill.log`). ssh로는 `/tmp/claude-gates/` 아래 로그만 읽었다 |
| 확인하지 못한 범위·이유 | 실제 Gitea runner(Actions 꺼짐). user namespace를 허용하는 호스트의 사전 점검과 `test:system`. 12-04의 게이트 단위 동시 실행(드릴은 e2e 실행 단위였다). desktop 옆 백엔드 checkout의 HEAD(규칙상 `/tmp/claude-gates` 밖은 읽지 않는다) |
| 이전 리뷰와 비교 가능한 범위 | `8a44226..bbde570`의 영역 커밋. 지난 실행 결과는 현재 증거로 다시 쓰지 않았다. 지난 12-R3 변이(`support/` → http 배럴)는 이번에 그래프 회귀 fixture로 들어왔다 |
## 2. 지난 발견 재확인
### 2.1 상태
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/12-01 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없음 (Medium·P1) | **고쳐짐**(허용 호스트 PASS는 단위 테스트만) | **완료 기준 1절(이 desktop에서 exit 1, 제한을 이름으로):** 충족. FE-GATE-013 로그가 사전 점검 보고서로 끝난다. 원문: "this host does not allow unprivileged user and network namespaces …", "probe: /usr/bin/bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net --ro-bind / / -- /bin/true exited 1", "bwrap stderr: bwrap: loopback: Failed RTM_NEWADDR …", "host settings: kernel.apparmor_restrict_unprivileged_userns = 1, …", 고치는 법 셋(`FE-GATE-013.txt`, E3). 코드: 옵션 목록은 한 상수이고 provider와 점검이 같이 쓴다(`scripts/lib/provider-sandbox-namespaces.ts:13-18`, `scripts/run-and-validate-provider.ts:257`, `scripts/check-system-test-prerequisites.ts:39-43`). **2절(허용 호스트 PASS):** 가짜 호스트 단위 테스트뿐이다(`tests/unit/system-test-prerequisites.test.ts:46-55`, 5건 통과 `FE-GATE-005.txt:255`). 실제 허용 호스트는 없다(5절). **3절(요구 목록 세 곳):** `docs/operations/ci-quality-gates.md:198-238`, `docs/security/supply-chain.md:186-193`, `docs/testing/taxonomy.md:15`·`:64-71`. 더해서 README(`README.md:335-338`), `config/ci/gates.json:2040-2043`, workflow 주석(`.gitea/workflows/quality-gates.yml:37-38`). 요구를 지우거나 바꾸면 기준선이 실패한다(`scripts/contracts/ci-gates.ts:508`, `:519`, 테스트 `tests/unit/ci-workflow-generation.test.ts:582-602`, 435건 통과 `FE-GATE-005.txt:41`). **§16과 다른 점:** §16.2 D4는 "PR A `9655958`, 기준선 `67082cc`"라고 적는다. `67082cc`는 PR A 끝 `a793b83`의 조상이 아니다(`git merge-base --is-ancestor` 거짓). PR B의 `c3c595f`로 들어왔다. PR A만으로는 `hostRequirements`가 gate 모양 해시 밖이었다. 기록 오류이고 기준 상태는 맞다. **경계:** provider job 둘(`quality-gates.yml:225`, `:271`)에는 주석이 없다. 그 job의 러너 전제는 1101/13-03(영역 13)이다 |
| 1105/12-02 | 문서 검사가 짝 백엔드를 pin이 아니라 옆 작업 트리에서 찾음 (Low·P2) | **고쳐짐** | 짝 목록과 커밋을 pin 파일에서 읽는다(`scripts/verify-documentation-readiness.ts:245-251`). 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 찾는다(`:255-272`). 없으면 이유(HEAD, pin 12자)와 함께 미확인으로 남긴다(`:263-267`, `:521-527`). pin에 없는 저장소로 나가는 `../` 링크는 실패다(`:277`). **완료 기준:** (가) pin 없는 checkout → PASS + 미확인: 단위 테스트 "reports the references as not verified when the checkout does not have the pinned commit"(`tests/unit/documentation-readiness.test.ts:311-322`). desktop 옆 checkout은 이제 pin 커밋을 가진 것으로 보인다. 로컬 실행에 미확인 줄이 없다(`r5/snap/verify-documentation.local.txt`, 출력 조건 `:519-527`). (나) pin 뒤 HEAD → pin 트리와 같은 결과: 단위 테스트 `:279-309`(pin 뒤 커밋과 미커밋 파일이 `missingPaths`). (다) 저장소 이름 오타 → 실패: `:325-330`. 22건 통과(`FE-GATE-005.txt:180`). 짝 없는 실행: PASS_SCOPED + 17개 미확인, 이유에 pin을 적는다(`verify-documentation.no-sibling.txt`, E3) |
| 1105/12-03 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 다름 (Medium·P2) | **남음**(이 기준) | `CLAUDE.md:23`이 명령 11개를 그대로 적는다(`git log 8a44226..bbde570 -- CLAUDE.md` 0건). 고친 커밋 `e9d9c36`은 `claude/mystifying-carson-f61c35`(원격 `docs/improvement-manual`, PR #6)에만 있다. PR #6은 이 라운드 범위 밖이라 내용은 판정하지 않는다. 그 커밋의 변경 파일은 `CLAUDE.md`와 `docs/improvement/` 셋이다(`git show --stat`). 완료 기준의 "README도 손으로 나열하지 않는다"는 그 커밋 밖이다. `README.md:343`이 14개 ID를 손으로 적는다(지금은 merge stage와 같다). 이번 라운드는 오케스트레이터가 merge stage를 `ci:gate`로 따로 돌려 메웠다(BRIEF §1) |
| 1105/12-04 | 한 checkout 두 실행이 고정 출력·포트로 부딪힘 (Medium·P2) | **오케스트레이터 판정.** 드릴: e2e 실행 단위 통과. 내 판단: 게이트 단위는 남음 | **된 것:** Playwright 설정 다섯이 `TEST_RUN_ID`로 결과·report·JUnit·서빙 빌드를 `.tmp/runs/<id>/`에 둔다(`playwright.config.ts:18-42`, `scripts/lib/run-isolation.ts:42-60`). 빌드 단계는 `RUN_OUTPUT_ROOT`를 읽는다(`scripts/build-frontend.ts:51`, `:66`, `scripts/generate-build-manifest.ts:31`, `vite.config.ts:184-188`). 서버는 빈 포트를 고르고 `--strictPort`, `reuseExistingServer: false`다(`run-isolation.ts:104-145`, `playwright.config.ts:19`, `:39-41`, `playwright.dev.config.ts:16`, `:32-34`). 생성 인덱스는 같으면 쓰지 않고 다르면 rename한다(`ddbda4d`). 단위 테스트 33건·11건 통과(`FE-GATE-005.txt:100`, `:242`). 문서: 테스트 전략 13.6절(`docs/testing/frontend-platform-testing-strategy.md:996-1060`), README(`README.md:362-367`). **안 된 것(코드로 본 것):** `ci:gate`와 증거 검사는 기본 경로만 읽는다. 그래서 게이트는 "한 checkout에 하나씩"으로 문서에만 정했다(`README.md:362-363`, M1). 1105 완료 기준은 게이트 단위("FE-GATE-008과 005, 또는 008 둘을 동시에")다. **오케스트레이터 드릴(`bbde570`, `R5-01-1204-drill.log`):** 한 checkout에서 `TEST_RUN_ID`를 다르게 준 e2e 두 실행을 함께 돌렸다. 부분 실행 19+19 통과, 전체 222+222 통과(각 4 skipped). "already used" 0줄, 포트(41159/46739, 33661/35167)와 출력 폴더가 달랐다. 부분 실행의 ✘ 1건은 실패를 기대하는 test다(`tests/e2e/preload-use.spec.ts:258-265`, `strictTest.fail()`). 그래서 e2e 실행 단위의 동시 실행은 확인됐다(E3). **내 판단:** 문언의 완료 기준(게이트 두 개를 동시에)은 이 드릴로 닫히지 않는다. 코드상 `ci:gate` 둘은 여전히 루트 `dist`와 `artifacts/`를 같이 쓴다. 저장소는 이것을 문서로 막았다(`README.md:362-363`, M1). 둘 다 적고 판정은 오케스트레이터에 둔다. **수정이 만든 결함:** 3절 12-02 |
| 1103/12-05 | 문서 검사가 지운 심볼·1절 밖 문서를 안 봄 | **일부**(§16.5와 같다) | `e72fb6e`는 지난 라운드가 든 예 한 곳(테스트 전략 11.2절의 `auth-recovery.test.ts`)만 고쳤다. 지운 심볼 검사와 1절 밖 문서 검사는 결정 대기다(커밋 본문) |
| 0929/12-03 | feature 안 layer 밖 폴더에 경계 규칙 없음 | **일부**(§16.6은 고침) | **고친 것:** `feature-and-app-roots-do-not-reach-adapters`의 from이 `src/features/` 전체에서 기능 `adapters/`와 `feature-adapter-contribution.ts`만 뺀다(`.dependency-cruiser.json:302-312`). 지난 12-R3 모양(`support/` → adapter 배럴)이 그래프 회귀 fixture가 됐다(`scripts/check-architecture.ts:823-840`). "31 regression checks PASS"(`FE-GATE-010.txt:4`, 지난 라운드 29). vitest 3건 통과(`tests/architecture/feature-adapter-reach.test.ts`, `FE-GATE-005.txt:766`). **남은 것:** 계층 밖 폴더에서 나가는 간선 중 `src/adapters/`만 막는다. 자기 기능 `adapters/`로 가는 간선은 막지 않는다. 그 규칙의 to는 `^src/adapters/`뿐이다(`.dependency-cruiser.json:309-311`). feature presentation → `support/`도 규칙이 없다(presentation의 금지 목록은 `src/adapters`, `src/bootstrap`, 기능 `adapters/`, `@tanstack`, `:118-127`). 그래서 presentation → `support/x.ts` → `../adapters/reference-http-gateway.ts` → `src/adapters/http/index.ts`의 간선 셋이 모두 규칙을 통과한다(E1). 같은 길로 `@tanstack`과 `src/bootstrap`에도 닿는다. 그래프는 간선 하나씩 본다(규칙 주석 `:303`). **실행(12-R3):** `support/gateway-reexport.ts`가 `../adapters/reference-http-gateway.ts`를 다시 내보내고 `presentation/r5-12-probe.ts`가 그것을 다시 내보내게 했다. `check:architecture` arch-rc=0("421 modules, 1301 dependencies", 무변이 419/1299 `FE-GATE-010.txt:3`, fixture 31 PASS), ESLint eslint-rc=0(`R5-12-R3.log`, E3). 결함 모양은 지난 12-R3과 같고 경로가 한 단계 길어졌을 뿐이다. 그래서 새 발견이 아니라 이 ID의 남은 부분으로 둔다 |
| 0929/12-07 | 예외 목록에 담당·재검토 시점 없음 | **남음**(§16.6 결정 대기) | 스키마가 `script`(또는 `path`)와 `reason`뿐이다(`scripts/lib/ungated-scripts.ts:17-30`, `scripts/lib/ungated-tests.ts:20-34`). §16.6은 owner 값을 고르는 결정으로 적었다. 스키마는 그대로다 |
| 0929/12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 안 봄 | **남음** | 파일 커밋 0개. receiver 이름 정규식(`scripts/check-request-fanout.ts:23`), 같은 줄 `fanout-reviewed:`만 인정(`:109`) |
| 0929/12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | **남음** | `config/ci/contract-baseline.json:6-8`(100/104/110)과 `tests/unit/ci-workflow-generation.test.ts:199-203`(100, 104, 110). 절차 문서에 테스트 갱신 단계가 없다(`docs/operations/ci-quality-gates.md:15-27`). `67082cc`는 해시만 바꿔 이 둘을 건드리지 않았다 |
| 0929/12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | **남음** | `package.json:182` `"dependency-cruiser": "18.1.0"`. 검사기는 자기 그래프를 쓴다 |
| 0929/12-06 | Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈 | **남음** | `scripts/lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어). Vitest는 `*.test.*`만 돈다(`vitest.config.ts:45`) |
| 1101/12-03 | 디자인 규칙이 정해진 파일·형식만 봄 | **남음** | `check-design-system.ts`, `lib/design-system-rules.ts` 커밋 0개 |
참고(§16.5·16.6 밖, 세지 않음): 1101 FOLLOW-UP `noUnusedParameters`는 그대로다(`tsconfig.base.json`, `tsconfig*.json` 커밋 0개). 1101 U-1(Actions 꺼짐)은 미확인이다(Gitea를 부르지 않았다). 1103/12-01의 보존 조건("셸 CSS를 바꾸면 시각 게이트가 여전히 실패")은 여전히 미검증이다(5절).
요약: 지난 라운드 영역 12의 1105 발견 4건, §16.5 1건, §16.6 7건을 봤다. 고쳐짐 2(1105/12-01·12-02), 일부 2(1103/12-05, 0929/12-03), 남음 7(1105/12-03, 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03), 재발 0, 틀린 발견 0, 오케스트레이터 판정 1(1105/12-04: e2e 실행 단위 드릴 통과, 게이트 단위는 남았다고 본다). §16과 다르게 본 것: 0929/12-03(고침 → 일부), 1105/12-01의 커밋 위치(`67082cc`는 PR B).
### 2.2 `8a44226` 이후 바뀐 검사의 약화 여부
| 바뀐 것 | 판정 | 근거 |
|---|---|---|
| 초기 JS 예산 `initialJsGzipBytes` 204,800 → 206,848 B(`287dc6f`, D7) | **결정된 상향. 약화로 세지 않는다** | 메인 세션 결정이고, 이유·버린 대안·재검토 조건이 커밋 본문과 `docs/operations/performance-evidence.md:44-53`, CHANGELOG(`CHANGELOG.md:56`)에 있다. 지난 라운드의 파일 상한 25 → 32와 같은 기준이다. **검사 자체는 그대로다:** 예산을 실행 때 읽고(`scripts/check-bundle.ts:30-32`), 비교는 `<=`(`scripts/lib/performance-budgets.ts:23-26`), 자가 fixture는 `예산+1`(`check-bundle.ts:56-97`). 두 파일은 이 범위에서 바뀌지 않았다. 생성 기능 드릴은 사본에서 merge stage를 돌고 `check:bundle`을 빼지 않는다(`scripts/lib/feature-scaffold-drill.ts:26-46`). 사본도 새 예산을 읽었다: "initial JS 205465 / 206848"(`FE-GATE-020.txt:6206`). 템플릿은 CI env에서 204,158 B(`FE-GATE-012.txt:76`). 여유: 템플릿 2,690 B, 드릴 1,383 B. 넘는 빌드의 실제 실패도 확인했다(12-R1: "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)", bundle-rc=1). **함께 움직인 한도 없음:** `budgets.json` diff는 이 값과 새 `featureRouteInteractionMs`(500 ms, `81701ad`) 두 줄이다. `initialJsFiles` 32, `lazyChunkGzipBytes` 122,880, lab `lcpMs`·`cls`·`namedInteractionMs`, field 값은 그대로다. `feature-shape-ceilings.json`은 기록(`initialJavascript`)만 다시 적었다(`0fee3fe`). 기록 대조 허용치는 1% → 256 B로 오히려 좁아졌다(`scripts/scale/measure-feature-shape-growth.ts:227`) |
| 제거 fixture 문서 테스트 목록 2 → 6(`5c0b37e`, `6d084cf`, 14-01·14-02 커밋, `scripts/lib/removal-fixture.ts:70-81`) | **약화 1건 → 새 발견 12-01** | 새로 넣은 넷 중 `backend-contract-pin.test.ts`는 `8a44226`에서 capability 드릴 사본에서도 돌던 파일이다(그때 목록은 2개, 그 파일은 문서를 읽지 않았다). 이제 문서를 읽는 test 1건 때문에 15건 전체가 빠진다. 나머지 셋은 새 테스트라 전에 돌던 것이 빠진 것은 아니다. 같은 모양이 `feature-tracked-files.test.ts`(문서 무관 1건)에도 있다 |
| vite 빌드 입력 목록을 한 모듈로(`c9aa73f`), `run-isolation.ts` 추가(`b8d53c9`, `f4d5761`) | **약화 아님** | 목록은 `scripts/lib/vite-build-inputs.ts:11-21` 하나다. 테스트가 `vite.config.ts`의 상대 import 그래프를 따라가 빠진 파일을 이름으로 실패시킨다(`tests/unit/vite-build-inputs.test.ts:28-46`, `:58-71`, 2건 통과 `FE-GATE-005.txt:275`). 소비자를 `existsSync`로 거르는 것(`:19-22`)은 측정 스크립트를 지우는 샘플 제거 사본 때문이다. 템플릿에서는 둘 다 있고, 측정 스크립트가 없어지면 `feature-shape-growth.test.ts`가 import에서 실패한다 |
| `playwright-run-isolation.test.ts`가 capability 설정이 있을 때만 그 설정을 본다(`f4d5761`, `0e72c0c`) | **약화 아님** | `HAS_CAPABILITIES`(`tests/unit/playwright-run-isolation.test.ts:27-42`, `:245`)는 그 설정을 지우는 `test:browser-file-storage-removal` 사본 때문이다. 템플릿에는 파일이 있어 33건이 돈다(`FE-GATE-005.txt:100`) |
| gate 모양 해시에 `hostRequirements`(`67082cc`) | **강화** | 1105/12-01. 요구 한 줄을 지워도 기준선이 실패한다(`tests/unit/ci-workflow-generation.test.ts:582-602`) |
| `feature-and-app-roots-do-not-reach-adapters` from 확대(`a37ebba`) | **강화** | 0929/12-03. 허용은 바뀌지 않고 금지만 늘었다. 저장소 위반 0(`FE-GATE-010.txt:3-4`) |
| dev 설정 `reuseExistingServer: true` → `false`, 서버 넷 `--strictPort`(`0e72c0c`) | **강화** | 남의 서버를 검사하는 길이 막혔다(`playwright.dev.config.ts:32-34`) |
| 문서 검사: 짝 checkout에 pin 커밋이 없으면 실패 대신 미확인(`fc95672`) | **약화 아님** | 1105/12-02가 권한 동작이다. 문서와 무관한 실패를 없앤다. 출력에 이유가 남는다(`verify-documentation-readiness.ts:263-267`, `:521-527`). 대신 저장소 이름 오타는 이제 실패한다 |
| 문서 검사가 지운 템플릿 기능의 경로를 요구하지 않음(`332bfee`, `50b631e`) | **영역 14가 판정** | 기능의 `feature-module.ts`가 없을 때만이다(`scripts/lib/removable-template-features.ts`) |
| `orphanExemptRows`에 `AUTH_REDIRECT_TRANSACTION`(`dc7c95b`) | **영역 05가 판정** | `config/contracts/registry-governance.json:376` |
| 새 `skip`·`fixme`·`eslint-disable`·`@ts-ignore` | **영역 12 경로 0건** | `git diff 8a44226..bbde570 -- src scripts tests eslint.config.ts '*.config.ts'`의 추가 줄 검색. 나온 것은 `tests/e2e/service-worker-update.spec.ts`의 firefox skip(기존 줄의 이동과 새 test 1건, 영역 06)과 음성 타입 테스트의 `@ts-expect-error` 2건뿐이다 |
## 3. 이번 발견 (36.3)
새 발견 2건: Low 2 / P3 2 / 확인된 결함 1 · 구조적 위험 1. High 이상 없음. P1 없음.
### 3.1 발견 목록
| ID | 심각도·우선순위 | 성격 | 관련 관점 | 한 줄 |
|---|---|---|---|---|
| 12-01 | Low · P3 | 구조적 위험 | 10, 21, 27, 24 | 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건(짝 백엔드 답 표와 Envelope 판정 대조)도 빠진다 |
| 12-02 | Low · P3 | 확인된 결함 | 21, 19, 5, 23, 20 | 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰고 빌드 뒤 검사는 루트를 읽어, 그 변수를 셸에 두면 `check:bundle`(FE-GATE-012)이 이전 빌드로 판정한다 |
### 12-01 제거 fixture가 문서를 읽는 테스트를 파일째 빼서, capability 제거 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서와 무관한 14건도 빠진다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(검사 약화. 빠진 것은 실행으로 확인했고, 그 때문에 놓칠 결함은 확인하지 않았다) |
| 관련 관점 | 10, 21, 27, 24 |
| 근거 | **목록:** 문서를 복사하지 않는 사본에서는 `REMOVAL_FIXTURE_DOCUMENT_TESTS`의 파일을 지운다(`scripts/lib/removal-fixture.ts:70-81`, `:84-90`, `:160-162`). capability 드릴 셋이 그 사본을 쓴다(`scripts/test-optional-recipe-removal.ts:31`, `scripts/test-browser-file-storage-runtime-removal.ts:69`, `scripts/test-realtime-runtime-removal.ts:54`). 통합 때 `tests/unit/backend-contract-pin.test.ts`를 목록에 넣었다(`5c0b37e`, §16.3). **그 파일:** 15건 중 문서를 읽는 것은 6.1절 표를 읽는 1건뿐이다(`tests/unit/backend-contract-pin.test.ts:263-275`, `:293-303`). 나머지 14건은 config 파일과 코드만 본다. pin 커밋(`:151`), 답 표 사본(`:165`), 생성기 사실(`:187`), 중복(`:211`), 답 행마다 `envelopeFailureEffect`·`invitesKeyedResend`가 표의 답을 내는지(`:219-232`), Envelope 표 행이 답 표에 있는지(`:234-253`)다. **이전:** `8a44226`의 목록은 2개였고 이 파일은 문서를 읽지 않았다. 그래서 capability 사본에서도 돌았다(`git show 8a44226:scripts/lib/removal-fixture.ts`, 같은 커밋의 테스트 파일, E1). **지금(실행):** FE-GATE-020 로그에서 이 파일은 샘플 제거와 생성 기능 드릴 안에서만 나온다(`FE-GATE-020.txt` 8회, 마지막 `:7225`). capability 드릴 셋(`:9803` 이후)에는 없다(E3). **가드:** 목록이 "문서를 읽는 테스트"인지 보는 테스트는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만 본다(`tests/unit/removal-fixture.test.ts:161`). 이 파일은 주석 한 줄(`backend-contract-pin.test.ts:259`) 때문에 통과한다. 실제 읽기는 pin 값(`pin.frontend.contractDocument`)으로 한다. **같은 모양:** `tests/unit/feature-tracked-files.test.ts:25`(문서 무관 1건). 새 테스트라 전에 돌던 것이 빠진 것은 아니다 |
| 발생 조건 | capability 하나(optional recipe, browser file storage, realtime)를 지운 사본이 짝 백엔드 답 표 대조를 깨뜨릴 때. 예: 제거가 `src/adapters/http/backend-envelope.ts`나 `config/contracts/`의 파일을 함께 바꾸는 경우 |
| 영향 | 그 깨짐을 FE-GATE-020이 알리지 않는다. 템플릿 자신의 `test:unit`은 그 14건을 계속 돌린다(`FE-GATE-005.txt`). 지금 세 capability 제거는 그 파일들을 건드리지 않는다(추론). 그래서 지금 놓친 결함은 없다. 목록이 파일 단위라 문서를 읽는 test 하나를 어느 파일에 더하면 그 파일 전체가 드릴 사본에서 사라진다. 사람이 그것을 알아차릴 장치가 없다 |
| 심각도·우선순위 | Low · P3 — 사용자 피해와 게이트 실패가 없다. 결과 불명 쓰기의 판정 대조라는 중요한 검사가 사본 셋에서 빠지지만, 같은 판정은 `tests/unit/backend-envelope.test.ts`가 사본에서도 본다(`git grep envelopeFailureEffect -- tests`). 지난 라운드의 "변이가 살아남는 테스트" 항목들(1105/06-02 등 Low·P3)과 같은 기준이다 |
| 통제·증거 | 목표 M3(드릴 사본이 문서와 무관한 테스트를 모두 돈다) / 확인 M2(파일 단위 제외. 가드는 글자 검색) · E3(FE-GATE-020 로그) + E1 |
| 확실성과 남은 가정 | 빠진 사실과 건수는 확정이다. 그 때문에 놓칠 실제 결함은 없다고 본다(추론). capability 제거가 pin 대조 대상 파일을 바꾸는 경로는 지금 없다 |
| 결정의 근거 | 확인한 사실: 03-01의 새 test가 같은 파일에 들어갔고, 통합 때 ENOENT를 피하려고 파일째 뺐다(§16.3 `5c0b37e` 행). 추론: 통합 중의 가장 작은 수정을 골랐다. 그 test를 따로 떼는 것은 브랜치 범위 밖이었다 |
| 이해 비용 | 드릴을 고치는 사람은 목록의 파일마다 문서를 읽는 test가 몇 건인지 직접 세어야 한다 |
| 최소 개선 방향 | (1) 문서를 읽는 test를 자기 파일로 뗀다. 예: `codesPossiblyAfterWrite`와 그 describe를 `tests/unit/backend-contract-pin-document.test.ts`로 옮기고 목록에는 그 파일을 둔다. `feature-tracked-files.test.ts`도 같다. (2) 가드가 주석이 아니라 실제 읽기(`readFile*` 인자나 pin의 문서 경로)를 보게 한다 |
| 대안 비교 | (a) 현 상태: 비용 0, 파일 단위로 계속 빠진다. (b) 위 (1): 파일 두 개를 나눈다. 사본이 문서 무관 test를 다 돈다. (c) 사본에 pin이 가리키는 문서 한 개만 복사: 문서 테스트가 늘 때마다 복사 목록이 늘고, capability 드릴이 "문서 없이"를 증명한다는 전제(`removal-fixture.ts:50-55`)가 흐려진다. (b)를 권한다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 문서를 복사하는 드릴(샘플 제거, 생성 기능)의 동작은 그대로 둔다 |
| 비용·부작용 | 테스트 파일 둘 분리와 목록 두 줄. 실행 시간 변화는 수십 ms |
| 재검토 조건 | capability 드릴이 문서를 함께 복사하게 바뀌면 이 목록 자체가 필요 없다 |
| 완료 기준 | capability 드릴 셋의 `test:unit` 출력에 `backend-contract-pin` 대조 14건이 다시 나온다. 문서를 읽는 test만 사본에서 빠진다. 가드가 주석만 있는 파일을 거절한다 |
| 검증 방법 | FE-GATE-020 로그에서 `:9803` 이후 구간의 테스트 이름 검색. 가드 변이: 문서를 읽지 않고 주석에만 `docs/`가 있는 파일을 목록에 넣으면 `removal-fixture.test.ts`가 실패한다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
### 12-02 1105/12-04 수정 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰고 빌드 뒤 검사는 루트를 읽어, 그 변수를 셸에 두면 `check:bundle`이 이전 빌드로 판정한다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함(1105/12-04 수정 `f4d5761`이 만들었다. 문서가 금한 사용에서 거짓 통과를 실행으로 확인했다) |
| 관련 관점 | 21, 19, 5, 23, 20 |
| 근거 | **쓰는 쪽:** 빌드 단계 전부가 `RUN_OUTPUT_ROOT`를 읽는다. `dist`(`scripts/build-frontend.ts:51`, `vite.config.ts:184-188`), 생성 모듈(`build-frontend.ts:66`), build manifest(`scripts/generate-build-manifest.ts:31`). 값은 `.`이나 `.tmp/` 아래만 받는다(`scripts/lib/run-isolation.ts:63-75`). **읽는 쪽:** FE-GATE-012의 `check:bundle`은 `generate-supply-chain.ts`와 `check-bundle.ts`를 돈다(`package.json:115`). 둘 다 이 변수를 읽지 않는다. 루트 `artifacts/release/build-manifest.json`(`scripts/generate-supply-chain.ts:144`), 루트 `dist`(`:156`, `scripts/lib/release-candidate.ts:104`), 루트 `artifacts/performance/bundle.json`과 `dist/.vite/manifest.json`(`scripts/check-bundle.ts:24-29`)을 읽는다. **신선도 검사가 막지 못한다:** `ci:gate`는 명령 하나가 증거 파일을 새로 썼는지만 본다(`scripts/run-ci-gate.ts:41-56`, `:189-206`). FE-GATE-012의 증거 `bundle.json`은 `check:bundle`이 루트에 다시 쓴다(`generate-supply-chain.ts:325-329`, `check-bundle.ts:115-119`). 그래서 빌드가 다른 폴더에 썼어도 "freshly produced"가 된다. **문서:** "`RUN_OUTPUT_ROOT`는 직접 export하지 않는다"(`docs/testing/frontend-platform-testing-strategy.md:1035`, M1). 이를 막는 코드는 없다. 표(`:1026-1030`)는 이 변수를 "빌드 단계 전부"가 읽는다고만 적는다. **실행(12-R2, `R5-12-R2.log`):** 깨끗한 루트 빌드(root-build-rc=0) 뒤 entry를 키운 변이를 `RUN_OUTPUT_ROOT=.tmp/r5-12`로 빌드했다(run-build-rc=0). 같은 변수로 `check:bundle`을 돌리자 "Bundle budget: PASS (initial JS 204111 / 206848 gzip bytes, 27 / 32 files)", stale-bundle-rc=0. entry gzip 크기는 루트 `dist` 1,065 B, `.tmp/r5-12/dist` 7,321 B였다. 같은 변이를 루트에 빌드하면 "210352 … over by 3504"로 실패한다(12-R1). 그래서 이번 변경의 빌드는 예산을 3,504 B 넘는데 검사는 이전 빌드로 통과했다(E3) |
| 발생 조건 | 개발자나 에이전트가 셸에 `RUN_OUTPUT_ROOT`를 둔 채(예: 빌드 결과를 따로 받아 보려고) `build`, `check:bundle`, 또는 `ci:gate -- FE-GATE-012`를 돌릴 때. 루트에 이전 빌드가 남아 있어야 한다. 없으면 `dist is missing`으로 실패한다(`release-candidate.ts:106-108`) |
| 영향 | merge 게이트 하나가 이번 변경의 빌드가 아니라 이전 빌드의 크기로 통과한다. 예산을 넘는 변경이 로컬 게이트를 통과한 것으로 기록된다. CI는 이 변수를 두지 않아 영향이 없다(workflow env `quality-gates.yml:26-31`). `check:optional-recipes --require-dist`, `check:app-build-input:bundle`도 루트를 읽는 같은 모양일 수 있다(확인 안 함) |
| 심각도·우선순위 | Low · P3 — 문서가 금한 사용이 필요하고 CI에는 영향이 없다. 다만 증거 신선도 검사가 막지 못하는 거짓 통과라 고치는 비용(몇 줄)에 비해 가치가 있다 |
| 통제·증거 | 목표 M3(게이트가 쓰는 곳과 읽는 곳이 다르면 시작 전에 거절) / 확인 M1(문서 한 줄) · E3(12-R2, 대조군 12-R1) + E1 |
| 확실성과 남은 가정 | `check:bundle`의 거짓 통과는 확정이다. `ci:gate -- FE-GATE-012` 전체로는 돌리지 않았다. 신선도 검사가 막지 못한다는 것은 코드 추적이다(위 근거). Playwright 설정은 web server에 늘 값을 넣으므로(`playwright.config.ts:37`) Playwright 경로에는 이 문제가 없다 |
| 결정의 근거 | 확인한 사실: `f4d5761`은 "빌드 코드는 `TEST_RUN_ID`를 읽지 않는다"와 "게이트·증거 검사는 기본 경로만 읽는다"를 한계로 적었다(커밋 본문, 13.6절 한계). 그 한계를 `TEST_RUN_ID`로 게이트를 돌릴 때("not freshly produced"로 실패)만 따졌다. `RUN_OUTPUT_ROOT`를 직접 둔 경우는 적지 않았다. 추론: 빌드 출력 위치를 env로 바꿀 수 있게 하면서, 같은 빌드를 읽는 검사 쪽을 같은 변수에 묶지 않았다 |
| 이해 비용 | 통과한 게이트 로그만 보고는 어느 빌드를 쟀는지 알 수 없다. `bundle.json`의 `outputs` 이름과 `.tmp/` 아래 빌드를 직접 비교해야 한다 |
| 최소 개선 방향 | (1) `ci:gate`가 `RUN_OUTPUT_ROOT`나 `TEST_RUN_ID`가 있으면 이유를 적고 시작하지 않는다. (2) 또는 빌드 뒤 검사(`generate-supply-chain.ts`, `check-bundle.ts`, `release-candidate.ts`의 `collectDistOutputs`)가 `runOutputPath`로 같은 루트를 읽는다 |
| 대안 비교 | (a) 현 상태 + 문서: 비용 0, 거짓 통과 가능. (b) 위 (1): 몇 줄. 게이트는 늘 기본 경로라는 지금 전제(`README.md:362-363`)와 맞다. (c) 위 (2): 게이트도 run 단위로 격리하는 방향(D6 재검토 조건)과 맞지만 증거 경로 54개 파일과 upload를 손봐야 한다(1105 §14 12-04 비용). (b)를 먼저 권한다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. Playwright 실행 격리와 빈 포트는 그대로 둔다 |
| 비용·부작용 | (b)는 `run-ci-gate.ts` 몇 줄과 단위 테스트 1건. 디버깅으로 변수를 둔 사람은 게이트 전에 지워야 한다 |
| 재검토 조건 | 게이트와 증거 검사가 run ID를 읽게 될 때(D6 재검토 조건) |
| 완료 기준 | `RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`가 변수 이름을 적고 실패하거나, 같은 루트의 빌드를 잰다. 루트의 이전 빌드로 PASS하지 않는다 |
| 검증 방법 | 12-R2와 같은 순서(깨끗한 루트 빌드 → 예산 초과 변이를 다른 루트에 빌드 → 검사) |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 적용 제외 — 이 영역에 도메인 규칙이 없다 | — | — | - |
| 2 | 구조적 성숙도 | 적용 — 경계 강제 장치 | M3 / import 방향 M3(그래프 fixture 31), 계층 밖 폴더 → `src/adapters` 직접 M3, 계층 밖 폴더 → 기능 `adapters/` M0 | E2·E3 | P · 0929/12-03 일부. 두 단계 경로가 그래프·ESLint를 통과한다(12-R3) |
| 3 | 변경 용이성 | 적용 | M3 / P | E2 | P · 러너 요구를 바꾸면 기준선을 다시 적는다(의도한 비용, `67082cc`). 게이트 계약 크기가 기준선과 테스트 상수 두 곳(0929/12-04) |
| 4 | 인지 부하 | 적용 | — | E1 | P · `gates.json` 3,009줄, workflow 504줄. 실행 격리 변수 둘과 포트 변수 다섯이 한 절(13.6)과 한 모듈(`run-isolation.ts`)에 있다 |
| **5** | 위험 가시성 | 적용 | M3 / P | E3 | P · FE-GATE-013이 이제 PASS 대신 이름으로 실패한다(1105/12-01). `CLAUDE.md` 목록은 여전히 merge 게이트 7개를 빼고 "통과"라 할 수 있다(1105/12-03). `RUN_OUTPUT_ROOT`를 두면 `check:bundle`이 이전 빌드로 통과한다(12-02, 12-R2) |
| 6 | 실패 성숙도 | 적용 제외 — 런타임 실패 처리가 없는 영역 | — | — | - |
| 7 | 운영 성숙도 | 다른 영역 | — | — | > 영역 13 |
| 8 | 디버깅 가능성 | 적용 | M3 / P | E3 | P · 사전 점검이 원인·sysctl·고치는 법을 적는다(`FE-GATE-013.txt`). 문서 검사 미확인에 이유(pin, HEAD)를 적는다. 예산 실패가 초과량을 적는다. fanout 메시지는 그대로(0929/12-01) |
| 9 | 유지보수 성숙도 | 적용 | — | E1 | P · 미사용 `dependency-cruiser`(0929/12-05). merge 게이트 손 목록 둘(1105/12-03). 문서 테스트 제외가 파일 단위(12-01) |
| **10** | 테스트 성숙도 | 적용 | M3 / P | E2·E3 | P · 고친 검사마다 RED 테스트가 있다(2.1절). capability 드릴 사본에서 pin 대조 14건이 빠진다(12-01). 고아 `*.spec.ts` 판정(0929/12-06) |
| 11 | 데이터 성숙도 | 적용 제외 | — | — | - |
| 12 | 동시성 성숙도 | 일부 적용 — 한 checkout 두 실행(1105/12-04) | M2 / Playwright 실행 M3(단위 테스트·드릴), 게이트 M1(문서) | E2·E3 | P · e2e 두 실행이 한 checkout에서 함께 통과했다(오케스트레이터 드릴). 게이트 두 개는 여전히 함께 돌 수 없다. 다른 선택(`VITE_PRODUCT_FEATURES`)의 두 실행은 `src/.generated`를 서로 바꾼다(13.6절 한계) |
| 13 | 확장성 | 일부 적용 | — | E3 | > 영역 15. 이 영역 몫: 예산 여유 템플릿 2,690 B, 생성 기능 둘 드릴 1,383 B(CI env, `FE-GATE-012.txt:76`, `FE-GATE-020.txt:6206`) |
| 14 | 성능 성숙도 | 적용 | — | 로컬만 | ? · runner가 없다. desktop에서 FE-GATE-020 1,237초(job 상한 45분의 46%), 008 196초 |
| 15 | 보안 성숙도 | 적용(workflow 범위) | M4 / M4 | E1 | O · workflow diff는 주석 2줄과 13-01·13-02 변경뿐이다. `permissions: contents: read`(`quality-gates.yml:23-24`) 그대로. provider sandbox 검증은 이 호스트에서 돌지 못한다(FE-GATE-013) |
| 16 | 의존성 성숙도 | 적용 | M3 / P | E2·E3 | P · 문서 검사가 짝 백엔드 pin을 쓴다(1105/12-02 고쳐짐). 미사용 `dependency-cruiser@18.1.0`(0929/12-05) |
| 17 | API / Contract | 적용 | M3 / P | E2 | P · pin 답 표와 Envelope 판정 대조는 템플릿 `test:unit`에서 돈다. capability 드릴 사본에서는 빠진다(12-01). 백엔드 drift는 영역 07 |
| 18 | 배포 성숙도 | 다른 영역 | — | — | > 영역 13 |
| **19** | 설정 성숙도 | 적용 | M3 / P | E3 | P · 러너 요구가 계약(`hostRequirements`)·workflow·문서 셋·기준선 해시에 있다(1105/12-01 고쳐짐). 셸의 `RUN_OUTPUT_ROOT`가 빌드 위치만 바꾸고 검사 위치는 그대로다(12-02) |
| 20 | 개발자 경험 | 적용 | — | E3 | P · 이 desktop에서 FE-GATE-013이 첫 줄에서 고치는 법을 준다. `verify:documentation`이 짝 유무와 무관하게 통과한다. Playwright 두 실행이 한 checkout을 같이 쓴다. 게이트는 여전히 하나씩 |
| **21** | Guardrail 성숙도 | 적용 | M3 / 로컬 P, 머지 시점 미확인 | E3 | P(로컬) · ?(머지 시점) · merge 14게이트 중 13개가 이 호스트에서 통과한다. 013은 호스트 조건으로 실패한다(사용자 결정). 남은 틈: 1105/12-03, 0929/12-03(일부), 12-01, 12-02, 0929/12-06 |
| 22 | 추상화 성숙도 | 적용 | — | E1 | O · namespace 옵션은 provider와 점검이 한 상수를 쓴다. 실행 격리 규칙은 한 모듈이다. 빌드 입력 목록도 한 모듈이다 |
| **23** | 일관성 | 적용 | — | E1 | P · merge 게이트 목록이 계약·README·`CLAUDE.md` 세 곳(1105/12-03). 문서 검사와 pin 테스트가 같은 pin을 본다(1105/12-02 고쳐짐). 빌드와 빌드 뒤 검사가 다른 루트를 읽을 수 있다(12-02) |
| 24 | 네이밍 / 의미 | 적용 | — | E1 | P · "System test prerequisites: PASS"가 이 호스트에서 더는 나오지 않는다. `REMOVAL_FIXTURE_DOCUMENT_TESTS`의 주석은 "문서를 읽는 테스트"인데 문서와 무관한 test까지 뺀다(12-01) |
| 25 | 조직 확장성 | 적용(팀 하나라 구조만) | — | E2 | P · 두 에이전트나 IDE가 Playwright를 함께 돌릴 수 있다. 게이트는 한 checkout에 하나씩이다 |
| 26 | Ownership | 적용 | M1 / P | E1 | P · 예외 목록에 담당·재검토가 없다(0929/12-07, 결정 대기). 기준선 owner가 개인 이름이다(`config/ci/contract-baseline.json:3`) |
| 27 | 삭제 가능성 | 적용 | M3 / P | E3 | P · 제거 드릴 다섯이 통과한다(FE-GATE-020 rc=0). capability 사본은 pin 대조를 돌지 않는다(12-01) |
| 28 | 회복 가능성 | 적용 제외 — 이 영역에 복구 경로가 없다 | — | — | - |
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| user namespace를 허용하는 호스트에서 사전 점검 PASS와 `test:system` 114건 | 그런 호스트가 없다. 가짜 호스트 단위 테스트뿐이다 | bwrap AppArmor profile을 넣은 호스트나 다른 runner에서 1회 |
| 1105/12-04 완료 기준의 문언(게이트 두 개 동시 실행) | 오케스트레이터 드릴은 e2e 실행 단위였다. 게이트 단위는 코드상 기본 경로를 같이 쓴다 | 한 checkout에서 `ci:gate -- FE-GATE-008`과 `ci:gate -- FE-GATE-005`를 함께 |
| 12-02의 `ci:gate -- FE-GATE-012` 전체 | `check:bundle`만 돌렸다 | 12-R2 순서로 `RUN_OUTPUT_ROOT=… corepack pnpm ci:gate -- FE-GATE-012` |
| 1105/12-02의 "짝 HEAD가 pin 뒤"를 실제 checkout에서 | desktop 옆 checkout의 HEAD를 읽지 않았다(`/tmp/claude-gates` 밖) | desktop에서 `git -C ../clean-architecture-backend-template rev-parse HEAD`와 로컬 실행 대조 |
| 1103/12-01 보존 조건(셸 CSS 회귀가 시각 게이트에서 실패) | 지난 라운드 변이가 화면을 바꾸지 않았고 이번에 다시 요청하지 않았다 | 배경색이나 사이드바 너비를 바꾸고 기능 1개 상태에서 `test:visual` |
| 실제 Gitea runner와 머지 시점 강제 | Actions 꺼짐(1101 U-1) | runner 1대와 PR 1건 |
| 12-02 모양이 `check:optional-recipes --require-dist`, `check:app-build-input:bundle`에도 있는가 | 읽지 않았다 | 두 스크립트의 `dist` 읽기 경로 확인 |
## 6. 실행 기록
| ID | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 12-R1 | `corepack pnpm -s build; corepack pnpm -s check:bundle` | `scratchpad/r5/12/12-inflate-entry.diff`(entry에 압축 안 되는 문자열 약 8,000자) | build-rc=0, bundle-rc=1 | **기대대로.** "initial JavaScript 210352 gzip bytes > budget 206848 (over by 3504)". 무변이 대조 `FE-GATE-012.txt:76`(204158 PASS). load 2.55, `restore=clean` |
| 12-R2 | 변이를 빼고 루트 빌드 → 변이를 다시 넣고 `RUN_OUTPUT_ROOT=.tmp/r5-12` 빌드 → 같은 변수로 `check:bundle` | 12-R1과 같은 파일 | root-build-rc=0, run-build-rc=0, stale-bundle-rc=0 | **기대대로(후보 확인).** "Bundle budget: PASS (initial JS 204111 / 206848 …)". entry gzip: 루트 1,065 B, `.tmp/r5-12` 7,321 B. load 2.98, `restore=clean` |
| 12-R3 | `corepack pnpm -s check:architecture; corepack pnpm -s exec eslint <두 파일>` | `scratchpad/r5/12/12-support-two-hop.diff`(`support/gateway-reexport.ts`, `presentation/r5-12-probe.ts`) | arch-rc=0, eslint-rc=0 | **빈틈 확인.** "421 modules, 1301 dependencies"(무변이 419/1299), fixture 31 PASS. load 2.82, `restore=clean` |
| R5-01-1204-drill(오케스트레이터) | 한 checkout에서 `TEST_RUN_ID`가 다른 `playwright test` 두 개를 함께, 부분(2 spec)과 전체 | 없음 | a·b 모두 0 | 부분 19+19, 전체 222+222 통과(각 4 skipped). "already used" 0줄. 포트와 출력 폴더가 실행마다 달랐다. `restore=clean` |
| ssh 읽기 | `cat`·`grep`: `bbde570-ci/summary.txt`, `FE-GATE-0NN.log`, `gate-artifacts/FE-GATE-005·010·012·013·020.txt`, `bbde570-013-parts/*`, `r5/snap/verify-documentation.*.txt`, `build.txt`, `lab.txt` | 없음 | 0 | 0절·2절 근거 |
배치 rc는 마지막 echo의 것이라 판정은 로그 안의 `*-rc=` 줄로 했다. 노트북에서 돌린 것은 읽기 명령뿐이다(`git show`, `git log`, `git diff`, `git grep`, `git merge-base --is-ancestor`, `git apply --check`로 패치 적용 가능 확인). 패치 둘은 `bbde570`에 깨끗이 적용된다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 12-01 | Low · P3 | 구조적 위험 | 제거 fixture가 문서 테스트를 파일째 빼서 capability 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서 무관 14건도 빠진다 | `scripts/lib/removal-fixture.ts:70-81`, `tests/unit/backend-contract-pin.test.ts:219-253`, `tests/unit/removal-fixture.test.ts:161` |
| 12-02 | Low · P3 | 확인된 결함 | 셸에 `RUN_OUTPUT_ROOT`가 있으면 빌드는 `.tmp/` 아래에 쓰고 `check:bundle`은 루트의 이전 빌드로 판정한다(12-R2: 예산 3,504 B 초과 빌드에서 PASS) | `scripts/build-frontend.ts:51`, `scripts/generate-supply-chain.ts:144`, `:156`, `scripts/check-bundle.ts:24-29`, `scripts/run-ci-gate.ts:189-206` |
@@ -0,0 +1,186 @@
# 영역 13 — 빌드·릴리스·설정·공급망
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.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/scan-dependency-advisories.ts`, `scripts/lib/{hosting-probe,build-environment,supply-chain,local-policy-evidence,runtime-config-switches,dependency-advisories}.ts`, `scripts/run-and-validate-provider.ts`(호스트 전제 부분), `scripts/contracts/{ci-gates,product-ci-overlay}.ts`(release·배포 job 부분), `scripts/generate-ci-workflow.ts`(release·제품 job 렌더링), `scripts/run-ci-gate.ts`(로그·콘솔), `vite.config.ts`, `vite.service-worker.config.ts`, `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `renovate.json`, `config/{hosting,security,runtime}/`, `config/ci/{gates,product-gates}.json`(release job), `.gitea/workflows/quality-gates.yml`(env, `release_gate`~`production_gate`), `src/contracts/{env,deployment-admission}.ts`
> 깊게 본 관점: 8, 16, 18, 19, 21
> 렌즈: 1105/13-01(`629c713`)·13-02(`92d5019`) 수정 결과와 검사 약화 여부 · 1103/13-03 결정 대기 상태 · FE-GATE-013의 test:system 뒤 명령 · 생성 workflow와 생성기 대조
> 영역 판정(35.8): **조건부 사용 가능.** "빌드 → 공개 대상 승인 → 손으로 배포"는 그대로 써도 된다. 지난 라운드 새 발견 둘은 코드로 들어왔다. 제품 merge 검사는 이제 같은 run의 release를 막는다(1105/13-02 고쳐짐). release job은 gate 로그와 advisory 기록을 따로 올린다. 다만 실제 runner에서 그 산출물을 본 적은 없다(1105/13-01 일부, 실행 환경 대기). 운영 의존성 high advisory 2건은 결정 대기 그대로다(1103/13-03). provider 없이 슬롯까지 가는 길은 아직 없다. provider job은 FE-GATE-013과 같은 user namespace를 요구하지만, workflow의 그 job에는 요구도 사전 점검도 없다(1101/13-03). 이 영역 수정이 검사를 약하게 한 곳은 찾지 못했다.
ID 표기: 이 문서의 `13-NN`은 2026-11-06 라운드 ID다(라운드 밖에서는 `1106/13-NN`). 지난 라운드는 `1105/13-NN`, 그 전은 `1103/…`, `1101/…`, `0929/…`다.
## 0. 결론
- **1105/13-02는 고쳐졌다(E2).** 제품 overlay에 gate가 있으면 `release_gate`가 `[merge_gate, product_merge_gate]`를 기다린다(`scripts/generate-ci-workflow.ts:68-78`, `:92`, `:130`, `:182-184`). 뒤의 release job은 모두 `release_gate`를 거쳐 기다린다(`scripts/contracts/ci-gates.ts:942-947`). `check:ci`는 그 연결이 없는 workflow를 거절한다(`generate-ci-workflow.ts:511-520`). overlay가 비면 workflow 바이트가 같다. 이 수정은 `.gitea/workflows/quality-gates.yml`을 바꾸지 않았고, bbde570의 FE-GATE-010이 `CI workflow bytes: PASS`다. 실제 Gitea의 `needs` 처리는 확인하지 못했다.
- **1105/13-01은 일부다. 실행 환경 대기다.** `immutable_build` 마지막 단계가 `if: always()`로 FE-GATE-015·027의 로그·evidence 6개와 advisory 기록을 올린다(`.gitea/workflows/quality-gates.yml:210-223`, `config/ci/gates.json:2512-2526`). 계약이 이 단계를 고정한다(`ci-gates.ts:961`, `:1159-1179`, `:1200-1219`). 단계를 빼거나, `always`를 빼거나, 경로를 빼거나, 순서를 바꾸면 계약이 거절한다. 이 5가지를 단위 테스트가 본다(`tests/unit/ci-workflow-generation.test.ts:1782-1865`). 그 테스트는 bbde570 CI env에서 통과했다. upload 대상 파일 쪽은 CI env에서 확인했다(13-R1, E3). FE-GATE-015가 실패하면 그 로그 하나가 새로 생기고 이유(`VITE_COMMIT_SHA does not identify the checked-out commit`)가 담긴다. FE-GATE-027이 거절되면 로그와 승인 기록이 새로 생기고 로그에 `release admission refused for production:`이 있다. 콘솔은 두 경우 모두 `FAIL` 한 줄이었다. 완료 기준의 나머지 절반은 "release 단계 run의 산출물"이다. runner가 없어 확인하지 못했다. 커밋 본문도 그렇게 적는다. README §16.4는 "고침"이라 했다. 이 문서는 일부로 본다.
- **1103/13-03은 일부다. 결정 대기다.** `8a44226..bbde570`에서 `package.json`의 의존성 칸과 `pnpm-lock.yaml`은 바뀌지 않았다. 운영 high 2건(`react-router-dom@7.18.1`, `zod@4.4.3`)이 그대로다(`package.json:160-161`). 새 사실이 하나 있다. 초기 JS 예산이 206,848 B로 올라 여유가 2,690 B다(D7, FE-GATE-012). 그래서 문서가 react-router 갱신 비용으로 적은 약 470 B는 이제 예산 안이다. zod의 약 7 KB는 여전히 넘는다(`docs/operations/ci-quality-gates.md:564-565`). 2026-11-06 04:24 결과는 `POLICY_VIOLATION`이다. 운영 high 2건(GHSA-qwww `react-router@7.18.1`, GHSA-mrhx `zod@4.4.3`)과 개발 moderate 2건이다. 지난 라운드와 같다(13-R1 B, E3).
- **새 발견은 1건이다. Low·P3다(13-01).** FE-GATE-027은 공개 대상 승인을 먼저 돌고 advisory 검사를 뒤에 돈다(`config/ci/gates.json:2212-2213`). `ci:gate`는 첫 실패에서 멈춘다(`scripts/run-ci-gate.ts:176-190`). 그래서 승인이 거절된 run에는 advisory 기록이 새로 생기지 않는다(13-R1 C, E3). 문서는 그 기록을 "성공·실패와 상관없이" 올린다고 적는다(`ci-quality-gates.md:169-173`, `:540-544`).
- **이 영역 수정은 검사를 약하게 하지 않았다.** 2.4절. 테스트 단언 두 곳이 바뀌었다. 하나는 `uses:` 개수를 33에서 34로 올렸다. 다른 하나는 한 줄만 바꿔 비교한다. 둘 다 새 단계·새 연결을 반영한 것이고, 새 단언이 그 줄을 직접 본다. 초기 JS 예산 상향(D7)은 영역 15 몫이다. 12-04가 빌드 단계에 넣은 `RUN_OUTPUT_ROOT`는 release job env에 넣을 수 없다.
- **FE-GATE-013의 test:system 뒤 명령 7개는 bbde570 CI env에서 모두 통과했다.** 후보 `c5760d69…`(105파일), `Supply chain: LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`, secret scan PASS(1,660파일), reproducible build PASS다. FE-GATE-013 자체는 이제 사전 점검에서 2초 만에 멈춘다. 원인과 고치는 법을 적는다(12-01 수정, 영역 12).
- **지난 이월 8건은 모두 남았다.** 0929/13-06만 일부다. 1101/13-03에는 새 사실이 있다. provider job도 bwrap namespace가 필요하다. 그런데 workflow의 provider job에는 요구 주석도 사전 점검도 없다. 이 desktop에서 provider를 돌리면 `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` 한 줄로 끝난다(`bbde570-013-parts/system-vitest.log`).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 |
| 커밋·작업 상태·확인 시점 | `bbde570`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 추적 파일 변경 없음)에서 읽기만 했다. 실행 증거는 desktop의 기존 로그다. merge 단계 CI env 실행(`/tmp/claude-gates/bbde570-ci/`, 2026-11-06 03:24~03:56), FE-GATE-013의 뒤 명령(`/tmp/claude-gates/bbde570-013-parts/`, 03:54~03:56), 그 실행이 남긴 산출물 사본(`/tmp/claude-gates/r5/snap/merge/`, `MTIMES.txt`로 03:24 이후 파일만 썼다)이다. `gate-artifacts/FE-GATE-015.txt`·`027.txt`와 사본의 `dependency-advisories.json`·`deployment-admission.json`은 2026-11-05 20:09 파일이라 쓰지 않았다. 추가 실험은 배치 13-R1(2026-11-06 04:24, `restore=clean`) |
| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker(기본 `null`). 사용자 목표: 짝 백엔드 템플릿과 빨리 출시하고 desktop 서버로 배포한다 |
| 필수 요구와 규모·운영 목표 | 초기 JS 206,848 gzip B와 파일 32개(`config/performance/budgets.json:4-5`, D7로 204,800에서 올림). 서빙 전제는 h2와 압축(`config/hosting/cache-policy.json:4`, `:29`) |
| 읽은 코드·구성 범위 | 머리의 경로 전체. `git diff 8a44226..bbde570`으로 이 영역 경로의 변경 30파일을 봤다. 수정 커밋 `629c713`, `92d5019`의 본문과 테스트. 주장 자료: `README.md`, `docs/operations/ci-quality-gates.md:163-205`, `:420-430`, `:531-565`, `CHANGELOG.md:32`, `:46`, `:48`, 지난 README §15·§16 |
| 수행한 테스트·실험 | 이 리뷰가 직접 돌린 것은 없다. 위 로그를 읽었다. 배치 13-R1 하나를 오케스트레이터가 desktop checkout(`bbde570`, CI env)에서 돌렸다. 2026-11-06 04:24, 끝난 뒤 `restore=clean`. 내용은 1105/13-01 완료 기준의 파일 쪽, 지금 advisory 수, 새 13-01이다. 결과 `desktop:/tmp/claude-gates/r5/batch/out/R5-13-R1.log`. 6절 |
| 확인하지 못한 범위·이유 | 실제 Gitea runner(upload 동작, `needs` 처리, 재실행), 채운 배포 슬롯, provider 실행, 실제 운영 호스트, advisory 도달 가능성. 5절 |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md`의 새 발견 2건, 그 문서 2.2절이 남음·일부로 둔 이월 8건, README §16.5의 1103/13-03. §16.6에는 영역 13 ID가 없다(이월 8건은 손대지 않았다는 뜻). `git log 8a44226..bbde570 -- <경로>`의 이 영역 수정 커밋은 `629c713`, `92d5019`다. 다른 영역 수정이 이 영역 파일을 건드린 커밋도 봤다(2.4절). 지난 실험 결과는 증거로 쓰지 않았다 |
### 1.1 게이트 결과 중 이 영역에 해당하는 것 (`bbde570`, CI env)
| 게이트 | 결과 | 이 영역에 주는 의미 |
|---|---|---|
| FE-GATE-005(`test:unit`) | rc=0, 208파일 3,056건 | 통과한 파일: `ci-workflow-generation` 435(지난 426), `hosting-probe` 39, `product-ci-overlay` 12(지난 11), `dependency-advisories` 5, `env-registry-coverage` 4, `build-environment` 4, `local-build-environment` 3, `build-environment-bundle` 2, `pnpm-install-policy` 2 |
| FE-GATE-010 | rc=0 | `CI contract: 27 gates, strict v2 graph and generated workflow model PASS`, `CI workflow bytes: PASS`. 커밋된 workflow가 생성기 출력과 같다 |
| FE-GATE-011 | rc=0 | 첫 줄 `derived SOURCE_DATE_EPOCH=1793901621 from HEAD`. 빌드와 Storybook 빌드 통과 |
| FE-GATE-012 | rc=0 | `initial JS 204158 / 206848 gzip bytes, 27 / 32 files`. 여유 2,690 B |
| FE-GATE-013 | rc=1, 2초 | 사전 점검이 멈췄다. `this host does not allow unprivileged user and network namespaces`, bwrap stderr, `kernel.apparmor_restrict_unprivileged_userns = 1`, 고치는 법 셋을 적는다. 12-01 수정(영역 12)이 동작한다 |
| FE-GATE-013의 뒤 명령(`bbde570-013-parts/`) | test:system rc=1(96/114). 나머지 7개 rc=0 | test:system 실패 18건은 모두 `tests/system/ci-runner/ci-artifact-contract.test.ts`다. 메시지는 `sandboxed external provider failed: exit=1, signal=none; sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`다. 나머지: `verify:reproducible-build` PASS(`6b69c08f…`), `build:release-candidate` 후보 `c5760d69…`(105파일)·공급망 `LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`·secret scan PASS(1,660파일)·release coherence PASS, `verify:local-evidence` PASS, `check:supply-chain:fixtures` 9 PASS, `check:supply-chain:provider-fixtures` PASS, `check:security:fixtures`·`check:browser-security`는 거절 fixture를 잡았다 |
| FE-GATE-008·020 | rc=0(196초·1,237초) | 테스트가 띄우는 로컬 빌드가 CI=true에서 통과한다(1103/11-08 수정 유지) |
## 2. 지난 발견 재확인
### 2.1 2026-11-05 라운드(이 영역) 새 발견
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/13-01 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다 | **일부(실행 환경 대기)** · §16.4는 "고침" | **들어온 것.** `immutable_build`의 마지막 단계 "Upload immutable gate evidence"가 `if: always()`로 7개 경로를 올린다(`.gitea/workflows/quality-gates.yml:210-223`). 경로는 FE-GATE-015의 로그와 evidence 3개, FE-GATE-027의 로그와 evidence 1개, advisory 기록이다(`config/ci/gates.json:2516-2523`). 계약은 단계 종류에 upload 하나를 더했다(`scripts/contracts/ci-gates.ts:961`). 경로는 gate 등록에서 계산해 대조한다(`:1167-1179`). 이 upload가 `always`이고 마지막 단계여야 한다(`:1206-1219`). advisory 경로는 상수 하나로 모았고 scan 스크립트도 그 상수를 쓴다(`scripts/lib/dependency-advisories.ts:7`, `scripts/scan-dependency-advisories.ts:23`). 후보 archive 멤버(`:151-203`)와 후보 upload(`:204-209`, `always` 없음)는 그대로다. **검증.** 정상 단언 1건(`tests/unit/ci-workflow-generation.test.ts:1782-1823`)과 거절 5건(`:1825-1865`: 단계 없음, `always` 없음, advisory 기록 빠짐, FE-GATE-027 로그 빠짐, 후보 upload 앞)이 bbde570 CI env의 FE-GATE-005에서 통과했다. 거절 5건은 계약을 바꿔 이 규칙의 메시지로 실패하는지 본다. 그래서 규칙 자체의 변이 시험 역할을 한다(E2). 생성 workflow는 생성기와 같다(FE-GATE-010). **남은 것.** 완료 기준은 "release 단계 run의 산출물에 FE-GATE-015·027 로그와 advisory 기록이 있다"이다. 실제 runner에서 `stage=release`를 돌린 적이 없다(커밋 본문 "위험·한계"). 업로드 action(`ChristopherHX/gitea-upload-artifact@81f940d…`)이 여러 줄 `path`에서 없는 파일을 건너뛰는지도 확인하지 못했다. **파일 쪽 확인(13-R1, CI env, E3).** 각 단계 앞에 표시 파일을 두고 7개 경로 중 더 새로 생긴 것을 봤다. A(FE-GATE-015를 HEAD가 아닌 커밋 ID로): rc=1. 새 파일은 `FE-GATE-015.txt` 하나다. 그 내용은 `VITE_COMMIT_SHA does not identify the checked-out commit`이다. B(빌드 뒤 FE-GATE-027, local 대상): rc=0. `FE-GATE-027.txt`, `deployment-admission.json`, `dependency-advisories.json`이 새로 생겼다. C(FE-GATE-027, production 대상): rc=1. `FE-GATE-027.txt`, `deployment-admission.json`이 새로 생겼고 로그에 `release admission refused for production:`이 있다. 세 경우 모두 콘솔은 PASS·FAIL 한 줄이었다. 그래서 실패한 run에도 올릴 파일이 최소 하나 있고, 거기에 이유가 있다. 콘솔은 여전히 gate마다 한 줄이다(`scripts/run-ci-gate.ts:243-249`). 문서가 산출물에서 읽으라고 적어 받아들인다(`docs/operations/ci-quality-gates.md:169-173`). 같은 원리로 1103/11-02를 지난 라운드에 "일부"로 정정했다 |
| 1105/13-02 | 제품 merge 검사가 실패해도 같은 run의 release·배포가 진행된다 | **고쳐짐** | **코드.** overlay에 gate가 있을 때만 `release_gate`의 `needs`에 `product_merge_gate`를 더한다(`scripts/generate-ci-workflow.ts:68-78`, `:92`, `:130`, `:182-184`). 뒤 job은 `release_gate`를 거쳐 기다린다. `immutable_build`는 `release_gate`를, provider는 `immutable_build`를, promotion·deployment는 그 둘을 기다린다(`scripts/contracts/ci-gates.ts:942-947`). `check:ci`가 부르는 `workflowGateExecutionFailures`는 제품 gate가 있는데 연결이 없으면 거절한다(`generate-ci-workflow.ts:511-520`). **조건 대조.** `product_merge_gate`의 `if:`는 merge 조건이다(`:148`). 그 조건은 release 조건이 참인 모든 경우에 참이다(tag push, dispatch `release`·`production`·`field`). 그래서 release가 도는 run에서는 제품 job도 돈다. 제품 job이 건너뛰어져 release가 같이 멈추는 경우는 없다. **완료 기준 확인.** "overlay에 gate 하나를 넣고 생성하면 release 쪽 job이 `product_merge_gate`를 기다린다"는 `tests/unit/product-ci-overlay.test.ts:163-189`가 본다. 연결이 없는 workflow를 `check:ci` 함수가 거절하는 것도 본다. bbde570 FE-GATE-005에서 통과했다(E2). "overlay를 비우면 workflow 바이트가 같다"는 둘로 확인했다. `92d5019`는 `.gitea/workflows/quality-gates.yml`을 바꾸지 않았다. `config/ci/product-gates.json:4`가 `"mergeGates": []`이고 FE-GATE-010이 `CI workflow bytes: PASS`다. 문서(`ci-quality-gates.md:424-430`)와 CHANGELOG "먼저 할 일" 9단계(`CHANGELOG.md:32`)가 바뀐 동작과 재생성 필요를 적는다. **남은 것.** Gitea가 `needs`와 암묵적 `success()`를 GitHub Actions처럼 처리하는지는 미확인이다(5절). 완료 기준에 들지 않는다 |
### 2.2 1103 이월(README §16.5)
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1103/13-03 | 취약점 판정이 운영 승격 provider에만 있고, lockfile이 자체 정책을 어기는데 merge·release에서 모른다 | **일부(결정 대기)** · §16.5 "결정 대기"와 같다 | **지난 라운드에 고쳐진 것은 그대로다.** FE-GATE-027이 `scan:dependency-advisories`를 돈다(`config/ci/gates.json:2212-2213`). 판정은 승격과 같은 정책을 쓴다(`scripts/scan-dependency-advisories.ts:25-44`). 항상 exit 0이다. **남은 것.** (1) 운영 high 2건. `8a44226..bbde570`에서 `pnpm-lock.yaml`은 바뀌지 않았다. `package.json`의 의존성 칸도 그대로다(바뀐 곳은 `test:all` script 한 줄). 그래서 `react-router-dom@7.18.1`·`zod@4.4.3`(`package.json:160-161`, `pnpm-lock.yaml:2376`, `:2816`)이 그대로다. 결정 조건과 재확인 날짜(2026-12-04)가 문서에 있다(`docs/operations/ci-quality-gates.md:556-565`). 2026-11-06 04:24 FE-GATE-027 로그는 `POLICY_VIOLATION (production: critical 0, high 2, moderate 0, low 0; development: critical 0, high 0, moderate 2, low 0)`다. 경고 대상은 `GHSA-qwww-vcr4-c8h2:react-router@7.18.1:high`와 `GHSA-mrhx-c7xc-m3w5:zod@4.4.3:high`다(13-R1 B, E3). (2) 신호 가시성. 지난 라운드의 원인(1105/13-01)은 계약 수준에서 고쳐졌다. 실제 run 확인은 남았다(2.1절). 승인이 거절된 run에는 기록이 없다(새 13-01). (3) renovate는 runner가 없어 동작하지 않는다(`renovate.json:4`). **새 사실.** D7로 초기 JS 예산이 206,848 B가 됐다. bbde570의 여유는 2,690 B다(FE-GATE-012). 문서가 react-router 7.18.5의 비용으로 적은 약 470 B는 이 여유 안이다. 그러면 react-router를 막는 것은 "owner와 다른 reviewer" 규칙 하나다. zod 4.6.7의 약 7 KB는 여전히 예산을 넘는다(`ci-quality-gates.md:564-565`). D7 근거도 "이 상향은 13-03을 정하지 않는다"고 적는다(지난 README §16.2) |
### 2.3 그 밖의 이월(지난 영역 문서 2.2절의 남음·일부)
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1101/13-03 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고 provider 없는 배포 경로가 없다 | **남음** | provider job은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:228`, `:274`). 배포 슬롯은 promotion 뒤에만 돈다(`:391`, `scripts/contracts/ci-gates.ts:946-947`). provider 없이 배포하는 절은 문서에 없다. **새 사실.** provider는 bwrap namespace 옵션으로 뜬다(`scripts/run-and-validate-provider.ts:255-257`). 문서는 이 조건이 "provider job과 merge 게이트 FE-GATE-013 둘 다에 걸린다"고 적는다(`docs/operations/ci-quality-gates.md:198-205`). 그러나 workflow에서 요구 주석은 merge job에만 있다(`.gitea/workflows/quality-gates.yml:37-38`). 주석은 job이 도는 gate의 `hostRequirements`에서 나온다(`scripts/generate-ci-workflow.ts:245-253`). provider job에는 gate가 없어 주석이 없다. provider job 시작 점검은 `/usr/bin/bwrap`이 있는지만 본다(`run-and-validate-provider.ts:116-117`). bbde570 test:system에서 provider supervisor는 18건 모두 `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝났다(E3, `bbde570-013-parts/system-vitest.log`). 이 desktop에 runner를 붙이면 provider job이 같은 한 줄로 끝날 것으로 본다(추정, runner 미실행). 1105/12-01(영역 12)과 원인이 같다. 12-01은 FE-GATE-013 쪽을 고쳤고 provider job 쪽은 이 항목에 남는다 |
| 0929/13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:19`의 `loadEnv`는 미선언 변수를 거절할 때만 쓴다. base와 설정 URL 검사는 `process.env`를 읽는다(`:193-194`). `scripts/generate-runtime-config.ts:77-78`, `scripts/generate-build-manifest.ts:42-46`, `vite.service-worker.config.ts:61-62`, `:68`도 `process.env`다. `.env.example:14`는 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다. 이번에 다시 재현하지는 않았다(E1) |
| 0929/13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **남음**(Medium·P2로 보고됨, fail-closed) | route chunk를 `entry.name === runtime?.moduleId && entry.isDynamicEntry`로 찾고 없으면 빌드가 멈춘다(`scripts/generate-build-manifest.ts:70-78`) |
| 0929/13-04(= R-3) | CSP가 여러 벌이고 내용 검사가 없다 | **남음** | 같은 CSP 문자열이 6곳에 있다: `config/hosting/security-headers.json:4`, `config/hosting/response-headers.fixture.json:7`, `:17`, `:27`, `:42`, `docs/operations/release-cache-rollback.md:121`. `scripts/check-browser-security.ts`에는 CSP 검사가 없다(grep 0건). live probe만 받은 헤더를 `security-headers.json`과 비교한다(`scripts/verify-hosting-headers.ts:174-186`). FE-GATE-019를 돌릴 때만 일어난다 |
| 0929/13-05 | SBOM이 `deduped` 노드를 따라가지 않는다 | **남음** | `scripts/lib/supply-chain.ts`에 `deduped`가 0건이다. 기준선의 `scheduler`가 `scope: development`다(`config/security/dependency-baseline.json:5778-5781`). bbde570에서 새로 만든 inventory도 같다(사본 `artifacts/release/dependency-inventory.json:5778-5781`, 03:56). 실제로는 react-dom 청크에 묶여 실린다(`vite.config.ts:259`) |
| 0929/13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자가 있다 | **일부(남음)** | live probe가 루트가 아닌 URL을 거절한다(`scripts/lib/hosting-probe.ts:453-456`) |
| 0929/13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | "unmodified checkout" 문구가 그대로다(`README.md:421-426`) |
| R-2 | 빌드 입력 기본값을 한 곳에서 정한다 | **남음** | 기본값이 다섯 곳에 흩어져 있다: `src/contracts/env.ts:54-55`(레지스트리), `:204-205`(`\|\|`), `scripts/generate-runtime-config.ts:77`(`\|\|`)·`:78`(`??`), `scripts/generate-build-manifest.ts:42-44`(`??`), `vite.service-worker.config.ts:61-62`(`??`) |
지난 라운드에 고쳐진 이 영역 발견의 재발도 봤다. 셈에 넣지 않는다.
| 지난 ID | 재발 | 근거 |
|---|---|---|
| 1103/13-01 | 없음 | `config.json` 비교(`scripts/lib/hosting-probe.ts:222-225`)와 슬롯 입력 규칙(`scripts/contracts/ci-gates.ts:1292`, `:1335`)이 그대로다. `hosting-probe` 39건 통과(FE-GATE-005) |
| 1103/13-02 | 없음 | ALPN 판정(`hosting-probe.ts:236-252`), entry `Content-Encoding` 판정(`scripts/verify-hosting-headers.ts:165-168`), 선언(`config/hosting/cache-policy.json:4`, `:29`)이 그대로다. live 분기는 이제 `probeLiveHosting` 하나로 묶였다(`verify-hosting-headers.ts:113-118`, 1105/06-02 수정) |
| 1103/13-04 | 없음 | `env-registry-coverage` 4건 통과(FE-GATE-005) |
| 1103/13-05 | 없음 | 배포 단계 `secrets.*`는 deploy 단계 `env:`에만 렌더링된다(`scripts/generate-ci-workflow.ts:376-377`) |
| 1103/11-08 | 없음 | `scripts/lib/build-environment.ts`는 이 범위에서 바뀌지 않았다. FE-GATE-008·020 CI env 통과 |
### 2.4 이 영역 파일을 바꾼 수정의 검사 약화 확인 (`git diff 8a44226..bbde570`)
| 커밋 | 바뀐 검사 | 판정 | 근거 |
|---|---|---|---|
| `629c713`(1105/13-01) | `ci-workflow-generation.test.ts`의 `actionUses` 개수 33 → 34 | 약화 아님 | upload 단계 하나가 늘었다. 개수는 여전히 정확히 비교한다. 계약 단계 목록도 upload 하나를 더 요구한다(`ci-gates.ts:961`). 새 규칙과 정상·거절 테스트 6건이 더해졌다 |
| `92d5019`(1105/13-02) | `product-ci-overlay.test.ts`의 "템플릿 부분 바이트가 같다" 단언 | 약화 아님 | 비교 전에 정확히 한 줄(`needs: [merge_gate, product_merge_gate]` → `needs: merge_gate`)만 바꾼다(`:151`). 그 줄은 새 테스트가 직접 단언한다(`:163-189`). 실패 목록 단언에 새 메시지가 더해졌다 |
| `9655958`·`67082cc`(1105/12-01) | gate 모양 digest가 `hostRequirements`를 본다. 기준선 재기록(`config/ci/contract-baseline.json`) | 약화 아님(영역 12) | gate·명령·artifact 수는 그대로다(27·100·104·110). digest만 바뀌었고 이유가 적혀 있다 |
| `4d6f254`(1105/06-02) | 자산 MIME probe의 fetch가 `redirect: "follow"` → `"manual"`, redirect면 FAIL | 강화(영역 06) | `hosting-probe.ts:291`, `:308-330`. Node의 `manual`은 3xx를 그대로 돌려준다. 그때 관측값은 `redirected`가 아니라 `HTTP 30x`로 남지만 FAIL은 같다 |
| `f4d5761`(1105/12-04) | 빌드 단계 경로가 `RUN_OUTPUT_ROOT` 아래로 갈 수 있다 | 약화 아님 | 값이 없으면 경로가 전과 같다(`scripts/lib/run-isolation.ts:63-83`). release job env와 workflow env는 계약과 바이트 비교가 고정한다. 지난 라운드에 job env 바인딩을 더하면 `check:ci`가 거절했다(1105 13-R03). 그래서 release 빌드에 이 값이 들어갈 길은 없다. 로컬에서 값을 export하고 `ci:gate FE-GATE-011`을 돌리면 evidence 신선도 검사가 실패한다(`scripts/run-ci-gate.ts:203` "command-generated evidence was not freshly produced", 정적 추론) |
| `287dc6f`(D7) | 초기 JS 예산 204,800 → 206,848 B | 기록된 상향(영역 15) | 메인 세션 결정. 근거와 재검토 조건이 지난 README §16.2에 있다. 이 문서는 1103/13-03과의 관계만 적는다(2.2절) |
| `81701ad`(1105/15-04), `7ead8d3`(0929/10-05) | lab 예산 칸 추가, `test:all` 경로 | 영역 15·10 | 이 영역 검사와 무관하다 |
## 3. 이번 발견 (36.3)
새 발견은 1건이다. Low 1. P3 1. 확인된 결함 1. High 이상과 P1은 없다.
### 13-01 FE-GATE-027의 공개 대상 승인이 거절되면 advisory 검사가 돌지 않아, 그 run의 증거에는 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다
| 필드 | 내용 |
|---|---|
| ID·제목 | 13-01(라운드 밖: `1106/13-01`) — 위 제목 |
| 성격 | 확인된 결함(문서와 동작의 차이). 1105/13-01 수정이 새로 쓴 문장이다 |
| 관련 관점 | 5, 8, 23, 16 |
| 근거 | **명령 순서.** FE-GATE-027은 `check-release-admission`을 먼저, `scan-dependency-advisories`를 뒤에 돈다(`config/ci/gates.json:2212-2213`). 1103/13-03 수정(`26ca2fd`)이 이 순서로 넣었다. **멈춤.** `ci:gate`는 기대와 다른 결과가 나온 첫 명령에서 `break`한다(`scripts/run-ci-gate.ts:176-190`). 승인 거절은 exit 1이다(`scripts/check-release-admission.ts:183-190`). FE-GATE-015가 실패하면 FE-GATE-027 단계 자체가 돌지 않는다(`.gitea/workflows/quality-gates.yml:147-150`, `always` 없음). **주장.** 문서는 같은 job이 "`scan:dependency-advisories` 기록을 … 성공·실패와 상관없이 올린다"고 적는다(`docs/operations/ci-quality-gates.md:169-173`). 영어 절도 "uploads … this record … whether the job passed or failed. Read why FE-GATE-015 or FE-GATE-027 failed, and the advisory status, there"라고 적는다(`:540-544`). 실제로 올라가는 것은 그 run에 생긴 파일뿐이다. **실행 확인(13-R1, CI env).** 같은 checkout에서 B(승인 통과)는 `dependency-advisories.json`을 새로 만들었다. C(production 대상 거절, rc=1)는 `FE-GATE-027.txt`와 `deployment-admission.json`만 새로 만들고 `dependency-advisories.json`은 만들지 않았다. C의 로그에는 `release admission refused for production:`만 있고 `Dependency advisories` 줄이 없다. 깨끗한 runner라면 이 파일은 아예 없다 |
| 발생 조건 | release 단계 run에서 FE-GATE-015가 실패하거나 FE-GATE-027의 승인이 거절될 때. 예: `RELEASE_TARGET`이 비었거나 `APP_PROFILE`과 다를 때, production 대상에 예시 endpoint가 남았을 때 |
| 영향 | 그 run의 산출물로는 advisory 상태를 알 수 없다. 거절 이유는 로그에 남는다. 승인을 고쳐 다시 돌리면 다음 run에 기록이 생긴다. 막지 않는 신호라 사용자 피해는 없다 |
| 심각도·우선순위 | Low · P3. 제한된 문서 불일치이고 진단 정보 하나가 한 번 늦게 보인다(35.2 Low) |
| 통제·증거 | 기록 생성 M2(승인 통과 때만) · E1(명령 순서와 `break`) + E3(13-R1 B·C, CI env) |
| 확실성과 남은 가정 | 순서와 멈춤은 코드와 실행으로 확인했다. 실제 runner의 upload가 없는 파일을 건너뛰는지는 미확인이다(5절) |
| 결정의 근거 | 확인한 사실: 승인은 막는 검사이고 advisory는 막지 않는 신호다(`scripts/scan-dependency-advisories.ts:18-21`). 기록된 의도: advisory 상태를 release 산출물에서 읽게 한다(`ci-quality-gates.md:540-544`). 리뷰어 추론: 막지 않는 신호를 막는 검사 뒤에 두면 막힌 run에서 신호가 사라진다. 앞에 두면 둘 다 남는다 |
| 이해 비용 | 거절된 run의 산출물을 연 운영자는 advisory 기록이 왜 없는지 문서로 알 수 없다 |
| 최소 개선 방향 | 둘 중 하나다. (a) 문서 두 곳을 "FE-GATE-027이 승인을 통과한 run에만 advisory 기록이 있다"로 고친다. (b) FE-GATE-027의 명령 순서를 scan → 승인으로 바꾼다. scan은 항상 exit 0이라 승인 판정은 그대로다 |
| 대안 비교 | (a) 문서만 — 가장 싸다. 신호는 계속 한 run 늦는다. (b) 순서 바꿈 — 승인이 거절된 run에도 기록이 남는다. gate 모양 digest가 바뀌어 계약 기준선을 다시 적어야 한다(`config/ci/contract-baseline.json`). 승인 전에 `pnpm audit`이 돌아 실패 run이 최대 120초 늦어질 수 있다(`scan-dependency-advisories.ts:36`). (c) scan을 별도 always 단계로 뺀다 — 계약 단계 목록이 바뀐다. 리뷰어 추천은 (a)다. 신호의 가치가 작다 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 승인 판정과 후보 archive 멤버는 그대로 둔다 |
| 비용·부작용 | (a) 문서 두 줄. (b) gates.json 두 줄, 기준선 재기록, 문서 |
| 재검토 조건 | advisory를 막는 검사로 바꾸거나, `ci:gate`가 실패 뒤에도 막지 않는 명령을 돌게 바뀌면 다시 본다 |
| 완료 기준 | 문서가 실제 동작과 같다. (b)를 고르면 승인이 거절된 run에서도 `artifacts/security/dependency-advisories.json`이 새로 생긴다 |
| 검증 방법 | 13-R1 C와 같은 실행. (b)면 `ci:gate FE-GATE-027`을 `RELEASE_TARGET=production`과 로컬 빌드로 돌려 기록이 생기는지 본다 |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음(신규) |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이 영역이 깊게 본 관점이다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 영역 09·12 | — | — | > — 두 수정 모두 주석이 문제·선택·남은 한계를 적는다(`generate-ci-workflow.ts:68-78`, `ci-gates.ts:1200-1205`) |
| 2 | 구조적 성숙도 | > 영역 12 | — | — | > |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1·E2 | P — 제품이 템플릿 파일을 고치지 않고 배포 job과 release를 막는 검사를 넣는다(1105/13-02 고쳐짐). 빌드 입력 기본값은 다섯 곳이다(R-2) |
| 4 | 인지 부하 | 적용 | M1 | E1 | P — release 실패 이유는 이름 있는 산출물 하나에서 읽는다고 문서가 적는다(`ci-quality-gates.md:540-544`). 콘솔은 한 줄이다 |
| 5 | 위험 가시성 | 적용 | M3 / 일부 M2 | E2·E3 | P — advisory 기록이 release 산출물에 올라간다(계약 M3). 파일은 CI env에서 생긴다(13-R1 B). 실제 runner run은 미확인. 승인이 거절된 run에는 기록이 없다(13-01, 13-R1 C) |
| 6 | 실패 성숙도 | 적용 | M3 | E2·E3 | O — 승인은 선언되지 않은 대상을 거절하고(`check-release-admission.ts:72-82`) 빌드 단계는 즉시 멈춘다. FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(영역 12) |
| 7 | 운영 성숙도 | 적용(일부) | M1 | E1·E3 | P — provider 없는 배포 경로가 없다. provider job의 namespace 요구가 그 job에 적혀 있지 않고 점검도 없다(1101/13-03, system-vitest 18건) |
| **8** | 디버깅 가능성 | 적용 | M3 / runner 미확인 | E2·E3 | P — release job이 gate 로그를 always로 올린다(1105/13-01, 계약이 고정). 실패한 FE-GATE-015·027의 로그에 이유가 남는다(13-R1 A·C). 실제 runner 산출물은 미확인이다. provider job 실패는 bwrap 원문 한 줄이다(1101/13-03). TLS·전송 실패는 `error.name`만 남는다(`hosting-probe.ts:168`, `:242`, `:319`) |
| 9 | 유지보수 성숙도 | 적용 | M2 | E1 | P — CSP 6벌(0929/13-04), 기본값 다섯 곳(R-2) |
| 10 | 테스트 성숙도 | 적용 | M3 | E2 | P — 두 수정 모두 정상·거절 단언이 있고 bbde570에서 통과했다. 거절 단언이 규칙 메시지를 확인해 변이 시험 역할을 한다. 실제 runner·TLS·nginx를 쓰는 자동 시험은 없다 |
| 11 | 데이터 성숙도 | > 저장소 영역 | — | — | > |
| 12 | 동시성 성숙도 | > 탭·저장소 영역 | — | — | > |
| 13 | 확장성 | > 영역 11·15 | — | — | > |
| 14 | 성능 성숙도 | 적용(서빙 전제) | M3 | E2 | P — h2·압축 판정은 그대로다(재발 없음). 초기 JS 204,158 / 206,848 B, 27 / 32파일(FE-GATE-012). 예산 상향은 영역 15 |
| 15 | 보안 성숙도 | 적용 | M3 / 일부 M0 | E1·E2 | P — 운영 high advisory 2건이 결정 대기다(1103/13-03). 슬롯 secret 위치·`config.json` 비교는 재발 없다 |
| **16** | 의존성 성숙도 | 적용 | 판정 M3(승격) / 신호 M3(계약) / 갱신 M1 | E1·E3 | P — lockfile이 이 범위에서 그대로다. 2026-11-06 advisory는 운영 high 2·개발 moderate 2다(13-R1 B). 운영 2건, 동작하지 않는 renovate, SBOM `scheduler` 분류(0929/13-05), 승인 거절 run의 기록 누락(13-01)이 남았다. react-router 갱신은 이제 예산 안이다 |
| 17 | API / Contract 성숙도 | 적용(설정 계약) | M3 | E2 | O — FE-REG-ENV 행과 스키마 대조가 유지된다(`env-registry-coverage` 4건) |
| **18** | 배포 성숙도 | 적용 | M3 / 일부 M0 | E1·E2 | P — 제품 검사가 release·배포를 막는다(1105/13-02). provider 없이 슬롯에 갈 수 없다(1101/13-03). 하위 경로 배포는 PASS할 수 없다(0929/13-06). 실제 runner에서 job 그래프를 돌린 적이 없다 |
| **19** | 설정 성숙도 | 적용 | M3 | E1 | P — `.env*` 입력 갈림(0929/13-02)과 기본값 갈림(R-2)이 남았다 |
| 20 | 개발자 경험 | 적용 | M1 | E1 | P — CHANGELOG가 제품 gate가 있는 다운스트림의 재생성 단계를 적는다(`CHANGELOG.md:32`). runner 요구 고치는 법이 문서에 있다(`ci-quality-gates.md:198-235`) |
| **21** | Guardrail 성숙도 | 적용 | M3·M4 | E2 | P — release job 증거 upload와 제품 gate → release 연결을 `check:ci`가 지킨다. 생성 workflow 바이트가 생성기와 같다(FE-GATE-010). 실제 runner 의미는 미확인이다 |
| 22 | 추상화 성숙도 | > 영역 09·12 | — | — | > |
| 23 | 일관성 | 적용 | M1 | E1 | P — 빌드 변수 출처(0929/13-02)와 기본값(R-2) 갈림, 문서와 동작 차이 하나(13-01) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 | E1 | O — `product_merge_gate`가 이제 release도 막아 이름과 동작이 맞는다(지난 P의 원인 해소) |
| 25 | 조직 확장성 | - 1인 관리 전제 | — | — | - |
| 26 | Ownership 성숙도 | 적용 | M1 | E1 | P — advisory 결정에 owner와 다른 reviewer가 필요한데 1인 운영에는 없다(`ci-quality-gates.md:564-565`). 선택 기능 결함 분류(0929/13-10)가 남았다 |
| 27 | 삭제 가능성 | > 영역 14 | — | — | > |
| 28 | 회복 가능성 | 적용 | M2 | E1 | P — 비상 스위치만 바꾼 호스트는 probe를 통과하는 규칙이 그대로다(`runtime-config-switches.ts`). 슬롯 배포 뒤 FE-GATE-019가 실패해도 자동으로 되돌리지 않는다(프로젝트 몫) |
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 실제 Gitea runner의 `immutable-gate-evidence` 산출물. 업로드 action이 여러 줄 `path`에서 없는 파일을 건너뛰고 `if-no-files-found: error`를 전체 0개일 때만 쓰는지 | runner 없음(Actions 꺼짐) | `stage=release` dispatch 1회, FE-GATE-027을 일부러 거절시킨 run 1회 |
| Gitea가 `needs`와 암묵적 `success()`를 GitHub Actions처럼 처리하는지(1105/13-02) | runner 없음 | 제품 gate 하나를 실패시키고 `stage=release` 1회 |
| 재실행 때 artifact 이름 충돌. merge·release·production gate의 upload 이름에는 `run_attempt`가 없다(`.gitea/workflows/quality-gates.yml:81`, `:120`, `:446`). immutable·provider·promotion 쪽은 있다 | runner 없음. action 버전의 동작을 모른다. 영역 12와 겹친다 | 실패한 run을 "다시 실행" 1회 |
| desktop에 runner를 붙였을 때 provider job이 같은 bwrap 한 줄로 끝나는가(1101/13-03) | runner 미실행. 같은 오류는 test:system에서만 봤다 | host-mode runner에서 provider job 1회 |
| `zod`·`react-router` advisory가 이 앱에서 실제로 닿는가 | 코드 경로를 끝까지 따라가지 않았다 | advisory 조건과 사용 지점 대조 |
| `.env*` 입력 갈림(0929/13-02) 재현 | 코드가 그대로라 정적 확인만 했다. 실험은 desktop checkout에 무시되는 `.env.local`을 남길 위험이 있어 요청하지 않았다 | 별도 사본에서 `.env.production.local`에 `VITE_ROUTER_BASE_PATH=/app/`를 두고 빌드 |
| `RUN_OUTPUT_ROOT`를 export한 채 `build:release-candidate`를 돌릴 때. 빌드는 `.tmp/…`에 쓰고 뒤 단계는 checkout의 `dist`를 읽는다 | CI에는 들어갈 수 없어 요청하지 않았다(2.4절). 로컬 오용만 해당한다 | 오래된 `dist`가 있는 checkout에서 한 번 돌려 fail-closed인지 본다 |
## 6. 실행 기록
이 리뷰는 desktop에서 직접 아무것도 돌리지 않았다. 1절의 기존 로그와 사본, 배치 결과를 `ssh desktop cat/grep/ls/sed`로 읽었다. 배치는 오케스트레이터가 desktop checkout에서 돌렸다(`ref=bbde5707`, `mode=plain`, `env=CIENV`, 부하 4.50). 끝난 뒤 `restore=clean`이다. 노트북에서는 git 읽기 명령과 파일 읽기만 썼다. 예외가 하나 있다. `config/ci/gates.json`의 gate별 명령 목록을 보려고 `python3 -I`로 JSON을 한 번 읽었다. 쓰기는 없었다. 브리프의 노트북 허용 목록 밖이라 적어 둔다.
| 이름 | 명령 · env | 변이 | rc | 결과 |
|---|---|---|---|---|
| 13-R1 | `bash 13-R1.sh`(스크립트 `scratchpad/r5/13/13-R1.sh`) · CIENV, 2026-11-06 04:24 | - | 0(스크립트). A rc=1, B build rc=0·gate rc=0, C rc=1 | 세 부분 모두 기대와 같다. **A** FE-GATE-015(`VITE_COMMIT_SHA`=0×40): 콘솔 `FE-GATE-015 release-coherence: FAIL`. 7개 경로 중 새 파일은 `FE-GATE-015.txt` 하나. 로그 `VITE_COMMIT_SHA does not identify the checked-out commit`. **B** FE-GATE-027(local): 콘솔 `PASS (release-coherence)`. 새 파일 `FE-GATE-027.txt`, `deployment-admission.json`, `dependency-advisories.json`. 로그 `local ADMITTED`, `POLICY_VIOLATION (production: … high 2 …; development: … moderate 2 …)`, `GHSA-qwww-vcr4-c8h2:react-router@7.18.1:high`, `GHSA-mrhx-c7xc-m3w5:zod@4.4.3:high`. **C** FE-GATE-027(production): 콘솔 FAIL 한 줄. 새 파일 `FE-GATE-027.txt`, `deployment-admission.json`. `dependency-advisories.json`은 새로 생기지 않았다. 로그 `release admission refused for production:`, `Dependency advisories` 줄 없음 |
요청 파일은 `scratchpad/r5/requests/13.md`, 결과는 `desktop:/tmp/claude-gates/r5/batch/out/R5-13-R1.log`다. 변이는 없다. 대조군이 필요한 판정은 없었다(세 부분 모두 같은 실행 안에서 비교했다).
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 13-01 | Low·P3 | 확인된 결함 | FE-GATE-027의 승인이 거절되면 advisory 검사가 돌지 않아 그 run의 증거에 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다 | `config/ci/gates.json:2212-2213`, `scripts/run-ci-gate.ts:176-190`, `docs/operations/ci-quality-gates.md:169-173`, `:540-544` |
@@ -0,0 +1,279 @@
# 영역 14 — 템플릿 제품성·문서·DX·업데이트 전파
> 검토일 2026-11-06 · 기준 `bbde570` (PR B 끝, 노트북 worktree 브랜치 `docs/maturity-review-2026-11-06`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
>
> 경로: `CHANGELOG.md`(특히 새 미출시 절 `:14-108`), `README.md`, `PRODUCT.md`, `docs/`(특히 `docs/manual/`, `docs/operations/performance-evidence.md`, `docs/architecture/starter-experience.md`), `recipes/`의 문서 주장, `scripts/verify-documentation-readiness.ts`, `scripts/lib/removable-template-features.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`, 문서 테스트(`tests/unit/documentation-readiness.test.ts`, `template-feature-removal-documents.test.ts`, `manual-paired-backend-settings.test.ts`, `changelog-review-ids.test.ts`). `docs/reviews/`는 이력이라 판정하지 않았다. 2026-11-05 README §16은 코드와 대조할 주장으로만 읽었다.
>
> 깊게 본 관점: 9 유지보수, 17 API/Contract, 20 개발자 경험, 23 일관성, 26 Ownership, 27 삭제 가능성, 30절 전체
>
> 렌즈: ① 새 미출시 절(`409d72e` → PR B)의 해시가 `bbde570` 이력에 있고 이름 댄 변경을 가리키는가. ② BREAKING 다섯의 "먼저 할 일"·[계약] 행이 코드와 커밋 꼬리말과 같고, 두 다운스트림(memento `d3810a0`, tech-log `7a4e201a`)이 따라 하면 맞는 변경이 되는가. ③ 1105 영역 14 발견 셋과 이월 열 건이 완료 기준을 채웠는가. ④ 이 영역 수정이 검사를 약하게 했는가. ⑤ D7(초기 JS 예산 상향) 문서가 이유와 재검토 조건을 §16.2와 같게 적는가.
>
> 영역 판정(35.8): **새 프로젝트를 복사해 시작하는 용도는 지정 범위에서 사용 가능**으로 올렸다(지난 조건 1105/14-02가 고쳐졌다). **이 미출시 묶음을 다운스트림에 전파하는 용도는 조건부 사용 가능**이다. 해시 75개와 BREAKING 행 다섯은 모두 맞고, 다섯 단계를 따라 하면 두 제품 모두 맞는 변경이 된다. 조건은 셋이다. BREAKING 1~3단계 설명 셋이 코드·다운스트림 모양과 다르다(14-01). 안내를 다운스트림에 적용해 본 사람이 없다(1103/14-02 잔여). 예제 기능 제거 드릴은 이번 배치에서 통과했지만(14-R1) 게이트 밖이라, 다시 깨져도 아무도 모른다.
>
> ID 표기: 이 문서의 새 발견은 `14-01`부터다. 라운드 밖에서는 `1106/14-NN`이다. 지난 라운드는 `1105/14-NN`, 그 전은 `1103/`, `1101/`, `0929/`다.
## 0. 결론
핵심은 둘이다. CHANGELOG 새 절의 해시와 BREAKING 행은 이번에 처음부터 맞다. 남은 결함은 안내 문장 몇 개와 커밋 본문 해시 둘이고, 둘 다 동작을 바꾸지 않는다.
```text
CHANGELOG 새 미출시 절 (409d72e → PR B, 비병합 79커밋)
해시 75개: 모두 bbde570에서 닿고 409d72e에서는 안 닿는다 / Refs가 행의 ID와 75/75 같다
인용 안 된 4커밋 = 리뷰 기록·CHANGELOG 커밋뿐 / ! 커밋 5개 = BREAKING 행 5개 = 먼저 할 일 1~5
: 287dc6f(D7) 본문이 다시 쓰기 전 해시 ab0d4a1·7ce9bf1을 가리킨다 (14-02, 새)
두 해시는 올리지 않은 로컬 fix/r1105-* 브랜치에만 있고, 원격 브랜치는 0개다
BREAKING 다섯 (먼저 할 일 1~5)
커밋 꼬리말·코드·[계약] 행이 서로 같다. 두 제품이 따라 하면 맞는 변경이 된다
: 1단계 "감싸지 않는 백엔드(memento-web, TechLog)" — TechLog는 Envelope다 (14-01 b)
: 2단계 requiresIdempotencyKey를 retrySemantics에서 다시 계산한다는 말이 없다 (14-01 c)
: 3단계 "부팅이 멈춘다" — 실제로는 그 기능 라우트에 처음 들어갈 때 실패한다 (14-01 a)
1105 영역 14 발견 셋: 모두 고쳐짐 (완료 기준을 변이·드릴로 확인)
14-01 예제 기능 드릴 PASS (17 checks), 예외를 끄면 새 테스트 2건 실패 (14-R1, 14-R2)
14-02 defaultValue를 지우면 새 테스트가 TS2322로 실패 (14-R4)
14-03 참조 기능 파일 이름을 바꾸면 매뉴얼 두 줄로 verify:documentation 실패 (14-R3)
: 예제 기능 드릴은 여전히 게이트 밖 (통제 잔여)
D7 문서: 이유·버린 대안·재검토 조건이 §16.2와 같다
: performance-evidence.md:209-210 "템플릿 그대로의 수(26)" — 지금 27 (15 영역 1103/15-02로 넘김)
```
- 새 발견 2건: Low 2(14-01, 14-02). High·P1은 없다.
- 지난 발견 13건(1105 셋, 1103 이월 셋, 그 밖의 이월 일곱): 고쳐짐 7, 일부 4, 남음 2. 재발·틀린 발견은 이 영역 범위에서 없다.
- §16과 다르게 본 것: 1105/14-01은 §16.4가 "일부"다. 완료 기준 셋을 모두 확인해서 **고쳐짐**으로 봤다(14-R1 드릴 PASS, 14-R2 변이, `PRODUCT.md:33`). "게이트가 드릴을 돌리지 않는다"는 완료 기준이 아니라 통제 수준 잔여로 4절 10·27번에 둔다. 0929/14-01은 §16.6이 "문서만 고쳤다"는 일부인데, 남은 것이 더 있다. 읽는 곳 없는 추적 산출물 13개가 남았다.
- 수정이 검사를 약하게 한 곳은 찾지 못했다. 지운 템플릿 기능의 경로를 받는 새 예외(`scripts/verify-documentation-readiness.ts:190-208`)는 `feature-module.ts`가 없을 때만 열린다. 양쪽 방향을 테스트가 보고, 예외를 끄면 그 테스트가 실패한다(14-R2). `tests/unit/removal-fixture.test.ts:161`의 정규식이 `docs/`를 받게 넓어졌지만, 목록의 새 테스트가 `docs/`를 읽기 때문이다.
- D7 상향 자체(예산 숫자)는 15 영역이 판정한다. 이 영역은 기록만 봤다.
지금 이해하면 되는 것:
1. 두 제품은 이 묶음을 받을 때 "먼저 할 일" 1~5를 그대로 따라 해도 된다. 1단계의 TechLog 설명과 3단계의 증상 설명만 틀리다.
2. tech-log는 2단계를 할 때 관리(management) 뮤테이션의 `requiresIdempotencyKey`가 `true`에서 `false`로 바뀐다는 것을 알아야 한다. 그 경로는 지금도 템플릿 실행기와 맞지 않는다.
3. 예제 기능을 지운 제품은 템플릿 문서를 고치지 않아도 문서 검사와 그 드릴을 통과한다(14-R1). 다만 그 드릴을 도는 게이트는 없다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 읽기만 한 저장소: `clean-architecture-backend-template`(pin `45d2a478`, `git cat-file`로만), `memento-frontend`(`d3810a0`), `tech-log-frontend`(`7a4e201a`). 두 다운스트림 HEAD는 지난 라운드와 같다 |
| 커밋·작업 상태·확인 시점 | `bbde570`, 노트북 worktree(읽기만), 2026-11-06. desktop에서는 `/tmp/claude-gates/` 아래 파일만 읽었다 |
| 목적과 지원 실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 짝 백엔드 템플릿과 함께 쓴다. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 필수 요구와 규모·운영 목표 | 두 템플릿으로 서비스를 빨리 출시한다. 두 다운스트림이 범위 단위로 동기화한다(memento merge, tech-log 3-way). 문서 규모 목표는 없다 |
| 지난 리뷰 뒤 바뀐 것 | `8a44226..bbde570` 비병합 79커밋, 병합 14커밋. 이 영역 경로를 고친 비병합 커밋 59개. `docs/` 문서 212개 98,440줄(지난 195개 93,445줄). 매뉴얼 2,278줄(지난 2,206줄). 리뷰 밖 문서·recipe diff 35파일 +747/−195줄. 새 파일: `scripts/lib/removable-template-features.ts`, `tests/unit/template-feature-removal-documents.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` |
| 읽은 코드·구성 범위 | `CHANGELOG.md` 전체(`:1-455`), `README.md:218-240`, `:372-424`, `PRODUCT.md`, `docs/README.md`, `docs/manual/` diff 전체, `docs/manual/reference/errors.md` 새 행, `docs/operations/performance-evidence.md` 전체, `docs/operations/ci-quality-gates.md:60-72`, `starter-experience.md:95-120`. 코드: 위 스크립트·테스트 전체, `src/contracts/external-contract-runtime.ts:230-245`, `:610-720`, `src/contracts/server-state.ts:265-330`, `src/adapters/realtime/polling/bounded-poll-coordinator.ts:1-140`, `:320-400`, `src/adapters/http/http-execution-v3.ts:445-515`, `src/features/installed-contract-contributions.ts`, `installed-feature-runtime-registries.ts`, `installed-feature-adapters.ts:40-90`, `src/bootstrap/runtime-adapters.ts:590-740`, `src/bootstrap/product-composition-contract.ts:60-170`, `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`. BREAKING 다섯 커밋(`56272e8`, `48c1ab7`, `5c0b37e`, `05330e3`, `757d1c7`)의 본문과 diff, `287dc6f`, `0fee3fe`, `832774f`, `f4be426`, `1e576ef`, `b834b8d`, `50b631e`, `332bfee`, `1dda18d`, `e6b2a4f`, `1ac336a`, `57e3586`, `1c4e57c`. 두 다운스트림의 뮤테이션 정책·HTTP descriptor 파일과 `git diff --name-status af3d8e6 HEAD -- src` |
| 수행한 테스트·실험 | 정적: 해시 대조(E-1), 범위 커밋·꼬리말 대조(E-2), 커밋 본문 해시(E-3), BREAKING 다섯과 두 다운스트림 대조(E-4), 다운스트림 수정 파일 분류 대조(E-5), CHANGELOG 경로 존재(E-6), 매뉴얼 새 오류 문구(E-7), 백틱 밖 지울 수 있는 기능 경로(E-8). 배치 14-R1~14-R4(`scratchpad/r5/requests/14.md`). 오케스트레이터가 `bbde570`에서 하나씩 돌렸고 매번 checkout을 clean으로 되돌렸다. 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-14-R1.log`~`R4.log`. 네 건 모두 기대대로다(6절) |
| 게이트 결과(같은 커밋, 다른 사람이 돌림) | `desktop:/tmp/claude-gates/bbde570-ci/summary.txt`(CI env): FE-GATE-001~012·020 rc=0, 013 rc=1(user namespace, 12 영역). FE-GATE-005 `test:unit` 208파일 3,056건 통과. 그 안에 `documentation-readiness.test.ts` 22건(`gate-artifacts/FE-GATE-005.txt:180`), `template-feature-removal-documents.test.ts` 4건(`:104`), `manual-paired-backend-settings.test.ts` 1건(`:94`), `changelog-review-ids.test.ts` 2건(`:293`), `env-registry-coverage.test.ts` 4건(`:280`), `hosting-probe.test.ts` 39건(`:76`). FE-GATE-020: 참조 기능을 지운 사본에서 "paths and scripts of removed template features not required: reference-feature" 뒤 `Documentation readiness: PASS_SCOPED`(`FE-GATE-020.txt:1539-1541`), `reference-feature removal: PASS (31 checks, no fixture IDs)`(`:3087`). 오케스트레이터 공유 실행: `verify-documentation.local.txt`(옆 백엔드 checkout 있음) `PASS_SCOPED`, `verify-documentation.no-sibling.txt` 17개 `not verified` 뒤 `PASS_SCOPED` |
| 확인하지 못한 범위·이유 | 두 다운스트림에서 실제 병합 뒤 게이트(제품 repo는 읽기만), tech-log 관리 쓰기 경로의 실제 동작, 다운스트림 descriptor의 `as` 단언이 `responseEnvelope` 누락을 잡는지(타입 검사 미실행), 깨끗한 환경 `install → dev`, 매뉴얼만 보는 기능 추가 재실험(X2), 목표 설계 문서 본문 전체 |
| 이전 리뷰와 비교 가능한 범위 | 1105 영역 14 발견 3건, §16.5의 1103 이월 3건(14-01, 14-02, 15-02의 CHANGELOG 부분), §16.6의 이월 7건을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|---|---|---|---|
| 1105/14-01 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | **고쳐짐** (통제 잔여: 드릴이 게이트 밖) | 고쳐진 것: ① 문서 검사가 지울 수 있는 템플릿 기능 목록(`scripts/lib/removable-template-features.ts:24-53`)을 읽는다. 그 기능의 `feature-module.ts`가 없으면 기능·테스트 폴더, context, 전용 파일, 전용 script를 요구하지 않는다(`scripts/verify-documentation-readiness.ts:190-208`, `:388`, `:395-398`). 설치된 동안은 그대로 본다. 목록에 없는 폴더는 실패한다. ② `tests/unit/template-feature-removal-documents.test.ts:86-115`가 기능마다 그 경로를 지운 사본에서 사본의 검사기를 돈다. 설치된 기능 아래 없는 경로와 목록에 없는 폴더는 실패하는 것도 본다. FE-GATE-005(CI env)에서 4건 통과(`FE-GATE-005.txt:104`). ③ `tests/unit/hosting-probe.test.ts:252`가 테스트 전용 ID `fixture-feature`를 쓴다. ④ `PRODUCT.md:33`이 예제 화면 3개를 같은 드릴로 지울 수 있다고 적는다. ⑤ `starter-experience.md:104-118`이 지우는 법과 검사 규칙을 적는다. 완료 기준 셋을 확인했다. (가) 세 폴더를 지운 사본의 문서 검사: 위 ②가 FE-GATE-005에서 통과(E2). 예외를 끄는 변이에서는 "passes in a copy without platform-examples-feature"가 `starter-experience.md names paths that do not exist: src/contexts/platform-examples-context, src/features/platform-examples-feature, tests/features/platform-examples-feature`로 실패했다(14-R2, E3). 지난 라운드 14-R1의 실패 문구와 같다. (나) 드릴: `test:sample-removal -- --feature=platform-examples-feature`가 `platform-examples-feature removal: PASS (17 checks, no fixture IDs)`, `drill-rc=0`이다(14-R1, E3). 그 안에서 타입 검사·lint·`verify:documentation`(“removed template features not required: platform-examples-feature” 뒤 `PASS_SCOPED`)·i18n·디자인 시스템·아키텍처·레지스트리·`test:all`·커버리지·빌드가 돌았다(`R5-14-R1.log:5-33`, `:2144`, `:2198-2199`). (다) `PRODUCT.md:33`이 코드와 같다(E1). 통제 잔여: 어느 게이트도 이 드릴을 돌리지 않는다(`CHANGELOG.md:93`, FE-GATE-020은 참조 기능만). 다음에 깨져도 알리는 것은 문서 쪽 unit 테스트뿐이다. 4절 10·27번에 둔다 |
| 1105/14-02 | 매뉴얼 04 §3.2 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | **고쳐짐** | `docs/manual/04-paired-backend-session.md:126-129` 두 행에 `defaultValue: null`. `tests/unit/manual-paired-backend-settings.test.ts:112-144`가 §3.2의 첫 ts 블록을 사본의 `product-contracts.ts` 옆에 그대로 넣고 `tsc --project tsconfig.app.json`(= `check:types:app`의 tsc, `package.json:30`)과 FE-REG-ENV 행 대조를 돈다. FE-GATE-005에서 통과(`FE-GATE-005.txt:94`). 완료 기준("그대로 옮긴 사본에서 `check:types:app`과 env-registry-coverage가 통과")을 채운다(E2). 테스트가 매뉴얼 블록을 실제로 읽는지도 봤다. 두 행에서 `defaultValue: null`을 지운 변이에서 그 테스트가 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`로 실패했다(14-R4, `R5-14-R4.log:17-19`, E3). 지난 라운드 14-R3의 실패와 같은 문구다. 작은 잔여: 행 대조는 `tests/unit/env-registry-coverage.test.ts:22-27`의 규칙을 테스트 안 문자열(`manual-paired-backend-settings.test.ts:64-89`)로 한 벌 더 가진다. 지금 두 규칙은 같다. 새 발견으로 세지 않는다 |
| 1105/14-03 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | **고쳐짐** | `1dda18d`가 README와 §1 문서 12개의 참조 기능 경로·`test:reference-feature`를 다시 백틱(또는 명령 한 줄)으로 적었다. `template-feature-removal-documents.test.ts:129-155`가 §1 문서에서 지울 수 있는 기능의 경로·script가 백틱·링크·셸 블록 밖에 나오면 실패한다. FE-GATE-005 통과. 완료 기준 뒤 절반("참조 기능을 지운 사본에서는 통과")은 FE-GATE-020이 본다(`FE-GATE-020.txt:1539-1541`, `:3087`, E2). 앞 절반("파일 이름을 바꾸면 매뉴얼 줄 때문에 실패")은 같은 테스트 파일 `:99-114`가 덧붙인 경로로 본다. 실제 이름 변경도 돌렸다. `src/features/reference-feature/adapters/reference-http-gateway.ts`의 이름을 바꾸자 `verify:documentation`이 `docs/manual/01-add-a-feature.md`와 `docs/architecture/backend-api-and-server-state-contract.md`의 그 경로로 `FAIL_UNVERIFIED`, `verify-rc=1`이었다(14-R3, `R5-14-R3.log:4-8`, E3). 지운 기능 예외를 끄면 참조 기능을 지운 사본에서 12개 문서가 실패한다(14-R2, `R5-14-R2.log:15-26`). 다시 백틱으로 적은 경로가 실제로 검사를 받는다는 뜻이다. 커밋이 적은 한계(언어 없는 펜스 안 명령 아닌 줄은 안 본다)를 대조했다. 지금 그런 줄에 지울 수 있는 기능 경로는 없다(E-8) |
| 1103/14-01 | CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다 | **고쳐짐** | 지난 잔여 셋: (a) 초기 파일 상한이 `CHANGELOG.md:207`, `:317` 모두 32다(`config/performance/budgets.json:5`). `:317`의 커밋이 `1b8cb12` 대신 `2fef27d`이고 그 커밋은 `752a61f..8a44226` 안에 있다. (b) 알려진 제한 머리가 "범위 끝 `8a44226`"이다(`:359`). (c) `verify:documentation`(FE-GATE-017)이 "merge 게이트 밖"에 있다(`:218-220`). 모두 `832774f`. `:207`, `:372`의 "여유 1,873 B"는 기록 값이라고 커밋 본문이 적는다 |
| 1103/14-02 | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 | **일부** | 고쳐진 것: "옮기기 전" 2단계(`CHANGELOG.md:133-139`)가 수를 적는다. memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2). 두 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(기능·context 폴더 밖)를 다시 세니 같다(E-5). 추가·수정 파일은 모두 세 분류(제품 소유 자리 있음 `:137`, 없음 `:138`, 템플릿 결함 후보 `:139`) 중 하나에 이름이 있다. 남은 것: 완료 기준 "memento-web 모양에 안내를 그대로 적용하면 `check:registries`가 통과한다"는 실행하지 않았다(`:91`, `:108`). 자리 없는 파일을 템플릿에 들일지는 결정 대기다(`:99`) |
| 1103/15-02 (CHANGELOG 부분) | CHANGELOG가 초기 파일 예산을 26으로 적는다 | **고쳐짐** | `CHANGELOG.md:207`, `:317`이 32다(`832774f`). 같은 ID의 문서 부분에 새로 어긋난 곳이 있다. `docs/operations/performance-evidence.md:209-210`이 "상한은 템플릿 그대로의 수(26)에 6을 더한 32"라고 적는데, 기록은 `files: 27`이다(`config/scale/feature-shape-ceilings.json:43`, `0fee3fe`. 08-03 `f849d78`이 초기 파일 하나를 더했다). 1103/15-02의 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시 어긴다. 15 영역 소관이라 여기서 세지 않는다(2.3절) |
| 1101/14-02 | 리뷰 ID 꼴이 섞인다 | **고쳐짐** | `b834b8d`: `CHANGELOG.md:11`이 네 꼴(`MMDD/NN-MM`, `MMDD README N.N`(+`X2`), `MMDD NN 영역 P-NN-NN`, `백엔드 리뷰 MMDD/NN-MM`)을 정한다. `tests/unit/changelog-review-ids.test.ts:36-49`가 괄호 안의 README·X·P·백엔드 참조를 그 꼴로 막는다. FE-GATE-005 통과(`:293`). 작은 잔여: 괄호 밖 참조와 그 네 낱말이 없는 참조는 보지 않는다. 지금 그런 참조는 찾지 못했다 |
| 0929/14-01 | 실행 로그·작업 기록이 복사 대상에 섞인다 | **일부** | 고쳐진 것: `docs/README.md:91`이 루트 `SPEC.md`·`tasks/`의 이유를 끝난 라운드에 맞췄다(`1ac336a`). README 지울 목록에 둘이 있다(`README.md:228`). 추적 `.log` 0개. 남은 것: 완료 기준 "`git ls-files artifacts`에 `.gitkeep`과 게이트가 읽는 증거만 남는다"를 채우지 못한다. `artifacts/tests/coverage-gateway/` 10개(2026-09-18 `ec7f20e`, `reference-http-gateway.ts.html` 포함)와 `artifacts/local-preview/*.png` 3개(2026-07-30 `d3ef801`)가 추적된다. `scripts`·`config`·`tests`·`.gitea`·`package.json` 어디도 읽지 않고(`git grep` 0건), README 지울 목록(`README.md:224-230`)에도 없다 |
| 0929/14-02 | README 업데이트 절차가 범위 반영을 다루지 않는다 | **일부** | 고쳐진 것: `README.md:396-404`가 범위를 받는 두 명령(`git merge --no-ff`, `git merge-recursive <range base> -- HEAD …`)을, `:406-408`이 기준점 기록을 적는다(`57e3586`). 남은 것: 명령은 실행하지 않았다(커밋 본문). 완료 기준 "기준점 형식이 하나다"는 그대로다(`.template-origin`과 `template.lock.json`, `:406-408`). 새 문장끼리 어긋난다: `:407`의 "(below)"가 가리키는 `.template-origin` 설명은 위(`:381-383`)에 있다. `:408`은 "범위를 받으면 범위 끝으로 옮긴다", `:418-419`는 "태그까지 따라잡으면 `.template-origin`을 고친다"다 |
| 0929/14-03 | 제품이 고치는 템플릿 파일 목록이 없다 | **일부** | 두 제품의 수정 파일 분류는 이제 빠짐이 없다(1103/14-02 행). 완료 기준의 "README에 표"와 "다음 동기화의 공통 충돌 경로가 모두 표에 있다"는 그대로다. 목록은 CHANGELOG와 매뉴얼 03 C·D절에만 있고, 충돌 경로는 재지 않았다 |
| 0929/14-05 | `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적는다 | **고쳐짐** | `docs/operations/ci-quality-gates.md:69`가 "실패하는 검사는 없다"와 경고 두 곳을 적는다(`1c4e57c`). 코드와 같다: `scripts/check-release-admission.ts:131-142`(`release admission warning: … the override does nothing`), `src/bootstrap/runtime-adapters.ts:513`·`src/contracts/diagnostics.ts:21`(`feature.override.unknown`, warn). 작은 잔여: 같은 칸의 "(리뷰 09-09)"에 라운드가 없다. CHANGELOG 밖이라 테스트가 보지 않는다 |
| 0929/14-06 | 제품이 찾은 템플릿 결함 후보가 돌아오지 않는다 | **남음** (결정 대기) | 결정 대기로 적혀 있다(`CHANGELOG.md:99`). 첫 후보 하나가 상태와 함께 CHANGELOG에 처음 들어왔다(`:139`, "템플릿은 이것을 재현하지 않았다"). 받는 곳(이슈·FOLLOW-UP)은 정하지 않았다. `docs/manual/reference/errors.md`의 새 잔여 행은 "템플릿에 알린다"고만 적는다 |
| 1101/14-07 | 문서 위치가 상태를 드러내지 않는다 | **남음** (결정 대기) | 결정 대기(`CHANGELOG.md:99`). `docs/README.md:35`는 계약 문서의 4.1·6·6.1절만 현재 계약이고 나머지는 목표 설계라고 적는다. §2(`docs/README.md:67-79`)는 그대로 섞여 있다 |
### 2.1 BREAKING 다섯 — 안내대로 하면 맞는 변경이 되는가 (렌즈 ②)
새 절 "먼저 할 일" 1~5가 `!` 커밋 다섯과 1:1이다. 각 행은 커밋 꼬리말·코드·[계약] 행·두 다운스트림의 실제 모양 순으로 대조했다(E-4).
| 단계 · 커밋 | 꼬리말·코드와 CHANGELOG | memento `d3810a0` | tech-log `7a4e201a` | 판정 |
|---|---|---|---|---|
| 1 `responseEnvelope` 필수 · `56272e8` (1103/16-01) | 꼬리말: 필수 칸, 없으면 `check:types` 실패, 감싸지 않으면 `NONE`·Envelope면 `ENVELOPE_V1`, 런타임 같음. 코드: `src/contracts/external-contract-runtime.ts:239` 필수, 조립은 빠진 값을 `NONE`으로 읽는다(`:715-716`). `CHANGELOG.md:24`, `:59`가 같은 말을 한다. 다른 점: `:24`가 "감싸지 않는 백엔드(memento-web, TechLog)"라고 적는다 | descriptor가 모두 `contract()` 한 함수에서 나온다(`memento-http-contract-contribution.ts:217-267`). 줄 하나(`responseEnvelope: "NONE" as const`)로 끝난다. 동작은 같다 | TechLog의 출력 검증기는 Envelope(`{ success, data, meta }`)를 스스로 벗긴다(`tech-log-studio-contract-contribution.ts:71-78` `envelopeData`). 그래서 `NONE`이 지금 동작을 지키는 값이다. `ENVELOPE_V1`로 적으면 실행기가 한 번 더 벗겨 `envelopeData`가 실패한다. 같은 CHANGELOG의 아래 절은 TechLog를 "Envelope 뼈대만 검사"로 적는다(`:142`) | **맞는 변경이 된다.** 설명 둘이 틀리다(14-01 b). "빠뜨리면 `satisfies`에서 `check:types` 실패"도 두 제품에는 해당하지 않을 것이다. 두 제품은 `as` 단언으로 descriptor 타입을 붙인다(memento `:267`, tech-log `tech-log-management-contract-contribution.ts:106`, `:166`, `tech-log-public-contract-contribution.ts:89`). 빠뜨려도 런타임은 `NONE`이라 피해는 없다(정적 추론, 타입 검사 미실행) |
| 2 뮤테이션 operation ID brand · `48c1ab7` (1103/16-05) | 꼬리말: `operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`로. 코드: `src/contracts/server-state.ts:276-278` brand, `:294-312`가 `requiresIdempotencyKey = retrySemantics === "KEYED"`를 돌려준다, `:319`. `CHANGELOG.md:25`, `:65`가 같다 | 손으로 적은 정책 8개(`use-memento.ts:150-289`). 8개 모두 손으로 적은 `requiresIdempotencyKey`가 descriptor의 `KEYED` 여부와 같다(`memento-http-contract-contribution.ts:371`, `:429`, `:525`, `:567`, `:608`은 KEYED·true, `UPDATE_MEMORY`·`UPDATE_ALBUM`은 기본 NEVER·false, `:511`은 IDEMPOTENT·false) | 정책을 만드는 함수가 operation ID를 문자열 인자로 받는다(`studio-asset-server-state.ts:139-170`, `studio-management-server-state.ts:193-226`). 그 함수가 descriptor를 받게 바꾸면 된다. 관리(management) 정책은 `requiresIdempotencyKey: true`를 손으로 적고(`:209`), 키가 없으면 던진다(`:216-218`). 그런데 관리 쓰기 descriptor는 모두 `NEVER`다(`tech-log-management-contract-contribution.ts:143`). 2단계대로 하면 값이 `false`가 되고, 자기 가드가 저장마다 `TypeError`를 던진다. `check:types`는 통과한다 | **memento: 맞는 변경, 동작 같음.** **tech-log: 템플릿 계약에는 맞는 변경이다.** 지금도 그 경로는 `NEVER` descriptor에 키를 실어 보내고(`http-management-gateway.ts:63`), 실행기는 그것을 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절한다(`src/adapters/http/http-execution-v3.ts:508-512`, tech-log 사본 `:429`, 정적 추론). 그래서 동기화가 새로 깨는 것은 아니다. 다만 안내가 값이 다시 계산된다는 말을 하지 않는다(14-01 c) |
| 3 `refusedBeforeWrite` 플랫폼 code · `5c0b37e` (1105/03-01) | 꼬리말: `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`를 적으면 조립이 거절, 목록에서 지운다, 결과 불명으로 남는다. 코드: 목록 `external-contract-runtime.ts:638-660`(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8, `LOCK_ACQUISITION_TIMEOUT`, fileserver 9), 거절 `:691-695`, 실행기도 무시(`src/adapters/http/backend-envelope.ts:336`). 계약 문서 6.1 표와 같다(`backend-api-and-server-state-contract.md:319-325`). `CHANGELOG.md:26`, `:60`이 같다. 다른 점: `:26`이 "계약 조립이 거절해 부팅이 멈춘다"고 적는다 | `refusedBeforeWrite`는 `ENVELOPE_V1` operation에만 쓴다(`external-contract-runtime.ts:676-679`). memento는 `responseEnvelope`가 없다. `git grep refusedBeforeWrite` 0건. 할 일 없음 | 같다. 0건. 할 일 없음 | **맞는 변경이 된다.** 증상 설명이 틀리다(14-01 a). 브라우저는 부팅 때 빈 목록만 조립한다(`src/features/installed-contract-contributions.ts:94`). 기능 기여는 그 기능 실행부를 적재할 때 조립한다(`:96-111`, `src/features/installed-feature-adapters.ts:80`, `src/bootstrap/runtime-adapters.ts:735-739`). 그래서 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때(또는 플랫폼 구성 화면, `platform-overview-page.tsx:680`) 실패한다. CI에서는 `loaded-feature-runtimes.ts`를 읽는 `test:unit`과 `check:registries`가 먼저 잡는다 |
| 4 던지는 poll `execute` · `05330e3`, `27e3dec` (1105/04-02, 1103/04-01) | 꼬리말: 던지면(abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님), 네트워크 실패는 retryable `PROVIDER_UNAVAILABLE` 결과로. 코드: `bounded-poll-coordinator.ts:104-129`(결과로 돌려준다는 규칙과 `input.operation`), `:338-346`(던짐 → `null`), `:395-398`(`PROTOCOL_MISMATCH`). 결과 생성 함수 `realtimeFailure`는 배럴에 있다(`src/adapters/realtime/index.ts:38`). `CHANGELOG.md:27`, `:67`이 같다. 아래 절의 옛 행도 `1e576ef`이 고쳤다(`:298`, "위 절에서 다시 바뀌어") | `createBoundedPollCoordinator`는 템플릿 사본(`src/adapters/realtime/polling/`)과 템플릿 테스트에만 있다. 할 일 없음 | 같다. 할 일 없음 | **맞는 변경이 된다** |
| 5 `a11y.json` schemaVersion 2 · `757d1c7` (1103/11-01) | 꼬리말: `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 `notChecked`에 `{ routeId, reason }`. 코드: `scripts/contracts/release-artifacts.ts`(같은 커밋에서 바꿈, `:836` 근처). `CHANGELOG.md:28`, `:53`이 같다 | `a11y.json`을 읽는 것은 템플릿 파일(`scripts/write-a11y-report.ts`, `config/ci/gates.json`)뿐이다. 템플릿 것을 받으면 끝 | 같다 | **맞는 변경이 된다** |
정리: 다섯 단계 모두 행동은 맞다. 틀린 것은 설명 셋이다(14-01). "먼저 할 일" 6~10은 `!` 커밋이 아닌 수정에서 왔다. 행에는 **BREAKING** 표시가 없지만 단계 목록에는 있다. 안내가 실제로 쓰이는 곳은 단계 목록이라 문제로 보지 않았다. 표시 없이 생긴 필수 칸이 하나 있다. `ProductCompositionContext.notifySessionUnauthenticated()`(`src/bootstrap/product-composition-contract.ts:100`, `0007699`)다. context를 직접 만드는 제품 코드(테스트·fake)만 타입 검사에서 걸린다. 두 다운스트림과 템플릿 테스트 모두 그런 곳이 없다. 기록만 한다.
### 2.2 새 절의 해시 (렌즈 ①)
- 새 절(`CHANGELOG.md:14-108`)의 백틱 해시는 76개다. 기준점 `409d72e`를 빼면 75개다(E-1).
- 75개 모두 `bbde570`에서 닿고, `409d72e`에서는 닿지 않는다.
- PR A로 적은 셋(`9655958`, `629c713`, `397664e`, `:16`)은 `a793b83` 이력에 있다.
- 각 커밋의 `Refs:` 꼬리말이 그 행의 리뷰 ID와 같다(75/75, E-2). 해시를 여러 번 다시 쓴 통합에서도 CHANGELOG는 마지막 해시로 맞춰졌다.
- `409d72e..bbde570` 비병합 79커밋 중 인용되지 않은 것은 넷이다. 리뷰 기록(`e85c836`, `bbde570`)과 CHANGELOG 커밋(`a793b83`, `1c884e1`)이다.
- `!` 커밋 다섯(`5c0b37e`, `56272e8`, `757d1c7`, `48c1ab7`, `05330e3`)이 **BREAKING** 행 다섯이고, 모두 `BREAKING CHANGE:` 꼬리말이 있다.
- 범위 커밋 본문의 해시도 봤다(E-3). `287dc6f`(D7) 본문만 이 이력에 없는 해시 둘을 가리킨다(14-02).
- CHANGELOG는 `verify:documentation` 밖이다(`scripts/verify-documentation-readiness.ts:165`, `docs/README.md:50-51`). 해시·경로는 사람이 대조한다. 새 절의 repo 경로는 생성 산출물(`artifacts/tests/a11y.json`)과 백엔드 문서(`docs/fileserver/http-contract.md`, `:101`, 백엔드 pin에 있음)를 빼면 모두 있다(E-6).
### 2.3 D7 문서 (렌즈 ⑤)
| 항목 | README §16.2 D7 | `CHANGELOG.md:56` | `docs/operations/performance-evidence.md:44-53` | 판정 |
|---|---|---|---|---|
| 값 | 204,800 → 206,848 B(`287dc6f`) | 같다 | 같다(`:6` 머리도 202 KiB) | 맞다. `config/performance/budgets.json:4` |
| 이유 | 합친 빌드 204,111 B·27개(PR A 202,927 B·26개). 드릴이 기능 둘을 더해 205,463 B, 663 B 초과. 늘어난 곳 1,184 B(03-01 +327, 08-03 +293·파일 +1, 02-01 +251, 합칠 때 +148, 나머지 +165) | 1,184 B, 드릴(FE-GATE-020) 초과, 기록 204,111 B·27개 | 1,184 B, 663 B 초과, 03-01·08-03·02-01, 기록 커밋 `0fee3fe` | 맞다. 작은 차이: 두 문서 모두 08-03(홈 시작 링크의 `navigation-policy` 공유 청크)을 "검사·진단 코드"에 넣는다. §16.2는 따로 센다. performance-evidence는 파일 +1을 적지 않는다 |
| 버린 대안 | 줄이기. 라운드 중간 설계 변경이라 다음 라운드 숫자를 흐린다. 청크를 합치는 것만으로는 663 B를 못 채운다 | 없음 | 런타임 검사를 빌드 시점으로 옮겨 줄이기. 같은 이유 | 맞다 |
| 재검토 조건 | 예산을 다시 넘을 때, 1103/13-03을 정할 때. 그때 03-01·02-01 검사를 빌드 시점으로 옮기는 것부터. 13-03을 정하지 않는다 | performance-evidence를 가리킨다 | 같은 세 문장 | 맞다 |
| 결정자 | 메인 세션, 2026-11-06 | 없음 | 없음. README 16절을 가리킨다 | 작다. `docs/reviews/`를 지운 사본에서는 결정자가 안 보인다 |
| 같은 문서의 다른 숫자 | 초기 파일 26 → 27 | 27 | `:209-210` "템플릿 그대로의 수(26)에 6을 더한 32" | **틀리다.** 지금 27이고 여유는 5다. 1103/15-02 문서 부분이라 15 영역에 넘긴다 |
| 문서 자기 규칙 | — | — | `:90` "예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다". 표(`:58-70`)는 2026-11-01(`298201f`) 그대로 | 이유는 적었다. 출처별 표는 다시 재지 않았다. 작다 |
판정: CHANGELOG 행은 이유를 적고 재검토 조건은 performance-evidence를 가리킨다. performance-evidence는 이유·버린 대안·재검토 조건을 §16.2와 같게 적는다. **충족**, 작은 잔여 셋(08-03 분류, 결정자, 출처별 표). `:209-210`의 26은 15 영역 판정으로 넘긴다.
### 2.4 `verify:documentation` 출력
- 옆에 백엔드 checkout이 있는 실행: `Documentation readiness: PASS_SCOPED`. `not verified` 줄이 없다(`desktop:/tmp/claude-gates/r5/snap/verify-documentation.local.txt`).
- 옆 checkout이 없는 실행: 짝 백엔드 참조 17개(경로 14개) `not verified` 뒤 `PASS_SCOPED`(`verify-documentation.no-sibling.txt`).
- 지난 라운드는 로컬 실행이 rc=1이었다. 그때 백엔드 checkout이 pin이 아닌 `ef947e5`였다. 이제 검사기가 pin 커밋의 트리를 읽는다(`fc95672`, `CHANGELOG.md:50`). 그래서 checkout HEAD와 상관없이 같은 결과가 나온다. 이 부분 판정은 12 영역이다.
## 3. 이번 발견 (36.3)
수: Critical 0 · High 0 · Medium 0 · Low 2. P1 0 · P2 1 · P3 1. 확인된 결함 2.
### 14-01 새 미출시 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림 모양과 다르다 — 행동은 맞지만, 증상·대상·바뀌는 값을 틀리게 또는 빼고 적는다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 17, 23, 24, 20, 30.4 |
| 근거 | **(a) 3단계 증상.** `CHANGELOG.md:26`은 플랫폼 code를 `refusedBeforeWrite`에 적으면 "계약 조립이 거절해 부팅이 멈춘다"고 적는다. 브라우저는 부팅 때 빈 기여 목록만 조립한다(`src/features/installed-contract-contributions.ts:93-94`). 기능의 계약 기여는 그 기능 실행부를 적재할 때 `install`이 조립한다(`:96-111`, `src/features/installed-feature-adapters.ts:80`, `src/bootstrap/runtime-adapters.ts:735-739`). 같은 CHANGELOG의 아래 절도 "계약 기여는 기능 실행부를 적재할 때 설치되고"라고 적는다(`:180`). 그래서 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때와 플랫폼 구성 화면(`src/presentation/examples/platform-overview-page.tsx:680`)에서 실패한다. 6단계(`:29`)의 "조립이 `TypeError`로 멈춘다"는 부팅 조립(`runtime-adapters.ts:716-718`)이라 맞다. **(b) 1단계 대상.** `:24`는 "감싸지 않는 백엔드(memento-web, TechLog)는 `NONE`"이라고 적는다. TechLog의 출력 검증기는 `{ success: true, data, meta }`를 검사하고 `data`를 꺼낸다(tech-log `tech-log-studio-contract-contribution.ts:71-78`). 백엔드가 Envelope로 감싼다는 뜻이다. 아래 절은 TechLog를 "출력은 Envelope 뼈대만 검사"로 적는다(`:142`). 두 절이 같은 제품을 다르게 적는다. 같은 단계의 "빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다"는 템플릿·생성 기능에는 맞다. 두 제품은 `as` 단언으로 descriptor 타입을 붙인다(memento `memento-http-contract-contribution.ts:267`, tech-log `tech-log-management-contract-contribution.ts:106`, `:166`). **(c) 2단계의 바뀌는 값.** `:25`는 `operationId`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾸라고 한다. 이 함수는 `requiresIdempotencyKey`를 `retrySemantics === "KEYED"`로 다시 계산한다(`src/contracts/server-state.ts:303-311`). 손으로 적은 값이 descriptor와 다른 정책은 값이 바뀐다. 안내는 그 말을 하지 않는다. 실제 사례: tech-log 관리 정책은 `true`를 적고(`studio-management-server-state.ts:209`) 키가 없으면 던진다(`:216-218`). 관리 쓰기 descriptor는 `NEVER`다(`tech-log-management-contract-contribution.ts:143`). 안내대로 하면 `false`가 되고, `check:types`는 통과하고, 저장마다 자기 가드가 던진다. memento 8개는 값이 같아 바뀌지 않는다(2.1절) |
| 발생 조건 | 두 제품이 다음 동기화에서 새 절 "먼저 할 일"을 읽을 때. (a)는 운영자가 증상으로 원인을 찾을 때, (b)는 TechLog 담당이 `ENVELOPE_V1`이 맞는지 판단할 때, (c)는 tech-log가 관리 뮤테이션을 옮길 때 |
| 영향 | 행동은 모두 맞아서 데이터 피해는 없다. (a) "부팅이 멈춘다"를 기대한 사람은 앱이 뜨는 것을 보고 다른 원인을 찾는다. CI에서는 `test:unit`·`check:registries`가 먼저 잡는다. (b) TechLog 백엔드가 Envelope인 것을 아는 사람이 "Envelope면 `ENVELOPE_V1`"을 따르면, 실행기가 한 번 벗긴 `data`를 TechLog 검증기가 다시 벗기려다 모든 응답이 실패한다. (c) tech-log 관리 쓰기는 지금도 실행기가 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절하는 모양이다(`http-management-gateway.ts:63`, `src/adapters/http/http-execution-v3.ts:508-512`, 정적 추론). 그래서 동기화가 새로 깨는 것은 아니지만, 실패 이유가 실행기 위반에서 제품 `TypeError`로 바뀌고 안내는 그 이유를 주지 않는다 |
| 심각도·우선순위 | Low · P2 — 지난 라운드 1105/14-02(매뉴얼 예시 한 줄이 게이트를 깸)와 같은 기준이다. 문서 몇 줄의 어긋남이고 동작 피해는 없다. 다만 두 제품이 다음 동기화에서 그대로 읽는 문단이라 P2다 |
| 통제·증거 | 목표 M2(BREAKING 안내의 증상·대상 설명이 코드와 다운스트림 실제 모양과 같다). 확인: M1(사람이 쓰고 사람이 읽는다. CHANGELOG는 문서 검사 밖, `scripts/verify-documentation-readiness.ts:165`) · E1(코드·두 다운스트림 정적 대조). `as` 단언이 누락을 잡지 않는다는 것과 tech-log 관리 경로의 실제 거절은 실행하지 않은 추론이다 |
| 확실성과 남은 가정 | (a)·(b)의 코드 사실과 (c)의 값 변화는 코드로 확인했다. tech-log 관리 쓰기가 지금 실행기에서 거절된다는 것은 코드 경로를 읽은 추론이다. 제품 쪽 다른 우회가 있는지는 실행하지 않았다 |
| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다 |
| 이해 비용 | 제품 개발자가 증상(앱이 뜸)과 안내(부팅이 멈춤)가 다를 때 계약 조립 시점을 코드에서 찾아야 한다. tech-log 담당은 `commandMutationIdentity` 본문을 읽어야 값이 바뀌는 것을 안다 |
| 최소 개선 방향 | ① `:26`을 "그 기능 실행부를 적재할 때 조립이 거절한다. 라우트에 처음 들어갈 때 실패하고, CI에서는 `test:unit`과 `check:registries`가 잡는다"로 고친다. ② `:24`의 괄호를 "memento-web, 그리고 Envelope를 검증기에서 직접 벗기는 TechLog는 `NONE`"으로 고친다. ③ `:25` 끝에 "`requiresIdempotencyKey`는 descriptor의 `retrySemantics`가 `KEYED`일 때만 `true`다. 손으로 적은 값과 다르면 동작이 바뀐다(tech-log 관리 쓰기는 `NEVER`)"를 붙인다 |
| 대안 비교 | 적용 제외 — 문장 정정이다 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문장 세 곳 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 세 문장이 코드와 같다. 같은 CHANGELOG 두 절이 TechLog 백엔드를 같은 모양으로 적는다 |
| 검증 방법 | 문서 대조. (c)는 tech-log sync 브랜치에서 2단계 뒤 관리 저장 한 번 |
| 담당·기한·상태 | 미정 · 다음 동기화 전 · 신규 |
| 재검증 결과 | 미실시 |
### 14-02 D7 커밋 `287dc6f` 본문이 다시 쓰기 전 해시 둘을 가리킨다 — 통합에서 해시를 여러 번 다시 썼는데, CHANGELOG·커밋 본문의 해시를 대조하는 장치가 없다
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 |
| 관련 관점 | 9, 24, 21, 30.4 |
| 근거 | `git show 287dc6f` 본문의 "늘어난 곳"이 1105/03-01을 `ab0d4a1`, 1105/08-03을 `7ce9bf1`로 적는다. 두 객체는 이 노트북 저장소에 남아 있고 제목도 맞다. 오케스트레이터 설명대로 03-01·08-03을 마지막으로 다시 짓기 전의 해시다. 그러나 `bbde570`에서 닿지 않는다(`git merge-base --is-ancestor` 실패). 두 객체를 담은 것은 올리지 않은 로컬 브랜치뿐이다(`fix/r1105-docs`, `-sq2`, `-sq3`, `-v2`, `fix/r1105-http-forms-sq`). `git branch -r --contains`는 둘 다 0개다. `287dc6f` 자신은 `origin/fix/maturity-review-2026-11-05-b`에 있다. 그래서 원격에서 받은 clone에서는 두 해시를 열 수 없다. `bbde570` 이력의 같은 변경은 `5c0b37e`, `f849d78`이다. README §16.2와 `CHANGELOG.md:56`, `performance-evidence.md:48`은 올바른 해시를 쓴다. `409d72e..bbde570` 커밋 본문 전체에서 이 이력에 없는 이 repo 해시는 이 둘뿐이다(E-3. 나머지 두 개는 다른 repo의 `d3810a0`, `ef947e5`). CHANGELOG는 문서 검사 밖이다(`scripts/verify-documentation-readiness.ts:165`). 해시 대조는 리뷰가 손으로 한다. 이번 CHANGELOG는 75/75 맞았다(2.2절) |
| 발생 조건 | 다운스트림이나 다음 리뷰가 D7의 근거를 `git show 287dc6f`로 따라갈 때. 새 clone에는 두 객체가 없다 |
| 영향 | 근거 사슬 한 칸이 끊긴다. README §16.2에 같은 내용과 맞는 해시가 있어 피해는 작다. 이력은 이미 올라가 고칠 수 없다 |
| 심각도·우선순위 | Low · P3 — 문서 한 칸의 어긋남이고 대체 기록이 있다 |
| 통제·증거 | 목표 M3(통합 끝에 범위 안 CHANGELOG·커밋 본문 해시를 범위와 대조한다). 확인: M0(장치 없음) · E1(`git rev-parse`, `git merge-base`, `git branch -a/-r --contains`) |
| 확실성과 남은 가정 | 직접 확인했다. 원격 브랜치 목록은 이 노트북이 마지막으로 받은 것이다. 로컬 `fix/r1105-*` 브랜치를 나중에 올리면 두 해시는 열린다. 그래도 PR B 이력에서 닿지 않는 것은 그대로다. PR B가 원격에서 다시 쓰이면 CHANGELOG 해시 75개도 다시 대조해야 한다 |
| 결정의 근거 | 기록된 사실: §16.3이 브랜치 안 결함을 fixup으로 접었다고 적는다. 그때 해시가 바뀌었다. 오케스트레이터 설명: 이 본문은 마지막으로 다시 짓기 전에 썼다. 리뷰어 판단: 원인이 설명대로라도 결함은 남는다. 본문이 가리키는 커밋을 PR B 이력에서 찾을 수 없다 |
| 이해 비용 | 근거를 따라가는 사람이 없는 해시를 만나 README §16을 따로 찾는다 |
| 최소 개선 방향 | 이력은 고치지 않는다. 통합 절차(지금은 리뷰 README §16.1)에 "해시를 다시 쓴 뒤 범위 커밋 본문·CHANGELOG 새 절·README §16의 해시를 `git merge-base --is-ancestor`로 대조한다"는 한 단계를 둔다. 명령 한 줄이다 |
| 대안 비교 | (a) 현 상태: 리뷰가 매번 손으로 센다. (b) 절차 한 단계: 싸다. 사람이 빼먹을 수 있다. (c) CHANGELOG 해시 테스트: 미출시 절 머리의 범위로 대조한다. 그러나 복사한 프로젝트에는 템플릿 이력이 없어 그쪽에서는 건너뛰어야 한다. (b) 권장, (c)는 해시 어긋남이 다시 나오면 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | (b) 문서 한 줄. (c) 테스트 수십 줄과 이력 없는 사본의 건너뛰기 규칙 |
| 재검토 조건 | 통합에서 fixup·rebase를 하지 않게 되면 이 위험은 줄어든다 |
| 완료 기준 | 다음 통합 기록에 그 대조 결과가 있다 |
| 검증 방법 | 범위 커밋 본문의 7~12자리 해시마다 `git merge-base --is-ancestor <hash> <end>` |
| 담당·기한·상태 | 미정 · 다음 통합 · 신규 |
| 재검증 결과 | 미실시 |
## 4. 28개 관점 판정 (36.2)
기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 01~13 영역 | - | - | 이 영역은 문서·문서 검사·드릴 스크립트만 본다 |
| 2 | 구조적 성숙도 | > 09·12 영역 | M3 / M3 | E2 | 입구 문서의 폴더·규칙 설명은 지난 라운드처럼 검사된다. FE-GATE-005 통과 |
| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P — 두 제품이 고친 템플릿 `src` 파일 26/40개가 모두 "자리 있음·없음·결함 후보"로 나뉘었다(1103/14-02 잔여 (a) 고쳐짐). 자리 없는 것을 들일지는 결정 대기다 |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — `docs/` 212개 98,440줄. CHANGELOG 455줄에 미출시 절이 둘이다. 제품은 아래 절 단계를 먼저 하고 위 절을 한다(`:20`). 두 절이 같은 제품 모양을 다르게 적는 곳이 있다(14-01 b) |
| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | P — 알려진 제한 18줄은 각 항목의 상태(결정 대기·백엔드로 넘김·일부)를 적고, 다운스트림에 적용해 보지 않았다는 것도 적는다(`:91`). 3단계 증상 설명은 틀리다(14-01 a) |
| 6 | 실패 성숙도 | > 다른 영역 | - | - | - |
| 7 | 운영 성숙도 | > 11·13 영역 | - | - | - |
| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2 | O — 문서 검사가 지운 기능을 출력에 적는다(`verify-documentation-readiness.ts:513-518`, `FE-GATE-020.txt:1539`). 매뉴얼 errors.md의 새 오류 문구 5개가 코드에 있다(E-7) |
| 9 | 유지보수 성숙도 | **깊게 봄** | M3 / M2 | E1·E2 | P — 지난 라운드의 "브랜치끼리 문서에서 못 만남"(1105/14-01·14-03)을 목록 모듈 하나로 함께 풀었다. 남은 것: D7 커밋 본문 해시(14-02), performance-evidence의 손으로 적은 26(15 영역), 매뉴얼 04 테스트의 규칙 사본(작음) |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(문서), M0(예제 드릴의 회귀) | E2(FE-GATE-005), E3(14-R1~R4) | P — 문서 테스트 셋이 새로 생겼고 FE-GATE-005에서 돈다. 변이 셋(14-R2·R3·R4)에서 모두 기대한 이유로 실패해, 빈 통과가 아님을 확인했다. 예제 기능 제거 드릴은 이번에 통과했지만(14-R1) 게이트 밖이다(`CHANGELOG.md:93`). 다음에 깨지면 문서 쪽 unit 테스트만 알린다 |
| 11 | 데이터 성숙도 | - 이 영역에 데이터 경계가 없다 | - | - | - |
| 12 | 동시성 성숙도 | - 이 영역에 동시 실행 경로가 없다 | - | - | - |
| 13 | 확장성 | > 11·15 영역 | - | - | - |
| 14 | 성능 성숙도 | > 15 영역 | - | - | D7 기록만 봤다(2.3절) |
| 15 | 보안 성숙도 | > 09 영역 | - | E1 | 매뉴얼 04 4.3의 쿠키 401 연결(`createSessionCookieRejectionHandler`)은 recipe 코드와 같다(`recipes/session-owners/cookie-session-owner.ts:217-222`) |
| 16 | 의존성 성숙도 | 적용(제품에게 템플릿은 의존성) | M2 / M1 | E1 | P — 태그 `v0.2.0` 뒤 두 미출시 절이 태그 없이 쌓였다. 기준점 형식이 둘이다(0929/14-02) |
| 17 | API / Contract 성숙도 | **깊게 봄** | M3 / M2 | E1 | P — 해시 75/75, BREAKING 행 5/5가 꼬리말·코드와 같다. 다섯 단계를 따라 하면 두 제품 모두 맞는 변경이 된다(2.1절). 설명 셋이 틀리다(14-01). 표시 없이 생긴 필수 칸 `notifySessionUnauthenticated`는 영향 받는 곳이 지금 없다 |
| 18 | 배포 성숙도 | > 13 영역 | - | - | - |
| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2 | O — 매뉴얼 04 §3.2 예시를 테스트가 그대로 타입 검사한다(1105/14-02). `FEATURE_OVERRIDES` 문서가 코드와 같다(0929/14-05) |
| 20 | 개발자 경험 | **깊게 봄** | M3 / M3 | E1·E2 | P — 매뉴얼 diff의 명령·경로는 문서 검사를 지나고(FE-GATE-005), 새 오류 문구는 코드에 있다. 매뉴얼만 보는 재실험(X2)은 이번에도 미실시 |
| 21 | Guardrail 성숙도 | 적용 | M3 / M3(§1 문서), M0(CHANGELOG) | E2·E3 | P — 참조 기능 경로가 다시 검사된다. 파일 이름을 바꾸면 매뉴얼 두 줄로 실패한다(1105/14-03, 14-R3). 지운 기능의 예외는 조건부이고 양쪽 방향을 테스트하며, 예외를 끄면 그 테스트가 실패한다(14-R2). CHANGELOG는 일부러 문서 검사 밖이고(`verify-documentation-readiness.ts:165`), 해시를 대조하는 장치가 없다(14-02). 검사 약화는 찾지 못했다(0절) |
| 22 | 추상화 성숙도 | > 09 영역 | - | - | - |
| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 두 미출시 절이 TechLog 백엔드 모양을 다르게 적는다(14-01 b). README 기준점을 옮기는 시점이 두 문장이다(0929/14-02) |
| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P — "부팅이 멈춘다"(14-01 a). 커밋 본문의 옛 해시(14-02). 매뉴얼 04 머리의 "백엔드 `bbe944bd` 기준"(`04-paired-backend-session.md:10`)이 pin `45d2a478`과 다르다. 지난 라운드에 두 커밋 사이 인증 설정 변경이 0줄임을 확인했다. 그대로다 |
| 25 | 조직 확장성 | 적용 | M2 / M1 | E1 | P — 다운스트림 모양을 템플릿 리뷰가 직접 읽어 안내를 맞춘다. 다운스트림 모양 fixture로 안내를 검증하는 장치는 없다(1103/14-02 대안 (B) 미실시) |
| 26 | Ownership 성숙도 | **깊게 봄** | M1 / M1 | E1 | P — 다운스트림 결함 후보 하나가 상태와 함께 처음 기록됐다(`CHANGELOG.md:139`). 받는 곳은 결정 대기다(0929/14-06) |
| 27 | 삭제 가능성 | **깊게 봄** | M3 / M3(참조), M3(예제 문서)·M0(예제 드릴 회귀) | E2(FE-GATE-020·005), E3(14-R1) | P — 참조 기능 삭제는 드릴과 문서 검사를 함께 통과한다(FE-GATE-020). 예제 기능 삭제도 이번에 드릴 17검사를 통과했다(14-R1). 예제 기능을 지운 사본의 문서 검사는 FE-GATE-005가 매번 보지만, 드릴 자체는 어느 게이트에도 없다. 읽는 곳 없는 추적 산출물 13개(0929/14-01) |
| 28 | 회복 가능성 | > 다른 영역 | - | - | 동기화 되돌림(`git revert`, `README.md:419`)은 실행하지 않았다 |
### 4.1 30절 템플릿 기준
| 절 | 판정 | 근거 |
|---|---|---|
| 30.1 최소 구성과 안전한 기본값 | P | 지난 라운드와 같다. 깨끗한 환경 실행은 확인하지 못했다 |
| 30.2 옵션 조합의 수와 검증 책임 | P | 지울 수 있는 템플릿 기능 둘을 한 목록이 관리한다(`removable-template-features.ts`). 두 드릴 모두 이 커밋에서 통과했다(FE-GATE-020, 14-R1). 게이트에서 도는 것은 참조 기능 하나다 |
| 30.3 생성·복사 후 수정 권한 | P | 예제를 지운 제품도 템플릿 문서를 고치지 않아도 된다(1105/14-01). 제품 소유 자리가 없는 템플릿 수정은 결정 대기다(1103/14-02) |
| 30.4 버전과 업데이트 전파 | P | 새 절의 해시·BREAKING 행이 범위와 맞다. 남은 것: 설명 셋(14-01), 커밋 본문 해시(14-02), 다운스트림 적용 실험 없음, 기준점 형식 둘 |
| 30.5 샘플 코드의 대표성 | O | 매뉴얼이 가리키는 참조 기능 경로가 다시 검사된다(1105/14-03) |
| 30.6 도입·유지 비용 | P | 문서 212개 98,440줄. 미출시 절 둘을 함께 받는다. FE-GATE-020 한 번 1,237초(`bbde570-ci/summary.txt`) |
| 30.7 템플릿에서 졸업할 수 있는가 | P | 지난 라운드와 같다. 제품 자리가 없는 실행기 수정(memento `if-match`)이 제품을 템플릿 파일에 묶는다 |
| 30.8 배포 판단에 필요한 최소 증거 | P | "패치 전달": 안내와 두 제품 실제 모양 대조 E1, 적용 실험 없음. "선택 기능 분리": 참조 기능 E2(FE-GATE-020), 예제 기능 E3(14-R1 드릴, 14-R2 변이) |
## 5. 미검증
| 항목 | 이유 | 확인하려면 |
|---|---|---|
| 두 다운스트림의 실제 병합 뒤 게이트 | 제품 repo는 읽기만 했다 | 제품 sync 브랜치에서 두 절을 받고 CHANGELOG만 보고 `check:types`·`check:registries`·`test:unit`까지 |
| tech-log 관리 쓰기가 지금 실행기에서 거절되는지 | 코드 경로를 읽은 추론이다(14-01 c) | tech-log에서 관리 저장 한 번, 또는 `http-management-gateway` 단위 테스트 |
| 두 제품의 `as` 단언이 `responseEnvelope` 누락을 잡는지 | 타입 검사를 돌리지 않았다 | 제품 사본에서 그 줄 없이 `check:types:app` |
| 예제 기능 제거 드릴의 CI env 실행 | 14-R1은 local env다. 어느 게이트도 이 드릴을 돌리지 않는다 | `CI=true`와 workflow env로 같은 명령 1회, 또는 FE-GATE-020에 더하기 |
| 매뉴얼만 보는 기능 추가(X2) | 지난 두 라운드도 하지 않았다 | 깨끗한 clone에서 매뉴얼만 보는 에이전트 1회 |
| 04 §3.3·§4.3 코드 예시 컴파일 | §3.2만 테스트가 본다 | recipe를 `src/bootstrap/`에 복사하고 예시를 붙여 `check:types:app` |
| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` | 새 clone이나 컨테이너에서 README 명령만 |
| README 범위 동기화 두 명령(`README.md:402-403`) | 실행하지 않았다(커밋 본문도 같다) | scratch clone 두 개(이력 공유·비공유)에서 다음 범위를 받아 봄 |
| 목표 설계 문서 본문 전체 | 약 3만 줄. 상태 줄과 검색 결과만 봤다 | `git grep -i -E 'v2|replay|mapper registry'` 후보를 코드와 대조 |
## 6. 실행 기록
정적 확인(노트북, 읽기만):
| ID | 무엇을 | 어떻게 | 결과 |
|---|---|---|---|
| E-1 | 새 절 해시 위치 | `CHANGELOG.md:14-108`의 백틱 해시 76개를 `git rev-parse`, `git merge-base --is-ancestor`로 `bbde570`·`409d72e`·`a793b83`와 대조 | 75개 모두 `bbde570`에서 닿고 `409d72e`에서 안 닿는다. 남은 하나는 기준점 `409d72e`. PR A 셋은 `a793b83` 이력에 있다 |
| E-2 | 범위 커밋과 행 | `git log --no-merges 409d72e..bbde570`(79개)와 인용 해시 비교. 커밋마다 `Refs:`·`BREAKING CHANGE:` 꼬리말을 행의 ID와 대조 | 인용 75, 안 된 4(리뷰 기록·CHANGELOG 커밋). Refs 75/75 일치. `!` 커밋 5 = BREAKING 행 5, 모두 꼬리말 있음 |
| E-3 | 범위 커밋 본문의 해시 | 79+14커밋 본문에서 7~12자리 16진 토큰을 뽑아 이 repo 객체인지, `bbde570`에서 닿는지 | `287dc6f`의 `ab0d4a1`, `7ce9bf1`만 이 이력에 없다(14-02). `d3810a0`·`ef947e5`는 다른 repo |
| E-4 | BREAKING 다섯과 두 다운스트림 | 다섯 커밋의 diff·꼬리말, 위 코드 위치, 두 repo `HEAD`의 `refusedBeforeWrite`·`operationId: "`·`createBoundedPollCoordinator`·`a11y.json`·descriptor 생성 함수를 `git grep`·`git show` | 2.1절 표 |
| E-5 | 두 제품이 고친 템플릿 파일 | 각 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(제품 기능·context 폴더 제외), 파일 이름을 `CHANGELOG.md:130-140`과 대조 | memento A 3·M 23, tech-log A 2·M 38·D 17. CHANGELOG 수와 같다. 추가·수정 파일이 모두 세 분류 중 하나에 있다 |
| E-6 | 새 절의 repo 경로 | 백틱 경로가 `src`·`scripts`·`config`·`tests`·`docs`·`recipes` 등으로 시작하면 존재 확인 | 생성 산출물 `artifacts/tests/a11y.json`, 자리표시자 둘, 백엔드 문서 `docs/fileserver/http-contract.md`(백엔드 pin에 있음)를 빼면 모두 있다 |
| E-7 | 매뉴얼 새 오류 문구 | `docs/manual/reference/errors.md` diff의 새 5행 고정 부분을 `src`·`scripts`에서 `git grep -F` | 모두 있다(`external-contract-runtime.ts:691-695`, `:719`, `scripts/check-registries.ts:166`, `:414`, `scripts/test-sample-removal.ts:492`, `:523`) |
| E-8 | 언어 없는 펜스 안 지울 수 있는 기능 경로 | README와 `docs/`(리뷰·superpowers 제외)에서 언어 없는 펜스 안의 `reference-feature`·`reference-context`·`platform-examples` 줄 | 0건 |
desktop 실행: 이 영역 리뷰어는 desktop에서 아무것도 돌리지 않았다. 읽은 것은 `/tmp/claude-gates/bbde570-ci/`(summary, FE-GATE-005·020 로그), `/tmp/claude-gates/r5/snap/`(verify-documentation 두 파일, lab.txt), 배치 로그 `/tmp/claude-gates/r5/batch/out/R5-14-R*.log`다. 실험은 배치로 요청했다(`scratchpad/r5/requests/14.md`). 오케스트레이터가 2026-11-06 04:36~04:39에 `bbde570`(head `bbde570796b0…`)에서 하나씩, local env로 돌렸다. 항목마다 checkout을 되돌렸고 복구는 모두 `restore=clean`이다. 표의 rc는 로그의 `drill-rc=`·`rc=`·`verify-rc=` 줄이다(항목 끝 `echo`의 rc는 늘 0).
| 요청 | 명령 | 변이 | 발견 | 결과 |
|---|---|---|---|---|
| 14-R1 | `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` (local, load 2.76) | - | 1105/14-01 완료 기준 셋째 | `drill-rc=0`. `platform-examples-feature removal: PASS (17 checks, no fixture IDs)`(`R5-14-R1.log:2198`). 사본에서 `check:types`, lint, `verify:documentation`(지운 기능 `platform-examples-feature` 통지 뒤 `PASS_SCOPED`, `:19-21`), i18n, 디자인 시스템, 아키텍처, 레지스트리, `test:all`, 커버리지, 증거·CI 검사, 빌드가 돌았다(`:5-33`, `:895`, `:2124-2144`). 복구 clean |
| 14-R2 | `node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts` (local) | `requests/14-R2.diff`(지운 기능 예외를 늘 빈 목록으로) | 1105/14-01·14-03 테스트가 빈 통과가 아닌지 | `rc=1`, 2 failed / 2 passed(`R5-14-R2.log:7-10`, `:68`). 실패 둘이 기대한 그 둘이다. "without reference-feature"는 12개 문서의 참조 기능 경로로(`:15-26`), "without platform-examples-feature"는 `starter-experience.md`의 세 경로로(`:46`) `FAIL_UNVERIFIED`. 나머지 둘은 통과. 대조군 `FE-GATE-005.txt:104` 4건 통과. 복구 clean |
| 14-R3 | `corepack pnpm verify:documentation` (local) | `requests/14-R3.diff`(`reference-http-gateway.ts` 이름 변경 + import 한 줄) | 1105/14-03 완료 기준 앞 절반 | `verify-rc=1`. `docs/manual/01-add-a-feature.md`와 `docs/architecture/backend-api-and-server-state-contract.md`가 옛 경로를 적는다고 `FAIL_UNVERIFIED (failed: document references)`(`R5-14-R3.log:4-8`). 대조군 `verify-documentation.local.txt` `PASS_SCOPED`. 복구 clean |
| 14-R4 | `node scripts/run-vitest.ts run tests/unit/manual-paired-backend-settings.test.ts` (local) | `requests/14-R4.diff`(매뉴얼 04 §3.2 두 행의 `defaultValue: null` 삭제) | 1105/14-02 테스트가 매뉴얼을 실제로 읽는지 | `rc=1`, 1 failed. typecheck 단언에서 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`(`R5-14-R4.log:17-19`). 대조군 `FE-GATE-005.txt:94` 통과. 복구 clean |
판정 규칙(변이는 대조군이 통과하고 변이가 기대한 이유로 실패해야 검사를 증명한다)을 세 변이 모두 채웠다.
요청하지 않은 것과 이유: 참조 기능 제거 드릴은 FE-GATE-020(CI env) 로그가 대신한다. `verify:documentation` 두 환경은 오케스트레이터 공유 실행이 있다. CHANGELOG 테스트 셋은 FE-GATE-005 로그가 있다. 두 다운스트림 실행은 제품 repo를 바꾸므로 하지 않았다.
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 14-01 | Low·P2 | 확인된 결함 | 새 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림과 다르다: 3단계 "부팅이 멈춘다"(실제는 기능 라우트 첫 진입), 1단계 TechLog를 "감싸지 않는 백엔드"로 적음, 2단계가 `requiresIdempotencyKey` 재계산을 말하지 않음 | `CHANGELOG.md:24-26`, `src/features/installed-contract-contributions.ts:93-111`, `src/contracts/server-state.ts:303-311`, tech-log `studio-management-server-state.ts:209`, `tech-log-management-contract-contribution.ts:143` |
| 14-02 | Low·P3 | 확인된 결함 | D7 커밋 `287dc6f` 본문이 `bbde570` 이력에 없는 다시 쓰기 전 해시 `ab0d4a1`·`7ce9bf1`을 가리키고, CHANGELOG·커밋 본문 해시를 대조하는 장치가 없다 | `git show 287dc6f`, `scripts/verify-documentation-readiness.ts:165` |
@@ -0,0 +1,179 @@
# 영역 15 — 성능 실측·최적화
> 검토일 2026-11-06 · 기준 `bbde570`(PR B 끝, `fix/maturity-review-2026-11-05-b`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/schemas/lab-performance.schema.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,lab-performance,vite-build-inputs}.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/test-performance.ts`, `scripts/test-feature-scaffold.ts`(드릴의 기록 재작성 부분), `tests/unit/{feature-shape-growth,performance-budgets,lab-performance,vite-build-inputs,product-feature-selection-build}.test.ts`, `docs/operations/performance-evidence.md`, `vite.config.ts`, 15-01·15-05가 고친 `src/presentation/examples/platform-overview-page.tsx`·`src/presentation/styles/theme/base.css`, 시각 골든 5장(`tests/visual/__snapshots__/`), CHANGELOG 미출시 절의 성능 행
> 깊게 본 관점: 21, 14, 10, 13
> 렌즈: D7(초기 JS 예산 204,800 → 206,848 B)이 검사를 약하게 했나, 합칠 때 다시 쓴 기록(`0fee3fe`)이 빌드와 같은가, 1105/15-01~15-05와 이월 4건이 완료 기준까지 갔나
> 영역 판정(35.8): **조건부 사용 가능.** 번들 게이트(FE-GATE-012, merge)와 생성 기능 드릴(FE-GATE-020)이 CI env에서 통과한다. lab(FE-GATE-026)은 오케스트레이터 로컬 실행에서 통과한다. 조건은 둘이다. (1) 템플릿 + 생성 기능 둘의 여유가 1,383 B다. 다음 템플릿 변경이 약 1.4 KB를 쓰면 드릴이 다시 넘는다. 그때 줄일지 올릴지 정한 규칙이 없다(새 15-01). (2) lab은 플랫폼 화면과 예제 기능 화면 하나만 잰다. `create:feature`가 만드는 화면은 모두 세션이 필요해서, 예제를 지운 제품에서는 기능 라우트를 하나도 재지 않고 통과한다(1105/15-04 일부).
## 0. 결론
- **D7은 검사를 약하게 했다. 다만 이유가 기록된 결정이고 사용자 영향은 작다.** 옛 예산이면 `bbde570`에서 FE-GATE-012는 642 B 남기고 통과하고, FE-GATE-020 드릴은 665 B 넘어 실패한다(CI env). 새 예산에서는 템플릿 여유 2,690 B, 드릴 여유 1,383 B다. 필요했던 폭은 665 B인데 2,048 B를 올렸다. 결정 기록은 올린 뒤 여유(2,737 B, 1,385 B)를 적지만, 왜 그만큼 남기는지와 다시 내릴 조건은 적지 않는다. 폭의 근거는 "202 KiB"라는 값뿐이다. 새 발견 15-01(Low·P3).
- **D7이 건드리지 않은 것.** 기능 1 KiB·context 512 B 상한(`tests/unit/feature-shape-growth.test.ts:157-160`), 초기 파일 상한 32(`config/performance/budgets.json:5`), lazy 120 KiB(`:6`), lab LCP·CLS·200 ms(`:9-11`)는 그대로다. 기록 대조 허용치 256 B는 템플릿 여유(2,690 B)와 드릴 여유(1,383 B), 생성 기능 가장 작은 비용(새 context 기본 기능 328 B)보다 작다.
- **합칠 때 다시 쓴 기록(`0fee3fe`)은 빌드와 맞는다.** 기록 204,111 B·27개(`config/scale/feature-shape-ceilings.json:61-66`). CI env 빌드는 204,158 B·27개(FE-GATE-012)로 47 B 차이다. FE-GATE-005의 기록 대조 테스트가 CI env에서 통과한다. 로컬 env에서 측정 스크립트를 다시 돌리면 네 값이 기록과 바이트까지 같다(15-R1). 그러니 `--initial-baseline --write`로 쓴 값이다.
- **lab이 통과한다**(`r5/snap/lab.txt`, 로컬 env, 부하 0.70 → 0.73): LCP 2,032 ms, CLS 0, 상호작용 151 ms(150~153), 대상 화면 직접 진입 CLS 0(5회 모두 0), 기능 라우트 `EXAMPLES_UI` 402 ms(400~408) / 500 ms. 스크롤바를 보이게 띄운 실행이다.
- **지난 발견 10건: 고쳐짐 5, 일부 2, 남음 2, 재발 1, 틀린 발견 0.** 1105/15-02·15-05는 배치로 완료 기준을 실행해 확인했다. 기록보다 +448 B 늘린 빌드에서 기록 대조가 실패했다(15-R2). 1280×720·1366×657과 지연 없음·lab 조건, 18회 모두 첫 화면 layout shift가 0건이다(15-R3). §16과 다르게 본 것은 셋이다. 1103/15-02는 "고침"이 아니라 재발이다(`performance-evidence.md:209-210`이 템플릿 초기 파일을 26개로 적는다. 지금 27개). 1101/15-01은 "남김"이 아니라 고쳐짐이다(완료 기준 충족, 여유 문제는 D7이 정했고 그 판단은 새 15-01). 1101/15-04는 "남김"이 아니라 일부다(SW 실제 대기는 `ce191be`가 없앴다).
- **1105/15-04는 §16.4대로 일부이고, 남은 것이 하나 더 있다.** 요청 두 묶음(결정 대기) 말고도, 생성 기능 라우트는 모두 `session-required`라 lab 대상이 될 수 없다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`).
- **시각 골든 다시 찍기(`e02f252`)는 검사를 약하게 하지 않았다.** 옛·새 PNG를 열어 보니 내용은 같고 내용 폭만 1040 → 1025 px다. compact는 같은 내용이 15 px 좁아져 줄바꿈이 늘었다. FE-GATE-008에서 시각 6건이 통과한다.
- 새 발견: Low 1. P3 1. 구조적 위험 1. High 이상과 P1은 없다. 배치 3건(15-R1~R3)은 모두 기대대로 나왔다. 15-R3의 `clientWidth` 기대 하나만 틀렸다(2절 15-05 행).
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 15(성능 실측·최적화) |
| 커밋·작업 상태·확인 시점 | `bbde570796b0a648bae65c2c0568fca860a3ba4e`. 노트북 worktree(HEAD = 기준, 브랜치 `docs/maturity-review-2026-11-06`, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 2026-11-06 04:05~. 이 문서 하나만 썼다 |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 운영 서빙은 HTTP/2 이상이 전제다(`docs/operations/performance-evidence.md:208`) |
| 필수 요구와 규모·운영 목표 | `config/performance/budgets.json:3-19`: 초기 JS 206,848 gzip B, 초기 JS 파일 32개, lazy 청크 파일당 122,880 B, lab LCP 2,500 ms·CLS 0.1·이름 붙은 상호작용 200 ms·기능 라우트 첫 진입 500 ms. 기능 하나 1 KiB·context 하나 512 B(`tests/unit/feature-shape-growth.test.ts:157-160`). 기록 대조 합계 256 B(`scripts/scale/measure-feature-shape-growth.ts:227`). field p75는 표본 기준 미정이라 설계대로 `FAIL_UNVERIFIED` |
| 실행 환경 | 직접 실행 없음. desktop 기존 증거만 읽었다(모두 `bbde570`). (1) merge 단계 CI env 로그 `desktop:/tmp/claude-gates/bbde570-ci/`: `FE-GATE-005.txt`(unit·coverage), `FE-GATE-006.txt`, `FE-GATE-008.txt`(시각), `FE-GATE-012.txt`(번들), `FE-GATE-020.txt`(드릴). (2) 오케스트레이터 로컬 실행 `desktop:/tmp/claude-gates/r5/snap/`: `build.txt`, `lab.txt`, `base/performance/lab.json`(5회, `generatedAt` 2026-11-05T19:04:05Z). i5-10400F 12 CPU, Node v24.14.0, Chromium 151.0.7922.34. `base/performance/bundle.json`과 `merge/artifacts/performance/bundle.json`은 03:56에 FE-GATE-013 부분 실행의 `build:release-candidate`가 다시 쓴 것으로, `measurements`가 없어 쓰지 않았다. (3) 오케스트레이터 배치 15-R1~R3(`scratchpad/r5/requests/15.md`, 로그 `desktop:/tmp/claude-gates/r5/batch/out/R5-15-R*.log`, 같은 desktop, 부하 2.6~4.4) |
| 읽은 코드·구성 범위 | 머리말 경로. `git log 8a44226..bbde570 -- <이 영역 경로>`의 커밋 10개: `c9aa73f`(15-03), `46359a1`(15-02), `e02f252`(15-05), `138c195`(15-01), `81701ad`(15-04), `f4d5761`(12-04, `vite.config.ts`), `b8d53c9`(합친 커밋, 빌드 입력 목록), `1dda18d`(문서 경로, 영역 14), `0fee3fe`(기록), `287dc6f`(D7). 2026-11-05 README §15·§16.2~16.6, 영역 15 문서, 2026-11-01·11-03 영역 15 문서의 해당 발견. `config/ci/gates.json`의 FE-GATE-005·012·020·026과 stage(`:2240-2272`) |
| 수행한 테스트·실험 | 없음(규칙상 실행 금지). 게이트 로그와 스냅숏으로 판정했다. 시각 골든 5장은 `git show 8a44226:`·`bbde570:`로 꺼내 이미지로 비교했다. 완료 기준을 실행으로 봐야 하는 셋은 배치로 돌렸다: 기록 재측정(15-R1), 256 B 대조 변이(15-R2), 실제 스크롤바 첫 화면 shift(15-R3). 결과는 6절 |
| 확인하지 못한 범위·이유 | 5절 |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/15-performance.md`(기준 `8a44226`). 바이트는 결정적이라 비교한다. 다만 지난 라운드 바이트는 로컬 env, 이번 게이트 로그는 CI env라 build id만큼(수십 B) 다르다. lab 시간은 같은 호스트(i5-10400F)지만 부하가 다르다(지난 2~6, 이번 0.7) |
## 2. 지난 발견 재확인
README §16.4~16.6의 "고침"은 주장으로만 읽었다. 각 발견의 2026-11-05 영역 문서 3절(또는 그 이전 문서) 완료 기준과 `bbde570`의 코드·로그로 다시 판정했다.
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1105/15-01 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다. lab은 그 shift를 보지 못한다 | **고쳐짐** | 요약 전·실패 때도 같은 네 칸과 같은 hint 줄을 그린다(`src/presentation/examples/platform-overview-page.tsx:63-78`, `:439-484`). 컴포넌트 테스트가 요약 전후의 칸 이름·hint 유무가 같은지 본다(`tests/component/starter-platform-overview-page.test.tsx:252`, FE-GATE-006에서 11건 통과). lab이 run마다 대상 라우트를 직접 열어 CLS를 잰다(`scripts/test-performance.ts:230-242`). 판정은 `lab.cls`다(`scripts/lib/performance-budgets.ts:115`). `lab.json`의 `sampling.targetDeepLink.cls` 표본이 0·0·0·0·0이다. 완료 기준 둘(직접 열면 shift 0건, `lab.json`에 직접 진입 CLS가 있음)을 채운다. "0건"은 lab 조건에서 소수 넷째 자리 CLS 0으로 봤다(지난 shift는 0.0046이었다). 남은 위험(셈에 넣지 않음): 직접 진입 CLS 예산이 0.1이라 같은 크기의 shift가 다시 생겨도 lab은 통과하고 값만 남긴다(`138c195` 본문이 적음). 기능 라우트 클릭의 CLS는 재지만 버린다(`test-performance.ts:262-273`) |
| 1105/15-02 | 기록 대조 허용 오차 1%(2,029 B)가 남은 여유보다 크다 | **고쳐짐** | 합계 허용치가 256 B 상수다(`scripts/scale/measure-feature-shape-growth.ts:219-227`, 판정 `:235-248`). 기능·context 10%, 파일 수 정확은 그대로다. 단위 테스트가 48 B·200 B 차이는 같음, 300 B 증가·1,500 B 차이는 다름으로 고정한다(`tests/unit/feature-shape-growth.test.ts:175-206`). FE-GATE-005(CI env)에서 7건 통과(`FE-GATE-005.txt:18`). 256 B는 지금 여유보다 작다: 템플릿 2,690 B, 드릴 1,383 B(CI env). CI 빌드와 기록의 차이는 47 B라 CI에서 실제 변경에 쓸 수 있는 폭은 약 209 B다. 완료 기준 "초기 JS를 300 B 늘린 템플릿 변경에서 기록을 다시 쓰기 전까지 `test:unit`이 실패한다"를 15-R2(CI env)가 확인했다. entry에 문자열을 넣어 빌드가 204,158 → 204,606 B(+448 B)가 되자 기록 대조 1건이 `gzipBytes: record 204111, build 204606`으로 실패했다(`feature-shape-growth.test.ts:165`). 기능·context 비용 단언(766 B·221 B)과 나머지 6건은 통과했다. 변이 없는 같은 명령은 `FE-GATE-005.txt:18`에서 통과한다 |
| 1105/15-03 | 측정용 빌드 입력 목록이 두 파일에 있다 | **고쳐짐** | 목록은 `scripts/lib/vite-build-inputs.ts:11-21` 한 곳이다. 두 소비자가 import한다(`scripts/scale/measure-feature-shape-growth.ts:10`, `:104`, `tests/unit/product-feature-selection-build.test.ts:11`, `:39`). `git grep "const BUILD_INPUTS"`는 0곳이다(목록 이름은 `VITE_BUILD_INPUTS`). 새 테스트가 `vite.config.ts`의 상대 import 그래프가 목록 안에 있는지 본다(`tests/unit/vite-build-inputs.test.ts:58-71`). 합칠 때 `b8d53c9`가 12-04의 새 import(`vite.config.ts:9`)를 목록에 더했다(`vite-build-inputs.ts:19`). FE-GATE-005에서 `vite-build-inputs` 2건, `product-feature-selection-build` 1건, `feature-shape-growth` 7건 통과. **`c9aa73f`에 접은 변경은 약해진 검사가 아니다.** 소비자 목록을 있는 파일로 거르는 것(`vite-build-inputs.test.ts:19-22`)은 참조 기능을 지운 사본(FE-GATE-020)에서 측정 스크립트가 없기 때문이다. `8a44226`에는 이 테스트가 아예 없었다. 템플릿에서 측정 스크립트가 없어지면 `feature-shape-growth.test.ts`가 import에서 실패한다. 남은 틈(셈에 넣지 않음): 소비자 파일을 옮기면 (1)번 검사가 그 파일을 조용히 뺀다. 그래프는 정규식이라 동적 import·alias를 못 본다(커밋 본문이 적음) |
| 1105/15-04 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 어느 게이트도 재지 않는다 | **일부** | 고친 것: 설치된 기능이 가진 첫 공개 내비게이션 라우트를 고른다(`scripts/lib/lab-performance.ts:55-68`). run마다 같은 시계로 잰다(`scripts/test-performance.ts:262-273`). 예산 500 ms(`config/performance/budgets.json:12`), 판정(`scripts/lib/performance-budgets.ts:116-118`), 자가 검사 fixture(`test-performance.ts:381-393`). 단위 테스트가 커밋된 예산을 읽어 406 ms 통과·516 ms 실패를 고정한다(`tests/unit/performance-budgets.test.ts:106-136`). `lab.json`: `EXAMPLES_UI` 400·400·403·402·408, 중앙값 402 ms. 완료 기준(`lab.json`에 기능 라우트 시간과 표본)을 채운다. **남은 것 둘.** (1) 진입은 여전히 요청 두 묶음이다. 결정 대기(`docs/operations/performance-evidence.md:120-123`, `CHANGELOG.md:92`). (2) `create:feature`가 만드는 라우트는 목록·쓰기 모두 `session-required`다(`scripts/create-feature.ts:578`, `scripts/create-feature-write-slice.ts:130`). 공개 라우트는 예제 기능 `platform-examples-feature`뿐이고, 이 기능은 지울 수 있다(`scripts/lib/removable-template-features.ts:47-52`). 예제를 지운 제품에서는 `labFeatureRoute`가 null이고, lab은 `measured: false`로 남기고 통과한다(`performance-budgets.ts:117`). 15-04가 근거로 든 "다운스트림의 화면은 모두 기능 라우트다"가 그대로 남는다. `81701ad` 본문은 "생성 기능의 목록 라우트는 lab 대상이 되지 않는다"고 적었다. 문서(`performance-evidence.md:110-114`)는 그 결과(제품 화면을 재지 않음)를 말하지 않는다 |
| 1105/15-05 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다. 게이트는 스크롤바를 숨겨 못 본다 | **고쳐짐** | `:root`에 `scrollbar-gutter: stable`(`src/presentation/styles/theme/base.css:6-11`). lab은 `--hide-scrollbars`를 빼고 띄운다(`scripts/lib/lab-performance.ts:33-35`, `scripts/test-performance.ts:255`). `lab.json`의 `context.browser.scrollbars`가 `"visible"`이고(`test-performance.ts:303-307`), 그 실행에서 `/` CLS가 5회 모두 0이다(1280×720, lab 조건). 단위 테스트가 실행 옵션과 CSS 줄을 본다(`tests/unit/lab-performance.test.ts:123-133`). 완료 기준은 1280×720과 1366×657, 지연 없음과 lab 조건이다. 15-R3(지난 라운드 15-R2와 같은 스크립트, 스크롤바 보임)에서 세 창 × 두 조건 × 3회 = 18회 모두 layout shift 0건이다. 지난 라운드 `8a44226`에서는 같은 스크립트로 1280×720·1366×657 12회 모두 shift 1건(0.00023·0.00022, header 세션 영역 15 px 이동)이었다. 내 요청의 기대 하나는 틀렸다. `document.documentElement.clientWidth`는 지금도 홈이 그려지는 프레임에 1280 → 1265, 1366 → 1351로 바뀐다(지연 없음 396~415 ms, lab 조건 2,023~2,041 ms). 1920×960은 1920 그대로다. 그래서 이 값은 실제 스크롤바가 생겼는지만 보여 주고, 비어 있는 gutter는 빼지 않는 것으로 보인다(추론, 따로 재지 않음). 스크롤바를 숨긴 시각 골든의 내용 폭이 1040 → 1025 px로 줄어든 것이 gutter가 처음부터 자리를 잡는다는 근거다. 판정은 layout shift 기록으로 했다. **합칠 때 다시 찍은 골든 5장(`e02f252`)**: 옛·새 PNG를 비교했다. 플랫폼 구성·상태 화면·갤러리는 같은 내용에 폭만 1040 → 1025 px, wide 셸은 같은 1440×900, compact는 390 px 안의 내용 폭이 15 px 줄어 줄바꿈이 늘고 높이가 1297 → 1377 px다. 다른 그림 변화는 보지 못했다. FE-GATE-008에서 시각 6건 통과. 남은 위험(셈에 넣지 않음): lab CLS 예산 0.1이라 0.0002 shift가 다시 생겨도 통과한다(`e02f252` 본문). compact 골든은 overlay 스크롤바를 쓰는 휴대폰보다 15 px 좁게 그린다. 열린 drawer의 가림막이 gutter 15 px를 덮지 않는다(골든에 보인다, `e02f252` 본문). 일반 스크롤바 브라우저에서 내용이 짧은 화면이면 그 자리가 어둡게 되지 않은 띠로 남는다(추론, 재지 않음) |
| 1103/15-02 | 성능 기준선 숫자가 현재 빌드와 다르다 | **재발** | §16.5는 "고침(`832774f`)"이다. `832774f`는 11-03 CHANGELOG 절의 파일 상한(26 → 32)을 고쳤다. 그 절(`CHANGELOG.md:207`, `:317`)은 그 범위 끝(`8a44226`)의 값이라 지금 숫자와 달라도 세지 않는다. 그러나 살아 있는 문서 `docs/operations/performance-evidence.md:209-210`이 "상한은 템플릿 그대로의 수(26)에 6을 더한 32다"라고 적는다. 지금 템플릿은 27개다(기록 `config/scale/feature-shape-ceilings.json:63`, FE-GATE-012 `27 / 32 files`). `0fee3fe`가 기록을 27로 바꾸며 이 문장을 고치지 않았다. 지난 라운드가 "손으로 적었다(지금은 맞다)"고 적어 둔 바로 그 문장이다. 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시 어긴다. 바이트 쪽(기록 한 곳, 256 B 대조)은 지켜진다 |
| 1101/15-01 | 초기 JS 여유가 작고, 넘었는지 보는 검사가 release에서만 돈다 | **고쳐짐** | §16.6은 "남김(예산을 먼저 정해야 한다)"이다. 완료 기준 둘을 채운다. (1) 예산 + 1 B가 merge에서 실패한다: FE-GATE-012가 merge stage에 있다(`config/ci/gates.json:2257`). `check:bundle` 자가 fixture `initial-js-over-budget`(`scripts/check-bundle.ts:62`)와 `check-bundle-output.test.ts` 5건이 FE-GATE-005에서 통과한다. (2) 문서의 기준선·여유가 측정과 같다: 문서는 숫자 대신 기록을 가리키고(`performance-evidence.md:22-25`, `:42-43`), 기록은 CI 빌드와 47 B 차이다. 지난 라운드가 남겨 둔 "여유가 작다"는 D7이 예산을 정하며 답했다. 그 결정이 검사를 얼마나 약하게 했는지는 새 15-01에서 본다 |
| 1101/15-03 | 예산이 CSS를 빼고, lazy는 파일 단위만 본다 | **남음** | `scripts/check-bundle.ts:38-47`은 초기 JS 파일만 더한다. 문서도 그렇게 적는다(`performance-evidence.md:83`). CSS `index-Dv15Src3.css` 8.81 kB gzip(vite 출력, `FE-GATE-012.txt`). 라우트 진입 하나의 lazy 합계를 보는 예산은 없다. 새 기능 라우트 예산(500 ms)은 시간 검사라 바이트 합을 대신하지 않는다 |
| 1101/15-04 | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | **일부** | §16.6은 "남김"이다. SW 테스트의 실제 5초 대기는 `ce191be`(1101/10-07)가 가짜 시계로 바꿨다. `service-worker-runtime.test.ts` 64건이 320 ms다(`FE-GATE-005.txt:119`). 남은 것: `tests/setup.ts:1-2`가 여전히 모든 파일에 jest-dom·RTL을 싣는다. 자식 프로세스를 띄우는 파일이 unit에 남는다(`documentation-readiness` 22.5초, `product-extension-typecheck` 21.9초, `FE-GATE-005.txt:180`, `:172`). FE-GATE-005가 `test-unit`과 `test-coverage`를 둘 다 돈다(`config/ci/gates.json:1842-1848`). CI env unit: 208파일 3,056건 28.45초, setup 합 50.73초(`FE-GATE-005.txt:312-315`). coverage 실행 332파일 85.50초(`:781-784`) |
| 0929/11-04 | lab 판정이 호스트 부하로 뒤집힌다 | **남음** | `scripts/test-performance.ts:244`, `:257`, `:275`, `:300`은 부하를 기록만 한다. 이번 lab은 부하 0.70 → 0.73에서 표본 범위가 3 ms(상호작용)·8 ms(기능 라우트)다. 노출은 넓어졌다. 새 기능 라우트 예산의 여유가 98 ms(24%)로, 기존 상호작용 예산의 여유 49 ms(25%)와 같은 크기의 판정이 하나 더 생겼다. `81701ad` 본문이 이 위험을 적었다. 2026-09-27 기록(부하 11~17)에서는 상호작용이 30~60% 늘었다(`performance-evidence.md:133-138`) |
### 2.1 D7 — 예산 상향이 무엇을 통과시키나
| 상태(`bbde570`, CI env) | 초기 JS gzip B | 파일 / 상한 | 옛 예산 204,800 | 새 예산 206,848 |
|---|---:|---|---|---|
| 템플릿 그대로(FE-GATE-012, `FE-GATE-012.txt`) | 204,158 | 27 / 32 | 통과, 여유 642 | 통과, 여유 2,690 |
| 드릴: + `scaffold-feature`(새 context) + `scaffold-write-feature --with-create --keyed`(새 context)(`FE-GATE-020.txt:6206`, 기록 `:4414`) | 205,465 | 27 / 32 | **665 B 초과로 실패** | 통과, 여유 1,383 |
| 드릴에서 `scaffold-feature`를 지운 뒤(제거 드릴의 기록, `FE-GATE-020.txt:6309`) | 205,137 | 27 / 32 | 337 B 초과 | 통과 |
| 로컬 기록(`0fee3fe`, `feature-shape-ceilings.json:61-66`) | 204,111 | 27 / 32 | 여유 689 | 여유 2,737 |
- **통과시키는 것.** (1) PR B의 +1,184 B. 옛 예산이면 드릴이 실패한다. (2) 그 위에 템플릿이 1,383 B 더 늘어도 드릴이 통과하고, 2,690 B까지 FE-GATE-012가 통과한다. 옛 예산에서는 드릴이 이미 실패하고 템플릿 자체는 642 B였다.
- **그래도 막는 것.** 템플릿 변경이 256 B를 넘게 늘리면 기록 대조가 `test:unit`(FE-GATE-005, merge)에서 실패한다. 다만 `--initial-baseline --write`로 기록을 다시 쓰면 풀린다. 이번 라운드가 그렇게 했다(`0fee3fe`). 그래서 기록은 diff에 흔적을 남기는 알림이지 멈춤이 아니다. 멈춤은 예산뿐이다.
- **생성 기능 비용**(CI env, 위 표의 차): `--with-create --keyed` 기능(새 context) 979 B, 기본 기능(새 context) 328 B. 템플릿 여유 2,690 B에는 쓰기 기능 둘이 들어간다. D7의 "기능 셋이 들어간다"(README 2026-11-05 §16.2 `:556`)는 참조 모양 기능을 있는 context에 넣을 때(768 B × 3 = 2,304 B)만 맞다. 새 context마다 218 B를 더하면 둘이다.
- **움직이지 않은 것.** 기능 1 KiB·context 512 B 상한(`feature-shape-growth.test.ts:157-160`), 파일 상한 32(`budgets.json:5`), lazy 122,880 B(`:6`), lab 2,500 ms·0.1·200 ms(`:9-11`). 기록의 `perContextGzipBytes`는 233 → 218 B, `files`는 26 → 27이다(정확 대조). 파일 상한의 남은 칸은 6 → 5다.
- **256 B는 여전히 여유 아래다.** 템플릿 2,690 B, 드릴 1,383 B, 가장 싼 생성 기능 328 B, 참조 모양 기능 768 B 모두보다 작다.
- **이유는 구체적이다.** 늘어난 1,184 B를 출처별로 적었고(README 2026-11-05 §16.2 `:548-553`), 합(327 + 293 + 251 + 148 + 165)이 기록 차(202,927 → 204,111)와 같다. 커밋마다 잰 값 자체는 다시 재지 않았다.
- **올린 폭과 재검토 조건은 구체적이지 않다.** 필요한 폭(665 B)의 약 세 배를 올렸다. 폭의 근거는 "202 KiB"뿐이다(`performance-evidence.md:44-53`). 재검토 조건 "예산을 또 넘을 때"는 이번 상향을 만든 조건과 같다. 그때 줄일지 다시 올릴지는 "런타임 검사를 빌드 시점으로 옮기는 것부터 본다"로만 적혀 있다. 08-03 청크를 묶어 약 240 B를 되찾으면 예산을 내릴지도 적혀 있지 않다. 버린 대안의 240 B는 재지 않은 추정이다. 같은 라운드의 lab 기능 라우트 예산은 단위 테스트가 "지금 값 통과, 묶음 하나 더하면 실패"로 묶는데(`performance-budgets.test.ts:106-136`), 초기 JS 예산 값에는 그런 묶음이 없다(테스트의 `initialJsGzipBytes`는 fixture 값뿐, `tests/unit/bundle-artifact-contract.test.ts:30-40`). 새 발견 15-01.
- **근거 추적.** `287dc6f` 본문은 03-01을 `ab0d4a1`, 08-03을 `7ce9bf1`로 적는다. 둘 다 `bbde570`에서 닿지 않는 커밋이다(fixup 전 해시). README §16.2는 닿는 `5c0b37e`·`f849d78`을 적는다. 문서(`performance-evidence.md:53`)는 README를 가리키므로 결정 기록은 따라갈 수 있다.
### 2.2 합칠 때 다시 쓴 기록(`0fee3fe`)
- 바뀐 것은 `initialJavascript` 네 값뿐이다: 202,927 → 204,111 B, 26 → 27개, 기능 768 그대로, context 233 → 218 B(`git show 0fee3fe`). 키 순서와 형식은 `writeInitialBaseline`이 쓰는 모양이다(`measure-feature-shape-growth.ts:334-342`).
- 빌드와 맞는다: CI env 빌드 204,158 B·27개(FE-GATE-012)와 47 B 차이다. 지난 라운드가 적은 build id 차(6 B, 48 B)와 같은 크기다. FE-GATE-005(CI env)의 기록 대조 테스트가 통과한다(256 B, 파일 정확, 비용 10%).
- 스크립트가 쓴 값이다. 15-R1(로컬 env, `--write` 없이)이 `{"gzipBytes":204111,"files":27,"perFeatureGzipBytes":768,"perContextGzipBytes":218}`를 냈다. 기록과 네 값 모두 바이트까지 같다. 기록은 로컬 env 값이고 CI env 빌드는 47 B 크다.
- 드릴(`scripts/test-feature-scaffold.ts:71-94`)은 생성 기능을 더한 뒤 같은 스크립트로 기록을 다시 쓴다. 그래서 드릴 안에서는 256 B 대조가 시험되지 않는다(기록이 정의상 맞음). 드릴이 보는 것은 예산(FE-GATE-012)이다.
## 3. 이번 발견 (36.3)
새 발견 1건: Low 1. P3 1. 구조적 위험 1. High 이상과 P1은 없다.
### 15-01 초기 JS 예산 상향(D7)이 드릴 초과분(665 B)의 세 배를 올렸다. 올린 폭의 근거와 다시 내릴 조건이 없어, 다음 1.4 KB는 어느 merge 게이트도 멈추지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험(약해진 검사, 기록된 결정) |
| 관련 관점 | 21, 14, 13, 5, 10 |
| 근거 | `config/performance/budgets.json:4` 204,800 → 206,848 B(+2,048 B, `287dc6f`). CI env `bbde570`: FE-GATE-012 `initial JS 204158 / 206848 gzip bytes, 27 / 32 files`(`gate-artifacts/FE-GATE-012.txt`), FE-GATE-020 드릴 `initial JS 205465 / 206848`(`FE-GATE-020.txt:6206`). 옛 예산이면 드릴이 665 B 넘는다. 새 예산의 드릴 여유는 1,383 B다. 결정 기록은 올린 뒤 여유(템플릿 2,737 B, 드릴 1,385 B, 로컬 값)를 적지만 왜 그만큼 남기는지는 적지 않는다. 폭의 근거는 "202 KiB"라는 값뿐이다(`docs/operations/performance-evidence.md:44-53`, README 2026-11-05 §16.2 `:540-558`). 재검토 조건 "예산을 또 넘을 때"는 이번 상향의 조건과 같다. 다시 내릴 조건이 없다. 줄이기 대안의 240 B는 재지 않은 추정이다(`287dc6f` 본문). 같은 라운드의 lab 기능 라우트 예산은 단위 테스트가 커밋된 값을 읽어 묶는다(`tests/unit/performance-budgets.test.ts:106-136`). 초기 JS 예산 값을 묶는 테스트는 없다(`tests/unit/bundle-artifact-contract.test.ts:30-40`은 fixture 값). 기록 대조는 다시 쓰면 풀린다(`0fee3fe`). 커밋 본문의 해시 `ab0d4a1`·`7ce9bf1`은 `bbde570`에서 닿지 않는다 |
| 발생 조건 | 템플릿 변경(또는 리뷰 조치 묶음)이 초기 JS를 1,383 B 안에서 늘리고 기록을 다시 쓸 때. 이번 라운드의 조치 묶음은 1,184 B를 늘렸다 |
| 영향 | 그 폭은 어느 merge 게이트도 멈추지 않고 기록 diff만 남는다. 그 뒤에 넘으면 같은 결정을 다시 해야 하는데, 줄일지 올릴지 정한 규칙이 없다. 상한을 넘을 때마다 올린 것이 두 번째다(파일 상한 25 → 26 → 32, 바이트 200 → 202 KiB). 1101/15-01이 영향 칸에 "결국 예산을 근거 없이 올리기 쉽다"고 적은 경로다. 이번에는 이유가 적혀 있다. 사용자 영향은 작다. 2,048 B는 lab 조건(200 KB/s)에서 다운로드 약 10 ms다(계산, 재지 않음). lab LCP는 2,032 / 2,500 ms다 |
| 심각도·우선순위 | Low · P3 — 결정이 기록돼 있고 사용자 피해가 거의 없다. 남는 것은 폭의 근거와 되돌림 규칙이다. 템플릿 예산을 그대로 복사한 제품은 merge로 함께 올라간다(CHANGELOG `:56`이 "그대로 두거나 같은 이유로 올린다"고 안내) |
| 통제·증거 | 목표 M3(예산 값이 정한 여유 규칙에 묶여, 규칙 밖 상향이 테스트에서 걸림) / 확인 M1(문서의 이유·재검토 조건) · E2(FE-GATE-012·020 로그) + E1 |
| 확실성과 남은 가정 | 바이트는 CI env 로그와 15-R1(로컬 기록과 같음)이다. 10 ms는 계산이다. 다음 라운드 조치가 다시 1.4 KB를 쓸지는 추론이다(이번 라운드 1,184 B) |
| 결정의 근거 | 확인된 사실: 늘어난 1,184 B의 출처 표와 합이 맞는다. 기록된 의도: 라운드 중간의 설계 변경을 피하고, 13-03(zod 약 7 KB) 때 다시 본다. 리뷰어 추론: 665 B만 올렸으면 드릴 여유가 0이라 다음 변경 하나로 다시 넘는다. 여유가 필요했던 것은 맞다. 얼마가 필요한지가 적혀 있지 않다 |
| 이해 비용 | 다음 담당자는 예산을 넘었을 때 "올린다"와 "줄인다" 중 무엇이 규칙인지 문서에서 알 수 없다. 남은 여유를 "템플릿이 더 쓸 몫"과 "다운스트림 기능 몫"으로 나눈 기록도 없다 |
| 최소 개선 방향 | 예산을 "템플릿 기록 + 정한 여유"로 적는다. 예: 생성 기능 둘(드릴) + 템플릿 몫 N B. 그 수를 `performance-evidence.md`에 숫자로 둔다. 원하면 lab 기능 라우트 예산처럼 단위 테스트가 `budgets.json` 값과 기록의 차를 그 범위로 묶는다. 템플릿 몫을 다 쓰면 먼저 줄이는 것(08-03 청크 묶기, 런타임 검사 이동)을 재고, 줄여서 되찾은 만큼 예산을 내릴지도 적는다 |
| 대안 비교 | (a) 현상 유지: 다음에 넘을 때 다시 결정한다. (b) 여유 규칙을 숫자로 적기(권장, 문서 몇 줄). (c) (b) + 테스트로 묶기: 올리려면 테스트도 바꿔야 해서 diff에 드러난다. 테스트 하나. (d) 예산을 드릴 + 256 B(약 205,721 B)로 되돌리기: 다음 템플릿 변경마다 넘는다. (e) 줄이기: 08-03 청크(약 240 B, 추정)와 런타임 검사 이동. 측정이 먼저다 |
| 단순화의 보존 조건 | 드릴(생성 기능 둘)이 예산 안에 든다. 기록 대조 256 B. 초기 파일 상한 32 |
| 비용·부작용 | (b)는 문서. (c)는 테스트 하나와, 예산을 바꿀 때 테스트 한 줄 |
| 재검토 조건 | field p75 LCP 데이터가 생기면 예산 근거를 field로 옮긴다. 1103/13-03(zod)을 정할 때 |
| 완료 기준 | 문서에 여유의 크기와 나눈 몫이 숫자로 있다. (c)를 고르면 `initialJsGzipBytes`를 그 범위 밖으로 올리는 변이에서 `test:unit`이 실패한다 |
| 검증 방법 | (c): 예산 값 변이로 그 테스트를 돌린다 |
| 담당·기한·상태 | 결정권자: 메인 세션(D7을 정함) · 미정 · 신규 |
## 4. 28개 관점 판정 (36.2)
표기: O 충족 / P 부분 충족 / X 미충족 / ? 미검증 / - 적용 제외 / > 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 일부 적용(성능 스크립트) | M2 / M2 | E1, E2 | **O** — 판정기(`performance-budgets.ts`)에 새 지표가 타입으로 들어갔다(`:66-89`). lab 자가 fixture에 기능 라우트 초과가 더해졌다(`test-performance.ts:381-393`). 이 영역 테스트가 FE-GATE-005에서 모두 통과한다 |
| 2 | 구조적 성숙도 | 일부 적용(청크 구성) | M3 / M3 | E2 | **O** — 초기 파일 27개. 늘어난 하나는 08-03의 `navigation-policy` 공유 청크다(`0fee3fe` 본문). 생성 기능 둘을 더해도 27개 그대로다(FE-GATE-020) |
| 3 | 변경 용이성 | 적용 | — / — | E1, E2 | **P** — 빌드 입력 목록이 한 곳이 됐다(1105/15-03). 생성 쓰기 기능 둘이 예산 수정 없이 들어간다. 셋째부터는 결정이 필요하다(2.1절) |
| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | **P** — 문서가 템플릿 초기 파일을 26개로 적는다(1103/15-02 재발). 예산을 넘을 때의 규칙이 없다(15-01). lab CLS 예산 0.1이 작은 shift를 값으로만 남긴다는 점을 알아야 0의 뜻을 안다 |
| 5 | 위험 가시성 | 적용 | M3 / M2 | E2, E3 | **P** — lab이 직접 진입 CLS·기능 라우트·스크롤바를 남긴다. lab은 여전히 release 단계만이다(`config/ci/gates.json:2271`). 예제를 지운 제품에서는 기능 라우트가 `measured: false`로 통과한다(1105/15-04 일부) |
| 6 | 실패 성숙도 | 다른 영역(06·09) | — | — | **>** |
| 7 | 운영 성숙도 | 일부 적용 | M2 / M2 | E3 | **P** — `lab.json`에 스크롤바, 직접 진입, 기능 라우트 표본, 부하가 남는다. field는 설계대로 `FAIL_UNVERIFIED` |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | **O** — 기록 대조 실패가 잰 값과 고칠 명령을 말한다(`feature-shape-growth.test.ts:161-165`). lab 실패가 기능 라우트 표본을 말한다(`test-performance.ts:410-418`) |
| 9 | 유지보수 성숙도 | 적용 | M3 / M2 | E1, E2 | **P** — 바이트 기록은 한 곳이고 256 B로 대조한다. 손으로 적은 파일 수(26)가 다시 낡았다(1103/15-02 재발) |
| 10 | 테스트 성숙도 (깊게) | 적용 | M3 / M3 | E2 | **P** — FE-GATE-005(CI env): `feature-shape-growth` 7건, `check-bundle-output` 5건, `build-environment-bundle` 2건, `product-feature-selection-build` 1건, `lab-performance` 9건, `performance-budgets` 5건, `vite-build-inputs` 2건 통과. 시각 6건 통과(FE-GATE-008), 다시 찍은 골든은 gutter 폭만 다르다. 256 B 대조는 실제로 +448 B 늘린 빌드에서 실패한다(15-R2, 변이 실험 E3). 빠른 계층 시간은 일부만 줄었다(1101/15-04) |
| 11 | 데이터 성숙도 | 적용 제외 | — | — | **-** 이 영역에 저장 데이터가 없다 |
| 12 | 동시성 성숙도 | 다른 영역(03·05·12) | — | — | **>** 실행 격리 출력 경로(`vite.config.ts:173-189`)는 12-04, 오케스트레이터 몫 |
| 13 | 확장성 (깊게) | 적용 | M3 / M3 | E2 | **P** — 생성 기능 비용(CI env): 쓰기 기능 979 B, 기본 기능 328 B(새 context). 드릴 뒤 여유 1,383 B. 여유는 결정으로 생겼고 규칙이 없다(15-01) |
| 14 | 성능 성숙도 (깊게) | 적용 | M3 / 번들 M3(merge), lab M3(release) | E2, E3 | **P** — 번들 204,158 / 206,848 B. lab PASS: LCP 2,032 ms, CLS 0, 상호작용 151 ms, 직접 진입 CLS 0, 기능 라우트 402 / 500 ms. 진입 두 묶음 그대로(15-04). CSS·라우트 합 예산 없음(1101/15-03). field 미검증 |
| 15 | 보안 성숙도 | 다른 영역(13) | — | — | **>** zod advisory 갱신(약 +7 KB, 1103/13-03)은 지금 여유 2,690 B로도 들어가지 않는다. D7은 이 결정을 하지 않는다 |
| 16 | 의존성 성숙도 | 일부 적용 | M2 / M3 | E1 | **O** — react-router 운영 빌드 별칭은 그대로다(`vite.config.ts:156-171`) |
| 17 | API / Contract 성숙도 | 다른 영역(07) | — | — | **>** |
| 18 | 배포 성숙도 | 적용 | M3 / M3 | E2, E3 | **O** — FE-GATE-012 merge, FE-GATE-026 release. 이번 lab은 로컬 env 실행이다(CI env release 실행은 없음, 5절) |
| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | **O** — 예산은 `budgets.json` 한 곳, 기록은 `feature-shape-ceilings.json` 한 곳, 빌드 입력은 `vite-build-inputs.ts` 한 곳 |
| 20 | 개발자 경험 (깊게) | 적용 | M2 / M2 | E1, E2 | **P** — 생성 명령이 기록 재작성을 안내하고 드릴이 그대로 따른다(`scripts/test-feature-scaffold.ts:71-94`). 문서의 파일 수가 틀렸다. 예산을 넘을 때 할 일이 정해져 있지 않다 |
| 21 | Guardrail 성숙도 (깊게) | 적용 | M3 / M3(대조·lab), M1(예산 값) | E2 | **P** — 기록 대조가 1% → 256 B로 조여졌다. lab이 스크롤바·직접 진입·기능 라우트를 본다. 예산 자체는 넘자 올렸고 폭의 규칙이 없다(15-01) |
| 22 | 추상화 성숙도 | 다른 영역(16) | — | — | **>** |
| 23 | 일관성 | 일부 적용 | — | E1 | **P** — 빌드 입력 목록은 하나가 됐다. lab만 스크롤바를 보이게 띄우고 다른 Playwright 게이트는 숨긴다(문서가 적음, `performance-evidence.md:125-129`) |
| 24 | 네이밍 / 의미 성숙도 | 일부 적용 | — | E2 | **P** — react-router 청크는 여전히 자동 이름(`chunk-3WDNQUW5`)이다. 문서는 청크 이름으로 판단하지 않는다고 적는다(`performance-evidence.md:57`) |
| 25 | 조직 확장성 | 다른 영역(12·16) | — | — | **>** 기능 브랜치 둘이 기록 같은 줄에서 충돌하는 것은 1105/16-01(결정 대기, CHANGELOG `:97`) |
| 26 | Ownership 성숙도 | 다른 영역(14) | — | — | **>** 예산 결정은 다운스트림 몫이라고 문서에 있다(`performance-evidence.md:17-20`) |
| 27 | 삭제 가능성 | 다른 영역(14) | — | — | **>** 예제 기능을 지우면 lab 기능 라우트가 사라진다(1105/15-04 일부의 원인) |
| 28 | 회복 가능성 | 다른 영역(06) | — | — | **>** |
## 5. 미검증
| 범위 | 이유 | 확인 방법 |
|---|---|---|
| `clientWidth`가 빈 stable gutter를 빼지 않는다는 해석 | 15-R3은 layout shift 0건과 폭 변화를 같이 보였다. 원인은 재지 않았다 | `getBoundingClientRect()`로 `main`·header 폭을 프레임마다 기록 |
| gutter를 지운 변이에서 15-R3 스크립트가 shift를 다시 잡는지 | 지난 라운드 `8a44226`(gutter 없음)의 결과만 있다 | `base.css`의 `scrollbar-gutter` 줄을 지운 변이로 15-R3 재실행 |
| 대상 화면 직접 진입 shift의 지연 없음·Fast 3G 조건 | lab은 lab 조건만 잰다. 구조 수정과 컴포넌트 테스트로 판단했다 | 지난 라운드 `r4-15-platform-shift.mjs` |
| D7의 커밋별 증가량(327·293·251·148·165 B) | 주장으로만 읽었다. 합이 기록 차와 같은 것만 확인했다 | 커밋마다 `--initial-baseline` |
| 08-03 청크를 묶어 되찾는 바이트(약 240 B 추정) | 누구도 재지 않았다 | `vite.config.ts` 청크 그룹 변이 + `check:bundle` |
| CI env의 lab | FE-GATE-026은 release 단계라 merge 로그에 없다. `lab.txt`는 로컬 env다 | `CI=true` lab 1회 |
| 세션이 필요한 기능 라우트의 첫 진입 시간 | lab에 세션이 없다 | demo 세션을 붙인 lab |
| 시각 골든의 CI 러너 재현 | desktop에서만 통과를 봤다(영역 11) | CI 러너의 FE-GATE-008 |
| drawer 가림막이 덮지 않는 gutter 띠 | 골든(스크롤바 숨김)에서만 봤다. 일반 스크롤바·짧은 화면은 재지 않았다 | 일반 스크롤바 Chromium에서 짧은 화면 + drawer 스크린숏 |
| firefox·webkit의 lab 수치 | lab은 Chromium만이다 | — |
| field CLS·INP | 입력이 없다(설계대로 `FAIL_UNVERIFIED`) | — |
## 6. 실행 기록
이 리뷰어는 아무것도 실행하지 않았다(규칙). 아래 셋은 오케스트레이터 배치가 돌렸다(요청 `scratchpad/r5/requests/15.md`, 2026-11-06 04:39~04:40, 한 번에 하나, 항목마다 checkout을 되돌림). 패치는 `scratchpad/r5/a15/`에 있고 `bbde570`에 `git apply --check`로 맞는 것을 확인했다. 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-15-R{1,2,3}.log`다.
| ID | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 15-R1 | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline` · local | - | 0 | `initial JavaScript: {"gzipBytes":204111,"files":27,"perFeatureGzipBytes":768,"perContextGzipBytes":218}`. 기록(`feature-shape-ceilings.json:61-66`)과 같다. 기대대로. 부하 4.36. `restore=clean` |
| 15-R2 | `node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts` · CIENV | `15-R2.patch`(entry에 압축되지 않는 문자열, 측정상 +448 gzip B) | 1 | 7건 중 1건 실패: `bounds what one more feature and one more context add, and matches the record (15-01)`, `initialJavascript is stale (measured {"gzipBytes":204606,"files":27,"perFeatureGzipBytes":766,"perContextGzipBytes":221})`, `["gzipBytes: record 204111, build 204606"]`(`:165`). 나머지 6건 통과. 기대대로. 변이 없는 대조는 `FE-GATE-005.txt:18`(통과). 부하 4.17. `restore=clean` |
| 15-R3 | `mkdir -p /tmp/claude-gates/r5/exp && corepack pnpm build && node scripts/r5-15-scrollbar.mjs 3 /tmp/claude-gates/r5/exp/15-R3-scrollbar.json` · local | `15-R3.patch`(측정 스크립트만 추가) | 0 | Chromium 151, 스크롤바 보임. 18회 모두 `shifts 0 CLS 0.00000`. 폭: 1280×720은 1280 → 1265(지연 없음 412~415 ms, lab 조건 2,023~2,041 ms), 1366×657은 1366 → 1351(396~402 ms, 2,024~2,026 ms), 1920×960은 1920 그대로. shift 0건은 기대대로다. "창마다 폭 하나"라는 기대는 틀렸다(2절 15-05 행). 상세 `desktop:/tmp/claude-gates/r5/exp/15-R3-scrollbar.json`. 부하 3.92 → 2.63. `restore=clean` |
판정에 쓴 기존 출력(모두 `bbde570`):
| 출력 | 쓴 값 |
|---|---|
| `bbde570-ci/gate-artifacts/FE-GATE-012.txt`(CI env) | `Bundle budget: PASS (initial JS 204158 / 206848 gzip bytes, 27 / 32 files)`. CSS 8.81 kB gzip |
| `bbde570-ci/gate-artifacts/FE-GATE-020.txt`(CI env) | 드릴 `Bundle budget: PASS (initial JS 205465 / 206848 gzip bytes, 27 / 32 files)`(`:6206`). 드릴 기록 `{"gzipBytes":205465,"files":27,"perFeatureGzipBytes":765,"perContextGzipBytes":157}`(`:4414`). 제거 드릴 기록 `{"gzipBytes":205137,...}`(`:6309`). `feature scaffold: PASS (77 checks)` |
| `bbde570-ci/gate-artifacts/FE-GATE-005.txt`(CI env) | 이 영역 unit 7파일 통과(1번째 실행 `:6`, `:18`, `:61`, `:71`, `:86`, `:256`, `:275`). unit 208파일 3,056건 28.45초, setup 50.73초(`:312-315`). coverage 332파일 85.50초(`:781-784`). SW runtime 64건 320 ms(`:119`) |
| `bbde570-ci/gate-artifacts/FE-GATE-006.txt` | `starter-platform-overview-page.test.tsx` 11건 통과(`:15`) |
| `bbde570-ci/gate-artifacts/FE-GATE-008.txt` | 시각 6건 통과(`:343-348`) |
| `r5/snap/lab.txt`, `r5/snap/base/performance/lab.json`(로컬 env, 5회) | `Lab performance: PASS, median of 5 (LCP 2032ms, CLS 0, interaction 151ms [150-153], /examples/platform direct CLS 0 [0-0], feature route EXAMPLES_UI 402ms [400-408])`. 부하 0.70 → 0.73. `scrollbars: "visible"` |
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 15-01 | Low·P3 | 구조적 위험 | 초기 JS 예산 상향(D7)이 드릴 초과분 665 B의 세 배(2,048 B)를 올렸다. 폭의 근거와 다시 내릴 조건이 없어 다음 1,383 B는 어느 merge 게이트도 멈추지 않는다 | `config/performance/budgets.json:4`, `docs/operations/performance-evidence.md:44-53`, `tests/unit/performance-budgets.test.ts:106-136`(대조: 기능 라우트 예산은 묶임) |
@@ -0,0 +1,205 @@
# 영역 16 — 폴더 구조·리팩토링·기능 개발 패턴
> 검토일 2026-11-06 · 기준 `bbde570`(`fix/maturity-review-2026-11-05-b`, PR #7 끝) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`
> 경로: repo 구조 전체, `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `scripts/test-feature-scaffold.ts`, `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/feature-residue.ts`, `src/contracts/external-contract-runtime.ts`(descriptor 타입), `src/contracts/server-state.ts`(뮤테이션 ID), `config/contracts/backend-contract-pin.json`, `docs/manual/`, `docs/architecture/starter-experience.md`
> 깊게 본 관점: 2, 3, 4, 9, 20, 21, 22, 23, 27
> 렌즈: 기능 개발 경로를 처음부터 끝까지 따라간다. 생성(읽기 판, `--with-create` NEVER 판, `--with-create --keyed` 판) → 필수가 된 `responseEnvelope` → 기능과 함께 커밋하는 추적 파일 → 11단계 제품 기능 제거 드릴. 실행 증거는 오케스트레이터의 merge 단계 실행(`desktop:/tmp/claude-gates/bbde570-ci/`, CI env)과 이 영역의 배치 요청 16-R1~R4다.
> 영역 판정(35.8): **조건부 사용 가능.** 생성 명령의 세 판이 모두 손 수정 없이 merge 명령을 돈다(FE-GATE-020 rc=0). 기능 작성자의 실수 자리 둘(응답 모양 줄 누락, 손으로 쓴 뮤테이션 ID)이 이제 `check:types`에서 막힌다. 조건은 넷이다. (1) 기능 ID가 템플릿 소스의 경로나 글자와 겹치면 11단계 제거 드릴이 템플릿 파일을 잔여로 잡는다. `product-feature`나 `-feature` 없는 짧은 ID(`search`, `profile`, `items`)를 고르지 않는다(1105/16-04 일부). (2) 기능 브랜치 둘은 dev manifest와 초기 JS 기록에서 충돌한다. 손으로 합치지 않고 03 A절의 명령을 다시 돌린다(1105/16-01, 충돌 제거는 결정 대기). (3) 템플릿 변경이 생성 기능의 브라우저 경로만 깨면 CI는 모른다(1105/16-03). (4) 기능을 지울 때 그 기능의 e2e spec은 손으로 지운다. 드릴은 spec 본문의 기능 ID를 더 이상 잔여로 세지 않는다(16-01).
## 0. 결론
- **지난 영역 발견 10건: 고쳐짐 5, 일부 2, 남음 3.** 고쳐짐: 1105/16-01, 16-02, 1103/16-01, 1103/16-05, 0929/12-03. 일부: 1105/16-04, 1103/16-06. 남음: 1105/16-03, 1101/16-05, 1101/16-06. 재발과 틀린 발견은 없다.
- **§16과 다르게 본 것 둘.** 1105/16-01은 §16.4가 "일부"지만 완료 기준의 둘째 길(03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다)을 채웠다. 고쳐짐으로 본다. 충돌 자체는 남고 결정 대기다(`CHANGELOG.md:97`). 1105/16-04는 §16.4가 "고침"이지만 고친 것은 `tests` 쪽뿐이다. `src`는 여전히 대소문자 무시 부분 문자열 검색이다(`scripts/lib/feature-residue.ts:45-56`). 빌드 산출물 검사도 같은 넓은 패턴이다. 매뉴얼 예시 이름 `invoice-feature`의 쓰기 기능 제거는 이제 통과한다(16-R2 rc=0, `invoice-feature removal: PASS (17 checks, no fixture IDs)`). 그러나 `product-feature`는 실패한다(16-R3 rc=1). 잔여로 잡힌 것은 템플릿 `src` 13파일, `tests` 6파일, 빌드 파일 1개이고, 모두 템플릿 소유다. 지난 발견의 근거 ④가 이미 적은 부분이다. 그래서 일부로 본다.
- **BREAKING 둘이 실수 자리를 타입으로 막는다.** `responseEnvelope`가 descriptor의 필수 칸이다(`src/contracts/external-contract-runtime.ts:239`). 뮤테이션 정책의 operation ID는 brand 타입 `MutationOperationId`이고 `commandMutationIdentity`만 만든다(`src/contracts/server-state.ts:276-278`, `:302`, `:319`). 두 테스트의 `@ts-expect-error`(`tests/unit/external-contract-runtime.test.ts:396`, `tests/unit/command-mutation-identity.test.ts:51`)가 쓰이지 않으면 `check:types:test`가 실패한다. merge 실행의 FE-GATE-003이 PASS이므로 두 타입 오류는 실제로 난다(E2). 생성기의 목록 GET 템플릿에서 줄을 뺀 변이(16-R1)를 돌렸다. 읽기만 있는 생성 기여였는데도 `check:types:app` rc=1이었다. 오류는 `invoice-contract-contribution.ts(69,4)` TS1360 `Property 'responseEnvelope' is missing ...`였다. 지난 라운드에 남았던 부분이 막혔다(E3).
- **생성 경로 세 판이 모두 merge 명령을 돈다.** FE-GATE-020 rc=0(1,237초, CI env). 읽기 판과 KEYED 판: `feature scaffold: PASS (77 checks)`(FE-GATE-001~013의 merge 명령, `FE-GATE-003:check-types` 포함). NEVER 판: 참조 기능을 지운 사본에서 `scaffold-feature --with-create`를 만들고 같은 게이트를 돈다(`scripts/test-sample-removal.ts:499-510`, `reference-feature removal: PASS (31 checks, no fixture IDs)`). 생성 기능 제거: `scaffold-feature removal: PASS (17 checks, no fixture IDs)`. 다만 게이트가 지우는 것은 읽기 판 하나이고, 그 이름은 템플릿 파일에 없다. 게이트 밖에서 생성 쓰기 기능을 설치한 채 `test:a11y`를 돌렸다(16-R4 rc=0, 69건 통과). 생성 라우트 셋이 세 엔진에서 axe를 통과했다. 상세 라우트는 실패 화면으로만 검사해 `INVOICE_DETAIL not checked in its own state`로 따로 보고됐다. 다만 이 확인을 지키는 CI 장치는 여전히 없다(1105/16-03).
- **추적 파일 둘의 문서가 맞다.** 03 A절 표(`docs/manual/03-outside-feature-folder.md:34-45`), 정본 표(`docs/architecture/starter-experience.md:223-224`), 01 1단계(`docs/manual/01-add-a-feature.md:106`, `:110`), 생성 출력(`scripts/create-feature.ts:1775-1778`)이 같은 두 파일과 다시 쓰는 명령을 말한다. `tests/unit/feature-tracked-files.test.ts`가 그 상수와 두 문서를 대조한다(FE-GATE-005 PASS).
- **새 발견 2건, 모두 Low·P3.** 16-01: 1105/16-04를 고치면서 `tests`의 잔여 판정을 "파일 이름 또는 import"로 좁혔다. Playwright spec은 `test:all`이 돌지 않는데(`vitest.config.ts:45`), 매뉴얼은 "`test:all`이 실패한다"고 적는다(`docs/manual/01-add-a-feature.md:662`). 16-02: 계약 문서 4.1절의 bulk 안내가 아직 "`responseEnvelope`를 빼고"다(`docs/architecture/backend-api-and-server-state-contract.md:206-207`). 필수 칸과 한 기여 안 같은 값 규칙에 둘 다 어긋난다. 07 영역의 07-01과 같은 결함이다. 전체 집계에서는 07-01로 한 번만 센다.
- **약해진 검사는 16-01 하나다.** 의도한 좁힘이고 커밋 본문(`b45d6a0`)과 매뉴얼이 적는다. 빈틈은 안전망으로 든 `test:all`이 Playwright spec을 돌지 않는다는 것이다. 그 밖에 이 영역 수정에서 지운 단언, 넓힌 예외, 새 skip은 찾지 못했다. 제거 드릴 사본의 문서 테스트 제외 4개 추가(`scripts/lib/removal-fixture.ts:73-80`)는 문서를 복사하지 않는 사본에서만 빠진다. 본 `test:unit`은 그대로 돈다. 초기 JS 예산 상향(`287dc6f`, D7)은 15 영역이 판정한다.
## 1. 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` |
| 커밋·작업 상태·확인 시점 | `bbde570`. 코드 읽기는 노트북 worktree(HEAD = 기준, 읽기만). 2026-11-06 04:00~ |
| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 |
| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template`, pin `45d2a478`, 읽기만)와 짝으로 쓴다. 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 손으로 고치지 않고, merge 게이트를 통과하고, 지울 때 제거 드릴이 통과한다. 기능 수 증가 외 정량 목표 없음 |
| 읽은 코드·구성 범위 | `scripts/create-feature.ts`(1,837줄), `scripts/create-feature-write-slice.ts`(1,091줄), `scripts/test-feature-scaffold.ts`, `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `scripts/lib/feature-residue.ts`, `scripts/lib/removal-fixture.ts`, `scripts/lib/removable-template-features.ts`, `scripts/check-backend-contract-drift.ts`, `config/contracts/backend-contract-pin.json`, `.dependency-cruiser.json`(기능 규칙), `src/contracts/external-contract-runtime.ts`, `src/contracts/server-state.ts`, `tests/unit/{feature-tracked-files,feature-residue,command-mutation-identity,external-contract-runtime,backend-contract-pin,backend-contract-drift,create-feature}.test.ts`, `tests/helpers/mutation-operation-id.ts`, `docs/manual/01·03·reference/errors.md·reference/create-feature.md`, `docs/architecture/starter-experience.md` "Adding a feature", `docs/architecture/backend-api-and-server-state-contract.md` 4.1절, `CHANGELOG.md` 미출시 절, `vitest.config.ts`, `tsconfig.test.json`, `package.json` scripts. 백엔드 pin 커밋의 생성기 템플릿 여섯 파일 존재(`git -C <backend> cat-file -e 45d2a478:<path>`), pin과 백엔드 HEAD `3d73b6f1` 사이 그 파일과 `docs/web/http-contract.md`의 diff(없음). `git diff 8a44226..bbde570`의 이 영역 경로와 수정 커밋 `6d084cf`, `f600e6b`, `b45d6a0`, `56272e8`, `48c1ab7`, `a37ebba` 본문 |
| 수행한 테스트·실험 | 실행 환경 = desktop 로그와 스냅숏. merge 단계 실행 `bbde570-ci`(CI env, 2026-11-06 03:24~03:56): `summary.txt`, `FE-GATE-NNN.log`, `gate-artifacts/FE-GATE-005·010·012·020.txt`. 스냅숏 `r5/snap/merge/artifacts/tests/feature-scaffold.xml`(03:40, 77건 실패 0). `r5/snap/verify-documentation.local.txt`·`.no-sibling.txt`(둘 다 `PASS_SCOPED`). 이 영역 요청은 오케스트레이터 배치 16-R1~R4다(04:24~04:32, 항목마다 restore clean, 로그 `r5/batch/out/R5-16-R1~R4.log`, 6절) |
| 확인하지 못한 범위·이유 | 실제 Gitea 러너, FE-GATE-013의 `test:system`(이 호스트에 user namespace 없음, 12 영역), 두 기능 브랜치의 실제 `git merge`, 매뉴얼만 보는 사람·에이전트의 재실험, 실제 짝 백엔드 연결, 생성 기능 설치 상태의 FE-GATE-008(5절) |
| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md`의 16-01~16-04, 같은 폴더 README §16.5의 1103/16-01·16-05·16-06, §16.6의 1101/16-05·16-06, 지난 영역 문서 2.2절의 0929/12-03. 지난 실행 결과(`16-mut`, 16-R1)는 증거로 쓰지 않았다 |
## 2. 지난 발견 재확인
README §16.4~16.6의 상태는 주장으로 보고, 각 발견의 지난 완료 기준을 `bbde570`의 코드와 실행 결과에 대어 다시 판정했다.
### 2.1 1105 영역 16 발견 (README §15)
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|---|---|---|---|
| 1105/16-01 | 기능 하나를 더하면 추적 파일 둘이 바뀌고, 문서는 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | **고쳐짐**(완료 기준 둘째 길). §16.4는 "일부" | 완료 기준은 "추적 파일이 없다. **또는** 03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다"였다. 둘째를 채웠다. ① 03 A절 표가 두 파일, 누가 쓰나, 다시 쓰는 명령, 안 넣으면 무엇이 실패하나를 적는다(`docs/manual/03-outside-feature-folder.md:36-41`). 충돌 처리("아무 쪽이나 고른 뒤 명령을 다시 돌린다")는 `:43-44`다. ② 정본 표 두 행이 같은 명령과 "merge conflict"를 적는다(`docs/architecture/starter-experience.md:223-224`). ③ 01 1단계 흐름에 manifest 재작성 줄이 있다(`docs/manual/01-add-a-feature.md:106`, `:110`). ④ "기능을 지울 때"가 초기 JS 기록 재작성도 말한다(`03-outside-feature-folder.md:215`). ⑤ 생성 출력이 상수 `FEATURE_TRACKED_FILE_REWRITES`(`scripts/create-feature.ts:1703-1714`)로 충돌 줄을 쓴다(`:1777-1778`). FE-GATE-020 로그에 그 줄이 나온다(`gate-artifacts/FE-GATE-020.txt:1535-1537`). ⑥ `tests/unit/feature-tracked-files.test.ts:24-57`이 상수의 경로·명령이 03 A절과 정본 표에 있는지 본다. FE-GATE-005 PASS. 남은 것(완료 기준 밖): 충돌 자체. 대안 (b)·(d)는 결정 대기다(`CHANGELOG.md:97`). 참고: 참조 기능을 지운 다운스트림에서도 생성 출력의 충돌 목록이 없는 파일(`config/scale/feature-shape-ceilings.json`)을 든다(`create-feature.ts:1778`, 조건 없음). 3번 줄은 "있는 동안"이라고 조건을 단다(`:1775`). 해가 없어 세지 않는다 |
| 1105/16-02 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 옮겼는데 pin·drift 검사는 `http-contract.md`만 본다 | **고쳐짐** | pin에 `backend.scaffoldSources` 여섯 항목이 있다. 항목마다 백엔드 파일, 옮긴 사실, 옮긴 프론트 파일과 이름을 적는다(`config/contracts/backend-contract-pin.json:8-39`). drift 검사가 pin 뒤 HEAD에서 그 파일마다 diff를 보고, 바뀌면 다시 볼 프론트 위치를 말하며 1로 끝난다(`scripts/check-backend-contract-drift.ts:169-180`). 완료 기준("네 사실 중 하나가 바뀌면 drift 검사가 알린다")은 `tests/unit/backend-contract-drift.test.ts:314-331`이 가짜 백엔드의 `NAME_MAX_LENGTH = 120` 변경으로 본다(FE-GATE-005 PASS). `tests/unit/backend-contract-pin.test.ts:187-205`가 각 항목의 프론트 이름이 그 파일에 있는지 본다. 여섯 백엔드 경로는 pin 커밋에 모두 있고, pin과 백엔드 HEAD `3d73b6f1` 사이에 바뀌지 않았다(직접 확인). 남은 한계(설계): drift 검사는 게이트 밖이고 옆 checkout이 있을 때만 돈다(`CHANGELOG.md:105`). 참고: 문서 경로는 pin 커밋에 없으면 "비교 못 함"(rc=2)이지만(`check-backend-contract-drift.ts:119-122`), `scaffoldSources` 경로는 존재를 보지 않는다. 경로를 틀리게 적으면 그 항목은 늘 "바뀌지 않음"이다. 지금은 여섯 경로가 맞아 세지 않는다 |
| 1105/16-03 | 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 | **남음**(결정 대기) | 드릴의 제외 목록이 그대로다(`scripts/lib/feature-scaffold-drill.ts:18-46`, `8a44226` 뒤 변경 없음). 생성 출력도 "브라우저 게이트 FE-GATE-008/009와 test:system 밖"이라고 적는다(`gate-artifacts/FE-GATE-020.txt:1530`). merge 실행의 FE-GATE-008(196초)·009(51초) PASS는 템플릿 원래 상태다. 그 사이 생성 라우트의 화면이 바뀌었다(`90c489c` 확인 뒤 목록 열기, `f2b8ba7` 다른 저장 진행 중 표시, `757d1c7` a11y.json schema 2). 지금 그 경로가 통과하는지는 16-R4로 따로 확인했다(CIENV, rc=0). `/invoice`, `/invoice/items/a11y-1`, `/invoice/new` × chromium·firefox·webkit이 모두 통과했고, 전체는 69건 통과(58.3초)였다. `INVOICE_DETAIL`은 `not checked in its own state (scanned on its failure state only ...)`로 보고됐다. 참조 기능 상세와 같은 처리다. 통과한다는 사실과 별개로, 이 통과를 지키는 CI 장치는 없다. §16.4의 결정 대기와 같다 |
| 1105/16-04 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡는다 | **일부**. §16.4는 "고침" | 고친 것: `tests`는 파일 이름에 ID가 있거나 기능 폴더에서 import하는 파일만 잔여다(`scripts/lib/feature-residue.ts:46-60`, 호출 `scripts/test-sample-removal.ts:428-431`). 저장소 자체를 `invoice-feature`로 훑으면 잔여 0이다(`tests/unit/feature-residue.test.ts:40-42`, FE-GATE-005 PASS). 안내도 "템플릿 파일이 나오면 고치지 말고 템플릿에 알린다"로 바뀌었다(`docs/manual/reference/errors.md:199`). 완료 기준 첫째는 충족했다. 16-R2(CIENV)에서 `create:feature invoice-feature --with-create --keyed` 뒤 `test:sample-removal -- --feature=invoice-feature`가 rc=0이었다. 결과는 `invoice-feature removal: PASS (17 checks, no fixture IDs)`, `Risk coverage: PASS (418/418 production modules, 72 thresholds)`였다. 완료 기준 둘째(`src`에 ID를 남기면 실패)는 단위 테스트가 본다(`feature-residue.test.ts:44-60`의 `src/contracts/leftover.ts`, E2). 남은 것: `src`는 여전히 기능 ID·폴더 이름의 대소문자 무시 부분 문자열을 경로와 본문 전체에서 찾는다(`feature-residue.ts:45`, `:53-56`). 지난 발견의 근거 ④("경계 없는 부분 문자열이라 짧은 ID는 더 많은 파일에 걸린다")가 적은 부분이고, 커밋 본문도 "이번 범위 밖"이라 적었다(`b45d6a0`). 예: ID `product-feature`(KEBAB 규칙 `scripts/create-feature.ts:110`에 맞고 예약 이름이 없다)는 템플릿 `src` 추적 파일 10개에 걸린다(`git grep -il`). 경로가 걸리는 2개(`src/contracts/product-features.ts`, `src/application/ports/product-features-port.ts`), 그 둘을 import하는 4개, 생성 색인 `../.generated/product-feature-index.ts`를 import하는 `src/features/installed-product-manifest.ts:5`, 글자로 걸리는 3개(`src/contracts/env.ts:82`의 스크립트 이름, `src/features/local-draft-feature/NOT_A_FEATURE:3`, `src/presentation/examples/platform-overview-page.tsx:654`의 `data-product-feature`)다. 드릴 사본에는 생성 색인 파일 자신도 있다. `tests`에서는 파일 이름 6개(`tests/unit/product-feature-selection-build.test.ts` 등)가 걸린다. `-feature` 없는 ID도 허용되는데(`create-feature.ts:137`), `search`는 `src` 38파일, `profile` 31, `items` 30, `account` 21, `home` 15파일에 걸린다(`git grep -il`). 16-R3(CIENV)에서 `product-feature`로 실행했다. `create:feature product-feature`는 통과했고, 11단계 드릴은 rc=1이었다. 실패는 잔여 검사 둘뿐이고 다른 검사는 모두 통과했다. ① `fixture-id-residue`: `src` 13파일. 위 10개에 생성 파일 `src/.generated/product-app.ts`, `product-context-index.ts`, `product-feature-index.ts`가 더해졌다. `tests` 6파일. ② `built-fixture-id-residue`: `dist/assets/platform-overview-page-*.js`. `data-product-feature` 속성이 빌드에 남아서다. 빌드 잔여 검사는 1105/16-04 수정 전의 넓은 패턴을 그대로 쓴다(`scripts/test-sample-removal.ts:113-116`, `:467-475`). 잡힌 20개는 모두 템플릿 소유다. 안내(`errors.md:199`)를 따르면 "템플릿에 알린다"에서 멈춘다 |
### 2.2 1103 이월 (README §16.5, 이 영역)
| 지난 ID | 내용 | 상태 | 근거 (`bbde570`) |
|---|---|---|---|
| 1103/16-01 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트가 통과한다 | **고쳐짐** | `contract.responseEnvelope`가 필수 칸이다(`src/contracts/external-contract-runtime.ts:231-239`). 생성기의 세 descriptor는 모두 `satisfies InstalledHttpContract<...>`다(`scripts/create-feature.ts:820`, `scripts/create-feature-write-slice.ts:295`, `:349`). 그래서 줄을 빼면 그 자리에서 tsc가 실패한다. 읽기만 있는 기여에서 모두 빼는 경우(지난 라운드 남은 부분)도 같다. 증거는 둘이다. ① `tests/unit/external-contract-runtime.test.ts:394-404`의 `@ts-expect-error`가 merge 실행 FE-GATE-003 PASS에서 쓰였다(E2). ② 지난 검증 방법(E-1)을 생성 기능으로 다시 했다(16-R1, E3). 생성기의 목록 GET 템플릿에서 줄을 지우고(`requests/16-R1.diff`, `scripts/create-feature.ts:800`) `create:feature invoice-feature`를 돌렸다. 기여는 읽기 하나뿐이고 줄이 하나도 없었다. 생성은 통과했고 `check:types:app`은 rc=1이었다. 오류는 둘이다. `invoice-contract-contribution.ts(69,4)`의 TS1360 `does not satisfy ... Property 'responseEnvelope' is missing in type ...`, 그리고 `(83,11)`의 기여 배열 cast TS2352다. 변이 없는 대조는 FE-GATE-020 `FE-GATE-003:check-types` PASS다(같은 템플릿의 읽기 판 `scaffold-feature`). 완료 기준 둘째("매뉴얼 3단계와 예시에 이 줄이 있다"): `docs/manual/01-add-a-feature.md:213-216`, 예시 `:280`, `:290`, 감싸지 않는 백엔드 안내 `:240`, 오류표 `docs/manual/reference/errors.md:109`. 참조 기능 셋은 `"NONE"`을 적는다(`src/features/reference-feature/contracts/reference-feature-contract-contribution.ts:91`, `:146`, `:197`). CHANGELOG "먼저 할 일" 1이 이행을 적는다(`CHANGELOG.md:24`). 남은 것(설계, 매뉴얼 "못 잡음"): 모든 operation에 같은 틀린 값. 조립은 빠진 값을 여전히 `NONE`으로 읽는다(`external-contract-runtime.ts:715-716`). 같은 절의 bulk 안내가 낡았다: 새 16-02(= 07-01) |
| 1103/16-05 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **고쳐짐** | `BoundMutation.operationId`가 `MutationOperationId`다(`src/contracts/server-state.ts:276-278`, `:319`). 이 값을 내는 곳은 `commandMutationIdentity` 하나다(`:302`, `:310`). 완료 기준("E-2의 오타가 `check:types`에서 실패")은 `tests/unit/command-mutation-identity.test.ts:49-60`의 `@ts-expect-error`가 FE-GATE-003 PASS에서 쓰인 것으로 본다(E2). 생성 쓰기 slice(`scripts/create-feature-write-slice.ts:511`)와 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)이 helper를 펼친다. FE-GATE-020의 KEYED 판이 `FE-GATE-003:check-types`를 통과한다. 남은 것(매뉴얼 "못 잡음", `docs/manual/01-add-a-feature.md:499-500`): descriptor 대신 손으로 만든 객체를 helper에 넘기는 것. 그때 위반 이름은 여전히 `MISSING_IDEMPOTENCY_KEY`다 |
| 1103/16-06 | 반드시 채우는 칸 중 아무도 읽지 않는 칸 | **일부**(지난 라운드와 같음, 결정 대기) | 쿼리 `owner`·`operationId`, 뮤테이션 `owner`는 `@deprecated` 선택 칸이다(`src/contracts/server-state.ts:178-184`, `:322`). 라우트 계약 `title`·`navigationLabel`은 화면이 읽지 않는데 생성기가 채운다(`scripts/create-feature.ts:582-583`, `scripts/create-feature-write-slice.ts:134-135`). 매뉴얼이 그렇게 적는다(`docs/manual/01-add-a-feature.md:409`) — M1. §16.5의 결정 대기와 같다 |
### 2.3 그 밖의 이월 (README §16.6, 지난 영역 문서 2.2절)
| 지난 ID | 내용 | 상태 | 근거 |
|---|---|---|---|
| 1101/16-05 (R-6, R-7) | 같은 개념이 두 폴더에 | **남음** | 오류 경계 두 벌(`src/presentation/boundaries/render-error-boundary.tsx`, `src/platform/errors/feature-error-boundary.tsx`), `TelemetryPort` 두 타입(`src/platform/telemetry/telemetry-port.ts:10`, `src/application/ports/telemetry-port.ts:5`), 폐기 재수출(`src/application/result.ts:9`). 이 경로들에 `8a44226..bbde570` 커밋이 없다. §16.6 "남김(작지 않음)"과 같다 |
| 1101/16-06 (R-8) | 기능 `contracts/`가 와이어 계약·문구·뷰 타입을 함께 담는다 | **남음** | 생성기가 `contracts/<base>-mapper.ts`, `contracts/<base>-message-catalog.ts`를 쓴다(`docs/manual/reference/create-feature.md:50-53`, `gate-artifacts/FE-GATE-020.txt:1502`, `:1505`). §16.6과 같다 |
| 0929/12-03 | 기능 안 계층 밖 폴더와 `contracts/`를 거친 어댑터 import에 규칙이 없다 | **고쳐짐**(대표 판정은 12 영역) | 규칙의 출발 경로가 "기능의 `adapters/` 밖 `src/features` 전체"다(`.dependency-cruiser.json:306-307`). `support/`·`contracts/`의 파일이 `src/adapters`를 import하면 위반이다. 그래프 회귀 fixture에 `support/` 재수출 거절이 들었다(`scripts/check-architecture.ts:823-831`). merge 실행 FE-GATE-010 `Architecture graph fixtures: 31 regression checks PASS`(지난 라운드 29). 파일 단위 예외는 기존 하나(`feature-adapter-contribution.ts`, type only) 그대로다. 생성 기능 둘이 설치된 드릴의 `FE-GATE-010:check-architecture`도 통과했다(`feature-scaffold.xml`) |
0929/08-06은 1103/16-06에 합쳐졌다(위 행). README §14.7의 `BUILD_INPUTS` 두 벌은 1105/15-03(15 영역)이다.
### 2.4 다른 영역 발견에 이 영역이 더한 증거
| 발견 | 이 영역이 더한 증거 |
|---|---|
| 1101/15-01 초기 JS 여유(15 영역) | merge 실행 FE-GATE-012: 템플릿 204,158 / 206,848 B, 27 / 32 파일(`gate-artifacts/FE-GATE-012.txt`). 같은 실행의 생성 드릴: 새 context의 기능 둘(읽기, KEYED)을 더한 뒤 205,465 B, 27 파일, `Bundle budget: PASS`(`FE-GATE-020.txt:6206`). 둘이 1,307 B, 하나 약 650 B다. 남은 여유는 1,383 B다. 같은 크기면 기능 넷째쯤에서 넘는다(추론. 기능 모양과 context 선택에 따라 다르다). 기록의 `perFeatureGzipBytes` 768 B는 참조 기능 사본의 값이다(`config/scale/feature-shape-ceilings.json:41-46`). 예산 상향(D7)의 판정은 15 영역이다 |
| 1105/03-01 플랫폼 code의 `refusedBeforeWrite` 거절(03 영역) | 생성 쓰기 slice는 `<FEATURE>_INVALID` 하나만 적는다. 플랫폼 목록(`src/contracts/external-contract-runtime.ts:638-659`)과 겹치지 않는다. 기능 이름이 `bad-request`여도 `BAD_REQUEST_INVALID`라 겹치지 않는다. FE-GATE-020의 두 쓰기 판이 조립을 통과한다 |
## 3. 이번 발견 (36.3)
집계: Low 2 · P3 2 · 구조적 위험 1 · 확인된 결함 1. High 이상과 P1은 없다. 16-02는 07 영역 07-01과 같은 결함이다. 전체 집계에서는 07-01로 한 번만 세고, 이 영역에서는 같은 결함으로 적어 둔다. 그래서 이 영역에만 있는 새 발견은 16-01 하나다. 1105/16-04의 남은 부분은 옛 ID로 2.1절에 두고 세지 않았다.
| ID | 제목 | 성격 | 심각도·우선순위 | 관련 관점 |
|---|---|---|---|---|
| 16-01 | 제품 기능 제거 드릴이 `tests` 잔여를 "파일 이름·import"로 좁혔다. 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아, spec 본문에 남은 기능 ID를 아무 검사도 잡지 않는다 | 구조적 위험 (검사 약화, 문서 불일치 포함) | Low · P3 | 21, 10, 27, 8 |
| 16-02 (= 07-01) | 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남아, 필수 칸과 한 기여 안 같은 값 규칙에 어긋난다 | 확인된 결함 (문서 불일치) | Low · P3 | 23, 17, 4 |
### 16-01 제품 기능 제거 드릴의 `tests` 잔여 판정이 좁아졌는데, 안전망으로 든 `test:all`은 Playwright spec을 돌지 않는다
| 필드 | 내용 |
|---|---|
| 성격 | 구조적 위험 (1105/16-04 수정이 만든 검사 약화. 매뉴얼·주석의 틀린 문장 포함) |
| 관련 관점 | 21, 10, 27, 8 |
| 근거 | ① 전: 제품 기능의 잔여는 `src`·`tests` 모든 파일의 경로와 본문에서 기능 ID를 찾았다(`8a44226:scripts/test-sample-removal.ts:113-120`, `:417-425`). ② 지금: `tests`는 파일 이름에 ID가 있거나, `from`·`import(`·`import `·`mock(` 뒤 문자열이 `/features/<id>/`를 가리킬 때만 잔여다(`scripts/lib/feature-residue.ts:46-50`, `:57-60`). ③ 주석과 매뉴얼은 빠진 경우를 `test:all`이 잡는다고 적는다. "A test that still depends on the removed feature fails `test:all`"(`feature-residue.ts:18-20`). "그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다"(`docs/manual/01-add-a-feature.md:662`). 커밋 본문도 같다(`b45d6a0` "위험·한계"). ④ 그런데 `test:all`은 vitest 묶음이다(`package.json:85`). vitest는 `tests/**/*.test.{ts,tsx}`만 돈다(`vitest.config.ts:45`). `tests/e2e/*.spec.ts`는 돌지 않는다. 드릴의 다른 단계(타입·lint·아키텍처·레지스트리·커버리지·빌드, `scripts/test-sample-removal.ts:441-461`)도 spec을 실행하지 않는다. `check:types`는 spec을 컴파일하지만(`tsconfig.test.json:7-12`) URL만 쓰는 spec은 컴파일된다. ⑤ 그래서 기능 ID를 본문에만 담은 spec(예: `tests/e2e/invoice.spec.ts`에 `test.describe("invoice-feature", …)`와 `page.goto("/invoice")`)은 전에는 잔여였고 지금은 아무 검사도 잡지 않는다. 03 문서는 기능 전용 e2e spec을 손으로 지울 목록에 둔다(`docs/manual/03-outside-feature-folder.md:210`). 기능 ID를 파일 이름에 넣은 spec(`tests/e2e/invoice-feature.spec.ts`)은 여전히 잡는다(`tests/unit/feature-residue.test.ts:48`, `:56`) |
| 발생 조건 | 다운스트림이 기능 전용 e2e spec(또는 visual·storybook spec)을 기능 ID가 아닌 이름으로 두고, 본문에 기능 ID를 적은 뒤 기능을 지울 때 |
| 영향 | 11단계 드릴이 통과한다. 남은 spec은 지운 라우트를 열다가 다음 CI의 FE-GATE-008에서 실패한다. 사용자 피해는 없다. 원인은 실패한 spec이 말해 준다 |
| 심각도·우선순위 | Low · P3 — 피해가 없고 merge 게이트가 결국 잡는다. 빠지는 범위도 좁다(본문에만 ID가 있는 비-vitest 파일). 다만 문서가 든 안전망이 그 경우를 덮지 않는다 |
| 통제·증거 | 목표 M3(지운 기능을 가리키는 파일을 드릴이 잡는다). 확인 M3(파일 이름·import, 단위 테스트 `feature-residue.test.ts:44-60`) · 본문만 가리키는 비-vitest 파일은 M0 · 문서 M1(틀린 문장) · E1(코드 정적 확인) |
| 확실성과 남은 가정 | 정규식, vitest include, `test:all` 구성은 코드로 확인했다. 실행으로 재현하지 않았다. 다운스트림이 spec 본문에 기능 ID를 얼마나 적는지는 모른다. 템플릿 자신의 e2e spec에는 기능 ID 글자가 없다(`git grep reference-feature tests/e2e` 0건) |
| 결정의 근거 | 확인한 사실: 좁힌 이유는 템플릿 테스트가 예시 ID를 데이터로 쓰는 거짓 양성이다(1105/16-04). 커밋은 "제거 전 이미 걸리던 파일 제외"를 버렸다. `src/contracts`에 남긴 진짜 잔여도 제거 전부터 ID를 담으므로 같이 빠진다는 이유다(`b45d6a0`). 리뷰어 추론: 거짓 양성의 원인 파일은 모두 vitest 파일이다(`tests/unit/create-feature.test.ts` 등). 실행되지 않는 파일만 본문 검색을 남기면 거짓 양성 없이 빈틈이 닫힌다 |
| 이해 비용 | 기능을 지우는 사람이 "드릴이 통과했으니 남은 것이 없다"고 믿는다. 03 손 목록의 e2e spec 줄을 따로 기억해야 한다 |
| 최소 개선 방향 | 대안 (b) 또는 (a) |
| 대안 비교 | (a) 문서만 고친다. 매뉴얼 01:662와 주석에 "Playwright spec은 `test:all`이 돌지 않는다. 본문에만 ID가 있는 spec은 손 목록(03:210)으로 지운다"를 적는다. 가장 싸다. (b) `tests` 중 vitest가 돌지 않는 파일(`*.spec.ts`, `tests/e2e/**`, `tests/visual/**`)에는 본문 검색을 남긴다. 템플릿 자신의 spec에는 기능 ID 글자가 없어 거짓 양성이 다시 나지 않는다. 드릴 수십 줄. (c) 현상 유지. (b) 권장 |
| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 |
| 비용·부작용 | (b)는 `feature-residue.ts`에 조건 하나와 단위 테스트 한 건. 다운스트림 spec이 무관한 이유로 기능 ID 글자를 담으면 거짓 양성이 생길 수 있다 |
| 재검토 조건 | 드릴이 브라우저 테스트를 돌게 되면 본문 검색이 필요 없어진다 |
| 완료 기준 | 본문에만 기능 ID를 담은 `tests/e2e/<other>.spec.ts`를 남긴 변이에서 11단계 드릴이 실패한다. `invoice-feature` 제거(16-R2)는 계속 통과한다. 또는 매뉴얼 01:662와 주석이 이 경우를 "못 잡음"으로 맞게 적는다 |
| 검증 방법 | `create:feature invoice-feature` 뒤 위 spec을 더하고 `test:sample-removal -- --feature=invoice-feature` |
| 담당·기한·상태 | 미정 · 미정 · 신규 |
| 재검증 결과 | 해당 없음 |
### 16-02 (= 07-01) 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남았다 — 필수 칸과 한 기여 안 같은 값 규칙에 둘 다 어긋난다
07 영역이 같은 줄을 07-01로 적었다. 같은 결함이다. 오케스트레이터는 07-01로 한 번만 센다. 아래 표는 이 영역(1103/16-01 BREAKING의 문서 경로)에서 본 근거다.
| 필드 | 내용 |
|---|---|
| 성격 | 확인된 결함 (문서 불일치). 07-01과 같은 결함 |
| 관련 관점 | 23, 17, 4 |
| 근거 | ① 문장: "bulk 엔드포인트를 붙이려면 `responseEnvelope`를 빼고 기능 스키마가 본문 전체를 읽는다"(`docs/architecture/backend-api-and-server-state-contract.md:205-207`, `49a0986`). ② 이 칸은 이제 필수다(`src/contracts/external-contract-runtime.ts:239`). 빼면 `check:types`가 실패한다. 같은 절 몇 줄 위가 그렇게 적는다(`:195-198`, `56272e8`이 고친 줄). 매뉴얼도 "줄은 빼지 않는다"고 적는다(`docs/manual/01-add-a-feature.md:214`, `:240`). ③ 빼는 대신 `"NONE"`을 적어도, 같은 기여의 다른 operation이 `ENVELOPE_V1`이면 조립이 거절한다(`external-contract-runtime.ts:715-716`의 비교, 오류표 `docs/manual/reference/errors.md:108`). bulk 엔드포인트는 짝 백엔드 것이라 보통 같은 패키지에 있다. 문장은 기여를 나누라고 말하지 않는다. ④ `56272e8`은 같은 4.1절을 고쳤지만 이 문장은 남겼다 |
| 발생 조건 | 짝 백엔드의 bulk 엔드포인트를 붙이려고 이 문서를 따를 때 |
| 영향 | 따르면 `check:types`가 실패하고, `"NONE"`으로 바꾸면 조립이 거절한다. 두 오류 모두 문구와 오류표가 원인을 말한다. 사용자 피해는 없다 |
| 심각도·우선순위 | Low · P3 — 문서 한 문장이고, 따르면 바로 분명한 오류가 난다 |
| 통제·증거 | 목표 M1(문서가 코드와 맞다). 확인 M1(틀린 문장) · E1 |
| 확실성과 남은 가정 | 확정. bulk 엔드포인트를 실제로 붙여 보지 않았다 |
| 결정의 근거 | 적용 제외 — 낡은 문장 한 줄을 고치는 문제다 |
| 이해 비용 | 계약 문서를 정본으로 읽는 사람이 매뉴얼과 다른 안내를 받는다 |
| 최소 개선 방향 | "bulk 엔드포인트는 `responseEnvelope: "NONE"`인 기여로 나누고, 기능 스키마가 Envelope 전체를 읽는다. 그러면 Envelope 실패 판정(6.1 표)을 그 operation에서 잃는다"로 고친다 |
| 대안 비교 | 적용 제외 — 단순 결함 수정 |
| 단순화의 보존 조건 | 적용 제외 |
| 비용·부작용 | 문서 한 문장 |
| 재검토 조건 | 적용 제외 |
| 완료 기준 | 4.1절에 "`responseEnvelope`를 뺀다"는 안내가 없고, bulk 안내가 기여 나누기와 `"NONE"`을 말한다 |
| 검증 방법 | `git grep -n "responseEnvelope\`를 빼" docs` 0건 |
| 담당·기한·상태 | 미정 · 미정 · 신규(07-01과 같은 결함, 07-01로 센다) |
| 재검증 결과 | 해당 없음 |
## 4. 28개 관점 판정 (36.2)
판정: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | > 07·09. 생성 기능은 도메인 규칙이 없어 `domain/`을 만들지 않는다 | — | E1 | > |
| **2** | **구조적 성숙도** | 적용(깊게) | M4 / M3 | E2 | **P** — 기능 안 계층 밖 폴더와 `contracts/`를 거친 어댑터 접근을 그래프 규칙이 막는다(0929/12-03 고쳐짐, FE-GATE-010 fixture 31). 같은 개념 두 벌(1101/16-05)과 기능 `contracts/`의 세 역할(1101/16-06)은 남음 |
| **3** | **변경 용이성** | 적용(깊게) | M4 / M4(부분) | E2 | **P** — 응답 모양 줄과 뮤테이션 ID가 descriptor에서 오고, 빠뜨리거나 손으로 쓰면 tsc가 막는다(1103/16-01·16-05 고쳐짐). 기능마다 다시 쓰는 추적 파일 둘은 문서와 검사가 있으나 브랜치 충돌은 남는다(1105/16-01 완료 기준 밖) |
| **4** | **인지 부하** | 적용(깊게) | M1 / M1 | E1 | **P** — 생성 뒤 할 일(추적 파일, 충돌 처리)이 출력·01·03·정본 표에서 같다. 읽지 않는 라우트 `title`·`navigationLabel` 칸은 남는다(1103/16-06). 계약 문서의 bulk 안내가 매뉴얼과 다르다(16-02) |
| 5 | 위험 가시성 | 적용 | M4 / M4 | E3 | P — 기여 전체에서 Envelope 줄이 빠져도 tsc 오류다. 생성 읽기 기여 변이에서 TS1360이 났다(16-R1). 모든 operation에 같은 틀린 값을 적는 경우는 매뉴얼에 "못 잡음"으로 적혀 있다 |
| 6 | 실패 성숙도 | > 03·07 | — | E1 | > |
| 7 | 운영 성숙도 | - 이 영역 밖 | — | — | - |
| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1 | P — tsc 오류와 오류표(`errors.md:109`)가 Envelope 누락을 말한다. 제거 드릴 잔여의 안내가 "템플릿 파일이면 알린다"로 맞게 바뀌었다(`errors.md:199`). 손으로 만든 객체를 helper에 넘긴 ID 불일치는 여전히 `MISSING_IDEMPOTENCY_KEY`다. 16-01의 빈틈은 다음 CI의 e2e 실패로 드러난다 |
| **9** | **유지보수 성숙도** | 적용(깊게) | M3 / M3(수동) | E2 | **P** — 백엔드 생성기 사실의 사본 여섯이 pin과 drift 검사에 묶였다(1105/16-02 고쳐짐. 검사는 게이트 밖). 1101/16-05의 두 벌은 그대로. 생성기 두 파일이 2,928줄로 늘었다(전 2,857). FE-GATE-020이 생성 결과를 merge 명령으로 돌아 drift를 잡는다 |
| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 읽기·NEVER·KEYED 세 판이 merge 명령을 돈다(FE-GATE-020). 설치 상태의 브라우저 게이트는 CI가 돌지 않는다(1105/16-03). 이번 커밋에서는 손으로 돌려 통과했다(16-R4 `test:a11y` 69건). 제품 기능 제거 드릴의 `tests` 범위가 좁아졌다(16-01) |
| 11 | 데이터 성숙도 | > 05 | — | — | > |
| 12 | 동시성 성숙도 | > 03 | — | — | > |
| 13 | 확장성 | 적용(기능 수 축) | M3 / M3 | E2 | P — 기능당 초기 JS를 기록과 상한으로 막는다. 생성 기능 둘을 더한 뒤 여유 1,383 B(FE-GATE-020). 같은 크기면 넷째쯤 예산 결정이 필요하다(추론, 15 영역) |
| 14 | 성능 성숙도 | > 15 | — | E2 | > |
| 15 | 보안 성숙도 | > 03·13 | — | — | > |
| 16 | 의존성 성숙도 | > 12·13 | — | — | > |
| 17 | API / Contract | 적용 | M4 / M4(부분) | E2 | P — `responseEnvelope` 필수, 한 기여 안 같은 값은 조립이 거절, 백엔드 생성기 사본은 pin(수동 검사). 계약 문서 bulk 안내가 낡았다(16-02) |
| 18 | 배포 성숙도 | > 13 | — | — | > |
| 19 | 설정 성숙도 | 적용(일부) | M1 / M1 | E1 | O — 지난 라운드와 같다(`docs/manual/02-decision-tables.md` 3절) |
| 20 | 개발자 경험 | 적용 | M3 / M2 | E3 | P — 생성 명령 하나로 merge 명령을 통과한다. 매뉴얼 예시 이름의 쓰기 기능은 11단계도 통과한다(16-R2). 템플릿 소스와 겹치는 ID(`product-feature`, 짧은 ID)는 11단계가 템플릿 파일 20개를 잔여로 내며 실패한다(16-R3, 1105/16-04 일부). 0단계는 이런 이름을 경고하지 않는다 |
| 21 | Guardrail 성숙도 | 적용 | M4 / M3(부분) | E2 | P — 새로 막는 것: Envelope 줄 누락(기여 전체 포함), 손으로 쓴 뮤테이션 ID, 기능 안 폴더 우회. 아직 통과하는 것: 같은 틀린 Envelope 값, 손으로 만든 객체로 helper 호출, 생성 기능의 브라우저 경로(1105/16-03), 본문만 기능 ID를 담은 spec(16-01). 거짓 양성: `src`·`dist` 쪽 잔여 검사(1105/16-04 일부, 16-R3) |
| **22** | **추상화 성숙도** | 적용(깊게) | M4 / M4 | E2 | **P** — `MutationOperationId` brand는 런타임 값을 바꾸지 않는 작은 타입이다. 우회는 손으로 만든 객체와 명시 cast뿐이다. 읽지 않는 라우트 칸은 남았다(1103/16-06) |
| **23** | **일관성** | 적용(깊게) | M1 / M1 | E1 | **P** — 추적 파일을 말하는 곳 넷이 같다(1105/16-01). 계약 문서 4.1절 한 문장이 필수 칸과 다르다(16-02) |
| **24** | **네이밍 / 의미** | 적용(깊게) | M1 / M1 | E1 | **P** — 기능 ID를 고르는 규칙(0단계)이 템플릿 소스와 겹치는 이름을 경고하지 않는다(1105/16-04 일부). 1101/16-05의 같은 이름 두 타입 그대로 |
| 25 | 조직 확장성 | 적용(구조 준비, 팀 1개) | M3 / M2 | E2 | P — 손으로 고치는 템플릿 파일은 없다. 기능 브랜치 둘의 충돌 자리 둘은 문서와 다시 쓰는 명령으로 푼다(1105/16-01). 실제 `git merge`는 재현하지 않았다 |
| 26 | Ownership | > 14 | — | — | > |
| **27** | **삭제 가능성** | 적용(깊게) | M3 / M2 | E3 | **P** — 생성 읽기 기능 제거가 merge 게이트에서 돈다(`scaffold-feature removal: PASS (17 checks)`). 예시 이름 쓰기 기능 제거도 통과한다(16-R2, 게이트 밖). 겹치는 이름은 거짓 양성이다(16-R3, `src`·`tests`·`dist` 세 검사 모두, 1105/16-04 일부). 본문에만 ID를 담은 spec은 놓친다(16-01). 폴더 밖 손 목록(03:202-215)이 초기 JS 기록까지 말한다 |
| 28 | 회복 가능성 | > 06·02 | — | — | > |
집계(이 영역): O 1 · P 16 · X 0 · ? 0 · > 10 · - 1. 지난 라운드와 같은 분포다. 3·5·17·22의 확인 통제가 M3 → M4로 올랐다.
## 5. 미검증
| 항목 | 이유 | 확인 방법 |
|---|---|---|
| 생성 기능 설치 상태의 FE-GATE-008(e2e·capability·storybook·visual) | merge 게이트라 요청하지 않았다(BRIEF 4). 접근성 e2e만 16-R4로 봤다. 1105 조치가 생성 폼을 바꿨다(`90c489c`, `f2b8ba7`) | 생성 기능 브랜치에서 `ci:gate FE-GATE-008` |
| 생성 KEYED 쓰기 기능의 제거를 merge 게이트가 도는지 | 게이트(FE-GATE-020)는 읽기 판만 지운다. 쓰기 판 제거는 16-R2로 한 번 확인했다 | — (관찰. 발견으로 세지 않는다) |
| 1105/16-04 완료 기준 둘째의 드릴 실행(`src`에 ID를 남긴 변이) | 단위 테스트(`feature-residue.test.ts:44-60`)와 드릴 연결 코드(`scripts/test-sample-removal.ts:428-431`)로 판단했다. 요청하지 않았다 | `src/contracts/env.ts`에 `invoice-feature` 주석 한 줄을 넣고 16-R2 |
| 두 기능 브랜치의 실제 `git merge` 충돌과 명령 재실행(1105/16-01) | git 상태를 바꾸는 실행을 하지 않았다 | 임시 clone에서 기능을 하나씩 더한 두 브랜치를 합치고 03 A절 명령을 돌린다 |
| 16-01의 빈틈 실행 재현 | 코드로 확정했고 요청하지 않았다 | 16-01 검증 방법 |
| 실제 Gitea 러너, 실제 짝 백엔드 연결, FE-GATE-013 `test:system` | 이 영역 밖이거나 환경이 없다(12 영역) | 러너에서 생성 기능 PR 하나 |
| 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식) | 이번에도 하지 않았다 | 매뉴얼만 보는 에이전트가 생성 기능을 실제 계약으로 바꾸고 막힘을 센다 |
## 6. 실행 기록
이 영역은 desktop에서 직접 아무것도 돌리지 않았다. 아래 항목은 요청 파일 `scratchpad/r5/requests/16.md`대로 오케스트레이터가 배치로 돌렸다. 기준 `bbde570`, 항목은 하나씩 돌렸고 끝날 때마다 checkout을 깨끗하게 되돌렸다(로그 끝 `restore=clean`). 로그는 `desktop:/tmp/claude-gates/r5/batch/out/R5-16-R1~R4.log`다. 네 항목 모두 기대와 맞았다.
| ID | 명령 | 변이 | rc | 결과 |
|---|---|---|---|---|
| 16-R1 | `corepack pnpm create:feature invoice-feature && corepack pnpm check:types:app` · local, 04:24 | `requests/16-R1.diff`(생성기 목록 GET 템플릿의 `responseEnvelope` 줄 삭제, `scripts/create-feature.ts:800`) | 1 | **기대와 같다.** create:feature는 통과했다(라우트 `INVOICE_LIST` 하나). `tsc --project tsconfig.app.json`은 실패했다. ① `invoice-contract-contribution.ts(69,4)`: TS1360 `does not satisfy the expected type 'InstalledHttpContract<...>'` / `Property 'responseEnvelope' is missing in type ...`. ② `(83,11)`: TS2352 기여 배열 cast, 같은 이유. 대조(변이 없음): FE-GATE-020 `FE-GATE-003:check-types` PASS |
| 16-R2 | `corepack pnpm create:feature invoice-feature --with-create --keyed && corepack pnpm test:sample-removal -- --feature=invoice-feature` · CIENV, 04:24~04:27 | — | 0 | **기대와 같다.** `invoice-feature removal: PASS (17 checks, no fixture IDs)`. 그 안에서 `Risk coverage: PASS (418/418 production modules, 72 thresholds)`, `Test evidence: PASS (430 files ...)`, `CI contract: 27 gates ... PASS`가 나왔다. 로그의 stack trace는 오류 경계 component 테스트가 일부러 낸 것이다. 테스트는 통과했다 |
| 16-R3 | `corepack pnpm create:feature product-feature && corepack pnpm test:sample-removal -- --feature=product-feature` · CIENV, 04:27~04:31 | — | 1 | **기대와 같다.** create:feature는 통과했다(`product-context`, `/product`). 드릴 실패는 잔여 검사 둘뿐이다. `fixture-id-residue`: `src/.generated/product-app.ts`, `src/.generated/product-context-index.ts`, `src/.generated/product-feature-index.ts`, `src/application/ports/in/application-api.ts`, `src/application/ports/out/application-output-ports.ts`, `src/application/ports/product-features-port.ts`, `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/contracts/env.ts`, `src/contracts/product-features.ts`, `src/features/installed-product-manifest.ts`, `src/features/local-draft-feature/NOT_A_FEATURE`, `src/presentation/examples/platform-overview-page.tsx`, `tests/component/product-feature-switch.test.tsx`, `tests/features/product-features-scale.test.ts`, `tests/scripts/generate-product-feature-index.test.ts`, `tests/unit/product-feature-index-write.test.ts`, `tests/unit/product-feature-selection-build.test.ts`, `tests/unit/product-features.test.ts`. `built-fixture-id-residue`: `dist/assets/platform-overview-page-C26HW_up.js` |
| 16-R4 | `corepack pnpm create:feature invoice-feature --with-create --keyed && corepack pnpm test:a11y` · CIENV, 04:31~04:32 | — | 0 | **기대와 같다.** `69 passed (58.3s)`. `/invoice`, `/invoice/items/a11y-1`, `/invoice/new`가 chromium·firefox·webkit에서 모두 `no critical or serious axe violations`였다. 보고: `a11y: INVOICE_DETAIL not checked in its own state (scanned on its failure state only: INVOICE_GET_ITEM reads one resource)`. 참조 기능의 `REFERENCE_RESOURCE_DETAIL`도 같은 줄이 나왔다. a11y.json 배열 자체는 로그에 없다. 이 보고 줄로 `notChecked`를 판단했다 |
인용한 실행(같은 커밋, 오케스트레이터):
| 출처 | 내용 |
|---|---|
| `bbde570-ci/summary.txt`(CI env, 03:24~03:56) | FE-GATE-020 rc=0 1,237초, FE-GATE-001~012 rc=0, FE-GATE-013 rc=1(전제 실패, 12 영역). `restored ... clean=yes` |
| `bbde570-ci/gate-artifacts/FE-GATE-020.txt` | `reference-feature removal: PASS (31 checks, no fixture IDs)`(:3087, 안에 NEVER 판 `scaffold-feature --with-create` 생성 :1495와 게이트). `feature scaffold: PASS (77 checks)`(:7974), `scaffold-feature removal: PASS (17 checks, no fixture IDs)`(:7973). 초기 JS 기록 `{"gzipBytes":205465,"files":27,"perFeatureGzipBytes":765,"perContextGzipBytes":157}`, `Bundle budget: PASS (initial JS 205465 / 206848 gzip bytes, 27 / 32 files)`(:6206). 생성 출력의 충돌 처리 줄(:1535-1537) |
| `r5/snap/merge/artifacts/tests/feature-scaffold.xml`(03:40) | 77건, 실패 0. `create-feature`, `create-feature-write`, `initial-javascript-record`, FE-GATE-001~013의 merge 명령, `feature-removal` |
| `bbde570-ci/gate-artifacts/FE-GATE-005.txt` | `feature-residue.test.ts`(3), `feature-tracked-files.test.ts`(3), `command-mutation-identity.test.ts`(5), `external-contract-runtime.test.ts`(47), `backend-contract-pin.test.ts`(15), `backend-contract-drift.test.ts`(9) 통과 |
| `bbde570-ci/FE-GATE-003.log`, `FE-GATE-010.log`, `gate-artifacts/FE-GATE-010.txt`, `FE-GATE-012.txt` | typecheck PASS, architecture PASS(`Architecture graph fixtures: 31 regression checks PASS`), `Bundle budget: PASS (initial JS 204158 / 206848 gzip bytes, 27 / 32 files)` |
| `r5/snap/verify-documentation.local.txt`, `.no-sibling.txt` | 둘 다 `Documentation readiness: PASS_SCOPED` |
## 7. 새 발견 요약
| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line |
|---|---|---|---|---|
| 16-01 | Low · P3 | 구조적 위험 | 제품 기능 제거 드릴이 `tests` 잔여를 파일 이름·import로 좁혔고, 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아 spec 본문의 기능 ID를 아무 검사도 잡지 않는다. 매뉴얼·주석이 "test:all이 잡는다"고 적는다 | `scripts/lib/feature-residue.ts:18-20, 57-60`, `docs/manual/01-add-a-feature.md:662`, `vitest.config.ts:45`, `package.json:85` |
| 16-02 (= 07-01, 07-01로 센다) | Low · P3 | 확인된 결함 | 계약 문서 4.1절의 bulk 안내가 "`responseEnvelope`를 뺀다"로 남아 필수 칸·한 기여 안 같은 값 규칙과 어긋난다 | `docs/architecture/backend-api-and-server-state-contract.md:205-207`, `src/contracts/external-contract-runtime.ts:239` |
@@ -0,0 +1,598 @@
# 성숙도 리뷰 — 2026-11-06 (5라운드)
> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 대상: `bbde570`(PR B, PR #7 끝). 이 커밋은 2026-11-05 리뷰의 조치(그 README 16절)를 모두 담는다. 영역은 2026-11-05 리뷰의 16개를 그대로 썼다. 영역 에이전트는 노트북 worktree에서 코드를 읽었다. 실행은 desktop checkout 하나에서 했다. merge stage는 메인 세션의 실행을 증거로 썼고(11.1절), 그 밖의 실행은 오케스트레이터가 묶어서 한 번씩 돌렸다(11.4절). 이 문서는 오케스트레이터가 결과를 모은 것이다. 새 High·P1 후보 둘(03-01, 08-01)은 오케스트레이터가 코드를 직접 다시 읽었다. 리뷰 중 코드는 고치지 않았다.
>
> 메인 세션이 따로 물은 세 가지(D7 예산 상향이 검사를 약하게 했나, 16.3절 통합 수정, BREAKING 5건의 CHANGELOG 안내)의 답은 3절에 있다.
## 0. 평가 전제 (가이드 0.1)
| 전제 | 기록 | 판정에 미치는 영향 |
|---|---|---|
| 사용 목적 | 프론트엔드 템플릿(reference implementation). 짝 백엔드 템플릿과 함께 써서 desktop 서버에 서비스를 빨리 출시하는 시작점(`PRODUCT.md`) | 다운스트림이 그대로 복제하는 기본값과 문서가 판정 대상이다 |
| 사용자와 팀 | 작성자 1명 + AI 세션. 다운스트림 2개(tech-log, memento) | 템플릿 파일을 고쳐야 하는 지점은 동기화 비용이 된다 |
| 지원 실행 형태 | 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | 서버 메모리 상태·다중 인스턴스 경쟁은 적용 제외. 탭 사이 경쟁은 적용 |
| 데이터와 권한 | 세션(짝 백엔드 인증), 선택형 OPFS 개인 파일, 공개 캐시. 관리자·테넌트 기능 없음 | 로그아웃·계정 삭제 뒤 남는 데이터가 주된 피해 경로다 |
| 규모 목표 | 기능 수 증가 축만 있다. 초기 JS 206,848 B(gzip, 1105 D7로 204,800 B에서 올림), 초기 파일 32개, 기능 모양 상한(`config/scale/feature-shape-ceilings.json`). 요청량·데이터량 목표 없음 | 성능은 lab 예산과 번들 예산으로만 판정한다 |
| 의존 시스템 | 짝 백엔드(pin `45d2a478`, `config/contracts/backend-contract-pin.json`), 정적 호스팅(nginx 예시), Gitea Actions(꺼져 있음, U-1) | 짝 계약 어긋남과 러너 전제를 따로 본다 |
| 운영 목표 | lab 예산(`config/performance/budgets.json`: 상호작용 200 ms, 기능 라우트 첫 진입 500 ms 등). RPO·RTO 없음 | 운영 복구 목표는 판정하지 않는다 |
| 지원·비지원 | OPFS·realtime·SW·Web Push·업로드는 opt-in. bulk `results` 비지원(문서화). 실제 CI 러너 미가동 | 없는 기능을 결함으로 세지 않는다 |
## 1. 사용 결정 (36.5-1)
| 용도 | 결정 | 막는 항목 |
|---|---|---|
| 템플릿 상태 그대로 merge 게이트 통과 | 조건부 사용 가능 | 13/14 통과(CI env). FE-GATE-013은 비특권 user namespace를 허용하지 않는 호스트(이 desktop)에서 사전 점검이 제한을 이름으로 대며 실패한다(1105/12-01. 제한 없는 호스트에서 PASS하는지는 가짜 호스트 단위 테스트로만 봤다). 뒤 부분은 통과. 이 게이트를 멈춤 기준에서 어떻게 셀지는 사용자가 정한다 |
| `create:feature`로 기능을 더하고 템플릿 CI로 머지 | 조건부 사용 가능 | 생성 세 판이 손 수정 없이 merge 명령을 지난다(FE-GATE-020 scaffold 77 check). 제품 기능 제거 드릴이 짧은·흔한 ID(`product-feature`)에서 템플릿 파일 20개를 잔여로 잡는다(1105/16-04 일부). spec 본문에만 남은 기능 ID는 잡지 않는다(16-01) |
| 다운스트림(tech-log·memento)에 이 묶음 전파 | 조건부 사용 가능 | BREAKING 다섯 단계는 따라 하면 맞는 변경이 된다. 설명 셋(부팅 실패 시점, TechLog Envelope, `requiresIdempotencyKey` 재계산)이 틀렸다(14-01, Low·P2). 1103/16-05 안내가 descriptor 없는 뮤테이션의 길을 말하지 않는다(09-01) |
| 짝 백엔드에 붙는 쓰기 폼(NEVER) | 사용 가능 | 거절 문구 자리가 있다. 선언하지 않은 code는 결과 불명으로 남는다(1103/03-01 일부) |
| 짝 백엔드 KEYED 쓰기(`--keyed`) | 조건부 사용 가능 | 결과 불명 뒤 같은 키 재전송이 쓰기 전 거절(429·401·503 `RATE_LIMIT_*`)로 끝나면 다음 저장이 새 키로 나간다(03-01, Medium·P2. 03-R1 재현) |
| 짝 백엔드와 파일 업로드 | 조건부 사용 가능 | 202 `REJECTED`·504 `TRANSFER_TIMEOUT` 판정은 들어왔다. 504 뒤 READY 보장은 백엔드 몫(1105/01-02 일부·백엔드로 넘김). 실제 짝 백엔드 업로드는 돌려 보지 않았다 |
| 짝 백엔드 인증에 세션 붙이기 | 조건부 사용 가능 | 쿠키 세션 401 연결은 들어왔다(1105/09-02 고쳐짐). 실제 Keycloak·Redis 연동 미확인(1103/09-03) |
| OPFS에 개인 파일 저장 | 조건부 사용 가능(지난 라운드 사용 보류에서 올림) | 계정 삭제 purge가 늦게 들어온 put과 reconcile 겹침까지 모두 지운다(05-R1 메모리 51/51, 05-R2 Chromium·Firefox 24/24). WebKit은 정책상 돌지 않아 미확인 |
| release 단계(`RELEASE_READY`)까지 | 조건부 사용 가능 | lab 통과(상호작용 151 ms, 기능 라우트 402 ms). release job이 실패 때도 로그를 올린다(1105/13-01, runner 미가동이라 일부). 승인이 거절된 run에는 advisory 기록이 없다(13-01). advisory 2건은 결정 대기(1103/13-03) |
| 배포 슬롯을 채워 자동 배포 | 조건부 사용 가능 | 제품 merge 검사가 실패하면 release를 멈춘다(1105/13-02 고쳐짐). live probe가 `/service-worker.js`의 같은 출처 redirect를 통과시킨다(06-01) |
| 짝 백엔드 Envelope 조회 화면 | 사용 가능 | bulk `results`는 비지원(문서화). 계약 문서 4.1절의 bulk 안내가 필수 칸과 맞지 않는다(07-01) |
| opt-in realtime(SSE·WS)·bounded polling | 조건부 사용 가능 | poll 던짐은 `PROTOCOL_MISMATCH`, reconnect 던짐은 서버 장애로 다르게 끝난다(04-01). 결정 대기 0929/04-02·04-03 |
| SW `ACTIVE`·Web Push | 조건부 사용 가능 | 옛 탭의 지운 route·청크를 이전 캐시로 연다(06-R1). Firefox quarantine 아직 필요(06-R4) |
| 셸·디자인 시스템·읽기 화면 | 사용 가능 | 08 영역 Low 3건(다시 마운트한 폼, 생성 폼 이동, gutter 띠) |
## 2. 차단 항목 (36.5-3)
### 2.1 새 High — 없음
### 2.2 새 P1 — 없음
### 2.3 이월 항목 중 남은 큰 것
| ID | 지난 등급 | 지금 | 남은 부분의 등급 |
|---|---|---|---|
| 1103/13-03 | Medium·P1 | 일부, 결정 대기(7절 D1) | Medium·P1 그대로. 운영 high advisory 2건(react-router 7.18.1, zod 4.4.3)이 13-R1 B에서 그대로 나온다 |
| 1103/03-01 | High·P1 → Medium·P2 | 일부. 기능 거절 문구는 동작(08-R6) | Medium·P2. 선언하지 않은 code는 결과 불명 → "변경됨으로 확인"으로 거짓 성공. `refusalMessages`의 409 필드 오류가 VD-04 결정 5와 어긋난다(08 영역) |
| 1105/01-02, 1103/01-01 | Medium·P2, High·P1 | 일부 · 백엔드로 넘김 | 504 뒤 READY 보장은 백엔드 요청 (b)로는 안 된다(01 영역). 실제 업로드 미검증 |
| 1103/09-04, 1103/03-07, 1103/16-06, 1105/16-03 | — | 결정 대기 | 그대로 |
| 1105/12-04 | Medium·P2 | 일부(14절) | 소유자 완료 기준(e2e 두 실행을 함께)은 통과했다. 리뷰 완료 기준(FE-GATE-008 둘 또는 008과 005를 `ci:gate`로 함께)은 아니다. 두 `ci:gate` 실행은 아직 같은 `dist`·`artifacts/`를 쓰고, 그 제한은 문서로만 적혀 있다(`README.md:362-363`) |
### 2.4 심각도 재확인
| ID | 영역 제안 | 최종 | 이유(오케스트레이터가 코드를 다시 읽음) |
|---|---|---|---|
| 03-01 | Medium·P2 | 그대로 | 결과 불명 쓰기의 재실행(가이드 35.2 High 예시)과 모양이 같다. 그러나 재전송이 `NOT_STARTED`가 되는 길은 전송 전 거절뿐이다(scope 변경, 검증, 자격 해석 실패. `http-execution-v3.ts:751-790`). 실행기에 offline 검사는 없다. 그래서 실제로 이 길을 여는 것은 opt-in rate limit(429·503 `RATE_LIMIT_*`, 백엔드 기본 꺼짐)이나 세션 만료(401)다. 저장을 한 번 더 누르면 되던 0929/03-03(High)보다 훨씬 드물다. 03-R1이 다른 길을 찾지 못했다 |
| 08-01 | Low·P3 | 그대로 | 다시 마운트한 폼에서도 결과 불명 화면과 가드는 그대로다. 결과가 보이지 않을 뿐이다. 중복은 사용자가 같은 항목을 새로 입력할 때만 생기고, 그 시점에 결과 불명 상태가 아니다 |
## 3. 메인 세션이 물은 세 가지
### 3.1 D7 예산 상향이 검사를 약하게 했나
- **약하게 했다. 다만 결정한 만큼만이다.** `initialJsGzipBytes`만 204,800 → 206,848 B로 바뀌었다(`config/performance/budgets.json:4`). 기능 1 KiB·context 512 B 상한, 초기 파일 32개, lab 예산은 그대로다(15 영역).
- 예산 검사는 여전히 동작한다. entry를 약 6 KB 늘리면 `check:bundle`이 "210352 > budget 206848 (over by 3504)"로 실패한다(12-R1).
- 기록 대조도 동작한다. entry를 +448 B 늘리면 `feature-shape-growth.test.ts`가 "record 204111, build 204606"으로 실패한다(15-R2). 허용치 256 B는 두 여유(템플릿 2,690 B, 드릴 1,383 B, CI env)보다 작다.
- 기록 `0fee3fe`은 측정 스크립트가 쓴 값과 바이트까지 같다(15-R1).
- 남은 것(새 15-01, Low·P3): 필요한 폭(665 B)의 약 세 배를 올렸는데, 그 폭의 근거와 다시 내릴 조건이 결정 기록에 없다. 재검토 조건은 "다시 넘을 때 · 1103/13-03을 정할 때"뿐이다.
### 3.2 16.3절의 통합 수정
| 지난 16.3 위치 | 판정 | 근거 |
|---|---|---|
| `45c9c4d`(합친 커밋, pin `notCopied`) | 맞다 | 답 표·pin·`backend-envelope.ts`·계약 문서 4.1이 같다(03, 07). 사본에만 있는 행을 pin 테스트가 잡는다(07-R2). desktop의 옆 백엔드로 drift 실행도 rc=0(07-R3) |
| `b8d53c9`(합친 커밋, vite 빌드 입력) | 맞다 | `vite-build-inputs.ts`가 `vite.config.ts`의 local import를 덮는다(15) |
| 12-04 fixup `f4d5761`·`0e72c0c` | 새 결함을 만들었다 | capability 설정이 없는 사본에서 테스트가 조용히 줄어든다(33 → 25, 10-01). `RUN_OUTPUT_ROOT` 아래 빌드 뒤 검사가 루트를 읽는다(12-02, 12-04 수정 자체가 만든 것) |
| 05-01 fixup `dc7c95b`(`orphanExemptRows`) | 약화 아님 | 예외를 빼도 템플릿 `check:registries`는 PASS다(05-R4). 커밋의 이유는 반만 맞다(다른 예외 둘은 쓰는 곳이 없어야 하는 행, 이 행은 recipe가 쓰는 `external` 키). 새 발견으로 세지 않았다 |
| 1105/11-01 fixup(`use` → `provide`) | 맞다 | 동작은 같다(11) |
| 15-05 fixup `e02f252`(골든 재생성) | 일부 | layout shift는 0건이다(15-R3, 18회). 비운 15 px 띠를 drawer·모달 가림막과 header가 덮지 않고, 새 골든이 그 모습을 고정했다(08-03) |
| 15-03 fixup `c9aa73f`(있는 소비자만 본다) | 새 결함에 포함 | 10-01과 같은 모양 |
| 03-01·16-01의 문서 테스트 목록 | 새 결함 | 파일 전체를 빼서 문서를 읽지 않는 테스트 14~15건이 capability 드릴 셋에서 빠진다. 목록 가드는 주석 한 줄로 통과한다(12-01 = 10-02) |
| `0fee3fe`(초기 JS 기록) | 맞다. 다만 문서가 어긋남 | 기록은 맞다(15-R1). `performance-evidence.md:209-210`이 템플릿 초기 파일을 26개로 적는다(지금 27개, 1103/15-02 재발) |
| `287dc6f`(D7 커밋) | 본문이 닿지 않는 해시를 가리킨다 | `ab0d4a1`·`7ce9bf1`은 재작성 전 해시다(14-02) |
### 3.3 BREAKING 5건의 CHANGELOG 안내
| 커밋 | 코드 = 꼬리말 = CHANGELOG 행동 | 틀린 설명 |
|---|---|---|
| `5c0b37e` 03-01 `refusedBeforeWrite` | 같다(03) | 3단계가 "부팅이 멈춘다"고 적는다. 실제로는 그 기능 라우트에 처음 들어갈 때 실패한다(14-01) |
| `05330e3` 04-02 poll 던짐 → `PROTOCOL_MISMATCH` | 같다(04, 11-03 절 행 포함) | 없음 |
| `48c1ab7` 1103/16-05 손 operation ID | 같다(09) | `requiresIdempotencyKey`를 `retrySemantics`에서 다시 계산한다는 말이 없다(14-01). descriptor 없는 뮤테이션의 길이 없다(09-01) |
| `757d1c7` 1103/11-01 `a11y.json` schema 2 | 같다(11) | 없음. 다만 `notChecked` 분류를 지키는 test가 없다(11-01) |
| `56272e8` 1103/16-01 `responseEnvelope` 필수 | 같다(07, 16-R1이 빠진 줄을 TS로 잡음) | 계약 문서 4.1절 bulk 안내가 "뺀다"로 남았다(07-01). 1단계의 TechLog 설명이 틀렸다(14-01) |
두 다운스트림 모두 행동을 그대로 따라 하면 맞는 변경이 된다(14 영역). 02 영역이 물은 진단 키 `scope_participant`(`CHANGELOG.md:68`)는 진단 계약에 키를 더한 것이라 BREAKING 표시가 필요 없다(오케스트레이터 확인, `src/contracts/diagnostics.ts:47`, `:96`, `:125`). 새 절의 해시 75개는 모두 `bbde570` 이력에 있고, 각 커밋의 `Refs`가 행의 ID와 75/75 같다.
## 4. 새 발견 건수 — 지난 라운드와 비교
| 라운드 | 기준 | 새 발견 | High | P1 | Medium | Low |
|---|---|---|---|---|---|---|
| 1105 | `8a44226` | 48 | 0 | 3 | 11 | 37 |
| **1106** | `bbde570` | **25** | **0** | **0** | **1** | **24** |
- 우선순위: P2 2건(03-01, 14-01), P3 23건.
- 성격: 확인된 결함 13, 구조적 위험 9, 개선 제안 3.
- 합친 중복 2건(11.3절)은 한 번만 셌다. 영역 문서에 적힌 것은 27건이다.
- 지난 조치가 만든 새 발견이 16건, 고치며 남긴 것이 2건이다(25건 중 18건, 목록은 15절 머리).
멈춤 기준(새 High 0, 새 P1 0, merge 게이트 14개 통과): High·P1은 0이다. merge 게이트는 13/14이고 FE-GATE-013은 호스트 제약으로 사전 점검에서 실패한다(11.1절). 이 게이트를 어떻게 셀지는 사용자가 정한다.
## 5. 확인된 강점 (36.5-2)
- 지난 라운드 P1 셋은 이 repo에서 확인할 수 있는 부분을 모두 고쳤다. 09-01은 탐침 변이로(09-R1), 12-01은 namespace를 만들어 보는 사전 점검으로, 13-01은 실패 run의 업로드 파일로(13-R1) 확인했다. 남은 것은 실행 환경 쪽이다(12-01: 제한 없는 호스트의 PASS, 13-01: 실제 release run의 산출물).
- 수정을 되돌린 변이는 모두 해당 테스트에서 기대한 이유로 실패했다. 살아남기를 기대한 것(06-R3, 약해진 단언의 증거)은 살아남았다. 배치 65항목 중 예상과 다르게 나온 것은 셋이고, 판정을 바꾼 것은 없다: 08-R2(probe 단언 둘을 잘못 짰다. 측정값은 08-03을 뒷받침한다), 15-R3(`clientWidth`가 한 값일 거라는 예상만 틀렸다. shift는 0건), 03-R7(6건 실패 예상, 같은 규칙을 보는 테스트 1건이 더 실패). 네 라운드 동안 살아남던 L01(오래된 scope의 성공 응답)도 이제 잡힌다(10-R4).
- OPFS purge가 늦은 put과 reconcile 겹침까지 지운다(05-R1·R2). 지난 라운드 사용 보류의 원인이 풀렸다.
- 한 checkout에서 e2e 두 실행을 함께 돌려도 서로 지우지 않는다(14절).
- CHANGELOG 새 절의 해시 75개가 모두 이력에 있고 `Refs`와 맞는다.
## 6. 반복되는 원인 (36.5-4)
| 원인 | 이번 예 | 지난 예 |
|---|---|---|
| 제거·격리 사본에서 테스트가 조용히 줄어든다. 줄어든 수를 보는 장치가 없다 | 10-01, 12-01 | 1103/02-06(문서 테스트 ENOENT) |
| 고친 동작과 그 동작을 설명하는 문서가 따로 움직인다 | 03-02, 05-01, 07-01, 13-01, 14-01, 1103/15-02 재발 | 1105/04-03, 14-02 |
| 화면 상태를 폼 인스턴스가 들고 있어, 다시 마운트하면 결과를 잃는다 | 08-01, 08-02 | 1105/08-01 |
| 결과 불명 상태를 시도 하나의 판정으로 풀어 버린다 | 03-01 | 0929/03-03, 1103/03-01 |
| 수정이 단언을 느슨하게 하거나 검사 범위를 좁힌다 | 06-02, 16-01 | 1105/15-02(허용 오차) |
## 7. 결정이 필요한 것
| 번호 | 결정 | 선택지 | 관련 | 결정할 사람 |
|---|---|---|---|---|
| D1 | 운영 advisory 2건(이월) | zod 갱신(+약 7 KB) / react-router 갱신 / 위험 수용과 재검토일 | 1103/13-03 | 프론트 소유자 + reviewer |
| D2 | 플랫폼 구성 화면(이월) | 지난 7절 D2와 같다 | 1103/09-04 | 프론트 소유자 |
| D3 | 백엔드 생성기 목록 GET(이월) | 지난 7절 D3과 같다 | 1103/03-07 | 두 repo 소유자 |
| D8 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지 | 호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족 | 11.1절, 1105/12-01 | 사용자(메인 세션이 묻는 중) |
| D9 | D7의 폭과 되돌림 조건 | 지금 값 유지 + 근거 기록 / 필요한 폭으로 다시 / 되돌림 조건 추가 | 15-01 | 프론트 소유자 |
| D10 | 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝날 때 | 훅에서 결과 불명 유지(03 영역 안 a) / rate-limit 503을 다시 `MAYBE_APPLIED`로 / 생성 페이지만 고치기 | 03-01 | 프론트 템플릿 담당 |
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트(이월) | 지난 16-03과 같다 | 1105/16-03 | 템플릿 담당 |
## 8. 미검증 (36.5-5)
| 항목 | 이유 |
|---|---|
| FE-GATE-013의 `tests/system` 18건 | 이 호스트가 비특권 user namespace를 막는다. 다른 러너에서 돌린 적이 없다 |
| release 단계 run의 산출물(1105/13-01 완료 기준) | CI runner가 꺼져 있다(U-1) |
| 실제 짝 백엔드 업로드·Keycloak·Redis 연동 | 백엔드를 띄워 보지 않았다 |
| OPFS purge의 WebKit 동작, 이전 release 탭과의 공존 | WebKit 기본 정책이 OPFS 런타임을 거절한다. 공존은 돌리지 않았다 |
| 05-R2의 "파일 0" | partition 디렉터리가 없어서 나온 값일 수 있다. 파일이 있을 때 세는 대조 실행이 없다 |
| 06-01의 브라우저 동작(worker script redirect 거절) | 일반 지식이다. 이 repo에서 실행하지 않았다 |
| 03-01의 실제 백엔드 빈도 | 재전송이 rate-limit 거절을 받는 빈도는 재지 않았다 |
| 1103/11-02·11-03·11-04 완료 기준 | 글꼴 없는 깨끗한 러너, namespace를 허용하는 호스트가 필요하다 |
## 9. 개선 순서 (36.5-6)
1. 결정 D8·D9·D10을 받는다.
2. Medium 03-01(D10에 따라).
3. Low·P2 14-01(CHANGELOG 설명 셋. 다운스트림이 읽는 곳).
4. 검사가 조용히 줄어드는 것들: 10-01, 12-01, 12-02, 16-01, 06-02.
5. 문서 어긋남: 03-02, 05-01, 07-01, 13-01, 1103/15-02 재발, 14-02.
6. 나머지 Low(01-01, 02-01, 03-03, 04-01, 04-02, 06-01, 07-02, 08-01~08-03, 09-01, 11-01, 15-01).
## 10. 재검토 조건 (36.5-7)
- 백엔드 pin(`45d2a478`)을 올릴 때: 07 영역의 사본 대조와 01 영역의 Fileserver 계약을 다시 본다.
- FE-GATE-013을 다른 러너에서 돌릴 수 있게 될 때: 1103/11-02~11-04와 1105/12-01의 실행 부분.
- 초기 JS가 다시 예산에 닿거나 1103/13-03을 정할 때: D7·15-01.
- KEYED를 템플릿 기본으로 바꾸거나 rate limit을 기본으로 켤 때: 03-01의 심각도를 다시 본다(High 후보).
## 11. 리뷰 범위 (36.1)
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 pin `45d2a478`의 트리를 `git show`로 읽기만 했다(노트북 작업 트리는 `3d73b6f1`로 움직였다) |
| 커밋·작업 상태·확인 시점 | `bbde570`(PR B, PR #7 끝. PR A `a793b83` 위, main `409d72e` 위). 기록 브랜치 `docs/maturity-review-2026-11-06`은 `bbde570`에서 땄다. 2026-11-06 04:00~. 노트북 worktree는 이 커밋에서 깨끗했다(추적 안 된 `AGENTS.md` 하나는 리뷰와 무관). desktop checkout은 실행마다 원래 상태(`fix/maturity-review-2026-11-03` `8a44226`)로 되돌렸다 |
| 제외 | PR #6(매뉴얼, `docs/improvement/`, 문서만, 별도 PR). 기준 커밋에 없다 |
| 목적과 지원 실행 구성 | 0절 |
| 필수 요구와 규모·운영 목표 | 0절 |
| 읽은 코드·구성 범위 | `src/`, `tests/`, `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정(영역 표 11.2). 짝 백엔드는 pin 트리의 계약·생성기·인증 문서와 코드 일부 |
| 수행한 테스트·실험 | 11.1절 게이트(메인 세션 실행)와 공유 실행 1회, 오케스트레이터의 12-04 완료 드릴, 영역 요청 배치(11.4절) |
| 확인하지 못한 범위·이유 | 8절 |
| 이전 리뷰와 비교 가능한 범위 | 2026-11-05 리뷰의 새 발견 48건(README 16.4절)과 1103 이월 22건(16.5절), 그 밖의 이월(16.6절). 이전 실행 결과는 증거로 쓰지 않았다 |
실행 환경: desktop, Ubuntu 24.04.4, kernel 7.0.0-38, Intel i5-10400F(12 스레드), 31 GB, Node v24.14.0, pnpm 11.17.0, Playwright 1.62.0.
### 11.1 게이트 실행 결과 (메인 세션, `bbde570`, desktop)
같은 커밋이라 메인 세션의 merge stage 실행을 게이트 증거로 쓴다.
- 실행: 2026-11-06 03:24~03:56, workflow env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest 형식).
- 출처: `desktop:/tmp/claude-gates/bbde570-ci/`(`summary.txt`, 게이트별 `FE-GATE-NNN.log`, 전체 로그 `gate-artifacts/FE-GATE-NNN.txt`). FE-GATE-013의 사전 점검 뒤 명령은 `desktop:/tmp/claude-gates/bbde570-013-parts/`(03:54~03:56).
- 실행 뒤 작업 트리는 비어 있었다(`status-after.txt` 0 B, `restored ... clean=yes`).
| 게이트 | 결과 | 시간 |
|---|---|---|
| FE-GATE-020 | 통과(참조 기능·생성 기능 제거, 생성 기능 77 check, optional-recipe·browser-file-storage·realtime 제거 모두 PASS. 생성 기능 둘을 더한 빌드 초기 JS PASS) | 1,237초 |
| FE-GATE-001 | 통과 | 3초 |
| FE-GATE-002 | 통과(lint) | 18초 |
| FE-GATE-003 | 통과(typecheck) | 27초 |
| FE-GATE-004 | 통과(runtime-schema 60) | 2초 |
| FE-GATE-005 | 통과(unit 3,056, contract 24, coverage 4,085) | 132초 |
| FE-GATE-006 | 통과(component 278) | 10초 |
| FE-GATE-007 | 통과(integration 212 외) | 28초 |
| FE-GATE-008 | 통과(e2e 222·4 skip, capability 69, storybook 1, visual 6) | 196초 |
| FE-GATE-009 | 통과(a11y 60. `REFERENCE_RESOURCE_DETAIL`은 실패 화면으로만 검사해 notChecked) | 51초 |
| FE-GATE-010 | 통과(architecture, adapter inventory, CI contract) | 63초 |
| FE-GATE-011 | 통과 | 8초 |
| FE-GATE-012 | 통과(초기 JS 204,158 / 206,848 B, 27 / 32 파일) | 6초 |
| FE-GATE-013 | **실패** — 사전 점검이 user namespace를 만들지 못한다(`bwrap: loopback: Failed RTM_NEWADDR`, 호스트 `kernel.apparmor_restrict_unprivileged_userns = 1`). 사전 점검 뒤 부분: `tests/system` 96/114(실패 18건 모두 같은 bwrap `RTM_NEWADDR`), 뒤 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, 공급망 fixture 둘, 보안 fixture, `check:browser-security`) 모두 rc=0. 멈춤 기준에서 이 게이트를 어떻게 셀지는 사용자가 정한다 | 2초(사전 점검) + 81초(`tests/system`) |
CLAUDE.md 게이트 목록은 `verify:documentation`을 빼고 모두 merge stage 안에서 돈다(`check:architecture`·`check:adapter-inventory`·`check:ci`는 FE-GATE-010, `check:types` 003, `lint` 002, `test:unit`·`test:contract` 005, `test:component` 006, `test:integration` 007, `test:runtime-schema` 004). 그래서 따로 돌리지 않았다.
공유 실행(오케스트레이터, `bbde570`, local env, 2026-11-06 04:03, 잠금 안에서 1회, 48초. 출처 `desktop:/tmp/claude-gates/r5/snap/`):
| 명령 | 결과 |
|---|---|
| merge stage가 남긴 산출물 snapshot | `snap/merge/`(761 파일, `MTIMES.txt`). 03:24 전 날짜의 파일은 옛 실행이 남긴 것이라 쓰지 않았다 |
| `verify:documentation`(FE-GATE-017, documentation stage) | `PASS_SCOPED`(desktop의 옆 백엔드 checkout 있음) |
| 같은 명령, 옆 checkout 없는 임시 worktree | `PASS_SCOPED`(짝 repo 참조 17개 미검증. pin 트리를 읽을 checkout이 없다) |
| `build` + `test:performance -- --runs=5` | PASS. 중앙값 LCP 2,032 ms, CLS 0, 상호작용 151 ms, `/examples/platform` 직접 진입 CLS 0, 기능 라우트 `EXAMPLES_UI` 402 ms(`snap/base/performance/lab.json`) |
### 11.2 영역 분할 (2026-11-05 README 11.2절 재사용)
| 번호 | 영역 | 문서 | 새 발견 |
|---|---|---|---|
| 01 | adapters: browser-transfer | [01-adapters-browser-transfer.md](01-adapters-browser-transfer.md) | 1 |
| 02 | adapters: browser-files·cache·cross-context | [02-adapters-browser-files-cache.md](02-adapters-browser-files-cache.md) | 1 |
| 03 | adapters: http·state | [03-adapters-http-state.md](03-adapters-http-state.md) | 3 |
| 04 | adapters: realtime | [04-adapters-realtime.md](04-adapters-realtime.md) | 2 |
| 05 | adapters: storage·kernel | [05-adapters-storage-kernel.md](05-adapters-storage-kernel.md) | 1 |
| 06 | adapters: service worker·push | [06-adapters-service-worker-push.md](06-adapters-service-worker-push.md) | 2 |
| 07 | contracts | [07-contracts.md](07-contracts.md) | 2 |
| 08 | presentation | [08-presentation.md](08-presentation.md) | 3 |
| 09 | app core·bootstrap·features | [09-app-core.md](09-app-core.md) | 1 |
| 10 | tests: 빠른 계층 | [10-tests-fast-layers.md](10-tests-fast-layers.md) | 1 (10-02는 12-01로 합침) |
| 11 | tests: 브라우저·릴리스·규모 | [11-tests-browser-release-scale.md](11-tests-browser-release-scale.md) | 1 |
| 12 | guardrails·CI | [12-guardrails-ci.md](12-guardrails-ci.md) | 2 |
| 13 | build·release·supply chain | [13-build-release-supply-chain.md](13-build-release-supply-chain.md) | 1 |
| 14 | 템플릿·제품 문서 | [14-template-product-docs.md](14-template-product-docs.md) | 2 |
| 15 | 성능 실측·최적화 | [15-performance.md](15-performance.md) | 1 |
| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | [16-structure-patterns.md](16-structure-patterns.md) | 1 (16-02는 07-01로 합침) |
### 11.3 합친 중복
| 대표 | 같은 결함 | 이유 |
|---|---|---|
| 12-01 | 10-02 | 같은 목록(`scripts/lib/removal-fixture.ts:70-81`)이 문서를 읽는 테스트를 파일째 뺀다. 12는 가드레일 쪽, 10은 빠진 테스트 수 쪽을 봤다 |
| 07-01 | 16-02 | 같은 문서 줄(`docs/architecture/backend-api-and-server-state-contract.md:205-207`)의 bulk 안내 |
관련은 있지만 따로 센 것: 06-02(`ce191be`가 marker deadline 단언을 10 s → 20 s로 느슨하게 함)와 10 영역의 1101/10-07 일부 판정(실제로 1 s 기다리는 RPC 테스트 셋이 남음)은 같은 커밋에서 나왔지만 결함 위치가 다르다. 10-01(조건부 테스트 정의)과 12-02(`RUN_OUTPUT_ROOT` 빌드 뒤 루트를 읽는 검사)는 둘 다 12-04 수정에서 나왔지만 결함이 다르다.
### 11.4 실행 방식과 안전 사항
- merge stage는 메인 세션의 실행(11.1절)을 그대로 썼다. 오케스트레이터는 merge stage에 없는 명령과 리뷰어가 읽을 산출물만 잠금 안에서 한 번 돌렸다(공유 실행, 04:03, 48초).
- 리뷰어는 desktop에서 아무것도 돌리지 않았다. `/tmp/claude-gates/` 아래 로그와 snapshot만 읽었다. 더 필요한 실험은 요청 파일에 적었다.
- 오케스트레이터가 요청 65항목과 12-04 완료 드릴을 하나씩 돌렸다(`desktop:/tmp/claude-gates/r5/batch/`). 항목마다 공유 잠금(`/tmp/claude-gates/heavy.lock`)을 잡고, `bbde570`을 detached로 checkout하고, 변이를 적용하고, 끝나면 원래 브랜치로 되돌렸다(추적 파일 reset, 추적 안 된 파일 삭제, node_modules 유지). 67항목 모두 `restore=clean`이다. 끝에 `git status`는 비었고, 브랜치 `fix/maturity-review-2026-11-03`, head `8a44226`이다.
- 같은 명령을 두 번 돌리지 않았다. 변이 없는 대조군은 게이트 로그로 갈음했다.
- 되돌림은 git이 무시하는 파일을 지우지 않는다. 그래서 16-R4가 만든 `artifacts/tests/a11y-data-state/INVOICE_DETAIL.json`이 11-R2에 남아 있었다. 그 라우트는 설치되지 않아 보고서가 읽지 않았고 판정에 영향이 없다(11 영역 5절).
- 리뷰어 둘(08, 13)이 규칙을 한 번씩 벗어났다. 둘 다 JSON 파일 하나를 `python3`로 읽기만 했다(08은 desktop의 manifest, 13은 노트북의 `config/ci/gates.json`). 쓴 파일은 없다. 각 문서 6절에 적혀 있다.
### 11.5 오케스트레이터 자신의 실수
- **배치 runner를 둘 띄웠다.** 첫 runner가 `./daemon.sh`로 떠 있어 `pgrep` 패턴에 걸리지 않았고, 하나를 더 띄웠다. 둘째 runner를 끄는 사이 그것이 잠금을 얻어 06-R1의 변이를 적용한 채로 죽었다. 그 뒤 항목들이 "checkout-not-clean"으로 건너뛰어졌다. 잠금 안에서 checkout을 되돌리고(남은 프로세스 없음 확인), 06-R1을 다시 돌렸다. 다른 항목은 건너뛴 뒤 다음 순회에서 깨끗한 상태로 돌았다. 06-R1의 로그는 다시 돈 것이다.
- **brief에 skip 규칙 ID를 틀리게 적었다.** "0929/10-04"가 아니라 1101/10-04다(10 영역이 바로잡음). 같은 틀린 ID가 `tests/unit/playwright-run-isolation.test.ts:244` 주석에도 있다. 그 주석은 지난 수정 라운드에 오케스트레이터가 쓴 것이다.
- **14-02의 원인은 오케스트레이터다.** D7 커밋 본문을 쓴 뒤 PR B를 다시 쌓아 03-01·08-03의 해시가 바뀌었는데, 커밋 본문은 고치지 않았다.
## 12. 28개 관점 판정 (36.2)
판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 그 관점을 판정한 영역 중 가장 약한 판정을 쓴다. 한 영역이라도 X면 X다(35.7절). ?는 그 영역에 증거가 없다는 뜻이라, 다른 영역이 P를 준 관점에서는 종합을 바꾸지 않는다(지난 라운드와 같다). 이번에는 X를 준 영역이 없다. 각 영역의 목표·확인 통제와 증거는 영역 문서 4절에 있다. 근거 칸에서 ID 앞에 라운드가 없으면 이번 라운드의 새 발견이다.
| 번호 | 관점 | 영역 01~16 | 종합 | 종합 판정의 근거·잔여 위험 |
|---|---|---|---|---|
| 1 | 코드 성숙도 | `OPPOPPOPO>>->>O>` | P | P는 02·03·05·06·08. 지속 실패에서 release marker와 active pointer를 다시 쓰지 않는다(1105/02-02 남은 것, 02-01). 훅이 재전송 한 번의 결과를 논리 요청 전체의 결과로 쓴다(03-01). 다시 마운트한 폼과 생성 폼의 저장 뒤 처리(08-01, 08-02). 손상 chunk reference 행이 reconcile을 멈춘다(0929/05-01 ③) |
| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>OP` | P | `check:architecture` 통과(FE-GATE-010). P는 02·09·12·16. 기능 안 계층 밖 폴더 → 자기 기능 `adapters/` → `src/adapters`의 두 단계 경로가 그래프·ESLint를 통과한다(0929/12-03 일부, 12-R3). SW 활성화 화면과 선택 런타임이 템플릿 파일이다(1103/09-05). cross-context 예외가 배럴 전체를 연다(0929/02-06). 같은 개념 두 벌(1101/16-05) |
| 3 | 변경 용이성 | `OOPPPPOPPPPPPPPP` | P | 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04). poll `execute`를 V3 실행기에 잇는 자리에 타입·대응표가 없다(04-02). 드릴에 맞춘 파일 존재 조건과 파일 단위 제외가 이름 바꾸기·테스트 추가와 함께 검사를 옮긴다(10-01, 12-01). 기능 브랜치 충돌은 결정 대기(1105/16-01). 빌드 입력 기본값 다섯 곳(R-2) |
| 4 | 인지 부하 | `PPPPPPOPPPPPPPPP` | P | 같은 사실을 문서마다 다르게 적는다. 저장소 설계 문서의 registry 목록이 절반이다(05-01). 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다(09-01). 두 미출시 절이 TechLog 모양을 다르게 적는다(14-01 b). 계약 문서 bulk 안내(07-01). 두 coordinator가 같은 던짐을 반대로 읽는다(04-01) |
| 5 | 위험 가시성 | `PPPPPPOPPPPPPPPP` | P | 결과 불명이 조용히 풀린다(03-01). 증거가 틀린 상태를 통과로 적는다: `a11y.json` 분류(11-01), `check:bundle` 이전 빌드(12-02), 거절된 run의 advisory 기록(13-01), 드릴 요약에 안 나오는 빠진 테스트(10-01, 12-01). 예제를 지운 제품은 lab 기능 라우트가 `measured: false`로 통과한다(1105/15-04). 위험이 커밋 본문에만 있다(08-03, 04-01) |
| 6 | 실패 성숙도 | `PPPPPPOPPOO-O>>>` | P | KEYED 같은 키 재전송이 쓰기 전 거절로 끝나면 결과 불명이 풀리고 다음 저장이 새 키다(03-01, Medium·P2). 선언하지 않은 거절 code와 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송(1103/03-01). pointer 지속 실패를 일시 오류로 분류한다(02-01). reconnect가 던짐을 서버 장애로 재시도한다(04-01). SSE EOF·`retry:` 미정(0929/04-02·04-03) |
| 7 | 운영 성숙도 | `PPPPPP>>P-P>P>P-` | P | `FILE_REJECTED`에 trace가 없다(01-01). 업데이트 설치 실패와 `health()`가 이어지지 않았다(0925/06-05 일부). reconnect는 조합 결함과 서버 장애를 가르지 못한다(04-01). drill에 PASS 경로가 없다(0929/11-02). provider job에 namespace 요구 주석·점검이 없다(1101/13-03) |
| 8 | 디버깅 가능성 | `PPOPOPOPOOPPPOOP` | P | 나아진 것: 조립 오류 원인이 한 번 나온다(1105/09-03). 사전 점검이 호스트 원인을 말한다(1105/12-01). 남은 것: `FILE_REJECTED`의 trace·이유(01-01), pointer 지속 실패 신호 없음(02-01), 던짐의 원인 예외(04-01), 사전 점검을 넘긴 뒤 provider test 6건이 원인 없이 시간 초과(1105/12-01 남은 것, 11), TLS 실패는 `error.name`만(13) |
| 9 | 유지보수 성숙도 | `PPPPPPPPPPPPPPPP` | P | 낡은 문서: 05-01, 07-01, 09-01(매뉴얼 01 `:476`), 1103/15-02 재발(`performance-evidence.md:209-210`의 26), 14-02(D7 커밋 본문의 옛 해시). 사본: canonical JSON 3벌(0929/05-07), `scopeSnapshot` 4벌(1101/10-08), CSP 6벌(0929/13-04) |
| 10 | 테스트 성숙도 | `PPPPPPPPOPPPPPPP` | P | 지난 생존 변이가 거의 모두 잡힌다(01-R1~R4, 02-R2~R9, 03-R2~R7, 04-R1, 08-R3~R6, 09-R1~R3, 10-R1~R4, 11-R1, 15-R2). 남은 틈: 약해진 상한 test(06-02, 06-R3 생존), 드릴 사본의 검출 공백(10-01, 12-01), `notChecked` 분류(11-01), spec 본문 ID(16-01), 테스트 없는 경로(03-01·03-02·07-02·08-01·08-02), 골든이 gutter 띠를 고정(08-03), 예제 제거 드릴이 게이트 밖(1105/14-01 잔여) |
| 11 | 데이터 성숙도 | `OP-OPO>-P>-->-->` | P | "승인된 계정 삭제 뒤 bytes 0" 규칙을 이제 지킨다(1103/05-01, 05-R1 50/50, 05-R2 24/24). P는 02·05·09. 계속 읽히지 않는 marker·pointer는 adapter 밖에서만 고친다(1105/02-02 남은 것, 02-01). IndexedDB 롤백 중 계정 삭제가 실패한다(0929/05-05). local-draft ABA는 주석뿐(0925 FOLLOW-UP 09-08) |
| 12 | 동시성 성숙도 | `POPOPO-OPOPP>->>` | P | 한 논리 요청의 여러 시도 사이에서 확실성을 합치지 않는다(03-01). 게이트 두 개는 한 checkout에서 함께 돌 수 없다(1105/12-04 일부). reconcile이 partition lock을 쥐지 않는다(05, bytes는 남지 않았다). 두 탭 같은 uploadKey는 단위 테스트뿐(01). 이전 scope 401의 microtask 전환은 재현하지 않았다(09) |
| 13 | 확장성 | `PO>P?PO>O>P>>>PP` | P | 생성 기능 둘을 더한 뒤 초기 JS 여유 1,383 B. 같은 크기면 넷째쯤 예산 결정이 필요하다(15-01, 16). 조합 코드가 다른 descriptor를 넘기면 attempt마다 요청이 최대 3번(1103/04-01 잔여 위험). 생성 기능을 설치한 상태의 브라우저 게이트가 없다(1105/16-03). 05는 규모 목표가 없어 ? |
| 14 | 성능 성숙도 | `PP>P?P>O>P>?P>P>` | P | lab PASS: LCP 2,032 ms, CLS 0, 상호작용 151 ms, 기능 라우트 402 / 500 ms(로컬 env). 남은 것: 진입 요청 두 묶음(1105/15-04 결정 대기), CSS·라우트 합 예산 없음(1101/15-03), 릴리스마다 사전 캐시 전체 재다운로드(1101/06-05), `tests/unit` 133 → 176 s(1101/10-05). 05·12는 목표·runner가 없어 ? |
| 15 | 보안 성숙도 | `OPOOPOOPOO>OP>>>` | P | 운영 high advisory 2건이 결정 대기다(1103/13-03). 승인 정규식 두 벌(0929/05-06), 로그인 복귀 주소(0929/08-08), download media type 짝(1101/02-02). OPFS 계정 삭제 뒤 개인 파일이 남던 경로는 닫혔다(1103/05-01) |
| 16 | 의존성 성숙도 | `O->O-P>>->PPPPO>` | P | 1103/13-03. 승인이 거절된 run에는 advisory 기록이 없다(13-01). SBOM이 `deduped`를 따라가지 않는다(0929/13-05). 미사용 `dependency-cruiser`(0929/12-05). 깨끗한 러너의 글꼴 설치 미실행(1103/11-02). 기준점 형식 둘(0929/14-02) |
| 17 | API / Contract 성숙도 | `PPPPPPPPPP>POP>P` | P | 답 표 ↔ 사본 ↔ 프론트 표가 게이트에서 잠겼다(1105/07-01). 남은 것: 6.1절 rate-limit 문장(03-02), 03-01이 백엔드 §2 "새 키 금지"를 어긴다, bulk 안내(07-01), 두 칸 없는 응답 행(07-02), poll `input.operation` 타입(04-02), BREAKING 이행 안내(14-01, 09-01), Fileserver 계약이 pin 밖(1105/01-02), `refusalMessages`와 VD-04 결정 5(1103/03-01) |
| 18 | 배포 성숙도 | `OP>PPP>O>>P>P>O>` | P | 제품 gate가 release를 막는다(1105/13-02). 남은 것: 워커 스크립트 redirect(06-01), 워커 없는 빌드의 probe 범위(1105/06-02 결정 대기), `assetsDir` 상수(0925/06-08), marker·pointer 지속 실패로 rollback·activate 불가(1105/02-02, 02-01), provider 없는 배포 경로(1101/13-03), 하위 경로(0929/13-06), release run 산출물 미확인(1105/13-01) |
| 19 | 설정 성숙도 | `PPPPPPOPOPPPPOOO` | P | 셸의 `RUN_OUTPUT_ROOT`가 빌드 위치만 바꾸고 검사 위치는 그대로다(12-02). `.env*` 입력 갈림(0929/13-02), 기본값 다섯 곳(R-2), `assetsDir` 상수(0925/06-08), locale 목록(0929/08-01), 교차 origin 헤더 허용이 문서뿐(0929/03-02) |
| 20 | 개발자 경험 | `P>PP>PPPPPPPPPPP` | P | 안내대로 하면 실패하는 길: bulk(07-01), BREAKING 2단계(14-01 c, 09-01). 저장 중에 떠난 뒤 상세로 이동(08-02). V3 결과 → poll 결과 대응표 없음(04-02). 템플릿 소스와 겹치는 기능 ID로 제거 11단계 실패(1105/16-04 일부, 16-R3). 게이트는 한 checkout에 하나씩(1105/12-04), FE-GATE-020 1,237 s(10) |
| 21 | Guardrail 성숙도 | `PPOPPPPOPPPPPPPP` | P | 영역은 모두 P다(03·08은 O). 지난 라운드 X(오케스트레이터 판정)의 두 원인은 닫혔다. FE-GATE-005 탐침은 1105/09-01로 고쳐졌다. FE-GATE-013은 이제 사전 점검에서 이유와 함께 멈춘다(1105/12-01). 다만 이 desktop에서 FE-GATE-013은 여전히 실패하고, 허용 호스트 PASS는 단위 테스트뿐이다. 12 영역은 머지 시점을 ?로 둔다. 남은 틈: 검사가 틀린 답을 낸다(12-02, 12-R2에서 예산 3,504 B 초과 빌드가 PASS). 검사가 좁아졌다(06-02, 10-01, 12-01, 16-01). 지키는 test가 없다(11-01). 예산 상향 폭의 규칙이 없다(15-01). 손 게이트 목록(1105/12-03), 두 단계 경로(0929/12-03), 게이트 밖 드릴(1105/14-01 잔여, 1105/16-03). 다시 X로 둘지는 오케스트레이터가 정한다 |
| 22 | 추상화 성숙도 | `OPPPPOOPOPPO>>>P` | P | poll 계약과 실행기 사이 타입이 이어지지 않는다(04-02). 정책이 키 여부만 실어 훅이 NEVER와 IDEMPOTENT를 가르지 못한다(03-03). 저장 결과가 폼 인스턴스에만 있고 페이지가 코디네이터 상태와 손으로 합친다(08, 08-01·08-02의 반복 원인). 읽지 않는 라우트 칸(1103/16-06). kind·effect 두 함수(1101/03-04) |
| 23 | 일관성 | `PPPPPPPPPPPPPPPP` | P | 같은 입력을 자리마다 다르게 다룬다. 던짐(poll `PROTOCOL_MISMATCH`, reconnect 재시도, 04-01), redirect(자산 거절, 워커 스크립트 통과, 06-01), IDEMPOTENT(실행기 재전송, 훅 차단, 03-03), 빌드 위치와 검사 위치(12-02), 참조 폼과 생성 폼의 저장 뒤 이동(08-02). 문서와 코드: 03-02, 07-01, 14-01 b. 드릴 맞춤 방법 셋(10-01) |
| 24 | 네이밍 / 의미 성숙도 | `PPPPOPPPPPPPOPPP` | P | reconnect의 `PROVIDER_UNAVAILABLE`에 조합 결함이 남는다(04-01). 확인 중에 "변경 사항을 저장하고 있습니다."(08-01). "부팅이 멈춘다"(14-01 a). NEVER·IDEMPOTENT 결과 불명의 출구가 하나다(03-03). `REMOVAL_FIXTURE_DOCUMENT_TESTS` 이름과 동작(12-01), 틀린 근거 ID(10-01). `automatedStatus: "passed"`가 `scope`만 뜻한다(11) |
| 25 | 조직 확장성 | `-->-?-OPO->P-P>P` | P | 기능 브랜치 둘의 충돌 자리를 문서와 명령으로 푼다. 충돌 자체는 결정 대기이고 실제 `git merge`는 재현하지 않았다(1105/16-01). 게이트는 한 checkout에 하나씩(1105/12-04). 필드 문구 표·locale 목록이 템플릿 파일이다(08). 다운스트림 모양 fixture가 없다(14). 1인 관리라 01·02·04·06·10·13은 적용 제외 |
| 26 | Ownership 성숙도 | `P>P-?OO?>PPPPP>>` | P | Fileserver 계약 대조의 주인이 없다(1105/01-02). 예외 목록에 담당·재검토가 없다(0929/12-07 결정 대기). 다운스트림 결함 후보를 받는 곳이 없다(0929/14-06). owner와 다른 reviewer가 1인 운영에 없다(1103/13-03). 수동 접근성 기록 10건이 `pending-manual-review`다(08, ?). 05는 확인할 대상이 없어 ? |
| 27 | 삭제 가능성 | `POOOPOO>PPPP>P>P` | P | 제거 드릴 다섯이 통과한다(FE-GATE-020 rc=0). 남은 것: capability 사본에서 pin 대조가 파일째 빠진다(12-01), 조건부 8개가 말없이 사라진다(10-01), spec 본문 ID를 놓친다(16-01), 겹치는 이름의 거짓 양성(1105/16-04 일부), 예제 제거 드릴이 게이트 밖(1105/14-01 잔여), 읽는 곳 없는 추적 산출물 13개(0929/14-01), 플랫폼 구성 화면은 빠지지 않는다(1103/09-04) |
| 28 | 회복 가능성 | `PPPPPP-PO-P-P>>>` | P | active pointer·release marker가 계속 읽히지 않으면 adapter 안에서 돌아올 길이 없다(02-01, 1105/02-02). KEYED 결과 불명의 회복이 새 키로 바뀐다(03-01). IDEMPOTENT 결과 불명은 확인·새로고침뿐(03-03). 다시 마운트한 폼의 확인(08-01). 선언하지 않은 거절 뒤 거짓 성공 버튼(1103/03-01). kill switch의 서빙 전제를 probe가 보지 않는다(06-01). 손상 chunk reference가 reconcile을 막는다(0929/05-01 ③) |
합계: 충족 0 · 부분 충족 28 · 미충족 0 · 미확인 0 · 적용 제외 0. 지난 라운드는 부분 충족 27 · 미충족 1(21, 오케스트레이터 판정)이었다. 영역 판정 448칸은 O 80 · P 265 · ? 6 · - 25 · > 72다. ?는 05(13, 14, 25, 26), 08(26), 12(14)에 있다. 12는 21을 "P(로컬) · ?(머지 시점)"으로 적었고, 위 표에는 P로 넣었다.
## 13. 지난 발견 상태 (140건, `bbde570`)
대상은 넷이다.
- 1105 색인 48건(지난 §15). 1105/11-02는 지난 라운드에 1105/12-01로 합쳤으므로 12-01 행에서 센다.
- 1103 이월 22건(지난 §16.5).
- 그 밖의 이월 33건(지난 §16.6).
- §16.6에 없지만 영역 문서 2절이 연 이월 37건(ID가 있는 것). ID가 없는 이월 10건은 표 끝에 따로 적는다.
"지난 §16 판정"은 지난 README §16.4·16.5·16.6의 칸이다. 상태는 고쳐짐(완료 기준을 이 커밋에서 확인) · 일부(남은 것을 적음) · 남음 · 재발 · 틀린 발견이다. 결정 대기·백엔드로 넘김·실행 환경 대기는 상태 뒤에 붙인다. **(판정 정정)**은 지금 상태가 §16의 칸과 다른 것이다. 두 영역이 같은 ID를 보면 한 행으로 적는다. 판정이 갈리면 행에 적고 약한 쪽을 쓴다. 근거는 링크한 영역 문서 2절에 있다.
재발 확인만 한 지난 고쳐짐 항목(각 영역 2절 끝)은 표에 넣지 않았다. 재발은 1103/15-02 하나다. 판정하지 않은 것(0929/08-06·08-07, 08 영역. 08-06은 16 영역이 1103/16-06에 합쳤다)과 영역이 세지 않은 참고(12 영역의 1101 FOLLOW-UP `noUnusedParameters`·1101 U-1·1103/12-01 보존 조건, 01 영역의 1103 D3)도 넣지 않았다.
### 13.1 건수
| 묶음 | 건수 | 고쳐짐 | 일부 | 남음 | 재발 | 틀린 발견 |
|---|---|---|---|---|---|---|
| 1105 색인(§15) | 48 | 37 | 8 | 3 | 0 | 0 |
| 1103 이월(§16.5) | 22 | 7 | 14 | 0 | 1 | 0 |
| 그 밖의 이월(§16.6) | 33 | 7 | 8 | 18 | 0 | 0 |
| §16.6에 없던 이월 | 37 | 1 | 5 | 31 | 0 | 0 |
| 합계 | 140 | 52 | 35 | 52 | 1 | 0 |
- 결정 대기 22건: 1105/06-02·15-04·16-03, 1103/03-01·03-02·03-07·09-04·12-05·13-03·14-02·16-06, 0929/02-02·02-06·04-02·04-03·12-07·14-06, 1101/02-02·10-05·10-06·10-08·14-07.
- 백엔드로 넘김 4건: 1105/01-02, 1105/03-02(고쳐짐), 1103/01-01, 1103/09-03.
- 실행 환경 대기 5건: 1105/12-01, 1105/13-01, 1103/11-02·11-03·11-04.
- 1105/12-04는 오케스트레이터가 일부로 판정했다(14절).
- 1105/10-03(변이 도구 제안)은 조치하지 않아 남음으로 셌다. 10 영역은 세지 않고 오케스트레이터 몫으로 두었다.
### 13.2 §16과 다른 판정 (15건)
§16보다 약하게 본 것(9건):
- 1105/01-02: 고침 · 백엔드로 넘김 → 일부 · 백엔드로 넘김 (01)
- 1105/02-02: 고침 → 일부 (02)
- 1105/12-01: 고침(PR A) → 일부 · 실행 환경 대기 (11은 일부, 12는 고쳐짐. 약한 쪽)
- 1105/12-04: 고침 → 일부 (12 영역 의견, 오케스트레이터 판정 14절)
- 1105/13-01: 고침(PR A) → 일부 · 실행 환경 대기 (13)
- 1105/16-04: 고침 → 일부 (16)
- 1103/15-02: 고침 → 재발 (15. 14는 CHANGELOG 부분만 보고 고쳐짐)
- 1101/10-07: 고침 → 일부 (10)
- 0929/12-03: 고침 → 일부 (12는 일부, 16은 고쳐짐. 약한 쪽)
§16보다 강하게 본 것(5건):
- 1105/14-01: 일부 → 고쳐짐 (14)
- 1105/16-01: 일부 → 고쳐짐 (16)
- 1103/04-01: 일부 → 고쳐짐 (04. 남은 틈은 완료 기준 밖의 잔여 위험)
- 1101/15-01: 남김 → 고쳐짐 (15)
- 1101/15-04: 남김 → 일부 (15)
표기만 다른 것(1건):
- 1105/12-03: 매뉴얼 PR에 포함 → 남음 (12. 고친 커밋은 PR #6 브랜치에만 있다. §16.4도 PR B에는 없다고 적었다)
§16과 다르지 않지만 적어 둘 것:
- 1103/03-01은 §16.5대로 일부다. 08 영역이 §16.5에 없는 남은 것 둘을 더 적었다(선언하지 않은 code, VD-04 결정 5).
- 1103/09-03의 §16.5 "백엔드로 넘김"을 09 영역은 "일부 · 백엔드로 넘김"으로 적었다. 남은 것이 백엔드 쪽이라는 같은 뜻이다.
- 1105/12-01의 §16.2 D4가 PR A로 적은 기준선 `67082cc`는 PR B(`c3c595f`)로 들어왔다(12 영역). 기록 오류이고 지금 상태는 맞다.
- 0925/06-05는 §16에 없다. 지난 영역 문서의 남음을 06 영역이 일부로 올렸다.
### 13.3 §16.6이 빠뜨린 열린 이월 (36건)
§16.6은 "영역 문서 2절 '남음'"을 모은다고 적었다. 아래는 영역 문서 2절이 열려 있다고 적었는데 §16.6에 없던 것이다. 지금도 모두 열려 있다(1101 R4만 고쳐짐이라 뺐다).
- 01 (4): 1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05. FOLLOW-UP 셋과 1103/01-02 함께 볼 것 하나도 ID 없이 남았다.
- 02 (1): 0929/02-03.
- 03 (2): 1101/03-04, 0929/03-02.
- 05 (6): 0929/05-01, 1101/05-06, 0929/05-05, 0929/05-06, 0929/05-07, 0929/05-10.
- 06 (8): 0925/06-05, 0925/06-08, 0925 P3, 1101/06-03, 1101/06-05, 1101 R1, 1101 R2, 1101 R3.
- 08 (2): 0929/08-01, 0929/08-08.
- 09 (2): 0925 FOLLOW-UP 09-07, 0925 FOLLOW-UP 09-08.
- 11 (3): 0929/11-02, 0929/11-05, 0929/11-07. FOLLOW-UP 둘도 있다(하나는 06의 0925 P3와 같은 항목).
- 13 (8): 1101/13-03, 0929/13-02, 0929/13-03, 0929/13-04(= R-3), 0929/13-05, 0929/13-06, 0929/13-10, R-2.
- 10: ID 없는 작은 이월 다섯(13.5절).
### 13.4 상태 표
| ID | 지난 §16 판정 | 지금 상태 | 근거·남은 것 | 판정한 영역 |
|---|---|---|---|---|
| [1105/01-01](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | 202 `REJECTED`가 `FILE_REJECTED`·`NOT_APPLIED`가 되고(`fileserver-upload.ts:681-689`), 빈 파일은 `FILE_EMPTY`다. 실제 백엔드 업로드는 하지 않았다. 남은 진단 빈틈은 새 01-01 | 01 |
| [1105/01-02](01-adapters-browser-transfer.md) | 고침 · 백엔드로 넘김 | 일부 · 백엔드로 넘김 **(판정 정정)** | `TRANSFER_TIMEOUT`이 `NOT_APPLIED` 목록에서 빠졌다(`fileserver-upload.ts:194-199`, 01-R2 검출). 남은 것: Fileserver code 표와 202 state 해석이 pin 대조 밖이다(`check-backend-contract-drift.ts`에 Fileserver 0건). 커밋 `471b001` 본문의 백엔드 방법 (b)는 보장을 주지 못한다(`BlockingTransferExecutor.java:72-79`) | 01 |
| [1105/01-03](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | Envelope 실패가 `traceId`를 싣는다(`fileserver-upload.ts:701-708`, 테스트 18행) | 01 |
| [1105/01-04](01-adapters-browser-transfer.md) | 고침 | 고쳐짐 | FS4'·FS5·FS8 변이가 각각 기대한 테스트에서 실패했다(01-R1·R3·R4) | 01 |
| [1105/02-01](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | label 진단 한 건을 `toEqual`로 고정한다(`runtime-adapters-product-scope-participants.test.ts:160-197`), 02-R9 검출. 09 영역: 조립 쪽 발견 없음. 작은 잔여: label 중복을 막지 않는다 | 02, 09 |
| [1105/02-02](02-adapters-browser-files-cache.md) | 고침 | 일부 **(판정 정정)** | asset entry는 다시 stage로 고친다. release marker 본문이 계속 읽히지 않으면 stage가 다시 쓰지 않고 rollback 대상이 돌아오지 못한다(`public-response-cache-adapter.ts:463-468`, 02-R1 X1·X2). 설계 문서와 포트 주석이 범위를 넓게 적는다(`cache-storage-ports.ts:66-69`) | 02 |
| [1105/02-03](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | 레시피 주석이 매뉴얼과 같은 파일을 가리킨다(`browser-file-session-capability.ts:21-33`), 02-R8 검출 | 02 |
| [1105/02-04](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | 표 테스트 6행(`public-response-cache-repair.test.ts:541-597`). 변이 넷 검출, `INTEGRITY_FAILED` 변이는 동등 변이 | 02 |
| [1105/03-01](03-adapters-http-state.md) | 고침(BREAKING) | 고쳐짐 | 6.1절 "쓰기 뒤 가능" 플랫폼 code 20개를 조립이 거절한다(`external-contract-runtime.ts:638-663`), 03-R4~R6 검출 | 03 |
| [1105/03-02](03-adapters-http-state.md) | 고침 · 백엔드로 넘김 | 고쳐짐 · 백엔드로 넘김 | 503 `RATE_LIMIT_*` 둘이 `NOT_APPLIED`다(`backend-envelope.ts:177-181`), 03-R7 검출. 이 수정이 새 03-01의 길을 넓히고 03-02를 만들었다 | 03 |
| [1105/04-01](04-adapters-realtime.md) | 고침 | 고쳐짐 | 조합 transport `OFFLINE` 테스트 둘(`realtime-reconnect-coordinator.test.ts:2206`, `:2246`), MR1 검출(04-R1) | 04 |
| [1105/04-02](04-adapters-realtime.md) | 고침(BREAKING) | 고쳐짐 | 던지는 `execute`가 재시도 없이 `PROTOCOL_MISMATCH`다(`bounded-poll-coordinator.ts:336-347`). reconnect가 반대로 읽는 것은 새 04-01 | 04 |
| [1105/04-03](04-adapters-realtime.md) | 고침 | 고쳐짐 | VD-28·설계 3절이 V3 descriptor 규칙을 적는다(`VD-28-…md:117-120`). V2 칸 `git grep` 0건 | 04 |
| [1105/05-01](05-adapters-storage-kernel.md) | 고침 | 고쳐짐 | recipe 키가 registry `physicalKey`다(`oidc-pkce-session-owner.ts:51-52`). 글자 회귀는 테스트가 못 잡는다. `orphanExemptRows` 추가는 게이트 결과를 바꾸지 않는다(05-R4) | 05 |
| [1105/06-01](06-adapters-service-worker-push.md) | 고침 | 고쳐짐 | 수집기가 `BUILD_ASSET_DIRECTORY` 아래만 본다(`generate-service-worker-assets.ts:73-75`) | 06 |
| [1105/06-02](06-adapters-service-worker-push.md) | 일부 | 일부 · 결정 대기 | redirect FAIL과 live 분기 함수 테스트가 들어왔다(06-R2 검출). 워커 없는 빌드의 probe 범위는 결정 대기이고, 이제 redirect까지 넓어졌다(`hosting-probe.ts:327`) | 06 |
| [1105/06-03](06-adapters-service-worker-push.md) | 고침 | 고쳐짐 | 옛 탭 route test가 chromium·webkit에서 통과하고, 워커 fallback을 끊으면 두 엔진이 잡는다(06-R1) | 06 |
| [1105/07-01](07-contracts.md) | 고침 | 고쳐짐 | 답 표를 pin 커밋 표 사본과 행마다 대조한다(`backend-contract-pin.test.ts:165-179`, 07-R2). desktop drift rc=0(07-R3). 사본 ↔ 실제 백엔드는 게이트 밖(D6) | 07 |
| [1105/07-02](07-contracts.md) | 고침 | 고쳐짐 | 응답 행이 `REJECT_UNKNOWN`으로 좁혀지면 breaking이다(`registry-compatibility.ts:149-161`), 07-R1 registries-rc=1. 두 칸 없는 행은 새 07-02 | 07 |
| [1105/08-01](08-presentation.md) | 고침 | 고쳐짐 | 복구 뒤 포커스가 feedback 자리로 간다(`use-app-form.ts:123-135`), e2e 3엔진, 08-R3 검출. 다시 마운트한 폼은 새 08-01 | 08 |
| [1105/08-02](08-presentation.md) | 고침 | 고쳐짐 | 확인 뒤 목록으로 이동한다(`create-feature-write-slice.ts:724-731`). 짝 백엔드 목록 GET 없음은 1103/03-07 | 08 |
| [1105/08-03](08-presentation.md) | 고침 | 고쳐짐 | 셸과 홈이 `activeNavigationRoutes` 하나를 쓴다(`navigation-policy.ts:14-21`), 08-R4 검출. 공유 청크는 새 요청 단계를 만들지 않는다 | 08 |
| [1105/08-04](08-presentation.md) | 고침 | 고쳐짐 | 다른 저장 중 버튼을 끄고 진행 문구를 보인다(`reference-resource-form-page.tsx:60-61`), 08-R5 검출 | 08 |
| [1105/09-01](09-app-core.md) | 고침(PR A) | 고쳐짐 | 탐침이 제품 파일을 옆 이름으로 옮겨 덧붙인다(`product-extension-typecheck.test.ts:267-281`), 09-R1 검출 | 09 |
| [1105/09-02](09-app-core.md) | 고침 | 고쳐짐 | 조립 루트가 `notifySessionUnauthenticated`를 준다(`runtime-adapters.ts:705`), 09-R2 검출. 그 한 줄을 뺀 제품을 막는 검사는 없다(`CHANGELOG.md:107`) | 09 |
| [1105/09-03](09-app-core.md) | 고침 | 고쳐짐 | 원인이 한 번 나온다(`check-registries.ts:160-168`, `registry-governance.test.ts:656-711`) | 07, 09 |
| [1105/10-01](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `createRuntimeContractHttpExecutor`로 뺐다(`runtime-adapters.ts:284-319`). H53·L02 검출(10-R1·R2), 샘플 제거 사본에서 돈다 | 10 |
| [1105/10-02](10-tests-fast-layers.md) | 고침 | 고쳐짐 | interaction signal까지 감시한다(`http-execution-v3.test.ts:812-867`), R2b 검출(10-R3) | 10 |
| [1105/10-03](10-tests-fast-layers.md) | 제안으로 남김 | 남음(제안) | 변이 도구를 들이지 않았다. 10 영역은 세지 않고 오케스트레이터 몫으로 두었다 | 10 |
| [1105/11-01](11-tests-browser-release-scale.md) | 고침 | 고쳐짐 | 판정을 `browserFailureVerdict` fixture로 빼고 증명 spec이 기록 줄을 대조한다(`preload-use.spec.ts:180-202`). 변이 셋을 3엔진이 잡는다(11-R1) | 11 |
| [1105/12-01](12-guardrails-ci.md) (+ 1105/11-02) | 고침(PR A) | 일부 · 실행 환경 대기 **(판정 정정)** | **영역이 갈렸다.** 12는 고쳐짐: 사전 점검이 `bwrap … /bin/true`를 띄워 이유와 함께 멈춘다(`check-system-test-prerequisites.ts:39-43`, `FE-GATE-013.txt`). 11은 일부: 허용 호스트 PASS는 가짜 호스트 단위 테스트뿐이고, provider test 6건은 여전히 원인 없이 시간 초과다(`ci-artifact-contract.test.ts:1782`, `:1812`). 약한 쪽을 쓴다 | 12, 11 |
| [1105/12-02](12-guardrails-ci.md) | 고침 | 고쳐짐 | 짝 백엔드 참조를 pin 커밋 트리에서 찾는다(`verify-documentation-readiness.ts:245-285`) | 12 |
| [1105/12-03](12-guardrails-ci.md) | 매뉴얼 PR에 포함(PR B 없음) | 남음 | `CLAUDE.md:23`이 그대로 명령 11개다. `e9d9c36`은 PR #6 브랜치에만 있다. `README.md:343`도 손 목록이다 | 12 |
| [1105/12-04](12-guardrails-ci.md) | 고침 | 일부 **(판정 정정)** | e2e 두 실행은 한 checkout에서 함께 통과했다(오케스트레이터 드릴, 222+222). 완료 기준의 게이트 단위("FE-GATE-008 둘을 동시에")는 닫히지 않았다. `ci:gate`와 증거 검사가 루트 `dist`·`artifacts/`를 읽는다(`README.md:362-363`, M1). 수정이 새 12-02를 만들었다 | 12 |
| [1105/13-01](13-build-release-supply-chain.md) | 고침(PR A) | 일부 · 실행 환경 대기 **(판정 정정)** | `if: always()` upload 단계와 계약이 들어왔다(`quality-gates.yml:210-223`, `ci-gates.ts:1159-1219`). 파일 쪽은 CI env로 확인했다(13-R1). release run의 산출물은 runner가 없어 미확인. 거절된 run의 advisory 기록 누락은 새 13-01 | 13 |
| [1105/13-02](13-build-release-supply-chain.md) | 고침 | 고쳐짐 | `release_gate`가 `product_merge_gate`를 기다린다(`generate-ci-workflow.ts:68-78`). `check:ci`가 연결 없는 workflow를 거절한다. 실제 Gitea의 `needs` 처리는 미확인 | 13 |
| [1105/14-01](14-template-product-docs.md) | 일부 | 고쳐짐 **(판정 정정)** | 완료 기준 셋을 확인했다. 문서 검사 예외(`verify-documentation-readiness.ts:190-208`, 14-R2), 드릴 PASS 17 checks(14-R1), `PRODUCT.md:33`. 드릴이 게이트 밖인 것은 통제 잔여 | 14 |
| [1105/14-02](14-template-product-docs.md) | 고침 | 고쳐짐 | 매뉴얼 블록을 사본에서 tsc로 본다(`manual-paired-backend-settings.test.ts:112-144`), 14-R4 검출 | 14 |
| [1105/14-03](14-template-product-docs.md) | 고침 | 고쳐짐 | 경로를 다시 백틱으로 적었다. 파일 이름을 바꾸면 `verify:documentation`이 실패한다(14-R3) | 14 |
| [1105/15-01](15-performance.md) | 고침 | 고쳐짐 | 요약 전후에 같은 칸을 그린다(`platform-overview-page.tsx:63-78`). 직접 진입 CLS 표본 0 × 5 | 15 |
| [1105/15-02](15-performance.md) | 고침 | 고쳐짐 | 허용치가 256 B다(`measure-feature-shape-growth.ts:219-227`). +448 B 빌드에서 대조가 실패했다(15-R2) | 15 |
| [1105/15-03](15-performance.md) | 고침 | 고쳐짐 | 목록이 한 곳이다(`vite-build-inputs.ts:11-21`) | 15 |
| [1105/15-04](15-performance.md) | 일부 | 일부 · 결정 대기 | lab이 기능 라우트를 500 ms로 잰다(402 ms). 진입 두 묶음은 결정 대기. 더 남은 것: 생성 라우트가 모두 `session-required`라 lab 대상이 못 된다(`create-feature.ts:578`) | 15 |
| [1105/15-05](15-performance.md) | 고침 | 고쳐짐 | `scrollbar-gutter: stable`(`base.css:6-11`), 18회 모두 shift 0(15-R3). 가림막·header 띠는 새 08-03 | 15 |
| [1105/16-01](16-structure-patterns.md) | 일부 | 고쳐짐 **(판정 정정)** | 완료 기준의 둘째 길을 채웠다. 03 A절과 정본 표가 두 파일과 충돌 처리 명령을 적고(`03-outside-feature-folder.md:36-44`), `feature-tracked-files.test.ts`가 대조한다. 충돌 자체는 결정 대기(`CHANGELOG.md:97`) | 16 |
| [1105/16-02](16-structure-patterns.md) | 고침 | 고쳐짐 | pin `scaffoldSources` 여섯 항목(`backend-contract-pin.json:8-39`)을 drift가 본다. drift는 게이트 밖 | 16 |
| [1105/16-03](16-structure-patterns.md) | 결정 대기 | 남음 · 결정 대기 | 드릴 제외 목록이 그대로다(`feature-scaffold-drill.ts:18-46`). 손으로 돌린 `test:a11y`는 69건 통과(16-R4). CI 장치는 없다 | 16 |
| [1105/16-04](16-structure-patterns.md) | 고침 | 일부 **(판정 정정)** | `tests` 쪽은 고쳤다(`feature-residue.ts:46-60`, 16-R2 PASS). `src`·`dist`는 여전히 대소문자 무시 부분 문자열이다(`feature-residue.ts:45-56`). `product-feature`로 11단계 rc=1, 템플릿 파일 20개(16-R3). 좁힌 `tests` 판정의 빈틈은 새 16-01 | 16 |
| [1103/01-01](01-adapters-browser-transfer.md) | 일부 · 백엔드로 넘김 | 일부 · 백엔드로 넘김 | 프론트 몫은 끝났다. 백엔드 매뉴얼에 안내가 없고(`45d2a478:docs/manual/03-placement.md:30`), 백엔드 계약은 202 `VERIFYING`만 적는다(`docs/fileserver/http-contract.md:10`). 짝 백엔드 업로드는 하지 않았다 | 01 |
| [1103/03-01](03-adapters-http-state.md) | 일부(결정 대기) | 일부 · 결정 대기 | 거절 문구 자리 `refusalMessages`가 생겼다(`use-app-form.ts:50-59`, 08-R6). 남은 것: 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼(`backend-envelope.ts:271-276`). 08이 §16.5에 없는 둘을 더 적었다. 선언하지 않은 code가 "변경됨으로 확인"으로 "저장했습니다."가 된다. 선언한 409를 필드 오류로 바꿔 VD-04 결정 5와 어긋난다(`VD-04-native-form-facade.md:26`). Medium·P2 | 03, 08 |
| [1103/03-02](03-adapters-http-state.md) | 결정 대기 | 일부 · 결정 대기 | `meta.page`는 읽는다. bulk `results` 미지원은 계약 4.1에 적혀 있다(`backend-api-and-server-state-contract.md:205-207`) | 03 |
| [1103/03-07](03-adapters-http-state.md) | 결정 대기 | 일부 · 결정 대기 | 백엔드 생성기가 `POST`와 `GET /{id}`만 만든다(`__Feature__Controller.java.tmpl:49`, `:63`) | 03 |
| [1103/05-01](05-adapters-storage-kernel.md) | 고침 | 고쳐짐 | 끝까지 돈 purge는 늘 partition 삭제다(`opfs-byte-store-adapter.ts:900`, `:926-929`). 05-R1 50/50, 05-R2 Chromium·Firefox 24/24, 되돌리면 8건 실패(05-R3) | 05 |
| [1103/07-04](07-contracts.md) | 고침 | 고쳐짐 | 부팅 오류가 키 경로를 싣는다(`env.ts:125-170`, `load-runtime-config.ts:126-137`) | 07 |
| [1103/09-03](09-app-core.md) | 백엔드로 넘김 | 일부 · 백엔드로 넘김 | 쿠키 모드 401은 1105/09-02로 고쳤다. 실제 Keycloak·Redis는 돌리지 않았고, pin realm에 public client가 없다(`ca-skeleton-realm.json` 59·62행) | 09 |
| [1103/09-04](09-app-core.md) | 결정 대기 | 일부 · 결정 대기 | `EXAMPLES_PLATFORM`이 플랫폼 레지스트리에 있다(`routes.ts:33-45`). 예제 라우트를 쓰는 브라우저 spec 8개 그대로 | 09 |
| [1103/09-05](09-app-core.md) | 일부 | 일부 | `ProductComposition.serviceWorker`로 blockers·observe를 잇는다(`product-composition-contract.ts:127-139`, 09-R3 검출). 활성화 화면 자리가 없다. realtime·worker·offline은 `optional-runtime-host.ts:55-65`에서 거절된다 | 06, 09 |
| [1103/11-01](11-tests-browser-release-scale.md) | 고침(BREAKING) | 고쳐짐 | `a11y.json` schema 2에 `notChecked`가 있다(`write-a11y-report.ts:14-26`). 생성 기능 상세도 `notChecked`(11-R3). 분류를 지키는 test가 없는 것은 새 11-01 | 11 |
| [1103/11-02](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | workflow가 글꼴 넷을 설치한다(`quality-gates.yml:74`, `:113`). 깨끗한 Ubuntu 24.04에서 6/6은 돌리지 않았다 | 11 |
| [1103/11-03](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | 코드 그대로. 이 호스트에서는 provider가 뜨지 않아 `kills descendants` 단독 실행을 할 수 없다 | 11 |
| [1103/11-04](11-tests-browser-release-scale.md) | 실행 환경 대기 | 일부 · 실행 환경 대기 | 가림 코드 그대로(`run-and-validate-provider.ts:278-293`). 새 test 둘도 bwrap 오류로 실패한다 | 11 |
| [1103/12-05](12-guardrails-ci.md) | 일부 | 일부 · 결정 대기 | `e72fb6e`가 예 한 곳만 고쳤다. 지운 심볼과 1절 밖 문서 검사는 결정 대기 | 12 |
| [1103/13-03](13-build-release-supply-chain.md) | 결정 대기 | 일부 · 결정 대기 | 운영 high 2건 그대로(`package.json:160-161`, 13-R1 B `POLICY_VIOLATION`). D7 뒤 react-router 갱신(약 470 B)은 예산 안, zod(약 7 KB)는 넘는다 | 13 |
| [1103/14-01](14-template-product-docs.md) | 고침 | 고쳐짐 | 초기 파일 상한 32, 범위 끝 `8a44226`(`CHANGELOG.md:207`, `:317`, `:359`) | 14 |
| [1103/14-02](14-template-product-docs.md) | 일부 | 일부 · 결정 대기 | "옮기기 전" 수가 두 repo와 같다(`CHANGELOG.md:133-139`). memento 모양에 적용한 `check:registries`는 돌리지 않았다. 자리 없는 파일은 결정 대기 | 14 |
| [1103/15-02](15-performance.md) | 고침 | 재발 **(판정 정정)** | **영역이 갈렸다.** 14는 CHANGELOG 부분을 고쳐짐으로 봤다(`CHANGELOG.md:207`, `:317`이 32). 15는 재발: 살아 있는 문서 `performance-evidence.md:209-210`이 템플릿 초기 파일을 26으로 적는다. 지금은 27이다(`feature-shape-ceilings.json:63`). 약한 쪽을 쓴다 | 15, 14 |
| [1103/16-01](16-structure-patterns.md) | 고침(BREAKING) | 고쳐짐 | `responseEnvelope`가 필수 칸이다(`external-contract-runtime.ts:239`). 읽기만 있는 생성 기여에서 줄을 빼도 TS1360(16-R1). bulk 안내 한 줄은 새 07-01 | 07, 16 |
| [1103/16-05](16-structure-patterns.md) | 고침(BREAKING) | 고쳐짐 | brand 타입 `MutationOperationId`(`server-state.ts:276-278`). `@ts-expect-error`가 FE-GATE-003에서 쓰였다. 이행 안내의 빈칸은 새 09-01 | 09, 16 |
| [1103/16-06](16-structure-patterns.md) | 결정 대기 | 일부 · 결정 대기 | 화면이 읽지 않는 라우트 `title`·`navigationLabel`을 생성기가 채운다(`create-feature.ts:582-583`). 0929/08-06을 여기에 합쳤다 | 16 |
| [0929/03-03](03-adapters-http-state.md) | 고침 | 고쳐짐 | 훅이 키 없는 같은 입력을 보내지 않고(`application-query.ts:569-583`), 화면은 `=== true`일 때만 버튼을 그린다(`async-surface.tsx:227-229`). 03-R2·R3 검출. IDEMPOTENT까지 막는 부작용은 새 03-03 | 03, 08 |
| [1101/02-04](02-adapters-browser-files-cache.md) | 고침 | 고쳐짐 | host `storageArea` 비교 테스트(`cross-tab-invalidation.test.ts:392-481`), N38 검출(02-R7) | 02 |
| [0929/10-04](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `isCurrent`만 false로 바꾸는 테스트(`http-execution-v3.test.ts:574-620`), L01 검출(10-R4). 네 라운드 만에 닫혔다 | 10 |
| [0929/10-05](10-tests-fast-layers.md) | 고침 | 고쳐짐 | `test:all`이 `test:coverage`의 Vitest 경로를 모두 돈다(`package.json:85`, `test-all-paths.test.ts:20-31`) | 10 |
| [1101/10-07](10-tests-fast-layers.md) | 고침 | 일부 **(판정 정정)** | SW 5초 대기는 8 ms가 됐다. RPC는 1초를 자는 3개가 여전히 1.03~1.07 s다(`browser-rpc-remediation.test.ts:389`, `:412`, `:588`). 수정이 이미 빠른 3개에 시계를 넣었다. 이 수정이 marker 상한을 넓힌 것은 새 06-02 | 10 |
| [0929/12-03](12-guardrails-ci.md) | 고침 | 일부 **(판정 정정)** | **영역이 갈렸다.** 16은 고쳐짐: `support/`·`contracts/` → `src/adapters` 직접 간선이 막혔다(fixture 31). 12는 일부: 계층 밖 폴더 → 자기 기능 `adapters/` → `src/adapters`의 두 단계 경로가 `check:architecture`·ESLint를 통과한다(12-R3, `.dependency-cruiser.json:309-311`). 16도 대표 판정을 12에 두었다. 약한 쪽을 쓴다 | 12, 16 |
| [1101/14-02](14-template-product-docs.md) | 고침 | 고쳐짐 | 리뷰 ID 네 꼴(`CHANGELOG.md:11`)을 `changelog-review-ids.test.ts:36-49`가 막는다 | 14 |
| [0929/14-05](14-template-product-docs.md) | 고침 | 고쳐짐 | `ci-quality-gates.md:69`가 코드와 같다 | 14 |
| [1103/04-01](04-adapters-realtime.md) | 일부 | 고쳐짐 **(판정 정정)** | 원래 완료 기준(`retryBudget > 0` 거절, poll 3회 = 요청 3회)을 채운다. `27e3dec`가 생성 때 잡은 객체를 `input.operation`으로 넘긴다(`bounded-poll-coordinator.ts:149-150`, `:322-328`). 조합 코드가 그것을 무시하면 3배가 되는 것은 잔여 위험(`CHANGELOG.md:103`) | 04 |
| [0929/02-02](02-adapters-browser-files-cache.md) | 일부 | 일부 · 결정 대기 | 비용과 `verified`의 뜻이 포트 주석에 있다(`cache-storage-ports.ts:55-70`), M05 검출(02-R6). `inspect()`에 signal이 없고 판정 불가와 손상이 같은 `false`다 | 02 |
| [0929/14-01](14-template-product-docs.md) | 일부 | 일부 | `SPEC.md`·`tasks/`의 이유를 맞췄다. 더 남은 것: 읽는 곳 없는 추적 산출물 13개(`artifacts/tests/coverage-gateway/` 10, `artifacts/local-preview/*.png` 3) | 14 |
| [0929/14-02](14-template-product-docs.md) | 일부 | 일부 | 범위 반영 명령을 적었지만(`README.md:396-404`) 돌리지 않았다. 기준점 형식이 둘이고 `:407`·`:408`·`:418-419` 문장이 어긋난다 | 14 |
| [0929/14-03](14-template-product-docs.md) | 일부 | 일부 | 두 제품의 수정 파일 분류는 빠짐이 없다. README 표와 충돌 경로 측정은 없다 | 14 |
| [1101/02-02](02-adapters-browser-files-cache.md) | 결정 대기 | 일부 · 결정 대기 | `browser-files/` 변경 0줄. media type과 확장자 짝을 보지 않는다(`browser-file-policy-registry.ts:448-456`) | 02 |
| [0929/02-06](02-adapters-browser-files-cache.md) | 결정 대기 | 남음 · 결정 대기 | 예외가 배럴 전체를 연다(`.dependency-cruiser.json:261`). 쓰는 것은 `import type` 하나 | 02 |
| [0929/04-02](04-adapters-realtime.md) | 결정 대기 | 남음 · 결정 대기 | SSE 코드 diff 0줄. 도구는 `readSseForReconnect` 하나(`fetch-sse-connection.ts:498-513`), EOF 분류 미정 | 04 |
| [0929/04-03](04-adapters-realtime.md) | 결정 대기 | 남음 · 결정 대기 | `sse-parser.ts:330-341` 그대로. 설계 5.3·6.3과 다르다 | 04 |
| [0929/14-06](14-template-product-docs.md) | 결정 대기 | 남음 · 결정 대기 | 첫 결함 후보가 CHANGELOG에 들어왔다(`CHANGELOG.md:139`). 받는 곳은 정하지 않았다 | 14 |
| [1101/14-07](14-template-product-docs.md) | 결정 대기 | 남음 · 결정 대기 | `docs/README.md:67-79`가 그대로 섞여 있다 | 14 |
| [1101/10-05](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | 커졌다. 도구·import 없는 파일이 `tests/unit` 시간의 76%(지난 71%), 합 133.1 → 175.7 s | 10 |
| [1101/10-06](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | 한 머지에 `tests/unit` 13번 그대로. FE-GATE-020 1,156 → 1,237 s | 10 |
| [1101/10-08](10-tests-fast-layers.md) | 결정 대기 | 남음 · 결정 대기 | `scopeSnapshot` 4벌, `as never` 10곳, `deferred()` 7벌 | 10 |
| [0929/12-07](12-guardrails-ci.md) | 결정 대기 | 남음 · 결정 대기 | 스키마가 `script`·`reason`뿐이다(`ungated-scripts.ts:17-30`) | 12 |
| [0929/12-01](12-guardrails-ci.md) | 남김 | 남음 | `check-request-fanout.ts:23`, `:109` 그대로 | 12 |
| [0929/12-04](12-guardrails-ci.md) | 남김 | 남음 | 기준선(`contract-baseline.json:6-8`)과 테스트 상수(`ci-workflow-generation.test.ts:199-203`) 두 곳 | 12 |
| [0929/12-05](12-guardrails-ci.md) | 남김 | 남음 | `package.json:182`의 `dependency-cruiser`를 쓰지 않는다 | 12 |
| [0929/12-06](12-guardrails-ci.md) | 남김 | 남음 | `ungated-tests.ts:18`, `:94-95`. Vitest는 `*.test.*`만 돈다 | 12 |
| [1101/12-03](12-guardrails-ci.md) | 남김 | 남음 | 디자인 규칙 파일에 커밋 0개 | 12 |
| [1101/15-01](15-performance.md) | 남김 | 고쳐짐 **(판정 정정)** | 완료 기준 둘을 채운다. FE-GATE-012가 merge에 있고 예산+1 fixture가 통과한다. 문서가 숫자 대신 기록을 가리킨다(`performance-evidence.md:22-25`). 여유 문제는 D7이 정했고 그 판단은 새 15-01 | 15 |
| [1101/15-03](15-performance.md) | 남김 | 남음 | 초기 JS 파일만 더한다(`check-bundle.ts:38-47`). CSS 8.81 kB gzip, 라우트 lazy 합 예산 없음 | 15 |
| [1101/15-04](15-performance.md) | 남김 | 일부 **(판정 정정)** | SW 5초 대기는 `ce191be`로 사라졌다(64건 320 ms). `tests/setup.ts:1-2`의 RTL 전역 로드와 자식 프로세스 테스트가 남았다 | 15 |
| [0929/11-04](15-performance.md) | 남김 | 남음 | 부하는 기록만 한다(`test-performance.ts:244`). 기능 라우트 예산으로 같은 크기의 판정이 하나 늘었다 | 11, 15 |
| [1101/16-05](16-structure-patterns.md) | 남김 | 남음 | 오류 경계 두 벌, `TelemetryPort` 두 타입, 폐기 재수출(`application/result.ts:9`) | 16 |
| [1101/16-06](16-structure-patterns.md) | 남김 | 남음 | 생성기가 기능 `contracts/`에 mapper·문구를 쓴다(`create-feature.md:50-53`) | 16 |
| [1101/01-03](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | copyFactor가 설정값이다(`runtime-policy.ts:12`, `:68`) | 01 |
| [0929/01-03](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | 업링크 기본값이 세 곳이다(`resumable-upload-runtime.ts:1045-1049`, `fileserver-upload.ts:164-165`) | 01 |
| [0929/01-04](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | `check-adapter-inventory.ts:139-144`가 4파일을 이름으로 고정한다 | 01 |
| [0929/01-05](01-adapters-browser-transfer.md) | §16.6에 없음 | 남음 | `abort()` recovery의 행동 표가 없다(`resumable-upload.ts:105-127`) | 01 |
| [0929/02-03](02-adapters-browser-files-cache.md) | §16.6에 없음 | 남음 | CHANGELOG 0.2.0 browser-files [계약] 행의 경로가 틀리다(`CHANGELOG.md:418`) | 02 |
| [1101/03-04](03-adapters-http-state.md) | §16.6에 없음 | 남음 | 효과 판정과 화면 분류가 두 함수다(`backend-envelope.ts:352-363`, `:390-410`) | 03 |
| [0929/03-02](03-adapters-http-state.md) | §16.6에 없음 | 남음 | `x-correlation-id` CORS 허용이 문서뿐이다(`backend-api-and-server-state-contract.md:257-267`) | 03 |
| [0929/05-01](05-adapters-storage-kernel.md) | §16.6에 없음 | 일부 | 손상 chunk reference 행이 reconcile을 멈춘다(③, `indexeddb-opfs-journal.ts:855-862`). purge는 이제 영향을 받지 않는다 | 05 |
| [1101/05-06](05-adapters-storage-kernel.md) | §16.6에 없음 | 일부 | Web Storage W2·W5·W6를 보는 테스트가 없다(`browser-storage-codec.ts:204-206`) | 05 |
| [0929/05-05](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | 전체 삭제 조건이 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`) | 05 |
| [0929/05-06](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1930`) | 05 |
| [0929/05-07](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | canonical JSON 3벌, `sameScope` 2벌(`opfs-prepared-object.ts:138` 등) | 05 |
| [0929/05-10](05-adapters-storage-kernel.md) | §16.6에 없음 | 남음 | journal DB 접두사를 바꿀 수 없다(`indexeddb-opfs-journal.ts:131`) | 05 |
| [0925/06-05](06-adapters-service-worker-push.md) | §16.6에 없음(지난 영역 문서 남음) | 일부 | observe는 제품이 잇는다(1103/09-05). 업데이트 설치 실패와 `health()`는 이어지지 않았다(`service-worker-page-controller.ts:328-349`) | 06 |
| [0925/06-08](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음(영향 넓어짐) | `assets/`가 상수 하나(`src/contracts/service-worker.ts:126`)지만 Vite `build.assetsDir`와 이어지지 않는다. 1105/06-01 뒤 사전 캐시 수집기도 이 상수를 읽는다 | 06 |
| [0925 P3](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | SW update spec의 route chunk 변경을 helper 옵션으로(`service-worker-update.spec.ts:54-72`). 11 영역의 FOLLOW-UP과 같은 항목이다 | 06, 11 |
| [1101/06-03](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | PAGE_HELLO·UPDATE_READY·reload guard가 흔적만 남았다(`service-worker-protocol.ts:16`, `:18`) | 06 |
| [1101/06-05](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받는다(`service-worker-static-assets.ts:279-284`) | 06 |
| [1101 R1](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `retainedPreviousCaches`를 `void`로만 참조한다(`service-worker-lifecycle.ts:169`) | 06 |
| [1101 R2](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `validateActiveFence` 두 벌(`push-event-adapter.ts:196`, `notification-click-adapter.ts:356`) | 06 |
| [1101 R3](06-adapters-service-worker-push.md) | §16.6에 없음 | 남음 | `SYNC_WAKE_OBSERVED`만 프로토콜 버전을 숫자로 쓴다(`service-worker-entry.ts:170`) | 06 |
| [1101 R4](06-adapters-service-worker-push.md) | §16.6에 없음 | 고쳐짐 | `ce191be`(1101/10-07)가 가짜 시계로 바꿔 8 ms다. 실효 상한을 넓힌 것은 새 06-02 | 06 |
| [0929/08-01](08-presentation.md) | §16.6에 없음 | 남음 | 제품이 지원 locale을 선언할 곳이 없다(`message-contract.ts:8-13`) | 08 |
| [0929/08-08](08-presentation.md) | §16.6에 없음 | 남음 | 로그인 복귀 주소가 라우터 기준 경로다(`session-provider.tsx:99`) | 08 |
| [0925 FOLLOW-UP 09-07](09-app-core.md) | §16.6에 없음 | 일부 | 샘플 제거 드릴이 브라우저 테스트를 돌지 않는다(`test-sample-removal.ts:443-448`). 예제 제거 드릴은 게이트 밖 | 09 |
| [0925 FOLLOW-UP 09-08](09-app-core.md) | §16.6에 없음 | 남음(허용한 대안) | local-draft ABA를 주석으로 닫았다(`local-draft.ts:2-11`) | 09 |
| [0929/11-02](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없다(`drill-runbook.ts:245`) | 11 |
| [0929/11-05](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음(미검증) | 규모 기준선이 2026-11-01 `373b27b` 측정이다(`feature-shape-growth.json:3`) | 11 |
| [0929/11-07](11-tests-browser-release-scale.md) | §16.6에 없음 | 남음 | 빌드 helper 두 벌(`fixture-builds.ts:55`, `service-worker-builds.ts:177`) | 11 |
| [1101/13-03](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | provider job에 namespace 요구 주석·점검이 없다(`quality-gates.yml:228`, `:274`). 이 desktop에서 provider 18건이 bwrap 원문으로 끝났다 | 13 |
| [0929/13-02](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | `.env*` 빌드 변수를 번들과 스크립트가 다르게 읽는다(`vite.config.ts:19`, `:193-194`) | 13 |
| [0929/13-03](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | 청크 이름이 선언 없이 계약처럼 쓰인다(`generate-build-manifest.ts:70-78`, fail-closed) | 13 |
| [0929/13-04](13-build-release-supply-chain.md) (= R-3) | §16.6에 없음 | 남음 | CSP가 6벌이고 내용 검사가 없다(`security-headers.json:4` 등) | 13 |
| [0929/13-05](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | SBOM이 `deduped` 노드를 따라가지 않는다(`dependency-baseline.json:5778-5781`) | 13 |
| [0929/13-06](13-build-release-supply-chain.md) | §16.6에 없음 | 일부 | live probe가 루트가 아닌 URL을 거절한다(`hosting-probe.ts:453-456`) | 13 |
| [0929/13-10](13-build-release-supply-chain.md) | §16.6에 없음 | 남음 | "unmodified checkout" 문구 그대로(`README.md:421-426`) | 13 |
| [R-2](13-build-release-supply-chain.md) (13) | §16.6에 없음 | 남음 | 빌드 입력 기본값이 다섯 곳이다(`env.ts:54-55`, `:204-205`, `generate-runtime-config.ts:77-78` 등) | 13 |
### 13.5 ID 없는 이월 (10건, 모두 남음)
| 항목 | 영역 | 지금 상태 | 근거 |
|---|---|---|---|
| FOLLOW-UP: `maxPartCount` 바이트 검사가 transport에 넘길 때만 | 01 | 남음 | `fetch-json-transport.ts:157-167` |
| FOLLOW-UP: 업로드 PUT에 idle 제한 없음 | 01 | 남음(문서화된 선택) | 바뀌지 않았다 |
| FOLLOW-UP: probe 재사용 테스트가 공개 이미지만 씀 | 01 | 남음 | `image-cdn-runtime.test.ts:196`, `:311`, `:383` |
| 1103/01-02와 함께 볼 것: object store CORS의 `Retry-After` expose | 01 | 남음 | `server-file-capability-infrastructure.md:1666-1673` |
| FOLLOW-UP: Firefox SW quarantine | 11 | 남음(만료 2027-03-31) | 빠지는 test가 3 → 4개(`service-worker-update.spec.ts:306`) |
| `test:platform`만 `--no-file-parallelism`, 이유 없음 | 10 | 남음 | `package.json:141` |
| `--passWithNoTests` 3곳 | 10 | 남음 | `package.json:50`, `:58`, `:81` |
| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | 10 | 남음 | `tests/setup.ts:1-2`, setup 누적 50.73 s |
| (지난 R6) `typescript-tooling-smoke` 두 파일 | 10 | 남음 | `tests/unit/typescript-tooling-smoke.test.ts`, `tests/component/typescript-tooling-smoke.test.tsx` |
| `tsc-diagnostics-parser.test.ts` 제외 사유 | 10(12 몫) | 남음 | `config/ci/ungated-tests.json:25` |
## 14. 오케스트레이터 확인
### 1105/12-04 완료 드릴(`bbde570`)
- 실행: `R5-01-1204-drill`, 2026-11-06 04:06~04:10, 234초. 한 checkout에서 run ID가 다른 e2e 둘을 동시에 돌렸다.
- 부분 spec 둘(`compact-smoke`, `preload-use`): 두 실행 모두 rc=0, 19 passed.
- 전체 e2e: 두 실행 모두 rc=0, 222 passed·4 skipped.
- 두 실행 모두 "already used" 0줄, 자기 `dist/`·build manifest·`results.xml`·report를 가졌고, 포트가 달랐다(41159/46739, 33661/35167).
- 판정: **일부.** 메인 세션이 정한 완료 기준(한 checkout에서 e2e 두 실행이 함께 돌고 둘 다 통과)은 충족한다. 지난 리뷰의 완료 기준(FE-GATE-008 둘, 또는 FE-GATE-008과 FE-GATE-005를 함께 돌려 둘 다 통과하고 증거 파일이 섞이지 않는다)은 충족하지 않는다. 두 `ci:gate` 실행은 아직 저장소 루트의 `dist`·`artifacts/`를 함께 쓰고, 그 제한은 문서로만 적혀 있다(`README.md:362-363`, 12 영역). 12-04 수정이 12-02를 만들었다.
## 15. 새 발견 색인 (25건)
심각도·우선순위 순이고, 같은 칸 안에서는 영역 번호 순이다. 영역 문서 3절에 36.3 양식이 있다.
- 영역 문서가 적은 새 발견은 27건이다. 같은 결함 둘을 합쳐 25건으로 센다.
- 10-02는 12-01과 같은 결함이다. 제거 fixture의 문서 테스트 목록이 테스트 파일을 통째로 뺀다.
- 16-02는 07-01과 같은 결함이다. 계약 문서 4.1절의 bulk 줄 "`responseEnvelope`를 빼고"다. 16 영역도 07-01로 한 번 센다고 적었다.
- 심각도: High 이상 0 · Medium 1 · Low 24. 우선순위: P1 이상 0 · P2 2 · P3 23.
- 성격: 확인된 결함 13 · 구조적 위험 9 · 개선 제안 3 · 미검증 0.
- 지난 조치가 만들거나 남긴 것(영역 문서 근거 칸 기준):
- 만든 것: 01-01(1105/01-01), 03-01의 길 일부와 03-02(1105/03-02 `c6c37f3`), 03-03(0929/03-03 `683ccfb`), 04-01(1105/04-02 `05330e3`), 04-02(1103/04-01 `27e3dec`가 권한 `input.operation` 경로), 06-02(1101/10-07 `ce191be`), 08-01(1105/08-04 뒤 다시 마운트 경로), 08-03(1105/15-05 `e02f252`), 09-01(1103/16-05 `48c1ab7`), 10-01·12-01(§16.3 통합 수정), 11-01(1103/11-01 `757d1c7`의 분류에 지키는 test가 없음), 12-02(1105/12-04 `f4d5761`), 13-01(1105/13-01이 새로 쓴 문장), 14-01(PR B CHANGELOG 새 절), 14-02·15-01(D7 `287dc6f`), 16-01(1105/16-04 `b45d6a0`).
- 남긴 것: 07-01(1103/16-01 BREAKING `56272e8`이 같은 절의 이 줄을 고치지 않음), 05-01(`dc7c95b`가 행을 더하고 문서는 고치지 않음).
- 지난 라운드들이 보고하지 않은 기존 경로: 02-01, 06-01, 07-02, 08-02.
판정이 갈린 것(합치지 않고 적어 둔다):
- 10-01: 12 영역 2.2절은 같은 두 변경(`playwright-run-isolation.test.ts`의 `HAS_CAPABILITIES`, `vite-build-inputs.test.ts`의 `existsSync`)을 "약화 아님"으로 봤다. 15 영역 1105/15-03 행도 `vite-build-inputs` 쪽을 "약해진 검사가 아니다"로 봤다. 10 영역은 템플릿에서 이름이 바뀔 때의 검출 공백으로 셌다.
- 12-01: 07 영역 4절 27번은 같은 제외를 "드릴에 필요한 검사를 빼지 않았다. 개선 여지(세지 않음)"로 봤다. 10·12 영역은 구조적 위험으로 셌다. 셋 다 지금 놓친 결함은 없다고 적는다.
| ID | 심각도·우선순위 | 성격 | 내용 | 관련 관점 | 위치 | 합친 것 |
|---|---|---|---|---|---|---|
| [03-01](03-adapters-http-state.md) | Medium·P2 | 확인된 결함 | KEYED 결과 불명의 같은 키 재전송이 429·503 `RATE_LIMIT_*`·보내기 전 실패로 끝나면 훅이 결과 불명과 키를 버린다. 생성 폼의 "다시 시도"가 새 키로 보낸다(03-R1 `keys=["key-1","key-1","key-2"]`) | 6, 12, 28, 17, 10, 5 | `src/presentation/adapters/query/application-query.ts:599-604`, `:667-672`; `src/presentation/forms/use-app-form.ts:305-314`; `scripts/create-feature-write-slice.ts:716-719`; `src/adapters/http/backend-envelope.ts:177-181` | |
| [14-01](14-template-product-docs.md) | Low·P2 | 확인된 결함 | 새 미출시 절 BREAKING 1~3단계의 설명 셋이 코드·다운스트림과 다르다. 3단계 "부팅이 멈춘다"(실제는 기능 라우트 첫 진입), 1단계가 TechLog를 "감싸지 않는 백엔드"로 적음, 2단계가 `requiresIdempotencyKey` 재계산을 말하지 않음 | 17, 23, 24, 20 (30.4) | `CHANGELOG.md:24-26`; `src/features/installed-contract-contributions.ts:93-111`; `src/contracts/server-state.ts:303-311`; tech-log `studio-management-server-state.ts:209` | |
| [01-01](01-adapters-browser-transfer.md) | Low·P3 | 개선 제안 | 202 `REJECTED` 실패(`FILE_REJECTED`)에 성공 Envelope의 `traceId`가 없고, 백엔드 답에는 거절 이유가 없어 서버 기록과 잇지 못한다 | 8, 7, 23, 17, 26 | `src/adapters/http/fileserver-upload.ts:681-689`, `:787-800`; `src/adapters/http/backend-envelope.ts:97-117`; 백엔드 `UploadedFileResponse.java:11-29` | |
| [02-01](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | active pointer 본문이 계속 읽히지 않으면 activation·cleanup·inspect·조회가 모두 멈추고, adapter API 안에서는 돌아올 길이 없다(02-R1 X3) | 28, 6, 18, 24, 11 | `src/adapters/cache-storage/public-response-cache-adapter.ts:714-730`, `:813-819`, `:885-893`, `:246-254`, `:1041-1064` | |
| [03-02](03-adapters-http-state.md) | Low·P3 | 확인된 결함 | 계약 6.1절은 rate-limit 503에 "자동 재전송은 없다"고 적지만 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. 그 경로의 테스트가 없다 | 17, 23, 10, 5 | `docs/architecture/backend-api-and-server-state-contract.md:342`; `src/adapters/http/http-execution-v3.ts:1116-1138`, `:1786`; `CHANGELOG.md:61` | |
| [03-03](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 0929/03-03의 두 가드가 키 유무로만 갈라서, IDEMPOTENT 쓰기도 결과 불명 뒤 재전송과 같은 입력 재제출이 막힌다 | 28, 23, 22, 24, 12 | `src/presentation/adapters/query/application-query.ts:574-583`, `:853-867`; `src/contracts/server-state.ts:309-312` | |
| [04-01](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | reconnect coordinator는 던지는 `attempt`·`waitClosed`를 서버 장애로 재시도한다. `05330e3` 뒤 poll은 같은 던짐을 `PROTOCOL_MISMATCH`로 끝내고, 규칙은 어디에도 적혀 있지 않다. endpoint 설정 오류가 fetch 0회로 3번 재시도되고 `PROVIDER_UNAVAILABLE`(EXHAUSTED)로 끝난다(04-R2) | 23, 8, 24, 5, 6 | `src/adapters/realtime/reconnect-coordinator.ts:766-774`, `:954-961`; `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:1764-1770` | |
| [04-02](04-adapters-realtime.md) | Low·P3 | 개선 제안 | 권하는 `input.operation`은 `InstalledHttpContract<unknown, unknown, unknown>`이라 실행기 호출의 입력·출력 타입이 사라진다. V3 결과 9종 → poll 결과 대응표가 없고, 유일한 예는 SUCCESS 외 전부를 retryable `PROVIDER_UNAVAILABLE`로 바꾼다 | 20, 22, 17, 3 | `src/application/policies/bounded-polling.ts:41-45`; `src/adapters/realtime/polling/bounded-poll-coordinator.ts:119`; `tests/unit/realtime/bounded-poll-coordinator.test.ts:1153-1165` | |
| [05-01](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | 저장소 설계 문서가 registry 행 8개 중 4개만 "현재 등록되어 있다"고 적는다 | 9, 4, 15, 23, 5 | `docs/architecture/client-cache-and-storage.md:50-52`, `:1406-1407`; `docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md:66`; `src/contracts/storage-keys.ts:41-157` | |
| [06-01](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | live probe가 `/service-worker.js`의 같은 origin redirect를 통과시킨다. 브라우저는 워커 스크립트 redirect를 거절해 등록·업데이트·`REMOVE_REGISTRATION`이 실패할 수 있다 | 18, 21, 28, 5 | `scripts/lib/hosting-probe.ts:135`, `:142-157`; `docs/operations/release-cache-rollback.md:66-67` | |
| [06-02](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함(약해진 검사) | 1101/10-07 수정이 marker 읽기 시간 상한 test의 실효 상한을 10초에서 20초로 넓혔다. 상한을 15초로 올린 변이에서 64건이 모두 통과했다(06-R3) | 10, 21 | `tests/unit/service-worker-runtime.test.ts:2029-2034`; `src/adapters/service-worker/service-worker-lifecycle.ts:558` | |
| [07-01](07-contracts.md) | Low·P3 | 확인된 결함 | 계약 문서 4.1절이 bulk 엔드포인트에 "`responseEnvelope`를 빼라"고 적는다. 빼면 `check:types`가, 같은 기여에 `"NONE"`을 적으면 조립이 실패한다(1103/16-01 BREAKING 뒤 남은 줄) | 20, 9, 23, 17, 4 | `docs/architecture/backend-api-and-server-state-contract.md:205-207`; `src/contracts/external-contract-runtime.ts:239`, `:709-720` | 16-02(같은 줄, 영역 16) |
| [07-02](07-contracts.md) | Low·P3 | 구조적 위험 | 스키마 메타 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 정책 테스트가 건너뛰어, 응답 DTO를 strict로 바꿔도 `check:registries`·`test:unit` 어느 쪽도 보지 않는다 | 17, 21, 10, 20 | `tests/unit/schema-metadata-policy.test.ts:130`, `:157`; `config/contracts/registry-governance.json:263`; `src/contracts/schema-registry.ts:17-18` | |
| [08-01](08-presentation.md) | Low·P3 | 확인된 결함 | 다시 마운트한 참조 폼이 자기가 시작하지 않은 저장의 끝을 보이지 않는다. "변경됨으로 확인" 뒤 결과 문구가 없고 포커스가 `body`다(08-R1) | 28, 24, 1, 6, 10, 22 | `src/presentation/forms/use-app-form.ts:231-235` vs `:402-408`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:147-193` | |
| [08-02](08-presentation.md) | Low·P3 | 확인된 결함 | 생성 기능 작성 폼이 저장 중에 떠난 사용자를 저장이 끝나면 상세 화면으로 옮긴다(08-R7) | 1, 23, 28, 10, 20 | `scripts/create-feature-write-slice.ts:636-655` | |
| [08-03](08-presentation.md) | Low·P3 | 확인된 결함 | `scrollbar-gutter: stable`의 15 px 띠를 drawer·모달 가림막과 header가 칠하지 않는다. 새 골든이 이 띠를 고정했다(08-R2) | 1, 23, 10, 5 | `src/presentation/styles/theme/base.css:6-11`; `src/presentation/styles/theme/primitives.css:416-419`; `src/presentation/styles/theme/shell.css:45-57` | |
| [09-01](09-app-core.md) | Low·P3 | 확인된 결함 | 1103/16-05 이행 안내가 HTTP descriptor 없는 뮤테이션(Fileserver 업로드 등)과 테스트 fixture의 길을 말하지 않고, 매뉴얼 01이 손 ID의 실패 시점을 두 가지로 적는다 | 20, 17, 4, 9, 5 (30.4) | `CHANGELOG.md:25`; `docs/manual/01-add-a-feature.md:476`, `:499-500`; `src/contracts/server-state.ts:294-313`; `tests/helpers/mutation-operation-id.ts:11-15` | |
| [10-01](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 통합 수정이 새 테스트 둘의 검사를 "대상 파일이 있으면"으로 정했다. 드릴 사본에서 8개가 말없이 사라지고, 템플릿에서 이름을 바꿔도 같다. skip 차단은 이를 보지 못하고 주석의 근거 ID도 틀렸다 | 10, 21, 27, 23, 5, 24 | `tests/unit/playwright-run-isolation.test.ts:27-44`, `:243-252`; `tests/unit/vite-build-inputs.test.ts:19-22`, `:49-56` | |
| [11-01](11-tests-browser-release-scale.md) | Low·P3 | 구조적 위험 | `a11y.json`의 `notChecked` 분류를 지키는 test가 없고 기록 없는 라우트를 "검사함"으로 센다. spec의 기록 호출 한 줄을 바꾸면 상세 라우트가 다시 passed로 세지고 rc=0이다(11-R2) | 10, 21, 5 | `tests/e2e/accessibility.spec.ts:77-84`; `scripts/lib/a11y-data-state.ts:50`, `:61`; `scripts/contracts/release-artifacts.ts:853-868` | |
| [12-01](12-guardrails-ci.md) | Low·P3 | 구조적 위험 | 제거 fixture가 문서를 읽는 테스트를 파일째 뺀다. 그래서 capability 드릴 사본 셋에서 `backend-contract-pin.test.ts`의 문서 무관 14건과 `feature-tracked-files.test.ts`의 1건이 돌지 않는다. 목록 검사는 주석 한 줄로 통과한다 | 10, 21, 27, 24, 17, 5 | `scripts/lib/removal-fixture.ts:70-81`; `tests/unit/backend-contract-pin.test.ts:150-253`, `:259`; `tests/unit/removal-fixture.test.ts:161` | 10-02(같은 결함, 영역 10) |
| [12-02](12-guardrails-ci.md) | Low·P3 | 확인된 결함 | 셸에 `RUN_OUTPUT_ROOT`가 있으면 빌드는 `.tmp/` 아래에 쓰고 `check:bundle`은 루트의 이전 빌드로 판정한다. 예산을 3,504 B 넘는 빌드가 PASS했다(12-R2) | 21, 19, 5, 23, 20 | `scripts/build-frontend.ts:51`; `scripts/generate-supply-chain.ts:144`, `:156`; `scripts/check-bundle.ts:24-29`; `scripts/run-ci-gate.ts:189-206` | |
| [13-01](13-build-release-supply-chain.md) | Low·P3 | 확인된 결함 | FE-GATE-027의 공개 대상 승인이 거절되면 advisory 검사가 돌지 않아, 그 run의 증거에 advisory 기록이 없다. 문서는 결과와 상관없이 올린다고 적는다(13-R1 C) | 5, 8, 23, 16 | `config/ci/gates.json:2212-2213`; `scripts/run-ci-gate.ts:176-190`; `docs/operations/ci-quality-gates.md:169-173`, `:540-544` | |
| [14-02](14-template-product-docs.md) | Low·P3 | 확인된 결함 | D7 커밋 `287dc6f` 본문이 `bbde570` 이력에 없는 다시 쓰기 전 해시 `ab0d4a1`·`7ce9bf1`을 가리킨다. CHANGELOG·커밋 본문의 해시를 대조하는 장치가 없다 | 9, 24, 21 (30.4) | `git show 287dc6f`; `scripts/verify-documentation-readiness.ts:165` | |
| [15-01](15-performance.md) | Low·P3 | 구조적 위험 | 초기 JS 예산 상향(D7)이 드릴 초과분 665 B의 세 배(2,048 B)를 올렸다. 폭의 근거와 다시 내릴 조건이 없어, 다음 1,383 B는 어느 merge 게이트도 멈추지 않는다 | 21, 14, 13, 5, 10 | `config/performance/budgets.json:4`; `docs/operations/performance-evidence.md:44-53`; `tests/unit/performance-budgets.test.ts:106-136` | |
| [16-01](16-structure-patterns.md) | Low·P3 | 구조적 위험 | 제품 기능 제거 드릴이 `tests` 잔여를 파일 이름·import로 좁혔다. 안전망으로 든 `test:all`은 Playwright spec을 돌지 않아, spec 본문의 기능 ID를 아무 검사도 잡지 않는다. 매뉴얼·주석은 "`test:all`이 잡는다"고 적는다 | 21, 10, 27, 8 | `scripts/lib/feature-residue.ts:18-20`, `:57-60`; `docs/manual/01-add-a-feature.md:662`; `vitest.config.ts:45`; `package.json:85` | |