From e85c8361b68f75d6e8f5651da4a41f545f83b7c9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 20:52:21 +0900 Subject: [PATCH 1/5] =?UTF-8?q?docs(review):=202026-11-05=204=EB=9D=BC?= =?UTF-8?q?=EC=9A=B4=EB=93=9C=20=EC=84=B1=EC=88=99=EB=8F=84=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20=EA=B8=B0=EB=A1=9D?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 2026-11-03 리뷰의 조치가 main(409d72e)에 들어간 뒤 전체를 다시 봐야 한다. 지난 README 14.4절의 상태 판정("그 밖의 81건 고침")과, 조치가 검사를 약하게 했는지는 아무도 확인하지 않았다. 가이드 기준으로 16개 영역을 다시 리뷰했다. 기준은 8a44226(= main 409d72e 트리)이다. desktop에서 merge 단계 14개(workflow env)와 CLAUDE.md 게이트 목록을 직접 돌렸다. 실험은 게이트가 끝난 뒤 78항목을 한 묶음으로 하나씩 돌렸고, 항목마다 checkout을 기준 커밋으로 되돌렸다. 처음에는 영역마다 따로 실행했으나 공유 잠금에 30여 건이 줄을 서서 취소했다(README 11.4절). 결과: 새 발견 48건(High 0, Medium 11, Low 37 / P1 3, P2 15, P3 30). P1은 09-01, 12-01, 13-01. 지난 96건은 고쳐짐 74, 일부 22이고, 14.4절이 고침이라 한 13건을 일부로 바로잡았다. merge 게이트는 13/14 통과, FE-GATE-013은 호스트 user namespace 제한으로 실패한다. 위험·한계: 실제 Gitea 러너와 짝 백엔드 연동은 확인하지 못했다(README 8절). 리뷰라 코드는 고치지 않았다. 영역 문서의 실행 기록 일부는 리뷰 세션 scratchpad 경로를 가리킨다. 검증: desktop에서 이 커밋으로 documentation-readiness, deletable-history-documents, changelog-review-ids 테스트와 verify:documentation(옆 백엔드 checkout 없이)을 돌렸다. Refs: docs/reviews/2026-11-05-maturity-review/README.md --- .../01-adapters-browser-transfer.md | 281 ++++++++++ .../02-adapters-browser-files-cache.md | 297 ++++++++++ .../03-adapters-http-state.md | 205 +++++++ .../04-adapters-realtime.md | 232 ++++++++ .../05-adapters-storage-kernel.md | 242 +++++++++ .../06-adapters-service-worker-push.md | 229 ++++++++ .../07-contracts.md | 213 ++++++++ .../08-presentation.md | 255 +++++++++ .../2026-11-05-maturity-review/09-app-core.md | 206 +++++++ .../10-tests-fast-layers.md | 229 ++++++++ .../11-tests-browser-release-scale.md | 263 +++++++++ .../12-guardrails-ci.md | 223 ++++++++ .../13-build-release-supply-chain.md | 218 ++++++++ .../14-template-product-docs.md | 252 +++++++++ .../15-performance.md | 299 +++++++++++ .../16-structure-patterns.md | 276 ++++++++++ .../2026-11-05-maturity-review/README.md | 507 ++++++++++++++++++ 17 files changed, 4427 insertions(+) create mode 100644 docs/reviews/2026-11-05-maturity-review/01-adapters-browser-transfer.md create mode 100644 docs/reviews/2026-11-05-maturity-review/02-adapters-browser-files-cache.md create mode 100644 docs/reviews/2026-11-05-maturity-review/03-adapters-http-state.md create mode 100644 docs/reviews/2026-11-05-maturity-review/04-adapters-realtime.md create mode 100644 docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md create mode 100644 docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md create mode 100644 docs/reviews/2026-11-05-maturity-review/07-contracts.md create mode 100644 docs/reviews/2026-11-05-maturity-review/08-presentation.md create mode 100644 docs/reviews/2026-11-05-maturity-review/09-app-core.md create mode 100644 docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md create mode 100644 docs/reviews/2026-11-05-maturity-review/11-tests-browser-release-scale.md create mode 100644 docs/reviews/2026-11-05-maturity-review/12-guardrails-ci.md create mode 100644 docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md create mode 100644 docs/reviews/2026-11-05-maturity-review/14-template-product-docs.md create mode 100644 docs/reviews/2026-11-05-maturity-review/15-performance.md create mode 100644 docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md create mode 100644 docs/reviews/2026-11-05-maturity-review/README.md diff --git a/docs/reviews/2026-11-05-maturity-review/01-adapters-browser-transfer.md b/docs/reviews/2026-11-05-maturity-review/01-adapters-browser-transfer.md new file mode 100644 index 00000000..a3fd6bcf --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/01-adapters-browser-transfer.md @@ -0,0 +1,281 @@ +# 영역 01 — adapters: browser-transfer + +> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `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`(1103/01-01 수정, 지난 README 14.2 D1) +> 짝 백엔드: `clean-architecture-backend-template` `45d2a478`(읽기만. `config/contracts/backend-contract-pin.json:5`의 pin) +> 깊게 본 관점: 6, 10, 17, 20, 21, 23, 28 +> 영역 판정(35.8): presigned 실행기·vault는 **지정 범위에서 사용 가능**. resumable upload runtime은 **조건부 사용 가능**(제품 backend가 `PRESIGNED_MULTIPART_V1` BFF를 직접 만들 때). 짝 백엔드와 함께 파일 업로드를 출시하는 용도는 **조건부 사용 가능**(Fileserver client. 조건: 재개 없음, 파일 전체를 메모리에 읽음, 202 `REJECTED`를 읽지 못함(01-01), 504 `TRANSFER_TIMEOUT`을 자동 재전송하지 않음(01-02), `MAYBE_APPLIED` 뒤 재전송은 파일이 둘 생길 수 있음(백엔드가 키를 읽지 않음), 실제 짝 백엔드로 올려 본 적 없음). image CDN runtime은 **지정 범위에서 사용 가능**(reference runtime 범위). + +ID 표기: 이번 라운드 새 발견은 `01-01`부터 쓴다. 라운드 밖에서는 `1105/01-01`이다. 지난 라운드는 `1103/01-01`(2026-11-03), 그 전은 `1101/…`, `0929/…`다. + +## 0. 결론 + +- **1103/01-01(High·P1)은 일부 고쳐졌다.** 프론트에 짝 백엔드 Fileserver `POST /v1/files` client가 생겼다(`src/adapters/http/fileserver-upload.ts`). 요청 모양, 파트 이름, Envelope 성공·실패 본문, 크기 상한, `Retry-After`, 멱등 키 처리를 백엔드 `45d2a478` 코드와 대조했고 주된 경로는 맞다(2.1절). 프론트 문서 넷은 "presigned 레시피는 짝이 아니다"와 이 client를 가리킨다. 남은 것: 실제 짝 백엔드로 올려 본 증거가 없다(테스트는 MSW뿐), 백엔드 매뉴얼에는 안내가 없다(백엔드 repo 몫), 백엔드가 멱등 키를 읽지 않는다(백엔드 결정). 지난 README 14.4의 "고침"은 완료 기준("두 매뉴얼이 그 경로를 가리킨다")에 못 미친다. +- **새 Medium 01-01.** 백엔드는 동기 검증에서 거절된 파일을 202 `state: "REJECTED"`로 답한다. 기본 검증기 사슬에서는 0바이트 파일 하나로 닿는다. client의 schema에는 `REJECTED`가 없어 `SCHEMA_MISMATCH`(지원 문의 문구)로 끝난다(XB). 매뉴얼은 202를 "아직 검사 중"으로 적는다. 실제 202의 대부분은 `QUARANTINED`다. +- **새 Medium 01-02.** client는 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·`retryable:true`·`retryAfterMs:5000`으로 준다(XF). 매뉴얼대로면 기능이 5초 뒤 다시 올린다. 백엔드는 이 code를 작업 단계와 상관없이 대기 스레드에서 낸다. 작업 스레드가 게시·커밋 중이면 늦게 끝날 수 있다. client 주석의 "게시 전에 나는 code"라는 근거가 이 줄에는 맞지 않는다. 같은 client의 효과 표는 V3 표·계약 문서 6.1과도 갈라졌다(`IDEMPOTENCY_UNAVAILABLE`, Fileserver 4xx). pin 대조 밖이다. +- **새 Low 2건.** client가 실패 Envelope의 `traceId`를 버린다(01-03, V3는 1103/03-06에서 싣게 됐다). client 규칙 셋을 테스트가 고정하지 않는다: 바이트 비례 deadline, 읽기 전 크기 거절, 5xx `NOT_APPLIED` code 둘(01-04, 변이 FS4·FS5·FS8 생존). +- **지난 발견 재판정.** 고쳐짐 5건(1103/01-02, 1103/01-03, 1101/01-02, 0929/01-02, resumable spec 포트 고정). 일부 1건(1103/01-01). 남음 4건(1101/01-03, 0929/01-03, 0929/01-04, 0929/01-05)과 FOLLOW-UP 4건. 1103/01-03의 생존 변이 N2·N10·N17은 이번에 모두 잡혔다. N10은 네 라운드 만에 처음 잡혔다. +- **이 영역 수정이 검사를 약하게 만든 곳은 없다.** 테스트 diff는 단언 추가뿐이다. 바뀐 기대값 하나(422 `IDEMPOTENT_REQUEST_MISMATCH`)는 08-05에 맞춘 재정의다(2.2절). +- 실행: desktop 1회(`01-mutations`). 기준 실행 17파일 330건 통과. 변이 14건 중 11건 검출. 복원 `restored: clean at 8a442262`. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. `src/adapters/browser-transfer/` 27파일 12,919줄. 포트 `src/application/ports/browser-transfer/` 5파일 821줄. 새 client `src/adapters/http/fileserver-upload.ts` 735줄과 배럴 export(`src/adapters/http/index.ts:44-56`). 단위 테스트 15파일 + fixture 3파일 11,865줄, 통합 테스트 `tests/integration/fileserver-upload.test.ts` 557줄 | +| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree에서 읽기만 했다. 실행은 desktop checkout(같은 커밋)에서 helper로 했다. `e40684b..8a44226`의 이 영역 커밋: `3af2c8ea`(1103/01-03 테스트), `c695898a`(1103/01-02), `af4ebacb`(1103/01-01 문서), `274ae690`(1101/01-02), `af7d0b18`(0929/01-02), `f8005493`(Fileserver client), `ed499736`(spec 포트), `20a5b084`(422 재분류), `3d3d6527`(client 입력 타입). 영역·포트·client 4파일 +792/−16 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `productionComposition: false`(`config/recipes/frontend-capability-recipes.json:155-200`). Fileserver client는 레시피가 아니라 http adapter 배럴 export이고, 제품이 capability로 넘겨 기능 adapter가 만든다(`docs/manual/02-decision-tables.md:326-389`) | +| 필수 요구와 규모·운영 목표 | 사용자 목표: 짝 백엔드 템플릿과 함께 서비스를 빨리 출시한다. 업로드 크기·실패율 목표는 없다. 백엔드 기본 상한(`max-file-size 100MB`, `fileserver.yml:12-13`)과 프론트 기본 정책값(`runtime-policy.ts:60-81`)을 사실상의 목표로 보았다 | +| 읽은 코드·구성 범위 | 전부: `fileserver-upload.ts`, 그 통합 테스트, `e40684b..8a44226` 영역 diff 전부, 매뉴얼 02 7절(`:273-396`). 필요한 부분: `resumable-upload-runtime.ts`(`stripProviderFailure`와 호출 9곳, 재조정, 스트림 해시), `presigned/http-common.ts:154-212`, `fetch-json-transport.ts:155-170`, `:560-592`, `backend-envelope.ts:118-135`, `:246-290`, `http-execution-v3.ts:1708-1725`, 계약 문서 `backend-api-and-server-state-contract.md:202`, `:308`. **짝 백엔드**(`45d2a478`): `docs/fileserver/http-contract.md` 전체, `docs/web/http-contract.md` 1·2절, `docs/storage-capability-boundary.md`, `FileUploadController.java`, `MultipartUploadRequestMapper.java`, `UploadedFileResponse.java`, `UploadFileApplicationUseCase.java`, `FinalizeUploadApplicationUseCase.java:114-135`, `:296-343`, `:360-423`, `BlockingTransferExecutor.java`, `FileserverExceptionHandler.java`, `FileserverProblemHeaders.java`, `FileserverErrorCode.java`, `FileserverFailureContext.java`, `AmbiguousCompletionException.java`, 검증기 사슬(`FileserverVerificationConfiguration.java:44-57`, `LengthVerifier.java`, `MediaTypeVerifier.java`), `EnvelopeBodyAdvice.java`, `WebAdapterAutoConfiguration.java:53`, `GlobalExceptionHandler.java:281-290`, `CorsExposedHeaders.java`, `fileserver.yml`, `FileserverCompositionIntegrationTest.java` | +| 읽은 문서(주장) | 지난 영역 문서와 README 12·13·14절, 커밋 본문 9개, `server-file-capability-infrastructure.md:1-19`, `presigned-transfer-and-image-cdn.md:14-23`, `:392-397`, `:759-764`, `docs/manual/02-decision-tables.md` 4·7절, CHANGELOG 미출시 절(`:190`, `:241`, `:249`) | +| 수행한 테스트·실험 | **실행 환경 = desktop**(`/tmp/claude-gates/r4/exp.sh`, 공유 잠금). 실행 이름 `01-mutations` 1회: ① 기준 실행 — 영역 단위 15파일 + Fileserver 통합 1파일 + 실험 파일 1개, 17파일 330건 통과 ② 실험 XA~XF(`tests/integration/zz-area01-exp.test.ts`, 실행 안에서만 만들고 지움) ③ 변이 14건(6절). 이 실행은 19:46에 시작해 `restored: clean at 8a442262`로 끝났다. 19:55의 helper 종료·대기열 취소(BRIEF-2) 전이다. 그 뒤 따로 돌린 것은 없고 배치 요청도 없다. 오케스트레이터 결과(`desktop:/tmp/claude-gates/r4/`, 6절 끝): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:integration` rc=0, merge FE-GATE-001~007·020 rc=0 | +| 실험 조건 | node vitest + MSW. 출하 client를 그대로 만들고 백엔드 응답만 흉내 냈다. 응답 모양은 백엔드 `45d2a478` 코드에서 읽은 것이다(문서가 아니라 코드). 실제 백엔드·브라우저·네트워크는 쓰지 않았다 | +| 확인하지 못한 범위·이유 | 짝 백엔드를 띄운 업로드(백엔드 repo는 읽기만, helper는 프론트 checkout용). 실제 배포에서 Fileserver 성공 본문이 Envelope로 감싸지는지(정적으로만 확인, 2.1절 3행). 0바이트 파일이 백엔드 append·finalize를 끝까지 지나는지(막는 검사가 코드에 없음을 읽었다). `TRANSFER_TIMEOUT` 뒤 작업이 늦게 끝나는 경쟁(재현 안 함). 실제 브라우저에서 Fileserver client(spec 없음). resumable 경로의 실패 뒤 재개·두 탭 경쟁(브라우저 spec은 정상 경로뿐, 이번에 돌리지 않음) | +| 이전 리뷰와 비교 가능한 범위 | 지난 발견은 지금 코드와 이번 실행으로 다시 판정했다. 지난 라운드의 X1~X5, N1~N18, 265건, 번들 측정은 증거로 쓰지 않았다. 이번 N2·N10·N17은 지난 변이와 같은 자리를 같은 방식으로 바꿨다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| 1103/01-01 (High·P1) | 두 템플릿을 짝으로 쓰면 파일 업로드가 연결되지 않는다 | **일부** | 고친 것: client `createFileserverUploadClient`(`src/adapters/http/fileserver-upload.ts:181-275`), 배럴 export(`src/adapters/http/index.ts:44-56`), 문서 넷(`server-file-capability-infrastructure.md:3-19`, `presigned-transfer-and-image-cdn.md:14-23`, 레시피 fallback `frontend-capability-recipes.json:199`, 매뉴얼 `02-decision-tables.md:273-396`). 백엔드 코드와 대조한 결과는 2.1절이다. 남은 것: ① 완료 기준의 "두 매뉴얼" 중 백엔드 매뉴얼에 안내가 없다(`docs/manual/`에 Fileserver·업로드 짝 언급 0건, 백엔드 repo 몫) ② 검증 방법 "짝 백엔드를 띄우고 업로드"를 하지 않았다. 테스트는 MSW이고, 그 MSW가 백엔드 문서에서 왔다(`tests/integration/fileserver-upload.test.ts:14-19`). 그래서 백엔드 코드의 202 `REJECTED`를 놓쳤다(새 01-01) ③ 백엔드 `POST /v1/files`가 멱등 키를 읽지 않는다(`UploadFileApplicationUseCase.java:38-41` `NOT_IDEMPOTENT`, 컨트롤러에 키 처리 없음). 프론트는 이를 적었다(`fileserver-upload.ts:93-99`, 매뉴얼 `:320-324`). 남은 부분은 High가 아니다. "연결되지 않는다"는 고쳐졌고, 남은 것은 연동 미검증과 새 발견 01-01·01-02다 | +| 1103/01-02 (Medium·P2) | 상한을 넘는 `Retry-After`에 part 단계가 `retryable:true`를 준다 | **고쳐짐** | `stripProviderFailure`가 정책을 받아 상한 밖이면 `retryable:false`로 만든다(`resumable-upload-runtime.ts:1683-1705`). 호출 9곳이 모두 정책을 넘긴다(`:575`, `:676`, `:999`, `:1079`, `:1083-1086`, `:1136`, `:1251`, `:1316`). 테스트: part 두 단계 × 429·503(`resumable-upload-runtime-recovery.test.ts:332-389`), transport 상한 30초·60초 두 조합(`:397-462`). 완료 기준(X1a·X1b `false`, X1d·X1f 같은 답)을 테스트가 그대로 본다. 변이 M0102(수정 되돌림) 5건 실패 — 검출. 남은 차이: 헤더 없는 part 단계 429는 backoff 뒤 `retryable:true`, control plane은 `false`다. 커밋 `c695898a` 본문이 범위 밖으로 적었고 완료 기준에도 없다(관점 23에 남김) | +| 1103/01-03 (Low·P3) | `Retry-After`·멱등 키 규칙 세 개를 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 셋이 더해졌다: 503 행(`resumable-upload-runtime-recovery.test.ts:333-338`), abort 키 재사용(`:625-666`), transport 헤더 없는 429(`resumable-upload-fetch-transport.test.ts:322-347`). 완료 기준대로 다시 돌렸다: N2 4건, N10 1건, N17 1건 실패 — 모두 검출 | +| 1101/01-02 (Low·P3) | `FILE_BYTE_SOURCE` 재개가 수락된 part까지 다시 해시한다 | **고쳐짐** | 수락 확인이 검증 앞으로 왔다(`resumable-upload-runtime.ts:881-883`). 테스트가 part 크기 digest 수 10을 본다(`resumable-upload-runtime-recovery.test.ts:1374-1459`). 변이 N11r(되돌림) 1건 실패 — 검출. 수락된 part는 보내지 않으므로 검증을 빼도 서버 객체는 manifest와 같다 | +| 1101/01-03 (Low·P3) | 메모리 상한 식의 copyFactor가 설정값이다 | 남음 | `runtime-policy.ts:12`, `:68`, `:101-107`. 바뀌지 않았다 | +| 0929/01-02 (Low·P3) | 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | **고쳐짐** | 삭제 결과와 상관없이 `{QUARANTINED, resourceId, replayed:true}`를 준다(`resumable-upload-runtime.ts:584-598`). 테스트가 남은 행과 다음 호출의 정리까지 본다(`resumable-upload-runtime-recovery.test.ts:757-802`). 문서도 고쳤다(`presigned-transfer-and-image-cdn.md:392-397`). 변이 N18(되돌림) 1건 실패 — 검출 | +| 0929/01-03 (Low·P3) | 느린 업링크 설정이 runtime 정책과 실행기에 따로 있다 | 남음 | `resumable-upload-runtime.ts:1047`, `presigned-transfer-executor.ts:140-145`. Fileserver client도 같은 기본값을 글자로 복사했다(`fileserver-upload.ts:141-142`). 다른 경로라 이 발견의 범위를 넓히지는 않는다 | +| 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:103-133`). 닫힌 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`는 `e40684b` 뒤 바뀌지 않았다(`:196`, `:311`, `:383`이 `publicAsset()`) | +| FOLLOW-UP: `resumable-upload.spec.ts` `PAGE_ORIGIN` 포트 고정 | — | **고쳐짐** | 설정의 `baseURL`에서 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:5-10`, `ed499736`) | +| 1103/01-02 함께 볼 것: object store CORS의 `Retry-After` expose가 handoff 문서에 없다 | — | 남음 | `server-file-capability-infrastructure.md:1668-1673`은 receipt 헤더만 적는다. 짝 백엔드는 자기 응답에 expose한다(`CorsExposedHeaders.java:27-36`) | +| 1103 D3: `issuePartCapability` 포트 주석에 "`PERMISSION_DENIED`는 `NONE`" 한 줄 | — | 안 함 | `resumable-upload.ts:215`에 주석이 없다. 결정 권고였고 발견은 아니다 | + +1103 라운드의 이 영역 발견은 README 12절의 3건(01-01·01-02·01-03)이다. 10.3절에 합친 항목과 13절 추가는 이 영역에 없다. + +### 2.1 1103/01-01 수정을 짝 백엔드 `45d2a478` 코드와 대조 + +| 항목 | 짝 백엔드(코드) | 프론트 client | 판정 | +| --- | --- | --- | --- | +| 경로·요청 | `POST /v1/files`, `consumes multipart/form-data`, `produces application/json`(`FileUploadController.java:98-103`) | base 아래 `v1/files`(`fileserver-upload.ts:307-310`), `content-type: multipart/form-data; boundary=…`, `accept: application/json`(`:227-234`) | 맞다 | +| 파트·파일 이름·타입 | `@RequestParam("file")`. 이름이 비면 `upload.bin`. part의 Content-Type은 주장이다(`MultipartUploadRequestMapper.java:18-33`). `application/octet-stream` 주장은 검증기가 받아들인다(`MediaTypeVerifier.java`의 `FALLBACK`) | 파트 `file`, 기본 이름 `upload.bin`, 기본 타입 `application/octet-stream`(`:139-147`, `:440-444`). 이름의 `"`·CR·LF는 escape(`:434-438`) | 맞다 | +| 성공 본문 | 컨트롤러는 `UploadedFileResponse` 7필드를 돌려준다(`UploadedFileResponse.java:11-29`). 배포 구성에서는 `EnvelopeBodyAdvice`가 감싼다(`WebAdapterAutoConfiguration.java:53`, `EnvelopeBodyAdvice.java:76-93`) | `readSuccessEnvelope` 뒤 7필드 schema, 모르는 필드는 버림(`:191-202`, `:621-635`) | 정적으로 맞다. 백엔드 자신의 조립 테스트는 advice 없는 좁은 context에서 감싸지 않은 모양을 읽는다(`FileserverCompositionIntegrationTest.java:217`, `:486-505`). 실제 감싸짐을 본 테스트는 두 repo에 없다(미검증) | +| 201·202 | `READY`면 201, 그 밖의 모든 state는 202(`FileUploadController.java:195-200`). 업로드는 동기 검증이다(`FinalizeUploadRequest(…, false)`, `:185`). 그래서 202는 `QUARANTINED`(이름·타입 불일치·스크립트), `REJECTED`(악성 아닌 거절), `VERIFYING`(검증기 RETRY)이다(`FinalizeUploadApplicationUseCase.java:300-343`). 문서는 "202 VERIFYING"만 적는다(`docs/fileserver/http-contract.md:10`) | enum `READY`·`UPLOADED`·`VERIFYING`·`QUARANTINED`(`:194`), 201⇔`READY` 검사(`:627`) | **어긋남** — 202 `REJECTED`를 읽지 못한다(새 01-01) | +| 크기 상한 | servlet `max-file-size 100MB`·`max-request-size 110MB`가 Fileserver 정책과 같은 placeholder다(`fileserver.yml:12-13`, `:55-56`). servlet 상한은 413 `PAYLOAD_TOO_LARGE`(`GlobalExceptionHandler.java:281-290`), 선언 길이 정책은 413 `FILE_TOO_LARGE`(`CreateUploadApplicationUseCase.java:172-176`). 0바이트는 `LengthVerifier`가 REJECT(`LengthVerifier.java:35-36`) | `maxFileBytes` 필수, 기본값 없음(`:338`). 선언 크기가 크면 읽기 전에 `FILE_TOO_LARGE`(`:424-428`). 413·415·422(불일치 제외)는 `VALIDATION_REJECTED`(`:663-667`). 하한은 없다(XA: 0바이트도 보낸다) | 대체로 맞다. 서버 413 code는 둘인데 주석은 "server's code for the same refusal"(`:426`)이라 적는다(XD). 0바이트는 새 01-01 | +| 멱등 키 | 업로드 use case는 `NOT_IDEMPOTENT`이고 executor를 거치지 않는다(`UploadFileApplicationUseCase.java:38-41`). 키 헤더는 무시된다 | 키가 있으면 `Idempotency-Key` 헤더로 보낸다(`:231-233`). 스스로 다시 보내지 않는다(`:53-54`). 백엔드가 읽지 않는다고 적었다(`:93-99`, 매뉴얼 `:320-324`) | 맞게 적었다. 재전송 중복 위험은 백엔드 결정으로 남는다 | +| 실패 본문·효과 | Envelope + `details.ambiguous`·`reconciliationRequired`(`FileserverExceptionHandler.java:52-66`). 모호하지 않은 실패는 업로드를 취소한다(`UploadFileApplicationUseCase.java:77-82`). 게시 뒤 실패는 `AMBIGUOUS_COMPLETION`으로 바꾼다(`FinalizeUploadApplicationUseCase.java:405-420`, `AtomicMoveContentPublisher.java:89-95`, `:113-120`). 단, `TRANSFER_TIMEOUT`은 대기 스레드가 작업 단계와 상관없이 낸다(`BlockingTransferExecutor.java:64-79`) | `ambiguous` → `MAYBE_APPLIED`, 4xx → `NOT_APPLIED`, 정한 5xx 여섯 → `NOT_APPLIED`, 그 밖 → `MAYBE_APPLIED`(`:163-179`, `:691-704`) | 단일 업로드에서 대부분 맞다. `TRANSFER_TIMEOUT` 한 줄은 근거가 없다(새 01-02) | +| `Retry-After` | 재시도 가능한 409·429·503·504에 code별 초(`FileserverProblemHeaders.java:30-37`, `:48-53`). CORS로 노출(`CorsExposedHeaders.java:27-36`) | 읽고, 상한 30초를 넘으면 버리고 `retryable:false`(`:650-680`) | 맞다. 1103/01-02와 같은 규칙이다 | +| 인증·CORS | `file:upload` 권한(`fileserver.yml:23-27`), `access-policy: required`(`:80`), CORS 허용 헤더 `*`(`security.yml:51`) | 인증 프로필의 `credentials`, 프로필이 허락한 증명 헤더만(`:221-226`, `:536-560`) | 프론트 쪽은 맞다. 세션 owner는 09 영역 몫 | +| 문서 | — | 상태 줄·안내 넷이 맞게 바뀌었다(위 1행). 남은 틀림: 매뉴얼 `:289`, `:311`이 202를 "`VERIFYING` 등, 아직 검사 중"으로 적는다. SHA 표기가 `bbe944bd`다(`fileserver-upload.ts:38`, `:95`, `:161`, 매뉴얼 `:320`, `:394`). pin은 `45d2a478`이다. 두 SHA 사이 Fileserver main 코드와 `docs/fileserver/http-contract.md`는 바뀌지 않았다(`git diff --stat bbe944bd..45d2a478` 0파일) | 표기만 낡았다. 202 안내는 새 01-01 | + +### 2.2 수정이 검사를 약하게 만들었는가 + +`git diff e40684b..8a44226 -- tests/unit/resumable-upload-* tests/unit/presigned-transfer* tests/unit/image-cdn* tests/unit/upload-cancellation* tests/integration/fileserver-upload.test.ts tests/browser-capabilities/resumable-upload.spec.ts`를 읽었다. + +- 지운 단언, 넓힌 허용 목록·정규식, 새 skip, 늘린 시간 제한·예산은 없다. 단위 테스트 2파일은 +309/−10이고, 지운 10줄은 같은 단언을 더 강하게 고친 자리다(`resumable-upload-runtime-recovery.test.ts:374-383`에 `retryable:false`, `recovery` 추가). +- 바뀐 기대값 하나: `20a5b084`가 422 `IDEMPOTENT_REQUEST_MISMATCH`를 `VALIDATION_REJECTED`에서 `UNKNOWN_CLIENT_FAILURE`로 바꿨다(`fileserver-upload.test.ts:320`). 08-05(필드 목록 없는 422는 입력 오류가 아니다)에 맞춘 재정의다. 같은 커밋이 그 밖의 422를 파일 거절로 남겨 MALWARE 행(`:319`)은 그대로다. 약화가 아니다. +- spec 변경(`ed499736`)은 같은 값을 설정에서 읽게 했을 뿐이다. + +## 3. 이번 발견 (36.3) + +새 발견 4건: Medium 2 · Low 2 / P2 2 · P3 2 / 확인된 결함 3 · 구조적 위험 1. High 이상 0, P1 0. + +### 01-01 Fileserver client가 짝 백엔드의 202 `REJECTED`를 "서버 응답 모양 오류"로 읽는다 — 빈 파일 하나로 닿고, 매뉴얼은 202를 "아직 검사 중"으로 적는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(두 템플릿 사이 응답 해석 불일치) | +| 관련 관점 | 17, 6, 8, 20, 10, 24 | +| 근거 | **백엔드.** 업로드는 동기 검증이다(`FileUploadController.java:185`, `FinalizeUploadRequest.java`의 `async=false`). 검증 결과가 REJECT이고 code가 `MALWARE_REJECTED`가 아니면 예외 없이 `REJECTED` `FileView`를 돌려준다(`FinalizeUploadApplicationUseCase.java:300-343`, 백엔드 테스트 `FinalizeUploadApplicationUseCaseTest.java:132-148`). 컨트롤러는 `READY`가 아니면 모두 202다(`FileUploadController.java:195-200`). 기본 검증기 사슬의 첫 검증기는 0바이트를 `REJECT("EMPTY_CONTENT")`로 본다(`LengthVerifier.java:35-36`, 사슬 `FileserverVerificationConfiguration.java:48-56`). REJECT는 다른 판정보다 우선한다(`VerificationVerdict` 주석 "REJECT > QUARANTINE > RETRY > ACCEPT"). 0바이트를 앞에서 막는 검사는 찾지 못했다(`CreateUploadApplicationUseCase.java:172-176`은 상한만 본다). 문서는 202를 `VERIFYING`으로만 적는다(`docs/fileserver/http-contract.md:10`). **프론트.** state enum에 `REJECTED`가 없다(`fileserver-upload.ts:60`, `:194`). schema를 통과하지 못하면 `SCHEMA_MISMATCH`·`APPLIED_CONFIRMED`다(`:624-631`). 0바이트 하한은 없다(`:424-428`). 테스트는 202 `VERIFYING`만 본다(`tests/integration/fileserver-upload.test.ts:183-189`). 그 MSW는 백엔드 문서대로라고 적는다(`:14-19`). 매뉴얼은 "그 밖(202 `VERIFYING` 등)은 서버가 아직 검사 중이다"라고 적는다(`docs/manual/02-decision-tables.md:289`, `:311`). **실험.** XA: 0바이트 파일도 요청 1회를 보낸다. XB: 202 + `state:"REJECTED"` → `{ok:false, kind:"SCHEMA_MISMATCH", code:"UPLOADED_FILE_INVALID", effect:"APPLIED_CONFIRMED", httpStatus:202, userMessageKey:"error.schema_mismatch", action:"none"}`. XC(대조군): 202 `QUARANTINED` → 성공 | +| 발생 조건 | 사용자가 빈 파일을 고른다(기본 검증기 사슬). 또는 제품이 악성 아닌 이유로 REJECT하는 검증기를 더한다(예: 서명 검사). 그때마다 닿는다 | +| 영향 | 기능은 "이 파일은 거절됐다"를 "서버 계약이 깨졌다"와 구별하지 못한다. 사용자는 파일을 바꾸라는 안내 대신 응답 형식 오류 문구를 본다. `fileId`도 잃는다. 서버에는 공개되지 않은 `REJECTED` 레코드가 남고 정리 작업이 예약된다(`FinalizeUploadApplicationUseCase.java:327-333`). 데이터 손상은 없다. 별도로, 매뉴얼을 따르면 기능은 `QUARANTINED`(동기 검증의 202 대부분)를 "검사 중"으로 보여 준다. 격리 파일은 관리자 결정 전까지 내려받을 수 없으므로 화면이 끝나지 않는 대기가 된다 | +| 심각도·우선순위 | Medium · P2 — 지원 구성(짝 백엔드 기본 사슬)에서 닿고 사용자 결과가 틀린다. 범위는 거절되는 파일로 제한되고 데이터 피해는 없다. 1103/01-02(같은 범위의 잘못된 신호, Medium·P2)와 같은 급으로 맞췄다 | +| 통제·증거 | 202 state 해석: M2(일부 state만 구현) · `REJECTED`: M0(이 경로를 확인했고 받는 코드가 없다) · E1(두 repo 코드) + E2(XB) | +| 확실성과 남은 가정 | 백엔드가 202 `REJECTED`를 내는 경로는 코드와 백엔드 단위 테스트로 확정했다. 0바이트가 append·finalize를 실제로 끝까지 지나는지는 실행하지 않았다(막는 코드를 찾지 못했다). 실제 배포에서 성공 본문이 Envelope로 감싸진다는 전제는 정적 확인이다 | +| 결정의 근거 | [확인한 사실] client는 백엔드 `FileState` 일부(`UPLOADED`, `QUARANTINED`)를 문서보다 넓게 받았다. `REJECTED`만 빠졌다. [리뷰어 추론] 202 목록을 백엔드 문서에서 시작해 코드로 일부만 넓힌 결과다. 고를 선택지가 있는 문제라 아래에서 비교한다 | +| 이해 비용 | 기능 작성자는 매뉴얼 7절만 보고 202를 "검사 중"으로 처리한다. 실제 202의 뜻을 알려면 백엔드 컨트롤러·finalize·검증기 세 파일을 읽어야 한다 | +| 최소 개선 방향 | ① schema가 `REJECTED`를 받고, 202 `REJECTED`를 `VALIDATION_REJECTED` 실패(code `FILE_REJECTED`, `NOT_APPLIED`, `fileId`는 실패에 싣지 않음)로 돌려준다. 422 `MALWARE_DETECTED`를 읽는 방식과 같다 ② 0바이트는 보내기 전에 거절한다(읽기 전 크기 거절과 같은 자리) ③ 매뉴얼 `:289`, `:311`을 "202는 `VERIFYING`(검사 중) 또는 `QUARANTINED`(격리, 내려받기 불가)"로 고친다 | +| 대안 비교 | (가) 위 ①②③. (나) `REJECTED`를 성공 state로 그대로 넘긴다 — 타입 변경이 작지만 기능마다 성공 값에서 거절을 다시 찾아야 한다. (다) ②만 — 기본 사슬은 막지만 제품 검증기의 REJECT는 그대로다. (가)를 권한다. 거절을 실패로 주는 것이 413·415·422와 같은 규칙이다 | +| 단순화의 보존 조건 | 201⇔`READY` 검사(`:627`), size 일치 검사, 모르는 필드 무시(`:202`)를 유지한다 | +| 비용·부작용 | 수십 줄과 테스트 3행. `upload()` 결과가 바뀌므로 CHANGELOG [계약] 한 줄 | +| 재검토 조건 | 백엔드가 REJECT를 422로 던지도록 바꾸거나, 202 state 목록을 계약 문서에 적을 때 | +| 완료 기준 | 202 `REJECTED`와 0바이트가 `SCHEMA_MISMATCH`가 아니다. 테스트가 202 `QUARANTINED`·`REJECTED`·`VERIFYING`을 각각 본다. 매뉴얼이 `QUARANTINED`의 뜻을 적는다 | +| 검증 방법 | 통합 테스트 행 추가. 가능하면 짝 백엔드를 띄워 빈 파일 하나를 올린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규(1103/01-01 수정이 만든 결함) | + +### 01-02 Fileserver client가 504 `TRANSFER_TIMEOUT`을 "적용 안 됨, 5초 뒤 다시"로 준다 — 백엔드는 이 code를 작업 단계와 상관없이 대기 스레드에서 내고, 같은 client의 효과 표는 V3 표·계약 문서 6.1과도 갈라졌다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(늦은 완료로 파일이 둘 생기는 인과 경로가 있고, 재현은 하지 않았다). 표가 갈라진 사실은 확인했다 | +| 관련 관점 | 6, 28, 17, 23, 9, 21, 5 | +| 근거 | **이 줄.** client는 `TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에 둔다(`fileserver-upload.ts:163-170`). 근거로 "the backend raises [these] before the file is published"라고 적는다(`:154-161`). 백엔드는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가 `await-seconds`(기본 300초, `fileserver.yml:75`)가 지나면 `future.cancel(true)` 뒤 `TRANSFER_TIMEOUT`(retryable)을 던진다(`BlockingTransferExecutor.java:64-79`). 그 시점에 작업 스레드가 어느 단계인지는 보지 않는다. interrupt는 FileChannel 복사는 멈추지만, 게시(rename)와 READY 커밋(JDBC)은 멈추지 않는다(`FinalizeUploadApplicationUseCase.java:381-423`). 그래서 504 뒤에 파일이 `READY`가 될 수 있다. 백엔드는 이 code에 `Retry-After: 5`를 붙인다(`FileserverProblemHeaders.java:30-37`). **실험 XF**: 504 `TRANSFER_TIMEOUT` → `{kind:"SERVER_FAILURE", effect:"NOT_APPLIED", retryable:true, action:"retry"}`. 매뉴얼은 "`retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다"고 적는다(`02-decision-tables.md:318`). 4절 표는 `NOT_APPLIED`의 다음 전송을 "새 멱등 키"로 둔다(`:162-167`). 대조군 XE: 프록시가 준 HTML 504는 `MAYBE_APPLIED`다. **표가 갈라진 곳.** ① `IDEMPOTENCY_UNAVAILABLE`(503): client는 `NOT_APPLIED`(`:169`, 테스트 `fileserver-upload.test.ts:326`). V3 표는 `MAYBE_APPLIED`(`backend-envelope.ts:249-254`). 매뉴얼 4절은 굵은 글씨로 "`NOT_APPLIED`로 분류하지 않는다"(`02-decision-tables.md:187-206`) ② Fileserver 4xx: 계약 문서 6.1은 `MALWARE_DETECTED`·`INTEGRITY_MISMATCH`·`CONCURRENT_MODIFICATION` 등을 "쓰기 뒤 가능, `MAYBE_APPLIED`"로 적는다(`backend-api-and-server-state-contract.md:202`, `:308`). client는 4xx를 모두 `NOT_APPLIED`로 본다(`fileserver-upload.ts:702`, 테스트 `:319`). 두 문서 모두 다른 쪽을 언급하지 않는다 ③ pin 대조(`scripts/check-backend-contract-drift.ts`, `backend-contract-pin.json:5-12`)는 web 계약 §1·2·4와 `backend-envelope.ts`만 본다. Fileserver 계약과 이 표는 밖이다. 매뉴얼은 "백엔드 SHA가 바뀌면 같이 다시 본다"(`:394`)고 적었지만, pin이 `45d2a478`로 올라갈 때(`580be58`) 이 표의 SHA 표기는 `bbe944bd` 그대로다 | +| 발생 조건 | 이 줄: 전송 풀이 밀리거나 저장소·DB가 느려 한 업로드의 대기가 300초 경계에 걸리고, 그때 작업 스레드가 게시·커밋 구간에 있다. 기능이 매뉴얼대로 5초 뒤 자동으로 다시 올린다. ①은 배포가 업로드를 멱등성 executor 뒤에 둘 때만 닿는다(client 주석 `:95-98`이 말하는 구성). ②는 누군가 한 표를 다른 표에 맞출 때 | +| 영향 | 같은 파일이 두 번 `READY`가 된다. 기능은 두 번째 `fileId`만 안다. 첫 파일은 참조 없이 저장 공간과 quota를 쓴다. 업무 데이터 손상은 없다. ①②는 지금 짝 백엔드의 `POST /v1/files`에서는 결과가 달라지지 않는다. 대신 같은 백엔드 code의 효과가 템플릿 안에서 세 곳에 따로 적혀 있고 서로 다르다 | +| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 "결과 불명 작업의 재실행" 모양이지만 닿는 조건이 좁고(300초 경계의 경쟁), 피해가 중복 파일 하나로 제한된다. 백엔드 자신이 이 code를 retryable로 선언한다는 점도 반영했다. High로 올리지 않았다 | +| 통제·증거 | 효과 판정의 단일 출처: M0(세 표가 따로 있고 대조 검사가 없다) · `TRANSFER_TIMEOUT` 행: M2(구현만, 테스트 없음 — 변이 FS4 생존) · E1(두 repo 코드) + E2(XF) | +| 확실성과 남은 가정 | 대기 스레드가 단계와 상관없이 504를 낸다는 것과 커밋이 interrupt로 멈추지 않는다는 것은 코드로 확인했다. 실제로 늦게 끝나는 빈도는 재현하지 않았다. multipart 본문은 컨트롤러 전에 다 받으므로(Spring 기본 `resolve-lazily=false`) 풀 작업은 대개 짧다. 그래서 빈도는 낮다고 본다(추론) | +| 결정의 근거 | [확인한 사실] client는 백엔드 `UploadFileApplicationUseCase`의 "모호하지 않은 실패는 취소한다"를 근거로 표를 만들었다. 그 근거는 작업 스레드 안의 실패에만 맞다. [기록된 의도] V3 표는 "같은 키로 다시 보낼 것"을 결과 불명으로만 표현할 수 있어 `IDEMPOTENCY_UNAVAILABLE`를 `MAYBE_APPLIED`로 두었다(`backend-envelope.ts:249-250`). client 커밋 `f8005493`은 "효과 판정 표는 백엔드 bbe944bd 기준이다. 어긋남을 알리는 검사는 없다"고 적었다. [리뷰어 추론] 단일 업로드에서 4xx를 `NOT_APPLIED`로 보는 client 쪽 판단은 맞다. 문제는 근거가 다른 세 표가 서로를 모르는 것과, 한 줄이 근거 밖이라는 것이다 | +| 이해 비용 | Fileserver 실패의 효과를 알려면 client 표, `backend-envelope.ts` 표, 계약 문서 6.1, 백엔드 `BlockingTransferExecutor`를 함께 읽어야 한다 | +| 최소 개선 방향 | ① `TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에서 빼 `MAYBE_APPLIED`로 둔다(한 줄 + 테스트 행). 백엔드에는 "대기 시간 초과는 작업이 시작됐으면 모호한 결과"를 넘긴다 ② `IDEMPOTENCY_*`는 client가 `backend-envelope.ts`의 판정을 그대로 쓴다 ③ 계약 문서 6.1 fileserver 행에 "`POST /v1/files` 단일 업로드는 use case가 취소하므로 4xx `NOT_APPLIED`(`fileserver-upload.ts`)"를 적는다 ④ client·매뉴얼의 SHA 표기를 pin에 맞추고, pin 대조 대상에 `docs/fileserver/http-contract.md`를 더한다 | +| 대안 비교 | (가) ①~④. (나) ①만 — 위험한 줄은 없어지지만 세 표의 갈라짐은 남는다. (다) client 효과 판정을 V3 표로 통째로 바꾼다 — Fileserver 4xx가 모두 결과 불명이 되어 413·415·422 파일 거절의 화면이 나빠진다. (가)를 권한다 | +| 단순화의 보존 조건 | `ambiguous` 우선(`:701`), 4xx 파일 거절의 `VALIDATION_REJECTED`(`:663-667`), 상한 밖 `Retry-After` 규칙(`:654-657`)을 유지한다 | +| 비용·부작용 | 수 줄과 문서 몇 줄. ①은 504 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다 | +| 재검토 조건 | 백엔드가 `TRANSFER_TIMEOUT`을 작업 시작 전에만 내도록 고치거나 모호 표시를 붙일 때 ①을 되돌린다. 업로드가 멱등성 executor 뒤로 갈 때 ②를 다시 본다 | +| 완료 기준 | 504 `TRANSFER_TIMEOUT`이 `NOT_APPLIED`가 아니다. 같은 백엔드 code의 효과가 client·V3·계약 문서에서 같거나, 다른 이유가 한 곳에 적혀 있다. 변이 FS4가 실패를 만든다 | +| 검증 방법 | 통합 테스트 504 `TRANSFER_TIMEOUT` 행. drift 검사 대상 추가 뒤 `check-backend-contract-drift` 실행 | +| 담당·기한·상태 | 미정(①의 백엔드 쪽은 백엔드 소유자) · 미정 · 신규(1103/01-01 수정이 만든 결함) | + +### 01-03 Fileserver client가 실패 Envelope의 `traceId`를 버린다 — V3 실행기는 1103/03-06에서 싣게 됐다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(진단 정보 누락, 두 실행 경로 불일치) | +| 관련 관점 | 8, 23, 7 | +| 근거 | `readFailureEnvelope`는 `meta.traceId`를 함께 돌려준다(`src/adapters/http/backend-envelope.ts:118-135`, `631ce339` "실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다"). V3는 그 값을 실패에 싣는다(`http-execution-v3.ts:1712-1721`). client는 `envelope.value`만 넘기고 `envelope.traceId`를 버린다(`fileserver-upload.ts:638-640`). `envelopeFailure`와 `createFailure` 호출에 trace 값이 없다(`:668-676`). XB·XD·XF 결과에도 `traceId`가 없다(MSW가 `meta.traceId: "trace-1"`을 보냈다) | +| 발생 조건 | 업로드 실패 하나를 백엔드 로그와 맞춰 볼 때 | +| 영향 | 지원 담당이 업로드 실패를 서버 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다 | +| 심각도·우선순위 | Low · P3 — 진단 편의. 동작 피해는 없다 | +| 통제·증거 | M0(이 경로를 확인했고 싣는 코드가 없다) · E1 + E2(XB 등 결과에 없음) | +| 확실성과 남은 가정 | 코드와 실험으로 확정했다 | +| 결정의 근거 | 적용 제외 — 이미 정한 규칙(1103/03-06)을 이 경로에 적용하는 문제다 | +| 이해 비용 | 적용 제외 — 지역 누락이다 | +| 최소 개선 방향 | `envelopeFailure`에 `envelope.traceId`를 넘겨 `createFailure`의 `traceId`로 싣는다 | +| 대안 비교 | 적용 제외 — 기대 계약이 정해져 있다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄과 테스트 단언 하나 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | Envelope 실패 결과에 `traceId`가 있다 | +| 검증 방법 | 통합 테스트 실패 표에 `traceId` 단언 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 01-04 Fileserver client 규칙 셋을 테스트가 고정하지 않는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(테스트 빈틈. 규칙을 바꿔도 48건이 모두 통과한다) | +| 관련 관점 | 10, 21, 6, 14 | +| 근거 | 변이 세 건이 `tests/integration/fileserver-upload.test.ts` 48건을 모두 통과했다. **FS4**: `ATOMIC_PUBLISH_UNSUPPORTED`·`TRANSFER_TIMEOUT`을 `NOT_APPLIED_5XX_CODES`에서 뺌(`fileserver-upload.ts:163-170`). 테스트 표에 두 code 행이 없다(`:312-329`). **FS5**: deadline에서 바이트 비례 몫을 없앰(`:211-215`). 시간 초과 테스트는 작은 고정값만 본다(`:430-447`). 큰 파일이 느린 망에서 30초에 끊기는 회귀를 못 잡는다. **FS8**: 선언 크기가 `maxFileBytes`보다 큰 파일을 읽기 전에 거절하지 않게 함(`:424-428`). 읽는 중 상한 검사가 같은 code를 내서 테스트가 통과한다(`:498-510`). 그런데 이 검사가 없으면 선언 크기만큼 버퍼를 먼저 잡는다(`:448-451`) | +| 발생 조건 | 이 근처를 고치는 리팩토링. 01-02를 고칠 때도 FS4 자리를 바꾼다 | +| 영향 | 규칙이 조용히 깨질 수 있다. FS5가 깨지면 큰 파일 업로드가 기본 30초에 끊긴다. FS8이 깨지면 큰 선언 크기에 버퍼를 먼저 잡는다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 의도대로다(FS4 자리는 01-02가 따로 다룬다) | +| 통제·증거 | 세 규칙 M2(구현만, 검출 없음) · E2(변이 FS4·FS5·FS8, 6절) | +| 확실성과 남은 가정 | 변이 실행으로 확정했다 | +| 결정의 근거 | 적용 제외 — 정한 규칙을 테스트로 고정하는 문제다 | +| 이해 비용 | 적용 제외 — 지역 빈틈이다 | +| 최소 개선 방향 | ① 5xx 표에 `ATOMIC_PUBLISH_UNSUPPORTED` 행과 01-02에서 정한 `TRANSFER_TIMEOUT` 행 ② 주입한 `monotonicNow`·지연 fetch로 큰 파일이 기본 deadline을 넘겨도 끊기지 않음을 본다 ③ 선언 크기 초과에서 `stream()`이 한 번도 불리지 않음을 본다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 — 테스트 추가뿐이다 | +| 비용·부작용 | 테스트 세 건 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | FS4·FS5·FS8이 각각 한 건 이상 실패를 만든다 | +| 검증 방법 | `01-driver.mjs`의 FS4·FS5·FS8을 다시 돌린다(6절) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | O | M3 / M3 | E2(330건, 변이 11/14) | checkpoint 상태 전이·CAS는 그대로다. client는 입력 검사, 바이트 상한, deadline 하나, 고정된 결과 객체를 갖는다(`fileserver-upload.ts:368-505`). 효과 판정 변이 FS1·FS2·FS3·FS6·FS7이 잡혔다 | +| 2 | 구조적 성숙도 | O | M4 | E1, 오케스트레이터 `check:architecture` rc=0 | client는 http adapter 안 파일과 kernel(`platform/abortable-operation.ts`, `platform/retry-after.ts`)만 import한다(`fileserver-upload.ts:1-33`). 새 adapter 사이 예외가 없다. browser-file-storage 포트도 import하지 않는다(`:62-73`, `3d3d6527`) | +| 3 | 변경 용이성 | O | M3 | E2 | 1103/01-02를 한 함수(`stripProviderFailure`)에서 고쳐 두 단계·두 상한 조합이 같은 답을 낸다. 포트 타입은 바뀌지 않았다 | +| 4 | 인지 부하 | P | M2 | E1 | 업로드 경로 둘의 비교표가 매뉴얼에 생겼다(`02-decision-tables.md:295-301`). 남은 것: 같은 백엔드 code의 효과가 세 곳에 따로 있다(01-02). `maxRetryAfterMs`가 factory 셋(transport, 정책, client)에 있다 | +| **5** | 위험 가시성 | P | M2 / M2 | E1 | "짝 아님"이 문서 넷에 있다(1103/01-01 본체). 남은 것: 매뉴얼의 202 안내(01-01), client 주석의 "게시 전" 근거가 `TRANSFER_TIMEOUT`에 맞지 않음(01-02), SHA 표기 `bbe944bd` | +| **6** | 실패 성숙도 | P | M3 / M2~M3 | E2 | resumable: 상한 안 대기·상한 밖 `retryable:false`가 두 단계에서 같다. client: `ambiguous`, 모호하지 않은 실패의 취소 규칙을 백엔드 코드대로 읽는다. 남은 것: 202 `REJECTED`(01-01), `TRANSFER_TIMEOUT`(01-02), 헤더 없는 part 단계 429의 `retryable:true`(control plane은 `false`) | +| 7 | 운영 성숙도 | P | M2 | E1 | resumable은 part마다 관측 1건이다(`resumable-upload-runtime.ts:834-840`). client에는 관측 지점이 없다. 실패 값만 돌려준다. traceId도 버린다(01-03) | +| 8 | 디버깅 가능성 | P | M2 | E2 | 실패에 code·httpStatus·effect가 있다. 남은 것: traceId 누락(01-03), `REJECTED`가 `UPLOADED_FILE_INVALID`로 보임(01-01), `abort()` recovery의 뜻(0929/01-05) | +| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본: `isAbortSignal` 두 벌(`checkpoint-schema.ts:195`, `http-common.ts:231`), media type 정규식 세 벌(`checkpoint-schema.ts:26`, `presigned-capability-http-provider.ts:50`, `fileserver-upload.ts:151`), 업링크 기본값 글자 복사(`fileserver-upload.ts:141-142`), 효과 표(01-02) | +| **10** | 테스트 성숙도 | P | M3 / M3(대부분) | E2(330건, 변이 11/14) | 1103/01-03의 N2·N10·N17이 잡혔다. 이번 수정 넷(M0102, N18, N11r, FS 표)도 테스트가 붙었다. 남은 것: FS4·FS5·FS8 생존(01-04), MSW가 백엔드 문서에서 와 202 `REJECTED`를 놓침(01-01), client의 브라우저 실행 없음 | +| 11 | 데이터 성숙도 | O | M3 | E2 | 0929/01-02가 고쳐져 재조정에서 resourceId를 잃지 않는다(N18 검출). 계정 partition과 checkpoint allowlist는 그대로다 | +| 12 | 동시성 성숙도 | P | M3 / M3(탭 하나) | E2 | 바뀌지 않았다. 두 탭 같은 uploadKey 경쟁은 단위 테스트(메모리 lock)뿐이다. client는 상태가 없다 | +| 13 | 확장성 | P | M2 | E1 | 발급 요청 `2N+4`, `maxPartCount` 검사는 transport에 넘길 때만. client는 요청 하나에 파일 전체다 | +| 14 | 성능 성숙도 | P | M3 / M2 | E2 | 1101/01-02 고쳐짐(N11r 검출). 남은 것: copyFactor 설정값(1101/01-03). client는 크기 선언이 없으면 조각 보관 뒤 한 번 복사해 파일의 약 2배를 쓴다(`fileserver-upload.ts:446-499`, 문서화됨). 바이트 비례 deadline을 테스트가 고정하지 않는다(01-04) | +| 15 | 보안 성숙도 | O | M4 / M3 | E2 | resumable·presigned 경로는 바뀌지 않았다. client: `credentials`는 프로필이 정하고, 증명 헤더는 프로필에 맞춰 받고, `redirect:"error"`, `no-referrer`, `no-store`, 응답 상한, 이름 escape를 테스트가 본다(`fileserver-upload.test.ts:229-257`, `:534-548`). 이번에 이 부분 변이는 돌리지 않았다 | +| 16 | 의존성 성숙도 | O | M2 | E1 | 새 패키지 없음. multipart 본문을 직접 만든다(`FormData`·`Blob` 없음) | +| **17** | API / Contract 성숙도 | P | M3 / M2 | E1, E2 | 짝 계약이 생겼다(2.1절). 남은 것: 202 `REJECTED`(01-01), 효과 표 갈라짐과 pin 밖(01-02), `abort()` 표 없음(0929/01-05) | +| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 바꾼 빌드가 이전 checkpoint를 잇는 테스트가 기준 실행에서 통과했다. 바뀌지 않았다 | +| 19 | 설정 성숙도 | P | M2 | E1 | resumable의 두 상한 조합은 이제 결과가 같다. 남은 것: 업링크 기본값 세 곳(0929/01-03 + client), copyFactor(1101/01-03). client `maxFileBytes`를 백엔드 `max-file-size`에 맞추라는 안내가 없다(매뉴얼 예시는 20 MiB) | +| **20** | 개발자 경험 | P | M2 / M2 | E1 | 지난 X에서 올랐다. 매뉴얼 7절에 고르는 기준, 조립 예, 결과 읽기, 틀리면이 있다(`02-decision-tables.md:273-396`). 남은 것: 202 안내(01-01), tus client 없음(재개 필요 시 짝 경로 없음, 매뉴얼이 적음), 백엔드 매뉴얼에 안내 없음 | +| **21** | Guardrail 성숙도 | P | M3 | E2 | 1103/01-03 고쳐짐. 남은 것: Fileserver 계약이 pin 대조 밖(01-02), FS 생존(01-04), 게이트가 이 영역 파일 이름을 고정(0929/01-04) | +| 22 | 추상화 성숙도 | O | M3 | E1 | client는 의존성을 받는 factory이고 기능 adapter 기여에서 만든다. 새 포트를 만들지 않았다. 레시피 번들·제거 드릴과 떨어져 있다(오케스트레이터 FE-GATE-020 PASS) | +| **23** | 일관성 | P | M2 | E1, E2 | 같은 code의 효과가 client와 V3에서 반대(01-02), traceId(01-03), 헤더 없는 429(part 단계 `true` / control plane `false`), 닫힌 runtime에서 `upload()` `NONE` / `abort()` `RESUME` | +| 24 | 네이밍 / 의미 성숙도 | P | M2 | E1 | `REJECTED`가 `UPLOADED_FILE_INVALID`로 나온다(01-01). 같은 이름 `maxRetryAfterMs`가 셋이다. `abort()`의 `RESUME` 뜻이 정해져 있지 않다 | +| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 | +| 26 | Ownership 성숙도 | P | M1 / M1 | E1 | 지난 X에서 올랐다. presigned 서버 주인은 "제품 backend"로 적혔다(`server-file-capability-infrastructure.md:3-5`). 짝 경로는 Fileserver다. 남은 것: Fileserver 계약 대조의 주인이 없다(pin은 web 계약만), 백엔드에 넘길 것(멱등 키, `TRANSFER_TIMEOUT`)이 지난 README 14.7 한 줄뿐이다 | +| 27 | 삭제 가능성 | P | M3 / 레시피 단위 M0 | E1, 오케스트레이터 FE-GATE-020 PASS | client는 browser-file-storage·file-transfer 레시피 제거 드릴 뒤에도 남는다. 어댑터만 지우면 게이트가 실패한다(0929/01-04) | +| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | resumable: 재조정 삭제 실패에도 resourceId를 준다(0929/01-02 고쳐짐), ABORT 키 재사용 고정(N10 검출). client: 재개 없음(문서화), `MAYBE_APPLIED` 뒤 재전송은 백엔드가 키를 읽지 않아 중복 가능(문서화), `TRANSFER_TIMEOUT` 자동 재전송(01-02) | + +충족 O 8 · 부분 충족 P 19 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1. 지난 라운드의 X 둘(20, 26)은 1103/01-01 수정으로 P가 됐다. + +## 5. 미검증 + +| 범위 | 이유 | 확인 방법 | +| --- | --- | --- | +| 짝 백엔드를 띄운 업로드(201, 202 `QUARANTINED`·`REJECTED`, 413 두 code, 실패 Envelope) | 백엔드는 읽기만 했다. helper는 프론트 checkout만 다룬다 | 백엔드 기본 구성 + 프론트 client로 파일 넷(정상, 빈 파일, 타입 불일치, 상한 초과)을 올린다 | +| 배포 구성에서 Fileserver 성공 본문이 Envelope로 감싸지는지 | 정적 확인뿐. 백엔드 조립 테스트는 advice 없는 context다(`FileserverCompositionIntegrationTest.java:486-505`) | 위 실행에서 응답 원문을 본다 | +| 0바이트 파일이 백엔드 append·finalize를 끝까지 지나는지 | 실행 안 함. 막는 코드를 찾지 못했다 | 위 실행 | +| `TRANSFER_TIMEOUT` 뒤 작업이 늦게 `READY`가 되는 경쟁 | 재현 안 함 | 백엔드 `await-seconds`를 1초로, 검증기에 지연을 넣고 업로드 | +| client를 실제 브라우저에서(Uint8Array 본문, 비ASCII 파일 이름, CORS preflight) | spec 없음 | capability spec 하나 | +| resumable 경로의 실패 뒤 재개·두 탭 경쟁을 실제 브라우저에서 | 브라우저 spec은 정상 경로뿐. 이번에 영역 spec을 돌리지 않았다(오케스트레이터 FE-GATE-008이 돌린다) | 실패 주입 spec | +| file-transfer 레시피 번들 크기 | 이번에 재지 않았다. 커밋 `af4ebacb` 본문의 56,084 / 57,800은 주장이다 | `check:optional-recipes:source` | + +## 6. 실행 기록 + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 시작 부하 | +| --- | --- | --- | --- | --- | --- | --- | +| `01-mutations` | `ssh desktop '/tmp/claude-gates/r4/exp.sh 01-mutations - 900 "node /tmp/claude-gates/r4/mut/01-driver.mjs"'` | driver 안에서 하나씩 넣고 원문으로 되돌림(아래 표) | 0 (25초) | 기준 실행 17파일 330건 통과, 변이 14건 중 11건 검출, `restored: clean at 8a442262` | 733초 | 12.03 | + +driver(`/tmp/claude-gates/r4/mut/01-driver.mjs`)는 실험 파일 `tests/integration/zz-area01-exp.test.ts`를 만들어 기준 실행에 넣고 지운 뒤, 변이마다 `node scripts/run-vitest.ts run <관련 테스트>`를 돌린다. 영역 변이는 영역 단위 15파일(276건), FS 변이는 `tests/integration/fileserver-upload.test.ts`(48건)를 돌렸다. 모든 변이의 바꿀 글자는 파일에서 정확히 한 번 나온다는 것을 확인한 뒤 넣었다. 끝난 뒤 helper가 checkout을 되돌렸다. + +**기준 실행**: 17파일 330건 통과(영역 276 + Fileserver 48 + 실험 6), 2.0초. + +**실험**(MSW, 출하 client): + +| ID | 백엔드 응답(코드에서 읽은 모양) | 결과 | 쓰인 곳 | +| --- | --- | --- | --- | +| XA | 0바이트 파일, 201 `READY` | 요청 1회를 보낸다(보내기 전 하한 없음) | 01-01 | +| XB | 202 `state:"REJECTED"`, size 0 | `{ok:false, kind:SCHEMA_MISMATCH, code:UPLOADED_FILE_INVALID, effect:APPLIED_CONFIRMED, httpStatus:202, userMessageKey:error.schema_mismatch, action:none}` | 01-01 | +| XC | 202 `state:"QUARANTINED"` | 성공, `state:"QUARANTINED"`(대조군) | 01-01 | +| XD | 413 `PAYLOAD_TOO_LARGE`(servlet 상한) / 선언 2,000 B > 상한 1,024 B | 서버: `VALIDATION_REJECTED`, code `PAYLOAD_TOO_LARGE`, `NOT_APPLIED`. 로컬: `VALIDATION_REJECTED`, code `FILE_TOO_LARGE`, `NOT_STARTED`. 같은 거절에 code가 둘이다 | 2.1절 | +| XE | 프록시 HTML 504 | `SERVER_FAILURE`, code `CONTENT_TYPE_MISMATCH`, `MAYBE_APPLIED`(대조군) | 01-02 | +| XF | 504 `TRANSFER_TIMEOUT` Envelope(`retryable:true`) | `SERVER_FAILURE`, `NOT_APPLIED`, `retryable:true`, `action:"retry"` | 01-02 | + +모든 실험 결과에 `traceId`가 없다(MSW는 `meta.traceId`를 보냈다, 01-03). + +**변이**(하나씩 넣고 되돌림): + +| ID | 바꾼 것 | 결과 | +| --- | --- | --- | +| N2 | part 단계가 503의 `Retry-After`를 읽지 않음(`http-common.ts:173-176`) | 4 실패 — 검출(1103/01-03) | +| N10 | abort 시도마다 멱등 키를 바꿈(`resumable-upload-runtime.ts:1222-1230`) | 1 실패 — 검출(1103/01-03, 네 라운드 만에 처음) | +| N17 | control plane 헤더 없는 429를 `retryable:true`로(`fetch-json-transport.ts:588`) | 1 실패 — 검출(1103/01-03) | +| M0102 | 1103/01-02 수정 되돌림(`stripProviderFailure`의 `waitRefused` 무시) | 5 실패 — 검출 | +| N18 | 0929/01-02 수정 되돌림(재조정 `QUARANTINED`가 삭제 실패를 돌려줌) | 1 실패 — 검출 | +| N11r | 1101/01-02 수정 되돌림(수락된 part도 해시) | 1 실패 — 검출 | +| FS1 | 4xx를 모두 `MAYBE_APPLIED`로 | 10 실패 — 검출 | +| FS2 | `details.ambiguous` 무시 | 1 실패 — 검출 | +| FS3 | `Retry-After` 상한 무시 | 1 실패 — 검출 | +| FS4 | `ATOMIC_PUBLISH_UNSUPPORTED`·`TRANSFER_TIMEOUT`을 `NOT_APPLIED` 5xx에서 뺌 | **48 통과 — 검출 못 함**(01-04. 뺀 쪽이 01-02의 권고 방향이다) | +| FS5 | deadline의 바이트 비례 몫 제거 | **48 통과 — 검출 못 함**(01-04) | +| FS6 | 201/202와 state 대조 제거 | 2 실패 — 검출 | +| FS7 | Envelope `retryable:false`가 좁히지 않음 | 2 실패 — 검출 | +| FS8 | 선언 크기 초과를 읽기 전에 거절하지 않음 | **48 통과 — 검출 못 함**(01-04) | + +**오케스트레이터 결과**(이 문서를 쓸 때까지 나온 것, `desktop:/tmp/claude-gates/r4/`): + +- `gates/summary.txt`(local env): `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` 모두 rc=0. `gates/test_unit.log`: 194파일 2,883건 통과, 이 영역 15파일 모두 ✓(합 276건, 이번 기준 실행과 같다). `gates/test_integration.log`: 11파일 189건 통과, `tests/integration/fileserver-upload.test.ts` 48건 ✓. +- `merge-48/summary.txt`(CI=true workflow env): FE-GATE-001~007·020 rc=0. FE-GATE-020 로그 `FE-GATE-020 removability: PASS (merge-cycle)`(browser-file-storage·optional-recipe 제거 드릴 포함, client가 남아도 통과). +- 나머지 게이트와 snapshot(`r4/snap/`)은 이 문서를 쓸 때 없었다. 결론에 영향 없는 범위라 기다리지 않았다. file-transfer 번들 크기는 5절 미검증으로 남긴다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 01-01 | Medium·P2 | 확인된 결함 | Fileserver client가 짝 백엔드의 202 `REJECTED`(빈 파일 하나로 닿음)를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "아직 검사 중"으로 적는다 | `src/adapters/http/fileserver-upload.ts:194`, `:624-631`; `docs/manual/02-decision-tables.md:311`; 백엔드 `FileUploadController.java:195-200`, `FinalizeUploadApplicationUseCase.java:300-343` | +| 01-02 | Medium·P2 | 구조적 위험 | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주지만 백엔드는 작업 단계와 상관없이 낸다. 효과 표가 V3 표·계약 문서 6.1과 갈라졌고 pin 밖이다 | `src/adapters/http/fileserver-upload.ts:154-170`, `:691-704`; `src/adapters/http/backend-envelope.ts:249-254`; 백엔드 `BlockingTransferExecutor.java:64-79` | +| 01-03 | Low·P3 | 확인된 결함 | Fileserver client가 실패 Envelope의 `traceId`를 버린다 | `src/adapters/http/fileserver-upload.ts:638-640` | +| 01-04 | Low·P3 | 확인된 결함 | Fileserver client 규칙 셋(5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절)을 테스트가 고정하지 않는다 | `src/adapters/http/fileserver-upload.ts:163-170`, `:211-215`, `:424-428` | diff --git a/docs/reviews/2026-11-05-maturity-review/02-adapters-browser-files-cache.md b/docs/reviews/2026-11-05-maturity-review/02-adapters-browser-files-cache.md new file mode 100644 index 00000000..ffa970bf --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/02-adapters-browser-files-cache.md @@ -0,0 +1,297 @@ +# 영역 02 — adapters: browser-files · cache-storage · cross-context-invalidation + +> 검토일 2026-11-05 · 기준 `8a44226` · 가이드 `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,file}.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`, 제거 fixture `scripts/lib/removal-fixture.ts`와 드릴 5개 +> 깊게 본 관점 1, 6, 8, 10, 15, 21, 27, 28 +> 이번 라운드 렌즈: 지난 라운드 수정이 완료 기준까지 갔는가. 수정이 검사를 약하게 하거나 새 결함을 만들었는가 +> 영역 판정(35.8): cross-context-invalidation **지정 범위에서 사용 가능** · cache-storage **조건부 사용 가능** · browser-files **조건부 사용 가능** · 이 영역 제거 드릴(FE-GATE-020) **통과**(0절) + +ID 표기: 이번 라운드 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-11-03) 발견은 `1103/02-01`, 그 전 라운드는 `1101/…`, `0929/…`로 쓴다. + +실행 증거의 출처: 이번 라운드는 리뷰어가 desktop에서 따로 돌리지 않았다(BRIEF-2). 변이 31개와 실험 4개는 요청 `02-R1` 하나로 오케스트레이터 배치에서 돌았다(rc=0, 59초, 앞뒤 checkout 깨끗). 게이트 결과는 오케스트레이터 실행(merge-48, 로컬 env 목록, snapshot)을 인용한다. + +## 0. 결론 + +- **지난 라운드 6건은 모두 고쳐졌다.** 고친 커밋은 `60b721f`(02-04), `7e7614f`(02-05), `f19d4c6`(02-02), `1dfe86a`(02-03), `f485e51`(02-01), `f08c93a`·`a28b8a4`(02-06)다. 수정이 고쳤다고 한 규칙을 바꾼 변이 23개를 새 테스트가 모두 잡았다(6.2절). 오케스트레이터 `test:unit`(194파일 2,883건), `test:recipes`(77건), 이 영역 browser spec 21건(3 spec × 3엔진)이 이 커밋에서 통과했다. +- **제거 드릴 고장(1103/02-06 = 06-05)은 고쳐졌다.** 오케스트레이터가 CI env로 돌린 FE-GATE-020이 rc=0(1,156초)이다. 드릴 5개 junit이 모두 `failures="0"`이다(browser-file-storage 7/7, realtime 7/7, optional-recipe 6/6, sample 31/31, feature-scaffold 77/77). 문서를 읽는 테스트 제외 목록은 `scripts/lib/removal-fixture.ts:70-82` 한 곳에만 있다. +- **이월 7건 중 2건이 고쳐졌고 2건이 일부 고쳐졌다.** `0929/02-04`(설계 문서 줄 번호)와 `0929/02-05`(handoff 실패 lease, M10 검출)는 고쳐졌다. `1101/02-04`는 7개 중 6개가 검출되고 ②(host `storageArea` 비교, N38)만 살아남는다. `1101/02-02`는 위험 확장자를 막았고 media type 짝 검사는 남았다. `0929/02-02`(M05 생존)·`0929/02-03`·`0929/02-06`은 그대로다. +- **수정이 새 결함 넷을 만들었다.** 넷 다 데이터를 새게 하지는 않는다. + - **02-01(Medium·P2)**: 1103/02-01이 제품 closer를 scope reset에 넣었다. closer가 던지면 scope가 `FAILED`로 멈추고 진단 기록이 하나도 생기지 않는다. 실험 E-3에서 확인했다. 계약의 `ProductScopeParticipant.label`을 읽는 곳이 없다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. + - **02-02(Low·P3)**: 1103/02-02가 본문 읽기 실패를 "손상"에서 "모름"으로 옮겼다. 그래서 다시 쓰기 전까지 읽히지 않는 entry는 다시 stage해도 고쳐지지 않는다. 실험 E-1에서 확인했다. 안내는 `RETRY`인데 다시 해도 같다. rollback 대상 release는 cleanup도 지우지 않아 되돌릴 길이 없다. 수정 전 판정에서는 같은 상황이 다시 stage 한 번으로 풀린다. + - **02-03(Low·P3)**: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를 보강한다"고 적는다. 매뉴얼은 그 방식이 `check:types:node`에서 키를 잃는다고 막는다. 레시피 테스트는 capability를 기능에 넘기는 절반을 돌지 않는다(`capabilities: {}`). + - **02-04(Low·P3)**: 1103/02-02가 만든 "손상 code 4개" 목록의 경계를 테스트가 고정하지 않는다. 목록에서 하나를 빼거나(4개 모두) `NOT_READABLE`을 더해도 테스트가 통과한다. 특히 `INTEGRITY_FAILED`를 빼면 바이트가 바뀐 후보를 다시 stage로 고치지 못하는데, 이것도 잡히지 않는다. +- **검사를 약하게 한 수정은 찾지 못했다.** `git diff e40684b..8a44226`에서 이 영역 테스트의 단언 삭제는 0건이다. 지운 줄은 browser spec의 버튼 붙이는 위치 2곳뿐이다(11-10, 실제 클릭 경로는 그대로). 제거 fixture가 문서 테스트 2개를 빼는 것은 약화가 아니다. 그 테스트는 이전에도 fixture에서 한 번도 통과한 적이 없고, 본 저장소 `test:unit`은 계속 돈다. + +| ID | 심각도·우선순위 | 한 줄 | +| --- | --- | --- | +| 02-01 | Medium · P2 | 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈춘다 | +| 02-02 | Low · P3 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | +| 02-03 | Low · P3 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고, capability 전달은 테스트 밖이다 | +| 02-04 | Low · P3 | 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다(변이 5개 생존) | + +**영역 판정 (35.8)** + +- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** `e40684b` 뒤 코드 변경이 없다(`git diff --stat` 0줄). 범위는 지난 라운드와 같다. 실제 BroadcastChannel·localStorage 경로가 3엔진에서 통과한다(오케스트레이터 FE-GATE-008). host `storageArea` 비교만 테스트가 없다(`1101/02-04` ②). +- cache-storage(service-worker-pwa 레시피, 미조립): **조건부 사용 가능.** 조건은 둘이다. 정적 release 조합에만 쓴다. activate·stage가 같은 후보에서 `UNAVAILABLE`/`NOT_READABLE`을 계속 내면 `cleanupOwned()` 뒤 다시 stage하는 절차를 제품이 정한다(02-02). rollback 대상 release에는 이 절차도 듣지 않으므로 새 release를 배포한다. +- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 세션 수명 연결(1103/02-01)이 생겨 지난 라운드의 첫째 조건은 풀렸다. 로그아웃·계정 전환 모두 이전 runtime을 닫는다(E-2, 기존 테스트). 남은 조건은 둘이다. 제품이 추가하는 scope closer는 던지지 않게 쓴다(02-01). download 정책의 media type과 확장자 짝은 제품이 직접 검토한다(`1101/02-02` 남은 부분). +- 템플릿 CI의 FE-GATE-020: **통과.** 지난 라운드 "사용 보류" 사유가 풀렸다. 실제 Gitea 러너에서는 돌리지 않았다(오케스트레이터 결과는 CI env를 준 로컬 실행이다). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 02: `src/adapters/browser-files/` 10파일 4,840줄, `src/adapters/cache-storage/` 5파일 2,339줄, `src/adapters/cross-context-invalidation/` 3파일 1,062줄 | +| 커밋·작업 상태·확인 시점 | `8a44226`(laptop worktree, HEAD = 기준). 2026-11-05 19:20~20:10. 지난 기준 `e40684b` 뒤 이 영역을 바꾼 커밋: 소스 `60b721f`·`7e7614f`·`f19d4c6`·`4f78890`, 테스트 `1dfe86a`·`0a74bd4`·`de2670c`·`3bfe6a8`, 조립 `f485e51`·`b9524cf`, 문서 `d9ca653`, 제거 fixture `f08c93a`·`a28b8a4`(`git log e40684b..8a44226 -- <경로>`) | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker, SSR 없음. cross-context는 기본 조립이다. cache-storage는 service-worker-pwa, browser-files는 file-transfer 레시피의 `AVAILABLE_NOT_COMPOSED` runtime이다(`config/recipes/frontend-capability-recipes.json:155-200`). 공개 경계는 배럴 세 개다 | +| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 본다(지난 라운드와 같다) | +| 읽은 코드·구성 범위 | 세 폴더의 `e40684b..8a44226` 차이 전체, 바뀐 함수 전체(vault `inspect`·`resolveFile`·`resolveVerifiedFile`·`release`·`dispose`, preview `create`, cache `inspect`·`cleanupOwned`·stage 재사용·activate·`verifyReleaseCandidate`, `readAndValidateResponse`, `mapBrowserDataException`). 조립: `runtime-adapters.ts:380-425`·`:505-560`·`:660-690`, `server-state-scope-runtime.ts` 전체, `product-composition-contract.ts` 전체, 레시피와 그 테스트 2개, `scripts/lib/removal-fixture.ts` 전체, 드릴 5개의 fixture 준비 부분 | +| 읽은 설정·문서(주장) | `docs/architecture/browser-file-and-origin-storage.md:350-385`·`:447-453`·`:955-1000`, `docs/architecture/client-cache-and-storage.md:80-105`, `docs/manual/03-outside-feature-folder.md:96-115`, `CHANGELOG.md:57-65`·`:179`·`:188-189`·`:240`·`:316`, 각 수정 커밋 본문, 지난 라운드 영역 문서와 README 10.3·12·14절 | +| 수행한 테스트·실험 | ① 오케스트레이터 게이트 결과(6.1절): merge-48(CI env) 14개 중 13개 rc=0(FE-GATE-013은 `test:system`의 host bwrap 문제로 rc=1, 이 영역과 무관). 로컬 env 목록은 `verify:documentation` 밖 모두 rc=0. ② 배치 `02-R1`(desktop, 오케스트레이터 실행): 테스트 묶음 4개 대조 실행, 변이 31개(검출 23, 생존 8), 실험 E-1~E-3(6.2·6.3절) | +| 확인하지 못한 범위·이유 | 레시피를 조립한 실제 화면(조립 코드 없음). 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지(E-1은 메모리 fake에서 오류를 주입했다). 실제 Gitea 러너. 5절 | +| 이전 리뷰와 비교 가능한 범위 | 변이 ID(L1·L4~L7·L11·N26·N26b·N27·N29·N30·N38·N39·M05·M10)는 지난 라운드와 같은 규칙을 같은 방식으로 바꾼다. 지난 라운드 실행 결과(E-1~E-7, 변이 30건)는 현재 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| `1103/02-01` | browser-files runtime을 로그아웃·계정 전환에 맞춰 닫는 공식 연결점이 없다 | **고쳐짐** | `ProductComposition.scopeParticipants`가 생겼다(`src/bootstrap/product-composition-contract.ts:100-103`, `:127`). template이 order 10 participant 하나로 제품 closer를 차례로 부르고, 하나라도 실패하면 던진다(`src/bootstrap/runtime-adapters.ts:396`, `:409-423`). `composeProduct` 결과를 그 자리에 넣는다(`:681`). 레시피는 기능에 getter를 주고 closer가 runtime을 dispose한 뒤 다음 호출에서 새로 만든다(`recipes/frontend-capabilities/browser-file-session-capability.ts:38-57`). 설계 문서(`browser-file-and-origin-storage.md:370-384`)와 매뉴얼(`docs/manual/03-outside-feature-folder.md:108`)이 이 방법을 가리킨다. 완료 기준의 테스트가 있다(`tests/recipes/browser-file-session-capability.test.ts:226-284`, 오케스트레이터 `test:recipes` 통과). 로그아웃판(E-2)도 통과했다: 이전 runtime `readRange` `UNAVAILABLE`, download `ABORTED`, handoff 0회, 새 runtime 선택 성공. 변이 F0201a~e(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락, 레시피 runtime 유지) 5개 모두 검출. 이 수정이 만든 새 결함: 02-01, 02-03 | +| `1103/02-02` | 활성화 재검증이 캐시 본문 읽기의 일시 오류를 무결성 실패로 보고한다 | **고쳐짐** | 저장된 바이트·헤더 판정 4개 code만 `REPAIRABLE`이고 나머지는 `UNKNOWN`이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `:1139-1144`). 활성화는 `UNKNOWN`을 자기 operation으로 돌려준다(`:681-685`). 완료 기준 시나리오가 테스트에 있다(`tests/unit/public-response-cache-repair.test.ts:177-234`). 되돌리는 변이 F0202가 그 테스트에 걸린다. 이 수정이 만든 새 결함: 02-02(회복 공백), 02-04(목록 경계 테스트 공백) | +| `1103/02-03` | 손상 데이터·로그아웃 경로의 보호 규칙 5개를 테스트가 잡지 못한다 | **고쳐짐** | L1·L4·L5·L6·L7 다섯 변이가 모두 새 테스트 하나씩에 걸린다. L4 `tests/unit/browser-file-content.test.ts:653`, L5 `:672`(리뷰가 제안한 `readRange` 대신 `openSource`로 고정했다. `readRange`는 slice 뒤 한 번 더 검사해 L5를 못 잡는다는 커밋 `1dfe86a` 설명이 코드와 맞다), L1 `:697`, L6 `tests/unit/public-response-cache-repair.test.ts:530`, L7 `:552` | +| `1103/02-04` | `inspect()`와 `release()`가 겹치면 놓은 ref에 receipt가 발급되고 File이 남는다 | **고쳐짐** | `#disposed` 재확인 바로 뒤에 ref 재확인이 생겼다(`src/adapters/browser-files/browser-file-vault.ts:355-363`). 결과는 `NOT_FOUND`/`RESELECT`로 `resolveFile`의 없는 ref 결과와 같다(`:568-571`). 테스트 `tests/unit/browser-file-content.test.ts:617`이 변이 F0204를 잡는다. L11(`resolveVerifiedFile`의 `records.has`, `:614`)은 이제 동등 변이다. `release()`가 receipt를 먼저 지우고(`:627`) inspect가 놓은 ref에 receipt를 내지 않으므로, ref 없는 receipt가 남는 경로가 없다. 같은 ref를 두 정책으로 동시에 inspect하면 receipt가 둘 생긴다. 둘 다 자기 정책에 맞고 release·dispose가 지운다(커밋 `60b721f`가 범위 밖으로 적음). 결함으로 세지 않는다 | +| `1103/02-05` | pointer가 손상되면 `inspect()`가 아무 상태도 보여 주지 않는다 | **고쳐짐** | `CORRUPT_DATA`면 후보 목록을 끝까지 채우고 `activePointer: "UNREADABLE"`을 준다(`public-response-cache-adapter.ts:872-875`, `:911-916`). 일시 오류는 그대로 실패다. 포트에 필수 칸이 생겼다(`src/application/ports/browser-file-storage/cache-storage-ports.ts:43-51`). [계약] CHANGELOG 행이 있다(`CHANGELOG.md:188`). 변이 F0205(되돌림), F0205b(일시 오류도 UNREADABLE), F0205c(`NONE`을 `READABLE`로) 모두 `public-response-cache-repair.test.ts:469`에 걸린다. 지난 영향 칸의 "오류 operation이 `CACHE_LOOKUP`이라 구분되지 않는다"는 남았다(`:923`). 완료 기준에 없던 부분이고 커밋 `7e7614f`가 공유 operation union 변경이라 미뤘다고 적었다 | +| `1103/02-06` (= `06-05`, + `test:optional-recipe-removal`) | 제거 드릴이 문서 테스트 2파일 때문에 항상 실패한다 | **고쳐짐** | 제외 목록이 한 곳에 있다(`scripts/lib/removal-fixture.ts:56-82`). `prepareRemovalFixture`가 문서를 복사하지 않은 fixture에서만 두 테스트를 지운다(`:152-154`). sample·scaffold 드릴은 문서를 같이 복사하고 두 테스트를 돈다(`scripts/test-sample-removal.ts:211-214`, `scripts/test-feature-scaffold.ts:60-63`). 다섯 드릴이 같은 함수를 쓰는지 테스트가 고정한다(`tests/unit/removal-fixture.test.ts:143-178`). 완료 기준: 오케스트레이터 merge-48(CI env) FE-GATE-020 rc=0, 1,156초. junit(snapshot `artifacts/tests/`, 19:25~19:39): browser-file-storage-runtime-removal 7/7, realtime-runtime-removal 7/7, optional-recipe-removal 6/6, reference-feature-removal 31/31, feature-scaffold 77/77, 모두 `failures="0"`. 새 레시피 파일도 드릴이 같이 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:41`) | +| `1101/02-02` | download 정책 `safeExtension`이 금지 목록·media type을 보지 않는다 | **일부** | 금지 목록은 이제 본다. 금지 확장자이거나 그것으로 끝나면(`.tar.js`) 조립이 `TypeError`다(`src/adapters/browser-files/browser-file-policy-registry.ts:456`, `file-policy.ts:103-108`). 목록은 사용자 파일명과 같은 `DEFAULT_FORBIDDEN_EXTENSIONS` 하나다(`file-policy.ts:63-96`). 테스트 3건(`tests/unit/browser-file-policy-registry.test.ts:180-204`)이 F110102(검사 삭제)와 F110102b(`endsWith`를 일치 비교로)를 잡는다. 남은 것: media type과 확장자 짝은 여전히 보지 않는다. `application/pdf` + `.zip` 정책이 통과한다. 설계 문서가 한계로 적었다(`browser-file-and-origin-storage.md:450-453`) | +| `1101/02-04` | 보호 규칙 7개가 변이에서 살아남는다 | **일부** | 6개가 이제 검출된다. ① N29 합계 바이트 상한(`tests/unit/browser-file-content.test.ts:985`), ③ N27 재검사 receipt 무효화(`:1008-1010`), ④ N26b `no-cache`와 ⑦ N26 `Set-Cookie`(`tests/unit/public-response-cache-codec.test.ts:160-166`), ⑤ N39 조회의 `keys()` 재확인(`tests/unit/public-response-cache-repair.test.ts:587-612`), ⑥ N30 fragment(`tests/unit/browser-file-download.test.ts:296`). 남은 것: ② N38 host `storageArea` 비교(`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:291-295`)는 CX 묶음 46건을 모두 통과한다(생존). 커밋 `3bfe6a8`이 하네스가 필요해 미뤘다고 적었다 | +| `0929/02-02` | `inspect()`의 비용·취소·판정 불가가 포트 계약에 없다 | **남음** | 포트에 signal이 없다(`cache-storage-ports.ts:93`). 호출부가 `undefined`를 넘긴다(`public-response-cache-adapter.ts:899`). 판정 불가(`UNKNOWN`)도 `verified:false`다(`:904`). M05(판정 불가를 `verified:true`로)가 CS 묶음 59건을 모두 통과한다. 1103/02-02 뒤 `UNKNOWN`이 본문 읽기 실패까지 넓어져 이 칸이 "손상"과 "읽지 못함"을 더 많이 합친다. E-1c에서 읽히지 않는 r1이 `r1:false`로 보인다 | +| `0929/02-03` | CHANGELOG 0.2.0 browser-files [계약] 행의 경로·대상이 틀렸다 | **남음** | `CHANGELOG.md:316`의 영향 경로가 여전히 `src/adapters/browser-file-storage/`다. Cache Storage를 "browser-files recipe"로 적는다 | +| `0929/02-04` | 설계 문서 줄 번호 참조가 밀렸다 | **고쳐짐** | 지난번 밀린 5곳이 고쳐졌다. `client-cache-and-storage.md:93-102`는 줄 번호 대신 심볼 이름을 쓴다(`crossContextCacheEpochForRelease`, `createServerStateGenerationStore` 콜백, `activateNextGeneration`, coordinator `dispose()`, 커밋 `d9ca653`). 남은 줄 번호 5곳을 대조했다. `storage-keys.ts:112`, `browser-cross-context-host.ts:36-37`·`:286-296`, `browser-cross-context-invalidation.ts:197-201`, `server-state-generation-store.ts:50-57` 모두 맞다. `browser-file-and-origin-storage.md`의 줄 번호(`create-browser-file-runtime.ts:93`·`:154`·`:163`·`:177-188`, `object-url-lease.ts:48-71`·`:143-151`, `download-delivery-adapter.ts:150`·`:390-396`)도 맞다. 문서 줄 번호를 보는 자동 검사는 여전히 없다. 심볼 이름으로 바꾼 것이 그 대신이다 | +| `0929/02-05` | handoff 실패 lease 반환을 테스트가 고정하지 않는다 | **고쳐짐** | 테스트 "revokes the lease of a handoff that throws"(`tests/unit/browser-file-download.test.ts:774`)가 M10(`download-delivery-adapter.ts:858`의 `lease?.release()` 삭제)을 잡는다 | +| `0929/02-06` | cross-context kernel 예외가 쓰임보다 넓다 | **남음** (결정 대기) | 예외가 `cross-context-invalidation/index.ts` 전체를 연다(`.dependency-cruiser.json:261`). adapter 쪽 사용은 여전히 query-cache의 `import type` 하나다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:21`). repo `CLAUDE.md`가 이 예외를 kernel로 열거하고, 새 파일 단위 예외는 제안하지 않는다. 좁힐지는 소유자 결정이다 | + +지난 라운드에 고쳐짐으로 닫은 `1101/02-01`·`1101/02-03`·`1101/02-05`·`0929/02-01`은 이번 diff에서 그 코드가 바뀌지 않았다(`object-url-lease.ts:192-208`, `public-response-cache-adapter.ts:497`, `browser-cross-context-invalidation.ts:318`·`:337`, `public-cache-codec.ts:456-461`). 재발 없음으로 본다. 그 변이(F1~F7)는 다시 걸지 않았다. + +## 3. 이번 발견 (36.3) + +새 발견 4건. 심각도 Medium 1 · Low 3. 우선순위 P2 1 · P3 3. 성격 확인된 결함 2 · 구조적 위험 2. 넷 다 지난 라운드 수정이 만들었다(02-01·02-03은 `f485e51`, 02-02·02-04는 `f19d4c6`). + +### 02-01 제품 scope participant가 실패하면 scope가 진단 없이 `FAILED`로 멈춘다. 어느 participant인지도 남지 않는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(진단 공백) | +| 관련 관점 | 8, 7, 5, 17, 6 | +| 근거 | ① 1103/02-01 수정이 제품 closer를 scope reset에 넣었다. template participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는 `Error("A product scope participant failed.")`를 던진다(`src/bootstrap/runtime-adapters.ts:409-423`). 어느 closer가 무엇을 던졌는지 버린다. ② scope runtime은 participant 실패를 `failed = true`로만 받는다(`src/adapters/query-cache/server-state-scope-runtime.ts:136-141`). 그 뒤 `FAILED`를 lifecycle로만 알린다(`:161-171`). 이 runtime이 `diagnostics`에 남기는 것은 subject 누락 하나뿐이다(`:114`, `:239-250`). ③ `src`에서 `subscribeLifecycle`을 듣는 곳이 없다(`git grep subscribeLifecycle -- src`가 계약과 runtime 정의만 찾는다). ④ 계약은 `label`을 필수로 받는다(`src/bootstrap/product-composition-contract.ts:100-103`). 그런데 `label`을 읽는 코드가 없다(`runtime-adapters.ts`, `server-state-scope-runtime.ts`에 `.label` 0건). ⑤ `FAILED` 동안 모든 서버 요청이 `SCOPE_FENCED`로 막힌다. 자격 증명 붙이기가 phase를 먼저 본다(`runtime-adapters.ts:513-514`). 익명 profile도 같다. ⑥ 수정 전에는 이 경로가 사실상 닿지 않았다. template participant는 `conditionalValidators.clear()` 하나였다(`runtime-adapters.ts:404-408`). 이제 제품 코드(비동기 포함)가 이 경로로 들어온다. ⑦ 실험 E-3(실제 `createRuntimeAdapters`, 6.3절): `label: "r4-broken-closer"` closer가 던지게 하고 계정을 바꿨다. phase `FAILED`, lifecycle `FENCED → FAILED`. 같은 identity 알림을 한 번 더 주자 다시 `FENCED → FAILED`. 진단 기록 수는 전후 1건 그대로다(부팅 때 남은 `cache.operation.failed` 하나). label·scope·participant를 담은 기록은 0건이다 | +| 발생 조건 | 제품이 `scopeParticipants`에 closer를 넣는다. 그 closer가 로그아웃·계정 전환 때 던지거나 reject한다(예: IndexedDB close 실패, 소켓 정리 중 예외) | +| 영향 | 그 탭의 서버 상태가 멈춘다. 모든 요청이 `SCOPE_FENCED`다. 다음 session 알림이 reset을 다시 시도한다(`server-state-scope-runtime.ts:103-110`). closer가 계속 던지면 다시 `FAILED`다(E-3). 알림이 없는 세션(쿠키 세션)이면 새로 고침까지 그대로다. 진단 기록이 0건이라 개발자와 운영자는 "로그아웃 뒤 앱이 아무 요청도 안 보낸다"만 본다. 원인 closer를 찾으려면 제품 closer를 하나씩 지워 봐야 한다. 데이터 노출은 없다. 닫히는 쪽으로 실패한다 | +| 심각도·우선순위 | Medium · P2 — 가이드 35.2의 Medium 예시 "주요 진단 정보 부족"이다. 앱 전체 서버 상태가 멈추는데 흔적이 없다. 닫히는 쪽으로 실패하고 데이터가 새지 않아 High는 아니다. 레시피의 closer는 dispose 전에 `runtime = null`을 먼저 해 재시도에서 던지지 않는다(`browser-file-session-capability.ts:51-55`). 그래서 P1이 아니다. 매뉴얼이 제품에게 closer를 더하라고 안내하므로(`docs/manual/03-outside-feature-folder.md:108`) 제품 closer가 늘기 전에 고친다 | +| 통제·증거 | 실패를 막는 규칙(READY로 가지 않음) M3(`runtime-adapters-product-scope-participants.test.ts:135-152`, F0201b·F0201c 검출) · 실패를 알리는 규칙 M0(관측 코드 없음) · E1, E2(E-3) | +| 확실성과 남은 가정 | 진단 없음, `label` 미사용, 요청 차단은 코드와 E-3으로 확정했다. 화면이 `FAILED`를 어떻게 보이는지는 영역 08·09 몫이라 보지 않았다. scope runtime 자체의 무진단은 이번 수정 전부터 있었다(영역 03). 이 항목은 1103/02-01 수정이 그 경로를 제품 코드에 연 부분으로 센다. 영역 03·09가 같은 결함을 적었다면 오케스트레이터가 하나로 합친다 | +| 결정의 근거 | 확인한 사실: 실패는 닫히는 쪽(READY 막음)으로 처리되고 관측은 없다. 기록된 의도: 계약 주석 "A close that throws or rejects keeps the scope from reaching READY"(`product-composition-contract.ts:93-99`). 관측 의도는 기록이 없다. 리뷰어 추론: `label`은 진단용으로 둔 칸인데 연결이 빠졌다 | +| 이해 비용 | 제품 개발자가 로그아웃 뒤 멈춘 앱을 보면 scope runtime, template participant, 제품 closer 세 곳을 읽어야 "closer가 던졌다"를 안다 | +| 최소 개선 방향 | scope runtime이 participant 실패와 `FAILED` 진입을 그 participant의 `label`과 함께 diagnostics에 한 번 남긴다. 제품 wrapper는 실패한 제품 closer의 `label`을 실어 던진다 | +| 대안 비교 | (가) 현상 유지 + 문서에 "closer는 던지지 않게 쓴다": 0줄, 결함은 그대로. (나) 제품 wrapper만 label을 기록: 몇 줄, template participant 실패는 여전히 조용하다. (다) scope runtime이 participant마다 label과 함께 실패를 기록: template 것까지 한 곳에서 해결. (다)가 가장 작은 전체 해결이다. `label`은 제품이 고른 문자열이라 진단 projection이 받는 형식(닫힌 토큰)으로 제한해야 한다 | +| 단순화의 보존 조건 | reset 실패는 READY를 막는다. 나머지 closer는 계속 부른다(`runtime-adapters-product-scope-participants.test.ts:135-152`). 진단은 사용자·세션 값을 싣지 않는다 | +| 비용·부작용 | 수십 줄과 테스트 1~2개. 진단 eventId 레지스트리에 행 하나 | +| 재검토 조건 | 화면이 `FAILED`를 사용자에게 보이고 재시도 버튼을 주게 되면, 진단과 화면 신호를 같은 lifecycle 구독으로 묶는다 | +| 완료 기준 | 던지는 제품 closer 뒤 diagnostics에 그 `label`이 담긴 기록이 하나 있다. template participant 실패도 기록된다 | +| 검증 방법 | E-3 시나리오(`scratchpad/r4-02/02-setup.mjs`가 만든 테스트)를 `tests/unit/runtime-adapters-product-scope-participants.test.ts`에 옮겨 `outputPorts.diagnostics.entries()`를 단언한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-02 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않는다. 안내는 `RETRY`인데 다시 해도 같고, rollback 대상은 회복 길이 없다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(1103/02-02 수정이 만든 회복 공백) | +| 관련 관점 | 28, 6, 24, 11, 18 | +| 근거 | ① 1103/02-02 뒤 본문 읽기 실패(`UNAVAILABLE`·`NOT_READABLE`·`NOT_FOUND` 등)는 `UNKNOWN`이다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `:1139-1144`). 브라우저 오류 이름이 그 code로 바뀐다(`src/adapters/browser-file-storage/result.ts:49-104`: `TypeError` → `UNAVAILABLE`/`RETRY`, `NotReadableError` → `NOT_READABLE`/`REOPEN`). ② stage 재사용 경로는 `UNKNOWN`이면 실패를 돌려주고 다시 받지 않는다(`:492-497`). 테스트가 그렇게 고정한다: "neither reused nor fetched again over the network"(`tests/unit/public-response-cache-repair.test.ts:217-223`). ③ 수정 전에는 같은 상태가 `REPAIRABLE`이었다. 그때 stage는 모든 asset을 다시 받아 같은 캐시에 덮어썼다(`:505-548`). 덮어쓰기는 digest로 검증한 같은 바이트라 서비스 중인 release를 해치지 않는다. 실패하면 이미 바꾼 entry만 남긴다(`:573-578`). ④ cleanup은 pointer와 rollback 목록에 있는 캐시를 지우지 않는다(`:801-812`). ⑤ 설계 문서는 이 경우의 절차를 적지 않는다(`docs/architecture/browser-file-and-origin-storage.md:955-1000`). ⑥ 실험 E-1(6.3절): entry 하나가 다시 쓸 때까지 읽히지 않게 했다. 현재 코드: 후보 r2는 activate 2회 `UNAVAILABLE`/`RETRY`, 재stage 2회 같은 실패에 fetch 0회. cleanup이 r2를 지운 뒤에야 stage(fetch 2)와 activate가 성공했다. `NotReadableError`도 같다(`NOT_READABLE`/`REOPEN`). rollback 대상 r1: activate 2회, 재stage, cleanup(삭제 0, r1 보존), 다시 activate 모두 실패. 활성 r1: 조회 `UNAVAILABLE`, 재stage 실패, 조회 계속 실패. 수정 전 판정(F0202 되돌림)으로 같은 실험: activate는 `INTEGRITY_FAILED`/`REHYDRATE`, 재stage 한 번(fetch 2)으로 entry가 고쳐지고 activate·rollback·조회가 모두 성공했다 | +| 발생 조건 | Cache Storage의 한 entry 본문이 다시 쓰기 전까지 계속 읽히지 않는다(디스크의 blob 손실 등). 그 후보를 활성화하거나 같은 manifest로 다시 stage한다. 또는 rollback으로 그 release를 다시 활성화한다 | +| 영향 | 새 release 후보: 배포 흐름이 `RETRY`를 따르면 끝나지 않는다. 운영자가 cleanup을 돌린 뒤 다시 stage해야 풀린다. rollback 대상: 그 release로는 되돌릴 수 없다. 새 release를 배포해야 한다. 활성 release: 그 asset 조회가 계속 `UNAVAILABLE`이다. 제품 SW가 네트워크로 넘기면 사용자 피해는 오프라인에서 그 asset을 못 쓰는 것이다. 데이터를 지우지는 않는다 | +| 심각도·우선순위 | Low · P3 — 데이터는 지켜진다. 새 후보는 cleanup으로, 나머지는 새 release로 회복된다. 지속되는 본문 읽기 실패가 실제 브라우저에서 얼마나 생기는지는 모른다. 레시피가 미조립이다 | +| 통제·증거 | 지속 실패 회복 규칙 M0(다시 쓰는 길이 없음) · E1, E2(E-1, 메모리 fake에 오류 주입) | +| 확실성과 남은 가정 | 코드 경로와 동작은 E-1로 확정이다. 실제 Chrome·Firefox·Safari에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지는 확인하지 못했다. 일시 오류만 있다면 이 항목은 결함이 아니다 | +| 결정의 근거 | 확인한 사실: 수정은 일시 오류의 재다운로드 비용을 없애고 대신 지속 실패의 자가 회복을 잃었다. 기록된 의도: 커밋 `f19d4c6` "stage 재사용 경로는 본문을 읽지 못하면 이제 repair 대신 실패를 돌려준다. 손상이 아닌 것을 손상으로 고치지 않는다는 STO-RR-04와 같은 방향". 리뷰어 추론: STO-RR-04가 막으려던 것은 서비스 중인 release 삭제다(`:464-466` 주석). stage 덮어쓰기는 삭제가 아니라서 그 규칙이 막을 대상이 아니다. 지난 라운드 리뷰(1103/02-02 비용 칸)도 이 차이를 보지 않았다 | +| 이해 비용 | 운영자는 `UNAVAILABLE`/`RETRY`만 보고 cleanup이 답이라는 것을 코드 없이 알 수 없다. rollback이 안 되는 이유는 inspect의 `verified:false`(판정 불가와 손상을 합침, `0929/02-02`)로도 구분되지 않는다 | +| 최소 개선 방향 | stage 재사용 경로만 `UNKNOWN`(중단 제외)을 "덮어써 고침"으로 본다. 활성화는 지금처럼 본문 읽기 실패를 손상으로 보고하지 않는다. 다만 recovery를 "다시 stage"(`REHYDRATE`)로 안내한다. code는 그대로 둔다 | +| 대안 비교 | (가) 현상 유지 + 문서에 "계속 실패하면 cleanup 뒤 다시 stage, rollback 대상은 새 release": 0줄, rollback 대상은 못 고친다. (나) 재사용 경로의 `UNKNOWN`만 덮어쓰기: 몇 줄, 일시 오류에서 재다운로드 비용이 돌아온다(수정 전과 같다). 서비스 중인 release는 지우지 않는다. (다) 실패한 entry만 다시 받아 덮어쓰기: 비용이 가장 작지만 stage 경로를 entry 단위로 나눠야 한다. (나)가 가장 작다 | +| 단순화의 보존 조건 | 활성화는 검증된 후보만 올린다. 일시 읽기 실패로 캐시를 지우지 않는다(STO-RR-04). 바이트가 다르면 `INTEGRITY_FAILED`(`public-response-cache-repair.test.ts:236-263`). 조회는 지금처럼 `UNAVAILABLE`/`RETRY`다 | +| 비용·부작용 | 몇 줄과 테스트 1~2개. `public-response-cache-repair.test.ts:217-223`의 "fetch 0회" 단언을 바꾼다. service-worker-pwa 번들 여유 342 B 안에서 끝나야 한다(오케스트레이터 FE-GATE-012: 9,758 / 10,100 gzip B) | +| 재검토 조건 | 실제 브라우저에서 지속되는 본문 읽기 실패가 관찰되지 않으면 (가)로 닫는다. Service Worker drain 조합을 조립하면 rollback 대상 회복을 그 설계와 같이 본다 | +| 완료 기준 | E-1a·E-1c 시나리오에서 같은 manifest stage가 후보를 고치고 다음 activate(rollback 포함)가 성공한다 | +| 검증 방법 | E-1(`scratchpad/r4-02/zz-r4-02-e1.test.ts`)을 `public-response-cache-repair.test.ts`의 02-02 묶음에 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-03 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고, capability를 기능에 넘기는 절반은 테스트 밖이다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(문서 불일치 + 테스트 공백) | +| 관련 관점 | 9, 20, 17, 10 | +| 근거 | ① 레시피 주석은 "A product that installs a feature using it augments `FeaturePlatformCapabilities` with `files: SessionBrowserFiles`"라고 적는다(`recipes/frontend-capabilities/browser-file-session-capability.ts:21-24`). ② 매뉴얼은 그 타입을 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 적으라고 한다. `product-composition.ts` 안에서 `FeaturePlatformCapabilities`를 보강(`declare module`)하면 `check:types:node`가 그 키를 보지 못한다고 막는다(`docs/manual/03-outside-feature-folder.md:105-106`). 제품 쪽 인터페이스는 `src/features/product-capabilities.ts:28`, 상속은 `src/features/feature-adapter-contribution.ts:57`이다. ③ 레시피 주석의 예는 `capabilities: { files: browserFiles.files }`다(`:30`). 레시피 테스트는 `capabilities: {}`로 조립한다(`tests/recipes/browser-file-session-capability.test.ts:142`). 테스트는 `files.current()`를 직접 부른다(`:228`, `:278`). 기능 contribution이 `files` capability를 받아 쓰는 길은 돌지 않는다 | +| 발생 조건 | 제품 개발자가 레시피 주석만 보고 파일 기능을 붙인다 | +| 영향 | 주석대로 `declare module`로 보강하면 앱 typecheck는 통과하고 `check:types:node`에서 키를 잃는다. 매뉴얼이 이미 적은 함정이다. capability 전달 절반이 테스트 밖이라 그 길이 깨져도 레시피 테스트는 통과한다 | +| 심각도·우선순위 | Low · P3 — 실패가 typecheck에서 드러나고 매뉴얼이 정답을 적었다. 런타임 피해는 없다 | +| 통제·증거 | 문서 M1(주석과 매뉴얼이 다름) · 전달 경로 검출 M0 · E1 | +| 확실성과 남은 가정 | 주석 문장과 테스트 입력은 확정이다. "augments"를 `ProductFeaturePlatformCapabilities` 채우기로 읽는 사람도 있다. 그래도 어느 파일인지 적지 않아 매뉴얼과 다르게 읽힌다 | +| 결정의 근거 | 적용 제외 — 같은 저장소 안 두 안내가 다른 단순 불일치다 | +| 이해 비용 | 레시피에서 시작한 개발자는 매뉴얼 03 C절까지 와야 맞는 파일을 안다 | +| 최소 개선 방향 | 주석을 "`src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 `files: SessionBrowserFiles`를 적는다"로 고친다. 레시피 테스트에 `capabilities: { files }`를 넘기고 기능 contribution 하나가 `current()`로 받는지 단언을 더한다 | +| 대안 비교 | 적용 제외 — 기대 계약(매뉴얼)이 이미 정해져 있다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 | +| 비용·부작용 | 주석 몇 줄, 테스트 수십 줄 | +| 재검토 조건 | 적용 제외 — 선택을 바꾸는 판단이 없다 | +| 완료 기준 | 주석이 매뉴얼과 같은 파일을 가리킨다. 레시피 테스트가 capability를 기능까지 넘긴다 | +| 검증 방법 | 주석 대조(정적). 레시피 테스트에서 `capabilities.files`를 빼면 실패하는지 변이로 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-04 1103/02-02의 손상 code 목록 경계를 테스트가 고정하지 않는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(테스트 공백) | +| 관련 관점 | 10, 28, 6 | +| 근거 | 1103/02-02 수정은 `REPAIRABLE_READ_CODES` 4개를 새 판정 표로 두었다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`). 배치 02-R1에서 이 표의 경계를 바꾼 변이 5개가 CS 묶음(4파일 59건)을 모두 통과했다(6.2절). F0202-int(`INTEGRITY_FAILED` 뺌), F0202-cor(`CORRUPT_DATA` 뺌), F0202-pol(`POLICY_REJECTED` 뺌), F0202-lim(`LIMIT_EXCEEDED` 뺌), F0202-notreadable(`NOT_READABLE` 더함). 앞의 넷이 살아남는 이유: 활성화는 `UNKNOWN`도 원래 code로 돌려준다(`:681-685`). 그래서 "바이트가 다르면 `INTEGRITY_FAILED`" 테스트(`tests/unit/public-response-cache-repair.test.ts:236-263`)는 두 판정을 구분하지 못한다. 차이는 stage 재사용 경로(`public-response-cache-adapter.ts:482-497`)에서만 난다. 그런데 그 경로의 repair 테스트는 entry가 없는 경우(`!cached`, `:1127`)만 본다("repairs an evicted asset in place", `:320`). 마지막 하나는 `NotReadableError`를 쓰는 테스트가 없어서다. 지금 테스트는 `TypeError` 하나로 본문 실패를 만든다(`:190-194`) | +| 발생 조건 | 이 목록을 고치는 리팩터링이나 새 failure code 추가 | +| 영향 | `INTEGRITY_FAILED`가 빠지면 바이트가 바뀐 후보를 다시 stage로 고치지 못한다. 활성화는 `REHYDRATE`를 안내하는데 다시 stage도 같은 `INTEGRITY_FAILED`로 실패한다. 손상 회복의 기본 길이 끊겨도 테스트는 통과한다. `NOT_READABLE`이 더해지면 1103/02-02가 `NotReadableError`에서만 되돌아간다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 회귀를 막는 장치만 없다. 지난 라운드 같은 모양(1103/02-03, 변이 생존)과 같은 등급이다 | +| 통제·증거 | 판정 표 M2 구현 · 검출 M3 없음(경계 5개) · E2(변이 생존) | +| 확실성과 남은 가정 | 변이 결과는 확정이다. CS 묶음 밖의 테스트(browser spec)는 이 경계를 돌지 않는다(`public-cache-storage.spec.ts`의 두 테스트는 실패 B stage와 Vary 조회만 본다) | +| 결정의 근거 | 적용 제외 — 테스트를 더하는 문제다 | +| 이해 비용 | 목록을 고치는 사람은 테스트가 통과해도 어느 손상이 다시 stage로 고쳐지는지 알 수 없다 | +| 최소 개선 방향 | stage 재사용 경로에서 code마다 한 행씩 표 테스트를 둔다. 바이트 변경(`INTEGRITY_FAILED`), 정책 밖 헤더(`POLICY_REJECTED`), 길이 초과(`LIMIT_EXCEEDED`)는 다시 받아 고치고(fetch > 0, 다음 activate 성공), `TypeError`·`NotReadableError` 본문 실패는 fetch 0으로 실패한다. `CORRUPT_DATA`는 `DataError` 본문 오류로 만든다(`result.ts:67-69`) | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 표 테스트 1개(행 5~6개). 02-02를 고치면 본문 실패 행의 기대가 바뀐다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | F0202-int·-cor·-pol·-lim·-notreadable이 모두 실패한다 | +| 검증 방법 | `scratchpad/r4-02/02-runner.mjs`의 같은 변이를 다시 건다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| **1** | 코드 성숙도 | 적용 — "검증 뒤에만 성공", 같은 턴 경쟁 | M2 / M2 | E1, E2 | P — inspect·release 경쟁이 고쳐졌다(1103/02-04). 본문 읽기 실패 판정이 맞아졌다(1103/02-02). 대신 지속 실패의 자가 회복을 잃었다(02-02) | +| 2 | 구조적 성숙도 | 적용 — 배럴 경계, kernel 예외 | M3 / M3 | E2(`check:architecture` rc=0, 오케스트레이터) | P — 새 레시피도 배럴만 import한다(`browser-file-session-capability.ts:1-2`). cross-context 예외가 배럴 전체를 연다(`0929/02-06`, 결정 대기) | +| 3 | 변경 용이성 | 적용 — 수명 연결, 정책 추가 | M2 / M2 | E1, E2 | O — 제품 파일만 고쳐 file runtime을 세션에 묶는다(1103/02-01, 로그아웃·계정 전환 모두 확인). 정책·topic은 registry에 더하면 끝난다 | +| 4 | 인지 부하 | 적용 — 1.1k~1.2k줄 파일 2개, 수명 규칙 | — / — | E1 | P — 큰 파일 둘(`public-response-cache-adapter.ts` 1,215줄, `download-delivery-adapter.ts` 1,161줄)은 지난 판단대로 둔다. 세션 연결은 레시피 하나를 읽으면 된다. 레시피 주석이 매뉴얼과 다르다(02-03) | +| **5** | 위험 가시성 | 적용 — 실패 의미, 세션 수명 | M1~M2 / M1~M2 | E1, E2 | P — 손상 pointer를 inspect가 보인다(1103/02-05). 제품 closer 실패가 안 보인다(02-01) | +| **6** | 실패 성숙도 | 적용 — 손상·일시·지속 실패 구분 | M2 / M2 | E1, E2(E-1) | P — 일시 오류와 손상이 갈렸다(1103/02-02). 지속되는 읽기 실패가 일시 오류로 분류돼 끝나지 않는다(02-02). 그 경계를 테스트가 고정하지 않는다(02-04). 제품 closer 실패는 닫히는 쪽으로 처리된다(02-01) | +| 7 | 운영 성숙도 | 적용 — 관측 연결 | M2 / M1 | E1, E2(E-3) | P — cross-context 실패 관측은 그대로다. scope reset 실패가 관측에 없다(02-01). file·cache observer는 레시피 조립 몫이다 | +| **8** | 디버깅 가능성 | 적용 — reason·operation·label | M2 / M1 | E1, E2(E-3) | P — inspect가 pointer 상태를 준다(고쳐짐). inspect 실패 operation이 여전히 `CACHE_LOOKUP`이다(`public-response-cache-adapter.ts:923`). participant `label`을 아무도 읽지 않는다(02-01) | +| 9 | 유지보수 성숙도 | 적용 — 문서·CHANGELOG 정합 | M1 / M1 | E1 | P — 설계 문서 줄 번호가 맞다(고쳐짐). CHANGELOG 0.2.0 행이 그대로 틀렸다(`0929/02-03`). 레시피 주석과 매뉴얼이 다르다(02-03) | +| **10** | 테스트 성숙도 | 적용 — 수정 테스트, 변이 | M3 / M3 | E2(영역 unit 12파일·recipe 2파일 통과, 오케스트레이터), E2(변이 31개: 검출 23, 생존 8) | P — 수정이 고쳤다고 한 규칙의 변이 23개를 모두 잡는다. 지난 생존 변이 15개 중 12개가 검출로 바뀌었다. 생존 8개: N38·M05(이월), L11(동등), 02-02 판정 표 경계 5개(02-04). 레시피 capability 전달이 테스트 밖이다(02-03) | +| **11** | 데이터 성숙도 | 적용 — pointer·marker·캐시 entry | M2 / M2 | E1, E2 | P — 손상 marker는 다시 stage로 고친다(L7 검출). 지속적으로 읽히지 않는 entry는 고칠 길이 cleanup뿐이다(02-02) | +| **12** | 동시성 성숙도 | 적용 — async 경쟁, 탭 간 순서 | M3 / M3 | E1, E2 | O — inspect·release 경쟁이 고쳐졌다(F0204 검출). 조회의 `keys()` 재확인을 잡는다(N39 검출). 같은 ref 두 정책 동시 inspect는 receipt 둘로 끝나고 둘 다 정리된다(결함 아님) | +| 13 | 확장성 | 적용 — 상한 값 | M2 / M2 | E1, E2(N29 검출) | O — 상한 값 변경 없음. 합계 바이트 상한에 테스트가 생겼다. 부하 목표 없음 | +| 14 | 성능 성숙도 | 적용 — 레시피 번들, 관리 연산 비용 | M2 / M2 | E2(FE-GATE-012 PASS, 오케스트레이터) | P — service-worker-pwa 9,758 / 10,100(여유 342 B), file-transfer 56,130 / 57,800 gzip B(여유 1,670 B). `inspect()`·`cleanupOwned()`에 cursor·deadline이 없다(`0929/02-02`) | +| **15** | 보안 성숙도 | 적용 — 세션 경계, 위험 확장자, 익명 캐시 | M2~M3 / M2~M3 | E1, E2 | P — 로그아웃·계정 전환 때 file runtime이 닫힌다(1103/02-01, E-2). 위험 확장자 정책을 거절한다(F110102 검출). 익명 캐시의 `no-cache`·`Set-Cookie` 거절을 잡는다(N26b·N26 검출). media type 짝은 보지 않는다(`1101/02-02`). host `storageArea` 비교는 테스트 밖이다(N38 생존) | +| 16 | 의존성 성숙도 | 적용 제외 — 세 폴더의 외부 패키지 import 0건(grep) | — | E1 | - | +| **17** | API / Contract 성숙도 | 적용 — 포트·제품 확장 계약 | M2 / M2 | E1 | P — `activePointer`, `scopeParticipants`가 [계약] CHANGELOG 행과 함께 생겼다(`CHANGELOG.md:179`, `:188`). `ProductScopeParticipant.label`은 계약에만 있고 쓰이지 않는다(02-01). CHANGELOG 0.2.0 행(`0929/02-03`) | +| 18 | 배포 성숙도 | 적용 — 배포·rollback, 게이트 | M2 / M2 | E2(FE-GATE-020 rc=0, E-1c) | P — release 단계가 기다리는 FE-GATE-020이 통과한다(고쳐짐). rollback 대상에 읽히지 않는 entry가 있으면 되돌릴 수 없다(02-02, E-1c). Service Worker drain 조합은 범위 밖이다 | +| 19 | 설정 성숙도 | 적용 — 정책 조합 검증 | M3 / M3 | E1, E2 | P — 위험 `safeExtension`이 조립 때 `TypeError`다. media type 짝은 통과한다(`1101/02-02`) | +| 20 | 개발자 경험 | > 영역 14 — 레시피 주석과 매뉴얼 불일치(02-03)는 이 영역에서 센다 | — | — | > | +| **21** | Guardrail 성숙도 | 적용 — 제거 드릴, kernel 예외 | M3 / M3 | E2(FE-GATE-020, `check:architecture`) | P — 제거 드릴 5개가 통과한다(고쳐짐). 문서를 읽는 테스트 제외 목록은 손으로 관리한다(`removal-fixture.ts:70-73`). 새 문서 테스트를 빠뜨리면 capability 드릴이 ENOENT로 시끄럽게 실패한다. 조용히 통과하지는 않는다 | +| 22 | 추상화 성숙도 | 적용 — lease registry, 세션 getter | — / — | E1 | P — getter capability가 "부팅 때 한 번"과 "세대마다 새 runtime"을 잇는다. registry에 닫힘 상태가 없는 것은 지난 결정대로다(지난 라운드 5.2). 소비자 쪽 재확인(L4·L5)에 이제 테스트가 있다 | +| 23 | 일관성 | 적용 — 실패 분류 | — / — | E1, E2 | P — 같은 본문 읽기 오류가 조회·활성화·stage에서 같은 code다(고쳐짐). `QUOTA_EXCEEDED`의 recovery가 `READ_ONLY`와 `ONLINE_ONLY`로 갈린다(`result.ts:80-85`, `public-cache-codec.ts:597-603`, 지난 라운드와 같음) | +| **24** | 네이밍 / 의미 성숙도 | 적용 — 실패 이름이 약속하는 것 | M2 / M2 | E1, E2(E-1) | P — `RETRY`·`REOPEN`이 지속 실패에서는 지켜지지 않는다(02-02). `verified:false`가 판정 불가를 합친다(`0929/02-02`, M05 생존) | +| 25 | 조직 확장성 | 적용 제외 — 1인 관리 | — | — | - | +| 26 | Ownership 성숙도 | > 영역 12 | — | — | > | +| **27** | 삭제 가능성 | 적용 — 제거 드릴 | M3 / M3 | E2(FE-GATE-020 rc=0, junit 5개 failures 0) | O — browser-files·cache-storage·포트·새 레시피를 지운 fixture에서 7개 검사가 모두 통과한다. 지난 라운드 P(드릴 거짓 실패)에서 올라갔다. 실제 Gitea 러너는 미실행 | +| **28** | 회복 가능성 | 적용 — 손상 pointer·marker·entry 회복 | M2 / M2 | E1, E2(E-1) | P — 손상 marker 회복(L7)과 손상 pointer 진단(F0205)이 고정됐다. 지속적으로 읽히지 않는 entry는 다시 stage로 회복하지 못한다(02-02). 바이트가 바뀐 후보의 stage 회복은 테스트가 고정하지 않는다(02-04) | + +집계(이 영역에서 판정한 24개): O 4(3, 12, 13, 27) · P 20 · X 0 · ? 0. 적용 제외 2(16, 25) · 다른 영역 2(20, 26). 지난 라운드 대비: 27번 P → O(02-06 수정), 3번 P → O(1103/02-01 수정), 12번 P → O(1103/02-04 수정). 18번은 P 유지(원인이 02-06에서 02-02로 바뀜). 7번 확인 통제가 M2 → M1로 내려갔다(02-01). + +## 5. 미검증 + +| 항목 | 왜 확인하지 못했나 | 확인하려면 | +| --- | --- | --- | +| 실제 브라우저에서 Cache Storage 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로 오는지(02-02의 발생 가능성) | 실기에서 blob 손실을 만들지 않았다. E-1은 메모리 fake에 오류를 주입했다 | 브라우저별 프로필에서 cache entry의 blob 파일을 지운 뒤 `response.arrayBuffer()` 결과를 본다 | +| 레시피를 조립한 실제 화면에서 로그아웃 뒤 파일·download가 닫히는지 | 조립 코드가 없다. E-2와 레시피 테스트는 jsdom이다 | file-transfer 레시피를 조립한 제품 E2E | +| `FAILED` scope가 화면에서 어떻게 보이는지 | 영역 08·09 몫 | `FAILED` 주입 뒤 화면 상태 확인 | +| FE-GATE-020이 실제 Gitea 러너에서 같은 결과인지 | 러너가 없다 | 러너의 merge job | +| N38(host `storageArea`)을 실제 브라우저 spec이 잡는지 | `cross-context-invalidation.spec.ts`의 두 테스트에 sessionStorage 이벤트를 거절하는 경우가 없다(정적) | spec에 sessionStorage `storage` 이벤트 행 추가 | + +## 6. 실행 기록 + +### 6.1 오케스트레이터 게이트 결과(인용) + +| 출처 | 결과 | +| --- | --- | +| merge-48(CI env) FE-GATE-020 | rc=0, 1,156초. `removability: PASS`. junit 5개 failures 0(snapshot 시각 19:25~19:39) | +| merge-48 FE-GATE-001~012 | 모두 rc=0. FE-GATE-007(`test:recipes`): `optional-recipes.xml` 77건 failures 0, 그중 `browser-file-session-capability.test.ts` 1, `browser-file-storage-contracts.test.ts` 13. FE-GATE-008: browser capability 66건 failures 0, 이 영역 spec 21건(`browser-files` 3, `cross-context-invalidation` 2, `public-cache-storage` 2 × chromium·firefox·webkit). FE-GATE-012: `Optional recipes: PASS`, file-transfer 56,130 / 57,800, service-worker-pwa 9,758 / 10,100 gzip B | +| merge-48 FE-GATE-013 | rc=1. `test:system` 114건 중 18건 실패, 원인은 host bwrap(오케스트레이터 판정). 이 영역과 무관 | +| 로컬 env 목록 | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit` 194파일 2,883건, 이 영역 unit 12파일 통과. `verify:documentation`은 desktop의 짝 백엔드 checkout 옆에서 실패(오케스트레이터 몫) | + +### 6.2 배치 02-R1(변이) + +명령 `node /tmp/claude-gates/r4/mut/02-runner.mjs`, 변이 스크립트 `02-mut.sh`(임시 테스트 3개 생성), env local. 오케스트레이터 실행: 2026-11-05 20:01, 부하 1.48, rc=0, 59초, 앞뒤 checkout 깨끗(`8a44226`, git status 빈 상태). 스크립트 사본과 결과: `scratchpad/r4-02/`, `scratchpad/r4/results/02/`(`02-R1.log`, `02-mut-result.json`). + +대조 실행(변이 없음): BF 8파일 93건, CS 4파일 59건, CX 3파일 46건, BOOT 4파일 38건 모두 rc=0. 각 변이는 파일 한 곳을 바꾸고 해당 묶음을 돌린 뒤 원본으로 되돌렸다. + +| ID | 바꾼 규칙 | 결과 | 잡은 테스트 / 연결 | +| --- | --- | --- | --- | +| L1 | vault `dispose()`가 File 참조 Map을 비우지 않음 | 검출 | "lets go of every selected File on dispose" / 1103/02-03 | +| L4 | preview가 resolve 뒤 `#disposed`를 다시 보지 않음 | 검출 | "creates no object URL for a preview whose runtime is disposed while it resolves" / 1103/02-03 | +| L5 | vault `resolveFile`이 load 뒤 `#disposed`를 다시 보지 않음 | 검출 | "opens no byte source for a file whose vault is disposed while it loads" / 1103/02-03 | +| L6 | `cleanupOwned()`가 손상 pointer를 "없음"으로 보고 정리 | 검출 | "does not clean up on a damaged pointer…" / 1103/02-03 | +| L7 | stage가 손상 marker를 고치지 않고 실패 | 검출 | "repairs a damaged release marker by staging the same manifest again" / 1103/02-03 | +| F0204 | inspect의 ref 재확인 삭제(1103/02-04 되돌림) | 검출 | "issues no receipt for a ref released while inspect() was reading it" | +| L11 | `resolveVerifiedFile`이 ref 존재를 보지 않음 | 생존(동등) | release가 receipt를 먼저 지우고 inspect가 놓은 ref에 receipt를 내지 않는다(2절) | +| N27 | 재검사 때 이전 receipt 무효화 삭제 | 검출 | "ends the previous receipt when the same file is inspected again" / 1101/02-04 ③ | +| N29 | object URL 합계 바이트 상한 삭제 | 검출 | "caps retained files and aggregate object URL leases" / 1101/02-04 ① | +| N30 | browser-managed handoff의 fragment 거절 삭제 | 검출 | "rejects cross-origin or query-bearing browser-managed targets" / 1101/02-04 ⑥ | +| N26b | `Cache-Control: no-cache` 거절 삭제 | 검출 | "keeps response validation failure codes" / 1101/02-04 ④ | +| N26 | `Set-Cookie` 응답 거절 삭제 | 검출 | 같은 테스트 / 1101/02-04 ⑦ | +| N39 | 조회가 eviction 판정 전 `keys()`를 다시 읽지 않음 | 검출 | "lists caches again before it reports the active release evicted" / 1101/02-04 ⑤ | +| N38 | host가 `storageArea`를 캡처한 localStorage와 비교하지 않음 | **생존** | 1101/02-04 ② | +| M10 | bounded download catch의 `lease?.release()` 삭제 | 검출 | "revokes the lease of a handoff that throws" / 0929/02-05 | +| M05 | `inspect()`의 판정 불가를 `verified:true`로 | **생존** | 0929/02-02 | +| F110102 | download 정책의 위험 확장자 검사 삭제(1101/02-02 되돌림) | 검출 | "refuses a download policy whose safe extension is %s" 3건 | +| F110102b | `endsWith`를 정확히 같은지로 | 검출 | 같은 테스트의 `.tar.js` 행 | +| F0202 | 본문 읽기 실패를 다시 `REPAIRABLE`로(1103/02-02 되돌림) | 검출 | "reports a cached body that cannot be read during activation as retryable…" | +| F0202-notreadable | 손상 목록에 `NOT_READABLE` 더함 | **생존** | 02-04 | +| F0202-int | 손상 목록에서 `INTEGRITY_FAILED` 뺌 | **생존** | 02-04 | +| F0202-cor | 손상 목록에서 `CORRUPT_DATA` 뺌 | **생존** | 02-04 | +| F0202-pol | 손상 목록에서 `POLICY_REJECTED` 뺌 | **생존** | 02-04 | +| F0202-lim | 손상 목록에서 `LIMIT_EXCEEDED` 뺌 | **생존** | 02-04 | +| F0205 | inspect가 손상 pointer에서 다시 실패(1103/02-05 되돌림) | 검출 | "shows a damaged pointer and the candidates it leaves behind in inspect" | +| F0205b | inspect가 일시 오류도 `UNREADABLE`로 | 검출 | 같은 테스트 | +| F0205c | `activePointer` `NONE`을 `READABLE`로 | 검출 | 같은 테스트 | +| F0201a | 제품 participant 등록 누락 | 검출 | 레시피 테스트와 participant 테스트 2건(3건 실패) | +| F0201b | 제품 participant 실패를 삼킴 | 검출 | "keeps the scope from READY when one fails, and still closes the rest" | +| F0201c | 첫 실패에서 나머지를 부르지 않음 | 검출 | 같은 테스트 | +| F0201d | 레시피 closer가 dispose하지 않음 | 검출 | 레시피 테스트 | +| F0201e | 레시피 closer가 runtime을 비우지 않음 | 검출 | 레시피 테스트 | + +집계: 31건, 검출 23 · 생존 7 · 동등 1. 지난 라운드에 살아남았던 변이 15개(1103/02-03의 L1·L4·L5·L6·L7, 1103/02-04의 L11, 1101/02-04의 N26·N26b·N27·N29·N30·N38·N39, 0929/02-02의 M05, 0929/02-05의 M10)는 12개가 검출, 2개(N38·M05)가 생존, 1개(L11)가 동등으로 바뀌었다. 생존 7개 중 5개는 이번 수정이 만든 판정 표의 경계다(02-04). + +### 6.3 배치 02-R1(실험) + +| ID | 방법 | 결과 | +| --- | --- | --- | +| E-1a | 메모리 Cache Storage. r1 배포, r2 stage. r2의 entry 하나를 다시 쓸 때까지 `TypeError`로 읽히지 않게 함. activate 2회, 재stage 2회, activate, inspect, cleanup, 재stage, activate | 현재 코드: activate 2회 `UNAVAILABLE`/`retry`/`RETRY`, 재stage 2회 같은 실패·fetch 0, activate 실패, inspect `r2:false`, cleanup 삭제 1(r2), 재stage fetch 2 성공, activate 성공. 수정 전 판정(F0202): activate `INTEGRITY_FAILED`/`REHYDRATE`, 재stage 1회 fetch 2로 고쳐짐, activate 성공 | +| E-1b | E-1a와 같고 오류가 `NotReadableError` | 현재 코드: activate·재stage 모두 `NOT_READABLE`/`REOPEN`, fetch 0, cleanup 뒤에만 회복. 수정 전 판정: 재stage로 고쳐짐 | +| E-1c | r1·r2 배포(rollback 목록에 r1). r1 entry 손상. rollback activate 2회, 재stage, activate, cleanup, activate | 현재 코드: 모두 `UNAVAILABLE`/`RETRY`. cleanup 삭제 0(r1 보존). 끝까지 rollback 불가. 수정 전 판정: 재stage(fetch 2) 뒤 rollback 성공 | +| E-1d | 활성 r1 entry 손상. 조회, 재stage, 조회 | 현재 코드: 손상 asset 조회 `UNAVAILABLE`, 다른 asset 조회 hit, 재stage 실패, 조회 계속 실패. 수정 전 판정: 재stage 뒤 조회 hit | +| E-2 | `tests/recipes/browser-file-session-capability.test.ts`의 계정 전환을 로그아웃(`unauthenticated`, subject 없음)으로 바꾼 사본 | 통과. 이전 runtime `readRange` `UNAVAILABLE`, 진행 중 download `ABORTED`, handoff 0회, 다음 runtime 선택 `SELECTED` | +| E-3 | `tests/unit/runtime-adapters-product-scope-participants.test.ts` 사본에 던지는 closer(`label: "r4-broken-closer"`) 테스트를 더함. 계정 전환, 같은 identity 알림 한 번 더 | phase `FAILED`, lifecycle `FENCED, FAILED, FENCED, FAILED`. diagnostics 기록 전 1건·후 1건(부팅 때의 `cache.operation.failed`). label·scope·participant 언급 0건. dropped 없음 | + +임시 테스트 3개는 runner가 끝에 지웠고, 오케스트레이터가 checkout을 `8a44226`으로 되돌렸다(git status 빈 상태). + +### 6.4 리뷰어의 desktop 시도(실행 안 됨) + +| 이름 | 결과 | +| --- | --- | +| `02-mut` 1차(19:39 대기 시작) | 잠금 대기 중 19:55에 취소됐다(BRIEF-2). 실행되지 않았고 checkout을 건드리지 않았다 | +| `02-mut` 2차(19:48, `nohup`) | rc=93 `CLOSED: exp.sh no longer runs experiments`. 같은 내용을 배치 02-R1로 넘겼다 | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 02-01 | Medium · P2 | 확인된 결함(진단 공백) | 제품 scope closer가 던지면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | `src/bootstrap/runtime-adapters.ts:409-423`, `src/adapters/query-cache/server-state-scope-runtime.ts:136-171`, `src/bootstrap/product-composition-contract.ts:100-103` | +| 02-02 | Low · P3 | 구조적 위험 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:492-497`, `:1083-1088`, `:1139-1144` | +| 02-03 | Low · P3 | 확인된 결함 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | `recipes/frontend-capabilities/browser-file-session-capability.ts:21-30`, `tests/recipes/browser-file-session-capability.test.ts:142` | +| 02-04 | Low · P3 | 구조적 위험(테스트 공백) | 1103/02-02의 손상 code 목록 경계 변이 5개가 살아남는다 | `src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `tests/unit/public-response-cache-repair.test.ts:236-263`, `:320` | diff --git a/docs/reviews/2026-11-05-maturity-review/03-adapters-http-state.md b/docs/reviews/2026-11-05-maturity-review/03-adapters-http-state.md new file mode 100644 index 00000000..c71af73f --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/03-adapters-http-state.md @@ -0,0 +1,205 @@ +# 영역 03 — HTTP·서버 상태·인증·진단 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `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/bootstrap/runtime-adapters.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`, `src/contracts/external-contract-runtime.ts`, 참조 기능, `scripts/create-feature.ts`·`scripts/create-feature-write-slice.ts`, `config/contracts/backend-contract-pin.json`·`backend-idempotency-answers.json`, 짝 백엔드 `45d2a478`의 `docs/web/http-contract.md`·생성기 템플릿·`RateLimitInterceptor.java` +> 깊게 본 관점 5, 6, 10, 12, 17, 20, 21, 28 +> 렌즈: 지난 High 둘(1103/03-01 = 08-01, 0929/03-03)을 선언부터 화면까지 따라간다. 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`(지난 README 10.6)과 1103/03-04. 나머지 1103/03-*와 이월 항목 +> **영역 판정(35.8): 조건부 사용 가능.** 짝 백엔드 쓰기 폼은 이제 쓸 수 있다. `create:feature --with-create`(NEVER, `--keyed`면 KEYED)가 만든 폼과 참조 폼 모양이 여기에 든다. 조건은 둘이다. (1) 폼 밖에서 `mutation.submit`을 부르는 쓰기 화면은 결과 불명 동안 같은 입력의 제출을 스스로 막는다. 키 없는 쓰기(NEVER)면 그 제출이 보호 없는 두 번째 요청이 된다(0929/03-03 남은 부분). (2) `refusedBeforeWrite`에는 백엔드 코드에서 쓰기 전에만 나온다고 확인한 업무 code만 적는다. 쓰기 뒤에도 나오는 플랫폼 code를 적어도 조립이 막지 않는다(03-01). bulk 응답은 지원하지 않는다(1103/03-02, 문서화). + +ID 표기: `03-NN`은 이번(2026-11-05) 라운드 발견이다. 지난 라운드는 `1103/03-NN`, 그 전은 `1101/03-NN`, `0929/03-NN`이다. + +**실행 상태.** 처음 넣은 desktop 실행(`03-mut`, `03-gen`)은 큐에서 취소됐다(BRIEF-2). 변이와 실험은 오케스트레이터 배치로 돌렸다(03-R01~03-R18, `scratchpad/r4/requests/03.md`). 18건 모두 매 항목 앞뒤로 checkout이 `8a44226`으로 깨끗하게 복원됐다(`scratchpad/r4/results/03/summary.txt`). 대조군(변이 없는 실행)은 게이트 로그로 갈음했다. `test:unit` 2,883건, `test:component` 270건, `test:integration` 189건이 `8a44226`에서 rc=0이다. 변이 대상 파일 9개도 모두 통과로 찍혀 있다(`desktop:/tmp/claude-gates/r4/gates/test_{unit,component,integration}.log`, 오케스트레이터 결과). 생성 기능 쪽 대조군은 03-R02 안에서 돌렸다. + +## 0. 결론 + +- **1103/03-01(= 08-01, High·P1)은 완료 기준까지 고쳐졌다.** operation이 `commandEffect.refusedBeforeWrite`에 쓰기 전 업무 code를 적는다(`src/contracts/external-contract-runtime.ts:161-171`). 표 밖 400·409·422 중 적힌 code만 `NOT_APPLIED`다(`src/adapters/http/backend-envelope.ts:317-352`). 실행기가 설치된 목록을 넘긴다(`src/adapters/http/http-execution-v3.ts:1723-1727`). 조립은 Envelope 아닌 operation, 멱등성 code, 문법 위반, 중복을 거절한다(`external-contract-runtime.ts:616-646`). 폼 테스트가 끝까지 고정한다. 선언 code면 저장 버튼이 켜지고 fetch 2회, 키 `[key-1, key-2]`다. 선언하지 않은 code면 꺼진 채다(`tests/component/form-foundation.test.tsx:960-1008`). 생성기는 `_INVALID`를 적고 필드 오류로 보인다(`scripts/create-feature-write-slice.ts:306`, `:397-404`). 규칙을 깨는 변이 6개가 모두 기대한 테스트에서 실패했다. 판정을 끈 변이, 실행기가 목록을 넘기지 않는 변이, 런타임과 조립의 멱등성 code 거절을 뺀 변이, 생성기 선언을 지운 변이, 생성한 기능에서 선언 줄을 지운 변이다(03-R02 G1, 03-R03~R06, 03-R18). +- **0929/03-03(High·P1)은 화면 버튼 쪽만 고쳐졌다(일부).** 훅이 키 없는 intent에 재전송을 주지 않는다(`application-query.ts:800-804`, `:836-846`). 화면은 플래그가 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 두 가드를 깨는 변이는 템플릿 테스트와 생성 NEVER 페이지 테스트에서 모두 검출됐다(03-R07, R08, R02 M08·M09). 남은 길이 있다. 같은 입력을 다시 `submit`하면 훅은 키 없는 결과 불명 intent를 그대로 다시 보낸다(`application-query.ts:557-561`, `:590-596`). 실험 X1: 재전송은 `null`인데 같은 입력 `submit`이 두 번째 POST를 보냈다. 두 요청 모두 키가 없다(`keys=[null,null]`, 03-R01). 폼(`use-app-form.ts:325`)과 두 페이지가 막을 뿐 훅은 막지 않는다. 남은 부분은 Medium·P2로 본다. +- **503 `IDEMPOTENCY_COMPLETION_UNKNOWN`과 1103/03-04는 고쳐졌다.** 백엔드가 정한 5xx 넷을 status와 code를 함께 맞춰 `MAYBE_APPLIED`로 고정한다(`backend-envelope.ts:246-280`). 분류기가 `NOT_APPLIED`라고 해도 바뀌지 않고 자동 재전송도 없다(`tests/integration/http-execution-v3-envelope.test.ts:634-697`, `:912-933`). 백엔드 답 표 사본과 양방향으로 대조하는 테스트가 생겼다(`tests/unit/backend-contract-pin.test.ts:105-142`). 사본 7행은 백엔드 `45d2a478` §2 두 표와 §4 `REQUEST_TIMEOUT`과 같다. `COMPLETION_UNKNOWN` 행을 지운 변이는 단위·pin·통합 테스트 6건이 잡았다(03-R09). +- **나머지 1103/03-*:** 03-02 일부(bulk는 미지원으로 문서화), 03-03 고쳐짐, 03-05 고쳐짐, 03-06 고쳐짐(VD-23 부분은 14 영역), 03-07 일부(백엔드 목록 GET 결정 대기), 03-08(= 10-02) 03 부분 고쳐짐. 이월: 1101/03-03·1101/03-06·0929/03-06 고쳐짐, 1101/03-04·0929/03-02 남음. +- **새 발견은 2건, 모두 Low·P3다.** 03-01: `refusedBeforeWrite`가 프론트 자신의 6.1절 표가 "쓰기 뒤 가능"으로 적은 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다. 03-02: 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다. 둘 다 실험으로 확인했다(X2, X4, 03-R01). +- **변이 19개가 모두 검출됐다.** 템플릿 테스트 대상 16개(03-R03~R18)와 생성 기능 대상 3개(03-R02)다. 지난 라운드의 생존 변이 넷도 이제 잡힌다. M1 identity lease(03-R12), M3 반사 correlation 문법(03-R13), M6 표의 status 대조(03-R10), M7 처리 중 409 무재전송(03-R11)이다. +- **고친 커밋이 이 영역의 검사를 약하게 만든 곳은 찾지 못했다.** 지워진 단언은 다른 발견(1103/08-02, 08-05)의 동작 변경에 맞춘 교체였다(2절 끝). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 읽기만 했다 | +| 커밋·작업 상태·확인 시점 | 프론트 `8a44226`(laptop worktree, HEAD = 기준). 백엔드 HEAD `45d2a478` = `config/contracts/backend-contract-pin.json`의 commit. 2026-11-05 19~20시 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 사용자 목표는 두 템플릿을 짝으로 써서 빨리 출시하는 것 | +| 필수 요구와 규모·운영 목표 | 짝 백엔드 `docs/web/http-contract.md` §1·§2·§4, 프론트 계약 `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1, 매뉴얼 `docs/manual/02-decision-tables.md` 3·4절. 수치 운영 목표는 없다 | +| 읽은 코드·구성 범위 | 줄 단위: `backend-envelope.ts` 전부, `http-execution-v3.ts` 450~520·1440~1510·1700~1810, `feature-http-binding.ts` 280~575, `external-contract-runtime.ts` 155~175·450~670·800~845, `api-operations.ts` 125~143, `application-query.ts` 340~400·520~850·860~940, `use-app-form.ts` 170~400, `async-state.ts` 60~140, `async-surface.tsx` 120~235, `runtime-adapters.ts` 180~260·560~660, `fileserver-upload.ts` 150~200·685~705, 참조 폼 페이지·계약 기여·`use-reference-feature.ts`, `create-feature-write-slice.ts` 1~320·380~420·600~1010, `create-feature.ts` 40~160·760~830·1740~1800, `test-feature-scaffold.ts`·`test-sample-removal.ts`의 생성 부분, 위 수정의 테스트 9개 파일. `git diff e40684b..8a44226`(영역·흐름 20파일, +2,129/−277). 백엔드: `http-contract.md` §1~§4, 생성기 템플릿(UseCase·ErrorCode·RejectedException·Controller·HttpRequest), `new-feature.sh` 이름 변환, `RateLimitInterceptor.java`, `CorsSettings.java`. `src/adapters/auth`는 주석만, `browser-rpc`·`query-cache`·`diagnostics`·`telemetry`는 `e40684b` 뒤 변경이 없다(`git diff --stat`) | +| 수행한 테스트·실험 | 실행 환경 = desktop. 이 영역이 직접 돌린 `03-mut`, `03-gen`은 큐에서 취소됐다. 오케스트레이터 배치 03-R01(실험 X1~X4), 03-R02(생성 NEVER 슬라이스 + 변이 3), 03-R03~R18(변이 16)을 돌렸다(6절). 게이트는 오케스트레이터 결과를 인용한다. local env에서 `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci`는 rc=0이다. `verify:documentation`은 rc=1이다(desktop에 짝 백엔드 형제 디렉터리가 없어 문서의 백엔드 경로를 못 찾음, 이 영역의 결함이 아니다). CI env에서 FE-GATE-001~012·020은 rc=0이고 FE-GATE-013은 rc=1이다(13 영역) | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `e40684b..8a44226`의 영역 커밋 34개(`git log --oneline -- <경로>`). 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +지난 라운드 README 12절의 03 행 8개, 10.3절에서 합친 08-01·10-02, 지난 03 문서 2절이 "남음"으로 적은 이월 6개다. 13절 추가 발견 중 03 영역은 없다. README 14.4는 주장으로만 봤다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/03-01 (= 1103/08-01) High·P1 | 짝 백엔드의 업무 규칙 거절(표 밖 400·409·422)이 모든 쓰기에서 결과 불명이 된다 | **고쳐짐** (변이 6개 검출: 03-R02 G1, 03-R03~R06, 03-R18) | 완료 기준 넷을 코드와 테스트로 확인했다. ① 선언한 code는 결과 불명이 아니고 저장 버튼이 켜진다. 고친 값의 두 번째 요청은 새 키다(`form-foundation.test.tsx:960-987`, 키 `["key-1","key-2"]`). ② 선언하지 않은 code는 결과 불명이다(`:989-1008`, `http-execution-v3-envelope.test.ts:749-765`). ③ 처리 중 409를 목록에 넣으면 조립이 실패한다(`tests/unit/external-contract-runtime.test.ts:274-284`, 거절 `external-contract-runtime.ts:637-641`). 실행기도 따로 무시한다(`backend-envelope.ts:323-324`). ④ 생성기와 매뉴얼: 생성 create가 `refusedBeforeWrite: ["_INVALID"]`를 적고(`create-feature-write-slice.ts:306`) `mapProblem`이 이름 필드 오류로 바꾼다(`:397-404`). 생성 테스트가 "필드에 보이고 다시 저장"을 고정한다(`:864-886`). 이 테스트는 `test:sample-removal`(NEVER, `scripts/test-sample-removal.ts:496-503`)과 `test:feature-scaffold`(KEYED, `scripts/test-feature-scaffold.ts:64-69`)에서 돈다. FE-GATE-020 rc=0(오케스트레이터). 매뉴얼 `02-decision-tables.md:122`, `:179-185`, `01-add-a-feature.md:223`, `:359`. 백엔드 쪽 사실: `_INVALID`를 던지는 곳은 `build()` 하나이고 트랜잭션 전이다(`Create__Feature__UseCase.java.tmpl:52-60`, `__Feature__RejectedException.java.tmpl:21-27`). 남은 것: 선언하지 않은 업무 code는 설계대로 결과 불명이다(완료 기준). 화면 쪽 막다른 길은 08 영역이 본다. 플랫폼 code 선언을 막지 않는 것은 새 03-01이다. 변이 결과: M01(판정 끔)은 단위 3·통합 3·폼 1건, M06(실행기가 목록을 안 넘김)은 통합 3·폼 1건, M02(런타임 멱등성 접두사 거절 제거)는 "never lets a declaration decide an idempotency answer or a table code", M04(조립 거절 제거)는 멱등성 code 5개 `it.each`, M22(생성기 선언 제거)는 `create-feature.test.ts` "matches the backend scaffold's NOT_IDEMPOTENT create with a NEVER command"가 잡았다. 생성한 `memo-feature`에서 선언 줄을 지우면(G1) 생성 테스트 "shows the backend's refusal of the name on the field and saves again"과 "reads 400 MEMO_INVALID as not applied, on the name field"가 실패한다. 변이 없는 생성 테스트는 4 files / 21 tests 통과(03-R02 BASELINE) | +| 0929/03-03 High·P1 | 결과 불명 화면의 "같은 요청으로 다시 보내기"가 키 없는 쓰기에도 열려 있다 | **일부** (가드 변이 4개 검출: 03-R07, R08, R02 M08·M09. 남은 길 실험 03-R01) | 고쳐진 것: `canResend`가 intent의 키를 본다(`application-query.ts:836-846`). 없으면 `resendUnknownEffect`가 `null`이다(`:800-804`). 훅이 `canResendUnknownEffect`와 `state.unknownEffectResendable`을 낸다(`:806-828`, `async-state.ts:132-138`). 화면은 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 테스트: `application-mutation-admission.test.tsx:541-564`, `async-surface.test.tsx:105-136`, 생성 NEVER 페이지 테스트(`create-feature-write-slice.ts:754-770`). KEYED는 그대로 같은 키로 보낸다(`application-mutation-admission.test.tsx:503-539`). NEVER intent에 키를 넣는 길도 없다. 정책이 descriptor에서 키 여부를 받고(`src/contracts/server-state.ts:281-299`), 실행기가 NEVER intent의 키를 보내기 전에 거절한다(`http-execution-v3.ts:507-512`). **남은 것 ①** 같은 입력의 재제출. `submit`은 같은 canonical input의 결과 불명 admission을 찾아 그 intent를 그대로 쓴다(`application-query.ts:557-561`, `:590-596`). 키 없는 intent면 서버가 가려낼 수 없는 두 번째 요청이다. 훅은 이것을 막지 않는다. 막는 곳은 폼(`use-app-form.ts:325`, `unknownSubmissionRef`)과 두 페이지의 버튼·`onSubmit` 검사뿐이다(`reference-resource-form-page.tsx:52-66`, `create-feature-write-slice.ts:656-669`). 런북 6.3-4는 같은 입력 재저장을 "같은 `Idempotency-Key`로 보낸다"고만 적고 키 없는 경우를 적지 않는다(`docs/operations/api-contract-and-server-state-recovery.md:254-260`). 고친 커밋도 이 경로를 바꾸지 않았다고 적었다(`2017ef76` 본문 "위험·한계"). 실험 X1(03-R01): NEVER 쓰기의 첫 요청이 보낸 뒤 연결이 끊겼다. 결과 불명이 되고 `canResendUnknownEffect=false`, `resendUnknownEffect()`는 `null`, fetch는 1회 그대로였다. 그 뒤 같은 입력을 `submit`하자 fetch 2회, 키 `[null,null]`, 두 번째 응답 성공이다. 첫 요청이 실제로 적용됐다면 `NOT_IDEMPOTENT`인 짝 백엔드 create에는 같은 항목이 둘 생긴다(추론. 실험은 fetch mock이다). 같은 실험의 KEYED는 재전송이 같은 키(`key-1`, `key-1`)를 썼다. **남은 것 ②** 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을 그린다(`async-surface.tsx:227`의 `!== false`. 실험 X3(03-R01): `deriveAsyncState({ data, hasMutationEffectUnknown: true })`로 그리면 버튼이 있다). 콜백이 `resendUnknownEffect`면 `null`이라 보내지는 않는다. 남은 부분의 심각도는 Medium·P2로 본다. 템플릿의 폼 경로는 막혀 있고, 폼 밖에서 `submit`을 다시 부르는 손으로 만든 화면이어야 닿는다. 닿으면 피해는 중복 생성이다. 최소 개선: 훅의 `submit`이 키 없는 결과 불명 admission과 같은 입력이면 보내지 않고 `UNKNOWN_EFFECT_PENDING` 같은 `NOT_STARTED` 실패를 돌려준다. 런북 6.3-4에 키 없는 경우를 적는다 | +| 1103/03-02 Medium·P2 | Envelope 읽기가 `meta.page`를 버리고 bulk `results`를 거절한다 | **일부** (bulk는 미지원으로 문서화. 변이 검출 03-R15) | `meta.page`를 백엔드 범위(정수, `size` 1~100)로 읽고 범위 밖이면 버린다(`backend-envelope.ts:21-28`, `:49`, `:96-116`). 실행 결과에 `page`가 실리고(`http-execution-v3.ts:1454-1468`, `:1509`) `mapSuccess(value, { page })`로 간다(`feature-http-binding.ts:419-428`). 생성 목록은 `page?.total ?? items.length`를 쓰고 화면이 그 수를 보인다(`create-feature.ts:694-697`, `:1203`). 테스트 `http-execution-v3-envelope.test.ts:347-387`. bulk: 계약 4.1이 "지원하지 않는다, `ENVELOPE_MISMATCH`"로 적었다(`backend-api-and-server-state-contract.md:188-190`). README 14.4와 같은 판정이다 | +| 1103/03-03 Medium·P2 | 쓰기 operation을 `SAFE`로 설치할 수 있다 | **고쳐짐** (변이 검출 03-R14: "rejects SAFE retry semantics on a POST·PUT·PATCH·DELETE" 4건) | 조립이 쓰기의 `SAFE`를 거절한다(`external-contract-runtime.ts:564-571`). 읽기는 `SAFE`·`IDEMPOTENT`만 받는다(`:533-543`). 테스트 `external-contract-runtime.test.ts:181-200`. 생성 쓰기는 `NEVER`/`KEYED`다(`create-feature-write-slice.ts:227-236`) | +| 1103/03-04 Low·P2 (+ 지난 README 10.6 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`) | 백엔드의 다른 멱등성 실패와 503 `REQUEST_TIMEOUT`이 패키지 분류기에 달려 있다 | **고쳐짐** (변이 검출 03-R09: 단위 2·pin 1·통합 3건) | `MAYBE_APPLIED_ANSWERS` 네 행(503 `IDEMPOTENCY_UNAVAILABLE`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, 500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 503 `REQUEST_TIMEOUT`)을 status와 함께 맞춘다(`backend-envelope.ts:246-280`). 표가 판정하면 분류기를 부르지 않는다(`http-execution-v3.ts:1764-1771`). 관대한 분류기에도 셋은 `MAYBE_APPLIED`이고(`http-execution-v3-envelope.test.ts:680-697`) 자동 재전송이 없다(`:912-933`). 다른 5xx에 붙은 같은 code는 표 밖이다(`tests/unit/backend-envelope.test.ts:112-122`). 백엔드 답 표를 `config/contracts/backend-idempotency-answers.json`에 옮기고 양방향 대조한다(`backend-contract-pin.test.ts:105-142`). 사본 7행을 백엔드 `45d2a478` `http-contract.md` §2 두 표, §4 첫 행과 한 줄씩 대조했다. 모두 같다. 지난 제안의 "`RECOVERY_REQUIRED`는 재전송 불가 표시"는 이제 필요 없다. 백엔드 §2가 "같은 키 재전송은 안전하다"로 바뀌었다. 남은 것: §4의 rate-limit 503 둘이 사본에 없다(새 03-02) | +| 1103/03-05 Low·P3 | 결과 불명 쓰기의 진단·텔레메트리에 effect와 원인이 없다 | **고쳐짐** (변이 검출 03-R17: 진단 표 9행과 observability 1건) | 진단·텔레메트리가 닫힌 5값 `effect_certainty`를 싣는다(`runtime-adapters.ts:204-209`). 결과 불명의 원인이 닫힌 6값 `reason`으로 진단에 간다(`backend-envelope.ts:233-239`, `:298-308`, `http-execution-v3.ts:1728-1736`, `:1788-1792`). 테스트 `http-execution-v3-envelope.test.ts:801-830`. Envelope 아닌 operation의 결과 불명은 원인 없이 effect만 남는다(`39c1de2e` 본문 위험란) | +| 1103/03-06 Low·P3 | `AppFailure.traceId`를 채우는 곳이 없다, VD-23 401 문장 | **고쳐짐** (traceId. 변이 검출 03-R16) | 실패 Envelope의 `meta.traceId`가 `traceReference`를 거쳐 `AppFailure.traceId`가 된다(`http-execution-v3.ts:1716-1721`, `feature-http-binding.ts:376-389`). 테스트 `http-execution-v3-envelope.test.ts:441-455`. VD-23 부분은 14-03으로 합쳤다(10.3절). 지금 VD-23은 "401 response 뒤 숨은 refresh-and-replay를 하지 않는다"를 적는다(`VD-23-api-transport-selection-and-rest-execution.md:435-437`). 마감 목록·테스트 목록의 "401 recovery" 낱말은 남았다(`:407`, `:413`, `:714`, `:729-730`). 14 영역에 넘긴다. 소비자 0인 `projectCertaintyToUi`도 남았다(`http-effect-certainty.ts:155-167`). 배럴 밖이라 확장 지점이 아니다. 결함으로 세지 않는다 | +| 1103/03-07 Low·P3 | 두 생성기가 만드는 operation이 맞지 않는다 | **일부** (결정 대기: 백엔드) | 프론트 생성기가 백엔드 경로 규칙(`create-feature.ts:125-134`)과 create·read-by-id(`--with-create`, `create-feature-write-slice.ts:1-17`)를 맞췄다. NEVER가 기본이라 백엔드 `NOT_IDEMPOTENT`와 맞는다(`:12-15`). 백엔드 생성기에는 목록 GET이 아직 없다(`__Feature__Controller.java.tmpl:49-68`). 생성 목록이 405를 받는다고 주석이 적는다(`create-feature.ts:765-771`) | +| 1103/03-08 (= 1103/10-02로 합침) Low·P3 | 표의 "상태와 code를 함께" 규칙과 처리 중 409 무재전송 규칙의 테스트가 없다 | **03 부분 고쳐짐** (지난 생존 변이 M6·M7 이제 검출: 03-R10 "reads a table code under another status" 5행 외, 03-R11 "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own"과 pin 1건) | M6: 표 code가 다른 status로 오면 `MAYBE_APPLIED`(`backend-envelope.test.ts:96-101`, 409 `VALIDATION_FAILED`). M7: 처리 중 409를 자동 재전송하지 않는다(`http-execution-v3-envelope.test.ts:896-910`). 10-02 전체는 10 영역이 판정한다 | +| 1101/03-03 Low·P3 | mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 적는다 | **고쳐짐** | `commandMutationIdentity(descriptor)`가 둘을 descriptor에서 받는다(`server-state.ts:281-299`). 참조(`use-reference-feature.ts:57-61`)와 생성기(`create-feature-write-slice.ts:505`)가 쓴다. 정책에 문자열을 직접 적는 길은 남고, 매뉴얼이 "못 잡음"으로 적는다(`f59a806` 본문) | +| 1101/03-04 Low·P3 | 효과 판정과 화면 분류가 두 함수로 나뉜다 | **남음** (문서화) | kind는 `envelopeFailureReading`(`backend-envelope.ts:378-398`), effect는 `envelopeFailureEffect`(`:340-352`)가 따로 정한다. 필드 목록 있는 표 밖 422는 필드 오류와 저장 꺼짐이 함께 나온다. 테스트가 이것을 기대값으로 둔다(`form-foundation.test.tsx:1012-1030`). 선언 없이 `mapProblem`만 둔 업무 code도 같은 모양이고, 매뉴얼이 적는다(`02-decision-tables.md:185`). 짝 백엔드의 필드 검증은 400이라(백엔드 `http-contract.md` §4) 짝 사용에서는 드물다. Low 유지 | +| 1101/03-06 Low·P3 | V3 시간 초과 분류와 반사 correlation 문법 검사의 테스트가 없다 | **고쳐짐** (지난 생존 변이 M3 이제 검출: 03-R13, 두 건 모두 실패) | 문법 검사(`http-execution-v3.ts:1798-1810`)를 테스트 두 건이 고정한다. 마크업이 든 값과 129자 값을 버리고 보낸 id를 쓴다(`tests/integration/http-execution-v3-observability.test.ts:213-247`). 시간 초과 절반은 지난 라운드에 고쳐졌다 | +| 0929/03-02 Medium·P2 | `x-correlation-id` CORS 허용이 문서 통제뿐이다 | **남음** | 프론트 확인 수단은 계약 §5(`backend-api-and-server-state-contract.md:240-254`)와 런북 5.2-6(`api-contract-and-server-state-recovery.md:184-193`) 문장뿐이다. 짝 백엔드 기본은 모든 요청 헤더를 허용한다(백엔드 `CorsSettings.java:47-48`). `Idempotency-Key`도 같은 조건이다 | +| 0929/03-06 Low·P3 | UNKNOWN 동안 identity lease를 잡는 코드의 테스트가 없다 | **고쳐짐** (지난 생존 변이 M1 이제 검출: 03-R12) | 코드 `application-query.ts:669-672`. 두 칸 레지스트리에서 다른 입력 둘이 들어온 뒤에도 같은 입력이 같은 키를 받는 테스트가 생겼다(`application-mutation-admission.test.tsx:483-500`) | + +**고친 커밋이 검사를 약하게 만들었는가(관점 10·21).** `git diff e40684b..8a44226`의 영역·흐름 파일과 위 테스트 9개를 봤다. 지워진 단언은 셋이다. ① `form-foundation.test.tsx`의 `validationMessage("SOME_FUTURE_CODE")` 한 건은 5개 code로 늘어난 `it.each`로 바뀌었다(1103/08-03). ② 저장 중 버튼 `toBeDisabled()`는 `aria-busy`와 포커스 단언으로 바뀌었다. 두 번째 클릭 거절은 `dblClick` 뒤 `toHaveBeenCalledOnce()`가 그대로 본다(`tests/features/reference-feature/reference-page.test.tsx:332-339`, 1103/08-02). ③ Envelope 표 테스트의 422 기대 kind가 `VALIDATION_REJECTED`에서 `UNKNOWN_CLIENT_FAILURE`로 바뀌었다(1103/08-05의 의도된 동작 변경, effect 기대는 같다). `metaSchema`의 `page`에 붙은 `.catch(undefined)`(`backend-envelope.ts:49`)는 완화가 아니다. 그 전에는 `.strip()`이 `page`를 늘 버렸다. 새 skip·quarantine·시간 상한 상향은 없다. **약해진 검사는 찾지 못했다.** + +## 3. 이번 발견 (36.3) + +새 발견 2건: Low 2 · P3 2 · 구조적 위험 1, 개선 제안 1. High 이상과 P1은 없다. 0929/03-03의 남은 부분(Medium·P2 제안)은 2절에 이월로 적었다. 새 발견으로 세지 않는다. + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 03-01 | Low | P3 | 구조적 위험 | 21, 6, 17, 5 | `refusedBeforeWrite`가 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code도 받아, 선언 하나로 결과 불명이어야 할 실패가 새 요청이 된다 | +| 03-02 | Low | P3 | 개선 제안 | 17, 6, 28, 9 | 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다 | + +### 03-01 `refusedBeforeWrite`가 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code도 받아, 선언 하나로 결과 불명이어야 할 실패가 새 요청이 된다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 21, 6, 17, 5 | +| 근거 | 조립 검사는 code 문법, `IDEMPOTEN(T|CY)_` 접두사, 중복, Envelope 여부만 본다(`external-contract-runtime.ts:608-646`). 실행기의 fail-close도 멱등성 접두사와 `REFUSED_BEFORE_WRITE`의 세 code만 뺀다(`backend-envelope.ts:317-327`). 그런데 프론트 계약 6.1절 표는 플랫폼 code 다수를 "쓰기 뒤 가능 → `MAYBE_APPLIED`"로 적는다. `BAD_PARAMETER`(어느 층이든 `IllegalArgumentException`), `MAPPING_FAILED`(멱등성 응답 직렬화는 action 뒤), `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, fileserver code들이다(`backend-api-and-server-state-contract.md:302-308`). 이 code를 `refusedBeforeWrite`에 적으면 조립이 통과하고, 그 code로 온 400·409·422가 `NOT_APPLIED`가 된다(`backend-envelope.ts:346-349`). 다음 저장은 새 키다. 매뉴얼은 "쓰기 전임을 확인했을 때만 적는다"를 문장으로 요구한다(`02-decision-tables.md:183`). 실험 X2(03-R01): `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_UNIQUE_VIOLATION`, `LOCK_ACQUISITION_TIMEOUT`을 선언한 NEVER 쓰기 계약이 `composeContractContributions`를 통과했다(`composeError=none`). 설치된 목록에 넷이 그대로 있고, 각 code의 400·409 답은 모두 `NOT_APPLIED`였다 | +| 발생 조건 | 개발자가 폼을 막는 400 `BAD_PARAMETER`나 409 `DB_UNIQUE_VIOLATION`을 보고 "폼이 다시 저장되게" 그 code를 목록에 넣는다. 그리고 그 code가 실제로 쓰기 뒤에 난다 | +| 영향 | 쓰기 뒤에 난 실패가 "적용 안 됨"으로 보인다. 사용자가 다시 저장하면 새 키(KEYED)나 키 없는 새 요청(NEVER)이 나가 같은 항목이 둘 생길 수 있다. 중복은 드문 조건 둘이 겹쳐야 한다 | +| 심각도·우선순위 | Low · P3 — 매뉴얼을 어긴 선언이 먼저 있어야 한다. 그러나 프론트가 이미 6.1절 표로 그 code들을 "쓰기 뒤 가능"으로 알고 있어, 막는 비용이 몇 줄이다 | +| 통제·증거 | 멱등성 code: M4(조립 거절) / 플랫폼 "쓰기 뒤 가능" code: M1(매뉴얼 문장) · E1(코드·문서 대조), E2(실험 X2, 03-R01) | +| 확실성과 남은 가정 | 조립과 판정의 동작은 코드로 확정이다. 개발자가 실제로 그런 선언을 할지는 가정이다. `DB_UNIQUE_VIOLATION`처럼 커밋에서 롤백되는 code는 DB 효과만 보면 적용 안 됨일 수 있다. 6.1절이 "쓰기 뒤 가능"으로 둔 판정을 그대로 따랐다 | +| 결정의 근거 | `[기록]` D2 ①은 "함수가 아니라 code 목록이라 리뷰할 수 있고, 상태 범위를 통째로 `NOT_APPLIED`로 만들 수 없다"를 골랐다(지난 README 14.2). 멱등성 code만 조립 거절 대상으로 정했다. `[사실]` 6.1절 표는 프론트가 백엔드 코드를 읽고 만든 판정이고 같은 repo에 있다. `[추론]` 업무 code는 기능 작성자만 알지만, 플랫폼 code의 단계는 템플릿이 이미 안다. 그 지식을 조립 검사가 쓰지 않는다 | +| 이해 비용 | 폼이 막힌 개발자는 막는 code를 목록에 넣고 싶어진다. 그 code가 업무 code인지 플랫폼 code인지 가르려면 6.1절 표를 찾아 읽어야 한다 | +| 최소 개선 방향 | 6.1절 표의 "쓰기 뒤 가능" 플랫폼 code를 `backend-envelope.ts`에 상수 목록으로 두고, 조립이 그 code의 선언을 거절한다. 거절 문구에 6.1절을 적는다. `backend-contract-pin.test.ts`처럼 그 목록과 6.1절 표를 대조하는 테스트를 하나 둔다 | +| 대안 비교 | (a) 현상 유지: 매뉴얼 문장에 기댄다. (b) 플랫폼 code 거절(위): 몇 줄, 6.1절과 함께 갱신. (c) 업무 code 접두사 규칙(예: `_`로 시작하는 code만 허용): 다운스트림 code 이름을 강제해 과하다. (b)가 가장 좁다 | +| 단순화의 보존 조건 | 업무 code 선언은 지금처럼 된다. 멱등성 code 거절은 그대로다 | +| 비용·부작용 | 상수 1개, 조립 검사 몇 줄, 테스트 1건. 이미 플랫폼 code를 적은 다운스트림은 부팅에서 실패한다(CHANGELOG [계약] 행) | +| 재검토 조건 | 백엔드가 실패 Envelope에 단계 신호(D2 ②)를 내면 선언 목록 자체를 다시 본다 | +| 완료 기준 | X2의 계약이 조립에서 "`BAD_PARAMETER`는 6.1절에서 쓰기 뒤 가능" 이유로 거절된다 | +| 검증 방법 | `tests/unit/external-contract-runtime.test.ts`의 `refusedBeforeWrite` 묶음에 `it.each` 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-02 백엔드 §4의 rate-limit 503 두 code가 답 표 밖이라, 생성 기능의 쓰기는 실행 전 거절을 결과 불명으로 보인다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 17, 6, 28, 9 | +| 근거 | 백엔드 §4 표는 web 전용 code 넷을 적는다. `REQUEST_TIMEOUT`, `IDEMPOTENCY_KEY_INVALID`, `RATE_LIMIT_UNAVAILABLE`(503, retryable, `Retry-After` 있음), `RATE_LIMIT_INCOMPATIBLE`(503)이다(백엔드 `docs/web/http-contract.md` §4 표). 뒤의 둘은 `RateLimitInterceptor.preHandle`이 컨트롤러 전에 낸다(백엔드 `RateLimitInterceptor.java:30-63`). pin은 §4를 대조했다고 적는다(`backend-contract-pin.json`의 `sectionsCompared: ["1","2","4"]`). 그러나 답 표 사본에는 §4에서 `REQUEST_TIMEOUT` 한 행만 있다(`config/contracts/backend-idempotency-answers.json`의 7행). 프론트 표에도 없다(`backend-envelope.ts:152-172`, `:246-269`). 그래서 이 503은 기능 분류기가 정한다(`http-execution-v3.ts:1764-1771`). 생성 기능의 분류기는 늘 `MAYBE_APPLIED`다(`create-feature-write-slice.ts:298`). 같은 생성 기능이 429 `RATE_LIMIT_EXCEEDED`는 `classifyStatus`로 `NOT_APPLIED`로 본다(`:303`). 실험 X4(03-R01, 생성 기능과 같은 분류기): 429 `RATE_LIMIT_EXCEEDED` → `RATE_LIMITED/NOT_APPLIED`, 503 `RATE_LIMIT_UNAVAILABLE` → `SERVER_FAILURE/MAYBE_APPLIED`, 503 `RATE_LIMIT_INCOMPATIBLE` → `SERVER_FAILURE/MAYBE_APPLIED` | +| 발생 조건 | rate-limit 저장소가 응답하지 않거나 제공자가 맞지 않는 동안 생성 기능으로 쓰기를 저장한다 | +| 영향 | 아무 일도 일어나지 않은 저장이 결과 불명이 된다. NEVER 쓰기는 재전송 버튼이 없어(0929/03-03 수정) "변경됨으로 확인"을 눌러야 폼이 풀린다. 사실과 다른 확인이다. KEYED는 같은 키 재전송으로 빠져나온다. 데이터 피해는 없다(안전 쪽) | +| 심각도·우선순위 | Low · P3 — 드문 장애 중에만 생기고 안전 쪽으로 실패한다 | +| 통제·증거 | M0(이 code의 판정이 없다) · E1(백엔드 코드·문서, 프론트 표 대조), E2(실험 X4, 03-R01) | +| 확실성과 남은 가정 | `preHandle`이 컨트롤러 전이라는 것은 코드로 확인했다. 다른 필터가 같은 code를 쓰기 뒤에 내는 곳은 찾지 못했다(백엔드 `src/**/main`에서 두 곳뿐) | +| 결정의 근거 | 적용 제외 — 기존 표에 행을 채우는 문제다 | +| 이해 비용 | 쓰기를 만드는 사람은 503이 표에 있는지 `backend-envelope.ts`를 읽어야 안다. 매뉴얼 4절은 표의 5xx 넷만 적는다(`02-decision-tables.md:176-178`) | +| 최소 개선 방향 | 답 표 사본에 §4의 두 행을 `refusedBeforeWrite: true`, `sameKeyResend: false`로 옮긴다. 프론트 거절 표에 status와 함께 `NOT_APPLIED`로 더한다. 그러면 `backend-contract-pin.test.ts`가 둘을 함께 지킨다 | +| 대안 비교 | 적용 제외 — 표의 범위 누락이다 | +| 단순화의 보존 조건 | 503 `IDEMPOTENCY_UNAVAILABLE`의 `MAYBE_APPLIED`와 KEYED 자동 재전송은 그대로다 | +| 비용·부작용 | JSON 2행, 표 2행, 6.1절·매뉴얼 4절 1줄 | +| 재검토 조건 | 백엔드 §4 표가 바뀔 때(pin을 올리는 같은 변경) | +| 완료 기준 | X4에서 503 `RATE_LIMIT_UNAVAILABLE`이 분류기와 상관없이 `NOT_APPLIED`/`retry-later`다 | +| 검증 방법 | `backend-contract-pin.test.ts`가 새 행을 읽는다. `backend-envelope.test.ts`에 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +**다른 영역에 넘기는 관찰(세지 않음).** `fileserver-upload.ts`는 같은 백엔드 답을 자기 표로 따로 판정한다(`src/adapters/http/fileserver-upload.ts:158-180`, `:690-704`). 503 `IDEMPOTENCY_UNAVAILABLE`을 `backend-envelope.ts`는 `MAYBE_APPLIED`로, 업로드 client는 `NOT_APPLIED`로 본다. 4xx는 기본이 `NOT_APPLIED`다. 그래서 백엔드가 §2에 409 계열 code를 새로 더하면 `backend-contract-pin.test.ts`는 `backend-envelope.ts`만 알리고, 업로드 client는 그 code를 조용히 `NOT_APPLIED`로 읽는다. 갈라진 판정 복사본인지는 01 영역이 판단한다. + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1 | P — 짝 백엔드 판정이 한 모듈에 모였고(`backend-envelope.ts`), 선언 목록은 조립 때 고정 사본이 된다(`external-contract-runtime.ts:813-842`). 바인딩의 `default` 가지가 새 위반 종류를 `ENVELOPE_MISMATCH`로 흡수한다(`feature-http-binding.ts:571-572`, 1101 R3). 업로드 client가 같은 답을 따로 판정한다(01 영역) | +| 2 | 구조적 성숙도 | 다른 영역 | — | 게이트 | > 12·16 영역. `check:architecture` rc=0(오케스트레이터) | +| 3 | 변경 용이성 | 적용 | M3 / M2 | E1 | P — 쓰기 하나에 맞출 곳이 descriptor 한 곳으로 줄었다(`commandMutationIdentity`, 1101/03-03 고쳐짐). 업무 code는 descriptor 한 줄로 선언한다 | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 실패 판정 순서(401·403·429 → 표 → 선언 목록 → 분류기 → 폼 분기)를 알아야 한다. 매뉴얼 02 4절이 흐름도와 표로 설명한다(`02-decision-tables.md:150-185`) | +| **5** | 위험 가시성 | 적용 | M3 / M2 | E1 | P — 선언 목록이 descriptor와 FE-REG-API 행에 보인다(`src/contracts/api-operations.ts:130-143`). 플랫폼 code를 적은 위험은 descriptor만 보고 알 수 없다(03-01) | +| **6** | 실패 성숙도 | 적용 | M4 / M3 | E2(변이 19개 검출, 실험 X1·X4) | P — 업무 거절 뒤 다시 저장(1103/03-01), 5xx 넷 고정(1103/03-04), `SAFE` 쓰기 거절(1103/03-03), NEVER 재전송 버튼 제거가 들어왔다. 남은 것: 키 없는 같은 입력 재제출(0929/03-03 일부), 플랫폼 code 선언(03-01), rate-limit 503(03-02) | +| 7 | 운영 성숙도 | 적용 | M2 / M2 | E2 | P — `effect_certainty`로 결과 불명 쓰기를 셀 수 있다(1103/03-05). 진단 sink는 메모리 버퍼뿐이다 | +| **8** | 디버깅 가능성 | 적용 | M2 / M2 | E2 | O — 보낸 id fallback, `traceId`, 반사 id 문법, 전송 전 거절 `reason`, 결과 불명 `reason`이 모두 있다. Envelope 아닌 결과 불명은 원인이 없다(작은 잔여) | +| 9 | 유지보수 성숙도 | 적용 | M3 / M3 | E2 | P — pin과 답 표 사본을 테스트가 양방향으로 대조한다(`backend-contract-pin.test.ts`). 사본이 §4를 일부만 옮겼다(03-02). 백엔드 문서 변경 감지는 게이트 밖이다(12 영역) | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2 | O — 수정마다 테스트가 생겼고 게이트에서 통과한다(대상 9파일, 오케스트레이터). 규칙을 깨는 변이 19개가 모두 기대한 테스트에서 실패했다(03-R02 3개, 03-R03~R18 16개). 지난 생존 변이 M1·M3·M6·M7도 이제 잡힌다. 빈틈: 키 없는 같은 입력 재제출은 테스트가 없다(0929/03-03 일부, 실험 X1이 그 동작을 보였다) | +| 11 | 데이터 성숙도 | 적용 제외 | — | — | - 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent뿐이다 | +| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2 | P — KEYED 같은 입력 재제출은 같은 키, identity lease는 테스트가 생겼다(0929/03-06). 키 없는 같은 입력 재제출은 훅이 막지 않는다(0929/03-03 일부) | +| 13 | 확장성 | 다른 영역 | — | — | > 11·15 영역 | +| 14 | 성능 성숙도 | 다른 영역 | — | — | > 15 영역. 이 영역 변경은 실행 경로에 상수·작은 검사만 더했다 | +| 15 | 보안 성숙도 | 적용 | M4 / M3 | E2 | O — 쿠키 쓰기 CSRF 조립 검사(`external-contract-runtime.ts:587-599`), `redirect: "error"`·`no-referrer`·`no-store`(`http-execution-v3.ts:991-994`), 반사 correlation 문법 테스트(1101/03-06). 0929/03-02(CORS 헤더)는 19번 | +| 16 | 의존성 성숙도 | 다른 영역 | — | — | > 13 영역 | +| **17** | API / Contract | 적용 | M3 / M3 | E2 | P — §1 `meta.page`, §2 답 전부, §4 `REQUEST_TIMEOUT`을 읽는다. bulk는 미지원으로 문서화했다(1103/03-02 일부). §4 rate-limit 503 둘이 표 밖이다(03-02). 업무 code의 단계 신호는 계약에 없고 operation 선언으로 대신한다(D2 ② 백엔드 대기) | +| 18 | 배포 성숙도 | 다른 영역 | — | — | > 13 영역 | +| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 교차 origin `x-correlation-id`·`Idempotency-Key` 허용은 문서뿐이다(0929/03-02) | +| **20** | 개발자 경험 | 적용 | M3 / M2 | E2 | P — `--with-create`가 짝 백엔드 create·read-by-id와 쓰기 전 거절 선언, NEVER/KEYED 값을 만든다. 백엔드 목록 GET이 없다(1103/03-07 일부). 전체 판정은 14·16 영역 | +| **21** | Guardrail 성숙도 | 적용 | M4 / M4 | E2 | P — 조립이 쓰기 `SAFE`, 읽기 `KEYED`·`NEVER`, 목록 안의 멱등성 code, Envelope 없는 목록을 거절한다. "쓰기 뒤 가능" 플랫폼 code는 거절하지 않는다(03-01) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P — `FeatureHttpBinding`은 좁다. kind와 effect가 두 함수에서 정해진다(1101/03-04 남음) | +| 23 | 일관성 | 적용 | M2 / M2 | E1 | O — 401·403·429는 `classifyStatus`, 400·409·422는 `refusedBeforeWrite`로 operation이 "적용 안 됨"을 정할 수 있다. 지난 라운드의 불일치가 풀렸다 | +| 24 | 네이밍 / 의미 | 적용 | M1 / M1 | E1 | P — NEVER 결과 불명 화면의 출구는 "변경됨으로 확인" 하나다. 사용자가 적용 안 됨을 확인했어도 이 버튼을 눌러야 폼이 풀린다(`async-surface.tsx:126-128`의 설계 결정) | +| 25 | 조직 확장성 | 다른 영역 | — | — | > 14 영역 | +| 26 | Ownership | 적용 | M2 / M2 | E1 | P — pin이 담당(`frontend-platform`)과 대조 날짜를 적는다. 백엔드가 code를 더할 때 프론트에 알리는 길은 게이트 밖 drift 검사다 | +| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | O — 소비자 0인 `projectCertaintyToUi`가 남았다(배럴 밖, 결함 아님) | +| **28** | 회복 가능성 | 적용 | M3 / M2 | E2 | P — 선언한 업무 거절 뒤 고쳐서 저장한다. KEYED 결과 불명은 같은 키로 재전송한다. NEVER 결과 불명의 출구는 "변경됨으로 확인"이나 새로고침이다. rate-limit 503도 그 길로 간다(03-02) | + +X(미충족)는 없다. + +## 5. 미검증 + +| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| 생성 KEYED 슬라이스에 같은 변이를 넣은 결과 | 03-R02는 NEVER 슬라이스만 생성했다. KEYED 슬라이스는 `test:feature-scaffold`(FE-GATE-020 rc=0)에서 변이 없이만 돈다 | `create:feature x --with-create --keyed` 뒤 같은 G1 | +| 실험 X1~X4가 이 실험 파일 밖의 실제 화면에서도 같은가 | 실험은 jsdom에서 실제 실행기·바인딩·훅을 쓰고 fetch만 바꿨다 | 생성 기능 페이지에 폼 밖 버튼을 붙인 시나리오 | +| 짝 백엔드와의 실제 통합 | 백엔드는 읽기만 했다. 생성기 템플릿과 문서로 확인했다 | 백엔드 생성 기능을 띄워 빈 이름 create, rate-limit 저장소 장애 주입 | +| 실제 브라우저의 폼 흐름 | jsdom 테스트만 봤다 | Playwright 폼 시나리오 | +| 다운스트림이 폼 밖에서 같은 입력을 다시 `submit`하는 NEVER 쓰기를 갖고 있는가 | tech-log·memento를 읽지 않았다 | 두 제품의 `useApplicationMutation` 호출과 `retrySemantics: "NEVER"` grep | +| `src/adapters/browser-rpc`·`query-cache`·`diagnostics`·`telemetry`의 세부 동작 | `e40684b` 뒤 변경이 없다. 게이트 통과만 확인했다 | 지난 라운드 변이를 다시 돌리기 | + +## 6. 실행 기록 + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 | +|---|---|---|---|---|---|---| +| `03-mut` | `exp.sh 03-mut - 840 "bash /tmp/claude-gates/r4/mut/03-runner.sh"` | 스크립트 안의 21개 | — | **돌지 않았다.** 잠금 대기 중 19:55에 취소됐다(BRIEF-2). 로그 없음 | 취소 | — | +| `03-gen` | `exp.sh 03-gen - 600 "bash /tmp/claude-gates/r4/mut/03-gen.sh"` | 스크립트 안의 G1·M08·M09 | — | **돌지 않았다.** 같은 이유 | 취소 | — | +| 재시도 2건(19:48) | 같은 명령을 `nohup`으로 | — | 93 | `CLOSED: exp.sh no longer runs experiments` | — | — | +| 오케스트레이터 게이트(인용, 대조군) | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`(local), FE-GATE-001~012·020(CI env) | — | 0 | unit 194 files / 2,883 tests, component 40 / 270, integration 11 / 189. 대상 9파일 통과(`backend-envelope` 30, `external-contract-runtime` 42, `create-feature` 43, `backend-contract-pin` 10, `form-foundation` 31, `async-surface` 34, `application-mutation-admission` 17, `http-execution-v3-observability` 11, `http-execution-v3-envelope` 57). `verify:documentation` rc=1과 FE-GATE-013 rc=1은 이 영역 밖이다(1절) | — | 3.2~8.3 | + +배치 결과(오케스트레이터가 돌림, local env, 2026-11-05 20:02~20:03, 부하 2.2~3.3). 18건 모두 복원 깨끗(`restore=clean`). 로그는 `scratchpad/r4/results/03/03-Rnn.log`. 공통 명령: `ENV` = `node scripts/run-vitest.ts run` + `backend-envelope`·`backend-contract-pin`·`http-execution-v3-envelope`·`http-execution-v3-observability`·`form-foundation` 테스트 5파일(139 tests), `ECR` = `external-contract-runtime.test.ts`(42), `STATE` = `application-mutation-admission`·`async-surface`(51), `CF` = `create-feature.test.ts`(43). 변이 스크립트는 `node /tmp/claude-gates/r4/mut/03-files/mutate.mjs ` 하나를 부른다. 바꿀 문자열이 정확히 한 번 나와야 바꾸고, 아니면 exit 3이다. 모든 로그에 `: applied to `이 찍혔다. 대조군은 위 게이트 로그다(03-R02는 자기 안에서 돌렸다). + +| 이름 | 명령 | 변이 | rc | 결과(실패한 테스트) | +|---|---|---|---|---| +| 03-R01 | `node scripts/run-vitest.ts run tests/component/r04-03-experiments.test.tsx` | 실험 파일 추가만 | 0 (2 s) | 5/5 통과. X1 NEVER `canResend=false resendReturned=null fetchAfterResend=1 fetchAfterSameInputSubmit=2 keys=[null,null] second=true`. X1 KEYED `canResend=true ... keys=["key-1","key-1","key-2"]`. X2 `composeError=none`, 넷 모두 `NOT_APPLIED`. X3 `resendButtonDrawn=true`. X4 429 `RATE_LIMITED/NOT_APPLIED`, 503 둘 `SERVER_FAILURE/MAYBE_APPLIED` | +| 03-R02 | `bash /tmp/claude-gates/r4/mut/03-gen.sh` | 스크립트 안: G1, M08, M09 | 0 (15 s) | `create:feature memo-feature --with-create` rc=0, 생성 계약에 `refusedBeforeWrite: ["MEMO_INVALID"]`·`NEVER`·`retryBudget: 0`. BASELINE 4 files / 21 tests 통과. G1(선언 줄 삭제, 남은 줄 0) rc=1: "reads 400 MEMO_INVALID as not applied, on the name field", "shows the backend's refusal of the name on the field and saves again". M08 rc=1, M09 rc=1: 둘 다 "keeps a create whose response was lost unknown and offers no resend"만 실패 | +| 03-R03 | `ENV` | M01 선언 판정 끔 | 1 (8 s) | 7건: 단위 "reads a declared 400/409/422 ... as not applied" 3, 통합 "reads a declared 400 WORKLOG_INVALID / 409 POSTER_ALREADY_EXISTS as not applied"·"applies the list the composition installed" 3, 폼 "saves the corrected value after a declared pre-write refusal, with a new key" 1 | +| 03-R04 | `ENV` | M02 런타임 멱등성 접두사 거절 제거 | 1 (4 s) | 1건: "never lets a declaration decide an idempotency answer or a table code" | +| 03-R05 | `ECR` | M04 조립의 멱등성 code 거절 제거 | 1 (1 s) | 5건: "refuses to declare the idempotency answer" × `IDEMPOTENT_IN_FLIGHT`·`IDEMPOTENT_REQUEST_MISMATCH`·`IDEMPOTENCY_UNAVAILABLE`·`IDEMPOTENCY_COMPLETION_UNKNOWN`·`IDEMPOTENCY_KEY_INVALID` | +| 03-R06 | `ENV` | M06 실행기가 목록을 안 넘김 | 1 (8 s) | 4건: 통합 3("reads a declared ..." 2, "applies the list the composition installed"), 폼 1 | +| 03-R07 | `STATE` | M08 훅이 키를 안 봄 | 1 (2 s) | 1건: "offers no resend for an unknown request that carries no key" | +| 03-R08 | `STATE` | M09 화면이 플래그를 안 봄 | 1 (2 s) | 1건: "draws no resend for an unknown request that cannot be resent" | +| 03-R09 | `ENV` | M11 `COMPLETION_UNKNOWN` 행 삭제 | 1 (4 s) | 6건: 단위 "reads 503 IDEMPOTENCY_COMPLETION_UNKNOWN as maybe applied"·"never lets a declaration decide ...", pin "reads the backend's 503 IDEMPOTENCY_COMPLETION_UNKNOWN as its table says", 통합 "keeps the key and does not resend 503 ..."·진단 "503 IDEMPOTENCY_COMPLETION_UNKNOWN"·"keeps 400, 409, 422 outside the table ..." | +| 03-R10 | `ENV` | M13 거절 표가 status를 안 봄 | 1 (3 s) | 6건: "reads a table code under another status (...) as maybe applied" 5행, "never lets a declaration decide ..." | +| 03-R11 | `ENV` | M14 처리 중 409도 자동 재전송 | 1 (4 s) | 2건: "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own", pin "reads the backend's 409 IDEMPOTENT_IN_FLIGHT as its table says" | +| 03-R12 | `STATE` | M15 UNKNOWN 동안 identity lease 안 잡음 | 1 (2 s) | 1건: "keeps the unknown input's identity when the identity registry is full" | +| 03-R13 | `ENV` | M16 반사 correlation 문법 검사 제거 | 1 (3 s) | 2건: "drops a reflected correlation id that is an overlong value / a value with spaces and markup" | +| 03-R14 | `ECR` | M17 쓰기 `SAFE` 조립 거절 제거 | 1 (1 s) | 4건: "rejects SAFE retry semantics on a POST/PUT/PATCH/DELETE" | +| 03-R15 | `ENV` | M18 `meta.page` 버림 | 1 (4 s) | 3건: "hands the backend's meta.page to mapSuccess", "reads an unsorted page", "reads a page without sort" | +| 03-R16 | `ENV` | M19 실패 `traceId` 버림 | 1 (3 s) | 1건: "carries the failure Envelope's meta.traceId on the failure" | +| 03-R17 | `ENV` | M20 `effect_certainty` 안 실음 | 1 (4 s) | 10건: 진단 표 9행("400 IDEMPOTENCY_KEY_INVALID" … "503 REQUEST_TIMEOUT"), "projects every V3 terminal outcome through the closed diagnostics allowlist" | +| 03-R18 | `CF` | M22 생성기의 `refusedBeforeWrite` 줄 삭제 | 1 (1 s) | 1건: "matches the backend scaffold's NOT_IDEMPOTENT create with a NEVER command" | + +변이 19개(03-R02의 3개 포함) 모두 검출됐다. 각 변이는 요청서에 적은 기대 테스트에서 실패했다. 기대 밖에서 함께 실패한 것(03-R09의 "never lets a declaration decide ...", 03-R15의 page 2건, 03-R17의 observability 1건)도 같은 규칙을 보는 테스트다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 03-01 | Low·P3 | 구조적 위험 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다 | `src/contracts/external-contract-runtime.ts:608-646`, `src/adapters/http/backend-envelope.ts:317-327` | +| 03-02 | Low·P3 | 개선 제안 | 백엔드 §4의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`이 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | `config/contracts/backend-idempotency-answers.json`, `src/adapters/http/backend-envelope.ts:246-269`, `scripts/create-feature-write-slice.ts:298` | + +이월로 남은 것: 0929/03-03 일부(남은 부분 Medium·P2 제안), 1103/03-02 일부, 1103/03-07 일부, 1101/03-04 남음, 0929/03-02 남음. diff --git a/docs/reviews/2026-11-05-maturity-review/04-adapters-realtime.md b/docs/reviews/2026-11-05-maturity-review/04-adapters-realtime.md new file mode 100644 index 00000000..9fcfef57 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/04-adapters-realtime.md @@ -0,0 +1,232 @@ +# 04 realtime 어댑터 성숙도 리뷰 + +> 검토일: 2026-11-05 · 기준: `fix/maturity-review-2026-11-03` / `8a44226` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/realtime/`, `src/contracts/realtime-streams.ts`, `src/application/policies/bounded-polling.ts`. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`의 실시간 출구(읽기만) +> 깊게 본 관점: 6, 10, 17, 21, 24, 28 +> 렌즈: ① 1103/04-01 수정 뒤 poll 한 번이 실제 요청 한 번인가(지난 실험 P 재실행) ② 이 영역의 수정이 검사를 약하게 만들지 않았는가 ③ 1103/04-02 대응표가 백엔드 `45d2a478`과 맞는가 + +ID 표기: 이번 라운드 발견은 `04-01`부터 쓴다. 라운드 밖에서는 `1105/04-NN`이다. 지난 라운드(2026-11-03)는 `1103/04-NN`, 그 전은 `1101/04-NN`, `0929/04-NN`이다. + +**이 문서의 실행 증거.** 처음 건 영역 실행(`04-poll-mut`)은 lock 대기 중 19:55에 일괄 취소되어 돌지 않았다(6절). 그 뒤 실험·변이 네 건(04-R1~04-R4)을 배치로 요청했고, 오케스트레이터가 desktop에서 한 번씩 돌렸다(20:03, 부하 2.4~2.6, 매번 `8a44226`으로 되돌림 확인). 나머지 실행 증거는 오케스트레이터 게이트 로그와 snapshot이다. + +**영역 판정 (35.8)** + +| 범위 | 판정 | 이유 | +| --- | --- | --- | +| codec·stream coordinator·WebSocket 연결·live↔Poll handoff·reconnect coordinator | 지정 범위에서 사용 가능 | 지난 라운드의 남은 항목 1101/04-03(초당 event 상한 테스트)과 0929/04-04(heartbeat 주석)가 고쳐졌다. realtime 단위 테스트 14파일 267건이 게이트에서 통과했다 | +| reconnect coordinator + SSE | 조건부 사용 가능 | 서버 끊김 이름이 세 transport에서 같아졌다(1103/04-04 고쳐짐). 조합 코드가 SSE session bridge와 EOF 분류를 직접 정해야 하는 것(0929/04-02)과 `retry:` 상한 규칙(0929/04-03)은 그대로다 | +| bounded polling + V3 HTTP 실행기 | 조건부 사용 가능 | 조건이 하나로 줄었다. `execute` 안에서 coordinator에 넘긴 descriptor를 그대로 실행기에 넘겨야 한다. 그러면 실행기는 다시 보내지 않는다. 조립된 행으로 503·네트워크 실패·429 모두 poll 3회 = 요청 3회였다(04-R1 P2~P4). 다른 descriptor를 넘기면 막는 것이 없다. 그때는 poll 3회에 요청 9회다(04-R1 P5, 2절 1103/04-01 남은 틈) | +| 짝 백엔드 템플릿과 realtime push를 그대로 연결 | 해당 용도의 사용 보류 | 지금 연결되는 push 조합이 없다. 이제 설계 0.1절이 이것과 세 길을 적는다(1103/04-02 문서 고쳐짐). 길 선택은 제품 결정이다. 짝 백엔드와 bounded polling 조합은 위 행대로 쓸 수 있다 | + +## 0. 결론 + +- 지난 라운드 Medium 둘이 고쳐졌다. **1103/04-01**: poll은 이제 V3 descriptor를 받고 `frontend.retryBudget`이 0이 아니면 생성 때 거절한다(`bounded-polling.ts:115-139`). 실행기는 같은 칸에서 재시도 상한을 읽는다(`http-execution-v3.ts:557`, `:911-915`). 그래서 같은 descriptor를 실행기에 넘기면 poll 1회 = 요청 1회다. 실험 P를 조립된 행(`composeContractContributions`)으로 다시 돌렸다. 지난 라운드 9회이던 요청이 3회다(04-R1). 검사 줄을 지우는 변이(MP1)는 테스트 3건, 실행기가 `retryBudget`을 읽지 않게 하는 변이(MP2)는 1건에서 잡힌다(04-R2, 04-R3). **1103/04-02**: 설계 0.1절에 짝 백엔드 대응표가 생겼다. 표의 백엔드 사실을 `45d2a478`에서 다시 확인했고 맞다. +- 지난 라운드 Low 넷(04-03~04-06)과 이월 둘(1101/04-03, 0929/04-04)도 완료 기준까지 고쳐졌다. 남은 이월은 0929/04-02(SSE bridge·EOF)와 0929/04-03(SSE `retry:` 범위, 결정 대기) 둘이다. +- 1103/04-01에 남은 틈이 하나 있다. coordinator는 `execute`에 descriptor를 넘기지 않는다(`bounded-poll-coordinator.ts:104-113`, `:307-312`). 조합 코드가 검사받은 descriptor와 다른 descriptor로 실행기를 부르면 다시 요청이 3배가 된다(04-R1 P5: poll 3회, 요청 9회, 실행기 대기 6번). 커밋 `a65df74`가 위험으로 적었고 타입 주석이 "같은 객체"를 요구한다. 완료 기준은 충족해서 상태는 고쳐짐으로 둔다. +- 수정이 검사를 약하게 만든 곳이 하나 있다(새 04-01). `af00067`이 SSE 거절을 `PROVIDER_UNAVAILABLE`로 바꾸면서, 0929/04-01(서버만 끊기면 run이 멈춤)을 막던 테스트 두 건이 더는 transport `OFFLINE` 경로를 지나지 않는다. 그 규칙은 타입 주석과 설계 5.3에 남아 있다. 지운 두 줄을 되살리는 변이(MR1)에서 realtime 14파일 267건이 모두 통과했다. 같은 변이에서 리뷰 대조 C1·C2는 run이 멈춰 실패했다(04-R4). +- 같은 수정이 다른 결함 하나를 만들었다(새 04-02). poll `execute`가 던지면 이제 "서버에 닿지 않음"(`PROVIDER_UNAVAILABLE`)으로 보고 lease 안에서 재시도한다. V3 실행기는 네트워크 실패를 던지지 않고 결과로 돌려준다. 그래서 자연스러운 조합에서 던짐은 조합 코드 결함이고, 그 결함이 서버 장애와 예산 소진으로 보인다. +- 설계 결정 VD-28은 아직 지운 V2 poll 예산(`maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`)으로 poll 규칙을 적는다(새 04-03, 문서). +- 이번 발견 3건: **Low 3**, 모두 P3. High 이상·P1은 없다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(프론트 pin `config/contracts/backend-contract-pin.json`)은 읽기만 했다 | +| 커밋·작업 상태·확인 시점 | `8a44226`. laptop worktree(HEAD = 기준)에서 읽기만 했다. 2026-11-05 19:20~ | +| 목적과 지원 실행 구성 | 템플릿. realtime은 `RECIPE_AVAILABLE`·`AVAILABLE_NOT_COMPOSED`다. 조합 코드(bridge, 환경 신호, poll `execute`)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개 | +| 필수 요구와 규모·운영 목표 | 합의된 SLO 없음. 설계 문서의 상한표(11절)와 실패 어휘(13.1절)를 기준으로 봤다 | +| 읽은 코드·구성 범위 | `e40684b..8a44226`에서 영역을 바꾼 커밋 전부: `a65df74`(poll V3 descriptor), `af00067`(서버 끊김 kind), `a94006b`(snapshot 표 테스트), `3bc690d`(WS rate 테스트), `5d0f5ad`(heartbeat 주석), `5b2106d`(바인딩 출처 문서), `615da35`(짝 백엔드 대응표), `08ed0a0`의 `tests/unit/realtime/fixture.ts`. 전부 읽음: `bounded-polling.ts`, `bounded-poll-coordinator.ts`, 위 커밋의 diff와 테스트 변경. 필요한 부분: `http-execution-v3.ts`(재시도 상한, fetch 거절 처리), `external-contract-runtime.ts`(조립·동결·중복 검사), `reconnect-coordinator.ts`(online 대기, 재시도 분기), `fetch-sse-connection.ts`, `websocket-connection.ts`(heartbeat 훅, rate 상한), `realtime-streams.ts`(snapshot 바인딩), `sse-parser.ts`(`retry:`), `installed-feature-runtime-registries.ts`, `schema-registry.ts`, `boundary-mapper.ts` | +| 읽은 문서(주장) | 설계 `realtime-events-web-push-and-bounded-polling.md` 0.1·3·5.3·6.3·9.2·11·13.1절, `VD-28` 상태·1·poll 절, `VD-23` 상태와 8절, `optional-adapter-recipes.md` Realtime 절, 매뉴얼 03 C절, `CHANGELOG.md` 미출시 절, 지난 라운드 `2026-11-03-maturity-review/04-adapters-realtime.md`와 README 10.3·12·14절. 짝 백엔드 `src/adapter/inbound/websocket/README.md`, `src/adapter/inbound/web-advanced/README.md`, `docs/web/repository-adaptation.md`, `ForbiddenApiArchitectureTest.java`, `WebOpenApi32Generator.java` | +| 수행한 테스트·실험 | 배치 실험 04-R1(실험 P 재실행 + 대조 C), 변이 04-R2(MP1), 04-R3(MP2), 04-R4(MR1). desktop, 오케스트레이터 실행, local env(6절). 인용한 오케스트레이터 게이트 결과: `gates/summary.txt`의 check:architecture·check:types·lint·test:unit·test:component·test:integration·test:contract·test:runtime-schema·check:adapter-inventory·check:ci rc=0, `test_unit.log`의 realtime 14파일 267건 통과(194파일 2,883건 중). `merge-48/summary.txt`(CI=true env): FE-GATE-010 rc=0(realtime boundaries·fixture·optional recipes source 포함, snapshot `artifacts/quality/realtime-boundaries.json` violations 0, `optional-recipes.json` realtime 40,811 / 42,200 gzip B), FE-GATE-020 rc=0(1,156초, `artifacts/tests/realtime-runtime-removal.xml` 7 checks 0 failures) | +| 확인하지 못한 범위·이유 | 실제 브라우저·SSE/WS 서버·프록시(환경 없음). 짝 백엔드 실행(읽기만 허용). 0929/04-03은 코드가 그대로라 실험을 요청하지 않았다. 1103/04-03·04-04·1101/04-03 수정을 되돌리는 변이는 정적 근거로 충분해 요청하지 않았다(최소 요청). `verify:documentation`은 rc=1이지만 실패 원인은 짝 백엔드 경로를 적은 다른 문서다(`gates/verify_documentation.log`: 매뉴얼 01·02·04·README, `backend-api-and-server-state-contract.md`). 이 영역 문서(설계 0.1절, 레시피 Realtime 절)는 실패 목록에 없다 | +| 이전 리뷰와 비교 가능한 범위 | 지난 발견 6건, 합친 중복 2건(04-03 → 07-02, 04-05 → 14-01), 이월 남음 4건을 지금 코드로 다시 판정했다(2절). 지난 라운드의 실험·변이 결과는 증거로 쓰지 않았다. 실험 P는 같은 서버 조건(503만)에 조립된 행을 써서 다시 돌렸고(04-R1 P2), 네트워크 실패·429를 더했다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +| --- | --- | --- | --- | +| 1103/04-01 (Medium·P2) | bounded polling 계약이 지운 V2 행 어휘로 된 자기 선언이라 V3 실행기 재시도를 막지 못한다 | **고쳐짐** (남은 틈 1) | `a65df74`. `BoundedPollOperationContract`를 지우고 operation을 V3 descriptor로 받는다(`bounded-polling.ts:33-44`). 생성 검사는 operationId, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT, **`frontend.retryBudget !== 0` 거절**, `responseByteLimit` 1..8 MiB다(`:115-139`). 실행기는 `policy = operation.frontend`(`http-execution-v3.ts:557`)에서 `retryCeiling = min(policy.retryBudget, maxRetryAttempts, 2)`를 만든다(`:911-915`). 네트워크 실패 재시도(`:1060-1063`)와 status 재시도(`:1115-1124`) 모두 이 상한 아래에 있다. 그래서 같은 descriptor면 실행기 옵션과 상관없이 재시도가 0이다(정적, E1). 응답 상한은 `min(policy.maxResponseBytes, frontend.responseByteLimit)`이다(`bounded-poll-coordinator.ts:136-139`). 테스트: 거절 8가지(`bounded-polling-policy.test.ts:60-115`), 실제 V3 실행기(`maxRetryAttempts: 2`)와 503 서버로 poll 3회 = 요청 3회, 기본 GET 거절(`bounded-poll-coordinator.test.ts:1054-1163`). 게이트에서 통과(`test_unit.log`: bounded-polling-policy 11건, bounded-poll-coordinator 21건). **실험 P 재실행(04-R1, 6.1절):** 한 기여에 같은 경로 GET 둘(기본 `retryBudget: 2`, poll 전용 0)을 넣어 `composeContractContributions`로 조립했다. 조립된 기본 행은 생성 때 `TypeError`로 거절됐다(P1). poll 전용 행 + 실행기 `maxRetryAttempts: 2`에서 503·네트워크 실패·429(Retry-After 1)가 모두 poll 3회 = 요청 3회, 실행기 대기 0번이었다(P2~P4). 지난 라운드 같은 조건은 요청 9회였다. **변이 MP1(04-R2, 검사 줄 `:128` 삭제):** 3건 실패. "refuses a descriptor with one/two transport retry"(`bounded-polling-policy.test.ts:120`), "refuses the default read descriptor"(`bounded-poll-coordinator.test.ts:1134`). **변이 MP2(04-R3, 실행기 `:912` `policy.retryBudget` 삭제):** 1건 실패. "sends one request per poll attempt with a poll descriptor"가 요청 9개를 받았다(`bounded-poll-coordinator.test.ts:1161`). 변이 없는 실행은 게이트 `test_unit.log`가 통과다. V2 리터럴 필드는 src·설계 9.2에서 모두 사라졌다(`git grep` 0건, VD 문서는 새 04-03). **남은 틈:** `execute` 입력에는 descriptor가 없다(`bounded-poll-coordinator.ts:104-113`, `:307-312`). 조합 코드가 검사받은 descriptor와 다른 것(예: 같은 경로의 기본 GET, `retryBudget: 2`)을 실행기에 넘기면 막는 것이 없다. 04-R1 P5: lease는 poll 전용 행, `execute`는 기본 행 → poll 3회, 요청 9회, 실행기 대기 6번(125·250 ms × 3). 실행기를 `maxRetryAttempts: 0`으로 만들면 3회다(P6). 타입 주석(`bounded-polling.ts:33-38`, `bounded-poll-coordinator.ts:99-103`)과 설계 9.2(`:1655-1671`)가 "같은 descriptor를 넘긴다"고 적는다. 완료 기준("`retryBudget > 0` descriptor는 거절, 같은 조합에서 poll 3회 = 요청 3회")은 충족한다 | +| 1103/04-02 (Medium·P2) | 짝 백엔드 실시간 출구와 프론트 전송 규약이 맞지 않고 어디에도 적혀 있지 않다 | **고쳐짐** (문서). 전송 불일치 자체는 제품 결정으로 남음 | `615da35`. 설계 0.1절(`realtime-events-…md:81-118`)에 transport별 대응표, push가 필요할 때의 세 길, 재검토 조건이 있다. 레시피(`optional-adapter-recipes.md:225-229`)와 매뉴얼 03(`docs/manual/03-outside-feature-folder.md:110`)이 링크한다. **백엔드 `45d2a478`에서 다시 확인(정적):** STOMP-over-SockJS `/ws`·`/topic`·구독 1개·`Map` 투영(`src/adapter/inbound/websocket/README.md:7-12`, `:17-42`), simple broker는 재전송·영속 없음(`:77-81`), raw handler는 `servlet/PlatformWebSocketHandler.java`, `NO_SSE_EMITTER` 규칙(`ForbiddenApiArchitectureTest.java:516`), MVC SSE writer 없음(`docs/web/repository-adaptation.md:255-259`), `StreamMediaType.SSE`는 OpenAPI 생성기만 씀(`WebOpenApi32Generator.java:33`), 스트리밍 writer는 NDJSON·JSON text sequence(`web-advanced/README.md:28-29`), websocket main 코드에 `realtime.v1`·subprotocol 협상 코드 없음(`git grep` 0건). 커밋이 읽은 백엔드 `70fb80bf`과 `45d2a478` 사이 websocket 변경은 실패 로그(`StompHandlerFailureLog`)뿐이라 표의 결론이 같다. 정확히 하면 Spring STOMP 처리기는 STOMP subprotocol(`v1x.stomp`)을 협상한다(리뷰어 지식, 이 repo 코드로 확인하지 않음). `realtime.v1`이 없으니 결론은 같다. 완료 기준("대응표 하나로 지금 연결되는 조합과 새로 쓸 것을 안다")은 충족한다. 남은 것: 표는 백엔드 drift 검사(`check:backend-contract-drift`) 대상이 아니다. 백엔드가 바뀌면 사람이 0.1절 재검토 조건을 봐야 한다. push 경로 선택은 사용자 결정이다 | +| 1103/04-03 (Low·P3, README 10.3에서 07-02로 합침) | realtime snapshot 바인딩 검사를 막는 테스트가 없다 | **고쳐짐** | `a94006b`. `realtime-stream-registry.test.ts:219-316`이 6 method × 4 retrySemantics를 CURSOR·SNAPSHOT_ONLY 두 모드로 돈다. 행은 조립한 descriptor를 `projectApiOperationRows`로 뽑은 것이다(`:227-229`). 받는 조합은 GET×SAFE·GET×IDEMPOTENT뿐이고 나머지는 throw를 기대한다. 없는 id도 거절한다(`:311-315`). 검사 코드(`realtime-streams.ts:457-474`)에서 method 조건을 지우면 HEAD×SAFE가 받아져 표가 실패한다(정적 추론, E1). 게이트 통과 30건(`test_unit.log`). 변이 실행은 07-02 대표 영역 판정을 따른다 | +| 1103/04-04 (Low·P3) | 서버만 끊긴 실패의 이름이 transport마다 다르고 13.1 표가 맞지 않는다 | **고쳐짐** (수정이 다른 결함 둘을 만듦: 새 04-01, 04-02) | `af00067`. SSE fetch 거절(`fetch-sse-connection.ts:217-225`)·reader 거절(`:402-407`)·poll execute 거절(`bounded-poll-coordinator.ts:322-328`)이 `PROVIDER_UNAVAILABLE`(retryable)이다. WS는 원래 그렇다. src/adapters/realtime에서 transport가 `OFFLINE`을 만드는 곳은 없다. 남은 `OFFLINE`은 환경 신호(`bounded-poll-coordinator.ts:177`, `:216-219`, `:597`, `reconnect-coordinator.ts:458`, `:720`, `:758`)뿐이다. 13.1 표가 두 행을 고쳤다(`realtime-events-…md:1955`, `:1961`). 5.3도 고쳤다(`:825-829`). 테스트 기대값 3곳이 새 kind를 고정한다(`realtime-reconnect-coordinator.test.ts:2122-2137`, `:2181-2198`, `bounded-poll-coordinator.test.ts:906-948`). 그 기대값은 정확한 kind를 비교하므로 옛 kind로 되돌리면 실패한다(정적). CHANGELOG [계약] 행(`CHANGELOG.md:197`) | +| 1103/04-05 (Low·P3, README 10.3에서 14-01로 합침) | CHANGELOG에 handoff kind 변경 [계약] 행이 없고 알려진 제한이 틀렸다 | **고쳐짐** | `CHANGELOG.md:198`이 stream·handoff coordinator 둘과 `17fa8d1`을 적는다. 알려진 제한(`:256-277`)에 `IDLE_TIMEOUT` 줄이 없다(`grep IDLE_TIMEOUT CHANGELOG.md` → `:198` 하나) | +| 1103/04-06 (Low·P3) | realtime 레지스트리의 codec·mapper 바인딩을 기능이 채울 자리가 없다 | **고쳐짐** (최소 방향: 문서) | `5b2106d`. 레시피(`optional-adapter-recipes.md:230-245`)가 세 바인딩의 출처와 맞아야 하는 id를 적는다. 적힌 이름이 모두 있다: `loadInstalledFeatureRuntimeRegistries`(`installed-feature-runtime-registries.ts:30`, 반환 `apiOperations` `:67-70`), `runtimeSchemaCodecFromValidator`(`schema-registry.ts:39`), `composeRuntimeSchemaCodecs`(`:59`), `BoundaryMapper`·`composeBoundaryMapperRegistry`(`boundary-mapper.ts:44`, `:56`). 주의 한 가지: 그 함수는 설치된 모든 기능의 실행부를 적재한다. 앱 부팅은 일부러 부르지 않는다(`installed-feature-runtime-registries.ts:17-29`). realtime 조합이 런타임에 부르면 모든 기능 청크를 받는다. 레시피는 `projectApiOperationRows`도 함께 적어 한 기능 기여만 뽑는 길이 있다. 코드 칸 추가는 04-02 경로 선택 뒤로 미뤘다(커밋 본문) | +| 0929/04-02 (Medium·P2) | SSE↔reconnect 세션 bridge 부재, EOF 분류 미정 | **남음** | `readSseForReconnect`(`fetch-sse-connection.ts:498-513`)가 유일한 도구다. 테스트 안의 bridge는 EOF를 `PROTOCOL_MISMATCH`/`RECEIVE`/`retryable:false`로 끝낸다(`realtime-reconnect-coordinator.test.ts:1791-1798`). 설계 6.3 상태표는 `204`만 정하고 `200` 뒤 EOF는 정하지 않는다(`realtime-events-…md:1082-1092`). 영역 커밋 중 이것을 바꾼 것이 없다 | +| 0929/04-03 (Low·P3) | SSE `retry:` 처리 규칙이 설계 5.3·6.3과 코드에서 다르다 | **남음** (결정 대기, 1103 README 14.4) | `sse-parser.ts:330-341` 그대로다(60초 넘는 값은 버림). 5.3은 "SSE `retry`도 not-before, 상한을 넘으면 종료"(`:801-805`), 6.3은 "ceiling을 통과한 경우 다음 delay hint로만"(`:1077-1078`)이라 여전히 다른 말을 한다. `git diff e40684b..8a44226 -- src/adapters/realtime/sse/sse-parser.ts src/adapters/realtime/reconnect-coordinator.ts` 0줄 | +| 0929/04-04 (Low·P3) | hidden 탭에서 heartbeat를 멈춘 조용한 WS는 예산을 새로 받지 못한다 | **고쳐짐** | `5d0f5ad`. `heartbeatEligible` 옆 주석(`websocket-connection.ts:182-188`)과 설계 5.3(`:813-816`)이 결과와 대처(닫거나 visible 복귀 때 새 run)를 적는다. 완료 기준("주석만 보고 결과를 안다")을 충족한다. 동작은 바뀌지 않았다 | +| 1101/04-03 (Low·P3) | WS 구독별 초당 event 상한 테스트·문서 없음 | **고쳐짐** | `3bc690d`. `websocket-connection.test.ts:652-707`이 상한 2로 2개 → 1초 뒤 2개(열림) → 1개 더(닫힘, `EVENT_RATE_EXCEEDED`)를 본다. 검사(`websocket-connection.ts:995-1015`)를 끄면 `onEvent` 5회·`OPEN`이라 테스트가 실패한다(정적). 설계 11절 상한표에 행이 생겼다(`:1840`). 게이트 통과(websocket-connection 24건) | +| 0929/04-05 (Low·P3) | CHANGELOG [계약] 문장이 초기화 조건보다 넓다 | 지난 라운드에 닫음 | 1103 영역 문서 2절 "바뀜 — 닫아도 된다". 다시 보지 않았다 | + +### 2.1 수정이 검사를 약하게 만들었는가 (`git diff e40684b..8a44226`) + +| 커밋 | 테스트·검사 변경 | 판정 | +| --- | --- | --- | +| `a65df74` | 리터럴 선언 객체를 `TEST_LIST_HTTP_CONTRACT`를 펼친 descriptor로 바꿨다. 거절 사례가 2개에서 8개가 됐고 실제 V3 실행기 테스트가 생겼다 | 강해짐. 테스트 descriptor는 손으로 펼친 객체지만, 조립된 행으로도 같은 결과가 나왔다(04-R1 P1~P4). MP1·MP2 변이가 잡힌다(04-R2, 04-R3) | +| `af00067` | 기대 kind 3곳을 `OFFLINE` → `PROVIDER_UNAVAILABLE`로 바꿨다. poll "던지는 executor는 `OFFLINE`으로 끝" 테스트를 "lease 안에서 재시도"로 바꿨다 | **약해짐 1건(새 04-01).** 0929/04-01 회귀를 막던 두 테스트(`realtime-reconnect-coordinator.test.ts:2095`, `:2140`)가 이제 `PROVIDER_UNAVAILABLE` 경로만 지난다. 환경은 online이고 transport가 `OFFLINE`을 내는 테스트는 남아 있지 않다(`OFFLINE`을 만드는 곳은 `:503` 하나이고 그 테스트는 환경 offline을 함께 보낸다). 변이 MR1이 realtime 테스트 전부를 통과했다(04-R4). poll 테스트 변경은 동작 변경을 따른 것이다(새 04-02) | +| `a94006b`, `3bc690d` | 테스트만 더했다 | 강해짐 | +| `08ed0a0` | `tests/unit/realtime/fixture.ts`의 snapshot 행에 새 투영 칸 10개를 더했다 | 바뀐 검사 없음 | +| `5d0f5ad`, `5b2106d`, `615da35` | 문서·주석만 | 해당 없음 | + +시간 상한·skip·허용 목록 확대는 영역 diff에 없다. + +## 3. 이번 발견 (36.3) + +이번 발견 3건: **Low 3** · **P3 3** · 구조적 위험 2, 확인된 결함 1. + +### 04-01 서버 끊김 kind를 바꾼 뒤, 0929/04-01 회귀를 막던 테스트가 transport `OFFLINE` 경로를 지나지 않는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(수정이 만든 테스트 공백) | +| 관련 관점 | 10, 21, 6, 28 | +| 근거 | ① 규칙: 환경이 online이면 transport가 보고한 `OFFLINE`도 online 이벤트를 기다리지 않고 backoff로 재시도한다(`reconnect-coordinator.ts:111-117`, 설계 5.3 `:828-829` "조합 코드가 만든 transport가 `OFFLINE`을 보고해도"). `4d27b20`이 이 규칙을 위해 `requireOnline()` 두 줄을 지웠다. ② 그 수정을 막던 테스트는 SSE fetch·reader 거절이 `OFFLINE`이던 것을 이용했다. `af00067` 뒤 SSE는 `PROVIDER_UNAVAILABLE`을 낸다(`fetch-sse-connection.ts:221`, `:404`). 두 테스트(`realtime-reconnect-coordinator.test.ts:2095-2138`, `:2140-2198`)는 이제 `PROVIDER_UNAVAILABLE` 재시도만 본다. ③ transport가 `OFFLINE`을 내고 환경은 online인 테스트가 없다. 테스트 파일에서 `OFFLINE`을 만드는 곳은 `:503` 하나이고, 그 테스트는 환경 offline 이벤트를 같이 보낸다(`:522-526`). ④ 템플릿 transport는 이제 `OFFLINE`을 내지 않는다(13.1 `:1955`). 그래서 회귀가 생겨도 템플릿 SSE·WS 경로는 멈추지 않는다. 멈추는 것은 조합 코드가 만든 transport(예: 04-02 대응표 길 2의 STOMP transport)와 `classifyClosed`가 `OFFLINE`을 돌려주는 경우다. ⑤ **변이 MR1(04-R4, `4d27b20`이 지운 두 줄을 `reconnect-coordinator.ts:806`, `:1001` 뒤에 되살림): realtime 14파일 267건 모두 통과(생존).** 같은 실행에서 리뷰 대조 C1(attempt가 `OFFLINE`/`CONNECT`로 실패)·C2(세션이 `OFFLINE`/`RECEIVE`로 닫힘)는 실패했다. 둘 다 attempt 1회 뒤 run이 끝나지 않았다(`attempts 1`, `result null`, "expected 1 to be greater than 1"). 변이 없는 C1·C2는 attempt 3회 뒤 `OFFLINE` retryable로 끝난다(04-R1). 즉 규칙이 지금 동작에 실제로 걸려 있고, 저장소 테스트만 그것을 보지 못한다 | +| 발생 조건 | 누군가 reconnect coordinator의 재시도 분기를 고치며 transport `OFFLINE`에 online 대기를 다시 걸 때 | +| 영향 | CI가 통과한다. 그 뒤 transport가 `OFFLINE`을 내는 조합에서 서버만 끊기면 run이 재시도도 종료도 없이 멈춘다(0929/04-01과 같은 모양, 리뷰어 추론). 데이터 손상은 없다 | +| 심각도·우선순위 | Low · P3. 지금 코드는 맞다. 템플릿 transport는 영향이 없다. 회귀 탐지 공백이다 | +| 통제·증거 | 규칙 M1(주석·설계)·M2(구현) · 위반 검출 없음(MR1 생존) · E1 + E2(04-R1, 04-R4) | +| 확실성과 남은 가정 | 테스트 공백과 변이 생존을 실행으로 확인했다. 멈춤의 영향(조합 transport에서 run이 끝나지 않음)은 리뷰 대조 테스트로 확인했다. 실제 조합 transport는 repo에 없다 | +| 결정의 근거 | 적용 제외 — 기존 규칙에 테스트를 다시 붙이는 문제다 | +| 이해 비용 | 이 분기를 고치는 사람이 테스트로 규칙을 확인할 수 없다. 규칙은 주석 한 문단에만 있다 | +| 최소 개선 방향 | `realtime-reconnect-coordinator.test.ts`에 조합 transport 테스트 둘을 더한다. 환경 online, attempt가 `OFFLINE`/`CONNECT`로 실패 → 재시도 후 상한에서 끝남. 세션이 `OFFLINE`/`RECEIVE`로 닫힘 → 재시도. 리뷰 실험 파일의 C1·C2와 같다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 2건 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 변이 MR1이 realtime 테스트에서 실패한다 | +| 검증 방법 | 04-R4와 같은 패치(`scratchpad/r4/requests/04-R4-mr1.patch`의 src 부분)를 다시 넣고 realtime 테스트를 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 04-02 poll `execute`가 던지면 서버 장애로 보고 재시도해, V3 조합에서는 조합 코드 결함이 서버 장애와 예산 소진으로 보인다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(`af00067`이 만든 진단 의미 불일치) | +| 관련 관점 | 8, 24, 6, 7 | +| 근거 | ① poll은 `execute`의 reject를 `PROVIDER_UNAVAILABLE`/`POLL`/`retryable:true`로 바꾼다(`bounded-poll-coordinator.ts:322-328`). 주석은 "No server answered"라고 적는다(`:323`). 이 kind는 재시도 대상이다(`:121-125`). 설계 13.1도 "poll `execute` 거절"을 "환경은 online인데 서버·프록시에 닿지 않은 것"이라 적는다(`realtime-events-…md:1961`). ② V3 실행기는 fetch 거절을 잡아 `NETWORK_FAILURE` 결과로 돌려준다(`http-execution-v3.ts:1036-1049`, `:1077-1080`). 설계 9.2가 권하는 조합(`execute` 안에서 V3 실행기 호출, `:1655-1671`)에서 네트워크 실패는 던짐이 아니라 결과다. 그 조합에서 `execute`가 던지는 경우는 결과 매핑·디코딩 같은 조합 코드 결함이다. ③ 테스트가 지금 동작을 고정한다. `TypeError`를 던지는 execute → `maxAttempts`번 다시 불림, 관측 `ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE` × 3, 결과 `POLL_BUDGET_EXHAUSTED`(`bounded-poll-coordinator.test.ts:906-948`). ④ `execute` 타입 주석(`:104-113`)은 던졌을 때의 처리를 말하지 않는다. CHANGELOG는 "poll은 던지는 execute도 lease 안에서 다시 시도한다"고 적는다(`CHANGELOG.md:197`). 커밋 `af00067`도 "조합 코드의 버그 포함"을 위험으로 적었다 | +| 발생 조건 | 조합 코드의 `execute`가 결과를 만들다 던질 때(스키마 매핑 오류, 잘못된 필드 접근 등) | +| 영향 | 결함이 즉시 드러나지 않는다. lease가 backoff로 최대 `maxAttempts`(상한 120)번 요청하고 `POLL_BUDGET_EXHAUSTED`로 끝난다. 관측과 kind로 보는 화면은 "서비스 이용 불가"로 본다. 원인 예외는 어디에도 남지 않는다. 데이터 손상은 없다. 요청 수는 정상 poll과 같은 상한 안이다 | +| 심각도·우선순위 | Low · P3. 진단을 늦추는 문제이고 상한이 있다 | +| 통제·증거 | M1(동작은 CHANGELOG에만 있음) · E1 + E2(그 동작을 고정한 테스트가 게이트에서 통과) | +| 확실성과 남은 가정 | 코드와 테스트로 확인했다. 조합 코드가 V3 실행기 대신 `fetch`를 직접 부르면 던짐이 네트워크 실패일 수 있다. 그 조합은 설계가 권하지 않는다 | +| 결정의 근거 | 확인한 사실: 1103/04-04의 목적은 서버 끊김 이름을 transport마다 맞추는 것이었다. 기록된 의도: `af00067` 본문 "executor가 `PROVIDER_UNAVAILABLE`을 돌려준 경우와 같은 처리". 리뷰어 추론: poll의 "transport"는 `execute`이고, V3 조합에서 그 경계의 네트워크 실패는 이미 결과로 온다. 던짐까지 서버 장애로 묶을 이유가 약하다. 41절: (a) 현상 유지 (b) 던짐은 재시도하지 않고 `PROTOCOL_MISMATCH`(조합 결함)로 끝냄 (c) 동작은 두고 `execute` 주석과 13.1에 "던짐 = 조합 코드가 실패를 결과로 바꾸지 못함, 서버 장애로 재시도됨"을 적음 | +| 이해 비용 | 조합자가 poll이 끝난 이유를 보려면 coordinator 코드를 읽어야 던짐이 섞였는지 안다 | +| 최소 개선 방향 | (c) 주석 2줄 + 13.1 한 구절. 바꿀 거면 (b)이고 테스트 1건 기대값을 고친다 | +| 대안 비교 | (a)는 비용 0이고 진단이 늦다. (b)는 결함이 첫 attempt에서 드러난다. fetch를 직접 쓰는 조합에서는 네트워크 실패가 재시도 없이 끝난다. (c)는 동작이 같고 읽는 사람만 안다 | +| 단순화의 보존 조건 | lease 상한(시도·시간·바이트), abort 시 `ABORTED`, 환경 offline 시 `OFFLINE` | +| 비용·부작용 | (b)는 공개 동작 변경([계약]) | +| 재검토 조건 | 템플릿이 poll `execute` 기본 구현(V3 실행기 래퍼)을 제공하게 되면 (b)로 간다 | +| 완료 기준 | 던지는 execute의 결과를 보고 조합 결함과 서버 장애를 구분할 수 있다(동작이나 문서로) | +| 검증 방법 | (b)면 `bounded-poll-coordinator.test.ts:906-948` 기대값 변경. (c)면 문서 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 04-03 VD-28과 설계 3절이 지운 V2 poll 예산으로 poll 규칙을 적는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(문서) | +| 관련 관점 | 9, 24, 17 | +| 근거 | `VD-28-realtime-events-web-push-and-bounded-polling.md:441-444`: "operation은 registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`". `:117-118`: "VD-23의 terminal·replay-safe REST `QUERY` execution contract를 재사용". 설계 3절도 "REST `QUERY` operation"이라 적는다(`realtime-events-…md:363-370`). 이 칸들은 지운 V2 실행 예산이다. VD-23 상태 줄은 V2 실행 경로를 지웠다고 적는다(`VD-23-…md:10-13`). 지금 규칙은 descriptor `retryBudget: 0`(설계 9.2 `:1655-1671`)이고, V2 이름은 src에 없다(`git grep authRecoveryCount -- src` 0건). `a65df74`는 설계 9.2만 고쳤다(`git show --stat a65df74`) | +| 발생 조건 | 채택자가 VD-28을 보고 poll을 조립할 때 | +| 영향 | 없는 예산 칸을 찾는다. 지금 규칙(`retryBudget: 0`)은 VD-28에서 찾을 수 없다 | +| 심각도·우선순위 | Low · P3. 상세 설계 9.2는 맞다. VD-28 머리말이 상세 설계를 가리킨다 | +| 통제·증거 | M1(두 문서가 다른 말) · E1 | +| 확실성과 남은 가정 | 확인한 사실이다 | +| 결정의 근거 | 적용 제외 — 기록 누락이다. 1103 조치(14.3절)가 VD-23·VD-24의 V2 표시를 고친 것과 같은 종류다 | +| 이해 비용 | 결정 문서와 상세 설계를 대조해야 한다 | +| 최소 개선 방향 | VD-28 `:441-444`를 "poll operation은 GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor이고 `frontend.retryBudget` 0(상세 설계 9.2, 1103/04-01)"으로, `:117-118`과 설계 `:365-370`의 "REST `QUERY`"를 같은 말로 바꾼다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 4줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" -- docs/architecture/decisions/VD-28*` 0건, VD-28이 `retryBudget` 0 규칙을 적는다 | +| 검증 방법 | 문서 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역 판정을 따름 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E2 realtime 14파일 267건 통과(게이트 `test_unit.log`) | O. 바뀐 코드는 작고(poll 검사, kind 3곳) 상태 기계·terminal close는 그대로다 | +| 2 | 구조적 성숙도 | 적용 | M4 / M4 일부 | E2 `check:architecture` rc=0(게이트, 419 modules), FE-GATE-010 rc=0(snapshot `realtime-boundaries.json` violations 0) | O. `bounded-polling.ts`가 `external-contract-runtime.ts`를 type import로만 읽는다(`:1`). 제거 드릴이 통과했다(27번) | +| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | P. poll 조립이 V3 descriptor 하나로 줄었다. poll 전용 operation을 따로 등록해야 한다(조립은 같은 경로 두 GET을 막지 않는다: `external-contract-runtime.ts:1024-1036`은 operationId 중복만 본다, 04-R1 P0가 확인). SSE bridge는 여전히 직접 작성(0929/04-02) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P. V2 리터럴 9칸이 사라져 poll 읽기가 쉬워졌다. `runLoop` 크기는 그대로다. VD-28은 아직 옛 칸을 적는다(04-03) | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. poll 남은 틈(다른 descriptor로 실행)은 타입 주석과 설계 9.2에 적혀 있다. 던지는 execute 재시도는 CHANGELOG에만 있다(04-02) | +| 6 | 실패 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2(04-R1~R4) | P. poll 재시도 3배가 같은 descriptor 조건에서 막혔다(04-R1 P2~P4, MP1·MP2 검출). 서버 끊김 kind가 같아졌다. 회귀 테스트 공백(04-01), 던짐 분류(04-02), EOF 미정(0929/04-02), `retry:` 규칙(0929/04-03) | +| 7 | 운영 성숙도 | 적용 | M2 / M2 | E1 | P. 서버 끊김이 transport와 상관없이 `PROVIDER_UNAVAILABLE`이다. poll 관측에서 조합 결함이 서버 장애로 보인다(04-02) | +| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1·E2 | P. 04-02(던짐의 원인 예외가 남지 않음). 13.1 `OFFLINE` 행은 이제 실제와 맞다 | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. CHANGELOG 누락(1103/04-05)이 고쳐졌다. VD-28 옛 어휘(04-03). 설계 5.3의 줄 번호(`reconnect-coordinator.ts:556-568`)는 지금 코드(`:559-568`)와 거의 맞는다 | +| 10 | 테스트 성숙도 | 적용(깊게) | M3 / M3 일부 | E2 게이트, 변이 3건(MP1·MP2 검출, MR1 생존) | P. 지난 생존 변이 자리(S·P·R7)에 테스트가 생겼다. poll 수정은 변이 두 개로 막힌다. 수정이 만든 공백 1(04-01, MR1 생존). poll 테스트 descriptor는 손으로 펼친 객체지만 조립 경로도 같은 결과다(04-R1) | +| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1 | O. cursor는 effect 성공 뒤에만 전진한다. 이번 커밋들이 바꾸지 않았다 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. run 1개, DRAINING·generation fence 그대로. 영역 diff는 fence를 건드리지 않았다 | +| 13 | 확장성 | 적용 | M3 / M3 | E1·E2(04-R1) | P. poll 요청 수가 시도 수와 같아졌다(조건: 같은 descriptor, P2~P4). 다른 descriptor면 3배다(P5). WS 초당 상한 테스트가 생겼다 | +| 14 | 성능 성숙도 | 적용 | M2 / M2 | E2 FE-GATE-010 rc=0, snapshot `optional-recipes.json` realtime 40,811 / 42,200 gzip B(여유 1,389, 지난 라운드 40,857) | P. 레시피 번들 예산 안이다. production 번들에는 들어가지 않는다. 브라우저 실행 성능은 미측정 | +| 15 | 보안 성숙도 | 적용 | M4 / M4 | E1 | O. 고정 same-origin endpoint, URL credential 없음. 이번에 바뀐 곳 없음 | +| 16 | 의존성 성숙도 | 적용 | M3 / M3 | E1 | O. 외부 패키지 없음 | +| 17 | API / Contract 성숙도 | 적용(깊게) | M3 / M3 일부 | E1·E2 | P. poll 계약이 V3 descriptor에 묶였다. snapshot 바인딩이 표로 고정됐다. `execute`가 descriptor를 받지 않는 틈(2절). VD-28 옛 계약(04-03) | +| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P. 백엔드 배포의 SSE EOF를 재연결할지 미정(0929/04-02) | +| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | P. `MAX_RETRY_ATTEMPTS` 기본 2가 poll에 걸리지 않는다(descriptor 0이 우선, `http-execution-v3.ts:911-915`). 파서 `maxRetryMs`와 정책 `maxDelayMs`는 따로 논다(0929/04-03) | +| 20 | 개발자 경험 | 적용 | M2 / M2 | E1 | P. 짝 백엔드 대응표와 바인딩 출처가 문서 한 곳에 있다. SSE bridge 예시는 테스트 안에만 있다. 바인딩 출처 함수가 모든 기능 청크를 적재한다는 주의가 레시피에 없다(2절 1103/04-06) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 일부 | E2 check:architecture, FE-GATE-010·020, 변이 MP1·MP2 검출 | P. poll 검사는 생성 때 거절한다(M4에 가까운 경계 검사). 0929/04-01 규칙 회귀 검출 공백(04-01, MR1 생존) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | P. poll 계약과 실행기가 같은 descriptor 칸으로 이어졌다. `execute`는 그 descriptor를 받지 않는다 | +| 23 | 일관성 | 적용 | M2 / M2 | E1 | P. 서버 끊김이 세 transport에서 같은 kind다. `APPLY_FAILED`의 `retryable`이 handoff는 true, stream은 false인 것(1103 4절 23번)은 그대로다 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P. `OFFLINE`이 환경 신호 하나의 뜻이 됐다. poll의 `PROVIDER_UNAVAILABLE`에 조합 결함이 섞인다(04-02). VD-28 V2 이름(04-03) | +| 25 | 조직 확장성 | 적용 제외 — 작성자 1인 | - | - | - | +| 26 | Ownership 성숙도 | 적용 제외 — 제품 조합 없음 | - | - | -. 짝 백엔드 push 경로 선택의 결정자는 사용자다(1103/04-02) | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2 FE-GATE-020 rc=0(CI=true, `realtime-runtime-removal.xml` 7 checks 0 failures: typecheck·lint·architecture·test·build·optional-catalog·ci-contract) | O. 세 라운드 만에 처음으로 실행 증거가 생겼다(오케스트레이터 실행) | +| 28 | 회복 가능성 | 적용 | M3 / M3 일부 | E1·E2 | P. 서버 끊김 뒤 재연결로 회복한다. 그 규칙의 회귀 테스트가 템플릿 transport 경로만 본다(04-01). EOF 뒤 회복은 조합 코드 몫(0929/04-02) | + +## 5. 미검증 + +| 항목 | 왜 확인하지 못했나 | 확인하려면 | +| --- | --- | --- | +| 1103/04-03·04-04·1101/04-03 수정을 되돌리는 변이 | 기대값이 정확한 비교임을 정적으로 확인해 요청하지 않았다(최소 요청). 1103/04-03은 07-02 대표 영역의 판정을 따른다 | 필요하면 다음 라운드에서 한 번씩 | +| 실제 브라우저·SSE/WS 서버·프록시, 짝 백엔드 실행 | 환경 없음, 백엔드는 읽기만 | 설계 15.3의 로컬 서버 + 브라우저 실행 | +| 0929/04-03의 현재 동작 | 코드가 그대로라 실험을 요청하지 않았다 | 0929 실험 E9를 다시 돌림 | +| 브라우저에서의 realtime 실행 성능 | 측정 환경 없음. 번들 크기만 게이트에서 봤다 | lab 측정 | + +## 6. 실행 기록 + +모든 배치 항목: desktop `/home/donghyeon/workspace/clean-architecture-frontend-template`, 오케스트레이터 실행, env local, 각 항목 전후로 `8a44226`으로 되돌림(restore clean). 로그: `scratchpad/r4/results/04/04-R1.log`~`04-R4.log`. 변이 없는 대조: realtime 14파일 267건은 게이트 `gates/test_unit.log`가 통과다. 04-R1은 실험 파일 자체라 04-R4의 대조다. + +| 이름 | 명령 | 변이 | rc | 결과 | lock 대기 | 부하 | +| --- | --- | --- | --- | --- | --- | --- | +| `04-poll-mut` | `bash /tmp/claude-gates/r4/mut/04-driver.sh` | 실험 파일 + 변이 스크립트 | 없음 | **돌지 않았다.** 처음 건 ssh가 끊긴 뒤 원격 대기가 남아 lock 획득 전에 직접 끊었다. 다시 건 실행은 19:55 일괄 취소로 끝났다(`exp/04-poll-mut.stdout` 빈 파일, log 없음). checkout에 손대지 않았다 | 취소 | - | +| 04-R1 | `node scripts/run-vitest.ts run tests/unit/zz-review04/ --reporter=default` | 실험 파일 `tests/unit/zz-review04/zz-review04-1105.test.ts`만 추가(src 변경 없음) | 0 | 9건 통과. 6.1절 표 | 배치 | 2.59 | +| 04-R2 (MP1) | `node scripts/run-vitest.ts run tests/unit/realtime/ --reporter=default` | `bounded-polling.ts:128` `frontend.retryBudget !== 0 \|\|` 삭제 | 1 | **검출.** 3건 실패 / 267: `bounded-polling-policy.test.ts` "refuses a descriptor with one transport retry"·"two transport retries"(`:120`, expected function to throw), `bounded-poll-coordinator.test.ts` "refuses the default read descriptor, whose executor retries"(`:1134`) | 배치 | 2.59 | +| 04-R3 (MP2) | 같음 | `http-execution-v3.ts:912` `policy.retryBudget,` 삭제 | 1 | **검출.** 1건 실패 / 267: "sends one request per poll attempt with a poll descriptor"(`bounded-poll-coordinator.test.ts:1161`, expected length 3, got 9) | 배치 | 2.59 | +| 04-R4 (MR1) | `node scripts/run-vitest.ts run tests/unit/realtime/ tests/unit/zz-review04/ --reporter=default` | `reconnect-coordinator.ts:806`, `:1001` 뒤에 `if (… .kind === "OFFLINE") requireOnline();` 두 줄 + 04-R1 실험 파일 | 1 | **realtime 14파일 267건 모두 통과(생존).** 실패는 리뷰 대조 C1·C2 둘뿐(15파일 중 1, 276건 중 2, "expected 1 to be greater than 1", `attempts 1`, `result null`). P0~P6은 04-R1과 같은 값 | 배치 | 2.38 | + +### 6.1 실험 P와 대조 C (04-R1) + +한 기여(`TEST_CONTRACT_CONTRIBUTION`을 펼친 것)에 같은 경로 GET 둘을 넣어 `composeContractContributions`로 조립했다. 기본 행 `TEST_LIST_ENTITIES`(`retryBudget: 2`)와 poll 전용 행 `TEST_POLL_ENTITIES`(`retryBudget: 0`)다. 둘 다 조립됐고 동결돼 있다(P0). poll `maxAttempts: 3`. `execute`는 `createContractHttpExecutor`(`maxRetryAttempts: 2`, 앱 기본값)를 부른다. 가짜 clock, 실행기 `sleep`은 즉시 끝나는 함수로 주입했다. + +| 실험 | lease에 묶은 행 | 실행기에 넘긴 행 | 실행기 `maxRetryAttempts` | 서버 | poll 시도 | 실제 요청 | 실행기 대기 | 결과 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| P1 | 기본(2) | — | 2 | — | — | — | — | 생성 때 `TypeError` | +| P2 | poll(0) | poll(0) | 2 | 503 | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` | +| P3 | poll(0) | poll(0) | 2 | fetch 거절 | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` | +| P4 | poll(0) | poll(0) | 2 | 429 + `Retry-After: 1` | 3 | **3** | 0 | `POLL_BUDGET_EXHAUSTED` | +| P5 | poll(0) | **기본(2)** | 2 | 503 | 3 | **9** | 6번(125·250 ms × 3) | `POLL_BUDGET_EXHAUSTED` | +| P6 | poll(0) | 기본(2) | 0 | 503 | 3 | 3 | 0 | `POLL_BUDGET_EXHAUSTED` | + +지난 라운드 실험 P(같은 503, 실행기 기본값)는 요청 9회였다. 같은 descriptor를 쓰면 지금은 3회다(P2). P5는 남은 틈이다(2절). + +대조 C는 reconnect coordinator(`maxAttempts: 2`)에 조합 transport를 붙였다. 환경은 계속 online이다. + +| 실험 | transport 동작 | 변이 없음(04-R1) | 변이 MR1(04-R4) | +| --- | --- | --- | --- | +| C1 | attempt가 `OFFLINE`/`CONNECT`/retryable로 실패 | attempt 3회, `OFFLINE` retryable로 끝남 | attempt 1회, run이 끝나지 않음(실패) | +| C2 | 세션이 열린 뒤 `OFFLINE`/`RECEIVE`/retryable로 닫힘 | attempt 3회, `OFFLINE` retryable로 끝남 | attempt 1회, run이 끝나지 않음(실패) | + +인용한 오케스트레이터 결과(직접 실행 아님): `gates/summary.txt` check:architecture rc=0(3초), check:types rc=0, lint rc=0, test:unit rc=0(25초, 194파일 2,883건), test:component·test:integration·test:contract·test:runtime-schema·check:adapter-inventory·check:ci rc=0, verify:documentation rc=1(이 영역 밖 문서의 짝 백엔드 경로). `merge-48/summary.txt`(CI=true env) FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(이 영역 밖). snapshot `artifacts/quality/realtime-boundaries.json` violations 0, `artifacts/quality/optional-recipes.json` realtime 40,811 / 42,200 gzip B(여유 1,389), `artifacts/tests/realtime-runtime-removal.xml` 7 checks 0 failures. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 04-01 | Low·P3 | 구조적 위험 | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다. 지운 두 줄을 되살려도 realtime 테스트가 모두 통과한다(04-R4) | `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:2095-2198`, `src/adapters/realtime/reconnect-coordinator.ts:111-117` | +| 04-02 | Low·P3 | 구조적 위험 | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts:322-328`, `tests/unit/realtime/bounded-poll-coordinator.test.ts:906-948` | +| 04-03 | Low·P3 | 확인된 결함 | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | `docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md:117-118`, `:441-444` | diff --git a/docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md b/docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md new file mode 100644 index 00000000..be4836a3 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/05-adapters-storage-kernel.md @@ -0,0 +1,242 @@ +# 영역 05 — 저장소·adapter kernel + +> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`. 노트북 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/application/ports/browser-file-storage/opfs-ports.ts`, `src/contracts/storage-keys.ts`, `src/bootstrap/runtime-adapters.ts`·`boot-release-recovery.ts`·`optional-runtime-host.ts`·`product-composition-contract.ts`, `recipes/frontend-capabilities/browser-file-storage-fakes.ts`(OPFS fake), `recipes/session-owners/oidc-pkce-session-owner.ts`(Web Storage 키 부분), `tests/unit/opfs-worker-runtime.test.ts`·`indexeddb-opfs-journal.test.ts`·`storage-registry.test.ts`, `tests/recipes/browser-file-storage-contracts.test.ts`, `tests/browser-capabilities/opfs-runtime.spec.ts`, `docs/operations/browser-file-storage-recovery.md` §0·§7, `docs/architecture/layers.md` kernel 절, `.dependency-cruiser.json` kernel 규칙 +> 깊게 본 관점: 1, 11, 12, 17, 22, 28 +> 이번 렌즈: 1103/05-01~05-04 수정이 주장한 범위를 지키는가, 수정이 검사를 약하게 만들었는가, kernel 경계에 새 예외가 생겼는가 +> 영역 판정(35.8): **조건부 사용 가능.** kernel과 Web Storage 어댑터는 기본 구성에서 쓸 수 있다. 기본 구성은 Web Storage에 개인 데이터를 두지 않는다. OPFS 런타임은 crash가 남긴 put(1103 X2·X2b·X3)을 이제 계정 삭제가 지운다. **그러나 다른 탭이 새 파일을 쓰는 중에 계정을 삭제하면, partition에 객체가 3개 이상일 때 매번 `COMPLETED`를 보고하고 그 파일이 남는다**(1103/05-01 잔여 ①. 메모리 런타임 20/20, 실제 Chromium 6/6. 객체 0~1개일 때만 지운다). **OPFS에 개인 파일을 두는 제품은 이 잔여를 고친 뒤 조합한다.** 그 전에는 계정 삭제 전에 모든 탭의 그 partition 쓰기를 멈추는 장치를 composition이 직접 만들어야 한다. + +ID 표기: 이번 라운드 새 발견은 `05-NN`. 지난 라운드(2026-11-03)는 `1103/05-NN`, 그 전은 `1101/05-NN`, `0929/05-NN`이다. 배치 요청은 `05-R1`(변이 15개 + 실험 Y1a·Y1b·Y2, vitest), `05-R2`(Y1 브라우저판, Chromium)다(6.3절). + +## 0. 결론 + +- **이 영역은 `e40684b..8a44226` 사이 커밋 8개로 바뀌었다.** 수정 7개(`d13a393` 1103/05-01, `7b55f0f` 05-02, `fd6b631` 05-03, `8da33a5`·`36ff633` 05-04, `f6b74ed` 0929/05-09, `3f72ae7` 0929/05-08)와 테스트 1개(`b5c7128` 1101/05-06)다. OPFS 런타임·port·fake는 5파일 +215/−31줄이다. kernel(`src/adapters/platform/`), `browser-file-storage/`, Web Storage 어댑터, IndexedDB 런타임, `storage-keys.ts`는 한 줄도 바뀌지 않았다(`git diff --shortstat` 출력 없음). +- **지난 라운드 발견 13건 재판정: 고쳐짐 6, 일부 3, 남음 4.** 1103 4건 중 05-02·05-03·05-04는 고쳐졌다. **05-01은 일부다. README §14.4는 이 항목을 "고침"(그 밖의 81건)으로 적었다. 그 판정은 틀렸다.** 이월 9건 중 1101/05-04·0929/05-08·0929/05-09는 고쳐졌고, 0929/05-01(③ 손상 chunk reference 행)과 1101/05-06(W2·W5·W6)은 일부, 0929/05-05·05-06·05-07·05-10은 남았다. +- **수정이 더한 테스트는 규칙을 잡는다.** 변이 15개 중 12개가 죽었다(05-R1). 1103 수정 쪽 10개(M1~M9, M8b)는 모두 죽었다. Web Storage 5개 중 W4·W8은 죽고 W2·W5·W6은 살아남았다(1101/05-06의 남은 공백 그대로). +- **1103/05-01 수정은 journal을 세는 그 순간에 살아 있는 put만 잡는다(잔여 ①, Medium·P2 유지, OPFS 개인 파일 제품은 P1).** purge는 객체 목록을 읽고, 하나씩 지우고, 마지막에 journal 행을 센다(`opfs-byte-store-adapter.ts:821`, `:848`, `:899`). 다른 탭의 새 객체 put은 purge의 첫 remove가 origin lease를 기다리는 동안 앞서 끝나고, 지울 객체가 여럿이면 세기 전에 `complete`까지 마친다. 그러면 목록에도 행 수에도 없다. sweep은 그 객체의 chunk를 건너뛰고 `COMPLETED`를 돌려준다. 실험(손대지 않은 코드): + - Y1b(메모리 런타임, hook 없음): 객체 1개 10/10 `partitionDeleted`. 객체 3개·8개 **20/20 `COMPLETED` + 그 파일이 `[5]`로 읽힘**, partition 아래 파일 2개. + - 05-R2(실제 Chromium, OPFS·Web Locks·DedicatedWorker): 객체 0·1개 6/6 `partitionDeleted` + `NOT_FOUND`. 객체 3·8개 **6/6 `COMPLETED` + `OPENED`**. + - 저장소의 X1 테스트는 객체 1개(`opfs-worker-runtime.test.ts:2313`), 브라우저 X1은 0개(`opfs-runtime.spec.ts:332`)로만 돈다. 그래서 수정이 통과했다. +- **잔여 ②(드문 손상)도 재현됐다(05-R1 Y2).** FILES_READY에서 멈춘 put의 journal 행이 `logicalKey`를 잃으면 purge가 두 번 모두 `COMPLETED`다. staging receipt·chunk·manifest가 남는다. reconcile은 `corruptTransactions: 1, unattributedCorruptTransactions: 1`, 관측은 `SUCCEEDED`다. 05-03 수정 뒤 이 경우의 신호는 count 하나뿐이다. +- **새 발견은 1건이다. Low 1. High 이상과 P1은 없다.** 05-01: OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만든다(`oidc-pkce-session-owner.ts:44`). 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 `ca-frontend:`로 남는다. +- **kernel 경계는 그대로다.** kernel 예외 밖 adapter 간 import는 0건이다(6.1절 정적 스크립트, kernel 소비 79곳 외 위반 0). kernel 파일은 `contracts`·`application/ports` 타입과 kernel 안 파일만 import한다. 이번에 새로 생긴 kernel 소비는 `opfs-byte-store-adapter.ts:26` → `platform/abortable-operation.ts` 하나이고 허용된 것이다. `.dependency-cruiser.json`의 kernel 규칙은 주석만 바뀌었다(`:254`, `pathNot`은 같다). `check:architecture`·`check:adapter-inventory` rc=0, FE-GATE-010(boundaries 34건 거절 PASS) rc=0(오케스트레이터). +- **수정이 검사를 약하게 만든 곳은 없다.** 1103 X1 동작을 기대값으로 고정하던 테스트는 반대 기대값으로 바뀌었다(`opfs-worker-runtime.test.ts:2313-2343`). 0929/05-02 테스트는 타이밍만 바꾸고 `CONFLICT` 단언을 지켰다(`:2428-2479`). recipe의 FILES_READY rollback 테스트는 PREPARING으로 바꾸고, FILES_READY는 runtime과 fake를 함께 돌리는 parity 테스트로 옮겼다(`tests/recipes/browser-file-storage-contracts.test.ts:601`, `:765-960`). 05-03 수정은 소속 없는 손상 행의 `DEGRADED`를 껐다. 이것은 지난 리뷰가 권한 의도된 변경이다. 다만 그 권고의 전제("이런 행은 bytes를 남기지 않는다")가 잔여 ②에서 깨진다. 그래서 따로 세지 않고 1103/05-01 잔여 ②로 센다. 테스트 폭의 문제(X1을 객체 0~1개로만 본다)는 잔여 ①의 한 부분으로 적는다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 05 | +| 커밋·작업 상태·확인 시점 | `8a44226`, 2026-11-05 19:20~20:40. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop(같은 커밋, 깨끗한 checkout)에서 오케스트레이터 배치로만 했다 | +| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + Service Worker. 여러 탭 동시 실행. SSR 없음 | +| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터 두 벌(`runtime-adapters.ts:427`, `boot-release-recovery.ts:57`)과 kernel의 `createBrowserMutationIntentFactory`(`runtime-adapters.ts:31`), lifecycle runtime(`optional-runtime-host.ts:4`)이다. IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED` 레시피다(`config/recipes/frontend-capability-recipes.json:76-112`, 스냅샷 `artifacts/quality/optional-recipes.json`). 다운스트림이 켜는 확장 지점이다 | +| 필수 요구와 규모·운영 목표 | 규모·운영 목표는 없다(13·14번 미검증). 데이터 요구: OPFS 정책 예시가 `classification: "PERSONAL"`, `accountDeletionAction: "PURGE_PARTITION"`이다. 그래서 port 주석(`opfs-ports.ts:154-160`)과 runbook(`browser-file-storage-recovery.md:460-462`)이 적은 "LOGOUT·ACCOUNT_DELETION이 `COMPLETED`나 `partitionDeleted`를 보고하면 그 partition의 bytes가 없다(purge가 journal을 센 뒤 시작한 put은 예외)"를 이 영역의 필수 계약으로 본다 | +| 읽은 코드·구성 범위 | `e40684b..8a44226`의 영역 diff 전부(커밋 8개). `enforcePolicies` 전체(`opfs-byte-store-adapter.ts:730-987`), `withTransactionLock`·`withPartitionLock`(`:1130-1205`), put 흐름(`:177-360`), reconcile(`:564-728`), orphan sweep(`:1365-1440`). journal의 `listIncomplete`·`countPartitionTransactions`·`removePartition`·`hasPartitionKey`(`indexeddb-opfs-journal.ts:685-1000`). worker의 staging 보호(`opfs-worker-runtime.ts:999-1180`). fake의 put·reconcile·purge(`browser-file-storage-fakes.ts:1649-1945`). kernel 10개 파일의 import. 지난 발견이 가리킨 위치 전부 | +| 주장으로만 읽은 것 | 커밋 본문 8개, runbook §0·§7, `docs/architecture/layers.md` kernel 절, `docs/contracts/compatibility.md:31`, `docs/manual/04-paired-backend-session.md:40-50`, 지난 리뷰 문서·README §14.4 | +| 수행한 테스트·실험 | 노트북: 정적 읽기와 cross-adapter import 스크립트(6.1절, `grep`·`realpath`만 씀). desktop(오케스트레이터 배치, 둘 다 복원 clean): 05-R1 변이 15개(12 검출, 3 생존) + 실험 Y1a·Y1b(30회)·Y2, 05-R2 Chromium Y1(12회). 게이트 결과는 오케스트레이터 로그와 스냅샷을 인용한다(6.2절) | +| 확인하지 못한 범위·이유 | reconcile과 partition 삭제의 겹침, N-1 탭과의 공존, WebKit·Firefox의 Y1, WebKit의 OPFS 런타임 동작은 실행하지 않았다(5절) | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 발견 13건(1103 4건 + 이월 9건)을 이 커밋의 코드와 이번 실행으로 다시 판정했다(2절). 지난 라운드의 실행 결과(314/314, 변이, X1~X5)는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +상태: **고쳐짐**(완료 기준을 코드와 실행으로 확인) / **일부**(남은 것을 적음) / **남음** / **재발** / **틀린 발견**. 심각도는 지난 판정이다. 변이 ID는 6.3절 표다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/05-01 | 손상 없는 LOGOUT·ACCOUNT_DELETION purge가 같은 partition의 끝나지 않은 put을 보지 않고 "다 지웠다"고 보고한다 (Medium·P2, OPFS 개인 파일 제품 P1) | **일부** · Medium·P2 유지(OPFS 개인 파일 제품 P1). **README §14.4의 "고침"은 틀렸다** | **고쳐진 것**: 객체를 다 돈 뒤 `countPartitionTransactions`로 그 partition 키의 journal 행을 센다(`opfs-byte-store-adapter.ts:897-906`). 하나라도 있으면 sweep을 하지 않고(`:915`) exclusive partition lock 아래 partition을 지운다(`:950-975`). 세는 범위는 `LOGICAL_KEY_INDEX`의 `${scopeKey}\|` 범위로, `removePartition`이 지우는 범위와 같다(`indexeddb-opfs-journal.ts:891-899`, `:934-938`). 읽을 수 없는 행도 센다(`:902-905`, 값을 보지 않음). crash가 남긴 행(X2·X2b·X3, `opfs-worker-runtime.test.ts:2349-2421`)과 세는 순간 살아 있는 put(X1, `:2313`)을 테스트가 고정한다. 변이 M1(6건 실패), M2(2건), M3(1건)이 모두 죽었다. 브라우저 X1(`opfs-runtime.spec.ts:332`)은 FE-GATE-008에서 Chromium·Firefox 통과. **남은 것**: ① 세기 전에 끝난 새 객체 put. 객체 3개 이상이면 늘 일어난다(메모리 20/20, Chromium 6/6, 2.1절). ② `logicalKey`를 잃은 멈춘 put 행(Y2, 2.1절) | +| 1103/05-02 | partition lock을 기다리는 put·delete가 자기 abort signal을 무시하고 기다림에 상한이 없다 (Low·P3) | 고쳐짐 | put·remove가 `request.signal`을 `withTransactionLock`에 넘긴다(`opfs-byte-store-adapter.ts:222-226`, `:497-501`). `withPartitionLock`은 kernel `createAbortableOperation`으로 caller signal과 `mutationLockWaitTimeoutMs`를 묶어 lock을 요청한다(`:1175-1186`). caller abort는 `ABORTED`, 시간 초과는 retryable `BLOCKED`다(`:1191-1200`). lock을 얻으면 타이머를 지운다(`:1184-1187`). 테스트 "ends a queued put and a queued delete as soon as their caller aborts"(`opfs-worker-runtime.test.ts:2894`), "ends a partition lock wait at the policy bound as a retryable BLOCKED"(`:2942`). 변이 M4(signal 빼기)·M5(상한 ×1000)가 각각 그 테스트를 실패시켰다. 덧붙임: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다. 10분 넘는 다른 탭 put이 있으면 purge가 `BLOCKED`로 끝나고 호출자가 다시 부른다(커밋 본문, runbook `:504-507`). 전에는 끝없이 기다렸다 | +| 1103/05-03 | partition 삭제가 `logicalKey`를 읽을 수 없는 손상 journal 행을 지우지 못해 `DEGRADED`가 영원히 남는다 (Low·P3) | 고쳐짐 (완료 기준 두 개 충족) | ① runbook 문장이 코드와 맞는다: "키(`logicalKey`)를 읽을 수 있는 row뿐"(`browser-file-storage-recovery.md:42-44`), "그 값까지 깨진 row는 남는다"(`:480-481`). ② 운영 출구: journal이 소속 없는 손상 행을 `unattributedRows`로 따로 센다(`indexeddb-opfs-journal.ts:717-726`, `hasPartitionKey` `:980-995`). reconcile report에 `unattributedCorruptTransactions`가 실리고(`opfs-byte-store-adapter.ts:720-726`), `DEGRADED`는 지울 수 있는 손상 행이 있을 때만 낸다(`:716`). runbook에 할 일이 적혔다(`:45-52`). 테스트 `opfs-worker-runtime.test.ts:2616`, `indexeddb-opfs-journal.test.ts:877`. 변이 M6(1건)·M7(3건)이 죽었다. **전제 하나가 틀렸다**: 지난 리뷰는 "파일 bytes는 남지 않는다"(X4)를 전제로 이 행을 경보에서 빼라고 권했다. 그 행이 멈춘 put이고 다른 손상이 없으면 bytes가 남는다(Y2). 이것은 1103/05-01 잔여 ②로 센다 | +| 1103/05-04 | recipe fake의 reconcile이 FILES_READY에서 멈춘 put을 되돌리지만 런타임은 commit한다 (Low·P2) | 고쳐짐 | fake가 멈춘 단계를 기억한다. FILES_READY 행은 commit될 객체를 함께 둔다(`browser-file-storage-fakes.ts:1797-1808`). reconcile은 같은 generation 검사로 commit한다(`:1872-1886`). LOGOUT·ACCOUNT_DELETION은 멈춘 행을 지우고 `partitionDeleted`를 보고한다(`:1928-1941`). 완료 기준("같은 시나리오를 fake와 런타임에 돌린 결과가 같다"): parity 테스트가 두 단계 × 계정 삭제 여부 4경우를 메모리 OPFS·IndexedDB 위의 실제 런타임과 fake에 돌려 `toEqual`로 비교한다(`tests/recipes/browser-file-storage-contracts.test.ts:765-960`). FE-GATE-007 PASS. 변이 M8(fake가 FILES_READY를 다시 rollback)·M8b(fake purge가 멈춘 행 무시)가 parity 테스트를 실패시켰다. M1(런타임 쪽 되돌림)에도 parity 2건이 실패했다. 비교하지 않는 칸: `cleanedTransactions`, `removedObjects`. fake는 재검증 실패(digest 불일치)를 흉내 내지 않는다(커밋 본문). 결함으로 세지 않는다. 덧붙임: parity 테스트도 객체 0개 partition만 쓰므로 잔여 ①을 보지 않는다. fake에는 다른 탭이 없어 ①을 흉내 낼 수 없다 | +| 1101/05-04 | kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 예외를 받는다 (Low·P3) | 고쳐짐 (완료 기준의 두 번째 조건) | 1101 완료 기준은 "각 파일이 기준을 만족한다. 또는 기준 밖 파일이 문서에 따로 적혀 있다"다. `layers.md:83-90`이 두 파일을 "Two bootstrap-only platform services … (no adapter imports them)"로 따로 적는다. `.dependency-cruiser.json:254` 주석도 같다. 쓰는 곳은 여전히 bootstrap 둘뿐이다(`runtime-adapters.ts:31`, `optional-runtime-host.ts:4`, `grep`). 남는 위험: 규칙은 adapter가 두 파일을 import하는 것을 막지 않는다(폴더 예외). 커밋 `3f72ae7` 본문은 이 항목을 "남음"이라 적었지만, 그것은 파일을 옮기지 않았다는 뜻이다. 4절 22번에 잔여 위험으로 남긴다 | +| 1101/05-06 | Web Storage 어댑터·codec 분기 5개(W2·W4·W5·W6·W8)를 테스트가 잡지 못한다 (Low·P3) | **일부** | W4·W8에 테스트가 생겼고(`b5c7128`) 변이가 죽었다: W4 → "falls back to memory on Firefox's quota error name too"(`storage-registry.test.ts:287`) 실패, W8 → "reads a record expiring at 100 at time 100 as undefined"(`:420-450`) 실패. **W2(TTL 모양 검사, `browser-storage-adapter.ts:123`), W5(`__proto__` 등 키 거절, `browser-storage-codec.ts:204`), W6(accessor 거절, `:206`)는 살아남았다**(3파일 52건 통과). codec을 직접 부르는 테스트가 0개다(`grep browser-storage-codec tests`). 커밋 본문도 "codec을 직접 부르는 테스트는 여전히 없다"고 적는다 | +| 0929/05-01 | journal·staging 손상 한 건이 계정 삭제 purge와 reconcile·GC를 멈춘다 (Medium·P2) | **일부** | 1103에서 남은 셋 중 ①(손상 journal 행이 partition 삭제 조건에 없음)은 1103/05-01 수정으로 키가 읽히는 행에 한해 고쳐졌다(M2 검출). ②(키 없는 행)는 지우지 않기로 정하고 따로 센다(1103/05-03). **③은 그대로다**: 손상 chunk reference 행은 `isChunkReferenced`가 `CORRUPT_DATA`로 실패하고(`indexeddb-opfs-journal.ts:855-862`), GC가 그 실패를 그대로 돌려준다(`opfs-byte-store-adapter.ts:1417-1423`). reconcile은 앞에서 처리한 결과를 버리고 실패한다(`:702`). purge 쪽만 partition 삭제로 빠져나간다 | +| 0929/05-05 | IndexedDB 전체 삭제 경로가 롤백 중 계정 삭제에 쓰이지 않는다 (Low·P3) | 남음 | 전체 삭제 조건은 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2586`). N-1 탭은 `VersionError`를 `INCOMPATIBLE`로 바꾼다(`:663-672`). 파일은 `e40684b` 뒤 바뀌지 않았다 | +| 0929/05-06 | 두 런타임이 삭제 승인 계약을 다르게 요구 (Low·P3) | 남음 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`) 대 `{16,512}`(`opfs-byte-store-adapter.ts:1951`) | +| 0929/05-07 | canonical JSON 3벌, `sameScope` 2벌 (Low·P3) | 남음 | `opfs-prepared-object.ts:138`, `cache-storage/public-cache-codec.ts:637`, `realtime/event-codec.ts:414`. `sameScope`는 `indexeddb-opfs-journal.ts:1428`, `opfs-worker-runtime.ts:1690`. 덧붙임: 05-03 수정의 `hasPartitionKey`(`indexeddb-opfs-journal.ts:980-995`)가 partition 키 문법(`\|`로 나눈 세 토큰 + 토큰 정규식)을 한 번 더 적는다. 정규식은 `opfs-policy.ts:58`과 같다 | +| 0929/05-08 | kernel 범위 설명이 실제보다 좁다 (Low·P3) | 고쳐짐 | `layers.md:83-90`과 `.dependency-cruiser.json:254`가 실제 10개 파일(공유 메커니즘 7종 + bootstrap 전용 2종 + 배럴)을 적고, 편입 기준 위치(`indexeddb-connection.ts:21-26`)를 가리킨다. `ls src/adapters/platform`과 맞다 | +| 0929/05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 (Low·P3) | 고쳐짐 | `assertOpfsRuntimePolicy`가 `putIdleTimeoutMs >= mutationLockWaitTimeoutMs`를 거절한다(`opfs-policy.ts:111-112`). 테스트 "rejects an idle bound equal to / longer than the lock wait"(`opfs-worker-runtime.test.ts:3041-3059`). 변이 M9(`>=` → `>`)에 "equal to"가 실패했다 | +| 0929/05-10 | OPFS journal DB 접두사를 바꿀 수 없다 (Low·P3) | 남음 | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` 고정 | + +지난 라운드 앞에 이미 고쳐진 8건(1101/05-01·05-02·05-03·05-05·13.6, 0929/05-02·05-03·05-04)은 재발이 없는지만 봤다. pulse 행 `backend: "external"`(`storage-keys.ts:116`), 진단 `reason: cause`(`browser-storage-adapter.ts:382`), lifecycle 테스트 5건(test:unit ✓), 영역 코드의 `파일:줄` 참조 0건(`grep -oE '\.(ts|json|md):[0-9]+'`), 여러 페이지 purge 테스트(`opfs-worker-runtime.test.ts:2277`), recipe contracts의 src port import(`browser-file-storage-contracts.ts:1-14`)가 그대로다. offline-indexeddb 레시피는 이번 측정 **37,714 / 38,500 gzip B**(여유 786 B, FE-GATE-012 `check:optional-recipes`)다. 측정표(`optional-adapter-recipes.md:83`)의 37,327 B보다 +387 B로, 표의 3% 규칙(+1,120 B) 안이다. + +### 2.1 1103/05-01 잔여 (36.3) + +| 필드 | 내용 | +|---|---| +| ID·제목 | 1103/05-01 (잔여) 승인된 LOGOUT·ACCOUNT_DELETION이 journal 행을 한 순간만 세서, 그 전에 끝난 새 객체 put과 키를 잃은 행의 bytes를 남긴 채 `COMPLETED`를 보고한다 | +| 성격 | 확인된 결함 (재현 Y1a·Y1b·Y2, 실제 Chromium 05-R2) | +| 관련 관점 | 11, 15, 12, 17, 10, 5, 28, 24 | +| 근거 | **① 세기 전에 끝난 새 객체 put.** purge 순서는 (a) `listCommittedObjects`로 페이지를 읽고(`opfs-byte-store-adapter.ts:821`) (b) 객체마다 `objects.remove`(`:848`) (c) 마지막에 `countPartitionTransactions`(`:899`) (d) 0이면 sweep(`:913-940`)이다. 다른 탭 put의 journal 행은 `complete`가 지운다(`:335`). 그 앞의 `commitPut`(`:298`)이 객체 행을 만든다. 그래서 put이 (a) 뒤에 commit하고 (c) 앞에 `complete`하면, (a)의 목록에도 (c)의 수에도 없다. sweep은 committed 객체가 참조하는 chunk를 건너뛴다(`isChunkReferenced`, `:1417-1424`). 덮어쓰기라면 (b)의 remove가 `CONFLICT`가 되어 `moreObjectsAvailable: true`가 된다(`:853-861`). 새 객체에는 그런 장치가 없다.
**왜 객체 수에 달렸나.** (b)의 remove는 worker의 origin lease를 기다린다. 다른 탭 put은 BEGIN부터 FINISH까지 그 lease를 쥔다(`opfs-policy.ts:26-31`). 그래서 purge의 첫 remove가 put의 FINISH까지 멈추고, 그 뒤 put의 commit·finalize·complete와 purge의 남은 remove가 lease를 번갈아 쓴다. 지울 객체가 1개면 purge가 먼저 센다. 3개 이상이면 put이 먼저 `complete`한다.
**재현(손대지 않은 코드)**:
• Y1a(메모리, 저장소 0929/05-02 테스트와 같은 hook, `opfs-worker-runtime.test.ts:2440-2447`: 목록 읽기 직후 다른 탭 put을 끝냄) → report `{inspectedObjects:1, removedObjects:1, releasedBytes:3, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. 그 뒤 `object_late_0001`이 `{generation:1, bytes:[5]}`로 읽히고 chunk 1·manifest 1이 남는다.
• Y1b(메모리, hook 없음, 저장소 X1 테스트와 같은 순서에 객체 수만 바꿈, 각 10회): 객체 1개 → 10/10 `partitionDeleted`, 파일 0. 객체 3개 → 10/10 `chunkSweep:"COMPLETED"`, 파일 `[5]`로 읽힘, 파일 2. 객체 8개 → 10/10 같은 결과.
• 05-R2(실제 Chromium, 저장소 브라우저 X1 테스트에 객체 수만 더함, 각 3회): 객체 0·1개 → 6/6 `partitionDeleted` + `NOT_FOUND`. 객체 3·8개 → 6/6 `{removedObjects:3 또는 8, moreObjectsAvailable:false, chunkSweep:"COMPLETED"}` + `OPENED`.
**테스트가 놓친 이유.** 저장소의 X1 단위 테스트는 객체 1개(`opfs-worker-runtime.test.ts:2313-2343`), 브라우저 X1은 0개(`opfs-runtime.spec.ts:332`), parity 테스트도 0개다. 1103 완료 기준("X1·X2·X2b·X3 순서에서…")을 그 순서 그대로만 옮겼다.
**② `logicalKey`를 잃은 멈춘 put 행.** 세기는 `LOGICAL_KEY_INDEX`로 찾으므로(`indexeddb-opfs-journal.ts:893-899`) 키가 없는 행은 세지 못한다(커밋 `d13a393` 본문). 그 행의 staging receipt가 chunk를 sweep에서 지킨다(`opfs-worker-runtime.ts:1104-1110`, `:1136-1180`). reconcile은 그 행을 손상으로 건너뛰므로 staging도 정리하지 않는다. 05-03 수정 뒤 이 행은 `DEGRADED`도 내지 않는다(`opfs-byte-store-adapter.ts:716`). 재현 Y2(메모리): FILES_READY에서 멈춘 put의 행에서 `logicalKey`만 지움 → 첫 purge `{removedObjects:1, chunkSweep:"COMPLETED"}`, 남은 파일 `staging/transaction_w_1/receipt.json`, chunk 1, `object_dead_0001` manifest 1. reconcile `{inspectedTransactions:0, corruptTransactions:1, unattributedCorruptTransactions:1}`, 관측 `SUCCEEDED`. 두 번째 purge도 `COMPLETED`, 파일 3개 그대로. runbook은 "같은 수로 남아 있으면 할 일이 없다"고 적는다(`browser-file-storage-recovery.md:48-49`).
**계약 문장.** port: "For those two reasons the partition's bytes are gone exactly when this is `COMPLETED` or `partitionDeleted` is set; a put that begins after the purge reached its journal check is kept"(`opfs-ports.ts:154-160`). runbook: "이 두 reason에서는 report의 `chunkSweep`이 `COMPLETED`이거나 `partitionDeleted`가 있을 때 그 partition의 bytes가 지워진 것이다"(`:460-462`), "purge가 journal row를 센 뒤에 시작한 put … 의 데이터는 남는다(point-in-time)"(`:507-509`). ①의 put은 purge 시작 전에 시작했다. ②의 행은 purge보다 먼저 있었다 | +| 발생 조건 | ① OPFS 런타임을 조합한 제품에서, 승인된 LOGOUT·ACCOUNT_DELETION을 부를 때 같은 사용자의 다른 탭이 **새 파일**을 저장하고 있고, partition에 객체가 3개 이상일 때. 실험에서는 그 조건이면 매번 일어났다. runbook은 "purge 전에 그 partition의 쓰기를 멈추는 것이 composition의 몫"이라고 적는다(`:508-509`). 그러나 다른 탭의 진행 중 put을 멈추거나 기다릴 공개 API는 없다. ② journal 행의 `logicalKey`가 깨지고, 그 행이 멈춘 put(staging 있음)이고, 같은 partition에 다른 손상이 없을 때. 드물다 | +| 영향 | 계정 삭제·로그아웃 뒤 그 사용자 파일(①)이나 staging bytes(②)가 기기에 남는다. ①의 파일은 같은 partition으로 열면 읽힌다(Chromium에서 `OPENED`). 호출자는 port 계약대로 "다 지웠다"를 받으므로 다시 부르지 않는다. 공유 기기에서는 이전 사용자 데이터가 origin 저장소에 남는다. ②는 스스로 풀리지 않고 신호도 count 하나뿐이다 | +| 심각도·우선순위 | Medium · P2 유지. **OPFS에 개인 파일을 두는 제품은 P1**(출시 전 차단). 피해의 모양은 지난 판정과 같다(개인 데이터 잔존 + 거짓 완료). 지난 라운드 X1과 같은 순서가 보통 크기 partition에서는 고쳐지지 않았다. 지속되는 crash 경우(X2·X2b·X3)는 고쳐졌다. OPFS 런타임은 기본 구성에 없어(`AVAILABLE_NOT_COMPOSED`) 지난 라운드와 같은 등급으로 둔다 | +| 통제·증거 | "승인된 계정 삭제가 완료를 보고하면 bytes 0" 규칙: 세는 순간 살아 있거나 crash가 남긴 행은 M3(테스트 4건 + 변이 M1·M2·M3 검출), 세기 전에 끝난 새 객체 put과 키 없는 행은 **M0 확인**(그 경우를 보는 코드가 없음) · E2(Y1a·Y1b·Y2), E3(05-R2 Chromium 6/6) | +| 확실성과 남은 가정 | 메모리 런타임(실제 adapter·journal·worker 코드)과 실제 Chromium에서 같은 결과다. Firefox·WebKit에서는 돌리지 않았다. Firefox도 OPFS·Web Locks 순서가 같으므로 같을 것으로 보지만 확인하지 않았다. 객체 2개일 때는 돌리지 않았다 | +| 결정의 근거 | [기록] `d13a393`은 리뷰 5.1절 (c)(끝나지 않은 행이 있으면 partition 삭제)를 골랐고 (d)(항상 partition 삭제)를 "예산 단위 진행과 `removedObjects`·`releasedBytes` 보고를 잃는다"며 버렸다. [사실] (c)의 판단은 세는 한 순간의 journal 상태에 기댄다. 그 순간 전에 끝난 put은 journal에서 사라지고, 목록은 그보다 더 앞의 상태다. 지난 리뷰의 (c) 권고도 이 틈을 보지 못했다. [추론] 두 관찰 사이에 끝난 일을 보려면 세기 뒤에 목록을 다시 보거나, 관찰과 삭제를 한 lock 안에 넣어야 한다 | +| 이해 비용 | port 주석만 보고는 "세는 순간"이 언제인지 알 수 없다. 호출자가 이 틈을 알려면 adapter의 순서와 origin lease 동작을 읽어야 한다 | +| 최소 개선 방향 | (d') 승인된 LOGOUT·ACCOUNT_DELETION은 객체 순회를 하되, sweep 대신 늘 partition 삭제로 끝낸다. exclusive partition lock이 그때 진행 중인 put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition 행을 지우므로 ①·② 모두 막는다. 순회는 `removedObjects`·`releasedBytes` 보고를 위해 남길 수 있다 | +| 대안 비교 | (a) 세기를 sweep 뒤로 한 번 더 하고, 그때 committed 객체도 한 페이지(limit 1) 다시 본다. 하나라도 있으면 partition 삭제: ①을 막는다. ②는 남는다. journal 읽기가 둘 는다. (b) sweep이 staging receipt 때문에 건너뛴 chunk가 있으면 partition 삭제: ②를 막는다. worker 응답에 칸이 하나 는다. ①은 남는다. (c) (a)+(b): 둘 다 막지만 판단 조건이 일곱 개가 된다(`unfinished`, `corruptObjects`, `damaged`, `moreObjectsAvailable`, `deadlineReached`, 재확인, staging). (d') 늘 partition 삭제: 조건이 줄고 ①·②를 함께 막는다. 잃는 것은 예산 단위 진행이다. partition 삭제는 지금도 예산에 묶이지 않고(`opfs-byte-store-adapter.ts:941-949` 주석), 다른 탭이 쓰는 중이면 이미 이 길로 가야 맞다. [추론] (d')를 권한다. 예산 단위 진행이 꼭 필요하면 (c) | +| 단순화의 보존 조건 | 승인 없이 partition을 지우지 않는다(`authorizePolicyMaintenance` 뒤에만). 다른 partition의 행·파일을 건드리지 않는다. 진행 중 put을 지우는 것은 exclusive partition lock 안에서만 한다. TTL·SESSION_END·UNTIL_SYNCED·PRESSURE는 바꾸지 않는다. purge의 abort와 `mutationLockWaitTimeoutMs` 상한(1103/05-02)은 그대로 둔다 | +| 비용·부작용 | (d'): 판단 조건이 줄어 코드가 준다. 모든 승인 purge가 다른 탭의 put을 기다린다(지금은 끝나지 않은 행이 있을 때만). recipe fake의 purge도 늘 `partitionDeleted`가 된다. 기존 테스트 기대값 `chunkSweep: "COMPLETED"`(`opfs-worker-runtime.test.ts:2247-2272`, `:2277-2307`, `:2428-2479`)를 바꿔야 한다 | +| 재검토 조건 | 한 partition에 서로 다른 LOGOUT 정책의 객체가 섞여야 할 때((d') 불가). partition이 커서 예산 없는 삭제가 화면을 오래 막을 때 | +| 완료 기준 | Y1a, Y1b(객체 1·3·8개 각 10회), Y2, 05-R2(Chromium 객체 0·1·3·8개)에서 승인된 ACCOUNT_DELETION이 `COMPLETED`나 `partitionDeleted`를 보고하면, 그 직후 partition 아래 파일이 0개이고 그 객체가 `NOT_FOUND`다 | +| 검증 방법 | Y1a·Y1b·Y2(`scratchpad/r4-05/05-exp-block.ts`)를 `tests/unit/opfs-worker-runtime.test.ts`의 05-04 describe로 옮긴다. 05-R2의 브라우저판(`05-browser-block.ts`)을 `opfs-runtime.spec.ts`로 옮긴다. X1 테스트의 객체 수를 3개 이상으로 바꾸는 것만으로도 ①을 잡는다(Y1b) | +| 담당·기한·상태 | 미정 · 미정 · 일부 고쳐짐 | +| 재검증 결과 | `8a44226`: X2·X2b·X3과 객체 0~1개 X1은 지운다(테스트 + 변이). ①은 메모리 20/20, Chromium 6/6에서 남음. ②는 메모리에서 남음 | + +## 3. 이번 발견 (36.3) + +새 발견 1건: Low 1 · P3 1 · 확인된 결함 1. Critical·High·Medium 0, P0·P1·P2 0. 구조적 위험·미검증·개선 제안은 새로 세지 않았다(미검증은 5절). + +| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 05-01 | Low | P3 | 확인된 결함 | 23, 17, 15, 9, 21 | OIDC PKCE session owner recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어, 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 갈라진다 | + +### 05-01 OIDC PKCE session owner recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어, 제품이 `APP_NAMESPACE`를 바꾸면 이 키만 갈라진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (계약 문서와 코드 불일치, 정적 확인). 영역 09(세션 owner)와 겹칠 수 있다. 같은 결함이면 하나로 합친다 | +| 관련 관점 | 23, 17, 15, 9, 21 | +| 근거 | ① recipe가 sessionStorage 키를 상수 문자열로 적는다: `export const OIDC_PKCE_TRANSACTION_KEY = "ca-frontend:auth:v1:oidc-pkce-transaction"`. 주석은 "`buildPhysicalKey("auth", 1, "oidc-pkce-transaction")`; never a token"이다(`recipes/session-owners/oidc-pkce-session-owner.ts:43-44`). 함수를 부르지 않는다. 쓰기·읽기·지우기가 이 상수로 주입된 Storage에 직접 간다(`:183`, `:466`, `:543`, `:563`).
② 템플릿의 키 규칙: 물리 키는 `buildPhysicalKey`가 `${APP_NAMESPACE}:${scope}:v${n}:${name}`로 만든다(`src/contracts/storage-keys.ts:1`, `:179-185`). 계약 표는 "Persisted client storage … `defineStorageKey` in `src/contracts/storage-keys.ts`"라고 적는다(`docs/contracts/compatibility.md:31`). 다른 어댑터가 직접 쓰는 키도 registry에 `backend: "external"` 행으로 둔다(pulse 키, `storage-keys.ts:107-123`, 1101/05-01의 수정). 이 키는 registry 7행 어디에도 없다(`grep oidc src/contracts`).
③ 제품이 `APP_NAMESPACE`를 바꾸는 것은 예정된 일이다. memento 설계 문서가 `ca-frontend` → `memento`로 바꾼다고 적는다(`docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:186`). 매뉴얼은 이 recipe를 `src/bootstrap/`로 복사하라고 한다(`docs/manual/04-paired-backend-session.md:48-50`).
④ Web Storage 접근을 registry로 모으는 검사는 lint의 `localStorage`·`sessionStorage` 속성 금지다(`eslint.config.ts:82-83`, `:127-128`). recipe는 bootstrap이 넘긴 Storage 객체를 쓰고(`runtime-adapters.ts:300`, `hostValue(host, "sessionStorage")`), 그래서 이 검사에 걸리지 않는다. 키가 registry에 있는지 보는 검사는 없다.
⑤ 커밋 `05958bb`(`e40684b` 뒤)에서 생겼다 | +| 발생 조건 | 제품이 OIDC PKCE recipe를 복사해 쓰고, `APP_NAMESPACE`를 바꿀 때. 또는 제품이 registry를 보고 로그아웃·계정 삭제 때 지울 Web Storage 키를 정할 때 | +| 영향 | 이 키만 `ca-frontend:` 접두사로 남는다. 같은 origin에 템플릿에서 나온 앱이 둘이면 서로의 sign-in transaction을 덮어쓴다(드묾). registry가 "앱이 쓰는 Web Storage 키 목록"이 아니게 된다. registry로 지울 키를 정하는 제품은 버려진 sign-in의 PKCE verifier·`state`·`nonce`·돌아갈 경로를 지우지 못한다. 다만 sessionStorage라 탭을 닫으면 사라지고, callback이 먼저 지우며, 10분 뒤에는 쓰이지 않는다(`oidc-pkce-session-owner.ts:25-27`). 토큰은 두지 않는다 | +| 심각도·우선순위 | Low · P3. 기본 구성에는 없고(recipe), 값의 수명이 짧다. 피해는 키 이름이 갈라지는 것과 목록이 불완전한 것이다 | +| 통제·증거 | "앱의 Web Storage 키는 registry가 만든다" 규칙: 템플릿 src 안은 M3(lint + registry 테스트), recipe 키는 **M0 확인**(문자열 상수, 검사 없음) · E1 | +| 확실성과 남은 가정 | 키 문자열, 계약 문장, memento의 namespace 변경 계획은 파일로 확인했다. memento가 실제로 이 recipe를 쓰는지는 모른다 | +| 결정의 근거 | 적용 제외 — 이미 있는 키 규칙(`buildPhysicalKey`, `external` 행)을 recipe에도 적용하는 단순 수정이다 | +| 이해 비용 | recipe를 복사하는 사람은 주석의 `buildPhysicalKey(...)`를 보고 키가 registry를 따른다고 읽는다. namespace를 바꿀 때 이 상수도 바꿔야 한다는 것은 어디에도 없다 | +| 최소 개선 방향 | recipe가 `buildPhysicalKey("auth", 1, "oidc-pkce-transaction")`를 부르게 한다. 그리고 registry에 `AUTH_REDIRECT_TRANSACTION` 행을 `backend: "external"`로 둔다(pulse 키와 같은 모양, StoragePort는 거절). registry 분류(`public-preference`·`opaque-cache`·`sensitive-forbidden`)에 맞는 것이 없으면 그 행의 분류를 정한다 | +| 대안 비교 | 적용 제외 — 기존 규칙을 따르는 수정이다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | recipe 한 줄, registry 행 하나, registry 테스트 한 줄. 이미 recipe를 복사한 제품은 키 이름이 바뀌어 진행 중인 sign-in 하나를 잃는다(로그인 다시 시작) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | recipe의 키가 `buildPhysicalKey`로 만들어지고 registry에 `external` 행이 있다. `APP_NAMESPACE`를 바꾸면 이 키도 같이 바뀐다 | +| 검증 방법 | `tests/recipes/oidc-pkce-session-owner.test.ts`에서 키가 `STORAGE_REGISTRY.<행>.physicalKey`와 같은지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 적용 제외 — 신규 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | 적용 | M3 / M2 | E2(게이트 test:unit 2,883건, 05-R1) | P — purge가 끝나지 않은 행을 본다(1103/05-01 고쳐진 부분). 판단이 세는 한 순간에 기대어 그 전에 끝난 새 객체 put과 키 없는 행을 놓친다(1103/05-01 잔여, Y1b 20/20) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1(6.1절 스크립트), E2(`check:architecture`·`check:adapter-inventory` rc=0, FE-GATE-010 rc=0) | O — kernel 예외 밖 adapter 간 import 0건. kernel 파일은 `contracts`·`application/ports` 타입만 import한다. kernel 규칙 `pathNot` 그대로(`.dependency-cruiser.json:258-263`) | +| 3 | 변경 용이성 | 적용 | M2 / M2 | E1, E2(FE-GATE-012) | P — journal port에 필수 메서드가 또 하나 늘었다(`countPartitionTransactions`, `opfs-ports.ts:398-405`). 직접 구현한 쪽은 깨진다(커밋 본문에 [계약]). offline-indexeddb 예산 여유 786 B(37,714 / 38,500) | +| 4 | 인지 부하 | 적용 | — | E1 | P — 큰 파일 넷(1,880~2,641줄) 그대로. purge 완료 판단이 플래그 여섯 개(`unfinished` 추가)에 흩어져 있다(`opfs-byte-store-adapter.ts:803-953`) | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E2(Y1·Y2), E3(05-R2) | P — port·runbook이 "exactly when … `COMPLETED`"라고 적지만 세기 전에 끝난 put과 키 없는 행은 예외다(1103/05-01 잔여). runbook은 키 없는 행에 "할 일이 없다"고 적는다(`:48-49`). README §14.4가 1103/05-01을 "고침"으로 적었다 | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2(M4·M5 검출) | P — lock 기다림이 취소되고 상한이 있다(1103/05-02 고쳐짐). 손상 chunk reference 행은 여전히 reconcile을 실패로 끝낸다(0929/05-01 ③) | +| 7 | 운영 성숙도 | 적용 | M1 / M1 | E2(Y2) | P — 소속 없는 손상 행이 늘 켜진 경보를 만들지 않는다(1103/05-03 고쳐짐). 그 행이 bytes를 쥔 경우의 신호는 count 하나다(Y2에서 관측 `SUCCEEDED`, 1103/05-01 잔여 ②). 선택형 런타임은 조합이 없어 경보 경로가 없다 | +| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1 | P — purge report에 sweep이 건너뛴 staged·참조 chunk 수가 없다. Y1에서 `COMPLETED` report만으로는 남은 파일 2개를 알 수 없다. `unattributedCorruptTransactions`는 생겼다 | +| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | P — canonical JSON 3벌·`sameScope` 2벌(0929/05-07), `hasPartitionKey`가 키 문법을 한 번 더 적는다, recipe 키 상수(05-01) | +| 10 | 테스트 성숙도 | 적용 | M3 / M2 | E2(05-R1 변이 15개 중 12개 검출) | P — 1103 수정 변이 10개는 모두 죽었다. parity 테스트가 fake와 런타임을 같이 돈다. 그러나 X1 테스트가 객체 0~1개로만 돌아, 객체 수만 3개로 바꾸면 실패하는 수정을 통과시켰다(1103/05-01 잔여). Web Storage W2·W5·W6이 살아남았다(1101/05-06) | +| **11** | 데이터 성숙도 | 적용 | M3 / M2 | E2, E3(05-R2) | P — **"승인된 계정 삭제가 완료를 보고하면 partition bytes 0" 세부 규칙은 미충족**(1103/05-01 잔여, Chromium 6/6). crash가 남긴 행과 손상 object 행 경로는 충족한다. IndexedDB 롤백 중 계정 삭제는 실패로 끝난다(0929/05-05) | +| **12** | 동시성 성숙도 | 적용 | M3 / M2 | E2(Y1b), E3(05-R2 Chromium, FE-GATE-008) | P — 세는 순간 살아 있는 다른 탭 put은 partition 삭제가 기다렸다 지운다. 객체 3개 이상이면 그 put이 세기 전에 끝나 남는다(잔여 ①). lock 기다림 취소·상한(1103/05-02 고쳐짐). reconcile 대 partition 삭제, N-1 탭 공존은 미검증 | +| 13 | 확장성 | 적용 | — | E1 | ? — 규모 목표가 없다. partition 삭제는 예산이 없다 | +| 14 | 성능 성숙도 | 적용 | — | E2(FE-GATE-012) | ? — 목표가 없다. offline-indexeddb 레시피 37,714 gzip B(지난 라운드 37,423 B, +291 B). put·delete마다 타이머 하나가 는다(`opfs-byte-store-adapter.ts:1175`) | +| 15 | 보안 성숙도 | 적용 | M2 / M2 | E2, E3 | P — 기본 구성은 Web Storage에 개인 데이터를 두지 않는다(`storage-keys.ts` 7행). OPFS 계정 삭제 뒤 개인 파일이 남는다(1103/05-01 잔여, Chromium에서 `OPENED`). recipe 키가 registry 밖이다(05-01). 승인 정규식 두 벌(0929/05-06) | +| 16 | 의존성 성숙도 | 적용 제외 | — | — | - — 외부 패키지 없이 브라우저 API만 쓴다 | +| 17 | API / Contract 성숙도 | 적용 | M2 / M1 | E2, E3 | P — port의 `COMPLETED` 문장이 실제 보장보다 넓다(1103/05-01 잔여). fake와 런타임의 reconcile 의미가 같아졌다(1103/05-04 고쳐짐, M8·M8b 검출). 계약 표의 키 규칙을 recipe가 따르지 않는다(05-01) | +| 18 | 배포 성숙도 | 적용 | M2 / M1 | E1 | P — `e5b7b3e`·`d13a393` 이전 release 탭은 partition lock을 쥐지 않고 journal도 세지 않는다. 롤아웃 중 섞이면 막은 경합이 다시 열린다(미검증). IndexedDB N-1 계정 삭제 실패(0929/05-05) | +| 19 | 설정 성숙도 | 적용 | M3 / M3 | E2(M9 검출) | P — timeout 관계를 정책 검사가 거절한다(0929/05-09 고쳐짐). partition lock 기다림도 같은 값에 묶였다. 접두사 고정(0929/05-10) | +| 20 | 개발자 경험 | 다른 영역 | — | — | > — 영역 14 | +| 21 | Guardrail 성숙도 | 적용 | M3 / M2 | E2(FE-GATE-005·007·008·010·012·020 rc=0) | P — 아키텍처·inventory·boundaries(34건 거절)·레시피 예산·제거 드릴 게이트가 돈다. Web Storage 키가 registry에 있는지 보는 검사는 없다(05-01). lifecycle 리스너 규칙은 검사가 없다고 주석이 밝힌다 | +| **22** | 추상화 성숙도 | 적용 | M2 / M2 | E1, E2 | P — kernel 문서가 실제 내용과 맞다(0929/05-08, 1101/05-04 고쳐짐). 남은 위험: 폴더 예외라 adapter가 bootstrap 전용 두 파일을 import해도 규칙이 막지 않는다. fake가 런타임과 같은 의미를 갖는다(1103/05-04). 중복 helper(0929/05-07) | +| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 승인 정규식 두 벌(0929/05-06). recipe 키가 namespace 규칙과 따로 논다(05-01) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E2, E3 | P — `chunkSweep: "COMPLETED"`는 "세는 순간 끝나지 않은 행이 없었고 참조 없는 chunk를 다 훑었다"다. port 문장은 "partition이 비었다"로 읽힌다. Y1에서 이 값과 함께 파일 2개가 남았다(1103/05-01 잔여) | +| 25 | 조직 확장성 | 적용 | — | E0 | ? — 팀이 하나다 | +| 26 | Ownership 성숙도 | 적용 | — | E0 | ? — 선택형 런타임 조합이 없어 runbook 담당을 확인할 대상이 없다 | +| **27** | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0) | P — 번들 제거 드릴이 통과한다. 새 parity 테스트가 src OPFS를 import하지만 드릴이 그 파일을 함께 지운다(`scripts/test-browser-file-storage-runtime-removal.ts:47`). 기기 데이터 삭제는 OPFS 정상 경로에 틈이 남았다(1103/05-01 잔여) | +| **28** | 회복 가능성 | 적용 | M2 / M2 | E2(Y2) | P — 키가 읽히는 손상 journal 행은 승인된 purge가 partition째 지운다(M2 검출). 키 없는 행은 출구가 정해졌으나 bytes를 쥐면 풀리지 않는다(Y2). 손상 chunk reference는 reconcile을 막는다(0929/05-01 ③) | + +적용 항목 26개(16 제외, 20은 영역 14): 충족 1(2번), 부분 충족 21, 미충족 0, 미검증 4(13, 14, 25, 26). 11번의 "계정 삭제 뒤 bytes 0" 세부 규칙은 미충족이다. + +## 5. 미검증 + +| 항목 | 이유 | 확인에 필요한 것 | +|---|---|---| +| 1103/05-01 잔여 ①의 Firefox·WebKit 재현 | 05-R2는 Chromium만 돌렸다(요청 최소화). WebKit은 기본 정책에서 OPFS 지원 판정이 거절해 spec이 일찍 끝난다 | `05-browser.sh`를 `--project=firefox`로 한 번 | +| 객체 2개 partition에서의 ① | 1·3·8개만 돌렸다 | Y1b의 `[1, 3, 8]`에 2를 더함 | +| reconcile과 partition 삭제의 겹침 | 코드로만 판단(지난 라운드 5.2절 ①과 같음. 코드 변화 없음) | 삭제 두 단계 사이에 다른 탭 reconcile을 넣는 단위 테스트 | +| N-1 탭(partition lock·journal 세기 없음)과의 공존 | 실행하지 않음 | 이전 커밋 adapter와 현재 adapter를 같은 메모리 루트로 묶은 테스트 | +| WebKit의 OPFS 런타임 동작 | 기본 정책에서 지원 판정이 거절해 spec이 일찍 끝난다(`opfs-runtime.spec.ts` `installOpfsTab`이 `false`면 `return`) | 정책을 바꾼 WebKit 실행 또는 지원 범위 문서화 | +| 0929/05-05·05-06·05-07·05-10 | 파일이 바뀌지 않아 정적 확인만 함 | 지난 라운드 재현을 테스트로 옮김 | + +## 6. 실행 기록 + +### 6.1 노트북 정적 확인 + +| 명령 | 결과 | +|---|---| +| cross-adapter import 스크립트(오케스트레이터 scratchpad `xadapter.sh`: `src/adapters` 아래 상대 import를 `grep`으로 모으고 `realpath`로 대상 그룹을 풀어 같은 그룹·kernel 예외를 뺀다) | kernel 소비 79곳(`browser-file-storage/result.ts` 30, `platform/abortable-operation.ts` 23, `indexeddb-transaction` 5, `indexeddb-connection` 4, `system-clock` 5, `retry-after` 5, `json-member-scanner` 3, `bounded-capacity` 3, `cross-context-invalidation/index.ts` 1). **위반 0건** | +| `grep` kernel 10파일의 import | `contracts/result.ts`, `contracts/mutation-intent.ts`, `application/ports/*` 타입, kernel 안 파일뿐 | +| `git diff --shortstat e40684b..8a44226 -- src/adapters/platform src/adapters/browser-file-storage src/adapters/storage/indexeddb src/adapters/storage/browser-storage-*.ts src/contracts/storage-keys.ts` | 출력 없음(변경 0) | +| `git show 8da33a5`의 옮긴 블록과 `tests/helpers/memory-opfs.ts` 비교 | 주석·`export` 빼면 같다(동작 변경 없음) | + +### 6.2 오케스트레이터 게이트(같은 커밋, desktop, 인용) + +| 출처 | 결과 | +|---|---| +| `gates/summary.txt`(로컬 env) | `check:architecture`·`check:types`·`lint`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit` rc=0(194파일 2,883건. 이 영역 파일: opfs-worker-runtime 84, indexeddb-opfs-journal 18, opfs-byte-store 24, storage-registry 26, browser-storage-policy 8, runtime-adapters 18, browser-lifecycle 5, indexeddb-runtime 31, indexeddb-connection 33, indexeddb-transaction 28, indexeddb-maintenance 22, abortable-operation 22 모두 ✓). `test:component`·`test:integration`·`test:contract`·`test:runtime-schema` rc=0. `verify:documentation` rc=1(짝 백엔드 경로 문제, 이 영역과 무관) | +| `merge-48/summary.txt`(CI=true env) | FE-GATE-001~012, 020 rc=0. FE-GATE-013 rc=1(`tests/system/ci-runner/ci-artifact-contract.test.ts`, 이 영역과 무관, 오케스트레이터 몫) | +| 스냅샷 `artifacts/quality/gates/FE-GATE-008.txt`, `tests/browser-capabilities/results.xml` | capability 66건 통과. `opfs-runtime.spec.ts`의 05-01 X1·reconcile 2탭 테스트가 Chromium·Firefox에서 통과(WebKit은 지원 판정에서 끝남) | +| 스냅샷 `FE-GATE-010.txt` | `Browser file/storage boundaries: PASS (owned adapter allowed, 34 direct or misplaced native access cases rejected)` | +| 스냅샷 `FE-GATE-012.txt` | `budgets=file-transfer:56130/57800, offline-indexeddb:37714/38500, realtime:40811/42200, service-worker-pwa:9758/10100 gzip bytes` PASS | + +### 6.3 desktop 실행 + +이 영역이 직접 걸었던 run 두 개(`05-batch`, `05-browser`)는 lock 대기 중 19:55에 취소돼 실행되지 않았다(BRIEF-2). 같은 내용을 오케스트레이터 배치로 다시 돌렸다. 스크립트와 변이 표는 desktop `/tmp/claude-gates/r4/mut/05/`와 노트북 `scratchpad/r4-05/`에 같은 내용으로 있다(md5 대조). 결과는 노트북 `scratchpad/r4/results/05/`. + +| 이름 | 명령 | 변이 | rc | 결과 | 시간·부하 | 복원 | +|---|---|---|---|---|---|---| +| 05-R1 | `bash /tmp/claude-gates/r4/mut/05/05-batch.sh` (local env) | `05-mutate.mjs` M1~M9·M8b·W2~W8을 하나씩 걸고 사본으로 되돌림 + `05-exp-block.ts` | 0 | 변이 15개 중 12 검출. 실험 89/89 통과(원래 84 + 실험 5) | 92초, 부하 1.0~2.5 | clean | +| 05-R2 | `bash /tmp/claude-gates/r4/mut/05/05-browser.sh` (local env, Chromium) | 없음(임시 spec 복사본) | 0 | 4건 통과(복사본의 기존 3건 + Y1). `R4OUT` 12줄 | 13초, 부하 1.4 | clean | + +대조 실행은 하지 않았다. 변이 없는 같은 파일이 `8a44226`에서 통과한 기록이 `gates/test_unit.log`와 FE-GATE-007(test:recipes)에 있다. + +**변이 (05-R1).** 돌린 파일: OPFS 4파일 139건(`opfs-worker-runtime`, `indexeddb-opfs-journal`, `opfs-byte-store`, `tests/recipes/browser-file-storage-contracts`), Web Storage 3파일 52건(`storage-registry`, `browser-storage-policy`, `runtime-adapters`). + +| ID | 바꾼 것 | 결과 | 실패한 테스트(요지) | +|---|---|---|---| +| M1 | 끝나지 않은 행이 partition 삭제를 부르지 않음(`opfs-byte-store-adapter.ts:915`, `:952`) | 검출(6) | X1 "waits for a put…", X2·X2b·X3 3건, parity의 purge 2건 | +| M2 | 세기가 읽을 수 있는 행만 셈(`indexeddb-opfs-journal.ts:902-905`) | 검출(2) | "counts the unfinished rows…, a damaged one included", "…whose journal row is damaged" | +| M3 | 세는 범위를 authority 전체로(`:897-899`) | 검출(1) | 같은 journal 테스트 | +| M4 | put·delete의 partition lock 요청에 signal을 넘기지 않음(`opfs-byte-store-adapter.ts:1148`) | 검출(5) | "ends a queued put and a queued delete as soon as their caller aborts"(215 ms). 나머지 4건은 그 테스트가 lock을 놓지 못해 뒤 테스트가 10초 timeout(변이와 무관한 연쇄) | +| M5 | 대기 상한 ×1000(`:1177`) | 검출(4) | "ends a partition lock wait at the policy bound as a retryable BLOCKED"(10초 timeout). 나머지 3건은 같은 연쇄 | +| M6 | 소속 없는 행도 `DEGRADED`(`:716`) | 검출(1) | "reports a damaged journal row no partition owns…" | +| M7 | 키 없는 행을 소속 있음으로(`indexeddb-opfs-journal.ts:985`) | 검출(3) | journal 2건, adapter 1건 | +| M8 | fake가 FILES_READY를 다시 rollback(`browser-file-storage-fakes.ts:1880`) | 검출(1) | parity "FILES_READY (… false)" | +| M8b | fake purge가 멈춘 행 무시(`:1930`) | 검출(2) | parity purge 2건 | +| M9 | 정책 검사 `>=` → `>`(`opfs-policy.ts:112`) | 검출(1) | "rejects an idle bound equal to the lock wait" | +| W2 | TTL 모양 검사 제거(`browser-storage-adapter.ts:123`) | **생존**(52/52) | — | +| W4 | Firefox quota 이름 제거(`:324`) | 검출(1) | "falls back to memory on Firefox's quota error name too" | +| W5 | `__proto__` 등 키 거절 제거(`browser-storage-codec.ts:204`) | **생존**(52/52) | — | +| W6 | accessor 거절 제거(`:206`) | **생존**(52/52) | — | +| W8 | 만료 비교 `<=` → `<`(`browser-storage-adapter.ts:138`) | 검출(1) | "reads a record expiring at 100 at time 100 as undefined" | + +**실험 (05-R1, 메모리 OPFS·IndexedDB·Node Web Locks, 실제 adapter·journal·worker 코드).** + +| ID | 시나리오 | 결과 | +|---|---|---| +| Y1a | 객체 1개. 탭 W가 새 객체 put(source 대기) 중 탭 P가 ACCOUNT_DELETION. P의 목록 읽기 직후 W의 put을 끝냄(저장소 0929/05-02 테스트와 같은 hook) | put `ok`. report `{inspectedObjects:1, removedObjects:1, releasedBytes:3, moreObjectsAvailable:false, deadlineReached:false, chunkSweep:"COMPLETED"}`. `object_late_0001`이 `{generation:1, bytes:[5]}`로 읽힘. 남은 파일: chunk 1, manifest 1 | +| Y1b | hook 없음. 객체 N개, W의 새 객체 put이 source 대기 중 P가 ACCOUNT_DELETION, 20 ms 뒤 source 풀기. N마다 10회 | N=1: 10/10 `partitionDeleted`, `NOT_FOUND`, 파일 0. N=3: 10/10 `chunkSweep:"COMPLETED"`, `[5]` 읽힘, 파일 2. N=8: 10/10 같음 | +| Y2 | W의 `commitPut` 실패로 FILES_READY 행이 남은 뒤 그 행의 `logicalKey`만 지움. P가 ACCOUNT_DELETION → reconcile → ACCOUNT_DELETION | 두 purge 모두 `chunkSweep:"COMPLETED"`, `partitionDeleted` 없음. 남은 파일 `staging/transaction_w_1/receipt.json`, chunk 1, `object_dead_0001` manifest. reconcile `{inspectedTransactions:0, corruptTransactions:1, unattributedCorruptTransactions:1}`, 관측 `SUCCEEDED:`. 행은 남음 | + +**실험 (05-R2, Chromium, 실제 OPFS·Web Locks·DedicatedWorker).** 저장소 브라우저 X1 테스트(`opfs-runtime.spec.ts:332`)에 객체 수만 더했다. 탭 B(승인)가 객체 N개를 둔 뒤, 탭 A가 새 객체 put(source 대기), 탭 B가 ACCOUNT_DELETION, 250 ms 뒤 source 풀기. + +| N | 회수 | report | 그 객체 | +|---|---|---|---| +| 0 | 3 | `partitionDeleted: true` | `NOT_FOUND` 3/3 | +| 1 | 3 | `removedObjects:1, partitionDeleted: true` | `NOT_FOUND` 3/3 | +| 3 | 3 | `removedObjects:3, moreObjectsAvailable:false, chunkSweep:"COMPLETED"` | **`OPENED` 3/3** | +| 8 | 3 | `removedObjects:8, moreObjectsAvailable:false, chunkSweep:"COMPLETED"` | **`OPENED` 3/3** | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 05-01 | Low · P3 | 확인된 결함 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 | `recipes/session-owners/oidc-pkce-session-owner.ts:43-44`, `src/contracts/storage-keys.ts:179-185`, `docs/contracts/compatibility.md:31` | + +이월 중 열린 것: **1103/05-01 일부(Medium·P2, OPFS 개인 파일 제품 P1. README §14.4의 "고침"은 틀림, 2.1절)**, 0929/05-01 일부(③), 1101/05-06 일부(W2·W5·W6 생존), 0929/05-05·05-06·05-07·05-10 남음. diff --git a/docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md b/docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md new file mode 100644 index 00000000..dd6dc867 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/06-adapters-service-worker-push.md @@ -0,0 +1,229 @@ +# 영역 06 — adapters: service worker, push + +> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `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` +> 깊게 본 관점: 10, 18, 21, 28 (그다음 15, 19) +> 렌즈: 지난 라운드 수정이 완료 기준을 채우는가 / 수정이 검사를 약하게 만들지 않았는가 / SW 제어 아래 preload 허용(11-09)이 워커 결함을 가리는가 / Firefox 격리가 아직 필요한가 +> 영역 판정(35.8): 기본 구성(SW `null`) **지정 범위에서 사용 가능** · SW `ACTIVE` **조건부 사용 가능** · Web Push **조건부 사용 가능** (0절) + +ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 라운드 밖에서는 `1105/06-NN`이다. 지난 라운드(2026-11-03)는 `1103/06-NN`, 그 전은 `1101/06-NN`, `0929/06-NN`, `0925/06-NN`이다. + +실행 방식: 이 리뷰가 desktop lock에 넣은 실험 3건은 19:55에 취소됐다(실행 안 됨, checkout 무변경). 대신 오케스트레이터가 배치로 `06-R1`~`06-R11`을 돌렸다(20:05~20:07, 11건 모두 restore clean). 요청은 `scratchpad/r4/requests/06.md`, 패치는 같은 폴더의 `06-Rk.diff`, 로그는 `scratchpad/r4/results/06/06-Rnn.log`다. 판정은 이 커밋의 코드, 오케스트레이터 게이트 결과, 이 배치 결과로 했다. + +## 0. 결론 + +| 구성 | 결정 | 조건·이유 | +| --- | --- | --- | +| 기본(SW `null`, Web Push 미선택) | 지정 범위에서 사용 가능 | 이 영역 런타임이 돌지 않는다. 선택은 제품 소유 파일 `src/features/product-capabilities.ts:34`의 `null`이다 | +| SW `ACTIVE` | 조건부 사용 가능 | 지난 라운드와 같은 조건이다. 업데이트 실패 관측·활성화 UI는 제품이 붙인다(`0925/06-05`). 호스팅은 이제 확장자별 MIME을 probe가 본다(`1103/06-03` 고쳐짐). 새 조건: `public/`에 PWA 아이콘을 두는 제품은 06-01을 먼저 고친다. 하위 경로 호스팅 게이트는 13 영역 `0929/13-06`이다 | +| Web Push | 조건부 사용 가능 | registry `path`의 dot segment 구멍이 고쳐졌다(`1103/06-02`, 변이 06-R4 검출). 서버의 짧은 TTL·send-time 인가 조건은 그대로다 | + +- **지난 라운드 이 영역 발견 5건은 모두 고쳐졌다.** `1103/06-02`·`06-03`의 테스트는 되돌리는 변이를 잡는다(06-R4 5건, 06-R3 2건 실패). `1103/06-01`·`06-04`는 문서로 완료 기준을 채웠다. `1103/06-05`(= 02-06)는 FE-GATE-020 rc=0이고 realtime 제거 드릴 junit 7 check가 모두 통과다. `1103/06-03`의 live 호출 줄은 테스트가 없다(변이 06-R2 생존). 이것은 새 06-02로 셌다. +- **이월 항목**: `0929/06-03`·`0929/06-05`·`0929/06-06`·`1101/06-04`가 고쳐졌다. `1101/06-04`의 변이 4건은 모두 잡힌다(06-R5~R8). 그중 M3은 단언이 아니라 10초 test 시간 초과로 잡힌다. `0929/06-06`은 문서 선택지로 닫혔고 동작은 그대로다. 남음 6건: `0925/06-05`, `0925/06-08`, `0925` P3(route chunk export), `1101/06-03`, `1101/06-05`, `1101` R1~R4. +- **새 발견 3건, 모두 Low·P3. High·P1은 없다.** + - 06-01: 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)을 해시 자산으로 넣는다(06-R1 실행 확인). + - 06-02: 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지우는 변이는 44건 통과로 생존한다(06-R1, 06-R2). + - 06-03: SW 제어 아래에서 route chunk를 import하는 test가 없다. 제어 아래 preload 검사는 허용 때문에 모두 꺼진다. +- **preload 허용(`service-worker-update.spec.ts:45-52`)은 워커 결함을 가리지 않는다. 다만 제어 아래 preload 검사는 사실상 꺼진다.** + - 06-R9: 제어 아래 test 6건(엔진 2개 × 3건)에서 preload 26~27개가 모두 `ALLOWED`였다(158줄). 허용 밖 줄은 0이다. 제어 전 첫 load의 preload 26개는 모두 실행 표시가 있어 줄이 없다. + - 06-R10: 워커가 직전 캐시로 답하지 않게 바꾸자 두 test가 실패했다. 실패 줄은 허용 밖에 있었다: console 404, `requestfailed`, "Failed to fetch dynamically imported module". + - 덧붙여: 그 변이에서 추가 test의 화면 단언은 통과했다. chunk 복구가 페이지를 reload해 B의 화면을 그렸기 때문이다. 화면 단언만으로는 이 결함을 못 잡는다(06-03 최소 개선 방향에 반영). +- **Firefox 격리(`expires=2027-03-31`)는 아직 필요하다.** 06-R11에서 skip을 지우자, 격리 대상 3 test가 주석대로 실패했다. 실패는 `requestActivation()` → `NO_WAITING_WORKER` 2건과 `blocked` 대신 `loaded` 1건이다. 나머지 3 test는 통과했다. recovery spec은 strict fixture(`page.route`)를 쓰지 않으므로, 원인은 fixture가 아니라 Playwright Firefox의 워커 제어다. Playwright를 올릴 때 다시 본다(`package.json:170` `1.62.0`). +- **약해진 검사**: 이 영역 경로에서 단언 삭제, 정규식 완화, timeout·상한 상향, skip 추가는 찾지 못했다(`git diff e40684b..8a44226`). 넓어진 허용 목록은 위 preload 허용 하나다. 판단은 06-03에 적었다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` (템플릿, reference implementation) | +| 커밋·작업 상태·확인 시점 | `8a44226`, laptop worktree(HEAD = 기준, 추적 파일 변경 없음), 2026-11-05 19~20시. `git log e40684b..8a44226 -- <영역 경로>` 19커밋. 이 영역 코드에서 바뀐 곳은 `notification-registry.ts`(1103/06-02), `hosting-probe.ts`·`verify-hosting-headers.ts`(1103/06-03, 13-01, 13-02), `vite.service-worker.config.ts`(`rolldownOptions` 이름), 운영 문서 2개, 테스트·e2e 도우미다. `src/adapters/service-worker/` 7파일은 바뀌지 않았다 | +| 목적과 지원 실행 구성 | 브라우저 SPA + 정적 호스팅 + Service Worker. SW 선택 기본값 `null`. 선택은 이제 제품 소유 `src/features/product-capabilities.ts:34`에 있고 템플릿 `installed-runtime-capabilities.ts:37-48`이 투영만 한다(1103/09-05). Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts:61-65`) | +| 필수 요구와 규모·운영 목표 | 합의된 SLO·업데이트 전파 목표는 없다. 사전 캐시 상한 256개·5 MiB(`src/contracts/service-worker.ts:13-16`) | +| 읽은 코드·구성 범위 | 경로 머리의 파일 전부. 연결: `src/contracts/{service-worker,service-worker-static-manifest,web-push}.ts`, `src/features/{product-capabilities,installed-runtime-capabilities}.ts`, `src/bootstrap/{create-runtime-composition,optional-runtime-host}.ts`, `src/adapters/web-push/inbound/*`, `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/e2e/support/service-worker-builds.ts`, `tests/support/browser/{strict-browser-test,preload-use}.ts`, `tests/unit/{service-worker-*,web-push-*,hosting-probe}.test.ts` | +| 읽은 문서(주장) | `docs/operations/browser-file-storage-recovery.md` 8절(`:533-647`), `docs/operations/release-cache-rollback.md`(`:41-99`, `:199-239`), `docs/architecture/optional-adapter-recipes.md`(`:112`, `:128-168`), `config/recipes/frontend-capability-recipes.json` `service-worker-pwa`(`:118-151`), `docs/architecture/realtime-events-web-push-and-bounded-polling.md:1594-1599`, 지난 라운드 README §12·§13·§14, 수정 커밋 본문. 모두 주장으로 읽었다 | +| 게이트(오케스트레이터, 같은 커밋) | local env(`gates/summary.txt`): `check:architecture`·`check:types`(`check:types:service-worker` 포함, `package.json:29`)·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `test:unit`은 194파일 2,883건이고 이 영역 `service-worker-runtime` 64·`web-push-worker-runtime` 26·`hosting-probe` 37·`service-worker-build-output` 7이 통과했다. `verify:documentation` rc=1(두 번 모두)의 실패 줄은 짝 백엔드 경로뿐이고 이 영역 문서는 없다. CI env(`merge-48/summary.txt`): FE-GATE-001~012·020 rc=0, 013 rc=1(이 영역 밖). FE-GATE-008의 첫 명령은 `test:e2e`다(`config/ci/gates.json:252-254`, 기본 config의 모든 spec, 3 엔진). 그래서 SW spec 2개가 CI env에서 통과했다는 뜻이다. FE-GATE-020이 쓴 `artifacts/tests/realtime-runtime-removal.xml`은 tests=7 failures=0이다. FE-GATE-019는 release 단계라 이번 실행에 없다(`config/ci/gates.json:2259-2279`). snapshot의 `hosting-headers.json`은 2026-07-27자라 현재 증거로 쓰지 않았다 | +| 수행한 테스트·실험 | 오케스트레이터 배치 11건(6절): 단위 probe 1, 단위 변이 7, e2e 3(추가 test·줄 출력, 워커 변이, Firefox skip 해제) | +| 확인하지 못한 범위·이유 | 5절. 실제 CDN·푸시 서비스, live 모드 probe, 하위 경로 브라우저 재확인 | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 문서(`docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md`)의 발견 5건과 2절 이월 항목 전부를 다시 봤다. 지난 실행 결과(변이 13건, L1~L3)는 현재 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +상태: **고쳐짐** = 완료 기준을 이 커밋에서 확인 · **일부** = 남은 것을 적음 · **남음** = 코드 그대로 · **재발** · **틀린 발견**. + +| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) | +| --- | --- | --- | --- | +| 1103/06-01 | 운영 문서가 "`verify:hosting-headers`는 워커 헤더를 보지 않는다"고 적음 | **고쳐짐** | 새 문장은 이렇다. 워커를 싣는 빌드에서 live 모드가 `/service-worker.js`를 요청해 `no-cache`를 확인하고, 다르면 FAIL이다. fixture 모드는 `UNVERIFIED`다. 하위 경로는 손으로 확인한다(`browser-file-storage-recovery.md:605-612`). 다른 문서와 같다(`release-cache-rollback.md:72-73`). 코드와도 맞다(`verify-hosting-headers.ts:86-89`, `cache-policy.json:41-47`, `hosting-probe.ts:411-418`). 완료 기준 "두 운영 문서가 같은 검사 범위를 적는다" 충족 | +| 1103/06-02 | Web Push registry `path`의 `..`·`%2e%2e`가 base path 밖을 엶 | **고쳐짐** | `safePath`가 정규화한 `pathname + search`가 입력과 같을 때만 받는다(`notification-registry.ts:117-125`). 테스트(`tests/unit/web-push-worker-runtime.test.ts:421-453`)는 06-R4 변이(비교 삭제)에서 5건 모두 실패했다: `/../admin`, `/%2e%2e/admin`, `/%2E%2E/admin`, `/./inbox`, `/inbox/..`. 문서도 규칙을 적는다(`realtime-events-web-push-and-bounded-polling.md:1596-1599`). 완료 기준 충족. 부수 동작(06-R1 실행): `/공지`, `/inbox?q=a b`, `/inbox?filter=it's`, `/inbox?`도 같은 일반 메시지 "registry is invalid"(`:53`)로 거절된다. 문서가 "parser가 바꾸지 않는 경로만"이라고 적으므로 결함으로 세지 않는다. 메시지가 이유를 말하지 않는 점은 8번 관점에 적었다 | +| 1103/06-03 | install은 7개 확장자 MIME을 정확히 요구하지만 probe는 JS만 봄 | **고쳐짐** | `probeAssetContentTypes`는 후보 dist의 `assets/`에서 확장자마다 첫 파일을 요청한다. 그리고 워커 표(`CACHEABLE_ASSET_CONTENT_TYPES`)와 비교한다(`hosting-probe.ts:255-315`). live 모드에서 부른다(`verify-hosting-headers.ts:119-120`). 테스트(`hosting-probe.test.ts:329-380`)는 06-R3 변이(`passed: true`)에서 2건 실패했다("fails a host that serves CSS as text/plain", "fails a font served as octet-stream …"). 완료 기준 "live probe가 CSS `text/plain` 호스트를 FAIL" 충족(함수 수준). 남은 관찰은 수정이 만든 새 모양이라 **06-02**로 셌다. live 호출 줄 무검사(06-R2 생존), redirect 통과(06-R1), 워커 없는 빌드다 | +| 1103/06-04 | waiting 워커가 바뀔 때마다 밀려난 후보 캐시가 쌓임 | **고쳐짐**(문서 선택지 (a)) | 완료 기준 (a) "문서가 waiting 기간 캐시 수를 적는다" 충족. 문서가 적는 것: 쌓이는 규칙, 예(A·B·C 3개 → C·A 2개), 5 MiB 상한, 쿼터 결과, 줄이는 방법(`requestActivation()` 화면), install이 지우지 않는 이유(`browser-file-storage-recovery.md:620-632`, `release-cache-rollback.md:211-215`). 동작은 그대로다(`service-worker-lifecycle.ts` `onActivate`만 지움). 재검토 조건(사전 캐시 1 MiB 초과 + 잦은 릴리스)은 남는다 | +| 1103/06-05 (= 02-06) | `test:realtime-removal`(FE-GATE-020)이 문서 테스트 15건으로 실패 | **고쳐짐** | 오케스트레이터 `merge-48/FE-GATE-020.log`: `FE-GATE-020 removability: PASS (merge-cycle)`, rc=0, 1,156초(CI env). `artifacts/tests/realtime-runtime-removal.xml`은 tests=7 failures=0이다. check는 typecheck·lint·architecture·test·build·optional-catalog·ci-contract다. 원인 수정은 02 영역 몫이다(문서를 읽는 테스트 제외 목록 공유, `scripts/lib/removal-fixture.ts:56-81`) | +| 0929/06-03 | 레시피가 오프라인 셸을 SW 설치 조건으로 적지만 계약은 금지 | **고쳐짐** | catalog `trigger`가 "navigation network-only, offline shell 없음"이다(`frontend-capability-recipes.json:140`). `failureKinds`는 `offline-navigation-network-error`다(`:145`). 레시피 표는 "오프라인 셸은 지원하지 않는다"고 적고(`optional-adapter-recipes.md:112`) 졸업 절차를 둔다(`:158-168`). 완료 기준 "catalog·레시피·설계의 주장이 같고 졸업 절차가 있다" 충족. 같은 절의 "사전 캐시는 해시 이름의 `assets/`뿐"(`:160-161`)은 코드와 다르다(**06-01**) | +| 0929/06-05 | `service-worker.js` `no-cache`가 호스팅 정책·probe에 없음 | **고쳐짐**(이 영역 몫) | 루트 base 검사는 지난 라운드에 고쳐졌다. 남았던 문서 문장은 1103/06-01로 고쳐졌다. 하위 경로 base를 probe가 거절하는 부분(`hosting-probe.ts:411-418`)은 13 영역 `0929/13-06`에서 센다 | +| 0929/06-06 | 제거 2·3단계가 `service-worker.js`를 내보내지 않음 | **고쳐짐**(문서 선택지) | 완료 기준 첫째 "운영 문서에 유지 기간 조건이 있다" 충족. 문서가 적는 것: `REMOVE_REGISTRATION` release는 최대 미방문 기간 이상 유지하고, 남은 사용자가 보이면 다시 배포한다(`browser-file-storage-recovery.md:640-647`, `release-cache-rollback.md:233-239`). 동작은 그대로다. 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 나온다(`scripts/build-frontend.ts`, 변경 없음) | +| 0925/06-05 | 업데이트 설치 실패·`observe`·`health()` 미연결 | **남음**(문서화됨) | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). composition은 `telemetry`만 넘긴다(`create-runtime-composition.ts:50-54`). `src`에서 `requestActivation`·`onUpdateWaiting`·`onReloadRequired`·`health()`를 읽는 곳은 어댑터·계약·host 밖에 없다(`git grep`). 레시피가 다운스트림 몫으로 적는다(`optional-adapter-recipes.md:134-150`) | +| 0925/06-08 | 이전 빌드 fallback이 `assets/`를 하드코딩 | **남음** | `service-worker-static-assets.ts:66`, `cache-policy.json:26` `pathPattern "/assets/*"`. 06-01과 같은 상수 문제로 이어진다(06-01 최소 개선 방향) | +| 0925 P3 | route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | **남음** | `service-worker-update.spec.ts:54-71` 그대로 | +| 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`)를 읽는 곳이 없다. `retainedPreviousCaches`는 `void`로만 참조된다(`service-worker-lifecycle.ts:169`) | +| 1101/06-04 | SW 보호 장치 변이 M1·M3·M9·N8이 살아남음 | **고쳐짐** | 테스트 3건이 생겼다: M1 `service-worker-runtime.test.ts:1084`, M3·M9 `:773`, N8 `:1418`. 배치 결과: M1(06-R5)은 `expected { cache: 'no-store', …(1) } to match object { …(2) }`로 실패했다. M9(06-R7)는 `expected true to be false`, N8(06-R8)은 `vi.fn() … called 1 times`로 실패했다. 모두 단언 실패다. M3(06-R6)은 `Test timed out in 10000ms`(10,001 ms)로 실패했다. 이유: nonce를 다시 받으면 두 번째 요청이 30초 drain(`src/contracts/service-worker.ts:19` `clientDrainMs`)을 기다리는데, test 상한이 10초다(`vitest.config.ts:43`). drain 상한을 10초 아래로 줄이면 drain 시간 초과도 `REJECTED`라서 M3은 다시 생존한다. 지금은 잡히므로 고쳐짐으로 본다 | +| 1101/06-05 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | **남음** | `service-worker-static-assets.ts:280-285`. 이전 캐시 재사용 없음(`:221-267`) | +| 1101 R1~R4 | 리팩터링 후보 | **남음** | R1 `service-worker-lifecycle.ts:169`. R2 `validateActiveFence` 두 벌(`web-push/inbound/push-event-adapter.ts:196`, `notification-click-adapter.ts:356`). R3 `SYNC_WAKE_OBSERVED`가 버전을 숫자로 씀(`service-worker-entry.ts:170`). R4 `bounds a stream that never produces a chunk`(`service-worker-runtime.test.ts:2006`). 파일 64건이 5,221 ms(`gates/test_unit.log`) | + +## 3. 이번 발견 (36.3) + +새 발견 3건. 심각도: Critical 0 · High 0 · Medium 0 · Low 3. 우선순위: P0 0 · P1 0 · P2 0 · P3 3. 성격: 확인된 결함 1 · 구조적 위험 1 · 미검증 0 · 개선 제안 1. + +### 06-01 사전 캐시 수집이 `assets/` 밖 public 파일도 "해시 이름"으로 보고 immutable 자산으로 넣는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 23, 5, 21 | +| 근거 | 해시 판정 정규식은 `/-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/`이다(`src/contracts/service-worker.ts:116`). 수집기는 dist 전체를 돌고 파일 이름만 이 정규식으로 본다. 디렉터리 제한이 없다(`scripts/generate-service-worker-assets.ts:57-64`). 같은 파일의 주석은 "Vite emits content-hashed names; only those may be treated as immutable"이다(`:44`). Vite가 내용 해시를 붙이는 곳은 `assets/`이고, `public/` 파일은 이름 그대로 dist 루트에 복사된다. **06-R1**(실제 `collectStaticAssets`, 임시 dist): 결과 manifest에 `/android-chrome-192x192.png`, `/apple-touch-icon.png`, `/safari-pinned-tab.svg`가 `assets/` 두 파일과 함께 들어갔다. `favicon.svg`는 빠졌다. 나머지 셋은 `assets/`만 가정한다. 이전 릴리스 fallback(`service-worker-static-assets.ts:66-74`), immutable 호스팅 surface `/assets/*`(`config/hosting/cache-policy.json:25-31`), 새 MIME probe(`scripts/lib/hosting-probe.ts:284-290`)다. 06-R1에서 probe는 같은 dist의 `assets/` 두 파일만 요청했다. 레시피 문서는 "사전 캐시는 해시 이름의 `assets/`뿐"이라고 적는다(`docs/architecture/optional-adapter-recipes.md:160-161`). 템플릿 `public/`에는 `config.json`·`release-manifest.json`뿐이라 지금 빌드에는 영향이 없다 | +| 발생 조건 | SW `ACTIVE` 제품이 PWA 아이콘을 `public/`에 둔다(이 레시피 id가 `service-worker-pwa`다). 같은 이름으로 내용을 바꾼다. CDN이 그 파일을 TTL 동안 옛 내용으로 준다(호스팅 정책에 그 파일의 캐시 규칙이 없다) | +| 영향 | 새 릴리스 install이 그 파일에서 `INTEGRITY_MISMATCH`로 전체 거절된다(`service-worker-static-assets.ts:333`). 사용자는 CDN TTL이 지날 때까지 옛 워커에 머문다. 첫 방문은 SW 없이 돌고 `service-worker.start.failed`가 남는다. 업데이트 실패는 신호가 없다(`0925/06-05`). 호스팅이 그 파일을 틀린 MIME으로 주면 probe는 보지 않고 install만 실패한다. 데이터 손상은 없다 | +| 심각도·우선순위 | Low · P3. 여러 조건이 겹쳐야 하고 결과는 업데이트 지연이다 | +| 통제·증거 | "immutable로 다룰 파일은 Vite가 해시한 `assets/` 파일뿐" 규칙: 수집기 M0(디렉터리 제한 없음), fallback·호스팅 M2 · E1 + E2(06-R1) | +| 확실성과 남은 가정 | 수집 결과는 실행으로 확인했다. CDN이 옛 내용을 준다는 것은 일반적인 CDN 기본 동작에 기댄 추론이다. 실제 브라우저 install 실패는 돌리지 않았다 | +| 결정의 근거 | 적용 제외 — 규칙("해시한 `assets/`만")이 주석·문서·fallback·호스팅 정책에 이미 있고 수집기만 어긋난다 | +| 이해 비용 | 제품 개발자는 문서대로 `assets/`만 사전 캐시된다고 믿는다. 루트 파일이 들어가는지는 정규식과 수집 루프를 같이 읽어야 안다 | +| 최소 개선 방향 | 수집기가 `assets/` 아래 파일만 받는다. 그 디렉터리 이름을 계약 모듈의 상수 하나로 둔다. fallback(`service-worker-static-assets.ts:66`)·probe(`hosting-probe.ts:285`)·수집기가 그 상수를 같이 쓴다. 그러면 `0925/06-08`(`assetsDir` 하드코딩)을 고칠 때 한 곳만 바꾸면 된다 | +| 대안 비교 | (a) 디렉터리 제한: 이름과 무관하게 맞다. (b) 정규식을 Vite 해시 형식(8자 고정)으로 좁힘: 우연히 맞는 이름이 남는다. (c) 문서만 고침: 아이콘 문제는 그대로다. (a)가 가장 작고 맞다 | +| 단순화의 보존 조건 | `assets/` 아래 해시 파일은 그대로 사전 캐시한다. `index.html`·`service-worker.js`·설정·manifest 제외 목록(`generate-service-worker-assets.ts:36-42`)을 유지한다 | +| 비용·부작용 | 수 줄. 루트에 해시 이름 파일을 일부러 두는 제품은 사전 캐시에서 빠진다(그런 파일은 Vite가 만들지 않는다) | +| 재검토 조건 | 제품이 `assetsDir`를 바꾸면 상수를 그 값에서 읽는다 | +| 완료 기준 | `collectStaticAssets`가 dist 루트의 `apple-touch-icon.png`를 manifest에 넣지 않고, `assets/` 아래 해시 파일은 넣는다 | +| 검증 방법 | 수집기 단위 테스트에 루트 아이콘 사례 1개(06-R1 첫 test와 같은 입력) | +| 담당·기한·상태 | 템플릿 소유자 · SW를 켜는 제품 전 · 열림 | +| 재검증 결과 | 해당 없음(이번 라운드 발견) | + +### 06-02 확장자별 MIME probe(1103/06-03 수정)가 install 조건 일부만 옮겼고, live 모드의 호출 줄은 테스트가 지키지 않는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관련 관점 | 21, 18, 10 | +| 근거 | ① redirect: install fetch는 `redirect: "error"`라서 redirect가 하나라도 있으면 `FETCH_FAILED`다(`service-worker-static-assets.ts:283`, `:296-297`). probe는 `redirect: "follow"`로 받고(`hosting-probe.ts:279`) 최종 status와 MIME만 본다(`:299-311`). 다른 surface는 `final-origin`을 보지만(`:148-154`) 이 함수는 보지 않는다. **06-R1**: `redirected: true`이고 최종 URL이 다른 200 응답을 `hashedAsset.js` `passed: true`로 냈다. ② 워커 없는 빌드: probe는 `workerShipped`와 무관하게 live 모드에서 늘 돈다(`verify-hosting-headers.ts:119-120`). `:86`의 조건은 `serviceWorker` surface에만 쓴다. 주석과 문서는 이유를 워커로만 적는다(`hosting-probe.ts:269-275`, `release-cache-rollback.md:74-79`). 워커가 없으면 글꼴·이미지의 정확한 MIME은 페이지에 필요하지 않다(`nosniff`는 script·style에 적용된다. 일반 지식, 이 저장소에서 확인하지 않음). ③ 호출 줄: live 분기의 `probeAssetContentTypes` 호출(`verify-hosting-headers.ts:120`)을 지키는 테스트가 없다. **06-R2**: 그 호출을 `void probeAssetContentTypes;`로 바꿔도 `hosting-probe`·`service-worker-build-output` 44건이 모두 통과했다(생존). live 모드는 루프백·http를 거절한다(`hosting-probe.ts:381-410`). 그래서 저장소 안 테스트는 이 분기에 들어갈 수 없다 | +| 발생 조건 | ① 호스트가 해시 자산을 같은 origin 안에서 redirect한다(정규 경로 규칙, object storage 웹사이트 규칙). ② SW `null` 제품이 글꼴을 `application/octet-stream`으로 주는 호스트를 쓴다(오래된 MIME 표). ③ 누군가 live 분기를 고치다 호출을 빠뜨린다 | +| 영향 | ① FE-GATE-019 PASS인데 워커 install이 매번 실패한다. ② 페이지에 피해가 없는 MIME으로 FE-GATE-019가 FAIL한다. 운영자가 원인을 워커 문서에서 찾는다. ③ `1103/06-03`의 검사가 조용히 사라지고 게이트는 계속 PASS다 | +| 심각도·우선순위 | Low · P3. ①은 드문 호스팅 구성이다. ②는 막는 쪽(안전한 쪽) 오판이다. ③은 미래 회귀 위험이다 | +| 통제·증거 | "probe PASS면 호스팅 때문에 install이 실패하지 않는다" 규칙: MIME은 M3(함수 테스트, 06-R3 검출), redirect는 M0, live 호출은 M2(코드에만 있음, 06-R2 생존) · E1 + E2 | +| 확실성과 남은 가정 | ①③은 실행으로 확인했다. ②는 코드로 확정된다 | +| 결정의 근거 | 수정 커밋(`0f58abbd`) 본문은 세 가지를 위험으로 적었다: "확장자마다 파일 하나만 본다", "cache-control은 다시 보지 않는다", "live 모드를 실제 호스트로 돌리지 않았다". redirect와 워커 없는 빌드는 적지 않았다. 리뷰어의 추론: install 조건(상태·MIME·redirect·워커 유무)을 probe가 한 함수로 따라가면 셋 모두 닫힌다 | +| 이해 비용 | 운영자는 FE-GATE-019 PASS를 "워커 install도 된다"로 읽는다. 실제 범위는 install의 fetch 옵션과 probe의 fetcher를 같이 읽어야 안다 | +| 최소 개선 방향 | (1) 자산 probe의 fetcher를 `redirect: "manual"`로 바꾸고 3xx·`opaqueredirect`를 FAIL로 본다. (2) 비JS 확장자는 `shipsServiceWorker`일 때만 요구한다. 의도라면 대신 "워커 없이도 정확한 MIME을 요구한다"고 주석·문서에 적는다. (3) live 분기를 fetcher를 받는 함수로 빼서, 테스트가 호출을 확인한다 | +| 대안 비교 | (a) 위 세 가지 (b) 문서에 한계만 적음(①③이 그대로) (c) 현상 유지. (a)의 (1)(3)은 수 줄이고 (2)는 정책 결정이다 | +| 단순화의 보존 조건 | 확장자별 MIME 검사와 `.js`의 `application/javascript` 허용(`hosting-probe.ts:261-267`, `hosting-probe.test.ts:374-380`)을 유지한다 | +| 비용·부작용 | 수십 줄과 테스트. 호스팅 검사는 13 영역과 같이 고친다 | +| 재검토 조건 | probe가 실제 사전 캐시 목록(워커에 들어간 manifest)을 읽게 되면 ②와 06-01의 probe 쪽 공백이 함께 닫힌다 | +| 완료 기준 | 같은 origin redirect 뒤 200을 주는 fetcher 대역에서 `hashedAsset.js`가 FAIL이다. 06-R2와 같은 변이가 테스트 1건을 실패시킨다 | +| 검증 방법 | `hosting-probe.test.ts`에 redirect 사례 추가, live 분기 함수 테스트, 06-R2 재실행 | +| 담당·기한·상태 | 템플릿 소유자(13 영역과 공동) · 미정 · 열림 | +| 재검증 결과 | 해당 없음 | + +### 06-03 SW 제어 아래에서 route chunk를 import하는 browser 검사가 없다. 11-09 허용 때문에 그 아래 preload 검사도 모두 꺼진다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안 (현재 결함은 없음, 06-R9에서 실제 경로가 동작함을 확인) | +| 관련 관점 | 10, 28, 21 | +| 근거 | 허용은 `allowedBrowserFailure: /^preloadunverifiable:service-worker:\/assets\/[\w-]+\.js$/u`다(`tests/e2e/service-worker-update.spec.ts:45-52`). fixture는 링크가 붙는 순간 워커가 제어 중이면 그 preload를 `service-worker`로 적는다(`tests/support/browser/preload-use.ts:72-74`, `:94-101`). 실행 표시가 없으면 `preloadunverifiable:service-worker:`로 낸다(`:198-199`). 워커는 해시 `/assets/*.js`를 모두 가로챈다(`service-worker-lifecycle.ts:272-278`, `service-worker-entry.ts:106-107`). 그래서 제어 아래 build script는 표시를 붙이는 route(`preload-use.ts:211`)를 거치지 않는다. WebKit의 3초 추정 경고도 이제 모든 spec에서 무시한다(`strict-browser-test.ts:16-24`). **06-R9**(줄 출력 패치): 제어 아래 test 6건(chromium·webkit 각 3건)에서 preload 26~27개 전부가 `ALLOWED`였다(158줄, 허용 밖 0줄). 제어 아래에서는 검사가 하나도 판정하지 못한다. 제어 전 첫 load(install test 4건)에서는 같은 26개가 모두 실행 표시를 받아 줄이 없다. 한편 spec 자체는 제어 아래에서 route를 import하지 않는다. 옛 탭 회복은 페이지의 `fetch(removedChunk)`로만 본다(`service-worker-update.spec.ts:267-276`) | +| 허용이 가리는가(오케스트레이터 질문) | **가리지 않는다. 06-R10이 확인했다.** 워커가 직전 캐시로 답하지 않게 바꿨다(`service-worker-lifecycle.ts:296`을 `return null`로). 기존 test "serves A's removed chunk …"는 `status 404 ≠ 200` 단언과 `console:error:Failed to load resource … 404`로 실패했다. 추가 test는 허용 밖 세 줄로 실패했다: console 404, `requestfailed:GET:/assets/not-found-page-…js:net::ERR_ABORTED`, `console:error:TypeError: Failed to fetch dynamically imported module`. 같은 run의 허용 줄 52개는 실패를 덮지 않았다. 코드로 본 이유: 허용이 숨기는 것은 "제어 아래 preload됐고 실행 표시가 없는 `/assets/*.js`"뿐이다. 무엇을 preload할지는 Vite 빌드가 정하고 워커가 정하지 않는다. `/assets/` 이름은 내용 해시라 워커가 옛 바이트를 줄 수 없다. 06-01의 루트 파일은 허용 패턴 밖이다. 워커가 청크 실행을 깨면 console·`requestfailed`·page error·`start:` 단언으로 드러난다 | +| 06-R9가 보인 실제 경로 | B가 제어하는 A 탭에서 client navigation으로 지워진 route를 열었다. 두 엔진 모두 not-found 화면이 그려졌다. `/assets/not-found-page-Dkdu-YsI.js`는 서버 요청 없이 응답됐고(navigation 뒤 서버 요청 `[]`), chromium `responseStatus` 200이다. entry는 A의 `index-DHUP7IEW.js` 그대로였다(reload 없음) | +| 06-R10이 보인 함정 | 워커 변이에서 추가 test의 화면 단언은 **통과**했다. 실패는 fixture 줄에서만 나왔다. chunk 복구가 페이지를 reload해 B를 부팅하고 B의 화면을 그렸기 때문이다. navigation 뒤 서버 요청은 `/review06-missing-route`, `/config.json`, `/release-manifest.json`이었다. entry도 B의 `index-HHScv93_.js`로 바뀌었다. 화면 단언만 두는 test는 이 결함을 못 잡는다 | +| 발생 조건 | 앞으로 워커의 fallback이나 route 쪽 변경이 `fetch()` 경로는 살리고 "옛 탭이 지워진 route를 연다"는 실제 경로만 깨는 경우. 지금 코드에서는 `classifyFetch`가 요청 종류(destination)를 보지 않는다(`service-worker-static-assets.ts:45-59`). 그래서 두 경로가 같은 분기를 탄다 | +| 영향 | 옛 탭 회복(지난 라운드의 확인된 강점)을 spec은 바이트 단위로만 확인한다. 깨지면 사용자는 reload를 겪고 탭의 화면 상태를 잃는다(06-R10에서 본 동작) | +| 심각도·우선순위 | Low · P3. 지금 결함은 없고 test 공백이다 | +| 통제·증거 | "옛 탭은 새 워커 아래에서 지워진 route를 reload 없이 연다" 규칙: 목표 M3 / 확인 M2(fallback 코드)+`fetch()` 단언 · E3(06-R9, 06-R10, 두 엔진/한 엔진) | +| 확실성과 남은 가정 | 실제 경로 동작과 허용의 효과는 실행으로 확인했다. 06-R10은 chromium 한 엔진, 워커 변이 한 종류다 | +| 결정의 근거 | 11-09 조치는 제어 아래 script에 표시를 포기했다. 표시를 붙이면 워커가 sha256으로 검사하는 바이트가 바뀌기 때문이다(`preload-use.ts:25-28`). 그 선택은 맞다. 리뷰어의 추론: 표시 대신 "reload 없이 route가 그려진다"를 단언하면 같은 목적을 이룬다 | +| 이해 비용 | spec을 읽는 사람은 `fetch()` 단언을 "옛 탭이 route를 연다"로 읽기 쉽다. 실제로는 바이트만 본다 | +| 최소 개선 방향 | update spec에 test 1건을 더한다. B가 제어하는 A 탭에서 client navigation으로 지워진 route를 연다. 단언은 세 가지다: 화면이 그려진다, entry script가 A의 것 그대로다(reload 없음), 허용 밖 실패 줄이 없다(strict fixture). 06-R9의 추가 test에 entry 단언 한 줄을 더해 옮기면 된다 | +| 대안 비교 | (a) 위 test 추가 (b) fixture가 워커 쪽 응답을 추적(Playwright의 워커 network 이벤트는 Chromium 전용) (c) 현상 유지. (a)가 엔진에 무관하고 작다 | +| 단순화의 보존 조건 | 허용 패턴은 `/assets/*.js`와 `service-worker` 종류만 받는다. 제어 전 preload 검사는 유지한다 | +| 비용·부작용 | test 1건, 엔진마다 약 7초(06-R9: 6.5~6.8초) | +| 재검토 조건 | fixture가 워커 제어 아래 실행을 볼 수 있게 되면(예: 엔진 공통 워커 network 이벤트) 허용을 지운다 | +| 완료 기준 | update spec이 제어 아래 route import를 reload 없이 단언한다. 06-R10과 같은 워커 변이에서 그 test가 실패한다 | +| 검증 방법 | 06-R9·06-R10과 같은 실행 | +| 담당·기한·상태 | 템플릿 소유자(11 영역 fixture와 공동) · 미정 · 열림 | +| 재검증 결과 | 해당 없음 | + +**Firefox 격리 판단(발견 아님).** 격리는 3곳이다(`service-worker-update.spec.ts:181`, `:223`, `:244`, `service-worker-recovery.spec.ts:84-88`). 근거는 "Playwright Firefox는 워커가 페이지를 제어하지 못한다"다. **06-R11**은 세 skip을 지우고 firefox로 두 spec을 돌렸다. 3건 통과, 3건 실패다. 실패는 모두 제어가 없을 때의 모양이다. "announces …"와 "serves A's removed chunk …"는 `requestActivation()`이 `NO_WAITING_WORKER`였다. B가 waiting 없이 스스로 활성화됐다는 뜻이고, 주석(`:174-180`)이 적은 그대로다. recovery는 `blocked` 대신 `loaded`였다. 망가진 워커 A가 페이지를 제어하지 않았다는 뜻이다. recovery spec은 strict fixture의 `page.route`를 쓰지 않으므로(`service-worker-recovery.spec.ts:91-94`), 원인은 fixture가 아니다. 격리는 아직 필요하다. install 2 test는 Firefox에서도 돈다. 만료일(2027-03-31)은 Playwright 버전(`package.json:170` `1.62.0`)을 올릴 때 다시 볼 날짜로 적당하다. + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 통제는 "목표 / 확인"이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 적용 | M2 / M2 | E1·E2 | P. registry 경로 정규화 구멍이 고쳐졌다(1103/06-02). 사전 캐시 수집이 루트 파일을 해시로 오인한다(06-01) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E1·E2 | O. worker·page realm을 tsconfig로 나눈다. `check:types:service-worker`가 통과한다(오케스트레이터 `check:types` 0). 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`) | +| 3 | 변경 용이성 | 적용 | M1 / M1 | E1 | P. SW 켜기는 제품 소유 파일 한 줄이 됐다(`product-capabilities.ts:34`). 활성화 UI·observe 연결은 템플릿 composition을 고쳐야 한다(0925/06-05) | +| 4 | 인지 부하 | 적용 | - | E1 | P. 쓰지 않는 kind·상수가 남았다(1101/06-03). lifecycle 736줄, page controller 642줄, subscription adapter 1,203줄 | +| 5 | 위험 가시성 | 적용 | M1 / M1 | E1 | P. 운영 문서가 검사 범위·waiting 캐시 누적·제거 유지 기간을 맞게 적는다(1103/06-01, 06-04, 0929/06-06). 레시피 문서의 "사전 캐시는 `assets/`뿐"이 코드와 다르다(06-01) | +| 6 | 실패 성숙도 | 적용 | M2 / M2 | E1·E2 | P. install 거절 11종을 구분한다. 거절 이유는 페이지에 오지 않는다 | +| 7 | 운영 성숙도 | 적용 | M2 / M1~M2 | E1 | P. 시작 실패만 `service-worker.start.failed`로 남는다. 업데이트 실패·`health()` 미연결(0925/06-05). probe PASS가 install 성공을 다 뜻하지는 않는다(06-02 ①) | +| 8 | 디버깅 가능성 | 적용 | M2 / M1 | E1·E2 | P. `observe` hook과 reason 코드가 조립되지 않는다. registry 거절 메시지가 어느 정의·이유인지 말하지 않는다(`notification-registry.ts:53`, 06-R1) | +| 9 | 유지보수 성숙도 | 적용 | M1 / M1 | E1 | P. 읽히지 않는 상수·kind(1101/06-03), `validateActiveFence` 두 벌(R2). 폐기 예정 옵션 `inlineDynamicImports`가 남았다(`vite.service-worker.config.ts:83`) | +| 10 | 테스트 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. 영역 단위 테스트(test:unit)와 SW e2e(FE-GATE-008 `test:e2e`, CI env)가 이 커밋에서 통과한다. 지난 수정의 변이 7건 중 6건을 단언이 잡고 1건(M3)은 시간 초과로 잡는다(06-R3~R8). live 호출 줄 변이는 생존한다(06-R2, 06-02). 제어 아래 route import test가 없다(06-03) | +| 11 | 데이터 성숙도 | 적용 | M2 / M2 | E1·E2 | O. 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 이를 테스트가 단언한다(`service-worker-runtime.test.ts:1084`, 06-R5 검출). 소유 캐시 이름은 exact 비교다. push fence에 계정 ID·endpoint가 없다 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | O. nonce 재사용과 요청받지 않은 drain 응답을 테스트가 잡는다(06-R6, 06-R7). 잔여: M3 검출이 drain 상한(30초) > test 상한(10초)에 기댄다 | +| 13 | 확장성 | 적용 | M2 / M2 | E1 | P. 256개·5 MiB 상한을 빌드가 막는다. waiting 기간 캐시 누적은 문서화만 했다(1103/06-04) | +| 14 | 성능 성숙도 | 적용 | M2 / M2 | E1 | P. 릴리스마다 사전 캐시 전체를 다시 받는다(1101/06-05) | +| 15 | 보안 성숙도 | 적용 | M3 / M3 | E2 | O. registry 경로가 앱 루트를 벗어나지 않고 되돌리면 테스트가 잡는다(06-R4). install fetch의 `credentials`·`redirect` 설정도 같다(06-R5). payload는 route intent만 고르고 클릭 URL은 same-origin이다 | +| 16 | 의존성 성숙도 | 적용 | - | E1 | P. 런타임 외부 패키지 없음. `rollupOptions`는 `rolldownOptions`로 바뀌었다. 안의 `inlineDynamicImports`는 폐기 예정 옵션 그대로다(`vite.service-worker.config.ts:79-85`) | +| 17 | API / Contract 성숙도 | 적용 | M2 / M2 | E1·E2 | P. registry `path` 계약을 이제 검사가 지킨다. 처리하지 않는 kind 3개를 받는다(1101/06-03). catalog의 오프라인 셸 약속이 없어졌다(0929/06-03) | +| 18 | 배포 성숙도 **(깊게)** | 적용 | M3 / M2~M3 | E1·E2·E3 | P. probe가 확장자별 MIME을 본다(1103/06-03). 옛 탭이 새 워커 아래에서 지워진 route를 연다(06-R9). 남은 것: 루트 파일 오인(06-01), redirect·워커 없는 빌드(06-02), 하위 경로 호스팅 게이트(13 영역 0929/13-06), `assets/` 하드코딩(0925/06-08). FE-GATE-019(release 단계)는 이번에 돌지 않았다 | +| 19 | 설정 성숙도 | 적용 | M3 / M3 | E1·E2 | P. 선택이 제품 소유 파일로 옮겨졌다. 빌드·호스팅 검사·e2e 도우미가 같은 투영을 읽는다(`installed-runtime-capabilities.ts:37-48`, `tests/e2e/support/service-worker-builds.ts:76`). 자산 디렉터리는 설정이 아니라 상수다(0925/06-08) | +| 20 | 개발자 경험 | 적용 | M1 / M1 | E1 | P. SW 켜기 체크리스트가 새 파일 위치를 적는다(`optional-adapter-recipes.md:128-153`). 활성화 UI·observe는 composition을 직접 고친다 | +| 21 | Guardrail 성숙도 **(깊게)** | 적용 | M3 / M3(일부) | E2·E3 | P. FE-GATE-020이 통과하고 realtime 제거 드릴 7 check가 모두 통과한다(오케스트레이터). 새 MIME probe가 있다. live 호출 줄 무검사·redirect 미검사(06-02). preload 허용은 워커 결함을 가리지 않는다(06-R10). 대신 제어 아래 preload 검사는 전부 꺼진다(06-R9, 06-03) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1·E3 | O. 구조적 facade로 워커 없이 테스트한다. 실제 브라우저 결과(06-R9·R10·R11)와 단위 테스트 가정이 어긋난 곳을 찾지 못했다 | +| 23 | 일관성 | 적용 | - | E1·E2 | P. "사전 캐시 = `assets/`" 규칙이 fallback·호스팅·probe·문서 네 곳에 있고 수집기만 다르다(06-01). `SYNC_WAKE_OBSERVED`만 버전을 숫자로 쓴다(R3) | +| 24 | 네이밍 / 의미 | 적용 | - | E1 | P. `retainedPreviousCaches`는 읽히지 않는다(R1). `HASHED_STATIC_ASSET_NAME`은 내용 해시를 뜻하는 이름인데 `apple-touch-icon.png`에 맞는다(06-01과 같은 결함, 따로 세지 않음) | +| 25 | 조직 확장성 | 적용 제외 | - | - | -. 1인 관리 전제(0.1) | +| 26 | Ownership 성숙도 | 적용 | M1 / M1 | E1 | P. 운영 문서가 코드 경로·검사 범위·유지 기간을 맞게 적는다. 레시피 문서 한 문장이 틀렸다(06-01) | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E3 | O. web-push·realtime을 지운 fixture에서 7 check가 모두 통과한다: typecheck·lint·architecture·test·build·optional-catalog·ci-contract(`realtime-runtime-removal.xml` 7/7, 오케스트레이터 FE-GATE-020, CI env). 지난 라운드 P(드릴 깨짐)에서 올라왔다 | +| 28 | 회복 가능성 **(깊게)** | 적용 | M3 / M2~M3 | E2·E3 | P. kill switch와 자기 해제 워커가 있다. 제거 단계 유지 기간이 문서에 있다(0929/06-06). 옛 탭은 새 워커 아래에서 지워진 route를 reload 없이 연다(06-R9). 그러나 이를 지키는 spec이 없다(06-03). `null` 릴리스 뒤 옛 워커를 걷어내는 장치는 여전히 없고 문서로 운영한다 | + +집계: 적용 27개 중 O 6(2, 11, 12, 15, 22, 27) · P 21 · X 0 · ? 0, 적용 제외 1. 지난 라운드 대비 12·15·27번이 P에서 O로 올라왔다. + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +| --- | --- | --- | +| 06-01 루트 아이콘의 실제 install 실패(CDN이 옛 내용을 줄 때) | 수집 결과만 실행으로 확인했다 | e2e 도우미 서버가 루트 아이콘을 다른 바이트로 주게 하고 첫 install 결과 확인 | +| live 모드 probe 전체(FE-GATE-019) | release 단계 게이트라 이번 실행에 없다. live 모드는 저장소 안에서 돌 수 없다. snapshot의 `hosting-headers.json`은 2026-07-27자다 | staging 호스트로 `HOSTING_BASE_URL` live probe | +| SW spec의 test별 CI env 결과 | FE-GATE-008 로그는 PASS 한 줄뿐이다. 06-R9는 local env다 | FE-GATE-008의 Playwright junit을 따로 보관 | +| 06-R10의 webkit 결과, 다른 워커 결함 종류 | 배치는 chromium 한 엔진, 변이 한 종류다 | 같은 변이를 webkit으로, MIME이 틀린 캐시 응답 변이 | +| Web Push end-to-end(실제 푸시 서비스, VAPID) | 푸시 서버 없음. `WEB_PUSH`는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 | +| 하위 경로(`/app/`) 브라우저 설치 재확인 | 지난 라운드 L1 이후 이 영역 SW 코드는 바뀌지 않았다. 이번에 다시 돌리지 않았다 | 지난 L1과 같은 실험 | +| 얼어 있는 탭이 Web Lock을 쥔 경우, A 워커 아래 B 부팅 지연 | 재현 환경 없음 | `Page.setWebLifecycleState(frozen)`, resource timing 비교 | + +## 6. 실행 기록 + +이 리뷰가 desktop lock에 넣은 `06-unit`, `06-e2e-sw`, `06-firefox-sw`는 19:55에 취소됐다. 실행되지 않았고 checkout을 건드리지 않았다(BRIEF-2). + +인용한 오케스트레이터 게이트(같은 커밋 `8a44226`): 1절 게이트 행. + +오케스트레이터 배치(2026-11-05 20:05~20:07, 부하 1.14~1.49, 항목마다 `8a44226`로 reset 후 실행, 11건 모두 restore clean). 요청 `scratchpad/r4/requests/06.md`, 패치 `06-R1.diff`~`06-R11.diff`(모두 `git apply --check` 통과), 로그 `scratchpad/r4/results/06/06-Rnn.log`. 변이를 넣은 실행의 무변이 대조는 게이트가 대신한다. 단위는 `gates/test_unit.log`, e2e는 `merge-48/FE-GATE-008.log`다. + +| ID | 명령 | 변이 | rc · 시간 | 결과 | +| --- | --- | --- | --- | --- | +| 06-R1 | `node scripts/run-vitest.ts run tests/unit/review06-r4-probe.test.ts` | 임시 test 파일 추가 | 0 · 0초 | 7건 통과. 루트 아이콘 3개 사전 캐시, probe는 `assets/` 2개만 요청, redirect 응답 `passed: true`, registry `/inbox`만 수락 | +| 06-R2 | `hosting-probe`·`service-worker-build-output` 단위 | live 호출 줄을 `void`로 | 0 · 4초 | 44건 통과 → **생존**(06-02) | +| 06-R3 | `hosting-probe` 단위 | `passed: true` | 1 · 1초 | 기대대로 2건 실패(CSS `text/plain`, 글꼴·404) | +| 06-R4 | `web-push-worker-runtime` 단위 | 정규화 비교 삭제 | 1 · 1초 | 기대대로 5건 실패(dot segment 5경로) | +| 06-R5 | `service-worker-runtime` 단위 | M1 | 1 · 6초 | 기대대로 1건 실패(fetch init 단언) | +| 06-R6 | 같음 | M3 | 1 · 16초 | 기대대로 1건 실패, `Test timed out in 10000ms` | +| 06-R7 | 같음 | M9 | 1 · 6초 | 기대대로 1건 실패(`expected true to be false`) | +| 06-R8 | 같음 | N8 | 1 · 6초 | 기대대로 1건 실패(`onUpdateWaiting` 1회 호출) | +| 06-R9 | `playwright test -c playwright.review06.config.ts --project=chromium --project=webkit tests/e2e/service-worker-update.spec.ts` | 임시 config, 옛 탭 test 추가, fixture 줄 출력 | 0 · 54초 | 12건 통과(52.7초). `ALLOWED` 158줄, `FAIL` 0줄. 옛 탭 test는 두 엔진 모두 reload 없이 not-found 화면 | +| 06-R10 | 같은 config, chromium, `--grep "removed chunk\|removed route chunk"` | R9 + 직전 캐시 응답 끊기(S1) | 1 · 24초 | 기대대로 2건 실패. 허용 밖 줄(console 404, `requestfailed`, dynamic import 실패)과 `status 404` 단언. 추가 test의 화면 단언은 reload 복구로 통과 | +| 06-R11 | 같은 config, firefox, update·recovery spec | Firefox skip 3개 제거 | 1 · 30초 | 3건 통과(install 2, build 1), 3건 실패(`NO_WAITING_WORKER` 2, `loaded` 1) → 격리 유지 | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +| --- | --- | --- | --- | --- | +| 06-01 | Low · P3 | 확인된 결함 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)도 해시 자산으로 넣는다 | `scripts/generate-service-worker-assets.ts:57-64`, `src/contracts/service-worker.ts:116` | +| 06-02 | Low · P3 | 구조적 위험 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지워도 테스트가 통과한다 | `scripts/lib/hosting-probe.ts:276-315`, `scripts/verify-hosting-headers.ts:119-120` | +| 06-03 | Low · P3 | 개선 제안 | SW 제어 아래 route import를 지키는 test가 없다. 11-09 허용으로 그 아래 preload 검사도 모두 꺼진다(허용이 워커 결함을 가리지는 않음) | `tests/e2e/service-worker-update.spec.ts:45-52`, `:267-276` | diff --git a/docs/reviews/2026-11-05-maturity-review/07-contracts.md b/docs/reviews/2026-11-05-maturity-review/07-contracts.md new file mode 100644 index 00000000..1da44b16 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/07-contracts.md @@ -0,0 +1,213 @@ +# 영역 07 — contracts (공유 어휘·외부 계약) + +> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/contracts/`(44파일, 9,183줄), `schemas/`, `config/contracts/`(6파일. 새 파일 `backend-contract-pin.json`, `backend-idempotency-answers.json`) +> 깊게 본 관점: 17, 21, 10, 15, 19 +> 렌즈: 1103/07-01(FE-REG-API가 wire 칸을 보는가), 07-02(CSRF·realtime snapshot 변이), 07-03, 07-04 남은 부분, 결정 D6(pin과 답 표가 백엔드 변경을 잡는가) +> 영역 판정(35.8): **조건부 사용 가능.** 외부 계약 조립기, FE-REG-API 투영, 쿠키 쓰기 CSRF 조립 검사, FE-REG-ENV 대조, 스키마 정책 대조는 그대로 써도 된다. 조건은 둘이다. (1) 짝 백엔드 checkout을 frontend 옆에 두고, 백엔드를 받을 때마다 `check:backend-contract-drift`를 돌린다. 게이트는 백엔드 변경을 보지 못한다(07-01). (2) 응답 스키마를 `.strict()`로 바꾸는 PR은 사람이 본다. 레지스트리가 behavior-change로만 적는다(07-02). + +ID 표기: 이 문서의 `07-NN`은 2026-11-05 라운드 ID다. 지난 라운드(2026-11-03)는 `1103/07-NN`, 그 전은 `1101/07-NN`, 2026-09-29 라운드는 `P-07-NN`(= `0929/07-NN`)이다. + +## 0. 결론 + +- **지난 라운드 영역 07 발견 10건 중 9건이 고쳐졌다.** 1103/07-01·02·03·05, 1101/07-05·07, P-07-05·06·07이다. 07-02에 합친 10-03·04-03도 같이 닫혔다. 남은 것은 1103/07-04의 한 부분(부팅 오류에 키 이름이 없다)뿐이다. Low다. +- **1103/07-01이 닫혔다.** FE-REG-API 행이 status 목록·상한·마감·재시도 예산·traffic·command 칸·검증 생략을 담는다(`src/contracts/api-operations.ts:52-61, 88-112`). 지난 라운드 X2(생성 API `[200, 201]`→`[201]`)가 이제 `acceptedStatuses:allowed-value-removed` breaking으로 실패한다. X4·X5·R1도 실패한다. X3·X6은 behavior-change로 스냅샷에 남는다(6절 07-a). 완료 기준을 모두 채웠다. +- **1103/07-02가 닫혔다.** 지난 라운드에 살아남은 변이 M2·M3·M9·M9b와, 이번에 더한 H19(`x-csrf-token` 허용 삭제)·S2(retry 조건 삭제)가 모두 죽는다(6절 07-b). +- **D6(pin + 답 표)은 답 표와 프론트 판정의 어긋남은 잡는다. 백엔드 변경은 게이트가 잡지 못한다(07-01, Low).** 답 표 한 칸을 뒤집거나(D6a), 행을 더하거나 빼거나(D6d·D6e2), 프론트 표 행을 지우면(D6e) `backend-contract-pin.test.ts`가 실패한다. 그러나 이 테스트는 프론트 파일만 읽는다. 백엔드 문서의 §2 행을 바꾼 가짜 백엔드에서 drift 스크립트는 rc=1로 알렸지만, 같은 상태에서 테스트는 통과했다(D6g). 답 표 JSON이 pin한 백엔드 문서와 같은지는 아무 검사도 보지 않는다. drift 스크립트는 desktop(게이트를 도는 곳)에서 rc=2 "비교 불가"이고(D6f), worktree에서는 "skipped"로 rc=0이다. 매뉴얼에 이 스크립트가 없다. +- **응답 스키마를 strict로 바꾸는 변경은 behavior-change다(07-02, Low, 개선 제안).** 1103/07-03 수정으로 행과 검증기는 묶였다. 그러나 둘을 같이 바꾸면 FE-REG-SCHEMA의 `unknownFieldPolicy`는 breaking 칸이 아니라 통과한다(`config/contracts/registry-governance.json:288`). 배치 07-R1: `check:registries` PASS `compatibility=behavior-change`, 관련 vitest 25파일 180건 통과. +- **이번 수정들이 검사를 약하게 만든 곳은 찾지 못했다.** `git diff e40684b..8a44226`의 영역 테스트에서 지운 단언은 없고, 바뀐 것은 공용 함수로 옮긴 리팩터링이다. governance의 `defaultValue` 타입에 `object`가 더해진 것은 스키마 기본값을 그대로 적기 위해서다. +- High 이상 발견은 없다. 이번 라운드 새 발견 2건(Low 2). P1도 없다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 07 | +| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree는 읽기만 했다. 실행은 desktop checkout(`~/workspace/clean-architecture-frontend-template`, 같은 커밋)에서 helper로 2회(07-a, 07-b). 둘 다 `restored: clean at 8a442262`. 2026-11-05 19:46~19:47, 잠금 대기 약 745초, load 8.5~10.6 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 템플릿과 함께 빨리 출시하는 것이 목표 | +| 필수 요구와 규모·운영 목표 | 합의된 규모·운영 목표 없음. 짝 백엔드 응답은 백엔드 `45d2a478`의 `docs/web/http-contract.md`(노트북 checkout, 읽기만)를 기준으로 했다 | +| 읽은 코드·구성 범위 | 줄 단위: `api-operations.ts` 전체, `external-contract-runtime.ts:450-670, 800-845, 1020-1035`, `env.ts` 전체, `product-contracts.ts`, `schema-registry.ts:1-60`, `realtime-streams.ts:455-475`, `errors.ts:115-145`, `unvalidated-payload.ts`, `config/contracts/*` 6파일, `scripts/lib/registry-compatibility.ts` 전체, `scripts/check-registries.ts:680-773`, `scripts/check-backend-contract-drift.ts` 전체. `git diff e40684b..8a44226 -- src/contracts config/contracts schemas` 전체. 함께 읽은 곳: `src/adapters/http/backend-envelope.ts:120-360`, `src/bootstrap/load-runtime-config.ts:100-135`, 참조 기능 `contracts/` 3파일, `scripts/create-feature-write-slice.ts:290-300`, 테스트 `api-operation-rows`, `rest-profile-contract`, `realtime-stream-registry:220-330`, `external-contract-runtime:110-360`, `schema-metadata-policy`, `env-registry-coverage`, `backend-contract-pin`, `second-api-feature-registries`의 diff | +| 읽은 문서(주장) | `docs/manual/01-add-a-feature.md:530-560`, `docs/manual/03-outside-feature-folder.md:106-115`, `docs/architecture/backend-api-and-server-state-contract.md:160-180`, `docs/architecture/starter-experience.md:160-175`, `docs/contracts/compatibility.md:1-60`, `config/ci/ungated-scripts.json:4-7`, 커밋 `08ed0a08`·`a94006b9`·`5bee9abe`·`3b40f736`·`9800bc89`·`e4caafda`·`ba2b4f4c` 본문, 지난 라운드 07 문서와 README 12~14절. 백엔드 `45d2a478:docs/web/http-contract.md` §2(81-135줄)·§4(184-200줄) | +| 수행한 테스트·실험 | 6절. 07-a: `check:registries` 변이 7종 + `check:architecture` 변이 1종(각각 변이 없는 대조 포함). 07-b: vitest 변이 17종(대조 1회, 6파일 106건 통과)과 drift 스크립트 2회. 게이트는 다시 돌리지 않았다. 오케스트레이터 결과(local env, `desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`·`check:types`·`lint`·`test:unit`(194파일 2,883건)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory` rc=0, `verify:documentation` rc=1(desktop 옆 백엔드 checkout에 문서가 없다, 07-01 근거에 인용). merge-48(CI env): FE-GATE-001~009, 020 rc=0. `check-registries`를 품은 FE-GATE-010은 이 문서를 쓸 때 돌고 있었다 | +| 확인하지 못한 범위·이유 | 07-c(응답 스키마와 행을 같이 strict로)는 잠금 대기 중 취소됐다. 오케스트레이터 배치 07-R1로 돌렸다(20:11, restore clean). `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 이번 diff가 없어 읽지 않았다. 실제 짝 백엔드를 띄워 답을 받아 보지는 않았다. FE-GATE-010·012·013의 결과는 아직 없었다 | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 07 문서의 실험 X2·X2b·X3·X4·X5·X6·X8·R1·Z1·E-4와 변이 M2·M3·M9·M9b를 같은 이름으로 이 커밋에서 다시 돌렸다. 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) | +|---|---|---|---| +| 1103/07-01 | V2 행 삭제 뒤 FE-REG-API가 status 목록·상한·마감·재시도 예산·`commandEffect`를 보지 않고, `problemSchema`는 반만 잠겼다 | **고쳐짐** | 투영이 함수 밖 descriptor 값을 모두 담는다(`src/contracts/api-operations.ts:52-61, 88-112`). governance가 새 칸을 필수 칸으로 두고(`registry-governance.json:150-163`), `problemSchema`·`unvalidated`를 breaking 칸에 넣고(`:242-255`), `problemSchema`가 FE-REG-SCHEMA를 참조한다(`:232-236`). 읽기는 `SAFE`·`IDEMPOTENT`만 조립된다(`external-contract-runtime.ts:533-543`). 실험(6절 07-a): X2·X2b `breaking change missing evidence: FE-REG-API:CREATE_REFERENCE_RESOURCE:acceptedStatuses:allowed-value-removed`로 실패. X3+X6 PASS `compatibility=behavior-change`, `responseByteLimit 32768 -> 8388608`, `totalDeadlineMs 10000 -> 60000` 기록. X4 `problemSchema references unknown FE-REG-SCHEMA.schemaId=WhateverProblem` 3건 + breaking 3건으로 실패. X5 `unvalidated:field-changed` breaking으로 실패. R1·R1b `GET is a read; its retrySemantics is SAFE or IDEMPOTENT, not KEYED/NEVER`로 실패. 매뉴얼이 breaking과 behavior-change를 나눠 적고, 행에 없는 함수(`classifyProblem`·`classifyStatus`·`projectRequest`)를 "못 잡음"에 적는다(`docs/manual/01-add-a-feature.md:539-541, 555`). 완료 기준(X2·X4·R1 실패, X3·X6 기록, X5 breaking)을 모두 채웠다 | +| 1103/07-02 (= 10-03, 04-03) | CSRF·realtime snapshot 검사가 한 사례씩만 테스트된다 | **고쳐짐** | CSRF는 POST·PUT·PATCH·DELETE마다 CSRF 없는 프로필과 `x-tenant-context`만 요구하는 프로필을 거절하고, 두 CSRF 헤더를 각각 받는지 본다(`tests/unit/rest-profile-contract.test.ts:110-138`). realtime은 6 method × 4 retrySemantics 표를 두 복구 모드로 돈다(`tests/unit/realtime/realtime-stream-registry.test.ts:226-320`). 변이(6절 07-b): M2 3건 실패, M3 4건, H19 4건, M9 10건, M9b 22건, S2 2건. 모두 죽었다. 검사 코드는 그대로다(`external-contract-runtime.ts:585-598`, `realtime-streams.ts:457-474`) | +| 1103/07-03 | FE-REG-SCHEMA의 `unknownFieldPolicy`·`direction`이 검증기와 묶이지 않은 손 사본이다 | **고쳐짐** | 설치된 HTTP descriptor의 입력·응답·실패 검증기를 행과 대조한다. 방향, 쓰인 자리의 boundary, 모르는 키 탐침으로 본 정책을 비교한다(`tests/unit/schema-metadata-policy.test.ts:127-165`). X8(응답 DTO `.strip()`→`.strict()`, 행은 그대로): `row STRIP_UNKNOWN, validator REJECT_UNKNOWN` 3건으로 실패(07-b). 완료 기준을 채웠다. 남은 것: 탐침은 첫 객체 단계만 본다(테스트 주석 `:19-23`, 커밋 `5bee9abe`이 한계로 적음). 행과 검증기를 같이 바꾸는 경우는 새 발견 07-02로 적었다 | +| 1103/07-04 | 제품 설정 키의 금지 이름 검사가 부팅 때만 돈다 | **일부** · Low · P3 | `test:unit`이 스키마 키와 FE-REG-ENV runtime 키 전부를 `assertSafeConfigNames`로 검사한다(`tests/unit/env-registry-coverage.test.ts:70-83`). E4(제품 키 `PRODUCT_COOKIE_NOTICE`)가 `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE`로 실패한다(07-b). 매뉴얼에 규칙이 있다(`docs/manual/03-outside-feature-folder.md:113`). **남은 것:** 부팅 오류 `CONFIG_SECRET_NAME_REJECTED`는 여전히 `buildId`만 싣고 키 이름을 버린다(`src/bootstrap/load-runtime-config.ts:118-124`). 같은 파일의 스키마 실패는 키 이름을 싣는다(`:134-135` 주석 "Key names tell an operator what to fix"). 기본값에 없고 값으로만 생기는 중첩 키는 여전히 부팅에서만 걸린다(커밋 `9800bc89` 한계) | +| 1103/07-05 (→ 09-10) | `starter-experience.md`가 지워진 V2 모양으로 `FeatureRuntime`을 설명한다 | **고쳐짐** | 문장이 `schemas`·adapter 기여·contract 기여로 바뀌었다(`docs/architecture/starter-experience.md:166-171`). 실제 타입과 같다(`src/features/feature-module.ts:52-66`). `runtime schemas, mappers` grep 0건. 대표 발견은 영역 09의 09-10이다 | +| 1101/07-05 | 오류 어휘 둘과 두 "retry"의 관계가 타입 옆에 없다 | **고쳐짐** | `AppFailure` 위에 `AppError`와의 관계와 재시도 규칙이 있고, `retryable` 칸에 "src에서 읽는 곳 없음"과 `action: "retry"`와의 차이가 있다(`src/contracts/errors.ts:121-145`). `src`의 `.retryable` 읽기는 upload·realtime·파일 결과 타입의 것뿐이다(git grep). `AppFailure.retryable`을 읽는 곳은 찾지 못했다 | +| 1101/07-07 | `commandRecovery`를 실행기가 읽지 않고 수습 책임이 타입 옆에 없다 | **고쳐짐** | 타입 위 주석이 "실행기는 읽지 않는다, 기능 gateway가 정한다"고 적는다(`external-contract-runtime.ts:130-138`). FE-REG-API 행이 이 값을 기록한다(`api-operations.ts:109-112`) | +| P-07-05 | FE-REG-ENV runtime 행이 zod 스키마와 다르다 | **고쳐짐** | 행 값 5곳이 스키마와 같아졌다(`src/contracts/env.ts:59-80`). 테스트가 두 방향(스키마→행, 행→스키마)과 `required`·`defaultValue`를 대조한다(`tests/unit/env-registry-coverage.test.ts:33-63`). 오케스트레이터 `test:unit` rc=0에서 4건 통과(`gates/test_unit.log`) | +| P-07-06 | zod facade 규칙이 `"zod"`만 막는다 | **고쳐짐** | 규칙 경로가 `^zod(/|$)`다(`.dependency-cruiser.json:60-68`). Z1: 변이 없이 `check:architecture` rc=0, 참조 스키마의 import를 `"zod/v4"`로 바꾸면 `Architecture violation [zod-is-reached-through-contracts-zod]` rc=1(07-a) | +| P-07-07 | CHANGELOG [계약] 행이 레지스트리 분류기를 잘못 가리킨다 | **고쳐짐** | 행이 "설정 스키마 호환성 분류기(`classifyObjectSchemaChange`)"라 적고 레지스트리 분류기와 다르다고 적는다(`CHANGELOG.md:310`). README 14.4가 적었듯 지난 판정은 이름과 둘째 경로만 맞았다 | + +틀린 발견으로 판정한 것은 없다. + +## 3. 이번 발견 (36.3) + +새 발견 2건. 심각도 Low 2. 우선순위 P3 2. 성격 구조적 위험 1, 개선 제안 1. High 이상과 P1은 없다. 남은 지난 발견(1103/07-04 일부, Low·P3)은 2절에 있다. + +### 07-01 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 스크립트만 알린다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (검출 경로를 실행으로 확인. 실제 백엔드 변경으로 생긴 피해는 미확인) | +| 관련 관점 | 17, 21, 10, 20, 26 | +| 근거 | D6은 세 조각이다. **(1) pin**(`config/contracts/backend-contract-pin.json:1-19`): 백엔드 커밋 `45d2a478`, 대조한 절 `["1", "2", "4"]`(`:7`). **(2) 답 표 테스트**: `tests/unit/backend-contract-pin.test.ts`는 pin과 답 표 JSON 두 파일만 읽는다(`:76, 79`). 두 파일의 커밋이 같은지(`:91-98`), 답마다 프론트 판정이 표와 같은지(`:108-121`), 프론트 표의 행이 답 표에 있는지(`:123-140`)를 본다. **(3) drift 스크립트**: `scripts/check-backend-contract-drift.ts`는 게이트 밖이다(`config/ci/ungated-scripts.json:5-6`). 옆 디렉터리 `../clean-architecture-backend-template`(`:30`)에서 pin 커밋과 HEAD 사이에 `http-contract.md` 글자가 바뀌었는지만 본다(`:60`). **실행(6절 07-b):** 답 표의 한 칸 뒤집기(D6a), pin 커밋만 바꾸기(D6b), 답 표에 새 답 더하기(D6d), 프론트 표 행 지우기(D6e), 답 표 행 지우기(D6e2)는 모두 테스트가 실패한다. pin과 답 표의 커밋을 함께 `c508b1ba`로 바꾸면 통과한다(D6c). 가짜 백엔드 repo에서 §2의 `IDEMPOTENCY_COMPLETION_UNKNOWN` status를 503→500으로 바꾼 커밋을 HEAD로 두자, drift 스크립트는 바뀐 표 줄을 찍고 rc=1이었다. 같은 pin 상태에서 테스트는 10건 모두 통과했다(D6g). **빈 곳 셋.** (a) 답 표 JSON이 pin한 커밋의 백엔드 문서와 같은지는 테스트도 스크립트도 보지 않는다. 테스트는 사본만, 스크립트는 문서끼리만 비교한다. 지금 사본은 §2 표 6행과 §4 `REQUEST_TIMEOUT`이 백엔드 `45d2a478:docs/web/http-contract.md:89-91, 111-113, 190`과 같다(리뷰어가 대조). §4의 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`(`:192-193`)은 옮기지 않았다. 프론트 계약 문서는 "§2 표와 §4 `REQUEST_TIMEOUT`"만 옮겼다고 적는다(`docs/architecture/backend-api-and-server-state-contract.md:170`). pin의 `sectionsCompared`는 §4 전체처럼 읽힌다. (b) drift 스크립트가 실제로 돌 수 있는 곳이 좁다. desktop(게이트를 도는 곳)의 옆 백엔드 checkout은 `ef947e5`(2026-09-16)라 pin 커밋이 없어 rc=2 "cannot compare"다(D6f). 같은 원인으로 오케스트레이터의 local `verify:documentation`도 rc=1이다(`gates/verify_documentation.log`, 영역 14·12 몫이라 여기서 세지 않음). 기본 경로가 cwd 기준이라 `.claude/worktrees/<이름>`에서 돌리면 옆 디렉터리가 없어 "skipped"로 rc=0이다(`:40-45`). (c) `docs/manual/`에 이 스크립트가 없다(git grep 0건). 실행 시점은 `ungated-scripts.json`의 "Run this before moving the pin"과 아키텍처 문서(`:175-177`)에만 있다. 백엔드가 움직이고 pin은 그대로인 경우를 누가 언제 보는지는 적혀 있지 않다 | +| 발생 조건 | 짝 백엔드가 §2·§4의 답(status, 쓰기 전 거절 여부, 같은 키 재전송)을 바꾸고, 프론트는 그 백엔드를 받았지만 drift 스크립트를 돌리지 않았을 때. 또는 pin을 올리면서 답 표를 잘못 옮겼을 때 | +| 영향 | 프론트 Envelope 판정이 실제 백엔드와 달라진다. 위험한 방향은 지금 `NOT_APPLIED`인 code(`src/adapters/http/backend-envelope.ts:152-172`)가 백엔드에서 "적용됐을 수 있음"으로 바뀌는 경우다. 그러면 다음 저장이 새 키를 써 같은 작업이 두 번 적용될 수 있다(추론, 실행 안 함). D6g 같은 status 변경은 표의 status+code 짝이 안 맞아 기능 분류기로 넘어간다(`backend-envelope.ts:340-351`). 생성 뼈대 분류기는 늘 `MAYBE_APPLIED`라(`scripts/create-feature-write-slice.ts:298`) 지금 템플릿에서는 결과 불명으로 끝난다. 이 설정은 모든 다운스트림에 복제된다 | +| 심각도·우선순위 | Low · P3 — 지금 사본은 맞고, 모르는 답은 템플릿 분류기에서 결과 불명으로 끝난다. 피해는 백엔드 변경과 사람 절차 누락이 겹칠 때만 난다. 다만 지난 라운드 중 백엔드가 세 번 움직였고(README 14.3), 이 경로가 게이트에서 보이지 않으니 P3 안에서 먼저 한다 | +| 통제·증거 | 목표 M3(pin한 백엔드 문서와 사본의 어긋남, pin 뒤 백엔드 변경을 기계가 알림) / 확인: 사본↔프론트 표 M3, 사본↔pin 문서 M0, pin 뒤 백엔드 변경 M1(게이트 밖 스크립트, 돌 때만 M3) · E2(D6a~D6g) | +| 확실성과 남은 가정 | 실행으로 확인했다. D6g는 진짜 백엔드가 아니라 백엔드 문서 한 파일로 만든 가짜 repo다. 다운스트림 두 repo가 백엔드 checkout을 어디에 두는지는 보지 않았다 | +| 결정의 근거 | 기록된 결정: D6 "(1) pin 파일 + (2) 답 표 JSON 대조 테스트 + 로컬 drift 검사"(README 14.2). 이유는 CI가 frontend만 checkout한다는 것이다(`ungated-scripts.json:6`). 리뷰어 판단: 게이트 밖에 두는 이유는 타당하다. 빠진 것은 사본과 pin 문서를 잇는 고리 하나와, 스크립트가 "비교 못 함"을 통과처럼 끝내는 경우다 | +| 이해 비용 | 백엔드를 올리는 사람은 아키텍처 문서 4.1절을 찾아 읽어야 스크립트와 세 파일을 함께 고쳐야 한다는 것을 안다 | +| 최소 개선 방향 | (1) drift 스크립트가 pin 커밋의 백엔드 문서에서 §2·§4 표 행(code·status)을 읽어 답 표 JSON과 비교한다. 옮기지 않는 행(`RATE_LIMIT_*`)은 pin에 이유와 함께 적는다. (2) 옆 checkout이 없으면 "skipped"를 rc=0이 아닌 다른 값으로 끝내거나, `--backend`를 필수로 한다. (3) 매뉴얼 04(짝 백엔드)나 01의 Envelope 단계에 "백엔드를 받으면 `check:backend-contract-drift --backend `"를 한 줄 적는다 | +| 대안 비교 | (A) 현 상태: 비용 0. 사본 오타와 백엔드 이동을 사람이 본다. (B) 위 (1)~(3): 표 파서 수십 줄, 문서 한 줄. 게이트 밖이라 CI 비용은 없다. (C) 백엔드 문서 사본(또는 다이제스트)을 프론트에 두고 테스트가 사본에서 표를 읽음: 게이트 안에서 사본↔JSON을 본다. 대신 백엔드 문서를 프론트에 복사하는 사본이 하나 더 생긴다. (D) 계약 패키지(`@org-contracts/*`)에 답 표를 넣어 두 repo가 같은 파일을 읽음: 가장 단단하지만 패키지 배포 경로가 아직 없다 | +| 단순화의 보존 조건 | 답 표 테스트의 양방향 대조(D6a·D6d·D6e·D6e2 실패)는 그대로 둔다. CI는 frontend만 checkout한다는 전제를 바꾸지 않는다 | +| 비용·부작용 | (B) 백엔드 문서 표 형식이 바뀌면 파서도 고친다. 백엔드 §5("바꿀 때")에 프론트 파서를 적어야 할 수 있다 | +| 재검토 조건 | 계약 패키지가 생기면 (D)로 옮기고 pin과 drift 스크립트를 지운다. 백엔드 표가 기계 형식(YAML 등)으로 따로 나오면 (1)은 그 파일을 읽는다 | +| 완료 기준 | D6g처럼 pin과 다른 행을 가진 답 표, 또는 pin 문서에만 있는 행을 drift 스크립트가 rc≠0으로 알린다. 옆 checkout이 없을 때 rc=0으로 끝나지 않는다. 매뉴얼에서 스크립트를 찾을 수 있다 | +| 검증 방법 | D6g 재실행과, 답 표 JSON의 status 하나를 pin 문서와 다르게 바꾼 경우 | +| 담당·기한·상태 | 미정 · 미정 · 신규 (D6 이후 생긴 경로. 영역 12의 12-06 후속과 겹치면 하나로 센다) | +| 재검증 결과 | 미실시 | + +### 07-02 응답 스키마를 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 (배치 07-R1로 실행 확인) | +| 관련 관점 | 17, 21, 23 | +| 근거 | FE-REG-SCHEMA의 breaking 칸은 `schemaId`·`boundary`·`runtime`뿐이다(`config/contracts/registry-governance.json:288`). `unknownFieldPolicy`·`direction`은 governance에 이름도 없다. 분류기는 breaking 칸이 아닌 값 변경을 `behavior-change`로 본다(`scripts/lib/registry-compatibility.ts:346-351`). 기준선에 응답 행의 `STRIP_UNKNOWN`이 있다(`config/contracts/registry-baseline.json:618, 627`). 1103/07-03 수정 테스트는 행과 검증기가 같은지만 본다(`tests/unit/schema-metadata-policy.test.ts:154-165`). 그래서 응답 DTO를 `.strict()`로 바꾸고 행을 `REJECT_UNKNOWN`으로 같이 고치면 모든 검사가 통과한다. **07-R1(배치):** 그 패치에서 `check:registries`가 `11 registries PASS; compatibility=behavior-change`로 통과했다. 변경은 `FE-REG-SCHEMA:ReferenceResourceListPayload:unknownFieldPolicy:field-changed behavior-change`와 `ReferenceResourcePayload`의 같은 줄 2건이다. `tests/unit/schema-metadata-policy.test.ts`, `tests/features/reference-feature`, `tests/contract`, `tests/runtime-schema` 25파일 180건이 모두 통과했다. 응답에 모르는 필드를 싣는 테스트가 없어 아무 테스트도 잡지 않았다. 같은 경계에서 FE-REG-API는 `acceptedStatuses` 축소를 breaking으로 본다(1103/07-01 수정). 호환 문서는 REJECT_UNKNOWN 경계에서 필드 추가가 breaking이라 적고(`docs/contracts/compatibility.md:18-19`), 참조 응답 DTO를 additive라 적는다(`:28`). 경계를 strict로 바꾸면 이 표의 칸이 바뀌지만 그 변경을 잡는 검사는 없다 | +| 발생 조건 | 기능 작성자가 응답 DTO를 `.strict()`로 바꾸고, 정책 테스트가 실패하자 메타데이터 행도 `REJECT_UNKNOWN`으로 고칠 때 | +| 영향 | 백엔드가 응답에 필드 하나를 더할 때마다 그 API가 `SCHEMA_MISMATCH`로 실패한다. 리뷰어는 스냅샷 diff에서 behavior-change 한 줄로만 본다. 런타임 피해는 백엔드가 필드를 더한 뒤에 생긴다 | +| 심각도·우선순위 | Low · P3 — 지금 템플릿 코드는 맞다. 바뀌는 경우도 스냅샷에 기록은 남는다. 등급만 FE-REG-API와 맞지 않는다 | +| 통제·증거 | 목표 M3(응답 경계를 좁히는 변경은 breaking) / 확인 M2(기록만, behavior-change) · E2(07-R1) | +| 확실성과 남은 가정 | 실행으로 확인했다. test:component·integration·e2e는 이 패치로 돌리지 않았다. MSW 응답이 DTO 키만 보내면 그쪽도 통과할 것이다(추론) | +| 결정의 근거 | 기록된 결정: `5bee9abe`·`3b40f736`은 행과 검증기를 묶었고 등급은 바꾸지 않았다. 리뷰어 판단: 응답 방향의 `STRIP_UNKNOWN`→`REJECT_UNKNOWN`만 breaking이면 충분하다. 요청 방향이나 반대 방향(REJECT→STRIP)은 읽는 쪽을 넓히는 변경이라 behavior-change가 맞다 | +| 이해 비용 | 적음. 기능 작성자는 FE-REG-API와 FE-REG-SCHEMA의 등급 규칙이 다르다는 것을 governance JSON을 읽어야 안다 | +| 최소 개선 방향 | (1) governance FE-REG-SCHEMA에 `unknownFieldPolicy`·`direction`을 `fieldTypes`로 선언한다. (2) 분류기에 "RESPONSE 행의 `STRIP_UNKNOWN`→`REJECT_UNKNOWN`은 breaking" 규칙 하나를 더하거나, 더 단순하게 `unknownFieldPolicy`를 breaking 칸에 넣는다(완화 쪽도 증거가 필요해지지만 드문 변경이다) | +| 대안 비교 | (A) 현 상태: 기록만. (B) `unknownFieldPolicy`를 breaking 칸에: governance 한 줄과 기준선 재승인 1회. 완화도 증거를 요구한다. (C) 방향 규칙을 분류기에: 정확하지만 레지스트리별 특수 규칙이 생긴다 | +| 단순화의 보존 조건 | 적용 제외 — 등급 규칙 추가다 | +| 비용·부작용 | governance 계약 변경이라 `contract-field-changed` breaking으로 기준선 재승인 1회. 다운스트림은 동기화 때 1회 | +| 재검토 조건 | 응답 검증기가 정책을 스스로 보고하게 되면(생성 검증기 등) 행 칸 대신 검증기 정보를 레지스트리에 싣는다 | +| 완료 기준 | 07-R1 변이에서 `check:registries`가 `FE-REG-SCHEMA:...:unknownFieldPolicy` breaking 증거 누락으로 실패한다 | +| 검증 방법 | 07-R1 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 (1103/07-03 수정 뒤 남은 범위) | +| 재검증 결과 | 미실시 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | 적용. 조립기가 계약 규칙의 유일한 입구다 | M4 / M4 | E2(07-b MR1·MW1·MF1, 07-a R1) | O — 읽기 `SAFE`·`IDEMPOTENT`, 쓰기 `SAFE` 금지, 쓰기 전 거절 목록, 기여당 wire 틀 하나가 조립에서 막히고 변이가 모두 죽는다. 함수(`classifyProblem` 등)의 내용은 조립이 보지 않는다(매뉴얼에 적힘) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2(`check:architecture` rc=0, 오케스트레이터) | O — 계약은 application·presentation·bootstrap을 import하지 않는다. 이번 diff의 새 import는 `platform/traffic` 타입 하나다(`api-operations.ts:11`) | +| **3** | 변경 용이성 | 적용. API 하나 추가·변경 | M3 / M3 | E2(07-a X2~X6) | O — wire 칸 변경이 스냅샷에 보이고 축소는 breaking이다. 함수가 보내는 값(`projectRequest`)은 PR에서 본다(매뉴얼 "못 잡음") | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | O — 오류 어휘 둘의 관계가 타입 옆에 있다. 폐기 별칭 `MappingResult`는 제거 조건과 lint로 남아 있다(`boundary-mapper.ts:1-28`) | +| 5 | 위험 가시성 | 적용 | M2 / M3 | E2(07-a X5) | O — 검증 생략이 행(`unvalidated`)과 breaking 등급으로 드러난다. `commandRecovery`를 누가 읽는지 타입 옆에 있다 | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | O — 조립 실패가 operation·method·원인을 메시지에 싣는다(`external-contract-runtime.ts:291-293`). `check:registries`가 그 원인을 찍는다(07-a R1) | +| 7 | 운영 성숙도 | 다른 영역 | - | - | > 영역 03·13 | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E2(07-b E4, D6g) | P — 테스트와 drift 스크립트는 고칠 곳을 말한다. 부팅 `CONFIG_SECRET_NAME_REJECTED`는 키 이름을 버린다(1103/07-04 남음) | +| 9 | 유지보수 성숙도 | 적용 | M2 / M2 | E1 | O — 낡은 문서 줄(1103/07-05)과 CHANGELOG 행(P-07-07)이 고쳐졌다 | +| **10** | 테스트 성숙도 | 적용 | M3 / M3 | E2(변이 26종) | P — 07-a·07-b의 변이 26종이 모두 기대한 대로 죽거나(실패) 기록됐다. 답 표 사본과 pin 문서를 잇는 테스트는 없다(07-01). 행과 검증기를 같이 strict로 바꾸면 테스트 25파일이 모두 통과한다(07-R1, 07-02) | +| 11 | 데이터 성숙도 | 다른 영역 | - | - | > 영역 05 | +| 12 | 동시성 성숙도 | 적용 제외. 계약은 순수 선언과 검사다 | - | - | - | +| 13 | 확장성 | 적용 | M2 / M2 | E2(`second-api-feature-registries`, test:unit 통과) | O — 새 operation은 additive이고 governance를 고치지 않는다 | +| 14 | 성능 성숙도 | 다른 영역 | - | - | > 영역 15. 이번 diff는 투영 칸을 늘렸지만 투영은 레지스트리 검사와 개요 화면에서만 돈다 | +| **15** | 보안 성숙도 | 적용 | M4 / M4 | E2(07-b M2·M3·H19, 07-a Z1, 07-b E4) | O — 쿠키 쓰기 CSRF 조립 검사가 method·헤더 이름별로 잠겼다. zod 하위 경로도 facade를 거친다. 금지 설정 키가 `test:unit`에서 막힌다. descriptor 밖 쿠키 POST(upload 제어)는 영역 01 | +| 16 | 의존성 성숙도 | 다른 영역 | - | - | > 영역 13 | +| **17** | API / Contract 성숙도 | 적용 | M3 / M3(부분) | E2(07-a, 07-b D6a~D6g, 07-R1) | P — FE-REG-API가 실행되는 wire 값을 모두 기록한다(큰 개선). 짝 백엔드 답 표는 사본↔프론트만 잠겼고 사본↔백엔드는 게이트 밖이다(07-01). 응답 경계를 좁히는 변경은 기록만 된다(07-02) | +| 18 | 배포 성숙도 | 다른 영역 | - | - | > 영역 13 | +| **19** | 설정 성숙도 | 적용 | M3 / M3 | E2(07-b E4, test:unit) | P — FE-REG-ENV 행이 두 방향과 값까지 스키마와 같다(P-07-05 고쳐짐). 금지 이름이 test:unit에서 잡힌다. 부팅 오류에 키 이름이 없다(1103/07-04 남음) | +| 20 | 개발자 경험 | 적용 | M2 / M1 | E1 | P — 매뉴얼이 breaking과 behavior-change, 못 잡는 것을 맞게 적는다. drift 스크립트는 매뉴얼에 없고, worktree에서는 "skipped" rc=0이다(07-01) | +| **21** | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E2 | P — breaking 칸 12개, 참조 3개, 조립 규칙이 동작한다. 백엔드 변경 검출은 게이트 밖이고 desktop에서 비교 불가다(07-01) | +| 22 | 추상화 성숙도 | 적용 | M2 / M2 | E1 | O — 투영이 descriptor 하나에서 행을 뽑아 사본이 없다. 스키마 메타 행은 남았지만 테스트가 쓰임과 대조한다 | +| 23 | 일관성 | 적용 | M2 / M1 | E1 | P — FE-REG-API는 경계 축소를 breaking으로, FE-REG-SCHEMA는 behavior-change로 본다(07-02). Browser RPC는 여전히 `KEYED_COMMAND`·`NON_REPLAYABLE`이다(`src/contracts/browser-rpc.ts:51-52`) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E1 | P — `unknownFieldPolicy`가 이제 검증기와 대조돼 이름에 효과가 생겼다. `SAME_ORIGIN_COOKIE` 전송이 `credentials: "include"`도 받아 이름보다 넓다(`src/contracts/rest-profiles.ts:177-183`, 지난 라운드와 같음, 발견으로 세지 않음). pin의 `sectionsCompared: ["4"]`가 실제로 옮긴 범위(§4 한 행)보다 넓게 읽힌다(07-01) | +| 25 | 조직 확장성 | 적용 | M2 / M2 | E2(second-api 테스트) | O — 기능 팀이 governance나 기준선을 고치지 않고 API를 더한다 | +| 26 | Ownership 성숙도 | 적용 | M2 / M2 | E1 | P — pin에 `owner`·`comparedOn`이 있다. 백엔드가 움직였을 때 누가 drift를 돌리는지는 정해져 있지 않다(07-01) | +| 27 | 삭제 가능성 | 적용 | M3 / M3 | E2(FE-GATE-020 rc=0, 오케스트레이터) | O — 참조 기능 제거 드릴이 통과한다. 정책 테스트는 설치된 기능이 없으면 빈 채로 통과한다(`schema-metadata-policy.test.ts:124-125`) | +| 28 | 회복 가능성 | 적용 제외. 계약은 복구 절차를 소유하지 않는다 | - | - | - | + +X(미충족)인 관점은 없다. + +## 5. 미검증 + +- 07-R1 패치로는 `check:registries`와 vitest 25파일만 돌렸다. test:component·integration·e2e는 돌리지 않았다. +- 실제 짝 백엔드를 띄워 §2·§4 답을 받아 프론트 판정을 본 적은 없다. D6g는 문서 한 파일로 만든 가짜 repo다. +- FE-GATE-010(`check-registries` 포함)·012·013의 merge-48 결과는 이 문서를 쓸 때 아직 없었다. `check:registries` 변이 없는 결과는 07-a의 A0(`11 registries PASS; compatibility=none`)를 썼다. +- 다운스트림 두 repo가 백엔드 checkout을 어디에 두고 drift 스크립트를 돌리는지는 보지 않았다. +- `browser-rpc.ts`, `service-worker*.ts`, `web-push.ts`, `query-keys.ts`, `deployment-admission.ts`는 이번 diff가 없어 다시 읽지 않았다. + +## 6. 실행 기록 + +모든 실행은 desktop helper(`/tmp/claude-gates/r4/exp.sh`)로 했다. 변이 스크립트는 사례마다 `perl -0pi`로 한 파일을 바꾸고, 바뀌지 않으면 그 사례를 건너뛰고, 명령 뒤 `git checkout -- .`로 되돌렸다. 스크립트는 `desktop:/tmp/claude-gates/r4/mut/07-lib.sh`, `07-loop-a.sh`, `07-loop-b.sh`, 사례별 출력은 `desktop:/tmp/claude-gates/r4/exp/07-cases/`다. 처음 띄운 두 실행은 ssh 수명 문제로 잠금을 얻기 전에 직접 멈췄다(로그 없음, checkout에 닿지 않음). 07-c는 19:55 helper 종료로 취소돼 배치 요청 07-R1이 됐다. + +| 실행 | 명령 | 잠금 대기·load | rc | 복구 | +|---|---|---|---|---| +| 07-a | `bash /tmp/claude-gates/r4/mut/07-loop-a.sh` (env local) | 740초 · 10.57 · 19:46:44 | 0 (11초) | `restored: clean at 8a442262` | +| 07-b | `bash /tmp/claude-gates/r4/mut/07-loop-b.sh` (env local) | 749초 · 8.45 · 19:46:55 | 0 (16초) | `restored: clean at 8a442262` | +| 07-c | `bash /tmp/claude-gates/r4/mut/07-loop-c.sh` | — | 실행 안 됨 | 취소(checkout에 닿지 않음) → 07-R1 | +| 07-R1(오케스트레이터 배치) | 패치 `requests/07-R1-strict-response.diff` 적용 뒤 `corepack pnpm -s check:registries`, 변경 출력, `node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts tests/features/reference-feature tests/contract tests/runtime-schema` (env local) | 배치 · 1.01 · 20:11:41 | registries-rc=0, vitest-rc=0 (8초) | restore clean(앞뒤로 `8a44226`) | + +### 6.1 07-a: FE-REG-API와 zod facade (`corepack pnpm -s check:registries`, Z1은 `check:architecture`) + +| 사례 | 변이 | rc | 결과 | +|---|---|---|---| +| A0 | 없음 | 0 | `11 registries PASS; compatibility=none` | +| X2 | 생성 API `acceptedStatuses` `[200, 201]`→`[201]` | 1 | **잡힘.** `breaking change missing evidence: FE-REG-API:CREATE_REFERENCE_RESOURCE:acceptedStatuses:allowed-value-removed` | +| X2b | 같은 칸 → `[200]` | 1 | **잡힘.** 같은 메시지 | +| X3+X6 | GET 상세 `responseByteLimit` 32,768→8,388,608, `totalDeadlineMs` 10,000→60,000 | 0 | PASS `compatibility=behavior-change`. `responseByteLimit:field-changed behavior-change 32768 -> 8388608`, `totalDeadlineMs:field-changed behavior-change 10000 -> 60000` | +| X4 | problem 검증기 id `ReferenceProblem`→`WhateverProblem` | 1 | **잡힘.** `problemSchema references unknown FE-REG-SCHEMA.schemaId=WhateverProblem` 3건, `problemSchema:field-changed` breaking 3건 | +| X5 | GET 상세 출력 검증기 → `unvalidatedPayload` | 1 | **잡힘.** `breaking change missing evidence: FE-REG-API:GET_REFERENCE_RESOURCE:unvalidated:field-changed` | +| R1 | GET 상세 `retrySemantics` `SAFE`→`KEYED` | 1 | **잡힘.** `GET is a read; its retrySemantics is SAFE or IDEMPOTENT, not KEYED` | +| R1b | 같은 칸 → `NEVER` | 1 | **잡힘.** `... not NEVER` | +| Z1-base | 없음 (`check:architecture`) | 0 | `Architecture graph fixtures: 29 regression checks PASS` | +| Z1 | 참조 스키마 import를 `"zod/v4"`로 | 1 | **잡힘.** `Architecture violation [zod-is-reached-through-contracts-zod]: ... -> zod/v4` | + +### 6.2 07-b: 조립 규칙·정책·설정·D6 (`node scripts/run-vitest.ts run <파일>`) + +| 사례 | 변이 | 테스트 파일 | rc | 결과 | +|---|---|---|---|---| +| B0 | 없음 | 아래 6파일 전부 | 0 | 6파일 106건 통과 | +| M2 | CSRF 검사 `!isRead`→`method === "POST"` | rest-profile-contract, realtime-stream-registry | 1 | **죽음.** PUT·PATCH·DELETE 거절 3건 실패 | +| M3 | CSRF 헤더 이름 검사 → "필수 헤더가 0개면" | 같음 | 1 | **죽음.** POST·PUT·PATCH·DELETE 4건 | +| H19 | `x-csrf-token` 허용 삭제 | 같음 | 1 | **죽음.** "accepts a %s that requires x-csrf-token" 4건 | +| M9 | snapshot의 `method === "GET"` 조건 삭제 | 같음 | 1 | **죽음.** HEAD·POST·PUT·PATCH·DELETE × SAFE·IDEMPOTENT 10건 | +| M9b | method·retrySemantics 조건 모두 삭제 | 같음 | 1 | **죽음.** 22건 | +| S2 | retrySemantics 조건만 삭제 | 같음 | 1 | **죽음.** GET × KEYED·NEVER 2건 | +| MR1 | 읽기 `SAFE`·`IDEMPOTENT` 규칙 끔 | external-contract-runtime | 1 | **죽음.** GET·HEAD × KEYED·NEVER 4건 | +| MW1 | 쓰기 `SAFE` 거절 끔 | 같음 | 1 | **죽음.** POST·PUT·PATCH·DELETE 4건 | +| MF1 | `assertSameWireFrame` 호출 삭제 | 같음 | 1 | **죽음.** "refuses an operation that forgot the Envelope" 1건 | +| X8 | 응답 DTO `.strip()`→`.strict()`(행 그대로) | schema-metadata-policy | 1 | **죽음.** `row STRIP_UNKNOWN, validator REJECT_UNKNOWN` 3건 | +| E4 | 제품 키 `PRODUCT_COOKIE_NOTICE`(zod 필드 + FE-REG-ENV 행) | env-registry-coverage | 1 | **죽음.** `Forbidden client configuration key: PRODUCT_COOKIE_NOTICE` | +| D6a | 답 표 `IDEMPOTENT_REQUEST_MISMATCH.refusedBeforeWrite` true→false | backend-contract-pin | 1 | **잡힘.** `expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'` 외 1건 | +| D6b | pin 커밋만 `c508b1ba`로 | 같음 | 1 | **잡힘.** "names one backend commit" | +| D6c | pin과 답 표 커밋을 함께 `c508b1ba`로 | 같음 | 0 | **통과.** 10건. 테스트는 백엔드를 읽지 않는다 | +| D6d | 답 표에 새 답(409, 쓰기 전 거절, 같은 키 아님) | 같음 | 1 | **잡힘.** `expected 'MAYBE_APPLIED' to be 'NOT_APPLIED'` | +| D6e | 프론트 표에서 `REQUEST_TIMEOUT` 행 삭제 | 같음 | 1 | **잡힘.** `expected undefined to be 'MAYBE_APPLIED'` | +| D6e2 | 답 표에서 `REQUEST_TIMEOUT` 행 삭제 | 같음 | 1 | **잡힘.** `503 REQUEST_TIMEOUT: expected false to be true` | +| D6f | 없음. `node scripts/check-backend-contract-drift.ts` | — | 스크립트 rc 2 | `cannot compare /home/donghyeon/workspace/clean-architecture-backend-template with the pinned 45d2a478b800`. desktop 옆 checkout은 `ef947e5`(2026-09-16)라 pin 커밋이 없다 | +| D6g | 가짜 백엔드 repo(커밋1 = `45d2a478` 문서, 커밋2 = `IDEMPOTENCY_COMPLETION_UNKNOWN` 503→500). pin·답 표 커밋을 커밋1로 | drift 스크립트 `--backend <가짜>`, backend-contract-pin | 스크립트 rc 1, 테스트 rc 0 | drift가 바뀐 표 줄 두 개(`-| ... | 503 |`, `+| ... | 500 |`)와 "Recheck ..."를 찍었다. 같은 상태에서 테스트는 10건 통과 | + +변이 26종(07-a 8종, 07-b 18종) 중 통과를 예상한 X3+X6·D6c와 D6g의 테스트 쪽을 빼면 모두 기대한 메시지로 실패했다. 변이 없는 대조(A0, Z1-base, B0)는 모두 통과했다. + +### 6.3 배치 요청 + +| 요청 | 내용 | 상태 | +|---|---|---| +| 07-R1 | 응답 DTO `.strict()` + 두 응답 행 `REJECT_UNKNOWN` 패치로 `check:registries`와 정책·참조 기능·contract·runtime-schema vitest | 완료. `11 registries PASS; compatibility=behavior-change`. `FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:field-changed behavior-change "STRIP_UNKNOWN" -> "REJECT_UNKNOWN"` 2건. vitest 25파일 180건 통과. 변이 없는 대조는 07-a A0와 `gates/test_unit.log`·`test_contract.log`·`test_runtime-schema.log`, FE-GATE-005다. 결과 로그는 `scratchpad/r4/results/07/07-R1.log` | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 07-01 | Low · P3 | 구조적 위험 | 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 drift 스크립트만 알린다(desktop에서 비교 불가, worktree에서 skipped rc=0, 매뉴얼에 없음) | `tests/unit/backend-contract-pin.test.ts:76-79`, `scripts/check-backend-contract-drift.ts:30, 40-45, 60`, `config/contracts/backend-contract-pin.json:7` | +| 07-02 | Low · P3 | 개선 제안 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과하고 관련 테스트 25파일이 모두 통과한다(07-R1) | `config/contracts/registry-governance.json:288`, `scripts/lib/registry-compatibility.ts:346-351`, `tests/unit/schema-metadata-policy.test.ts:154-165` | diff --git a/docs/reviews/2026-11-05-maturity-review/08-presentation.md b/docs/reviews/2026-11-05-maturity-review/08-presentation.md new file mode 100644 index 00000000..dbebec74 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/08-presentation.md @@ -0,0 +1,255 @@ +# 영역 08 — presentation + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로 `src/presentation/`. 연결 확인: 참조 기능 폼 페이지(`src/features/reference-feature/presentation/`), 생성기 쓰기 슬라이스 템플릿(`scripts/create-feature-write-slice.ts`), 라우트 충돌 검사(`src/apps/deployable-app-module.ts`), Envelope 판정 일부(`src/adapters/http/backend-envelope.ts`) +> 깊게 본 관점 4, 5, 8, 14, 15, 23, 24 +> 렌즈: 선언한 업무 거절 뒤의 폼(이유·포커스·다시 저장), 결과 불명 화면의 재전송 버튼(키 없음/KEYED), 1103/08-02~08-05 수정, 15-01 수정의 플랫폼 구성 화면 +> **영역 판정(35.8): 조건부 사용 가능.** 셸, 디자인 시스템, 읽기 화면, 필드 검증 400을 받는 폼, `refusedBeforeWrite`를 선언한 짝 백엔드 쓰기 폼은 쓸 수 있다. 조건: 기능이 업무 거절 code를 모두 선언한다. 선언하지 않은 code는 지금도 막다른 길이다(2절 1103/08-01). 거절 이유를 사용자 말로 보이려면 페이지가 따로 만들어야 한다. + +## 0. 결론 + +- **지난 라운드 08 발견 중 4건(1103/08-02~08-05)은 고쳐졌다.** 각 수정에 테스트가 붙었고, 수정을 되돌리는 변이를 넣으면 그 테스트가 기대한 이유로 실패한다(08-R3, 08-R5~08-R7, 6절). +- **1103/08-01(= 03-01) 폼 쪽은 일부만 고쳐졌다.** `refusedBeforeWrite`에 적은 code는 이제 결과 불명이 아니다. 값을 고치면 저장 버튼이 켜져 있고 새 키로 저장된다(08-R1 A1~A4: 두 번째 요청 키 `key-2`). 생성 기능은 이름 거절을 필드 옆에 보인다. 남은 것은 둘이다. (1) 거절 이유가 사용자 말로 안 보인다. 선언한 400은 "요청을 처리할 수 없습니다." + "지원 정보 확인", 409는 "다른 변경과 충돌했습니다."다. 기능이 자기 거절 문구를 붙일 자리가 없다. (2) 선언하지 않은 code는 지난 라운드와 같은 막다른 길이다. KEYED면 `500 IDEMPOTENCY_RECOVERY_REQUIRED` 뒤에도 재전송 버튼이 남아 같은 키로 끝없이 다시 보낸다(08-R1 A5: 3회). +- **0929/03-03 화면 쪽은 고쳐졌다.** 결과 불명 화면은 키 없는 쓰기에 "같은 요청으로 다시 보내기"를 그리지 않는다. KEYED에는 그대로 그리고, 3엔진에서 같은 키로 다시 보낸다(08-R2 B2). 코디네이터와 화면이 같은 판정(`canResend`)을 쓴다. 키 조건을 지우면 테스트가 실패한다(03-R07 = 08-R4). +- **15-01 수정(플랫폼 구성 화면) 쪽 화면 결함은 없다.** 제목과 선언 정보가 먼저 그려지고, 실행부 표만 `Suspense` 뒤에서 기다린다. 로딩 자리는 이름 있는 `aria-busy` 영역이다. 청크 실패는 그 라우트의 청크 복구 경계로 간다. +- **새 발견 4건, 모두 Low·P3.** 복구 버튼을 키보드로 누른 뒤 포커스가 `body`로 떨어진다(08-01, 3엔진 확인). 생성 기능 폼은 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다(08-02). 홈 시작 링크가 런타임에 꺼진 기능을 가리킨다(08-03, `b96d61d8`이 만듦, 확인). 저장 버튼이 다른 저장이 진행 중일 때 켜져 있지만 눌러도 반응이 없다(08-04, `2d5d41f8`이 만듦, 확인). +- **약해진 검사는 없다**(2.1절). Critical·High·Medium 없음. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` | +| 커밋·작업 상태·확인 시점 | `8a44226`(`fix/maturity-review-2026-11-03`, 같은 커밋이 `fix/ui-design-audit-2026-11-01`·PR #4). 노트북 worktree `happy-easley-233d07`에서 읽기만 했다. 미추적 `AGENTS.md`는 무시했다. 2026-11-05 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(`config/contracts/backend-contract-pin.json`의 pin) | +| 필수 요구와 규모·운영 목표 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어. 짝 백엔드 Envelope 계약(계약 문서 6.1절). 화면 규모 목표 없음 | +| 읽은 코드·구성 범위 | `src/presentation/forms/` 전부, `components/async-surface.tsx`·`state-surfaces.tsx`, `templates/page-templates.tsx`, `adapters/query/application-query.ts`(250-280, 330-380, 560-850행), `examples/platform-overview-page.tsx` 전부, `pages/home-page.tsx`, `layouts/app-shell.tsx`(190-215행), `routes/app-router.tsx`(340-420, 500-625행)·`route-runtime.tsx`, `boundaries/chunk-recovery-boundary.tsx`, `providers/session-provider.tsx`, `i18n/catalog.ts`·`message-contract.ts` 일부, `design-system/primitives/button.tsx`. 연결: `reference-resource-form-page.tsx`, `use-reference-failure-action.ts`, `create-feature-write-slice.ts`(280-330, 385-410, 585-990행), `deployable-app-module.ts`(50-140행), `backend-envelope.ts`(90-400행), `http-execution-v3.ts`(1690-1790행), `contracts/errors.ts`(1-260행), `mutation-intent.ts`, `browser-mutation-intent-factory.ts`, 매뉴얼 01·02 해당 절, VD-04. `git diff e40684b..8a44226 -- src/presentation tests/component tests/features tests/e2e/reference-save.spec.ts tests/architecture/context-route-roots.test.ts` | +| 수행한 테스트·실험 | 직접 실행 0건. 오케스트레이터 배치 7건(6절): 08-R1 폼·홈 probe(jsdom), 08-R2 포커스 probe(Playwright 3엔진), 08-R3·08-R5~08-R7 변이 4종, 08-R4는 같은 변이인 03-R07로 대신했다. 모든 항목의 restore가 clean이었다. 게이트는 오케스트레이터 결과를 읽었다(아래) | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `2026-11-03-maturity-review/08-presentation.md`의 08-01~08-05와 그 문서 2절의 "남음" 이월 항목, README §12·§13·§14.4. README §14.4는 주장으로만 읽었다. 지난 실행 결과는 증거로 쓰지 않았다 | + +게이트(오케스트레이터, `8a44226`). 로컬 env(`desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`·`check:types`·`lint`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0, `test:unit` 194 files / 2,883 tests, `test:component` 40 / 270, `test:integration` 11 / 189 통과. `verify:documentation`은 rc=1이다(짝 백엔드 문서 경로 3개, 영역 14 소관). merge 단계(CI=true, `merge-48/summary.txt`): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(security, 영역 13 소관). 이 영역 근거로 쓴 것: `test_component.log`에서 `form-foundation` 31, `async-surface` 34, `application-mutation-admission` 17, `starter-platform-overview-page` 10, `starter-platform-overview-route` 1, `layout-landmarks` 4 모두 ✓. snapshot `artifacts/tests/coverage.xml`(FE-GATE-005)에서 `reference-page.test`·`context-route-roots` 48건 실패 0. FE-GATE-008 로그에서 `reference-save.spec.ts` 5건 × 3엔진 통과(포커스 2건 포함). FE-GATE-012: 초기 JS 202,973 / 204,800 gzip B, 26 / 32 파일, PASS. + +## 2. 지난 발견 재확인 + +줄 번호는 `8a44226` 기준이다. 08-Rk는 6절의 배치 실험 ID다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/08-01 (= 03-01, 폼 쪽) | 짝 백엔드의 업무 규칙 거절이 결과 불명이 되어, 거절 이유가 안 보이고 값을 고쳐 다시 저장할 수 없다 | **일부** | **고쳐진 것.** operation이 `commandEffect.refusedBeforeWrite`에 적은 code의 400·409·422는 `NOT_APPLIED`다(`backend-envelope.ts:317-327`, `:340-351`, `http-execution-v3.ts:1722-1737`). 폼은 결과 불명으로 붙들지 않는다. 값을 고치면 저장 버튼이 켜져 있고 새 키로 저장된다(`form-foundation.test.tsx` "saves the corrected value after a declared pre-write refusal, with a new key", 08-R1 A1~A4: 두 요청의 키 `key-1` → `key-2`, 결과 "저장했습니다."). 생성기는 `_INVALID`를 선언하고(`create-feature-write-slice.ts:306`) `mapProblem`으로 name 필드 오류로 바꾼다(`:397-404`). 그래서 생성 기능 폼은 "올바른 값을 입력해 주세요."를 필드 옆에 보이고 첫 오류 필드로 포커스를 옮긴다(08-R1 A4: 오류 요약 "새 항목 이름: 올바른 값을 입력해 주세요.", 포커스는 이름 입력란). **남은 것 (1) 이유 문구.** 선언한 409는 kind `CONFLICT`라 "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요."다(`use-app-form.ts:244-248`, `catalog.ts:153-154`). 선언한 400은 `UNKNOWN_CLIENT_FAILURE`·`action: "contact-support"`라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이다(`backend-envelope.ts:386-392`, `errors.ts:79-83`, `use-app-form.ts:260-267`). 고칠 수 있는 입력인데 지원 문의로 보낸다. `mapProblem`으로 필드 오류를 만들어도 문구는 플랫폼 표(`form-contracts.ts:33-64`)에서 issue code로만 고른다. 표에 없는 `DUPLICATE`는 "입력값을 확인해 주세요."다(08-R1 A3). 기능이 `*_ALREADY_EXISTS` 같은 자기 거절 문구를 붙일 자리가 없다. `conflict` 결과에서는 `form.failure`가 `null`이라(`use-app-form.ts:385`, `:411-416`) 페이지가 code를 읽어 따로 그릴 수도 없다. 매뉴얼은 "거절 이유를 필드 옆에 보이려면 `mapProblem`"이라고만 적는다(`docs/manual/02-decision-tables.md:185`). VD-04 결정 5는 "409 conflict는 validation으로 바꾸지 않는다"(`VD-04-native-form-facade.md:26`)여서 409 업무 거절을 어느 쪽으로 보일지 문서끼리 갈린다. **(2) 선언하지 않은 code.** 지난 라운드와 같다. 결과 불명, 저장 꺼짐, "변경됨으로 확인"이 저장되지 않은 요청을 "저장했습니다."로 바꾼다. KEYED면 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`를 받아도 결과 불명이 이어지고 재전송 버튼이 계속 남는다(08-R1 A5: 키 `key-1` 3회, 세 번 모두 같은 화면). `canResend`는 응답 원인을 보지 않는다(`application-query.ts:836-845`). 백엔드 표 주석은 이 응답을 "스스로 다시 보내지 않는다, 사용자가 데이터를 확인한다"로 적는다(`backend-envelope.ts:261-266`). 남은 부분의 심각도는 Medium·P2로 본다. 저장이 막히는 High 조건은 선언한 code에서 풀렸다. 판정 규칙은 영역 03 소관이다 | +| 1103/08-02 | 키보드로 저장했다가 필드 오류가 아닌 실패를 받으면 포커스가 `body`로 떨어진다 | 고쳐짐 | 폼이 렌더 뒤 feedback 자리로 포커스를 옮긴다(`use-app-form.ts:91-101`). 표시는 필드 오류·성공이 아닌 분기 5곳이다(`:230`, `:236`, `:245`, `:253`, `:262`). 템플릿이 그 자리를 `id` + `tabIndex=-1`로 만든다(`page-templates.tsx:73-82`). 참조 폼은 `feedbackId`를 넘기고 저장 중에 `disabled` 대신 `pending`을 쓴다(`reference-resource-form-page.tsx:71`, `:124-131`). 생성기 템플릿도 같다(`create-feature-write-slice.ts:674`, `:693-698`). 테스트: `reference-page.test.tsx:470-517`(결과 불명, 429), `reference-save.spec.ts:120-132`, `:166-173`. 변이(포커스 제거)는 이 두 행으로 실패한다(08-R3). FE-GATE-008에서 `reference-save.spec.ts` 포커스 2건이 3엔진 통과. 완료 기준(저장 뒤 포커스가 실패 상태 안, Tab 한 번에 복구 버튼)을 충족한다. 복구 버튼을 누른 **뒤**의 포커스는 새 발견 08-01이다 | +| 1103/08-03 | 폼 문구 표가 `Object.prototype` 이름까지 찾는다 | 고쳐짐 | `form-contracts.ts:74-80` `Object.hasOwn`. `form-foundation.test.tsx:677-685`가 `constructor`·`toString`·`__proto__`·`hasOwnProperty`를 본다. 변이(`!== undefined`)는 내장 이름 4행으로 실패한다(08-R5, "요청한 문구를 표시할 수 없습니다.") | +| 1103/08-04 | 대소문자·끝 슬래시만 다른 기능 라우트를 놓친다 | 고쳐짐 | `deployable-app-module.ts:115-121` 모양 키를 소문자로 바꾸고 끝 슬래시를 지운다. `context-route-roots.test.ts:226-251` 두 행. 변이(`.toLowerCase()` 제거)는 대소문자 행으로 실패한다(08-R6). `/a/new`·`/a/:id` 허용 행은 그대로 통과한다 | +| 1103/08-05 | 422 `IDEMPOTENT_REQUEST_MISMATCH`를 입력 오류로 보인다 | 고쳐짐 | 422는 필드 목록이 있을 때만 필드 검증이다(`backend-envelope.ts:216-225`). 없으면 `UNKNOWN_CLIENT_FAILURE`다(`:386-392`). 폼은 `unavailable` + 지원 참조다. `form-foundation.test.tsx:346-` "shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status". 변이(422 → 항상 필드)는 이 행으로 실패한다(08-R7) | +| 0929/03-03 (화면 쪽, 판정은 영역 03) | 결과 불명 화면의 재전송이 키 없는 쓰기에도 열린다 | 고쳐짐 | `canResend`가 결과 불명·키 있음·조정 중 아님을 함께 본다(`application-query.ts:836-845`). `resendUnknownEffect`도 같은 함수를 쓴다(`:800-804`). 같은 답을 `state.unknownEffectResendable`로 넘기고(`:807-820`) 화면은 `false`면 버튼을 그리지 않는다(`async-surface.tsx:225-231`). 키는 `requiresIdempotencyKey`일 때만 생기고(`browser-mutation-intent-factory.ts:38-45`) 없는 키는 칸째 빠진다(`mutation-intent.ts:82-84`). 그래서 `idempotencyKey !== undefined` 판정이 맞다. KEYED는 그대로 보인다(`application-mutation-admission.test.tsx` "offers the same-key resend…", 08-R2 B2: 3엔진 모두 같은 키로 재전송). 키 없는 생성 기능의 테스트가 "재전송 버튼 없음"을 본다(`create-feature-write-slice.ts:752-769`). 키 조건을 지우면 "offers no resend for an unknown request that carries no key"가 실패한다(03-R07, 08-R4와 같은 변이) | +| 0929/08-01 | 제품이 지원 locale을 선언할 곳이 없다 | 남음 | `message-contract.ts:8-13` 고정 목록, `app-shell.tsx:86-89` 선택지에 `en-XA`·`ar-EG`. 1103 README §14.4가 "큰 것은 남겼다"고 적은 항목이다 | +| 0929/08-08 | 로그인 복귀 주소가 라우터 기준 경로다 | 남음 | `session-provider.tsx:88`, `:99` `beginSignIn(pathname + search + hash)`. `useLocation()`은 basename을 뺀 값이다(basename은 `runtime-application.tsx:52`). `use-reference-failure-action.ts:26`도 같다. `beginSignIn(returnTo?)`(`auth-session-port.ts:38`)은 어느 기준인지 적지 않는다 | +| 0929/08-06, 0929/08-07 | 라우트 제목 세 곳, 제품 폰트 자리 | 판정 안 함 | 지난 라운드와 같이 렌즈 밖이다. 08-06은 1103/16-06(라우트 계약 `title`을 화면이 읽지 않음, §14.4 일부)과 겹친다 | +| 1103 3.6절 관찰 셋 | 지원 참조가 재전송마다 바뀜, `role="status"` 안의 버튼, 레이아웃 `
` 미검사 | 그대로(발견 아님) | `use-app-form.ts:392-395`, `async-surface.tsx:197-239`, `layout-landmarks.test.tsx`에 `tabIndex` 단언 0건 | + +### 2.1 수정이 검사를 약하게 했는가 + +`git diff e40684b..8a44226`로 이 영역 수정 9커밋(`4282a541`, `2d5d41f8`, `2017ef76`, `d7c6cb4f`, `d549ceb3`, `b96d61d8`, 병합 3)과 대상 테스트를 봤다. **약해진 검사는 없다.** + +| 바뀐 검사 | 판단 | +|---|---| +| `reference-page.test.tsx:334-339` "deduplicates create": `toBeDisabled()` → `aria-busy="true"` + 포커스 유지 | 약해지지 않았다. `toHaveBeenCalledOnce()`는 그대로다. 버튼이 꺼지지 않으므로 두 번째 클릭이 실제로 폼까지 가고, 폼의 중복 차단(`use-app-form.ts:324`)을 직접 검사하게 됐다 | +| `starter-pages.test.tsx`에서 예제 화면 테스트 2건 삭제 | 옮겨졌다. `tests/features/platform-examples-feature/example-pages.test.tsx:51-79`에 같은 단언이 있다(`b96d61d8`) | +| `starter-platform-overview-page.test.tsx` 전부 `await act` + `Promise.resolve(...)` | 단언은 같다. 대기 중 경로는 새 `starter-platform-overview-route.test.tsx`가 본다. load 실패 경로는 전에도 지금도 테스트가 없다(5절) | +| `form-foundation.test.tsx` "keeps the default copy" 1건 → `it.each` 5건 | 넓어졌다(`:677-685`) | +| `application-mutation-admission.test.tsx`, `async-surface.test.tsx`, `context-route-roots.test.ts` | 더하기만 했다 | + +## 3. 이번 발견 (36.3) + +**새 발견 4건.** 심각도: Low 4(Critical·High·Medium 0). 우선순위: P3 4. 성격: 확인된 결함 4(코드 + 실행으로 확인 3건, 코드로만 확인 1건(08-02)). + +### 3.0 짝 백엔드 Envelope 쓰기가 거절될 때 폼이 보이는 것 + +코드 읽기와 08-R1(A1~A5, 참조 폼 실제 페이지·코디네이터, gateway 결과만 주입)로 채웠다. 생성기 행은 코드 읽기만이다. 참조 폼 페이지의 배선(`reference-resource-form-page.tsx:51-183`)과 생성기 템플릿(`create-feature-write-slice.ts:584-721`)을 기준으로 했다. + +| 서버 답 | 판정 | 폼 결과 | 사용자가 보는 것 | 포커스 | 다시 저장 | +|---|---|---|---|---|---| +| 선언한 409 업무 code(예: `POSTER_ALREADY_EXISTS`) | `NOT_APPLIED`, kind `CONFLICT`(`errors.ts:284-293`) | `conflict`(`use-app-form.ts:244-248`) | 오류 요약 "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", feedback "충돌을 해결한 뒤 다시 제출할 수 있습니다." | feedback 자리 | 됨, 새 키 | +| 선언한 400 업무 code(예: `WORKLOG_INVALID`), `mapProblem` 없음 | `NOT_APPLIED`, `UNKNOWN_CLIENT_FAILURE`·`contact-support` | `unavailable`(`:260-267`) | "요청을 처리할 수 없습니다." + "지원 정보 확인"(참조 폼은 지원 상태 화면으로 이동, `use-reference-failure-action.ts:36-41`) + 지원 참조 | feedback 자리 | 됨, 새 키(`form-foundation.test.tsx` "saves the corrected value after a declared pre-write refusal") | +| 선언한 code + `mapProblem`이 필드 목록, issue code가 표 밖(예: `DUPLICATE`) | `NOT_APPLIED`, `VALIDATION_REJECTED` | `validation-error` | 필드 옆 "입력값을 확인해 주세요." | 첫 오류 필드 | 됨 | +| 생성기 기본(`_INVALID` → issue `INVALID`) | 같음 | `validation-error` | 필드 옆 "올바른 값을 입력해 주세요." | 첫 오류 필드 | 됨 | +| 선언하지 않은 400·409·422 | `MAYBE_APPLIED` | `effect-unknown` | "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인"(+ KEYED면 "같은 요청으로 다시 보내기") + 지원 참조 | feedback 자리 | 안 됨(1103/08-01 남은 부분) | +| 위 KEYED 재전송에 `500 IDEMPOTENCY_RECOVERY_REQUIRED` | `MAYBE_APPLIED` | `effect-unknown` | 같은 화면, 재전송 버튼 그대로 | feedback 자리 | 안 됨 | + +공통: 담당·기한·상태는 `미정 · 미정 · 신규`, 재검증 결과는 `없음(신규)`이다. + +### 08-01 실패 상태의 복구 버튼(변경됨으로 확인, 같은 요청으로 다시 보내기, 다시 시도)을 키보드로 누르면, 일이 끝난 뒤 그 버튼이 사라지면서 포커스가 `body`로 떨어진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 6, 10, 28 | +| 근거 | 폼은 결과가 필드 오류도 성공도 아닌 실패일 때만 렌더 뒤 feedback 자리로 포커스를 옮긴다(`use-app-form.ts:91-101`, 표시는 `:230`, `:236`, `:245`, `:253`, `:262`). 성공 쪽 `settleSuccessfulValues`(`:176-195`)는 표시하지 않는다. 그 길을 타는 것이 "변경됨으로 확인"(`settleApplied`, `:197-201`), 재전송 성공(`resendUnknown` → `applyOutcome` → `:213-215`), "다시 시도" 성공(`submitForm`)이다. **참조 폼, 확인.** 누르면 코디네이터가 그 시도를 `RECONCILING`으로 바꾸고(`application-query.ts:761`) 화면 표시가 `mutation-pending`이 된다(`:815-819`). 그 사이 feedback은 `null`이다. `form.failure`는 상태 결과에만 있고(`use-app-form.ts:385`) `form.result`는 아직 `effect-unknown`이라 어느 가지에도 들지 않는다(`reference-resource-form-page.tsx:141-183`). feedback 자리(`page-templates.tsx:73-82`)가 통째로 빠지고 포커스가 있던 버튼도 빠진다. 끝나면 "저장했습니다."가 새 `

`로 그려진다(`:178-179`). **재전송·다시 시도.** 성공하면 그 버튼을 그리던 `AsyncSurface`·`FormFailureStatus`가 `

`로 바뀐다. **생성 폼.** 재전송 성공은 상세로 이동해 라우터가 제목으로 포커스를 옮긴다(`create-feature-write-slice.ts:629-647`, `:718`). 확인 뒤에는 feedback이 `null`이다(`:704-721`, 08-02). 브라우저는 포커스된 요소가 문서에서 빠지면 포커스를 `body`로 돌린다. 1103/08-02 테스트는 저장 **직후**의 포커스만 본다(`reference-page.test.tsx:470-517`, `reference-save.spec.ts:120-132`, `:166-173`). **실행.** 08-R2(빌드 preview, 3엔진): 키보드로 저장 → feedback 포커스 → Tab → 복구 버튼 → Enter → "저장했습니다." 뒤 `document.activeElement`가 chromium·firefox·webkit × 확인·재전송·다시 시도 9건 모두 `body`. 다음 Tab은 9건 모두 이름 입력란이었다. 08-R1(jsdom) B1~B3도 `BODY` | +| 발생 조건 | 키보드·스크린 리더 사용자가 실패 상태 안의 복구 버튼을 쓰고, 그 결과가 성공 또는 확인일 때. 1103/08-02 수정 뒤에는 저장 직후 Tab 한 번에 이 버튼에 닿으므로 이 경로를 더 자주 탄다 | +| 영향 | 저장이 끝난 뒤 보이는 포커스가 사라진다. 다음 Tab은 세 엔진 모두 이름 입력란으로 가서(08-R2) 키보드 이동은 이어진다. 1103/08-02 때(다음 Tab이 문서 맨 앞)보다 피해가 작다. 스크린 리더가 `body` 포커스에서 읽는 위치는 미확인이다. "저장했습니다."는 `role="status"`라 발표될 수는 있다 | +| 심각도·우선순위 | Low · P3 — 기능과 키보드 이동은 남는다. 모든 폼이 참조 폼·생성기 배선을 복사하고 `PRODUCT.md`가 WCAG 2.2 AA를 요구하지만, 다음 Tab이 제자리 근처로 가서 1103/08-02(Low·P2)보다 한 단계 낮게 둔다 | +| 확실성과 남은 가정 | 3엔진 실행으로 확인(E3). 실제 스크린 리더 발표는 미확인 | +| 결정의 근거 | 적용 제외 — 이미 있는 feedback 포커스 장치를 복구 뒤 전이에도 쓰지 않은 누락이다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | (1) 직전 결과가 상태 결과나 `effect-unknown`이었다가 성공·확인으로 바뀌면 `focusFeedbackRef`를 세운다(`useAppForm` 안, 페이지마다 복사하지 않음). (2) 참조 폼은 확인 중(`mutation-pending`)에도 feedback 자리를 비우지 않는다(예: `async.mutationPending` 문구). 08-04와 함께 고칠 수 있다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 처음 저장이 그냥 성공할 때는 포커스를 옮기지 않는다. 1103/08-02의 실패 뒤 포커스와 Tab 한 번 규칙 | +| 비용·부작용 | `use-app-form.ts` 몇 줄, 참조 페이지 한 가지, e2e 3건 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 08-R2의 세 경우에서 일이 끝난 뒤 포커스가 feedback 자리 안에 있다 | +| 검증 방법 | `tests/e2e/reference-save.spec.ts`에 08-R2 probe의 세 test를 넣는다 | + +### 08-02 생성 기능 폼은 "변경됨으로 확인" 뒤 아무것도 보이지 않은 채 입력을 비운다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (생성기 템플릿 코드로 확정. 생성한 기능으로 실행하지 않았다) | +| 관련 관점 | 24, 23, 20, 28 | +| 근거 | 생성기 템플릿의 feedback은 `form.failure`와 결과 불명 두 가지뿐이다(`create-feature-write-slice.ts:703-721`). 저장 성공은 상세 화면으로 이동해서 알린다(`:629-647`). "변경됨으로 확인"은 `reconcileUnknownEffect(...).then(form.settleApplied)`이고 이동하지 않는다(`:714`). `settleApplied` → `settleSuccessfulValues`가 결과를 `success`로 바꾸고 기본값 `resetOnSuccess: true`로 입력을 비운다(`use-app-form.ts:54`, `:176-195`). 그래서 결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 참조 폼은 같은 경우 "저장했습니다."를 보인다(`reference-resource-form-page.tsx:178-179`). 생성 기능 테스트는 결과 불명에서 재전송 버튼이 없다는 것까지만 본다(`create-feature-write-slice.ts:752-769`) | +| 발생 조건 | 생성 기능(짝 백엔드 기본은 `NEVER`)의 저장 응답을 잃어 결과 불명 → 사용자가 "변경됨으로 확인". `NEVER`에서는 이것이 화면 안의 유일한 행동이다(재전송 없음, 0929/03-03 수정) | +| 영향 | 사용자는 확인이 받아들여졌는지, 항목이 저장됐는지 화면에서 알 수 없다. 입력이 지워졌으므로 다시 입력해 저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 포커스도 `body`로 간다(08-01) | +| 심각도·우선순위 | Low · P3 — 응답을 잃는 드문 경로다. 중복은 사용자가 다시 입력할 때만 생기고 목록에서 보인다 | +| 확실성과 남은 가정 | 템플릿 문자열을 읽었다. 생성 결과 파일과 실행은 확인하지 않았다. 파일은 `scripts/`라 영역 16과 겹칠 수 있다. 합칠 때 하나로 센다 | +| 결정의 근거 | 적용 제외 — 참조 폼에 있는 가지가 생성기 템플릿에 빠진 누락이다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | 확인 뒤 목록으로 이동한다(목록 쿼리는 `reconcileUnknownEffect`가 이미 무효화한다). 또는 참조 폼처럼 `form.result === "success"` 가지에 확인 문구를 둔다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 저장 성공 뒤 상세 이동, 키 없는 결과 불명에 재전송 없음 | +| 비용·부작용 | 템플릿 몇 줄, 생성 기능 테스트 한 행 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 생성 기능 테스트에서 결과 불명 → "변경됨으로 확인" 뒤 확인 문구가 보이거나 목록 화면이다 | +| 검증 방법 | `renderCreatePageTest`(`create-feature-write-slice.ts:731-`)에 한 행. `test:feature-scaffold`가 생성 결과로 돈다 | + +### 08-03 홈 화면의 시작 링크가 런타임 설정으로 꺼진 기능의 라우트를 가리킨다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 1, 10 | +| 근거 | `home-page.tsx:21-23`의 `STARTER_ROUTES`는 모듈을 불러올 때 `NAVIGATION_ROUTES`에서 `APP_HOME`을 빼고 앞 3개를 고른다. 기능이 켜져 있는지는 보지 않는다. 셸 탐색은 같은 목록을 `runtime.isFeatureActive(owner)`로 거른다(`app-shell.tsx:196-202`, 주석 "A feature the runtime document disabled does not advertise itself"). 라우터는 꺼진 기능의 라우트에 사용 중지 화면을 그린다(`app-router.tsx:361-364`). 템플릿에서 시작 링크는 `EXAMPLES_PLATFORM`(순서 15, `contracts/routes.ts:44`), `EXAMPLES_UI`(20), `EXAMPLES_STATES`(30)이다(`platform-examples-contract.ts:16-39`). 뒤의 둘이 `platform-examples-feature`의 라우트다. 1103/09-04 수정(`b96d61d8`)이 예제 화면 셋을 끌 수 있는 기능으로 옮기면서 생겼다. 기능 끄기 테스트(`product-feature-switch.test.tsx`)는 셸 탐색과 직접 링크만 본다. **실행(08-R1 C, 실제 `AppRouter`).** `platform-examples-feature`를 `DISABLED_BY_CONFIG`로 두면 셸 탐색은 `/`, `/examples/platform`, `/examples/reference-resources`만 남는다. 홈 시작 링크는 켜져 있을 때와 같이 "플랫폼 구성 보기 → /examples/platform", "UI 구성요소 보기 → /examples/ui", "화면 상태 보기 → /examples/states"다. 둘째 링크를 누르면 `data-disabled-feature="platform-examples-feature"`, 제목 "현재 사용할 수 없는 기능입니다."다 | +| 발생 조건 | 운영자가 런타임 설정으로 `platform-examples-feature`를 끈다. 또는 제품이 탐색 순서 앞쪽 기능을 런타임에 끈다. 빌드에서 뺀 기능은 해당 없다 | +| 영향 | 홈의 주요 버튼 셋 중 둘이 사용 중지 화면으로 간다. 켜진 다른 기능은 그 자리에 오지 않는다 | +| 심각도·우선순위 | Low · P3 — 화면에서 바로 보이고 데이터 영향이 없다. 홈은 제품이 바꾸는 시작 화면이다 | +| 확실성과 남은 가정 | jsdom 실행으로 확인(E2). 브라우저에서는 돌리지 않았다 | +| 결정의 근거 | 적용 제외 — 셸과 같은 조건을 홈이 빠뜨린 누락이다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | 렌더 때 셸과 같은 조건으로 거른 뒤 앞 3개를 고른다. 셸과 홈이 같은 함수(예: "켜진 탐색 라우트")를 쓴다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 홈은 기능 라우트를 이름으로 부르지 않는다(`home-page.tsx:15-20` 주석, 1103/09-04) | +| 비용·부작용 | 몇 줄, 테스트 한 행 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 08-R1 C(disabled)에서 시작 링크에 꺼진 기능의 라우트가 없다 | +| 검증 방법 | `product-feature-switch.test.tsx`에 홈 시작 링크 단언 한 행 | + +### 08-04 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만, 눌러도 아무 일도 없고 아무것도 보이지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 1, 24, 6 | +| 근거 | 1103/08-02 수정(`2d5d41f8`) 전에는 저장 버튼이 `disabled={form.pending || mutationBlocked}`였다. 지금은 `disabled={mutationEffectUnknown}`만이다(`reference-resource-form-page.tsx:124-131`. 생성기 템플릿도 같다, `create-feature-write-slice.ts:693-698`). `mutationBlocked`는 코디네이터의 `mutation-pending`도 포함하고(`reference-resource-form-page.tsx:52-55`) `onSubmit`은 그때 아무것도 하지 않고 돌아간다(`:62-68`). `mutation-pending`은 이 폼이 저장 중이 아닐 때도 생긴다. (1) 저장 중에 화면을 떠났다가 같은 세션에서 돌아온 경우. 저장 중에는 이탈 확인이 꺼지고(`:56`), 코디네이터 채널은 진행 중 시도가 있는 동안 남는다(`application-query.ts:914-918`). (2) "변경됨으로 확인"을 처리하는 동안(`RECONCILING`이 pending으로 표시, `:815-819`). 그동안 feedback에는 진행 표시가 없다(`reference-resource-form-page.tsx:141-183`). 같은 조건에서 취소·초기화 버튼은 꺼진다(`:117`, `:135`). **실행(08-R1 D).** 저장을 걸어 둔 채 "목록으로 돌아가기" → 다시 `/examples/reference-resources/new` → 새 이름 입력: 저장 버튼 켜짐(`disabled=false`, `aria-busy` 없음), 취소 꺼짐, feedback 없음. 저장을 누르면 요청 수는 1 그대로이고 화면 변화가 없다. 첫 저장이 끝난 뒤에도 그 클릭은 실행되지 않았고 아무것도 보이지 않았다 | +| 발생 조건 | 위 (1)·(2). (1)은 저장이 끝나기 전(operation `totalDeadlineMs` 안)에 돌아와야 한다 | +| 영향 | 사용자가 저장을 눌러도 반응이 없다. 진행 중 시도가 끝나면 다시 누를 수 있지만 눌렀던 저장은 실행되지 않는다(08-R1 D). 중복 제출은 여전히 막히므로 데이터 피해는 없다 | +| 심각도·우선순위 | Low · P3 — 짧은 창에서만 생기고 스스로 풀린다 | +| 확실성과 남은 가정 | (1)은 jsdom 실행으로 확인(E2). (2)는 코드 읽기다 | +| 결정의 근거 | 적용 제외 — 1103/08-02 수정이 `disabled`를 `pending`으로 바꾸면서 다른 인스턴스의 진행 중 상태를 알리는 수단을 같이 지웠다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | `mutation-pending`이고 이 폼이 저장 중이 아니면 feedback에 `async.mutationPending`("변경 사항을 저장하고 있습니다.")를 보인다. 또는 그때만 버튼을 끈다(`disabled={mutationEffectUnknown \|\| (mutationBlocked && !form.pending)}`). 포커스를 잃지 않게 하려면 앞쪽이다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 저장 중 포커스 유지(1103/08-02), 중복 제출 차단(`use-app-form.ts:324-325`) | +| 비용·부작용 | 페이지·템플릿 몇 줄, 테스트 한 행 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 08-R1 D에서 다시 마운트한 폼이 진행 중 문구를 보이거나 저장 버튼이 꺼져 있다 | +| 검증 방법 | `reference-page.test.tsx`에 08-R1 D 행 | + +### 3.5 발견으로 올리지 않은 관찰 + +- **15-01 수정의 플랫폼 구성 화면(화면 쪽).** 결함은 찾지 못했다. 제목·릴리스·라우트 표는 곧바로 그린다. 실행부가 필요한 두 곳만 `Suspense` 뒤에 있다(`platform-overview-page.tsx:468-480`, `:526-528`). 요약 칸은 대기 중 "확인 중"을 보이고 칸 수가 같아 자리가 바뀌지 않는다(`:470-478`). 표 자리는 이름 있는 `aria-busy` + `aria-live` 영역이다(`async-surface.tsx:15-37`). 제목 h1이 바로 있어 라우터의 제목 포커스가 그대로다(`starter-platform-overview-route.test.tsx`). 실행부 load는 렌더 중의 dynamic import지만 `ChunkRecoveryBoundary` 안이라 청크 실패는 reload-once 복구로, 그 밖의 실패(기능 사이 중복)는 라우트 경계로 간다(`app-router.tsx:379-397`, `chunk-recovery-boundary.tsx:56-88`). 실패한 load는 캐시에서 지워 다음 방문에 다시 시도한다(`platform-overview-page.tsx:646-658`). load 실패 경로를 보는 테스트는 없다(전에도 없었다). 요약 칸 묶음에는 릴리스 칸(`:422`)과 달리 `aria-live`가 없어 값이 바뀌어도 발표되지 않는다. 정적 화면이라 결함으로 보지 않았다. +- **포커스를 받는 feedback 자리에 역할·이름이 없다**(`page-templates.tsx:73-82`). 안의 `role="status"`·`role="alert"`와 포커스 이동이 겹쳐 두 번 읽힐 수 있다. `2d5d41f8` 본문도 스크린 리더 확인을 하지 않았다고 적었다. 미검증(5절). +- **라우트 모양 키**(1103/08-04 수정)는 끝 슬래시만 지운다. 가운데 `//`(`/shop//items`)는 React Router가 합치지만 키는 그대로다. 오타 두 번이 겹쳐야 생겨 올리지 않았다. +- **지원 참조가 재전송마다 바뀐다**(`use-app-form.ts:392-395`). 지난 라운드 관찰 그대로다. +- **반복 원인.** 이번 새 발견 4건 중 3건(08-01, 08-02, 08-04)은 같은 자리다. 폼 결과(`useAppForm`)와 코디네이터 상태(`useApplicationMutation`)를 페이지가 손으로 합치고, 참조 폼과 생성기 템플릿이 그 합치기를 따로 복사한다. 지난 라운드 5.3절의 (B)(`useAppForm`이 코디네이터 상태를 받아 결과를 하나로 낸다)가 이 셋과 1103/08-01 남은 부분 일부를 함께 줄인다. + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | M3 / M3 | E3 | P — 1103/08-02~08-05 고쳐짐(변이 4종 + 03-R07 모두 잡힘). 복구 버튼 뒤 포커스 유실(08-01, 3엔진), 생성 폼 확인 뒤 무안내(08-02), 홈 시작 링크가 꺼진 기능을 가리킴(08-03), 다른 저장 진행 중 저장 버튼 무반응(08-04) | +| 2 | 구조적 성숙도 | 적용 | M3 / M3 | E2 | O — `check:architecture` 통과(오케스트레이터). presentation이 HTTP를 직접 모른다. 포커스 이동이 페이지가 아니라 `useAppForm`·`FormPage`에 있다 | +| 3 | 변경 용이성 | 적용 | M3 / M1 | E1 | P — locale 목록이 셸에 박혀 있다(0929/08-01 남음) | +| **4** | 인지 부하 | 적용 | — | E2 | P — "선언한 거절 뒤 화면에 무엇이 보이나"를 알려면 계약 칸(`refusedBeforeWrite`) → status별 kind(`backend-envelope.ts:386-392`) → kind별 action(`errors.ts`) → 폼 분기 순서(`use-app-form.ts:217-267`) → 플랫폼 문구 표(`form-contracts.ts:33-64`) → 페이지 feedback 분기를 읽어야 한다. 매뉴얼은 저장이 풀린다는 것만 적고 무엇이 보이는지는 적지 않는다(1103/08-01 남은 부분) | +| **5** | 위험 가시성 | 적용 | M2 / M2 | E2 | P — 선언 목록이 틀리면 중복 위험이 생긴다는 것은 매뉴얼과 조립 검사에 있다(`02-decision-tables.md:183`). 화면은 선언한 400을 "지원 정보 확인"으로 보내 사용자가 거절 이유를 알 수 없다(1103/08-01 남은 부분) | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 거절은 다시 저장된다(08-R1 A1~A4). 선언하지 않은 code와 `RECOVERY_REQUIRED` 뒤 재전송은 막다른 길이다(1103/08-01 남은 부분, 08-R1 A5) | +| 7 | 운영 성숙도 | > | — | — | 영역 09·13 | +| **8** | 디버깅 가능성 | 적용 | M3 / M3 | E2 | P — 상태 실패와 결과 불명에 지원 참조가 있다. 422 불일치가 상태와 참조로 보인다(1103/08-05 고쳐짐, `form-foundation.test.tsx:346-`). `conflict` 결과에는 참조가 없다(`use-app-form.ts:392-395`). 참조가 재전송마다 바뀐다(관찰, 그대로) | +| 9 | 유지보수 성숙도 | 적용 | — | E1 | P — `application-query.ts` 1,004줄(지난 981줄). harness용 LEGACY 분기가 그대로다 | +| 10 | 테스트 성숙도 | 적용 | M3 / M3 | E2 | P — 이번 수정 다섯 개는 모두 테스트에 잡힌다(08-R3, 08-R5~08-R7, 03-R07). 복구 버튼 뒤 포커스(08-01), 홈 시작 링크와 기능 끄기(08-03), 생성 폼 확인 경로(08-02), 다시 마운트한 폼(08-04)을 보는 테스트가 없다. 플랫폼 구성 화면의 load 실패 경로도 테스트가 없다 | +| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 | +| 12 | 동시성 성숙도 | 적용 | M3 / M3 | E2 | P — 중복 제출은 폼(`use-app-form.ts:324-325`)과 `REJECT_WHILE_ACTIVE`가 막는다. 결과 불명 재전송은 같은 키, 키 없는 쓰기는 재전송 없음(0929/03-03 고쳐짐). 다른 인스턴스의 저장이 진행 중일 때 저장 버튼이 켜진 채 조용히 거절한다(08-04) | +| 13 | 확장성 | > | — | — | 영역 09·15·16 | +| **14** | 성능 성숙도 | 적용 | M3 / M3 | E2 | O — FE-GATE-012 PASS, 초기 JS 202,973 / 204,800 gzip B, 26 / 32 파일(오케스트레이터). 여유 1,827 B. 이 영역 수정은 작다(`useEffect` 하나, 홈 링크 계산). 플랫폼 구성 화면은 제목·선언 정보를 먼저 그리고 실행부 표만 기다린다(`platform-overview-page.tsx:468-480`, `:526-528`, `:646-663`). 측정(FE-GATE-026)은 영역 15 | +| **15** | 보안 성숙도 | 적용 | M3 / M3 | E2 | P — 백엔드 message를 그리지 않는다(`form-foundation.test.tsx` "raw backend copy", 422 행). 이번 수정에 새 입력 경로는 없다. 로그인 복귀 주소(0929/08-08) 남음 | +| 16 | 의존성 성숙도 | > | — | — | 영역 13 | +| 17 | API / Contract 성숙도 | 적용 | M3 / M3 | E2 | P — 선언한 code는 VD-04 결정 5(입력 보존·재제출)가 짝 백엔드에서 성립한다. 409 업무 거절을 필드 오류로 보이라는 매뉴얼(`02-decision-tables.md:185`)과 "409는 validation으로 바꾸지 않는다"(VD-04 결정 5)가 갈린다 | +| 18 | 배포 성숙도 | 적용 | M3 / M2 | E1 | O — 플랫폼 구성 화면이 렌더 중에 부르는 dynamic import도 `ChunkRecoveryBoundary` 안에 있어 청크 실패는 reload-once 복구로 간다(`app-router.tsx:379-397`, `chunk-recovery-boundary.tsx:56-88`). 실행 확인은 안 했다 | +| 19 | 설정 성숙도 | 적용 | M2 / M1 | E1 | P — 0929/08-01 남음 | +| 20 | 개발자 경험 | 적용 | — | E2 | P — 기능이 업무 거절 문구를 자기 catalog로 붙일 자리가 없다(1103/08-01 남은 부분). 생성 폼의 확인 경로가 아무것도 보이지 않는다(08-02) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3 | E2 | O — 라우트 모양 키가 라우터 규칙(대소문자, 끝 슬래시)과 맞다(1103/08-04). 키 없는 재전송을 코디네이터와 화면이 둘 다 막는다(0929/03-03). 두 수정 모두 변이에 잡힌다(03-R07, 08-R6) | +| 22 | 추상화 성숙도 | 적용 | — | E2 | P — 폼 결과와 코디네이터 상태를 페이지가 합친다(지난 5.3절 그대로). `form.failure`가 상태 결과에만 있어 `conflict`의 code를 페이지가 못 읽는다. 그 합치기를 참조 폼과 생성기가 따로 복사해 08-01·08-02·08-04가 같은 자리에서 났다(3.5절) | +| **23** | 일관성 | 적용 | — | E2 | P — 셸 탐색은 꺼진 기능을 빼는데 홈 시작 링크는 빼지 않는다(08-03). 참조 폼은 확인 뒤 "저장했습니다."를 보이는데 생성 폼은 아무것도 보이지 않는다(08-02) | +| **24** | 네이밍 / 의미 성숙도 | 적용 | — | E2 | P — 선언한 400 업무 거절에 "요청을 처리할 수 없습니다." + "지원 정보 확인"(1103/08-01 남은 부분). "변경됨으로 확인"이 선언하지 않은 거절을 "저장했습니다."로 바꾼다(같은 항목) | +| 25 | 조직 확장성 | 적용 | — | E1 | P — 필드 거절 문구 표(`form-contracts.ts:33-64`)와 locale 목록이 템플릿 파일에 있어 제품이 템플릿 파일을 고친다 | +| 26 | Ownership 성숙도 | 적용 | — | E1 | ? — 수동 접근성 기록 10건이 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`) | +| 27 | 삭제 가능성 | > | — | — | 영역 09·16. 홈 화면은 예제 기능을 지운 빌드에서 그 라우트를 이름으로 부르지 않는다(`home-page.tsx:15-23`) | +| 28 | 회복 가능성 | 적용 | M3 / M2 | E3 | P — 선언한 거절 뒤 화면 안에서 고쳐 다시 저장된다(08-R1 A1~A4). 선언하지 않은 거절은 여전히 거짓 성공 버튼과 끝나지 않는 재전송만 남는다(08-R1 A5). 복구 버튼 뒤 포커스가 `body`다(08-01) | + +## 5. 미검증 + +- **브라우저에서 돌리지 않은 것.** 08-03(홈 링크)과 08-04(다시 마운트)는 jsdom에서만 확인했다. 08-01만 3엔진에서 확인했다. +- **실제 스크린 리더.** 포커스된 feedback 자리(역할·이름 없음)를 어떻게 읽는지, 그 안의 `role="status"`·`role="alert"`와 겹쳐 두 번 읽히는지 확인하지 않았다. 수동 접근성 기록 10건은 모두 `pending-manual-review`다(`artifacts/tests/a11y-manual/*.md`). +- **생성기로 만든 기능 폼.** 생성 명령을 돌려 결과 파일을 보거나 실행하지 않았다(08-02, 3.0절 생성기 행). 템플릿 문자열만 읽었다. +- **짝 백엔드.** 실제로 띄우지 않았다. 도메인 거절 뒤 같은 키 재전송이 `500 IDEMPOTENCY_RECOVERY_REQUIRED`가 된다는 것은 지난 라운드의 백엔드 코드 읽기이고, 이번에 다시 읽지 않았다(백엔드 HEAD `45d2a478`). 08-R1 A5는 그 응답을 흉내 냈다. +- **플랫폼 구성 화면의 load 실패 경로**(기능 사이 중복, 실행부 청크 실패). 코드만 읽었다. 측정(FE-GATE-026)은 영역 15다. +- **영역 밖 게이트 실패.** `verify:documentation` rc=1(짝 백엔드 문서 경로), FE-GATE-013 rc=1(security). 이 영역 판정에 쓰지 않았다. + +## 6. 실행 기록 + +리뷰어가 직접 돌린 desktop 실행은 0건이다. 처음 넣은 `08-vt`·`08-pw`는 잠금을 기다리는 동안 ssh가 끊겨(rc 255) 시작하지 못했고, 19:55에 별도 실행이 닫혔다(`BRIEF-2.md`). 노트북에서는 읽기와 `git apply --check`(상태를 바꾸지 않음)만 했다. 아래는 오케스트레이터가 한 배치로 돌린 결과다(`scratchpad/r4/results/08/`, 20:02~20:08, 부하 2.0~4.5). 매 항목 전후로 checkout을 `8a44226`으로 되돌렸고 모두 `restore=clean`이다. 요청과 패치는 `scratchpad/r4/requests/08.md`, `scratchpad/r4-08/patch/`. + +| ID | 명령 | 변이 | rc·시간 | 결과 | +|---|---|---|---|---| +| 08-R1 | `node scripts/run-vitest.ts run tests/features/reference-feature/probe-08-r4.test.tsx` | probe 파일 추가 | 0 · 8초 | 11 passed. 관찰은 아래 표 | +| 08-R2 | `corepack pnpm exec playwright test tests/e2e/probe-08-r4-focus.spec.ts --project=chromium --project=firefox --project=webkit --reporter=list` | spec 추가 | 0 · 13초 | 9 passed. 9건 모두 `after=BODY tab=이름 입력란`, 재전송 3건 `keysSame=true` | +| 08-R3 | `… run tests/features/reference-feature/reference-page.test.tsx` | M1 `use-app-form.ts:100` 포커스 제거 | 1 · 16초 | 기대대로. 2 failed / 21 passed: "moves focus to the failure status after a keyboard save ('unknown')", "('rate-limited')" — `toHaveFocus` 실패 | +| 08-R4 → 03-R07 | `… run tests/component/application-mutation-admission.test.tsx tests/component/async-surface.test.tsx` | 영역 03 M08(= 이 영역 M3, `application-query.ts:842` 키 조건 제거) | 1 | 기대대로. 1 failed / 50 passed: "offers no resend for an unknown request that carries no key" — `expected true to be false`. `async-surface.test.tsx`는 상태를 직접 만들어 통과(화면 쪽 조건은 그 파일의 "draws no resend …"가 본다) | +| 08-R5 | `… run tests/component/form-foundation.test.tsx` | M5 `form-contracts.ts:77` `hasOwn` → `!== undefined` | 1 · 3초 | 기대대로. 4 failed / 27 passed: `constructor`·`toString`·`__proto__`·`hasOwnProperty` 행, "요청한 문구를 표시할 수 없습니다." ≠ "입력값을 확인해 주세요." | +| 08-R6 | `… run tests/architecture/context-route-roots.test.ts` | M6 `deployable-app-module.ts:120` `.toLowerCase()` 제거 | 1 · 1초 | 기대대로. 1 failed / 24 passed: "rejects two feature routes whose paths differ 'only by letter case'" — throw 없음 | +| 08-R7 | `… run tests/component/form-foundation.test.tsx` | M8 `backend-envelope.ts:221` 422 → 항상 필드 | 1 · 4초 | 기대대로. 1 failed / 30 passed: "shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status, not an input error" | + +변이 없는 대조는 게이트 출력이다: `tests/component`는 `gates/test_component.log`(40 / 270 통과), `tests/features`·`tests/architecture`는 snapshot `artifacts/tests/coverage.xml`(FE-GATE-005, 3,869건 실패 0, 그중 `reference-page.test`·`context-route-roots` 48건). 변이 넷과 03-R07 모두 변이 없는 실행은 통과, 변이 실행은 기대한 테스트가 기대한 이유로 실패했다. + +08-R1 관찰(참조 폼, 실제 `AppRouter`·코디네이터, gateway 결과만 주입): + +| 경우 | 거절 직후 | 값 고친 뒤 다시 저장 | +|---|---|---| +| A1 선언한 409 `POSTER_ALREADY_EXISTS`(`CONFLICT`, `NOT_APPLIED`) | 요약 "입력 내용을 확인해 주세요. 다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.", feedback "충돌을 해결한 뒤 다시 제출할 수 있습니다.", 저장 켜짐, 포커스 feedback | 키 `key-1` → `key-2`, "저장했습니다." | +| A2 선언한 400 `WORKLOG_INVALID`(`UNKNOWN_CLIENT_FAILURE`) | feedback "요청을 처리할 수 없습니다. / 지원 정보 확인 / 지원 참조: corr-a2", 저장 켜짐, 포커스 feedback | `key-2`로 저장 | +| A3 선언 + `mapProblem` 필드 `DUPLICATE` | 요약 "새 항목 이름: 입력값을 확인해 주세요.", `aria-invalid="true"`, 포커스 이름 입력란 | `key-2`로 저장 | +| A4 생성기 모양 필드 `INVALID` | 요약 "새 항목 이름: 올바른 값을 입력해 주세요.", 포커스 이름 입력란 | `key-2`로 저장 | +| A5 선언하지 않은 409(`MAYBE_APPLIED`) → 재전송 2회 `500 IDEMPOTENCY_RECOVERY_REQUIRED` | "변경 결과를 확인할 수 없습니다." + "변경됨으로 확인" + "같은 요청으로 다시 보내기", 저장 꺼짐 | 재전송 키 `key-1` 3회, 세 번 모두 같은 화면과 같은 버튼 | +| B1·B2·B3 확인 / 재전송 성공 / 429 뒤 다시 시도 성공 | 복구 버튼에 포커스 | 끝난 뒤 `document.activeElement` = `BODY`(셋 모두) | +| C 기능 켜짐 / 꺼짐 | 시작 링크 셋 같음. 꺼짐이면 셸 탐색에서 `/examples/ui`·`/examples/states`·`/examples/auth`가 빠짐 | 꺼짐에서 둘째 링크 → 사용 중지 화면 | +| D 저장 중 이탈 → 복귀 | 저장 켜짐, 취소 꺼짐, feedback 없음 | 클릭해도 요청 1 그대로, 화면 변화 없음 | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 08-01 | Low · P3 | 확인된 결함 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 버튼이 사라지며 포커스가 `body`로 떨어진다 | `src/presentation/forms/use-app-form.ts:91-101`, `:176-195`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:141-183` | +| 08-02 | Low · P3 | 확인된 결함 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | `scripts/create-feature-write-slice.ts:703-721`, `:714` | +| 08-03 | Low · P3 | 확인된 결함 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다(`b96d61d8`) | `src/presentation/pages/home-page.tsx:21-23` vs `src/presentation/layouts/app-shell.tsx:196-202` | +| 08-04 | Low · P3 | 확인된 결함 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다(`2d5d41f8`) | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:52-68`, `:124-131` | + +이월(새로 세지 않음): 1103/08-01(= 03-01) 일부, 0929/08-01 남음, 0929/08-08 남음. diff --git a/docs/reviews/2026-11-05-maturity-review/09-app-core.md b/docs/reviews/2026-11-05-maturity-review/09-app-core.md new file mode 100644 index 00000000..8f350e69 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/09-app-core.md @@ -0,0 +1,206 @@ +# 영역 09 — 애플리케이션 코어·기능·조립 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`. 09-03 판정에 필요한 만큼 `recipes/session-owners/`, `docs/manual/04-paired-backend-session.md`, `tests/unit/product-extension-typecheck.test.ts`도 읽었다. +> 깊게 본 관점: 3, 6, 10, 15, 20, 21, 22, 25 +> 렌즈: 지난 라운드 09-01~09-11 수정이 완료 기준까지 갔는가, 그 수정이 검사를 약하게 하거나 다른 결함을 만들었는가, 다운스트림(제품 소유 파일을 채운 상태)에서도 템플릿 테스트가 통과하는가, 부팅 경로가 예전에 거절하던 것을 받게 됐는가 +> 영역 판정(35.8): **조건부 사용 가능.** 지난 11건 중 8건은 코드와 테스트로 닫혔다. 조건은 넷이다. (1) 기능에 제품 capability를 주는 다운스트림은 이 커밋을 받으면 `test:unit`(FE-GATE-005)이 템플릿 테스트 하나로 실패한다(09-01). (2) 짝 백엔드 Redis session 모드는 recipe와 매뉴얼대로 이으면 서버 401이 세션에 닿지 않는다. `onCredentialRejected`를 제품이 직접 잇는다(09-02). (3) 짝 백엔드 실제 연동은 아무도 확인하지 않았다. realm public client와 Redis 모드 로그인 엔드포인트는 제품 몫이다(1103/09-03 일부). (4) 플랫폼 구성 화면은 끌 수 없고, 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 일부). SW `blockers`·`observe` 연결은 템플릿 파일을 고친다(1103/09-05 일부). + +## 0. 결론 + +- 지난 라운드 이 영역 발견 11건: 고쳐짐 8(09-01, 09-02, 09-06~09-11), 일부 3(09-03, 09-04, 09-05). 이월 둘은 일부 1(0925 FOLLOW-UP 09-07), 남음 1(0925 FOLLOW-UP 09-08, 허용한 대안). 틀린 발견은 없다. +- 09-01·09-08 수정은 변이로 지켜진다. 수정 전 동작으로 되돌리면 테스트 4건이 실패한다(09-mut). 수정 전후의 테스트 diff에 느슨해진 단언·skip·상한 증가는 없다(3절 머리). +- 부팅 쪽 검사는 약해지지 않았다. `load-release-manifest.ts`, `contract-set.ts`, `load-runtime-config.ts`, `release-artifacts.ts`, `runtime-config-schema.ts`는 `e40684b`와 같다. 16-09 수정은 커밋된 dev manifest를 다시 쓰는 쪽만 바꿨다. 부팅이 새로 받게 된 것은 "제품 provider가 낸 자격증명의 401은 세션을 로그아웃시키지 않는다" 하나다(1103/09-01 수정, 의도된 변경). 이것이 09-02를 만들었다. +- 새 발견 09-01: 09-02 수정이 더한 타입 검사 탐침이 복사본의 `product-composition.ts`·`product-contracts.ts`를 탐침 내용으로 덮어쓴다. 그래서 제품 capability를 기능에 주는 다운스트림에서는 그 capability가 사라져 app 타입 검사가 실패한다(09-probe-downstream). 두 다운스트림 모두 제품 capability를 쓴다(`CHANGELOG.md:57`). +- 새 발견 09-02: 1103/09-01 수정(401을 자격증명을 낸 쪽에만 알림)과 1103/09-03 recipe(쿠키 세션 owner)가 다른 브랜치에서 들어와 맞지 않는다. 쿠키 모드의 모든 operation은 제품 provider 프로필이라, 서버 401이 세션 owner에 가지 않는다. recipe와 매뉴얼은 "서버 401 → unauthenticated"라고 적는다(09-cookie401). +- 새 발견 09-03: 1103/09-07 수정과 1103/14-06 수정이 둘 다 원인을 붙여, `check:registries` 출력에 같은 원인이 두 번 나온다(Low). +- 401과 계정 전환이 겹치는 경쟁(지난 1.2 미확인)은 코드로는 실행기가 막는다. 응답 admission(401 본문 cancel 포함)이 scope fence와 경쟁하고, fence가 이기면 결과가 `SCOPE_FENCED` 위반(`CONTRACT_VIOLATION`)이라 조립 루트가 401을 알리지 않는다(`src/adapters/http/http-execution-v3.ts:1088-1114`). 09-R1(배치)에서 `R4-09 race: switched=true outcome=CONTRACT_VIOLATION previousScopeCurrent=false subject=user-b notify=0`. 발견 없음. +- 새 발견: Medium 2 · Low 1. P1 1 · P2 1 · P3 1. 확인된 결함 3. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` | +| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽었다. 실행은 desktop checkout에서 공유 잠금 helper(`/tmp/claude-gates/r4/exp.sh`)로 19:43에 4개를 돌렸다. 그 뒤 helper가 닫혀(BRIEF-2) 남은 1개는 오케스트레이터 배치(09-R1, 20:08)로 돌렸다. 2026-11-05 19~20시 | +| 목적과 지원 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 짝 백엔드 `clean-architecture-backend-template` `45d2a478`(읽기만) | +| 필수 요구와 규모·운영 목표 | 두 템플릿을 짝으로 빨리 출시. 다운스트림(tech-log, memento)이 템플릿을 동기화한다. 정량 운영 목표 없음 | +| 읽은 코드·구성 범위 | `src/bootstrap/` 전체(`runtime-adapters.ts` 280~720행, `product-composition{,-contract}.ts`, `product-session-owner-context.ts`, `session-owner-fetch.ts`, `optional-runtime-host.ts`, `load-release-manifest.ts` 계약 집합 부분), `src/features/` 최상위 파일 전부와 `platform-examples-feature/`, `local-draft-feature/`, `src/apps/`, `src/contexts/`, `src/application/ports/auth-session-port.ts`·`view-models/async-state.ts`·`result.ts`. 연결 확인: `src/adapters/auth/external-session-adapter.ts`, `src/adapters/http/http-execution-v3.ts`(401·scope·admission 부분), `src/adapters/http/feature-http-binding.ts:464-467`, `src/presentation/providers/session-provider.tsx`, `src/contracts/{routes,env,product-contracts,external-contract-runtime,contract-set}.ts`, `recipes/session-owners/*.ts`, `scripts/{generate-product-feature-index,write-dev-release-manifest,test-sample-removal,test-feature-scaffold,check-registries,create-feature-write-slice}.ts`, `tests/unit/{product-extension-typecheck,dev-release-manifest,runtime-adapters*}.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, `docs/manual/{02,03,04}*.md`, `docs/architecture/{starter-experience,optional-adapter-recipes}.md`, `config/ci/gates.json`(FE-GATE-005·007). `git diff e40684b..8a44226 -- <영역 경로>` 32파일 전부와 영역 커밋 31개의 본문 | +| 수행한 테스트·실험 | 6절. desktop 실행 4개: `09-ctrl`(변이 없음), `09-mut`, `09-cookie401`, `09-probe-downstream`. `09-race401`은 잠금 대기 중 취소돼 오케스트레이터 배치 09-R1로 돌렸다. 전체 게이트는 다시 돌리지 않고 오케스트레이터 결과를 인용했다(6절 끝) | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/09-app-core.md` 09-01~09-11과 2절의 이월 항목, README 10.3(07-05 → 09-10), 14.4·14.6. README 14.4는 주장으로만 읽었다. 각 항목을 현재 코드와 이번 실행으로 다시 판정했다(2절) | + +오케스트레이터 게이트 결과(`desktop:/tmp/claude-gates/r4/merge-48/`, `gates/`)는 이 문서를 쓰는 동안 채워지는 중이었다. 6절 끝에 그 내용을 적었다. snapshot(`r4/snap/`)은 읽지 않았다(이 영역 판단에 필요한 출력이 게이트 로그에 있었다). + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/09-01 | 자격증명을 싣지 않은 요청의 401도 세션을 로그아웃시킨다 | **고쳐짐** (이 수정이 새 결함 09-02를 만들었다) | `reportServerUnauthenticated`가 `attachCredentials`와 같은 순서로 401의 주인을 가른다(`src/bootstrap/runtime-adapters.ts:577-593`, 호출 `:647-652`). ANONYMOUS면 아무에게도, 제품 provider 프로필이면 `onCredentialRejected`에, 나머지는 세션에 알린다. 완료 기준(ANONYMOUS 두 경우 세션 유지·알림 0회·scope 유지, bearer 대조군 1회)을 `tests/unit/runtime-adapters-auth-profile.test.ts:371-441`이 그대로 본다. provider 경로는 `runtime-adapters-credential-order.test.ts:357-420`. **09-mut**: 함수 첫 줄을 수정 전 동작(`authSession.onUnauthenticated()` 후 return)으로 바꾸면 3건 실패. 지난 1.2의 "401과 계정 전환 경쟁"은 코드로는 실행기가 막는다(`http-execution-v3.ts:1088-1114`). 09-R1에서 이전 scope의 401이 새 사용자에게 닿지 않음을 확인했다(6절) | +| 1103/09-02 | 제품 확장 지점의 타입 검사 경로가 막힌다 | **고쳐짐** (템플릿 상태). 수정이 더한 탐침이 다운스트림에서 실패한다(새 09-01) | capability 타입은 제품 소유 `src/features/product-capabilities.ts:28`에 두고 `FeaturePlatformCapabilities`가 extends한다(`src/features/feature-adapter-contribution.ts:9`, `:56-62`). 그래서 node 프로그램에도 보인다. 템플릿 테스트는 `testRuntimeConfig`로 제품 기본값을 실제 스키마에서 채운다(`tests/helpers/runtime-config.ts:31-58`). 완료 기준(문서 위치 보강 + `.default()` 키로 tsc 3종 통과)을 `tests/unit/product-extension-typecheck.test.ts:164-212`가 실제 파일로 확인한다. **09-ctrl**에서 통과 | +| 1103/09-03 | 짝 백엔드 인증 방식에 맞는 세션 owner가 없다 | **일부** | 생긴 것: OIDC PKCE owner(`recipes/session-owners/oidc-pkce-session-owner.ts`, 651행)와 쿠키 owner + CSRF provider(`cookie-session-owner.ts`, 199행), owner context의 시간 제한 fetch·page·redirectStorage(`src/bootstrap/product-session-owner-context.ts:80-102`, `session-owner-fetch.ts:128-194`), 매뉴얼 04, 조립 루트를 지나는 테스트(`tests/recipes/session-owners-runtime.test.ts`, 09-ctrl 통과). 남은 것: ① 완료 기준인 실제 Keycloak 로그인·Redis 쓰기 1회는 아무도 하지 않았다(README 14.4 "실제 Keycloak·Redis 연동 미확인"). ② 백엔드 realm에는 confidential client `ca-skeleton-api` 하나뿐이다(백엔드 `45d2a478` `infra/keycloak/realms/ca-skeleton-realm.json:59-65`). Redis 모드 로그인·세션 조회 엔드포인트도 없다. 둘 다 제품 몫으로 적었다(`docs/manual/04-paired-backend-session.md:192-200`). ③ 쿠키 모드에서 서버 401이 owner에 닿지 않는다. 이것은 1103/09-01 수정과 맞물린 다른 결함이라 새 09-02로 센다 | +| 1103/09-04 | 플랫폼 예제 화면 4개를 끌 자리가 없다 | **일부** (결정 대기) | 셋은 기능으로 옮겼다(`src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/context-module.ts:9-12`). 남은 것: ① `EXAMPLES_PLATFORM`은 플랫폼 레지스트리에 고정이다(`src/contracts/routes.ts:33-45`). FE-GATE-028 서명 대상이고 기록은 `pending-manual-review`다(`artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md:3`). 옮기면 lab이 443 ms로 FAIL이라 남겼다(`b96d61d8` 본문). ② 예제 기능을 빼면 예제 화면을 자기 페이지로 쓰는 브라우저 spec 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`)를 제품이 고치거나 지운다(`docs/architecture/starter-experience.md:122-125`). 완료 기준 "템플릿 파일 diff 0"에 못 미친다 | +| 1103/09-05 | SW 등 선택 런타임을 켜는 일이 제품 확장 지점 밖에 있다 (흡수: 1101/09-05) | **일부** | 선택 상수 넷은 제품 소유 파일로 옮겼다(`src/features/product-capabilities.ts:30-43`). 템플릿 파일은 검사·투영만 한다(`src/features/installed-runtime-capabilities.ts:36-46`). 매뉴얼 03 "SW 켜기"가 생겼다(`docs/manual/03-outside-feature-folder.md:128-154`). 남은 것: `blockers`·`observe` 연결은 여전히 템플릿 소유 `src/bootstrap/create-runtime-composition.ts`를 고친다(같은 매뉴얼 `:154`, `docs/architecture/optional-adapter-recipes.md:134-146`). realtime·worker·offline은 여전히 "Connect a runtime in src/bootstrap/optional-runtime-host.ts"로 거절된다(`src/bootstrap/optional-runtime-host.ts:60-64`) | +| 1103/09-06 | 참조 기능이 짝 백엔드 응답 모양이 아니다 | **고쳐짐** (대안 B) | README 14.6의 결정은 생성 명령 확장으로 났다. `create:feature --with-create [--keyed]`가 짝 백엔드 생성기와 같은 Envelope 쓰기 slice를 만든다(`scripts/create-feature-write-slice.ts`). 생성 테스트가 KEYED 생성·503 재전송·409 `IDEMPOTENT_IN_FLIGHT`·400 필드 오류를 본다(`:898-921`, `:971`). 생성 드릴이 이 slice를 만들고 게이트를 돈다(`scripts/test-feature-scaffold.ts:41`, `:62-70`). 참조 기능은 problem details 예제로 남는다(`src/features`의 `responseEnvelope` 0건). 드릴 실행 결과는 오케스트레이터 FE-GATE-020에 있다(6절) | +| 1103/09-07 | 제품 인증 프로필 id 오타 시 원인 없는 메시지, 문서가 사라진 메시지를 약속 | **고쳐짐** (부작용: 새 09-03) | message에 reason을 싣는다(`src/contracts/external-contract-runtime.ts:290-297`). 테스트가 operation·프로필 id를 본다(`tests/unit/second-api-feature-registries.test.ts:279-293`). 문서 문구가 실제 출력과 같다(`docs/manual/02-decision-tables.md:245`, `docs/architecture/starter-experience.md:224`). 옛 문구 grep 0건(docs/manual·docs/architecture·src·scripts) | +| 1103/09-08 | `needs` 좁히기가 타입에서만 (이월: 1101/09-08) | **고쳐짐** | `invokeContribution`이 `needs`의 키만 골라 frozen 객체로 넘긴다(`src/features/feature-adapter-contribution.ts:154-161`). 주석 두 곳(`runtime-adapters.ts:682`, `scripts/create-feature.ts:1027`)이 이제 맞다. 테스트 `tests/contract/reusable-capability/feature-adapter-composition.test.ts:166`. **09-mut**: 전체 context를 넘기도록 되돌리면 그 1건 실패 | +| 1103/09-09 | `NOT_INSTALLED` 다의, 표시와 선언이 함께 있어도 설치 (이월: 1101/09-04) | **고쳐짐** | 표시 이름 `NOT_A_FEATURE`(`scripts/generate-product-feature-index.ts:284`), 함께 있으면 실패(`:316-320`), 옛 이름 거절. 테스트 `tests/scripts/generate-product-feature-index.test.ts:167-192`(09-ctrl 통과). 런타임 상태 `NOT_INSTALLED`는 그대로다(`README.md:124`) | +| 1103/09-10 (+ 07-05) | V2 삭제 뒤 기능 실행부 모양 설명 네 곳 | **고쳐짐** | `git grep -nE "V2 API registr\|runtime schemas, mappers\|runtime schemas and mappers" -- src docs/architecture` 0건. `src/features/feature-module.ts:12-14`, `installed-feature-contracts.ts:12-14`가 지금 모양을 적는다 | +| 1103/09-11 | 세션 복구 버튼이 `recover()` 결과를 버린다 | **고쳐짐** | `"no-session"`이면 owner가 다음에 알릴 때까지 화면이 `unauthenticated`로 본다(`src/presentation/providers/session-provider.tsx:36-62`). 계약에 전이 표를 적었다(`src/application/ports/auth-session-port.ts:1-16`, `:46-55`, `src/adapters/auth/external-session-adapter.ts:25-36`). `tests/component/session-recovery.test.tsx` 4건(09-ctrl 통과) | +| 0925 FOLLOW-UP 09-07 | 샘플 제거 드릴이 lint·`check:i18n`·e2e를 건너뜀 | **일부** | lint, `verify:documentation`, `check:i18n`, `check:design-system`이 더해졌다(`scripts/test-sample-removal.ts:434-441`). e2e·시각 테스트는 여전히 돌리지 않는다(`b96d61d8` 본문 "제거 드릴은 브라우저 테스트를 돌리지 않아 이것을 보지 않는다"). 위 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` 표시로 기능이 아니다 | +| README 14.6 결정 (참조 기능 Envelope 이행) | 결정 기록 없음 | **고쳐짐** | 1103/09-06과 같다. 생성 명령 확장(B)으로 결정됐다(README 14.4 "그 밖의 81건 고침", 커밋 `2ec9d560`) | +| (영역 16) 1103/16-09 — 부팅 쪽만 | dev server의 고정 contract set | **부팅 검사 약화 없음** | 수정 `799ab7f`은 `scripts/write-dev-release-manifest.ts:17-25`, `scripts/create-feature.ts`, `scripts/test-sample-removal.ts`, `tests/unit/dev-release-manifest.test.ts`, `vite.config.ts`만 바꿨다. 부팅 검사(`src/bootstrap/load-release-manifest.ts:296-305`, `src/contracts/contract-set.ts:64-110`)는 `e40684b`와 같다(`git diff --stat` 0). 테스트는 커밋된 `contractSet` 전체(digest 포함)를 설치된 기능의 값과 비교한다(`dev-release-manifest.test.ts:17-26`). 09-ctrl 통과 | + +## 3. 이번 발견 (36.3) + +요약: Medium 2 · Low 1. P1 1(09-01) · P2 1(09-02) · P3 1(09-03). 확인된 결함 3. + +검사 약화 점검(브리프 4절): `git diff e40684b..8a44226`의 영역 테스트에서 지운 단언은 셋이다. `context-route-roots.test.ts:193-210`은 예로 쓴 라우트를 `EXAMPLES_UI`에서 아직 플랫폼인 `EXAMPLES_PLATFORM`으로 바꿨다(같은 단언). `second-api-feature-registries.test.ts`의 생성 단언은 helper로 옮겼다. `reference-page.test.tsx`의 "저장 중 버튼 disabled"는 aria-busy·focus 단언으로 바뀌었고 호출 1회 단언은 남았다(08 영역 08-02). `runtime-adapters.test.ts:58-70`의 `API_FEATURE_IDS`는 API 없는 예제 기능을 빼지만, 기준 커밋에서도 API 있는 기능은 참조 기능 하나였다. skip·quarantine·timeout·상한 증가는 영역 경로에 없다. 약화로 센 것은 없다. + +### 09-01 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 탐침 내용으로 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서는 `test:unit`이 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 25, 3, 20, 13(제품 수 축) (30.3, 30.4) | +| 근거 | 탐침은 저장소 복사본에서 `src/contracts/product-contracts.ts`와 `src/bootstrap/product-composition.ts`를 통째로 탐침 내용으로 쓴다(`tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`). capability 타입만 제품 선언 끝에 덧붙인다(`:35-39`, `:180-182`). 탐침의 `composeProduct`는 `typecheckProbeSettings` 하나만 돌려준다(`:74-82`). 조립 루트는 `composeProduct`의 capability를 기능 로더에 넘긴다(`src/bootstrap/runtime-adapters.ts:689-697`). 로더의 context 타입은 설치된 기능들이 `needs`에 적은 키를 모두 요구한다(`src/features/installed-feature-adapters.ts:21-27`, `:48-49`, `feature-adapter-contribution.ts:124-129`). 그래서 제품이 문서대로 capability를 타입에 적고(`docs/manual/03-outside-feature-folder.md:105`) `product-composition.ts`에서 돌려주고 자기 기능의 `needs`에 적으면, 복사본에서는 값이 사라져 app 프로그램이 실패한다. **09-probe-downstream**: 제품 소유 파일 두 개(`product-capabilities.ts`에 `r4NoticeSettings` 타입, `product-composition.ts`가 그 값을 돌려줌)와 제품 기능·context 폴더(`needs: ["r4NoticeSettings"]`)만 더했다. 그 상태의 저장소는 `check:types:app`·`:node`·`:test`가 모두 rc=0이다. 탐침은 실패한다: `tsconfig.app.json: … /tmp/product-extension-typecheck-T7Vx60/src/bootstrap/runtime-adapters.ts(695,5): error TS2741: Property 'r4NoticeSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …; http…`. 변이 없는 09-ctrl에서는 탐침이 통과한다 | +| 발생 조건 | 다운스트림이 이 커밋 이후로 동기화하고, 제품 capability를 하나 이상 기능에 준다. CHANGELOG가 두 다운스트림의 capability를 적는다: memento `offsetUpload`·`runtime`, tech-log Studio 소스·HTTP(`CHANGELOG.md:57`) | +| 영향 | merge 게이트 FE-GATE-005(`test-unit`, `config/ci/gates.json:1840-1848`)가 코드와 무관하게 항상 실패한다. 통과시키려면 템플릿 테스트를 고치거나 지운다. 동기화마다 충돌 자리가 된다. 1103/09-02 수정의 목적("제품 소유 파일만 고치고 템플릿 게이트 통과")이 첫 제품 capability에서 다시 깨진다. 실패 메시지는 복사본 경로의 TS 오류라 원인(탐침이 파일을 덮어씀)을 말하지 않는다 | +| 심각도·우선순위 | Medium · P1 — 사용자 피해 없는 "merge 게이트 항상 실패"(지난 라운드 02-06·12-01과 같은 눈금). 동기화 직후 두 다운스트림 모두에 해당한다 | +| 통제·증거 | 목표 M3(탐침이 제품 파일을 보존한 채 실행) / 확인 M0(다운스트림 상태를 보는 검사 없음) · E3(09-probe-downstream, 실제 tsc) | +| 확실성과 남은 가정 | 다운스트림 상태를 desktop 복사본에서 만들어 재현했다. 실제 tech-log·memento에 이 커밋을 넣어 보지는 않았다. 제품 capability를 기능에 주지 않는 제품은 통과한다. 같은 모양의 다른 경우(추론, 실행 안 함): 탐침 context가 소유 앱을 `template-app`으로 고정한다(`tests/unit/product-extension-typecheck.test.ts:152-156`). 앱 id를 바꾼 제품에서는 생성기가 "Context typecheck-probe-context belongs to undeclared app template-app"으로 멈출 것이다(`scripts/generate-product-feature-index.ts:357-358`) | +| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `235143c` 본문이 "product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔 쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 … 타입 오류가 날 수 있다"를 위험으로 적었다. CHANGELOG는 "제품의 capability 선언을 덮어쓰지 않는다"고 적는다(`CHANGELOG.md:249`). 리뷰어 추론: 선언(타입)은 지켰지만 값(`composeProduct`)을 덮어써, 선언한 capability를 실제로 쓰는 제품이 막힌다. X2 #1이 고치려던 바로 그 제품이다 | +| 이해 비용 | 제품 개발자는 실패한 tsc 출력이 임시 복사본(`/tmp/product-extension-typecheck-*`)의 `runtime-adapters.ts`를 가리키는 이유를 탐침 소스를 읽어야 안다 | +| 최소 개선 방향 | 탐침이 제품 파일 내용을 버리지 않는다. (가) 복사본 안에서 원래 `product-composition.ts`를 다른 이름으로 옮기고, 새 파일이 원래 `composeProduct` 결과를 펼친 뒤 탐침 capability를 더한다. `product-contracts.ts`도 원래 필드를 펼친 뒤 탐침 키·행을 더한다. 또는 (나) 제품 파일이 출하 상태(빈 값)가 아니면 탐침을 건너뛴다. 그 상태의 타입 경로는 제품 자신의 `check:types`가 본다 | +| 대안 비교 | (A) 현 상태: 템플릿에서는 통과, 다운스트림 실패. (B) (가): 다운스트림에서도 같은 검사를 한다. 제품 파일의 export 이름(`composeProduct`, `PRODUCT_*`)에 기댄다. 그 이름은 계약이라 바뀌지 않는다. (C) (나): 더 단순하다. 탐침의 목적(템플릿 테스트와 node 프로그램이 제품 키·capability를 받아들임)은 출하 상태에서 이미 확인된다. 다운스트림 상태의 확인은 잃는다. (D) 다운스트림이 동기화 때 탐침을 지우게 문서화: 충돌 자리가 남는다 | +| 단순화의 보존 조건 | 템플릿 출하 상태에서 tsc 3종을 실제 파일로 돈다. `.default()` 제품 키와 node 프로그램에 보이는 capability 타입을 계속 본다. 예약 이름 `typecheck-probe-*` 충돌 검사(`:171`)는 남긴다 | +| 비용·부작용 | 테스트 파일 하나 수십 줄 | +| 재검토 조건 | 제품 소유 파일이 늘거나, 다운스트림이 템플릿 테스트를 따로 고르는 방식으로 바뀌면 | +| 완료 기준 | 09-probe-downstream 상태(제품 capability + 그것을 쓰는 제품 기능)에서 탐침 통과. 템플릿 출하 상태에서도 통과 | +| 검증 방법 | 09-probe-downstream 변이를 테스트 안 픽스처로 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음(신규) | + +### 09-02 짝 백엔드 Redis session 모드를 recipe와 매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 6, 28, 15, 17, 22, 4, 5, 10, 9 (32 세션 만료, 30.5) | +| 근거 | 1103/09-01 수정 뒤 조립 루트는 제품 provider 프로필의 401을 세션에 알리지 않고 선택 hook `onCredentialRejected`만 부른다(`src/bootstrap/runtime-adapters.ts:583-591`, 계약 `src/bootstrap/product-composition-contract.ts:111-120`). 쿠키 recipe에서는 모든 operation이 provider 프로필이다. owner의 `attachCredential`은 항상 throw하고 `SESSION_COOKIE_*` 프로필을 쓰라고 한다(`recipes/session-owners/cookie-session-owner.ts:163-167`, provider `:181-199`). 매뉴얼의 연결 예시는 `credentialProviders`만 돌려주고 `onCredentialRejected`가 없다(`docs/manual/04-paired-backend-session.md:238-246`). recipe와 매뉴얼은 반대를 적는다: "a server 401 signs out"(`cookie-session-owner.ts:33`), "its 401 reaches the owner"(`:179`), "서버 401 → [unauthenticated]"(매뉴얼 `:186`), "서버의 401은 owner에게 간다"(`:249`). hook을 이으려 해도 `ProductCompositionContext`에 세션이나 owner가 없다(`product-composition-contract.ts:81-91`). owner는 다른 함수 `composeProductSessionOwner`에서 만들어지므로 제품은 모듈 변수로 둘을 이어야 한다. 이 방법은 어디에도 없다(`git grep onCredentialRejected` → CHANGELOG·매뉴얼 02·계약·테스트뿐). 두 변경은 다른 브랜치에서 만들어져 `c17b3a05`·`b029dcc0`로 합쳐졌다. 조립 루트를 지나는 recipe 테스트는 쿠키 모드의 401을 보지 않는다(`tests/recipes/session-owners-runtime.test.ts:342-396`). owner 단위 테스트는 `notifyUnauthenticated`를 직접 불러, 조립 루트가 그것을 부른다고 가정한다(`tests/recipes/cookie-session-owner.test.ts:121-133`). **09-cookie401**: 같은 테스트 파일의 조립 루트와 매뉴얼 4.3 연결 그대로, 세션 조회는 200(`user-1`), API는 401로 답하게 했다. 읽기(`SESSION_COOKIE_READ`)·쓰기(`SESSION_COOKIE_WRITE`) 모두 `outcome=UNAUTHENTICATED sent=true credentials=include state=authenticated scopeCurrent=true`. 매뉴얼이 적은 `unauthenticated`를 단언한 두 테스트가 `expected 'authenticated' to be 'unauthenticated'`로 실패했다. 같은 파일의 기존 4건은 통과했다 | +| 발생 조건 | 짝 백엔드 `APP_SECURITY_AUTH_MODE=redis-session`에서 서버 세션이 끝난다(Redis TTL 만료, 다른 탭·서버에서 로그아웃, 세션 삭제). 그 뒤 화면이 요청을 보낸다 | +| 영향 | 세션 상태가 `authenticated`로 남는다. scope fence가 일어나지 않아 끝난 세션의 서버 상태 캐시가 화면에 남는다. 셸은 로그인한 사용자로 보인다. 요청마다 `AUTH_REQUIRED` 실패 화면이 뜬다(`src/adapters/http/feature-http-binding.ts:464-467`). 실패 화면의 로그인으로 다시 들어가면 풀린다. 다른 사용자가 로그인하면 owner가 세션을 다시 묻고 subject가 바뀌어 fence가 일어나므로(`cookie-session-owner.ts:106-133`, `auth-session-port.ts:14-15`), 다른 사용자 데이터 노출은 없다 | +| 심각도·우선순위 | Medium · P2 — 지원하는 짝 모드 하나에서 세션 만료 판정(R-3.2)이 빠진다. 사용자는 실패 화면에서 회복할 수 있고 정보 노출은 없다. 지난 라운드의 반대 방향 결함(1103/09-01, 과잉 로그아웃)과 같은 눈금이다 | +| 통제·증거 | 목표 M3(조립 루트를 지나는 recipe 테스트가 쿠키 모드 401을 본다) / 확인 M0 · E2(09-cookie401) | +| 확실성과 남은 가정 | 조립 루트 테스트에서 재현했다. 실제 Redis 백엔드에는 붙이지 않았다. 다운스트림 memento·tech-log가 이미 hook을 이었는지는 보지 않았다(CHANGELOG `:58`는 "여기서 owner에 알린다"고 안내한다) | +| 결정의 근거 | 확인한 사실: 위 근거. 기록된 의도: `0aada28b` 본문 "제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이 hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02 5절에 적었다". `05958bbd`(recipe)는 그 전 동작(provider 401도 세션에 감)을 전제로 썼다. 리뷰어 추론: 1103/09-01의 판단(자격증명을 낸 쪽이 판정)은 맞다. 다만 템플릿이 직접 내놓은 provider 예시가 그 판단의 첫 소비자인데 이어지지 않았다 | +| 이해 비용 | 쿠키 모드 제품 개발자는 recipe, 매뉴얼 04, 매뉴얼 02 5절, 계약 주석, CHANGELOG가 서로 다른 말을 하는 것을 맞춰야 한다 | +| 최소 개선 방향 | recipe가 owner와 provider를 한 번에 만드는 함수를 내고, 그 결과에 `onCredentialRejected: () => owner.notifyUnauthenticated()`를 담는다. 또는 `ProductCompositionContext`에 세션 알림(`notifySessionUnauthenticated`)을 준다. 매뉴얼 04 4.3 예시와 recipe 주석을 고치고, `session-owners-runtime.test.ts`에 쿠키 모드 401 케이스를 더한다 | +| 대안 비교 | (A) 현 상태 + 문서만 고침: 모듈 변수 연결을 제품마다 쓴다. (B) recipe가 hook까지 만든다: recipe 몇 줄, 계약 그대로. (C) context에 세션 알림 함수: 계약 칸 하나, 모든 BFF 제품이 같은 한 줄을 쓴다. (D) provider 선언에 "이 provider는 템플릿 세션의 자격증명을 낸다" 표시를 두고 조립 루트가 세션에 알림: 판정이 선언 하나로 모인다. 계약 칸이 하나 는다 | +| 단순화의 보존 조건 | ANONYMOUS 401은 아무에게도 알리지 않는다. 세션과 무관한 provider(외부 API 토큰)의 401은 세션을 로그아웃시키지 않는다(1103/09-01 완료 기준). hook의 throw는 결과를 바꾸지 않는다 | +| 비용·부작용 | (B) recipe·매뉴얼 수십 줄, 테스트 1~2개 | +| 재검토 조건 | 짝 백엔드 Redis 모드가 세션 조회·로그인 엔드포인트를 템플릿에 들이면 owner와 provider를 다시 맞춘다 | +| 완료 기준 | 매뉴얼 04 4.3대로 이은 조립 루트에서 쿠키 읽기·쓰기 operation이 401을 받으면 세션이 `unauthenticated`이고 이전 scope는 current가 아니다 | +| 검증 방법 | 09-cookie401 테스트를 `tests/recipes/session-owners-runtime.test.ts`에 옮기고 수정 전 실패를 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음(신규) | + +### 09-03 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(작은 출력 중복) | +| 관련 관점 | 8, 20, 23 | +| 근거 | 1103/09-07 수정은 오류 message 끝에 reason을 붙인다(`src/contracts/external-contract-runtime.ts:293`). 1103/14-06 수정은 `check:registries`가 message 첫 줄 뒤에 `(reason: …)`를 또 붙인다(`scripts/check-registries.ts:158-163`). 두 수정이 다른 브랜치에서 들어왔다(`f98d0c36`, `84d6e526`). 그래서 출력은 "…not composable: X/OP: unknown authProfileId Y (reason: X/OP: unknown authProfileId Y)"가 된다(정적 확인). `tests/unit/registry-governance.test.ts:637-645`는 reason이 message에 없는 가짜 오류로 시험해 중복을 보지 않는다 | +| 발생 조건 | 계약 조립 실패(프로필 id 오타 등)로 `check:registries`가 레지스트리를 읽지 못한다 | +| 영향 | 같은 원인이 두 번 보여 읽기 어렵다. 동작 피해는 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 목표 M3 / 확인 M0(실제 오류로 출력을 보는 테스트 없음) · E1 | +| 확실성과 남은 가정 | 코드로 확인했다. 실행하지 않았다 | +| 결정의 근거 | 적용 제외 — 두 수정이 같은 일을 겹쳐 한 단순 중복이다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | `loadErrorText`가 message에 reason이 이미 있으면 붙이지 않는다. 또는 테스트가 실제 `ContractContributionError`를 던진다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 프로필 id 오타 하나로 `check:registries` 출력에 원인이 한 번 나온다 | +| 검증 방법 | `registry-governance.test.ts`의 케이스를 실제 오류 클래스로 바꾼다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음(신규) | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 | 조립 불변식 M3 / M3 | E2(09-ctrl, 09-mut) | P — 라우트 루트·핸들·경로 중복(대소문자·끝 슬래시 포함)·needs·자격증명 순서를 throw·테스트로 지킨다. 쿠키 모드 401이 세션에 닿지 않는다(09-02) | +| 2 | 구조적 성숙도 | 적용 | 공개 경계 M3 / M3 | E1, 오케스트레이터 `check:architecture` | P — 제품 소유 파일이 셋으로 정리됐다(`product-composition.ts`, `product-contracts.ts`, `product-capabilities.ts`). SW 연결·플랫폼 구성 화면은 템플릿 파일이다(1103/09-04·09-05 일부) | +| 3 | 변경 용이성 | 적용 | 제품 변경 = 제품 파일만 M2 / M1 | E3(09-probe-downstream) | P — 기능·capability·설정 키·SW 선택은 제품 파일만 고친다. 그런데 제품 capability를 쓰면 템플릿 테스트가 실패한다(09-01). 예제 기능을 빼면 브라우저 spec 8개를 고친다(1103/09-04 ②) | +| 4 | 인지 부하 | 적용 | 확장 위치 한 표 M1 / M1 | E1 | P — `starter-experience.md:224` 표와 매뉴얼 03이 맞다. 쿠키 모드 401은 recipe·매뉴얼 04·매뉴얼 02·CHANGELOG가 서로 다르게 말한다(09-02) | +| 5 | 위험 가시성 | 적용 | 판단 규칙이 호출부에서 보임 M2 / M2 | E1 | P — 401 판정 규칙이 함수 하나와 계약 주석에 모였다(`runtime-adapters.ts:571-593`). 탐침이 제품 파일을 덮어쓰는 위험은 커밋 본문에만 있다(09-01) | +| 6 | 실패 성숙도 | 적용 | 안전한 기본 M2 / M2 | E2(09-ctrl, 09-cookie401, 09-R1) | P — 401 판정이 자격증명 출처를 본다. 계정 전환 중 401은 실행기가 막는다(09-R1). owner fetch는 시간·크기 제한·redirect 거절(`session-owner-fetch.ts:128-194`). 쿠키 모드 만료를 놓친다(09-02) | +| 7 | 운영 성숙도 | 적용 | 경계 실패 진단 M2 / M2 | E1 | P — 결과 불명 쓰기의 effect가 진단에 실린다(`runtime-adapters.ts:209`). 제품 hook이 없을 때 provider 401이 조용히 버려지는 것은 진단에 남지 않는다(09-02) | +| 8 | 디버깅 가능성 | 적용 | 조립 오류가 원인을 말함 M3 / M3 | E2(`second-api-feature-registries.test.ts`) | P — 프로필 오타가 operation·프로필 id를 말한다(1103/09-07 고쳐짐). 원인이 두 번 찍힌다(09-03). 탐침 실패는 임시 복사본 경로를 가리킨다(09-01) | +| 9 | 유지보수 성숙도 | 적용 | 낡은 설명 정리 M1 / M1 | E1 | P — V2 설명 4곳 정리(1103/09-10). recipe 주석이 401 동작 변경을 따라가지 않았다(09-02). `src/application/result.ts` deprecated 재수출은 그대로(소비자 0, 제거 조건 없음) | +| 10 | 테스트 성숙도 | 적용 | 핵심 판단 M3 / M3(템플릿 상태) | E2(09-ctrl, 09-mut, 오케스트레이터 `test:unit` 194 files / 2,883 tests) | P — 지난 수정마다 RED 테스트가 있고 변이를 잡는다. 테스트는 템플릿 출하 상태만 본다. 다운스트림 상태에서 템플릿 테스트가 실패하고(09-01), 쿠키 모드 401 테스트가 없다(09-02) | +| 11 | 데이터 성숙도 | 적용(샘플 범위) | — / M1 | E1 | P — local-draft ABA는 주석으로만(0925 FOLLOW-UP 09-08, 허용한 대안). 이 영역에 데이터 손상 경로는 없다 | +| 12 | 동시성 성숙도 | 적용(401·계정 전환) | 이전 scope의 401은 새 세션에 닿지 않음 M3 / M2 | E2(09-R1, 리뷰 탐침) | P — 실행기의 admission 경쟁 처리(`http-execution-v3.ts:1088-1114`)가 막는다. 09-R1에서 `notify=0`. 다만 이 경쟁을 만드는 테스트는 저장소에 없다(탐침은 리뷰용). 조립 루트의 `reportServerUnauthenticated`는 scope를 다시 보지 않는다(실행기 반환과 알림 사이 한 microtask, 5절). 나머지 동시성은 > 03 영역 | +| 13 | 확장성 | 적용 | 기능·제품 수 축 M3 / M2 | E3(09-probe-downstream) | P — context 루트 충돌·예산 검사는 그대로다. 제품 수 축에서 09-01이 생겼다 | +| 14 | 성능 성숙도 | > 15 영역 | — | — | > — 플랫폼 구성 화면을 기능으로 옮기면 lab FAIL(`b96d61d8` 본문)이라 남긴 판단은 15 영역 | +| 15 | 보안 성숙도 | 적용 | fail-closed M3 / M3 | E2(09-ctrl) | P — ANONYMOUS는 세션을 묻지 않는다. provider 뒤 fence 재확인. OIDC recipe는 토큰 메모리 보관(`recipes/session-owners/oidc-pkce-session-owner.ts:23`), HTTPS·loopback 엔드포인트만(`:131-143`), return path 검사(`:166-177`), state·issuer 대조(`:474-477`), PKCE S256(`:553`), bearer origin 제한(`:581`)을 지킨다. ID token 서명은 보지 않는다(문서화, OIDC Core 3.1.3.7(6)). 쿠키 모드 만료 미감지(09-02)는 노출이 아니라 상태 오판이다 | +| 16 | 의존성 성숙도 | 적용 제외 — recipe가 OIDC 라이브러리를 쓰지 않는다. 영역 고유 의존성 없음 | — | — | - | +| 17 | API / Contract 성숙도 | 적용 | 401 의미가 계약과 같음 M3 / M2 | E2 | P — `ProductComposition.onCredentialRejected` 계약은 짧고 맞다. 계약을 쓰는 템플릿 예시가 계약을 따르지 않는다(09-02) | +| 18 | 배포 성숙도 | > 13 영역 | — | — | > — 플랫폼 구성 화면의 FE-GATE-028 서명 요구는 1103/09-04 일부 | +| 19 | 설정 성숙도 | 적용 | 제품 키 strict 검증 M3 / M3 | E2(09-ctrl 탐침) | O — 기본값 제품 키가 템플릿 테스트를 깨지 않는다. 기본값 없는 필수 키는 helper가 원인을 말하며 throw한다(`tests/helpers/runtime-config.ts:31-39`) | +| 20 | 개발자 경험 | 적용 | 생성·제품 파일 → 게이트 통과 M3 / M2 | E3(09-probe-downstream) | P — 생성 명령의 쓰기 slice(1103/09-06), dev manifest 재작성(16-09). 제품 capability를 쓰면 게이트가 원인 없이 실패하고(09-01), 쿠키 모드 연결 예시가 틀렸다(09-02) | +| 21 | Guardrail 성숙도 | 적용 | 조립 실수 차단 M3 / M3 | E2(09-mut) | P — 표시+선언 동시 존재, 경로 대소문자 중복, needs 밖 capability를 막는다. 템플릿 자신의 guardrail 테스트가 다운스트림 상태에서 오탐한다(09-01) | +| 22 | 추상화 성숙도 | 적용 | 계약이 짧고 정확 M2 / M2 | E1 | P — owner context가 fetch·page·redirectStorage를 준다(1103/09-03). `composeProduct`가 owner에 닿을 길이 없어 hook을 잇기 어렵다(09-02) | +| 23 | 일관성 | 적용 | 같은 선택은 같은 장치 M2 / M2 | E1 | P — 예제 화면 셋은 기능 선택으로 뺀다. 플랫폼 구성 화면만 예외다(1103/09-04 ①). 401 알림 경로가 bearer recipe(세션)와 쿠키 recipe(provider)에서 다르다(09-02) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | — / M2 | E2 | P — `NOT_A_FEATURE`로 나눴다(1103/09-09). `TEMPLATE_APP_MODULE`이 선택된 아무 앱을 가리키는 것은 그대로(`src/apps/template-app.ts:10`) | +| 25 | 조직 확장성 | 적용 | 동기화 충돌 자리 분리 M2 / M1 | E3(09-probe-downstream) | P — 제품 소유 파일 셋을 테스트가 고정한다(`product-composition-fixture.test.ts:605-628`, `product-runtime-capability-selection.test.ts:43-51`). 템플릿 테스트 하나가 다운스트림에서 실패해 충돌 자리가 된다(09-01) | +| 26 | Ownership 성숙도 | > 14 영역 | — | E2 | > — "Product-owned." 표시 세 파일 | +| 27 | 삭제 가능성 | 적용 | 기능·예제 제거 M3 / M2 | E1, `b96d61d8` 드릴 기록 | P — 예제 셋은 제거 드릴로 빠진다. 플랫폼 구성 화면은 빠지지 않고, 브라우저 spec 8개는 제거 드릴이 보지 않는다(0925 FOLLOW-UP 09-07 일부) | +| 28 | 회복 가능성 | 적용 | 세션·부트 회복 M2 / M2 | E2(`session-recovery.test.tsx`) | P — `no-session` 뒤 로그인 버튼(1103/09-11 고쳐짐). 쿠키 모드 만료 뒤 셸이 로그인 상태로 남는다(09-02) | + +집계(판정한 24개): 충족 1(19) · 부분 충족 23 · 미충족 0 · 미검증 0. 적용 제외 1(16), 다른 영역 3(14, 18, 26). 지난 라운드와 달리 12는 401·계정 전환 경쟁을 이 영역에서 판정했다(코드 + 09-R1). + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 짝 백엔드에 실제로 붙인 로그인·401 | Keycloak·Redis·백엔드를 띄우지 않았다. realm에 public client가 없다 | 백엔드 local + Keycloak에 public client를 더하고 OIDC recipe로 `EXTERNAL_BEARER` 1회. Redis 모드에 세션 엔드포인트를 더하고 쿠키 owner로 쓰기 1회, 세션 삭제 뒤 401 1회 | +| 다운스트림(tech-log, memento)에 이 커밋을 넣은 결과 | 두 제품 코드를 읽지 않았다 | 동기화 브랜치에서 `test:unit`(09-01), 쿠키 provider의 `onCredentialRejected` 연결 여부 grep(09-02) | +| 실행기 반환과 `reportServerUnauthenticated` 사이의 경쟁 | 09-R1은 admission 중 전환만 본다. 반환 뒤 한 microtask 안의 전환은 재현 장치를 만들지 않았다 | `contractHttp.execute`를 감싼 테스트에서 resolve 직전 subject를 바꾼다 | +| 예제 기능을 뺀 제품의 브라우저 게이트 | 무거운 실행이다(FE-GATE-008). 정적으로 spec 8개를 셌다 | `VITE_PRODUCT_FEATURES`에서 예제 기능을 빼고 `test:e2e`·`test:visual` | +| OIDC recipe의 실제 IdP 응답 모양(Keycloak refresh 응답의 `id_token`·`nonce`) | IdP를 띄우지 않았다. recipe 테스트는 가짜 응답이다 | Keycloak local로 refresh 2회 | + +## 6. 실행 기록 + +모두 desktop helper(`/tmp/claude-gates/r4/exp.sh`, 기준 `8a442262`, 공유 잠금)로 돌렸다. 노트북에서는 아무것도 실행하지 않았다. 변이 스크립트는 `desktop:/tmp/claude-gates/r4/mut/09-*.sh`, 전체 로그는 `desktop:/tmp/claude-gates/r4/exp/09-*.log`다. + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 · 부하 | +|---|---|---|---|---|---| +| 09-ctrl | `node scripts/run-vitest.ts run` 11파일: `tests/unit/{runtime-adapters-auth-profile,runtime-adapters-credential-order,product-extension-typecheck,product-session-owner-context,dev-release-manifest,product-runtime-capability-selection,product-composition-fixture}.test.ts`, `tests/contract/reusable-capability/feature-adapter-composition.test.ts`, `tests/recipes/session-owners-runtime.test.ts`, `tests/component/session-recovery.test.tsx`, `tests/scripts/generate-product-feature-index.test.ts` | 없음 | 0 | 11 files / 87 tests 통과, 5.58s. 아래 변이·탐침의 대조군 | 606s · 1.49 | +| 09-mut | `run-vitest.ts run` `runtime-adapters-auth-profile`, `runtime-adapters-credential-order`, `feature-adapter-composition` | 두 수정을 수정 전 동작으로: ① `reportServerUnauthenticated` 첫 줄에 `authSession.onUnauthenticated(); return;`(`runtime-adapters.ts:581`) ② `invokeContribution`이 `context` 전체를 넘김(`feature-adapter-contribution.ts:161`) | 1 | 4 failed / 27 passed. ①로 "keeps a demo session signed in when an ANONYMOUS request gets 401", "does not tell the external owner about an ANONYMOUS request's 401", "leaves the session alone and tells the product"(`credential-order.test.ts:380` notify 호출됨). ②로 "hands a contribution only the capabilities it names in needs"(`expected [['http','telemetry']] to deeply equal [['telemetry']]`). 대조군 09-ctrl은 같은 파일 모두 통과 → 두 수정은 테스트로 지켜진다 | 623s · 1.52 | +| 09-R1 (배치, 원래 09-race401) | `node scripts/run-vitest.ts run tests/unit/runtime-adapters-auth-profile.test.ts --reporter=default` · local | 같은 파일 끝에 탐침 1건 추가(`scratchpad/r4/requests/09-R1-race401.diff`): external owner(user-a) bearer 요청이 401을 받고, 실행기가 401 본문을 cancel하는 순간 owner가 user-b로 바뀐다. 단언: 이전 scope는 current가 아니고 `notifyUnauthenticated` 0회 | 0 | 17 tests 통과(기존 16 + 탐침 1). `R4-09 race: switched=true outcome=CONTRACT_VIOLATION previousScopeCurrent=false subject=user-b notify=0`. 계정 전환이 admission 도중에 일어났고(`switched=true`), 결과는 `UNAUTHENTICATED`가 아니며 새 사용자에게 알림이 가지 않았다. 대조군(변이 없는 16건)은 09-ctrl과 `gates/test_unit.log`. 발견 없음 | 오케스트레이터 배치 20:08 · 3.42 | +| 09-cookie401 | `run-vitest.ts run tests/recipes/session-owners-runtime.test.ts` | 같은 파일 끝에 탐침 2건 추가(읽기·쓰기): 매뉴얼 04 4.3 연결, 세션 조회 200, API 401. 단언: 세션 `unauthenticated`(매뉴얼 `:186`) | 1 | 2 failed / 4 passed. 두 건 모두 `outcome=UNAUTHENTICATED sent=true credentials=include state=authenticated scopeCurrent=true`, `expected 'authenticated' to be 'unauthenticated'`. 기존 4건 통과(09-ctrl에서도 통과) → 09-02 | 612s · 1.45 | +| 09-probe-downstream | `corepack pnpm -s check:types:app; …:node; …:test; run-vitest.ts run tests/unit/product-extension-typecheck.test.ts` | 다운스트림 흉내: `product-capabilities.ts`에 `r4NoticeSettings` 타입, `product-composition.ts`가 그 값을 돌려줌, 새 `src/contexts/r4-notice-context/`와 `src/features/r4-notice-feature/`(`needs: ["r4NoticeSettings"]`), 생성기 실행. 템플릿 파일은 고치지 않음(`git status`: M 2 + ?? 2) | 0(명령 묶음) | `APP_RC=0`, `NODE_RC=0`, `TEST_RC=0`. 탐침 `PROBE_RC=1`: `runtime-adapters.ts(695,5): error TS2741: Property 'r4NoticeSettings' is missing in type 'Readonly<{ typecheckProbeSettings: …`. 대조군 09-ctrl에서 탐침 통과 → 09-01 | 614s · 1.45 | + +직접 돌린 4개 모두 helper가 `restored: clean at 8a442262`를 출력했다. `REFUSED`·`RESTORE FAILED`는 없었다. 09-R1은 오케스트레이터가 `8a44226`으로 되돌린 checkout에서 돌렸고 restore=clean이다(`scratchpad/r4/results/09/09-R1.log`). + +오케스트레이터 결과(인용, 이 영역이 기대는 것만, 20시 전후 확인): + +- `gates/`(local env): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema` rc=0. `test:unit`은 194 files / 2,883 tests 통과이고, 이 영역의 `product-extension-typecheck.test.ts`(1 test), `runtime-adapters-auth-profile.test.ts`(16), `runtime-adapters-credential-order.test.ts`(10)가 들어 있다. `verify:documentation` rc=1: 짝 백엔드 sibling 경로가 없어서다(`docs/manual/04-paired-backend-session.md`가 `../clean-architecture-backend-template/docs/manual/07-authorization.md`를 가리킴 등). 오케스트레이터가 따로 다루는 환경 조건이라 이 영역 발견으로 세지 않았다. +- `merge-48/`(CI=true): FE-GATE-001~012·020 rc=0, FE-GATE-013 rc=1(원인은 오케스트레이터가 다룬다. 이 영역의 테스트를 돌리는 게이트가 아니다). FE-GATE-005(`test-unit`, 탐침 포함), FE-GATE-007(`test-recipes`, 세션 owner recipe 포함), FE-GATE-020(생성 드릴의 `--with-create --keyed` slice 포함, 1,156s). +- 이 결과는 모두 템플릿 출하 상태다. 09-01·09-02는 출하 상태에서 드러나지 않는다(09-probe-downstream, 09-cookie401). + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 09-01 | Medium·P1 | 확인된 결함 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` | +| 09-02 | Medium·P2 | 확인된 결함 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(1103/09-01 수정과 1103/09-03 recipe 불일치) | `src/bootstrap/runtime-adapters.ts:583-591`; `recipes/session-owners/cookie-session-owner.ts:33`, `:179`; `docs/manual/04-paired-backend-session.md:186`, `:238-249` | +| 09-03 | Low·P3 | 확인된 결함 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | `src/contracts/external-contract-runtime.ts:293`; `scripts/check-registries.ts:158-163` | diff --git a/docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md b/docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md new file mode 100644 index 00000000..23e2b048 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/10-tests-fast-layers.md @@ -0,0 +1,229 @@ +# 영역 10 — 테스트: 빠른 계층 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`, PR #4와 같은 커밋) +> 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 지난 문서: `docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md`(기준 `e40684b`) +> 경로: `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 영역) +> 깊게 본 관점: 10 테스트, 12 동시성, 20 개발자 경험, 21 Guardrail +> 렌즈: (1) 지난 라운드 생존 변이가 지금 잡히는가. (2) 1103/10-01이 한도만 올려 고친 것인가. (3) `e40684b..8a44226`의 테스트 변경이 검사를 약하게 했는가. +> 영역 판정(35.8): **지정 범위에서 사용 가능** — 템플릿 상태의 머지 게이트로 쓴다. 지난 조건 둘(10-02 Envelope 경계, 10-01 부하 실패)이 모두 풀렸다. 샘플을 지운 제품은 새 10-01의 두 규칙을 제품 테스트로 다시 고정해야 같은 검출력이 남는다. + +## 0. 결론 + +- **지난 라운드에 살아남은 변이 15종 중 14종이 이제 잡힌다.** Envelope 경계 6종(H14·H45·H15·H23·H10b·M7), CSRF 3종(H18·H19·07-02 M3), V3 동작 4종(H53·H56·H57·H21), 세션 복구 분기(L02)다. 남은 하나는 §10.8 마지막 검사(L01, 0929/10-04)다. 네 라운드째 아무 테스트도 고정하지 않는다(107파일 995개 통과). +- **수정 뒤에 생긴 규칙도 대부분 고정됐다.** 5xx 결과 불명 답의 status 대조(E7), 선언 목록이 멱등 code와 표의 code를 바꾸지 못하는 규칙(E8·E9)을 넣은 변이가 모두 새 테스트에서 실패했다. +- **1103/10-01은 한도만 올린 수정이 아니다.** 테스트가 준비 신호(fd 3의 1바이트)를 받은 뒤에 stdin을 닫는다(`tests/unit/task3-selective-integration.test.ts:247-273`, `:174`). 기동은 따로 5초 watchdog으로 잰다(`:272`). desktop에서 한 코어에 바쁜 이웃 6개를 둔 조건(지난 F5)이 5/5 통과했고, 이웃 14개도 3/3 통과했다. EOF 처리를 지운 변이(P1)는 잡혔다. +- **약하게 만든 검사는 찾지 못했다.** skip·todo·only가 새로 들어오지 않았다. 늘어난 시간 한도는 새 테스트의 것이거나 일이 늘어난 테스트의 것이다. 바뀐 기대값은 수정이 동작을 바꾼 자리다(3.0절 표). 다만 `6407904c`가 세션 복구 단언을 "보호 라우트가 있으면 본다"로 바꿔, 샘플을 지운 상태에서는 대상이 없다(새 10-01). +- **새 발견 2건, 모두 Low·P3다.** 10-01: 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 테스트가 함께 사라진다. 10-02: 호출자·scope signal listener 정리는 고정됐지만, 같은 자리의 interaction signal listener 정리는 지워도 107파일 995개가 통과한다. +- **비용 쪽 이월 항목은 커졌다.** `tests/unit` 194파일 중 `scripts`만 보는 파일과 import 없는 파일이 테스트 시간 합의 72%(94.2s / 130.9s)를 쓴다(지난 66%). 한 머지에서 `tests/unit`이 13번 돈다(1101/10-06, 2절). +- **오케스트레이터 게이트(로컬 env):** `test:unit` 194파일 2,883개, `test:component` 40파일 270개, `test:integration` 11파일 189개, `test:contract` 3파일 24개, `test:runtime-schema` 3파일 56개 모두 통과. merge 48회차(CI=true)에서 FE-GATE-004·005·006·020 PASS(인용, 1.1절). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 테스트 파일 수(`git ls-files`, `e40684b` 대비): unit 194(+18), component 40(+1), integration 11(+1), contract 3, runtime-schema 3, features 23(+2), platform 29, recipes 7(+4). 지원 코드: helpers 11, mocks 6, `tests/support`는 모두 `browser/` 아래(11 영역). 설정: `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts`, `scripts/lib/no-skipped-tests-reporter.ts` | +| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준)에서 읽기만 했다. 실행은 desktop 공유 checkout에서 `exp.sh`로 했고 매번 `restored: clean at 8a442262`를 확인했다. 확인 2026-11-05 19:25~20:10 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.12, Node 24.14.0, jsdom 29.1.1, MSW 2.15.0 | +| 필수 요구와 규모·운영 목표 | 빠른 계층은 머지 게이트다: FE-GATE-004(runtime-schema), 005(unit·contract·coverage·scale pr, `config/ci/gates.json:1840-1848`), 006(component), 007(integration·HTTP 시나리오·reference-feature·recipes, `:1873-1880`), 020(제거·생성 드릴 안에서 다시, `:2112-2120`). 러너 사양과 허용 실패율은 정해져 있지 않다(U-1) | +| 읽은 코드·구성 범위 | 위 설정 전체. `git log`/`git diff e40684b..8a44226`의 영역 경로 114커밋, 94파일(+9,541 / −455). 지난 발견의 수정 커밋 `12395662`, `5d0f8454`, `a94006b9`, `a6b85e87`, `fb206994`, `6407904c`, `1b1d972a`. 변이 대상 코드: `src/adapters/http/backend-envelope.ts`, `http-execution-v3.ts`, `src/bootstrap/runtime-adapters.ts:502`, `src/contracts/external-contract-runtime.ts:525-597`, `realtime-streams.ts:462-473`, `src/presentation/routes/navigation-policy.ts`, `scripts/lib/provider-scope-wrapper.ts`. 드릴: `scripts/test-sample-removal.ts`, `test-feature-scaffold.ts`, `lib/feature-scaffold-drill.ts`, 제거 드릴 셋 | +| 읽은 문서(주장으로만) | 지난 영역 문서, 지난 README 10.3·12·13·14절, 수정 커밋 본문 | +| 수행한 테스트·실험 | desktop: `10-mut-A`(Envelope 변이 9종), `10-mut-B`(V3·CSRF·이월·EOF 변이 11종), `10-eofload`(1103/10-01 부하 재실행). 세 실행 모두 restore clean. `10-mut-C`(지난 라운드에 잡힌 변이 대조군 4종 + H20)와 `10-eofload-old`(옛 테스트로 같은 부하 대조)는 19:55 실행 규칙 변경(BRIEF-2)으로 취소돼 돌지 않았다. 오케스트레이터 로그에서 unit 파일별 시간을 분류했다(J1) | +| 확인하지 못한 범위·이유 | 실제 Gitea 러너(U-1). 옛 EOF 테스트가 desktop의 같은 부하에서 떨어지는지(10-eofload-old 취소, 5절). 테스트별 시간(오케스트레이터 snapshot의 junit이 아직 없다. 파일별 시간만 로그에서 셌다). 브라우저 계층(11 영역) | +| 이전 리뷰와 비교 가능한 범위 | 지난 실행 결과는 증거로 쓰지 않았다. 지난 생존 변이는 `8a44226`의 같은 규칙 자리에 다시 넣었다(줄은 바뀌었다, 6절). 파일 분류(J1)는 지난 J1과 같은 기준(import 대상)이다 | + +### 1.1 게이트 결과 (오케스트레이터, `8a44226`, 인용) + +로컬 env(`desktop:/tmp/claude-gates/r4/gates/summary.txt`): `check:architecture`, `check:types`, `lint` rc=0. `test:unit` rc=0(194파일 2,883개, Duration 22.61s, setup 누적 43.97s, tests 130.90s). `test:component` rc=0(40파일 270개, 9.10s). `test:integration` rc=0(11파일 189개, 10.37s). `test:contract` rc=0(3파일 24개). `test:runtime-schema` rc=0(3파일 56개). merge 48회차(CI=true, `merge-48/summary.txt`): FE-GATE-004·005·006 PASS, FE-GATE-020 PASS(1,156s). 이 영역에서는 다시 돌리지 않았다. + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/10-01 | 자식 프로세스 EOF 테스트가 자식 기동까지 1초 안에 넣는다 | **고쳐짐** | `12395662`. 테스트는 loader로 래퍼를 띄우고(`task3-selective-integration.test.ts:247-265`), loader가 래퍼 import를 끝낸 뒤 fd 3에 1바이트를 쓴다(`:258-259`). 테스트는 그 신호를 받은 뒤 75ms를 기다리고 stdin을 닫는다(`:173-179`). 래퍼에는 top-level await가 없어 import가 끝나면 EOF 처리기가 붙어 있다(`scripts/lib/provider-scope-wrapper.ts:27-51`). 래퍼는 `argv.slice(2)`만 읽어 loader 자리에서도 같다(`:9`). 한도 5초는 멈춤만 본다(`:20-25`, `:180`). 기동은 별도 5초로 재고 "start-up"이라는 이름으로 실패한다(`:267-273`). 그래서 **한도만 올린 수정이 아니다**. 10-eofload: 이웃 0개 156~169ms 5/5, 이웃 6개(지난 F5 조건) 596~610ms 5/5, 이웃 14개 1,172~1,322ms 3/3 통과. P1(EOF 처리기 `:50` 제거): "uses early liveness EOF …" 실패. 완료 기준 둘을 모두 충족했다 | +| 1103/10-02 (= 03-08) | Envelope 실패 판정의 경계 다섯 곳 미고정, 처리 중 409 무재전송 미고정 | **고쳐짐** | `5d0f8454`. `tests/unit/backend-envelope.test.ts:29-49`(표 code를 다른 status로, 표 밖 422), `:143-150`(게이트웨이 408·425), envelope 통합 `:898`(409 IN_FLIGHT 한 번만), `:956`(응답 한도 초과 실패 Envelope), `:977`(JSON 아닌 실패 본문). 변이 E1(H14)·E2(H45)·E3(H15)·E4(H23)·E5(H10b)·E6(M7) 모두 잡힘(6절) | +| 1103/10-03 (→ 07-02) | 쿠키 쓰기 CSRF 조립 검사를 POST와 `x-xsrf-token` 하나로만 고정 | **고쳐짐** | `a94006b9`. `tests/unit/rest-profile-contract.test.ts:111-137`이 POST·PUT·PATCH·DELETE × (CSRF 없음, `x-tenant-context`만, `x-csrf-token`, `x-xsrf-token`)과 GET·HEAD를 돈다. C1(H18, POST만)·C2(H19, `x-csrf-token` 허용 삭제)·C3(07-02 M3, "아무 필수 헤더") 모두 잡힘 | +| 1103/10-04 | V2 삭제로 V3 동작 셋이 머지 게이트 보호를 잃음 | **고쳐짐(템플릿 상태)** | `a6b85e87`, `a94006b9`. ① `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`(FE-GATE-007의 `test-reference-feature`) — R1(H53) 잡힘. ② `tests/unit/http-execution-v3.test.ts:764-805` — R2(H56)·R3(H57) 잡힘. 이제 nightly 테스트가 아니라 머지 게이트 테스트가 잡는다. ③ `tests/unit/realtime/realtime-stream-registry.test.ts:226-316` — R4(H21) 잡힘. 남은 것 둘은 새 발견으로 적었다: ①이 샘플에 기댄다(새 10-01), 같은 자리의 interaction signal 정리는 고정되지 않았다(새 10-02) | +| 1101/10-03 | 보호 라우트의 세션 복구 대기 분기 미고정 | **고쳐짐(템플릿 상태)** | `fb206994` 뒤 `6407904c`. `tests/unit/navigation-policy.test.ts:40-56`이 보호 라우트마다 `recovery-pending → wait-for-session`을 단언한다. L02 잡힘("treats every non-public route as explicitly session-required"). 샘플을 지우면 보호 라우트가 0개라 단언 대상이 없다(새 10-01) | +| 1101/10-05 | `tests/unit`에 도구 테스트가 섞여 시간 대부분을 씀 | **남음 — 커짐** | J1: 194파일 중 `src`만 116파일 23.3s(18%), `scripts`만 51파일 72.6s(55%), 둘 다 12파일 12.4s(9%), import 없음(자식 실행) 15파일 22.6s(17%). 합 130.9s. 지난 라운드는 `scripts`만 44파일 51% + import 없음 11파일 15% = 66%였다. 가장 긴 파일 셋은 모두 도구 테스트다: `documentation-readiness.test.ts` 17.0s, `product-extension-typecheck.test.ts` 11.0s(새 파일), `ci-workflow-generation.test.ts` 7.5s. `tests/scripts`는 여전히 2파일이고 `test:coverage`에서만 돈다(`package.json:83`) | +| 1101/10-06 | 머지 단계가 빠른 계층을 여러 번 돌림 | **남음 — 커짐** | 다시 셌다. FE-GATE-005: `test:unit`, `test:coverage`(2번, `gates.json:1843-1845`). FE-GATE-020: `test:sample-removal`이 샘플 제거 뒤와 생성 기능을 더한 뒤 두 단계에서 `test:all`·`test:coverage`(4번, `scripts/test-sample-removal.ts:445-446`, `:503`). `test:feature-scaffold`가 merge 명령 전체에서 `test:unit`·`test:coverage`(2번, `scripts/test-feature-scaffold.ts:100-102`), 그 안의 생성 기능 제거 드릴에서 다시 2번(`:104`, 16-02 수정으로 생김). 제거 드릴 셋의 `test:all`(3번, `test-optional-recipe-removal.ts:73`, `test-realtime-runtime-removal.ts:128`, `test-browser-file-storage-runtime-removal.ts:179`). **한 머지에 `tests/unit`이 13번 돈다.** 같은 방법으로 `e40684b`를 세면 11번이다. 지난 문서의 "최대 5번"은 드릴 셋과 sample-removal 두 단계를 세지 않은 값이다. FE-GATE-020은 merge 48회차에서 1,156초 걸렸다 | +| 1101/10-07 | 프로덕션 시간 상수를 실제 시계로 기다림 | **남음** | `tests/unit/service-worker-runtime.test.ts:2006-2022`("bounds a stream that never produces a chunk")는 가짜 타이머 없이 `ACTIVATION_MARKER_READ_DEADLINE_MS = 5_000`(`src/adapters/service-worker/service-worker-lifecycle.ts:558`)을 기다린다. 파일 시간 5,221ms. `browser-rpc-remediation.test.ts` 파일 시간 4,451ms. 테스트별 시간은 snapshot junit을 보지 못해 세지 않았다 | +| 1101/10-08 | `scopeSnapshot` 갈라진 복사본 | **남음** | 공유 도우미 두 곳(`tests/helpers/traffic-test-kit.ts:13`, `tests/component/application-query-fixture.tsx:20`) 밖에 4개 파일이 각자 정의한다(`reference-diagnostics.test.ts:7`, `http-execution-v3-auth-profile.test.ts:41`, `-live-authority.test.ts:23`, `-observability.test.ts:24`). `identities: Object.freeze({}) as never`는 10곳(그중 `tests/scale` 1곳). `deferred()` 7벌 그대로 | +| 0929/10-01 | 실행 속도에 기대는 테스트 | **고쳐짐** | 지난 라운드에 남은 한 곳(task3 EOF)이 1103/10-01로 고쳐졌다 | +| 0929/10-04 | §10.8 마지막 검사(오래된 scope의 성공 응답 버림) 미고정 | **남음 — 네 라운드째** | L01: `src/adapters/http/http-execution-v3.ts:1493-1499`의 조건을 `false`로 바꿔도 대상 2파일 80개, 관련 107파일 995개가 통과했다. 지금 scope fence 테스트(`tests/unit/http-execution-v3.test.ts:532-627`)는 signal도 함께 abort해 앞 단계 검사가 먼저 잡는다 | +| 0929/10-05 | `test:all`이 CI 빠른 테스트 일부를 빠뜨림 | **남음 — 범위 넓어짐** | `package.json:85`는 `tests/features` 중 `test:reference-feature`만 돈다. 새 `tests/features/platform-examples-feature`(2파일, `b96d61d8`)와 `tests/scripts`는 `test:coverage`(`:83`)에서만 돈다 | +| (지난 2절) `boot-unexpected-failure.test.tsx`의 `vi.stubGlobal` 미복원 | | **고쳐짐** | `1b1d972a`. `tests/component/boot-unexpected-failure.test.tsx:19-23` `afterEach(vi.unstubAllGlobals)`. `vi.stubGlobal`을 쓰는 나머지 두 파일도 unstub이 있다 | +| (지난 2절) `test:platform`만 `--no-file-parallelism`, 이유 없음 | | **남음** | `package.json:141` | +| (지난 2절) `test:runtime-schema`의 `--passWithNoTests` | | **남음** | `package.json:50`. `test:recipes`(`:58`), `test:reference-feature`(`:81`)도 같다 | +| (지난 R1) 전역 setup이 DOM 없는 unit에도 RTL을 읽음 | | **남음** | `tests/setup.ts:1-3`. unit setup 누적 43.97s(1.1절) | +| (지난 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-26` | + +틀린 발견으로 판정한 지난 항목은 없다. 지난 문서 1101/10-06 행의 "최대 5번"은 셈이 모자랐다(위 행). + +## 3. 이번 발견 (36.3) + +새 발견 2건 — 심각도 Low 2 · 우선순위 P3 2 · 성격 구조적 위험 2. High 이상과 P1은 없다. + +### 3.0 검사를 약하게 했는지 (`git diff e40684b 8a44226 -- <영역 경로>`) + +지운 테스트 파일은 없다(이름 바꿈 1: `starter-ui-gallery-page.test.tsx` → `tests/features/platform-examples-feature/ui-gallery-page.test.tsx`). 새 `it.skip`·`todo`·`only`·`skipIf`·`context.skip()`는 없다(`git grep`, 0건). `vitest.config.ts:38` `allowOnly: false`와 `scripts/run-vitest.ts:66-72`의 skip reporter는 그대로다. 지운 `expect`가 있는 자리는 모두 아래 표에 있다. + +| 커밋 | 바뀐 것 | 판정 | +|---|---|---| +| `12395662` | EOF 대기 1,000ms → 5,000ms, 테스트 제한 기본 10s → 15s(`task3-selective-integration.test.ts:180`, `:184`) | 약화 아님. 기동을 준비 신호로 한도 밖에 뺐다. 래퍼에는 EOF 마감 같은 프로토콜 요구가 없다. P1이 잡혀 검출력이 남은 것을 확인했다 | +| `6407904c` | 세션 복구 단언을 "보호 라우트 하나를 찾고 없으면 실패"에서 "보호 라우트 반복 안"으로(`navigation-policy.test.ts:40-56`) | 템플릿 상태에서는 같다(L02 잡힘). 샘플을 지운 상태에서는 대상이 없다. 바꾼 이유는 제거 드릴이 그 테스트로 떨어졌기 때문이다(커밋 본문). → 새 10-01 | +| `c9e7bab2` | 기능당 초기 JS 상한: 첫 복사본(기능+새 context) ≤ 1,024 B → 같은 context의 기능 ≤ 1,024 B, 새 context ≤ 512 B, 기록과 ±10% 대조(`feature-shape-growth.test.ts:150-166`). 테스트 제한 120s → 180s | 약화로 세지 않음. 1103/15-04 권고대로 기준을 나눴다. 새 context의 첫 기능 합계 상한은 1,024 → 1,536 B로 넓어졌다. 대신 기록 대조(`scripts/scale/measure-feature-shape-growth.ts:234-247`)가 새로 생겨, 비용이 10% 넘게 움직이면 기록을 다시 써야 통과한다. 시간 제한은 빌드가 2번에서 3번으로 는 만큼이다(`:214-225`). 기준 숫자의 적절성은 15 영역 몫이다 | +| `b96d61d8` | FEATURE_OVERRIDES 테스트 반복 대상을 설치 기능 전체에서 API를 기여하는 기능으로(`runtime-adapters.test.ts:64-70`, `:380`, `:420`) | 약화 아님. 새 예제 기능은 application API가 없어 "API를 주지 않는다"는 규칙의 대상이 아니다 | +| `d13a3936` | purge와 겹친 put의 기대: "늦은 put이 읽힌다" → `NOT_FOUND`, partition 삭제 | 약화 아님. 05-01 수정이 동작을 바꿨고 단언이 늘었다(`opfs-worker-runtime.test.ts`) | +| `af000673` | 실패 kind 기대 `OFFLINE` → `PROVIDER_UNAVAILABLE` | 약화 아님. 04-04 동작 변경 | +| `2d5d41f8` | 저장 중 버튼 `toBeDisabled()` → `aria-busy`·포커스 단언 | 약화 아님. 08-02 동작 변경. 두 번 눌러도 한 번만 보낸다는 단언은 남았다(`reference-page.test.tsx:334`) | +| `b6bfc9b7` 등 | 문서 검사 테스트의 route ID 정규식을 `REFERENCE_RESOURCE_*` → `[A-Z]+_RESOURCE_*`(`documentation-readiness.test.ts:88`) | 약화 아님. 지운 뒤에도 문서 검사가 통과하는지 보는 테스트라, 지우는 범위를 넓힌 것이다 | +| 새 테스트의 시간 제한 | 30s ×2(`architecture-lint-fixtures`), 60s(`second-api-feature-registries`), 120s(`product-extension-typecheck`) | 새 테스트의 것이다. 기존 한도를 올린 것이 아니다 | + +### 10-01 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기대어, 샘플을 지우면 함께 사라진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(검출 공백, 샘플 제거 상태) | +| 관련 관점 | 10, 27, 21, 3, 19 | +| 근거 | ① `MAX_RETRY_ATTEMPTS` 전달(1103/10-04 ①의 수정). 유일한 테스트가 `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`에 있다. 샘플 제거는 `tests/features/<샘플>`을 지운다(`scripts/test-sample-removal.ts:130`, `:159-161`). 남는 플랫폼 테스트 `tests/unit/runtime-adapters.test.ts`(`:140`의 공통 목록)에는 이 단언이 없다. 커밋 `a6b85e87` 본문도 "샘플을 지운 제품에서는 이 테스트도 같이 빠진다"고 적는다. 같은 자리의 `REQUEST_TIMEOUT_MS`(`src/bootstrap/runtime-adapters.ts:507`)도 지난 라운드부터 `reference-production-vertical.test.tsx`만 잡는 같은 모양이다. ② 복구 중 세션 대기(1101/10-03의 수정). `tests/unit/navigation-policy.test.ts:40-56`은 설치된 보호 라우트를 돌며 단언한다. 보호 라우트는 참조 기능에만 있다(`src/features/reference-feature/contracts/reference-feature-contract.ts:27`, `:41`, `:54`, `:67`). 샘플을 지우면 반복이 0번이라 `navigation-policy.ts:20-22`를 지켜도 지우지 않아도 통과한다. ③ 제거 드릴은 이 손실을 알리지 않는다. 드릴의 공통 테스트 검사는 파일이 남았는지만 본다(`test-sample-removal.ts:132-150`). 그 주석은 "플랫폼 자신의 커버리지를 기능과 함께 조용히 지워 통과하는 것"을 막는다고 적는다 | +| 발생 조건 | 제품이 템플릿 안내대로 참조 샘플을 지운 뒤, 플랫폼 파일(`runtime-adapters.ts`, `navigation-policy.ts`)을 고치거나 템플릿 동기화에서 충돌을 손으로 풀 때 | +| 영향 | 제품 CI에서 운영자의 재시도 끄기 손잡이(`MAX_RETRY_ATTEMPTS: 0`)나 요청 마감 상한이 조용히 무시돼도 통과한다. 세션 복구 중인 사용자가 보호 화면에서 로그인 화면으로 튕겨도 통과한다. 템플릿 CI(샘플 있음)는 계속 잡는다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 맞고 템플릿 CI가 지킨다. 플랫폼 파일은 제품이 고치지 않는 것이 원칙이라 닿는 경로가 좁다. 그러나 0929/10-02에서 고친 원칙("샘플을 지워도 플랫폼 검사가 남는다")을 새 수정 둘이 다시 어겼다 | +| 확실성과 남은 가정 | 테스트 위치와 제거 범위, 보호 라우트 분포는 코드로 확인했다(E1). 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다(5절) | +| 결정의 근거 | [확인한 사실] `createRuntimeAdapters`는 설치된 기능의 HTTP가 있어야 조립 루트를 탄다(`a6b85e87` 본문). `decideRouteAccess`는 설치된 라우트 레지스트리(`getRoute`)를 읽는다(`navigation-policy.ts:15`). 그래서 테스트 전용 기능을 주입할 자리가 없다. [추론] 두 테스트가 샘플에 기댄 것은 테스트 작성자의 실수보다 조립 입력을 바꿀 수 없는 구조 탓이다 | +| 이해 비용 | 제품 작성자는 어느 플랫폼 규칙이 샘플 테스트에만 고정돼 있는지 알 수 없다. 알려면 제거 드릴 목록과 테스트를 맞춰 봐야 한다 | +| 최소 개선 방향 | ⓐ 두 규칙을 샘플 밖에서 고정한다. `MAX_RETRY_ATTEMPTS`는 `createContractHttpExecutor`를 `runtime-adapters.ts`와 같은 방식으로 조립하는 작은 함수로 빼고 그 함수를 `tests/unit`에서 시험한다. 라우트 결정은 `decideRouteAccess`가 라우트 정의를 인자로 받는 순수 함수를 하나 두고 `tests/helpers/fixture-feature.tsx`의 보호 라우트로 시험한다. ⓑ 지금 테스트를 두고, 제거 드릴이 샘플 제거 뒤 "보호 라우트 반복 0번"처럼 대상이 빈 단언을 알리게 한다. ⓒ 현 상태를 유지하고 매뉴얼에 "샘플을 지우면 이 두 규칙을 제품 테스트로 다시 고정한다"고 적는다 | +| 대안 비교 | ⓐ 테스트 대상이 샘플과 무관해져 원인을 없앤다. 운영 코드에 함수 경계가 하나씩 는다. ⓑ 실패를 알리지만 제품이 결국 테스트를 새로 써야 한다. ⓒ 가장 싸지만 사람이 기억해야 한다. [추론] ⓐ를 고른다. 0929/10-02를 고칠 때 쓴 방식(테스트 전용 기능)과 같은 방향이다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 | +| 비용·부작용 | 함수 경계 둘, 테스트 수십 줄 | +| 재검토 조건 | 조립 루트가 테스트 전용 contract 기여를 받게 되면 ⓐ의 함수 분리 없이 `runtime-adapters.test.ts`로 옮긴다 | +| 완료 기준 | 샘플을 지운 복사본에서 H53(`runtime-adapters.ts:502` 상수 2)과 L02(`navigation-policy.ts:21` → `show-sign-in`)가 각각 `test:all`에서 실패한다 | +| 검증 방법 | `test:sample-removal` 복사본에 두 변이를 넣고 `test:all` | +| 담당·기한·상태 | 미정 · 미정 · 신규(1103 수정 `a6b85e87`, `6407904c`에서 생김) | + +### 10-02 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(검출 공백) | +| 관련 관점 | 10, 12, 14, 21 | +| 근거 | 실행기는 호출자·interaction·scope 세 signal에 abort listener를 단다(`src/adapters/http/http-execution-v3.ts:634-652`). 끝날 때 셋을 모두 지운다(`:662-664`). 1103/10-04 ②의 새 테스트(`tests/unit/http-execution-v3.test.ts:764-805`)는 호출자와 scope signal만 감시한다. 변이 R2b(`:663` interaction 쪽 제거)가 대상 1파일 69개와 관련 107파일 995개를 통과했다(`10-mut-B`). 같은 자리의 R2(호출자)·R3(scope)는 잡혔다 | +| 발생 조건 | 이 정리 줄을 리팩터링할 때. 기능이 `ExecutionContext`(`src/platform/execution/execution-context.ts:31-60`)를 넘겨 한 interaction 안에서 요청을 여러 번 보낼 때 드러난다(`reference-feature-api.ts:20`이 받는 자리다) | +| 영향 | 요청마다 listener 하나(그 요청의 lifetime controller를 잡은 closure)가 interaction signal에 남는다. interaction은 마감이 있어(`MAX_INTERACTION_DEADLINE_MS`, `http-execution-v3.ts:565-576`) 남는 기간은 그 마감까지다. 그래서 피해는 1103/10-04 ②(세션 scope, 오래 산다)보다 작다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 남는 기간이 짧다. 고치는 비용은 기존 테스트에 signal 하나를 더하는 정도다 | +| 확실성과 남은 가정 | 변이 생존은 확인했다(E2). 실제 누수량은 재지 않았다 | +| 결정의 근거 | 적용 제외 — 테스트 경우 누락이다 | +| 이해 비용 | 작다. 테스트 이름("caller and scope signals")이 감시 범위를 말한다 | +| 최소 개선 방향 | 같은 테스트에서 `execution: createExecutionContext(...)`을 넘기고 그 `cancellation.signal`도 감시 목록에 넣는다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | R2b가 `http-execution-v3.test.ts`에서 실패한다 | +| 검증 방법 | 6절 R2b 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규(1103/10-04 ② 수정의 남은 자리, 03 영역 코드) | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | > 03·07 | — | — | 변이는 모두 테스트 검출력을 본 것이다. 새 코드 결함은 찾지 않았다 | +| 2 | 구조적 성숙도 | > 16 | — | — | — | +| 3 | 변경 용이성 | 적용 | M2 / M2 | E1 | **P** — 테스트 전용 fixture(`tests/helpers/external-contract-fixture.ts`, `runtime-config.ts`, `memory-opfs.ts`)로 새 테스트를 쉽게 만든다. 조립 루트와 라우트 결정은 테스트 입력을 바꿀 자리가 없어 샘플에 기댄다(10-01) | +| 4 | 인지 부하 | 적용 | M2 / M2 | E1 | **P** — 한 unit 파일이 한 머지에서 몇 번 도는지 알려면 `gates.json`과 드릴 스크립트 다섯 개를 맞춰야 한다(13번, 1101/10-06) | +| 5 | 위험 가시성 | 적용 | M2 / M2 | E1·E2 | **P** — 제거 드릴 주석은 플랫폼 커버리지 보존을 약속하지만 파일 존재만 본다(10-01). EOF 테스트는 기동 실패를 "start-up"으로 따로 알린다(1103/10-01 고쳐짐) | +| 6 | 실패 성숙도 | 적용 | M3 / M3 | E2 | **P** — Envelope 실패 경계 9종이 모두 잡힌다. 오래된 scope의 성공 응답 버림(L01)은 아무도 고정하지 않는다 | +| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | — | +| 8 | 디버깅 가능성 | 적용 | M2 / M3 | E2·E3 | **O** — EOF 테스트가 기동과 EOF를 다른 이름으로 실패한다(`task3-selective-integration.test.ts:180`, `:272`). skip reporter가 이유와 다음 행동을 출력한다. 변이 실패 이름이 바꾼 규칙을 그대로 말한다(6절) | +| 9 | 유지보수 성숙도 | 적용 | M2 / M1 | E1 | **P** — `scopeSnapshot` 4벌, `as never` scope 10곳, `deferred()` 7벌(1101/10-08). `test:platform`의 `--no-file-parallelism` 이유 없음 | +| **10** | **테스트 성숙도** | 적용 | 목표 M3 / 확인 M3 | E2(변이 20종), E3(부하) | **P** — 지난 생존 변이 15종 중 14종이 잡힌다. 새 규칙 변이 3종(E7~E9)과 EOF 변이가 잡힌다. 남은 생존 2종: L01(네 라운드째), R2b(10-02). 샘플 제거 상태의 검출 공백(10-01) | +| 11 | 데이터 성숙도 | > 05 | — | — | Envelope 판정 경계가 고정돼 짝 백엔드 쓰기 중복 위험(지난 10-02)이 테스트로 막힌다 | +| **12** | **동시성 성숙도** | 적용(테스트 격리·CPU 경쟁) | M3 / M3 | E3 | **O** — 테스트 사이 상태 격리(`vitest.config.ts:40-42`, `tests/setup.ts:15-20`), 전역 stub 복원(`boot-unexpected-failure.test.tsx:19-23`). 한 코어에 이웃 14개를 둬도 자식 프로세스 테스트가 통과한다(10-eofload). 실제 러너 사양은 미확인(U-1) | +| 13 | 확장성 | > 11·15 | — | — | — | +| 14 | 성능 성숙도 | 적용(테스트 실행 비용) | M2 / M1 | E2 | **P** — unit 테스트 시간 합 130.9s 중 도구·자식 실행 테스트가 72%(1101/10-05 커짐). 한 머지에 `tests/unit` 13번(1101/10-06 커짐). 실제 시계 5초 대기 남음(1101/10-07). setup 누적 44.0s(R1) | +| 15 | 보안 성숙도 | 적용(보안 규칙의 테스트) | M3 / M3 | E2 | **O** — 쿠키 쓰기 CSRF 조립 검사가 method 4종 × 헤더 4종으로 고정됐다(C1~C3 잡힘) | +| 16 | 의존성 성숙도 | > 13 | — | — | — | +| 17 | API / Contract 성숙도 | 적용(계약 테스트) | M3 / M3 | E2 | **P** — Envelope 판정 표, 5xx 결과 불명 표, 선언 목록 규칙, realtime snapshot 바인딩(6 method × 4 retry)이 고정됐다. FE-REG-API `authProfileId`(H20)는 fixture가 모두 `ANONYMOUS`라 빠른 계층이 여전히 못 본다(`check:registries` 몫, 정적 판단, 5절) | +| 18 | 배포 성숙도 | > 13 | — | — | — | +| 19 | 설정 성숙도 | 적용(러너·런타임 설정) | M3 / M2 | E2 | **P** — `MAX_RETRY_ATTEMPTS` 전달이 머지 게이트에서 고정됐지만 샘플에 기댄다(10-01). `--passWithNoTests` 3곳 남음 | +| **20** | **개발자 경험** | 적용 | M2 / M2 | E2·E3 | **P** — 부하 거짓 실패의 원인이 사라졌다. `test:all`이 CI 빠른 테스트 일부(예제 기능 2파일, `tests/scripts`)를 빠뜨린다(0929/10-05). FE-GATE-020이 1,156초다 | +| **21** | **Guardrail 성숙도** | 적용 | M3 / M3 | E2 | **P** — skip·todo·only 차단 유지. 이번 diff에 약화된 검사 없음(3.0절). 플랫폼 규칙의 유일한 테스트가 샘플과 함께 지워지는 것을 드릴이 알리지 않는다(10-01) | +| 22 | 추상화 성숙도 | 적용(테스트 도우미) | M2 / M2 | E1 | **P** — 새 공유 도우미 셋(`runtime-config.ts`, `memory-opfs.ts`, `external-contract-fixture.ts` 확장). scope fixture 복사본은 그대로 | +| 23 | 일관성 | 적용 | M2 / M2 | E1 | **P** — 자식 프로세스 대기 방식이 준비 신호 하나로 맞춰졌다(guardian, task3). `deferred()` 7벌 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M2 / M2 | E2 | **O** — 지난 라운드에 범위보다 넓게 읽히던 두 테스트 이름이 이제 맞다("refuses a %s whose cookie profile…", Envelope 표 테스트). 새 listener 테스트 이름은 감시 범위(caller and scope)를 정확히 말한다 | +| 25 | 조직 확장성 | - | 작성자 1인 | — | — | +| 26 | Ownership 성숙도 | 부분 적용 | M2 / M1 | E1 | **P** — `ungated-tests.json` 항목에 담당·재검토 시점이 없다(12 영역) | +| 27 | 삭제 가능성 | 적용 | M3 / M2 | E1 | **P** — V2 삭제가 남긴 보호 공백 세 곳이 메워졌다. 대신 샘플 삭제가 플랫폼 규칙 테스트 둘을 함께 지운다(10-01) | +| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | — | + +집계(적용 19개, `>`·`-` 제외): 충족 4(8, 12, 15, 24) · 부분 충족 15 · 미충족 0 · 미검증 0. 지난 라운드는 충족 0 · 부분 충족 18이었다. 8·12·15·24가 오른 근거는 각 행의 실행 증거다. 10번은 남은 생존 변이 2종과 샘플 제거 공백 때문에 P로 둔다. + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 옛 EOF 테스트가 desktop의 같은 부하(이웃 6·14개)에서 떨어지는지 | `10-eofload-old`가 19:55 규칙 변경으로 취소됐다. 지금 판단은 추론이다: 이웃 14개에서 새 테스트 전체가 1.17~1.32s라, 기동+EOF를 1,075ms 안에 넣던 옛 모양은 넘었을 것이다. 1103/10-01의 완료 기준(F5 5/5 통과, EOF 처리 제거 시 실패)은 이것 없이 충족됐다 | 옛 테스트 파일(`git show e40684b:tests/unit/task3-selective-integration.test.ts`)로 같은 부하 3회 | +| 지난 라운드에 잡힌 변이 대조군(H02·H05·H12·H27)과 H20 | `10-mut-C`가 취소됐다. H20은 정적으로 판단했다: 빠른 계층 fixture의 `authProfileId`가 모두 `ANONYMOUS`라(`tests/helpers/external-contract-fixture.ts:36`, `:167`, `tests/unit/api-operation-rows.test.ts:44`) 상수 `ANONYMOUS` 변이는 여전히 빠른 계층을 통과하고 `check:registries`가 잡는다. 지난 라운드와 같아 발견으로 세지 않았다 | 다음 라운드 변이 묶음에 넣는다 | +| 샘플을 지운 복사본에서 H53·L02가 통과하는지(10-01) | 정적 근거로 판단했다(E1). 제거 드릴 복사본에 변이를 넣는 실행은 비싸다 | 10-01 완료 기준의 실행 | +| 테스트별 시간(1101/10-07의 실제 대기 합) | snapshot junit을 보지 못했다. 파일별 시간만 로그에서 셌다 | `desktop:/tmp/claude-gates/r4/snap/artifacts/tests/unit.xml` | +| 실제 CI 러너의 실패율 | CI 꺼짐(U-1) | U-1 뒤 FE-GATE-005·020을 20회 | +| 10-02의 실제 누수량 | 재지 않았다 | 한 interaction 안에서 요청 N번 뒤 listener 수 | + +## 6. 실행 기록 + +모든 실행은 desktop `exp.sh`(공유 잠금, 기준 `8a44226` 확인 후 실행, 끝나면 `reset --hard` + `clean`)로 했다. 변이 드라이버(`desktop:/tmp/claude-gates/r4/mut/10-driver.mjs`, 원본 scratchpad `r4/10/10-driver.mjs`)는 변이마다 정확한 문자열 하나를 바꾸고(1회 등장 확인), 대상 테스트를 `node scripts/run-vitest.ts run <파일>`로 돈다. 실패한 테스트가 없으면 `related <소스> --run`을 더 돈다. 매번 원본으로 되돌리고, 끝에 `git status`가 비었는지 출력한다. "잡힘"은 실패한 테스트 이름이 바꾼 규칙과 맞는 경우만 적었다. + +| 이름 | 명령 | 변이 | rc · 시간 | 결과 | 잠금 대기 · 부하 | restore | +|---|---|---|---|---|---|---| +| 10-mut-A | `node /tmp/claude-gates/r4/mut/10-driver.mjs A` | 아래 E1~E9 | 0 · 15s | 무변이 기준: 3파일 156개 통과. 9종 모두 잡힘 | 595s · 1.52 | clean | +| 10-mut-B | `node /tmp/claude-gates/r4/mut/10-driver.mjs B` | 아래 R1~P1 | 0 · 63s | 무변이 기준: 9파일 167개 통과. 9종 잡힘, 2종 생존(R2b, L01) | 583s · 1.56 | clean | +| 10-eofload | `bash /tmp/claude-gates/r4/mut/10-eofload.sh`: `taskset -c 11`로 테스트 파일 전체 실행, 같은 코어에 `node -e 'for(;;){}'` 이웃 N개 | 없음 | 0 · 98s | 이웃 0: 5/5, EOF 테스트 156~169ms. 이웃 6: 5/5, 596~610ms. 이웃 14: 3/3, 1,172~1,322ms. 파일 7개 모두 통과 | 646s · 7.22 | clean | +| 10-mut-C | 대조군 K1~K5 | — | 돌지 않음 | 19:55 취소(BRIEF-2) | — | 해당 없음 | +| 10-eofload-old | 옛 테스트로 같은 부하 | — | 돌지 않음 | 19:55 취소(BRIEF-2) | — | 해당 없음 | + +### 6.1 변이 + +| ID | 지키는 규칙(지난 ID) | 바꾼 곳(`8a44226`) | 결과 | 잡은 테스트 | +|---|---|---|---|---| +| E1 | 쓰기 전 거절 = code와 status 둘 다(H14 = 03-08 M6) | `backend-envelope.ts:194` status 대조 제거 | 잡힘(6) | `backend-envelope.test.ts` "reads a table code under another status …" 5, "never lets a declaration decide …" 1 | +| E2 | 표 밖 422는 결과 불명(H45) | `:346` `|| status === 422` 제거 | 잡힘(5) | `backend-envelope.test.ts` 4, envelope 통합 "keeps 400, 409, 422 outside the table …" 1 | +| E3 | 게이트웨이 408·425는 SERVER_FAILURE(H15) | `:372` 408·425 제거 | 잡힘(2) | `backend-envelope.test.ts` "reads a gateway 408/425 as a server failure" | +| E6 | 처리 중 409는 자동 재전송하지 않는다(03-08 M7) | `:364` 409 `IDEMPOTENT_IN_FLIGHT`도 참 | 잡힘(1) | envelope 통합 "does not resend a 409 IDEMPOTENT_IN_FLIGHT on its own" | +| E7 | 5xx 결과 불명 답도 status와 code를 함께 본다(새 규칙, `37615072`) | `:275` status 대조 제거 | 잡힘(1) | `backend-envelope.test.ts` "leaves a status the table does not speak for to the package" | +| E8 | 선언 목록이 멱등 code를 바꾸지 못한다(새 규칙, `1e8b3d04`) | `:324` 정규식 조건 제거 | 잡힘(1) | "never lets a declaration decide an idempotency answer or a table code" | +| E9 | 선언 목록이 표의 code를 바꾸지 못한다(새 규칙) | `:323` 표 조건 제거 | 잡힘(1) | 같음 | +| E4 | 실패 Envelope 한도 = min(64 KiB, 응답 한도)(H23) | `http-execution-v3.ts:1636` 항상 64 KiB | 잡힘(1) | envelope 통합 "refuses a failure Envelope above the operation's response limit" | +| E5 | 실패 응답 media type 검사(H10b) | `:1657` 조건 `false` | 잡힘(1) | envelope 통합 "refuses a failure Envelope that is not sent as JSON" | +| R1 | `MAX_RETRY_ATTEMPTS`가 실행기에 닿는다(H53) | `runtime-adapters.ts:502` 상수 2 | 잡힘(2) | `reference-runtime-composition.test.ts` "honours MAX_RETRY_ATTEMPTS 0/1" | +| R2 | 호출자 signal listener 정리(H56) | `http-execution-v3.ts:662` 제거 | 잡힘(2) | `http-execution-v3.test.ts` "removes the listeners … after an answer / a caller abort" | +| R3 | scope signal listener 정리(H57) | `:664` 제거 | 잡힘(2) | 같음. 지난 라운드는 nightly `long-session` 하나만 잡았다 | +| R2b | interaction signal listener 정리(새로 확인) | `:663` 제거 | **생존**(대상 69개, 관련 107파일 995개) | 없음 → 10-02 | +| R4 | realtime snapshot은 GET만(H21 = 04-03) | `realtime-streams.ts:470` → `operation !== undefined` | 잡힘(10) | `realtime-stream-registry.test.ts` HEAD·POST·PUT 등 행 | +| C1 | 쿠키 쓰기 CSRF — 모든 쓰기 method(H18 = 07-02 M2) | `external-contract-runtime.ts:589` `!isRead` → `method === "POST"` | 잡힘(3) | `rest-profile-contract.test.ts` "refuses a PUT/PATCH/DELETE …" | +| C2 | `x-csrf-token`도 허용(H19) | `:592` `x-csrf-token` 제거 | 잡힘(4) | "accepts a POST/PUT/PATCH/DELETE that requires x-csrf-token or x-xsrf-token" | +| C3 | CSRF 헤더 이름만 증명이다(07-02 M3) | `:591-593` → 필수 헤더 수 > 0 | 잡힘(4) | "refuses a %s whose cookie profile requires no CSRF header" | +| L01 | §10.8 오래된 scope의 성공 응답 버림(0929/10-04) | `http-execution-v3.ts:1494` 조건 `false` | **생존**(대상 80개, 관련 107파일 995개) | 없음 → 0929/10-04 남음 | +| L02 | 복구 중 세션은 보호 라우트에서 기다린다(1101/10-03) | `navigation-policy.ts:21` → `show-sign-in` | 잡힘(1) | `navigation-policy.test.ts` "treats every non-public route as explicitly session-required" | +| P1 | EOF를 받으면 명령 프레임 없이 끝난다(1103/10-01 완료 기준) | `provider-scope-wrapper.ts:50` 제거 | 잡힘(1) | `task3-selective-integration.test.ts` "uses early liveness EOF …" (154ms에 code 불일치) | + +집계: 20종 중 18종이 잡혔고 2종이 살아남았다. 지난 라운드 생존 변이를 같은 규칙 자리에 다시 넣은 15종(E1~E6, R1~R4, C1~C3, L01, L02) 중 14종이 잡혔다. 수정 뒤 새 규칙 3종(E7~E9)과 EOF 변이(P1)는 잡혔고, 새로 확인한 R2b는 살아남았다. 관련 실행(`related`)은 생존 변이에만 돌았다. + +### 6.2 그 밖의 분석 + +| ID | 방법 | 결과 | +|---|---|---| +| J1 | 오케스트레이터 `test_unit.log`의 파일별 시간(194줄)을 파일의 import 대상(`src`/`scripts`/둘 다/없음)으로 분류해 합산(노트북, 로그 사본) | 합 130.9s. `src`만 116파일 18%, `scripts`만 51파일 55%, 둘 다 12파일 9%, 없음 15파일 17% | +| D1 | `git diff e40684b 8a44226 -- <영역 경로>`에서 지운 `expect`·`it` 줄, 새 skip·시간 한도·정규식·matcher를 파일별로 대조 | 3.0절 표 | +| D2 | 한 머지의 `tests/unit` 실행 횟수를 `gates.json` merge stage와 드릴 스크립트에서 셈 | 13번(`e40684b` 11번) | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 10-01 | Low · P3 | 구조적 위험 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라지고 제거 드릴은 알리지 않는다 | `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`, `tests/unit/navigation-policy.test.ts:40-56`, `scripts/test-sample-removal.ts:130-161` | +| 10-02 | Low · P3 | 구조적 위험 | 실행기가 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다(호출자·scope 쪽만 고정) | `src/adapters/http/http-execution-v3.ts:663`, `tests/unit/http-execution-v3.test.ts:764-805` | + +이월(새 발견으로 세지 않음): 0929/10-04(§10.8, L01 생존, 네 라운드째), 1101/10-05·10-06(커짐), 1101/10-07, 1101/10-08, 0929/10-05, `--no-file-parallelism`, `--passWithNoTests`, R1, R6, `tsc-diagnostics-parser` 제외(12 영역). 모두 Low. diff --git a/docs/reviews/2026-11-05-maturity-review/11-tests-browser-release-scale.md b/docs/reviews/2026-11-05-maturity-review/11-tests-browser-release-scale.md new file mode 100644 index 00000000..cf54d7a3 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/11-tests-browser-release-scale.md @@ -0,0 +1,263 @@ +# 영역 11 — 테스트: 브라우저·릴리스·규모 + +> 검토일 2026-11-05 · 기준 `8a44226`(`8a4422624e81e5d13a3809e212e826ff75aac62b`, 브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `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/check-system-test-prerequisites.ts`, `scripts/run-and-validate-provider.ts:240-300`, `scripts/write-a11y-report.ts`, `scripts/create-feature.ts`(목록 페이지 틀 `:1160-1222`), `scripts/drill-runbook.ts`, `tests/unit/runbook-drill.test.ts`, `tests/unit/indexeddb-runtime.test.ts:450-485`, `scripts/generate-ci-workflow.ts`·`.gitea/workflows/quality-gates.yml`(글꼴 단계), `scripts/lib/visual-test-fonts.ts`, `scripts/lib/build-environment.ts`, `config/hosting/security-headers.json`, `config/ci/gates.json`(FE-GATE-008·009·013) +> 깊게 본 관점: 10, 21, 8, 20, 18 +> 이번 라운드 렌즈(오케스트레이터 필수 4건): (1) 1103/11-09 수정 `aad005cb`의 preload 사용 검사가 실패해야 할 때 실패하는가. (2) 1103/11-10 수정 `ee37dd86`의 고정 층이 RED를 없애는가, 무엇을 건너뛰는가. (3) FE-GATE-013 `test:system` 실패 18건 분류. (4) 1103/11-01~11-10과 0929/11-* 이월 항목 상태 +> 영역 판정(35.8): **조건부 사용 가능.** 오케스트레이터 merge-48(CI env)에서 FE-GATE-008이 통과했다(e2e 202 통과·3 quarantine skip, capability 66, storybook 1, visual 6, 재시도 0). 브라우저 검사의 두 수정(11-09, 11-10)은 변이로 실패 방향까지 확인했다(배치 11-R1~R7). FE-GATE-013은 `test:system` 18건 때문에 실패했고, 18건 모두 호스트 원인이다(11-R10: 이 호스트의 bwrap은 repo 없이도 user namespace를 못 쓴다). 다음은 그대로 믿지 않는다. (a) strict fixture가 preload 결과를 버려도 커밋된 test는 아무것도 실패하지 않는다(새 11-01, 11-R3에서 확인). (b) `test:system`은 bwrap이 user namespace를 못 쓰는 호스트(desktop)에서 사전 점검 PASS 뒤 18건이 샌드박스 회귀처럼 실패한다(새 11-02, 영역 12의 12-01과 같은 결함). (c) 생성 기능의 상세 라우트는 접근성 e2e에서 실패 화면으로 검사되고 `a11y.json`은 "passed"라고 적는다(1103/11-01 남은 것). (d) CI 러너 위 실행은 여전히 없다(U-1) + +ID 표기: 이번 라운드 새 발견은 `11-01`부터 쓴다. 라운드 밖에서는 `1105/11-01`이다. 지난 라운드는 `1103/11-NN`(2026-11-03), 그 전은 `1101/…`, `0929/…`다. `11-Rk`는 `scratchpad/r4/requests/11.md`의 배치 실험이고, 결과 로그는 `scratchpad/r4/results/11/11-Rk.log`다(6절). + +## 0. 결론 + +- **1103/11-09(preload 검사)는 고쳐졌다.** strict fixture는 WebKit의 3초 추정 경고 한 문구만 정확한 정규식으로 무시한다(`tests/support/browser/strict-browser-test.ts:16-25`). 대신 세 엔진에서 같은 방법으로 "preload한 build script가 끝까지 실행됐는가"를 본다(`tests/support/browser/preload-use.ts:117-141`, `:173-231`). 변이 결과: check가 실패를 안 내면 변이 test가 세 엔진에서 실패했다(11-R1). 평가 표시를 빼면 9건 모두 실패했다(11-R2). strict test 안의 진짜 안 쓴 preload는 세 엔진에서 실패했다(11-R4 P1). WebKit 문구 그대로는 무시되고, Chromium 문구·뒤에 글자를 붙인 문구·같은 문구의 `console.error`·다른 warning은 세 엔진 모두 실패했다(11-R4 P2~P6). 허용 규칙을 가진 spec 셋(boot·old-tab·production-csp) 안에 허용 밖 안 쓴 preload를 넣으면 셋 다 그 한 줄로 실패했다(11-R5). 앞에 붙인 한 문장은 CSP 검사를 바꾸지 않는다. CSP가 `script-src 'self'`이고 해시·SRI가 없다(`config/hosting/security-headers.json:4`). +- **새 11-01(Low·P2): 증명 spec이 실패 방향 절반을 고정하지 않는다.** `preload-use.spec.ts`의 변이 test는 fixture가 아니라 tracker를 직접 부른다(`tests/e2e/preload-use.spec.ts:46`). strict fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다(`:105-144`). fixture가 `check()` 결과를 버리는 변이(11-R3)에서 `preload-use.spec.ts` 9건이 모두 통과했고, 안 쓴 preload를 넣은 probe P1도 세 엔진에서 통과했다. 같은 probe는 변이가 없으면 세 엔진에서 실패한다(11-R4). 3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다(`:126`). 지금은 찾는다(11-R1 끝 줄: `reference-feature-contract-contribution` 청크). +- **1103/11-10(고정 층)은 고쳐졌다.** 두 test가 붙이는 control은 `position: fixed` 층에 있다(`tests/browser-capabilities/browser-files.spec.ts:11-12`, `:34-37`, `:245-248`). mousedown 때 앱 root를 400 px 늘리는 재현에서 수정이 있으면 3건 모두 통과했다(11-R6). 수정을 되돌리면 두 test가 `filechooser`·`download` 대기 30 s 시간 초과로 실패했다(11-R7, firefox). 클릭은 여전히 Playwright의 신뢰된 클릭이고, 단언은 그대로다. 건너뛰는 검사는 없다. +- **FE-GATE-013의 `test:system` 18건은 모두 호스트 원인이다.** merge-48 실행(114건 중 18 failed, snapshot `artifacts/tests/system.xml`도 `failures="18"`)과 같은 커밋 메인 세션 실행(10:31)의 실패 18건이 이름까지 같다. 12건은 provider가 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 시작도 못 했다. 6건은 같은 provider가 시작하지 못해 기다리던 파일이 생기지 않았다. repo 없이 이 호스트에서 bwrap을 돌려도 `--unshare-net`은 같은 RTM_NEWADDR로, 네트워크 없는 `--unshare-pid --unshare-ipc --unshare-uts`도 `setting up uid map: Permission denied`로 실패한다(11-R10). 코드 결함으로 볼 실패는 없다. FE-GATE-013의 나머지 명령 7개는 모두 rc=0이다(`r4/013-rest`). 이 실패를 사전 점검이 PASS로 넘긴다(새 11-02, Low·P3, 영역 12의 12-01과 같은 결함). +- **지난 영역 11 발견 10건 재판정(2절).** 고쳐짐 6건(11-05·06·07·08·09·10), 일부 4건(11-01은 상세 라우트가 남음, 11-02·03·04는 코드가 들어왔고 완료 기준 실행이 남음). 11-01의 목록 라우트 쪽 완료 기준은 배치로 확인했다(11-R8b: 빈 상태에만 넣은 이름 없는 button을 세 엔진 axe가 잡음, 11-R8c: 응답 모양이 틀리면 경고 상자 단언에서 실패). 이월: 0929/11-08·11-09와 resumable 포트는 고쳐짐. 0929/11-02·11-04·11-05 잔여·11-07과 FOLLOW-UP 2건은 남음. +- **검사를 약하게 만든 수정:** 새 결함으로 셀 것은 11-01 하나다. 나머지 축소는 기록된 결정이나 지난 리뷰가 고른 방향이다. 시각 골든에서 기능 링크·4개 절을 뺀 것(D3, `tests/visual/platform.visual.spec.ts:17-54`), provider 테스트 상한 30초(지난 11-03의 개선 방향), IndexedDB 전이 상태 폴링 삭제(단위 테스트가 고정), storybook a11y 애드온 자동 실행 끔(spec이 axe를 직접 돈다). 3.3절 표. +- 실행: 이 영역이 직접 돌린 desktop 실행은 없다. 처음 넣은 세 실행(`11-preload`, `11-allow-files`, `11-a11y`)은 19:55에 줄에서 취소됐다(한 번도 돌지 않았다). 실험 10건은 오케스트레이터 배치로 돌았고 모두 복원이 깨끗했다(6절). 10건 모두 기대와 같은 결과였다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 11. `e40684b..8a44226`에서 이 영역 경로 29파일이 바뀌었다(+1,113/−128, `git diff --stat`). 새 파일: `tests/support/browser/preload-use.ts`(233줄), `tests/e2e/preload-use.spec.ts`(144줄), `tests/e2e/support/installed-api-answers.ts`(63줄). 골든 3장 교체 | +| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree에서 읽기만 했다. 이 영역 수정 커밋: `aad005cb`(11-09), `ee37dd86`(11-10), `b0195e3d`(11-02), `90440082`(11-03), `0edc3fc9`(11-04), `8d328c9c`(11-05), `b3ce7322`(11-06), `af312dee`(11-07), `b6936001`(11-08), `7f633106`(11-01), `ed499736`(resumable 포트), `0a6ff6e5`(12-01 시각 골든), `f92cfd9a`(storybook), `9bddfa52`(시각 빌드 식별값). 영역 밖이 이 경로를 건드린 것: `d13a3936`(05-01 OPFS test), `2d5d41f8`(08-02 키보드 포커스 e2e), `851fdedb`(08-04 라우트 테스트), `9edc8307`(09-09), `2963c6f4`(09-05 SW 선택 파일), `b96d61d8`(09-04 예제 화면). 영역 밖 `529615dc`(로그 추적 끊기), `8cd60bfb`(drill 검사) | +| 목적과 지원 실행 구성 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음. 브라우저 테스트는 FE-GATE-008(e2e·capability·storybook·visual)과 FE-GATE-009(`test:a11y`), 샌드박스 경계는 FE-GATE-013(`test:system`)이 merge 단계에서 돈다(`config/ci/gates.json:1893-1903`, `:2011-2022`) | +| 필수 요구와 규모·운영 목표 | 사용자 목표: 두 템플릿을 짝으로 써서 서비스를 빨리 출시한다. merge 게이트는 1회 판정이므로 코드와 무관한 실패가 없어야 한다(지난 라운드 심각도 기준). 규모·성능 목표는 영역 15 | +| 실행 환경 | 이 영역의 실행 없음(BRIEF-2: 별도 desktop 실행 금지, 배치 1회). 근거로 쓴 출력: 오케스트레이터 `desktop:/tmp/claude-gates/r4/merge-48/summary.txt`(CI env, 19:20 시작, load 0.42): FE-GATE-001~012·020 rc=0, 013 rc=1. `r4/gates/summary.txt`(local env): `check:ci` 등 rc=0, `verify:documentation` rc=1(영역 14). `r4/013-rest`: FE-GATE-013 나머지 명령 7개 rc=0. FE-GATE-008·013의 상세는 merge-48이 쓴 게이트 로그 파일(desktop checkout `artifacts/quality/gates/FE-GATE-008.txt` 19:56, `FE-GATE-013.txt` 20:00)을 snapshot 전에 복사해 읽었다(사본 `scratchpad/r4/a11/FE-GATE-008.m48.txt`, `FE-GATE-013.m48.txt`). 두 사본은 snapshot(`desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/`)의 같은 파일과 sha256이 같다(`fba324b9…`, `7fd37e75…`). 같은 커밋 메인 세션 실행(FE-GATE-013 10:31)은 대조에만 썼다. 배치 실험은 오케스트레이터가 같은 desktop checkout(`8a44226`)에서 local env로 돌렸다(20:11~20:16, load 1.7~6.5) | +| 읽은 코드·구성 범위 | 전부: 위 수정 커밋의 영역 diff, `preload-use.ts`, `strict-browser-test.ts`, `preload-use.spec.ts`, 허용 규칙을 가진 spec 4개(`boot-module-failure`, `old-tab-chunk-recovery`, `service-worker-update`, `production-csp`), `browser-files.spec.ts`, `accessibility.spec.ts`, `installed-api-answers.ts`, `check-system-test-prerequisites.ts`. 필요한 부분: `ci-artifact-contract.test.ts`의 provider 묶음(`:453-1204`), `service-worker-builds.ts:262-330`, `fixture-builds.ts:15-66`, `opfs-runtime.spec.ts` 새 test, `platform.visual.spec.ts`, `workshop.spec.ts` | +| 수행한 테스트·실험 | 배치 10건(11-R1~R8c, R10, 6절). 패치 9개는 노트북에서 `git apply --check`로 `8a44226`에 붙는 것을 먼저 확인했다 | +| 확인하지 못한 범위·이유 | `test:system` provider 묶음은 desktop에서 돌 수 없다(11-02). 그래서 1103/11-03·11-04의 완료 기준을 이 호스트에서 확인할 길이 없다. 실제 Gitea 러너(U-1). 글꼴이 없는 깨끗한 Ubuntu에서 FE-GATE-008 | +| 이전 리뷰와 비교 가능한 범위 | 지난 README 12절의 영역 11 행 5건(11-01~05), 13절 추가 5건(11-06~10), 10.3절에서 11-01에 합친 12-03·16-03 뒷부분, 지난 영역 문서 2절의 "남음" 이월(0929/11-02·04·05·07·08·09, FOLLOW-UP 3건). 지난 실행 결과는 증거로 쓰지 않았다. README 14.4의 "고침"은 주장으로 보고 코드와 오늘 게이트 출력으로 다시 봤다 | + +## 2. 지난 발견 재확인 + +상태: 고쳐짐(완료 기준 확인) / 일부(남은 것) / 남음 / 재발 / 틀린 발견. "일부(검증 남음)"은 코드 변경은 들어왔고 완료 기준 실행만 남은 경우다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/11-01 (+12-03, 16-03 뒷부분) | 생성 기능 라우트를 접근성 e2e가 Envelope 불일치 오류 화면으로 검사하고 `a11y.json`은 "passed" | **일부** | 고쳐진 것: spec이 설치된 descriptor로 GET을 찾아 빈 목록을 그 모양으로 답한다(`tests/e2e/support/installed-api-answers.ts:33-62`, Envelope면 `successEnvelope([])` `:42-45`). 목록 라우트는 "경고 상자가 없다"를 단언한 뒤 axe를 돈다(`tests/e2e/accessibility.spec.ts:72-74`). 답하지 못한 요청은 501로 답하고 test가 실패한다(`:55-56`, `:65-68`). 매뉴얼 문장이 동작과 맞다(`docs/manual/reference/create-feature.md:97`). **남은 것:** 하나의 자원을 읽는 라우트(생성기 `--with-create`의 상세 페이지, `scripts/create-feature.ts:360`)는 빈 목록으로 답할 수 없어 실패 화면으로 검사되고 annotation만 남는다(`accessibility.spec.ts:75-81`). `scripts/write-a11y-report.ts:11-17`은 그대로 모든 라우트 ID를 `scope`에 넣고 `automatedStatus: "passed"`를 쓴다. 지난 README 14.4도 16-03 쪽 남은 것으로 적었다. **완료 기준 실행(목록 라우트):** `create:feature sample-feature --with-create`(라우트 `/sample`, `/sample/items/:sampleId`, `/sample/new`) 뒤 생성 목록 페이지의 빈 상태에만 이름 없는 button을 넣자 `@a11y /sample`이 세 엔진 모두 `accessibility.spec.ts:88`의 axe `button-name`(`.zz-review-unnamed`)으로 실패했다. 상세·작성 라우트는 세 엔진 통과했고, 상세 라우트의 `a11y-data-state` annotation이 JSON 결과에 남았다(11-R8b). 답이 Envelope를 무시하게 바꾸자 `@a11y /sample`이 axe 전에 `accessibility.spec.ts:74`의 경고 상자 단언(받은 값 1)으로 실패했다(11-R8c). 같은 실행에서 상세 라우트는 실패 화면 그대로 통과했다. 그래서 목록 쪽 완료 기준은 충족, 상세 라우트와 `a11y.json` 쪽이 남는다 | +| 1103/11-02 | CI merge job이 시각 테스트 글꼴을 설치하지 않음 | **일부(검증 남음)** | 생성기와 workflow의 브라우저 단계 두 곳이 패키지 4개를 설치한다(`.gitea/workflows/quality-gates.yml:72`, `:111`). 목록은 한 곳에서 읽는다(`scripts/lib/visual-test-fonts.ts:9-16`, `tests/visual/fonts.setup.ts:6`, `:22-23`). 남은 것: 완료 기준 3번 "글꼴 없는 깨끗한 Ubuntu 24.04에서 그 단계 뒤 `test:visual` 6/6"은 커밋 본문도 실행하지 않았다고 적는다(`b0195e3d`). 러너가 root가 아니고 sudo도 없으면 `apt-get`이 실패한다(`$(command -v sudo || true)`). 생성기와 workflow가 맞는지는 `check:ci` rc=0(`r4/gates`). 글꼴이 있는 desktop에서는 merge-48 FE-GATE-008의 `test:visual` 6/6 통과 | +| 1103/11-03 | provider 테스트 10개가 10초 상한, 하나만 고르면 첫 테스트가 기반 fixture 빌드를 떠안음 | **일부(검증 남음)** | describe 옵션으로 묶음 전체가 30초다(`tests/system/ci-runner/ci-artifact-contract.test.ts:461`). 기반 fixture는 `beforeAll`에서 180초 상한으로 만든다(`:65-69`, `:462-464`). 묶음 안에 남은 개별 상한은 tar 폭탄 test의 40초 하나다(`:539`). 남은 것: 완료 기준(`-t 'kills descendants'` 단독 통과, loadavg 20+에서 5회)은 desktop에서 돌 수 없다. provider test가 호스트 원인으로 시작하지 못한다(11-02) | +| 1103/11-04 | worktree의 `.git` 파일 때문에 provider test 16개 실패, 사전 점검은 PASS | **일부(검증 남음)** | `.git`이 디렉터리면 tmpfs, 아니면 `/dev/null`을 `--ro-bind`로 겹친다(`scripts/run-and-validate-provider.ts:277-292`). 기반 fixture 복사가 `.claude`·`.worktrees`·`.tmp`·`graphify-out`을 뺀다(`ci-artifact-contract.test.ts:2235-2244`, `:2256`). 새 test가 두 모양을 본다(`:771-802`). 남은 것: 그 새 test 둘도 desktop에서는 호스트 원인으로 실패한다(4절 FE-GATE-013 분류). 가림을 지우는 변이는 커밋 본문도 "결론을 내지 못했다"고 적는다(`0edc3fc9`). 지금 증거는 E1뿐이다. 사전 점검이 worktree를 따로 보는 일은 없다(바꾸지 않았다) | +| 1103/11-05 | IndexedDB 차단 업그레이드 test가 500 ms 전이 상태를 폴링 | **고쳐짐** | 폴링을 지웠다(`tests/browser-capabilities/indexeddb-runtime.spec.ts:1023-1027` 주석, `:1028`). 남은 단언이 차단 결과(`code: "BLOCKED"`, `recovery: "RELOAD_OTHER_CONTEXTS"`)와 닫힌 상태를 본다(`:1029-1042`). 전이 상태는 제어된 시계로 단위 테스트가 고정한다(`tests/unit/indexeddb-runtime.test.ts:470-474`). 경쟁이 구조로 없어졌다. merge-48 FE-GATE-008에서 이 test가 세 엔진 모두 통과했다(1회). 지난 완료 기준의 5회 반복은 하지 않았다. 원인이 코드에서 사라졌으므로 고쳐짐으로 본다 | +| 1103/11-06 | compact smoke가 build id를 `local-build`로 고정 | **고쳐짐** | 기대값을 빌드와 같은 `VITE_BUILD_ID`에서 읽는다(`tests/e2e/compact-smoke.spec.ts:10`, `:27`). merge-48(`VITE_BUILD_ID=gitea-48-1`) FE-GATE-008에서 `[chromium-compact] compact-smoke.spec.ts:12` 통과. 기본값(`local-build`) 쪽 실행은 이번 라운드에 없다(코드상 `||` 대체값) | +| 1103/11-07 | CI 빌드 식별값이 vitest·dev server로 새어 merge 게이트 다섯 개 실패 | **고쳐짐** | dev·capability·visual web server가 로컬 식별값으로 뜬다(`playwright.capabilities.config.ts:35`, `playwright.dev.config.ts:17`, `playwright.visual.config.ts:57`). 완료 기준 "CI env로 merge 단계 14개 통과": merge-48에서 FE-GATE-005·006·007·008·020 rc=0. 14개 중 013만 실패이고 원인은 호스트다(3.2 (3)). capability 66건에 "Execution context was destroyed"가 없다 | +| 1103/11-08 | `CI=true`가 테스트 안 로컬 빌드까지 release 빌드로 검사 | **고쳐짐** | fixture 빌드 두 helper가 `localBuildEnvironment()`로 `CI`와 CI 식별값을 지운다(`tests/e2e/support/fixture-builds.ts:65`, `tests/e2e/support/service-worker-builds.ts:179`, `scripts/lib/build-environment.ts:61-66`). merge-48(`CI=true`, `CI_RUNNER_IMAGE` 포함): FE-GATE-005·008·020 rc=0. fixture 빌드를 쓰는 e2e(boot·old-tab·SW update/recovery)가 모두 돌았다 | +| 1103/11-09 | WebKit 3초 preload 추정에 기대어 FE-GATE-008이 가끔 실패하고, 정말 안 쓴 preload는 놓침 | **고쳐짐** | 3.2절 (1). 변이 없는 실행: merge-48 FE-GATE-008에서 `preload-use.spec.ts` 3건과 허용 spec 4개(boot·old-tab·production-csp·SW update)가 세 엔진 모두 통과(firefox SW 2건은 quarantine skip). 지난 13절의 두 증상: 곧 쓰일 preload(3.5 s 늦은 부모 청크)는 strict test에서 세 엔진 통과(11-R4의 `preload-use.spec.ts:105`), 정말 안 쓴 preload는 strict test에서 세 엔진 실패(11-R4 P1). 실패 방향 변이 셋(11-R1, R2, R5)도 모두 잡혔다. 증명 spec이 fixture 쪽 실패를 고정하지 않는 빈틈은 새 11-01 | +| 1103/11-10 | capability 파일·다운로드 test 버튼이 클릭 도중 움직여 firefox 시간 초과 | **고쳐짐** | 3.2절 (2). 변이 없는 실행: merge-48 FE-GATE-008에서 `browser-files.spec.ts:14`, `:225`가 세 엔진 모두 통과(1회). 400 px 재현: 수정 있음 3/3 통과(11-R6), 수정 되돌림 2/3 실패(두 test 모두 30 s 시간 초과, 11-R7). 지난 커밋 본문의 RED/GREEN과 같다 | +| 0929/11-02 | 운영 drill이 어떤 입력으로도 PASS가 될 수 없음 | 남음 | `scripts/drill-runbook.ts:245`, `:350`, `:392`, `:433`의 `providerVerificationRequired: true` 상수 그대로. `main()`은 runbook ID와 `--release-root`만 받는다(`:518-525`). 거짓 PASS는 내지 않는다(`:549`) | +| 0929/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(코드 기준, 영역 15) | `scripts/test-performance.ts`는 `d99301b` 뒤로 바뀌지 않았다(`git log`). `performance-budgets.ts`의 `46dfe23f`는 bundle 예산 변경이다. 실측은 영역 15 | +| 0929/11-05 남은 것 | 규모 기준선이 지금 코드를 대표하는지 | 남음(미검증, 영역 15) | `config/scale/feature-shape-growth.json:3`, `:16` — 2026-11-01 측정, 커밋 `373b27b`. 그 뒤로 기준선 파일은 바뀌지 않았다 | +| 0929/11-07 | 빌드 helper 두 벌 | 남음 | 제외 목록이 다르다(`.tmp`는 `fixture-builds.ts:24`에만). `run`(`fixture-builds.ts:55`, `service-worker-builds.ts:174`)과 한 번 치환(`editOnce` `fixture-builds.ts:43`, `replaceOnce` `service-worker-builds.ts:108`)이 두 벌이다. 일반 서버 `startBuildServer`(`service-worker-builds.ts:270`)를 SW와 무관한 spec 둘이 쓴다(`old-tab-chunk-recovery.spec.ts:15`, `boot-module-failure.spec.ts:11`). 지난 판단대로 결함으로 올리지 않는다(리팩토링 후보) | +| 0929/11-08 | drill "상수 판정 금지" 검사가 옛 모양만 찾음 | 고쳐짐 | `tests/unit/runbook-drill.test.ts:128-132`가 문자열 모양 셋을 더 찾는다(`8cd60bfb`). 지난 변이(`scripts/drill-runbook.ts:235-239`의 `verdict(await builtAssetsPresent(...))`를 `"PASS"`로)는 `assertion(…, "PASS",\n )` 꼴이 된다. `:130`의 `[^;]*`는 줄바꿈을 넘고 `,?\s*\)`가 끝 쉼표를 받으므로 이 모양을 잡는다(정적 대조). 변이 실행은 하지 않았다(커밋 본문이 실행했다고 적는다). 변이 없는 실행: `r4/gates/test_unit.log`에서 `runbook-drill.test.ts` 9건 통과. 변수에 담아 넘기는 우회는 여전히 못 본다(커밋 본문의 한계, 동작 test가 본다) | +| 0929/11-09 | 규모 tier 실행 로그가 커밋됨 | 고쳐짐 | `.gitignore:17` `artifacts/**/*.log`. `git ls-files 'artifacts/**/*.log'` 0개(`529615dc`). 로그를 읽는 코드는 없다(`git grep`) | +| FOLLOW-UP | `resumable-upload.spec.ts` 포트 하드코딩 | 고쳐짐 | 설정의 `baseURL`에서 origin을 읽는다(`tests/browser-capabilities/resumable-upload.spec.ts:5`, `:10`, `ed499736`) | +| FOLLOW-UP | SW update spec의 route chunk 변경을 helper 옵션으로 | 남음(문서화된 전제) | 아직 spec의 `beforeBuild`에서 덧붙인다(`tests/e2e/service-worker-update.spec.ts:58-73`). 전제는 주석에 있다 | +| FOLLOW-UP | Firefox SW quarantine | 남음(만료 2027-03-31) | `service-worker-update.spec.ts:181`, `service-worker-recovery.spec.ts:84` | + +## 3. 이번 발견 (36.3) + +심각도 분포: Critical 0 · High 0 · Medium 0 · Low 2. 우선순위: P2 1 · P3 1. 성격: 구조적 위험 1 · 확인된 결함 1. + +### 3.1 발견 + +#### 11-01 strict fixture의 preload 검사를 증명하는 spec이 실패 방향 절반을 고정하지 않아, fixture가 그 결과를 버려도 커밋된 test는 아무것도 실패하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 10, 21, 5 | +| 근거 | **증명 spec:** `tests/e2e/preload-use.spec.ts` 머리 주석은 "These tests prove that check on a real build"라고 적는다(`:15`). 그런데 안 쓴 preload를 넣는 변이 test는 `@playwright/test`의 맨 `test`에서 tracker를 직접 부른다(`:5`, `:45-46`). strict fixture를 쓰는 test는 3번 하나이고, "fixture가 통과해야 한다" 방향만 본다(`:105-144`). **fixture 연결:** strict fixture가 tracker 결과를 실패 목록에 넣는 곳은 한 줄이다(`tests/support/browser/strict-browser-test.ts:62`). 이 줄을 지우거나, 무시 정규식(`:16-17`)을 넓혀도 실패할 test가 없다. 다른 spec은 `allowedBrowserFailure`로 실패를 허용만 하고, 실패가 나야 한다고 단언하는 곳은 없다(`git grep allowedBrowserFailure`). 커밋 본문의 "새 fixture: 3/3 실패"는 커밋하지 않은 probe였다(`aad005cb` 본문 "변이를 fixture에 직접 넣은 probe(커밋 안 함)"). **조용한 퇴화:** 3번 test는 "boot가 아직 안 받은 청크를 import하는 기능 실행부의 정적 import"를 manifest에서 찾는다(`:116-123`). 못 찾으면 `if (parent !== undefined)`(`:126`)에서 지연을 걸지 않고 평범한 화면 방문으로 통과한다. 지금은 찾는다. 같은 계산을 빌드한 manifest에 돌리면 `_reference-feature-contract-contribution-XD-KpqsD.js`가 나온다(11-R1 끝 줄). 기능 실행부 모양이 바뀌면 이 test는 경고 없이 아무것도 재현하지 않게 된다. **변이 실행(11-R3, local env, 세 엔진):** `strict-browser-test.ts:62`를 `await preloads.check();`로 바꾸고, strict fixture로 안 쓴 modulepreload(`/assets/async-state-Cxfod8c-.js`)를 넣는 probe P1을 더했다. 결과: `preload-use.spec.ts` 9건 모두 통과, P1도 세 엔진 모두 통과(놓침). **대조(11-R4, 같은 명령, fixture 변이 없음):** P1이 세 엔진 모두 `preloadunused:/assets/async-state-Cxfod8c-.js`로 실패, `preload-use.spec.ts` 9건 통과. 그래서 그 한 줄이 사라져도 커밋된 test가 알아채지 못한다는 것이 실행으로 확인됐다 | +| 발생 조건 | strict fixture(`strict-browser-test.ts`)를 고치는 변경. 또는 Vite·기능 실행부 구조가 바뀌어 3번 test의 `parent`가 사라질 때 | +| 영향 | 1103/11-09가 새로 만든 검사(세 엔진의 안 쓴 preload 검출)가 조용히 사라질 수 있다. 사라져도 FE-GATE-008은 초록이다. 사용자 피해는 없다. 낭비된 다운로드 회귀를 다시 놓치게 된다. 템플릿을 받은 제품도 같은 fixture를 받는다 | +| 심각도·우선순위 | Low · P2 — 피해는 테스트 장치의 신뢰도에 한정된다. 고치는 비용이 몇 줄이다. 지난 라운드 1103/11-05와 같은 기준 | +| 통제·증거 | 목표 M3(fixture의 실패 방향을 test가 고정) / 확인 M2(검사는 구현됐고 동작하지만, fixture 쪽 실패를 고정하는 test 없음) · E3(11-R3·R4 변이와 대조) | +| 확실성과 남은 가정 | 연결 한 줄과 test 목록은 코드로 확정이다. `preload-use.spec.ts`가 그 변이를 놓친다는 것은 실행으로 확정이다. 전체 e2e도 놓친다는 것은 추론이다(초록 suite에는 진짜 안 쓴 preload가 없으므로 다른 spec도 실패할 이유가 없다). 무시 정규식을 넓히는 변이는 돌리지 않았다. 그 방향을 보는 커밋된 test가 없다는 것은 코드로 확인했다(11-R4의 P3~P6은 리뷰 probe다) | +| 결정의 근거 | 적용 제외 — 이미 정한 검사를 증명하는 test 보강이다 | +| 이해 비용 | fixture를 고치는 사람은 `preload-use.spec.ts`가 통과하면 검사가 살아 있다고 믿기 쉽다. 실제로는 tracker만 증명된다 | +| 최소 개선 방향 | (1) `preload-use.spec.ts`에 strict fixture로 안 쓴 preload를 넣는 test를 하나 둔다(이번 probe P1과 같다). 그 test는 `test.fail()`로 "fixture가 실패시켜야 한다"를 고정하거나, fixture의 실패 목록을 test가 읽을 수 있게 내보낸다. 같은 방식으로 WebKit 문구와 다른 warning 하나(이번 P3·P6)가 실패하는지도 고정한다. (2) 3번 test가 `expect(parent).toBeDefined()`로 시작한다 | +| 대안 비교 | 적용 제외 — test 추가 외에 고를 길이 없다. `test.fail()`과 실패 목록 노출은 같은 효과다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | test 1~3개, 엔진마다 수 초 | +| 재검토 조건 | fixture 검사가 별도 단위 테스트 가능한 모듈로 빠지면 그 모듈의 단위 test로 옮긴다 | +| 완료 기준 | 11-R3 변이(fixture가 결과를 버림)를 넣으면 `preload-use.spec.ts`가 세 엔진에서 실패한다. 무시 정규식을 `/.*/`로 넓혀도 실패한다. `parent`가 없으면 3번 test가 실패한다 | +| 검증 방법 | 11-R3과 같은 변이 + 정규식 변이로 `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +#### 11-02 `test:system` 사전 점검이 provider 샌드박스(bwrap namespace)를 한 번도 실행해 보지 않아, bwrap이 user namespace를 못 쓰는 호스트에서는 PASS 뒤 provider test 18건이 샌드박스 회귀처럼 실패한다 + +> 영역 12가 같은 결함을 12-01(Medium·P1, 러너 전제를 적지 않음 + 사전 점검 PASS 뒤 bwrap 원문 실패)로 적었다. 오케스트레이터가 README에서 둘을 합친다. 여기서는 영역 11이 본 근거와 등급을 그대로 적는다. + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 20, 26, 10, 21 | +| 근거 | **사전 점검:** `scripts/check-system-test-prerequisites.ts:15-38`은 `bwrap`·`systemctl`·`tar` 실행 파일, cgroup v2 controller, systemd bus만 본다. bwrap을 한 번도 실행하지 않는다. 실패 안내는 "compatible Linux CI-runner host"라고만 적는다(`:46-48`). **provider:** `scripts/run-and-validate-provider.ts:255-256`은 bwrap에 `--unshare-net`을 준다. bwrap은 새 네트워크 namespace에서 loopback을 올린다. **실행(merge-48 FE-GATE-013, CI env; 같은 커밋 메인 세션 10:31도 같다):** "System test prerequisites: PASS" 뒤 114건 중 18건 실패. 12건은 `sandboxed external provider failed: exit=1 … sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. 6건은 그 provider가 시작하지 못해 기다리던 파일이 안 생겼다는 메시지뿐이다(`provider output did not reach expected content` 4건, `expected path did not appear` 2건, `ci-artifact-contract.test.ts:1782`, `:1812`). 이 6건은 bwrap 원인을 보여 주지 않는다. 4절 FE-GATE-013 분류 표. **같은 bwrap을 쓰는 노트북**(Ubuntu 24.04.5, `kernel.apparmor_restrict_unprivileged_userns=1`, bwrap setuid 아님)에서는 지난 라운드에 provider 묶음이 돌았다(지난 영역 문서 6.2절 6번). 그래서 desktop만의 조건으로 본다. **호스트 확인(11-R10, repo 코드 없음):** desktop은 kernel `7.0.0-38-generic`, `kernel.apparmor_restrict_unprivileged_userns = 1`, bwrap 0.9.0(setuid 아님)이다. `bwrap --ro-bind / / --unshare-net /bin/true`는 같은 `loopback: Failed RTM_NEWADDR: Operation not permitted`로 rc=1이다. 네트워크를 빼고 `--unshare-pid --unshare-ipc --unshare-uts`만 줘도 `setting up uid map: Permission denied`로 rc=1이다. `systemd-run --user --scope` 아래에서도 같다. 즉 이 호스트의 bwrap은 비특권 user namespace를 쓸 수 없다. FE-GATE-013의 다른 명령 7개는 이 호스트에서 모두 통과한다(`r4/013-rest`) | +| 발생 조건 | bwrap이 비특권 user namespace를 만들거나 그 안에서 loopback을 설정하지 못하는 Linux 호스트(desktop: AppArmor 비특권 userns 제한, bwrap setuid 아님). 노트북도 같은 sysctl 값인데 지난 라운드에는 돌았다. 그래서 그 sysctl 하나로 갈리지는 않는다(원인 미상). 어떤 러너 이미지가 여기에 해당하는지는 미확인(U-1) | +| 영향 | FE-GATE-013이 코드와 무관하게 실패한다. 실패가 "sandboxed external provider failed"와 파일 대기 시간 초과로 나와 샌드박스 회귀처럼 보인다. 6건은 원인 문구도 없다. 사전 점검은 PASS라서 어디가 문제인지 알려 주지 않는다. 1103/11-04(worktree)와 같은 모양이다. 그때는 worktree를 지원하는 쪽으로 고쳤고 사전 점검은 그대로다 | +| 심각도·우선순위 | Low · P3 — 지금 확인된 범위는 개발·검증 호스트의 편의다. 러너가 같은 조건이면 merge 게이트가 항상 실패하는 Medium·P1이 된다(재검토 조건) | +| 통제·증거 | 목표 M3(사전 점검이 provider가 쓰는 샌드박스 옵션을 직접 시험하고 이유를 말함) / 확인 M1(필요 도구 목록만 확인) · E3(merge-48 게이트 로그 + 11-R10 호스트 확인) + E1 | +| 확실성과 남은 가정 | 사전 점검이 bwrap을 실행하지 않는다는 것, 18건의 메시지, 이 호스트의 bwrap이 repo 없이도 실패한다는 것은 확정이다. 6건이 같은 원인이라는 것은 같은 provider 시작 경로를 쓰고 같은 실행에서 났다는 데서 온 추론이다. 노트북과 desktop이 왜 갈리는지는 확인하지 않았다(환경은 고치지 않는다) | +| 결정의 근거 | 적용 제외 — 사전 점검에 provider와 같은 bwrap 호출 한 번을 더하는 보강이다 | +| 이해 비용 | 실패를 본 사람은 provider 샌드박스 코드(`run-and-validate-provider.ts`)와 18개 test를 읽고 나서야 호스트 문제라는 것을 안다. 메인 세션도 desktop 환경 문제로 따로 처리했다(지난 README 14.5 9·11회차) | +| 최소 개선 방향 | 사전 점검이 provider와 같은 bwrap 옵션 묶음(`scripts/run-and-validate-provider.ts:255-256`의 `--unshare-pid --unshare-ipc --unshare-uts --unshare-net`)으로 `/bin/true`를 한 번 돌린다. 옵션 묶음은 provider와 한 상수에서 읽는다. 11-R10처럼 네트워크를 빼도 실패하는 호스트가 있으므로 옵션 일부만 시험하면 안 된다. 실패하면 bwrap의 stderr와 "이 호스트의 bwrap은 비특권 user namespace를 쓸 수 없다"를 적고 멈춘다. 파일을 기다리는 test는 시간 초과 때 provider stderr를 메시지에 붙인다. 러너 전제는 영역 12의 12-01 방향대로 문서에 적는다 | +| 대안 비교 | 적용 제외 — `--unshare-net`을 빼는 것은 provider의 네트워크 차단 경계를 없애므로 대안이 아니다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 사전 점검에 bwrap 실행 1회(수 ms) | +| 재검토 조건 | 실제 러너에서 같은 RTM_NEWADDR이 나면 Medium·P1로 올리고, 러너 요구(비특권 userns + 네트워크 namespace)를 CI 문서와 러너 점검에 적는다 | +| 완료 기준 | desktop에서 `corepack pnpm test:system`이 사전 점검 단계에서 bwrap 원인과 함께 멈춘다. 지원 호스트에서는 그대로 PASS 뒤 114건이 돈다 | +| 검증 방법 | desktop과 지원 호스트에서 `corepack pnpm test:system` | +| 담당·기한·상태 | 미정 · 미정 · 신규(README에서 1105/12-01과 합칠 예정) | + +### 3.2 오케스트레이터 필수 확인 + +**(1) 1103/11-09 preload 검사 (`aad005cb`)** + +검사가 하는 일(코드): 문서마다 첫 바이트 전에 MutationObserver로 ``를 적는다(`preload-use.ts:61-87`). page.route로 `/assets/*.js`에 "이 URL이 평가됐다" 한 문장을 앞에 붙인다(`:38`, `:117-141`, `:152-171`, `:211`). test 끝에 preload됐는데 평가 기록이 없는 script를 `preloadunused:`로 센다(`:190-203`). script가 아닌 preload, worker 제어 중 preload, 표시 못 한 script는 `preloadunverifiable:`로 실패한다(`:192-200`). 끝까지 읽지 못한 문서는 `preloadcheck:unreadable-document`로 실패한다(`:221-227`). + +| 질문 | 판단 | 근거·상태 | +|---|---|---| +| (a) 진짜 안 쓴 modulepreload가 세 엔진에서 실패하는가 | 그렇다 | tracker 직접 호출: `preload-use.spec.ts:45-79`가 세 엔진에서 본다(FE-GATE-008 통과). strict test 안: 리뷰 probe P1이 홈 화면에서 안 받은 청크 `/assets/async-state-Cxfod8c-.js`를 modulepreload만 하고 실행하지 않자 세 엔진 모두 `unexpected browser console/page errors`에 `preloadunused:/assets/async-state-Cxfod8c-.js` 한 줄로 실패했다(11-R4). 커밋된 test에는 이 방향이 없다(11-01) | +| (a) fixture 변이를 무엇이 잡는가 | check가 실패를 안 내면 1번 test, 평가 표시를 빼면 세 test 모두, fixture가 결과를 버리면 아무것도 | 11-R1(`preload-use.ts:220` 실패 목록 비움): `reports a modulepreload the page never runs`만 세 엔진 실패(Expected `["preloadunused:/assets/async-state-Cxfod8c-.js"]`, Received `[]`), 나머지 6건 통과. 11-R2(`:139` 평가 표시 없음): 9건 모두 실패, 홈 화면만으로도 `preloadunused:` 26줄(boot·react·i18n 등). 11-R3(`strict-browser-test.ts:62` 결과 버림): 9건 통과 + probe P1 세 엔진 통과(놓침, 11-01) | +| (b) WebKit 무시가 정확한 문구인가 | 그렇다 | `strict-browser-test.ts:16-17`은 `^…$`로 묶인 WebKit 문구 하나이고 URL 자리만 `\S+`다. `:21`이 `warning` 타입만 본다. 엔진을 가리지 않고 문구로만 거른다. 11-R4(세 엔진): P2(WebKit 문구 그대로, `console.warn`) 통과. P3(Chromium 문구 "…has an appropriate \`as\` value…") 실패. P4(WebKit 문구 뒤에 " (and more)") 실패. P5(같은 문구를 `console.error`로) 실패. P6(다른 warning) 실패. 실패는 모두 `console:warning:`/`console:error:` 한 줄이다. 리뷰 probe라 커밋된 test는 아니다(11-01) | +| (c) 허용 규칙 아래에서 진짜 안 쓴 preload가 통과하는가 | 허용 목록에 없는 청크는 실패한다. worker 제어 중 preload는 통과한다(설계 한계) | **11-R5(chromium):** 네 spec의 주 단언 뒤에 허용 규칙이 이름 붙이지 않은, 아직 안 받은 청크 하나를 modulepreload하고 실행하지 않았다. boot-module-failure(`dist-broken`에서 `async-state-Cxfod8c-.js`), old-tab(`dist-a`에서 같은 청크), production-csp(`dist`에서 `badge-D6w1dKS_.js`)는 셋 다 `preloadunused:<그 청크>` 한 줄로 실패했다. service-worker-update "removed chunk" test는 `service worker controls: true` 상태에서 넣어 통과했다(아래 설계 한계 확인). **코드:** boot-module-failure: 깨진 빌드의 `boot.tsx` 정적 closure만(`boot-module-failure.spec.ts:46-64`). 끝 문서는 그 깨진 boot 문서 하나라 범위가 원인과 같다. old-tab: 없어진 페이지 이름 꼴 `MISSING_PAGE`(`old-tab-chunk-recovery.spec.ts:119`, `:168`)와 A 플랫폼 페이지·B UI routes의 정적 closure(`:155-169`). 끝에 남는 것은 B 탭 문서뿐이라 A 쪽 closure는 이제 B 탭 허용을 넓히기만 한다(A·B가 공유하는 청크). `context-routes-*`는 어느 context든 허용한다. 좁힐 여지는 있지만 실제 가림은 추론으로도 작다(B 탭은 그 청크들을 플랫폼 화면에서 이미 실행했다). service-worker-update: worker가 제어하는 문서의 preload 전부(`service-worker-update.spec.ts:50-52`). page.route가 worker 응답을 못 보므로 쓰였는지 알 길이 없다. 이 spec 안에서는 안 쓴 preload도 통과한다. 주석과 커밋 본문이 적은 한계다. production-csp: 허용 없음, `fulfillBuildScript`로 표시 유지(변이 없는 FE-GATE-008 통과가 쓰인 청크의 표시가 살아 있다는 증거다. 표시가 없으면 11-R2처럼 쓰인 청크도 전부 실패한다) | +| (d) 앞에 붙인 문장이 production-csp 등이 보는 것을 바꾸는가 | 바꾸지 않는다 | CSP는 `script-src 'self'`이고 해시 출처가 없다(`config/hosting/security-headers.json:4`). 붙인 문장은 같은 출처 외부 script 안이라 같은 규칙으로 허용된다. HTML 문서 응답에는 보안 헤더가 그대로 붙는다(`production-csp.spec.ts:36-39`, `preload-use.ts:124-130` 비-script 경로). 앱 HTML에 `integrity` 속성이 없다(`index.html`). 브라우저 쪽 크기 단언(`transferSize` 등)을 하는 browser spec이 없다(`git grep`). SW spec의 바이트 비교(`service-worker-update.spec.ts` "removed chunk" test의 `readFile` 대조, SW의 sha256 대조)는 worker가 직접 받은 바이트다. page.route는 worker 요청을 보지 않는다. `server.served`는 서버 쪽 기록이라 경로가 그대로다. `fulfillBuildScript`는 본문이 바뀌므로 `content-length`·`content-encoding`을 지운다(`:131-133`). 그래서 gzip 응답도 페이지에는 풀린 본문으로 간다. gzip 헤더 검사는 worker 쪽 test가 하므로 영향이 없다 | +| 부수 효과 | 기록 | page.route를 걸면 Playwright는 그 페이지의 HTTP cache를 끈다(Playwright 문서의 page.route 주의 문구, E0). 그래서 이제 strict fixture를 쓰는 모든 browser test가 HTTP cache 없이 돈다. 지금 HTTP cache 동작을 단언하는 browser test는 없다(테스트 서버는 `no-cache`를 보낸다, `service-worker-builds.ts:314`). 커밋 본문의 한계 목록에는 이 점이 없다. 결함으로 세지 않고 5절에 적는다 | + +**(2) 1103/11-10 고정 층 (`ee37dd86`)** + +| 질문 | 판단 | 근거·상태 | +|---|---|---| +| (a) 수정을 되돌리고 mousedown 때 앱 root를 400 px 늘리면 RED, 수정이 있으면 GREEN인가 | 그렇다 | 재현: 두 test의 click 직전에 capture 단계 mousedown listener가 `#root`에 `padding-block-start: 400px`를 주고 layout을 다시 계산한다. 11-R6(수정 있음, firefox): 3 passed(6.0 s). 11-R7(`ee37dd86`의 spec 변경을 되돌림, firefox, 줄 번호는 되돌린 파일 기준): `browser-files.spec.ts:3`이 `page.waitForEvent("filechooser")`, `:224`가 `page.waitForEvent("download")` 대기 중 30 s test 시간 초과로 실패, 세 번째 test(`showOpenFilePicker`)는 통과. 변이 없는 실행: merge-48 FE-GATE-008에서 두 test 세 엔진 통과 | +| (b) 고정 층 때문에 건너뛰는 검사가 있는가 | 없다 | 층은 control 셋(label·input·button)을 감쌀 뿐이다(`browser-files.spec.ts:34-37`, `:245-248`). 클릭은 그대로 `getByRole("button").click()`이라 신뢰된 입력이고, Playwright의 보임·안정·이벤트 수신 확인을 거친다(`:186`, `:324-326`). 파일 선택기·다운로드 이벤트 대기와 결과 단언(`:185`, `:201-224`, `:323`, `:340-`)은 바뀌지 않았다. 다운로드 anchor는 runtime이 `document.body`에 따로 붙인다(`src/adapters/browser-files/download-delivery-adapter.ts:66`). 층이 앱 header 왼쪽 위를 덮지만 두 test는 앱 UI를 누르지 않는다 | +| 남은 위험 | 기록 | 원인(앱이 첫 그리기 뒤 약 12 px 자람)은 그대로다. 두 test만 앱 흐름 밖으로 뺐다. 그리는 중인 앱 안의 요소를 바로 누르는 다른 browser test가 같은 이동을 만날 가능성은 남는다. 관찰된 사례는 없다(5절) | + +**(3) FE-GATE-013 `test:system` 실패 분류** + +출처: merge-48 FE-GATE-013(CI env, rc=1, 84 s)의 게이트 로그(`FE-GATE-013.m48.txt`). "System test prerequisites: PASS", 3파일 114건 중 18 failed / 96 passed. 실패는 모두 `tests/system/ci-runner/ci-artifact-contract.test.ts`의 `candidate archive and provider upload boundaries` 묶음이다. 같은 커밋 메인 세션 실행(10:31)의 실패 18건과 이름이 모두 같다. vitest가 같은 오류를 묶어 보여서 RTM_NEWADDR 블록은 8개이고, 그 블록이 아래 12건을 덮는다. + +| # | test | 실패 메시지 | 분류 | +|---|---|---|---| +| 1–3 | leaves no stale raw report after invalid trust / invalid archive / provider failure and permits a clean retry | `sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` | 호스트 | +| 4 | drains and kills provider background processes before sealing evidence | 같음 | 호스트 | +| 5 | does not expose or mutate a host path outside the sandboxed workspace | 같음 | 호스트 | +| 6–7 | hides repository metadata from the provider when .git is a directory / file (1103/11-04의 새 test) | 같음 | 호스트 | +| 8 | applies effective aggregate cgroup limits without exposing command or credentials | 같음 | 호스트 | +| 9 | observes EMFILE at the provider FD limit and still emits valid evidence | 같음 | 호스트 | +| 10 | enforces CPU RLIMIT before the independent wall-clock timeout | 기대 `exit=(?:137\|152)\|signal=SIGXCPU…`, 받은 값이 같은 bwrap 오류 | 호스트 | +| 11–12 | runs the vulnerability / provenance adapter offline and collects its unit | 같은 bwrap 오류 | 호스트 | +| 13–14 | kills and collects an active provider when its guardian dies / collects the whole provider scope when its supervisor dies | `provider output did not reach expected content` | 호스트(추론: provider가 시작하지 못해 출력 없음) | +| 15–16 | fails closed when the guardian dies after scope collection and before commit / cleans published evidence when the supervisor dies and permits same-workspace retry | `expected path did not appear` | 호스트(추론, 같음) | +| 17–18 | kills descendants and collects the scope on provider output / timeout termination | `provider output did not reach expected content` | 호스트(추론, 같음) | + +코드 결함으로 분류한 것은 0건이다. 통과한 96건에는 provider를 샌드박스에서 띄우지 않는 test가 모두 들어간다. 이 18건 때문에 1103/11-03·11-04의 완료 기준과 11-04의 가림 변이를 desktop에서 확인할 수 없다. 남는 코드 쪽 문제는 사전 점검과 진단 문구다(11-02). FE-GATE-013은 `test:system`에서 멈춘다. 나머지 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, `check:supply-chain:fixtures`, `check:supply-chain:provider-fixtures`, `check:security:fixtures`, `check:browser-security`)는 오케스트레이터가 `r4/013-rest`로 따로 돌려 모두 rc=0이다. 그래서 이 호스트에서 FE-GATE-013을 막는 것은 이 18건뿐이다. snapshot의 `artifacts/tests/system.xml`도 `tests="114" failures="18"`이다. 호스트 확인(11-R10, repo 코드 없음): bwrap 자체가 `--unshare-net`에서 RTM_NEWADDR, 네트워크 없이도 `setting up uid map: Permission denied`로 실패한다(11-02 근거). 이 결과로 분류를 "호스트"로 확정한다. 추론으로 둔 13~18번도 provider 시작 전에 bwrap이 실패하는 호스트라서 같은 원인으로 본다. + +**(4) 1103/11-*과 0929/11-* 이월 상태:** 2절 표. + +### 3.3 수정이 검사를 약하게 했는가 (`git diff e40684b..8a44226 -- <영역 경로>`) + +| 변경 | 약해진 것 | 판단 | +|---|---|---| +| strict fixture가 WebKit 경고 문구를 무시(`aad005cb`) | 끝에 열려 있지 않은 문서(이동·reload 전 문서)의 안 쓴 preload를 WebKit이 3초 뒤 잡던 경우가 사라졌다 | 대신 세 엔진에서 끝 문서를 검사한다. 커밋 본문 한계에 적혀 있다. 결함 아님. 증명 spec의 빈틈은 11-01 | +| old-tab 허용이 WebKit 전용 경고 → 모든 엔진의 `preloadunused:` | 허용이 엔진 전체로 넓어졌다 | 전에는 chromium·firefox에 preload 검사 자체가 없었다. 허용 청크 목록은 같은 계산이다. 결함 아님(3.2 (c)) | +| SW update spec에 `preloadunverifiable:service-worker:` 허용 | worker 제어 중 preload는 쓰였는지 안 본다 | 볼 수 없는 것이고 이름 붙인 허용이다. 결함 아님 | +| IndexedDB 전이 상태 폴링 삭제(`8d328c9c`) | 실제 브라우저에서 `BLOCKED` 전이 상태 단언 | 차단 결과 단언은 남았고 전이 상태는 단위 test가 고정한다. 지난 리뷰의 개선 방향 그대로. 결함 아님 | +| provider test 상한 10→30초(`90440082`) | 느려진 provider test가 늦게 실패한다 | 파일이 이미 정한 예산이고 지난 리뷰의 개선 방향이다. 결함 아님 | +| 시각 골든에서 기능 링크와 플랫폼 화면 4개 절을 숨김(`0a6ff6e5`) | 기능 링크 목록·설치 요약·라우트·계약·기능 절의 모양 회귀 | 기록된 결정(지난 README 14.2 D3). DataTable 하나·능력 카드·릴리스 신원·셸 CSS는 남고, 커밋 본문은 셸 링크 padding 변이를 두 장이 잡았다고 적는다(이번 미실행). 결함 아님 | +| storybook a11y 애드온 자동 실행 끔(`f92cfd9a`) | 애드온의 자동 axe | spec이 AxeBuilder로 위반 0을 단언한다(`tests/storybook/workshop.spec.ts:24-25`). 결함 아님 | +| capability·dev·visual web server가 로컬 식별값(`af312dee`, `9bddfa52`, `b6936001`) | 그 서버들은 CI 식별값으로 뜨지 않는다 | CI 식별값 빌드는 release e2e(`playwright.config.ts` webServer)와 compact smoke가 본다. 결함 아님 | +| compact smoke 기대값을 env에서 읽음(`b3ce7322`) | 고정 기대값 | 빌드가 같은 env를 읽으므로 빌드가 식별값을 무시하면 CI env에서 여전히 실패한다. 결함 아님 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | > | — | — | src는 영역 01~09 | +| 2 | 구조적 성숙도 | > | — | — | 12·16 | +| 3 | 변경 용이성 | P | M3 / M2 | E1 | 기능을 더해도 접근성 spec은 descriptor로 응답 모양을 정한다(1103/11-01 고쳐진 쪽). 시각 골든은 기능 수와 무관하다(D3). 상세 라우트는 실패 화면으로 검사된다(1103/11-01 남은 것) | +| 4 | 인지 부하 | P | M2 / M2 | E1 | preload 검사는 머리 주석이 한계까지 적는다(`preload-use.ts:3-36`). 빌드 helper 두 벌(0929/11-07) | +| 5 | 위험 가시성 | P | M3 / M2 | E1 | 볼 수 없는 preload를 이름 붙여 실패시킨다. 상세 라우트를 실패 화면으로 검사해도 `a11y.json`은 "passed"다(1103/11-01). 증명 spec이 tracker만 증명한다(11-01) | +| 6 | 실패 성숙도 | O | M3 / M3 | E3(merge-48 1회) | 부트 오류 화면, 구 탭 1회 reload, 429 재시도·불명 결과 저장, 깨진 SW 해제, 이전 캐시 응답이 FE-GATE-008에서 통과했다(SW 둘은 chromium·webkit, firefox quarantine) | +| 7 | 운영 성숙도 | P | M3 / M1 | E1 | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(0929/11-02) | +| 8 | 디버깅 가능성 (깊게) | P | M3 / M2 | E3·E1 | preload 실패는 경로와 이유 이름을 찍는다(`preloadunused:`, `preloadunverifiable::`, 11-R5의 실패 메시지가 주입한 청크 한 줄이었다). `test:system`은 사전 점검 PASS 뒤 bwrap 원인을 12건만 보여 주고 6건은 파일 대기 시간 초과로만 보인다(11-02) | +| 9 | 유지보수 성숙도 | P | M2 / M2 | E1 | 커밋 로그 추적을 끊었다(0929/11-09 고쳐짐). helper 두 벌(0929/11-07). 규모 기준선 재측정은 영역 15 | +| 10 | 테스트 성숙도 (깊게) | P | M3 / M3(검사 동작), M2(검사의 보호) | E3(merge-48 + 배치 변이 10건) | 강점: 세 엔진 같은 방법의 preload 사용 검사가 진짜 안 쓴 preload·표시 누락·허용 밖 청크를 잡는다(11-R1·R2·R4·R5). 고정 층은 400 px 이동 재현에서 RED→GREEN(11-R6·R7). 생성 기능 목록 라우트가 빈 상태로 검사되고 모양 오류는 경고 상자 단언에서 실패한다(11-R8b·R8c). 전이 상태 폴링 제거, provider 묶음 상한 통일. 약점: fixture 실패 방향을 test가 고정하지 않는다(11-01, 11-R3 놓침), 상세 라우트 실패 화면 검사(1103/11-01), provider 묶음은 지원 안 되는 호스트에서 원인 없이 실패(11-02) | +| 11 | 데이터 성숙도 | - | — | — | 이 영역에 데이터 이관 경로가 없다 | +| 12 | 동시성 성숙도 | P | M3 / M2 | E1 | 차단 업그레이드 test의 경쟁을 없앴다(1103/11-05). 05-01 OPFS 새 test는 `waitForTimeout(250)`이 경쟁 경로를 탈지 정한다(`opfs-runtime.spec.ts`, 영역 05 몫, 5절) | +| 13 | 확장성 | P | M3 / M2 | E1 | 접근성 spec·시각 골든이 기능 추가에 따라 손대지 않고 돈다. 규모 tier 재측정은 영역 15 | +| 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`의 호스트 요구가 적혀 있지 않다(11-02) | +| 17 | API / Contract | > | — | — | 07. 접근성 e2e 응답이 operation의 Envelope 선언을 따른다(1103/11-01 고쳐진 쪽) | +| 18 | 배포 성숙도 (깊게) | P | M3 / M3(브라우저), M1(drill) | E3(merge-48 1회) | 구 탭 청크 복구(세 엔진), SW A→B 업데이트(chromium·webkit), CI 식별값 빌드의 compact smoke가 CI env로 통과했다. drill로 provider 전환을 기록할 수 없다(0929/11-02). 실제 러너 미실행(U-1) | +| 19 | 설정 성숙도 | P | M3 / M2 | E1 | 로컬 식별값과 CI 식별값을 web server별로 나눈다(`LOCAL_BUILD_IDENTITY`). resumable spec 포트를 설정에서 읽는다 | +| 20 | 개발자 경험 (깊게) | P | M3 / M2 | E3·E1 | worktree에서 provider test가 돌 수 있게 됐다(코드). 지원 안 되는 호스트에서 사전 점검이 PASS다(11-02) | +| 21 | Guardrail 성숙도 (깊게) | P | M3 / M2 | E3(merge-48, 배치 변이) | merge-48(CI env)에서 FE-GATE-001~012·020 통과. 지난 라운드 CI env에서만 나던 실패 넷(11-06·07·08, 11-10의 firefox 시간 초과)이 이번 1회 실행에 없다. `forbidOnly`·quarantine 만료·mask 규칙 fixture가 기대대로 실패한다(FE-GATE-008 `check:test-evidence:fixture`). strict fixture 검사는 넓어졌지만 그 검사를 지켜 주는 test가 없다(11-01). FE-GATE-013은 이 호스트에서 코드와 무관하게 실패한다(11-02) | +| 22 | 추상화 성숙도 | P | M2 / M2 | E1 | preload 검사 하나가 fixture 하나에 들어갔고 `fulfillBuildScript` 한 함수로 직접 응답 spec과 맞춘다. helper 두 벌(0929/11-07) | +| 23 | 일관성 | P | M2 / M2 | E1 | 모든 browser spec이 같은 strict fixture를 쓴다(`chunk-load-error.spec.ts` 하나만 맨 test). 허용 규칙 셋의 모양이 spec마다 다르다(함수 fixture 둘, 정규식 하나) | +| 24 | 네이밍 / 의미 | P | M2 / M2 | E1 | 실패 이름(`preloadunused`·`preloadunverifiable:`)이 뜻과 맞다. 증명 spec 주석 "These tests prove that check"는 fixture까지 증명하지 않는다(11-01) | +| 25 | 조직 확장성 | > | — | — | 14 | +| 26 | Ownership 성숙도 | P | M2 / M1 | E1 | quarantine에 owner·만료가 있다. `test:system`을 어떤 호스트에서 돌려야 하는지 적힌 곳이 없다(11-02) | +| 27 | 삭제 가능성 | P | M2 / M2 | E1 | 커밋 로그가 없어졌다(0929/11-09). 시각 골든이 기능 링크를 빼서 기능을 지워도 골든이 안 바뀐다 | +| 28 | 회복 가능성 | P | M3 / M3(브라우저), M1(drill) | E3(merge-48 1회) | 깨진 SW 해제(`service-worker-recovery.spec.ts:79`, chromium·webkit)와 구 탭 청크 복구(세 엔진)가 통과했다. provider 전환 뒤 smoke를 drill 증거로 넣을 방법이 없다(0929/11-02) | + +집계(적용 21개): 충족 1(6) · 부분 충족 20 · 미충족 0 · 미검증 0 · 적용 제외 1(11) · 다른 영역 6(1, 2, 14, 15, 17, 25). +지난 라운드와 달라진 곳: 14는 이번에 실행 비용을 재지 않아 >(영역 15)로 넘겼다. 8은 새 11-02 때문에 근거가 바뀌었다(판정은 P 그대로). 21은 P 그대로지만 CI env의 merge 게이트 실패가 사라졌다. + +## 5. 미검증 + +| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| strict fixture의 무시 정규식을 넓히는 변이 | 배치는 결과를 버리는 변이(11-R3)만 돌렸다. 넓히는 쪽을 커밋된 test가 보지 않는다는 것은 코드로만 확인했다 | 정규식을 `/.*/`로 바꾸고 `preload-use.spec.ts` 세 엔진 | +| 1103/11-03·11-04의 완료 기준, `.git` 가림 변이 | provider 묶음이 desktop에서 시작하지 못한다(11-02, 11-R10) | bwrap이 비특권 user namespace를 쓸 수 있는 호스트(지난 라운드의 노트북)에서 `test:system`과 가림 삭제 변이 | +| 노트북과 desktop의 bwrap 동작이 왜 갈리는지 | 같은 `apparmor_restrict_unprivileged_userns=1`인데 노트북은 지난 라운드에 돌았다. 환경은 고치지 않는다(지시) | 두 호스트의 AppArmor 프로필·커널 차이 비교(영역 12·오케스트레이터) | +| 1103/11-02 깨끗한 러너의 글꼴 단계 | U-1 | 글꼴 없는 Ubuntu 24.04 컨테이너나 러너 1대 | +| page.route가 끄는 HTTP cache의 영향 | 근거가 Playwright 문서뿐이다. 지금 HTTP cache 동작을 단언하는 test는 없다 | cache 동작을 보는 test를 만들 때 fixture 밖에서 돌거나 fixture에 적는다 | +| 앱이 첫 그리기 뒤 자라는 12 px이 다른 browser test에 주는 영향 | 1103/11-10은 두 test만 뺐다. 다른 test의 사례는 없다 | 레이아웃 이동(CLS) 측정(영역 15)이나 같은 400 px 재현을 다른 클릭 spec에 | +| 05-01 OPFS 새 test가 경쟁 경로를 실제로 타는지 | `page.waitForTimeout(250)` 뒤에 put을 풀어 준다. purge가 그 안에 대기 지점에 닿지 않으면 경쟁 없이 같은 결과로 통과할 수 있다(추론). 영역 05의 수정 test다 | 영역 05의 수정 되돌림 변이 | +| `opfs-runtime.spec.ts`의 OPFS 미지원 엔진 조용한 통과(`:346`, `:438` `return`) | 지난 라운드부터 있던 모양. merge-48에서는 세 엔진 모두 2.5~4.7초 걸려 실제로 돈 것으로 보인다(추론). capability 증거 검사는 "22 cases x 3 engines, zero skipped"지만 `return`은 skip으로 세지 않는다 | test가 지원 여부를 단언하거나 `test.skip`으로 이름을 남김 | +| CI 러너 위 FE-GATE-008·013 | U-1 | 러너 1대와 PR 1건 | + +## 6. 실행 기록 + +이 영역이 직접 돌린 실행은 없다. 처음 낸 desktop 실행 셋(`11-preload`, `11-allow-files`, `11-a11y`)은 공용 잠금 줄에서 기다리다 19:55에 취소됐다(BRIEF-2). 셋 다 `restored: clean`을 찍기 전이고, checkout을 건드리지 않았다. + +배치 실험(요청 `scratchpad/r4/requests/11.md`, 패치 `scratchpad/r4/requests/11-Rk.diff`, 결과 로그 `scratchpad/r4/results/11/11-Rk.log`). 오케스트레이터가 desktop checkout(`8a44226`)에서 local env로 하나씩 돌렸다. 항목마다 전후로 checkout을 `8a44226`으로 되돌렸고, 10건 모두 `restore=clean`이다. 대조 실행은 merge-48 FE-GATE-008(변이 없는 같은 spec 통과)과 11-R4(probe의 대조)다. + +| ID | 명령(요약) | 변이 | rc · 시간 · load | 결과 | +|---|---|---|---|---| +| 11-R1 | `playwright test tests/e2e/preload-use.spec.ts` 세 엔진 + `11-parent.mjs` | `preload-use.ts:220` 실패 목록을 비움 | 1 · 16 s · 1.67 | 기대대로. `:45` test 세 엔진 실패(Expected `["preloadunused:/assets/async-state-Cxfod8c-.js"]`, Received `[]`), 6건 통과. parent = `_reference-feature-contract-contribution-XD-KpqsD.js` | +| 11-R2 | 같음(parent 없이) | `preload-use.ts:139` 평가 표시 없음 | 1 · 30 s · 1.89 | 기대대로. 9건 모두 실패. 실패마다 쓰인 청크가 `preloadunused:`로 수십 줄 나온다(1번 test는 홈 화면만으로 26줄 더) | +| 11-R3 | `preload-use.spec.ts` + probe 세 엔진 | `strict-browser-test.ts:62` 결과 버림 + probe | 1 · 27 s · 2.75 | 기대대로(놓침). `preload-use.spec.ts` 9건과 P1·P2 통과, P3~P6 12건 실패(콘솔 검사는 변이와 무관). P1이 통과한 것이 11-01의 근거 | +| 11-R4 | 같음 | probe만 | 1 · 31 s · 4.78 | 기대대로. `preload-use.spec.ts` 9건·P2 3건 통과. P1 3건 `preloadunused:/assets/async-state-Cxfod8c-.js`, P3~P6 12건 `console:warning:`/`console:error:` 한 줄로 실패(15 failed). rc=1은 probe가 일부러 실패한 것이다 | +| 11-R5 | 허용 spec 4개 chromium | 각 spec 끝에 허용 밖 안 쓴 preload 주입 | 1 · 17 s · 5.79 | 기대대로. boot(`async-state-…`)·old-tab(`async-state-…`)·csp(`badge-D6w1dKS_.js`) 세 test가 그 한 줄로 실패. SW "removed chunk" test는 `service worker controls: true`로 통과 | +| 11-R6 | `browser-files.spec.ts` firefox | 400 px 재현 | 0 · 7 s · 6.52 | 기대대로. 3 passed(6.0 s) | +| 11-R7 | 같음 | `ee37dd86` 되돌림 + 재현 | 1 · 71 s · 6.16 | 기대대로. 두 test가 `filechooser`·`download` 대기 30 s 시간 초과, `showOpenFilePicker` test 통과 | +| 11-R8b | `create:feature sample-feature --with-create` 뒤 `@a11y /sample` 세 엔진 | 생성 목록 빈 상태에 이름 없는 button(생성기 틀 `scripts/create-feature.ts:1214`) | 1 · 16 s · 2.29 | 기대대로. 생성 명령 성공(파일 33개, 라우트 3개). `@a11y /sample`만 세 엔진 axe `button-name`(`.zz-review-unnamed`, `accessibility.spec.ts:88`)으로 실패. `/sample/items/a11y-1`·`/sample/new` 세 엔진 통과. JSON 결과에 `a11y-data-state` 6곳(상세 라우트 3엔진) | +| 11-R8c | 같음 chromium | 답이 Envelope를 무시(`installed-api-answers.ts:43`) | 1 · 17 s · 2.70 | 기대대로. 생성 명령 성공. `@a11y /sample`이 `accessibility.spec.ts:74` `getByRole('alert')` 기대 0·받은 값 1로 실패. 상세·작성 라우트 통과 | +| 11-R10 | repo 없이 bwrap 옵션별 `/bin/true` | 없음 | 0 · 0 s · 3.26 | `--unshare-net` rc=1(RTM_NEWADDR), 네트워크 없이 rc=1(`setting up uid map: Permission denied`), `systemd-run --user --scope` 아래 rc=1(RTM_NEWADDR). kernel `7.0.0-38-generic`, `apparmor_restrict_unprivileged_userns = 1`, bwrap 0.9.0. 기대("네트워크 없이는 통과")와 한 곳이 달랐다. 그래서 호스트의 bwrap이 user namespace 자체를 못 쓰는 것으로 정정했다 | + +오케스트레이터가 짧다고 짚은 R08b·R08c(16~17 s)는 로그를 끝까지 읽었다. 둘 다 `create:feature`가 성공했고 webServer 빌드 뒤 test가 돌았다(14.7 s). rc=1은 변이가 일으킨 실패다. + +인용한 오케스트레이터 출력(이 영역이 돌린 것 아님): + +| 출력 | 결과 | +|---|---| +| `merge-48/summary.txt`(CI env, 19:20 시작, load 0.42) | FE-GATE-020 rc=0 1,156 s · 001 rc=0 579 s · 002 35 s · 003 53 s · 004 13 s · 005 133 s · 006 14 s · 007 29 s · **008 rc=0 181 s** · 009 54 s · 010 66 s · 011 9 s · 012 13 s · **013 rc=1 84 s** | +| FE-GATE-008 게이트 로그(`FE-GATE-008.m48.txt`, snapshot과 sha256 같음) | e2e 205건: 202 passed, 3 skipped(firefox SW quarantine, `service-worker-recovery.spec.ts:79`, `service-worker-update.spec.ts:219`, `:240`), 1.8 m, 6 workers. capability 66 passed(42.3 s), "Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)". storybook 1 passed. visual 6 passed. "Test evidence: PASS (416 files, 5 baselines …)". 금지 fixture 4종은 기대대로 실패(EXPECTED_FAILURE). 재시도·flaky 표시 없음. "Execution context was destroyed" 0건 | +| FE-GATE-013 게이트 로그(`FE-GATE-013.m48.txt`, snapshot과 sha256 같음) | 사전 점검 PASS, `test:system` 114건 중 18 failed / 96 passed(`ci-artifact-contract.test.ts` 110건 중 18건, 75 s). snapshot `artifacts/tests/system.xml` `failures="18"`. 3.2 (3) 표 | +| `r4/013-rest/summary.txt`(CI env) | FE-GATE-013 나머지 7개 명령 모두 rc=0 | +| `r4/gates/summary.txt`(local env) | `check:architecture`·`check:types`·`lint`·`test:unit`(194파일 2,883건, `runbook-drill.test.ts` 9건 포함)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0. `verify:documentation` rc=1(영역 14) | +| 메인 세션 FE-GATE-013(같은 커밋, 10:31) | 18 failed / 96 passed, 실패 이름이 merge-48과 같다(대조만) | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 11-01 | Low·P2 | 구조적 위험 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 그 결과를 버려도(11-R3, 9건 통과·안 쓴 preload probe 통과) 커밋된 test가 실패하지 않는다. 3번 test는 지연시킬 청크가 없으면 조용히 평범한 방문이 된다 | `tests/support/browser/strict-browser-test.ts:62`, `tests/e2e/preload-use.spec.ts:45-46`, `:105-126` | +| 11-02 | Low·P3 | 확인된 결함 | `test:system` 사전 점검이 provider의 bwrap 호출을 한 번도 시험하지 않아, bwrap이 user namespace를 못 쓰는 desktop(11-R10)에서 PASS 뒤 18건이 샌드박스 회귀처럼 실패한다(6건은 원인 문구도 없음). 영역 12의 12-01(Medium·P1)과 같은 결함, README에서 합침 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:255-256`, `tests/system/ci-runner/ci-artifact-contract.test.ts:1782`, `:1812` | diff --git a/docs/reviews/2026-11-05-maturity-review/12-guardrails-ci.md b/docs/reviews/2026-11-05-maturity-review/12-guardrails-ci.md new file mode 100644 index 00000000..4c2dd454 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/12-guardrails-ci.md @@ -0,0 +1,223 @@ +# 영역 12 — 가드레일·CI + +> 검토일 2026-11-05 · 기준 `8a44226` (`fix/maturity-review-2026-11-03`) · 가이드 `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`. 함께 본 것: `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-*.json`, `CLAUDE.md` 2단계 게이트 목록, `README.md` merge 게이트 절 +> 깊게 본 관점: 5, 19, 20, 21, 23 +> 렌즈: FE-GATE-013의 호스트 전제(비특권 user namespace)가 어디에 적혀 있고 사전 점검이 알아내는가 · 1103/12-* 9건의 완료 기준 · `e40684b` 이후 약해진 검사 · merge stage와 리뷰 게이트 목록의 차이 +> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드 12번 9건 중 7건은 고쳐졌고(12-01은 기능 2개를 더한 상태에서 시각 게이트 통과를 확인했다), 1건은 일부 남았다. 고친 검사들은 스스로 변이를 품은 단위 테스트로 지켜지고, 약해진 검사는 찾지 못했다. 조건은 셋이다. (1) **FE-GATE-013은 bwrap이 user namespace 안에서 네트워크를 만들 수 있는 호스트에서만 통과한다.** 이 desktop(Ubuntu 24.04, AppArmor 제한 켜짐)에서는 항상 실패한다. 사전 점검은 PASS라고 하고, runner 요구 목록 세 곳 어디에도 이 조건이 없다(12-01). (2) 리뷰·머지 확인은 `CLAUDE.md` 목록이 아니라 merge stage 14게이트를 `ci:gate`로 돈다. `CLAUDE.md` 목록은 merge 명령 87개 중 10개만 돌고 7개 게이트를 건드리지 않는다(12-03). (3) `verify:documentation`은 짝 백엔드 checkout이 없거나 pin 커밋에 있는 곳에서 돈다. 옆 checkout의 작업 트리를 읽어서, 이 desktop에서는 문서와 무관하게 실패한다(12-02). + +ID 표기: 이 문서의 `12-NN`은 2026-11-05 라운드 ID다. 2026-11-03 라운드 발견은 `1103/12-NN`, 그 전은 `1101/…`, `0929/…`로 적는다. + +## 0. 결론 + +- **지난 라운드 12번 발견 9건: 고쳐짐 7, 일부 1, 대표로 합쳐진 1.** 1103/12-02(드릴이 merge stage에서 명령을 뽑음), 12-04(금지 fixture를 운영 ESLint 설정으로 검사), 12-06(짝 백엔드 pin과 답 표), 12-07(제품 소유 overlay), 12-08(로그 추적 해제), 12-09(`branchesTrue`)는 코드와 게이트 로그로 확인했다. 12-01(시각 골든에서 설치 기능 부분을 숨김)은 `create:feature`로 기능 2개(새 context 둘, 라우트 4개)를 더한 상태에서 `test:visual` 6건이 골든 변경 없이 통과했다(12-R1). 완료 기준 둘째 절("셸 CSS를 바꾸면 여전히 실패")은 확인하지 못했다. 내 변이(12-R2)가 화면을 바꾸지 않는 변이였다. 12-05는 명령 안 경로와 짝 저장소 링크를 고쳤고, 1절 밖 문서는 남았다. 12-03은 11-01로 합쳐졌다(영역 11). +- **고친 검사가 실제로 잡는지 스스로 시험한다.** 운영 presentation 규칙을 끄면 금지 fixture 3개가 실패한다(`tests/unit/architecture-lint-fixtures.test.ts:30-47`). merge stage에 명령을 더하면 드릴이 그것을 돈다(`tests/unit/feature-scaffold-drill.test.ts:45`). 오케스트레이터 `test:unit` 2,883건 통과(`gates/test_unit.log`). +- **약해진 검사는 찾지 못했다(2.2절).** 초기 JS 파일 상한 25 → 26 → 32는 이유가 커밋 본문과 `docs/operations/performance-evidence.md:169-178`에 있다. 템플릿 자신의 파일 수는 기록 대조(허용 오차 0, `scripts/scale/measure-feature-shape-growth.ts:238-243`)가 따로 잡는다. 새 skip·`eslint-disable`·`@ts-ignore`는 0건이다. +- **FE-GATE-013의 호스트 전제가 기록에도 검사에도 없다(12-01, Medium·P1).** provider sandbox는 `bwrap --unshare-net`을 쓴다. 이 desktop에서는 `kernel.apparmor_restrict_unprivileged_userns = 1`이라 bwrap이 loopback을 못 올린다. 사전 점검은 "System test prerequisites: PASS"를 찍고, 이어서 provider 테스트 18건이 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 실패한다(메인 세션 `8a44226` 실행, 오케스트레이터 merge-48도 같다). 이 조건은 한 호스트에서 본 일회성 기록(원장)과 코드 주석에만 있고, runner 요구로 적힌 곳은 없다. +- **문서 검사가 pin이 아니라 옆 checkout의 작업 트리를 본다(12-02, Low·P2).** 1103/12-05 수정이 만든 결함이다. 이 desktop의 짝 백엔드는 `ef947e5`(9월)라 `verify:documentation`이 rc=1로 실패했다(`gates/verify_documentation.log`). 같은 커밋을 짝이 없는 임시 worktree에서 돌리면 PASS_SCOPED에 "17 reference(s) … not verified"다(`results/00/00-R2-docs-nosibling.log`). pin(`45d2a478`)에는 그 파일들이 있다. +- **`CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 다르다(12-03, Medium·P2).** 지난 라운드는 이 목록을 따르다 11-06·12-09를 놓쳤다(1103 README 10.5절). 목록은 그 뒤에도 바뀌지 않았다. 이번 라운드의 FE-GATE-013 실패도 이 목록으로는 보이지 않는다. +- **이월 항목은 그대로다.** 0929/12-01·12-04·12-05·12-06·12-07, 1101/12-03은 코드가 바뀌지 않아 남음. 0929/12-03도 남음이다. feature 안 `support/` 폴더를 거쳐 presentation이 http adapter 배럴에 닿아도 `check:architecture`와 ESLint가 둘 다 통과했다(12-R3). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 12 | +| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 미추적 `AGENTS.md`만)에서 읽었다. 2026-11-05 19:20~ | +| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 `config/ci/gates.json`에서 생성하는 Gitea Actions workflow. merge job은 `runs-on: ubuntu-latest` | +| 필수 요구와 규모·운영 목표 | 짝 백엔드 템플릿과 함께 빨리 출시한다. CI 시간·실패율 목표는 없다 | +| 읽은 코드·구성 범위 | `git diff e40684b..8a44226`의 영역 파일 31개(+1,168/−187) 전부. 전체: `check-system-test-prerequisites.ts`, `lib/architecture-lint-fixtures.ts`, `lib/feature-scaffold-drill.ts`, `check-backend-contract-drift.ts`, `contracts/product-ci-overlay.ts`, `lib/coverage-summary-metrics.ts`, `lib/build-environment.ts`, `lib/performance-budgets.ts`, `check-bundle.ts`. 부분: `verify-documentation-readiness.ts:160-445`, `generate-ci-workflow.ts`(diff), `contracts/ci-gates.ts:580-660`, `run-and-validate-provider.ts:105-130`·`:250-280`·`:390-420`, `check-architecture.ts:100-220`·`:1040-1090`, `check-registries.ts`(diff), `lib/removal-fixture.ts`(diff), `eslint.config.ts:455-500`·`:676-760`·`:900-945`, `gates.json` stage·job·FE-GATE-013, workflow 머리·merge job, 단위 테스트 7파일, `tests/visual/platform.visual.spec.ts`, `tests/e2e/accessibility.spec.ts:1-85` | +| 읽은 문서(주장) | `CLAUDE.md:23`, `README.md:262-270`·`:322-350`, `docs/README.md:17-52`, `docs/operations/ci-quality-gates.md:1-60`·`:100-140`·`:175-215`·`:335-395`, `docs/security/supply-chain.md:55-80`·`:175-215`, `docs/testing/taxonomy.md:10-30`, `docs/operations/adapter-remediation-ledger.md:495-560`, `docs/operations/performance-evidence.md:112-180`, `docs/manual/reference/create-feature.md:1-30`, 지난 라운드 12번 문서와 README 6·10·12~14절 | +| 게이트 결과 | 오케스트레이터 `desktop:/tmp/claude-gates/r4/gates/`(로컬 env): `check:architecture`·`check:types`·`lint`·`test:unit`(2,883)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory`·`check:ci` rc=0, 모두 `dirty=0`. `verify:documentation` **rc=1**(12-02). `merge-48/`(CI env): FE-GATE-001~012·020 rc=0(020 1,156초, 008 181초), **FE-GATE-013 rc=1**(84초). FE-GATE-013은 snapshot `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-013.txt`에서 "System test prerequisites: PASS" 뒤 114건 중 18건 실패(12-01). 짝 없는 임시 worktree의 `verify:documentation`: PASS_SCOPED, 17개 참조 미확인(`results/00/00-R2-docs-nosibling.log`). 메인 세션의 같은 커밋 실행 `desktop:/tmp/claude-gates/8a44226-ci/`(2026-11-05 10:02~10:31): 13게이트 rc=0, **FE-GATE-013 rc=1** | +| 수행한 테스트·실험 | **실행 환경 = desktop.** 내가 직접 띄운 실험 4개(`12-prereq`, `12-arch`, `12-misc`, `12-visual`)는 잠금 대기 중 취소되어 돌지 않았다(BRIEF-2). 대신 오케스트레이터 배치로 3개를 돌렸다: `12-R1`(기능 2개 상태의 `test:visual`), `12-R2`(같은 상태 + 셸 헤더 padding 변이), `12-R3`(0929/12-03 변이). 셋 다 restore 깨끗함. ssh로 읽기만 한 것: 호스트 `sysctl`·`/etc/os-release`·`/etc/apparmor.d` 목록·bwrap 버전, 짝 백엔드 checkout의 HEAD와 파일 존재, 게이트 로그 | +| 확인하지 못한 범위·이유 | 실제 Gitea runner(Actions 꺼짐, 1101 U-1). user namespace를 허용하는 호스트에서의 `test:system`. 1103/12-01 완료 기준 둘째 절(셸 CSS 회귀가 여전히 실패): 12-R2 변이가 화면을 바꾸지 않아 증거가 되지 못했다(6절) | +| 이전 리뷰와 비교 가능한 범위 | `e40684b..8a44226` 영역 커밋 34개. 지난 실험 결과는 증거로 다시 쓰지 않았다. 지난 라운드 변이 M2·M3·M4는 이번에 다시 돌리지 못했다. M2는 단위 테스트가 같은 변이를 매번 돈다 | + +## 2. 지난 발견 재확인 + +### 2.1 상태 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/12-01 | `create:feature` 하나로 merge 게이트 `test:visual`이 실패(Medium·P1로 조정) | **고쳐짐(보존 조건 하나는 미검증)** | **실행(12-R1):** `create:feature probe-feature`와 `probe-write-feature --with-create --keyed`(새 context 둘, 라우트 4개)를 더한 상태에서 `test:visual` 6 passed, 골든 변경 없음(`results/12/12-R1.log`). 지난 라운드에는 기능 1개로 3건이 실패했다. **코드:** 셸 두 장은 설치 기능 라우트의 링크와 `li`를 `display: none`으로 빼고 찍는다(`tests/visual/platform.visual.spec.ts:33-42`, `:60`, `:73`). 플랫폼 구성 화면은 설치 기능을 세거나 나열하는 절 4개와 계약 집합 다이제스트를 숨긴다(`:43-54`, `:115`). 목록은 `ROUTE_FEATURE_OWNER`에서 뽑으므로 기능 수와 무관하다(`:33-35`). 골든 3장을 다시 찍었다(플랫폼 구성 456,747 → 187,585 B). 깨끗한 템플릿의 통과는 `merge-48/FE-GATE-008` rc=0. **확인 못 한 것:** "셸 CSS를 바꾸면 여전히 실패"는 증거가 없다. 12-R2에서 헤더 위아래 padding을 `0.75rem` → `1rem`으로 바꿨는데 6건이 그대로 통과했다(`results/12/12-R2.log`). 이 변이는 화면을 바꾸지 않는다. 헤더 높이는 grid 행 `4.5rem`이 정하고(`src/presentation/styles/theme/shell.css:38`) 내용은 가운데 정렬이다(`:51`). 변이를 잘못 고른 리뷰어 실수다. 정적으로는 숨김 규칙이 기능 라우트의 `a`·`li`와 플랫폼 화면 절 4개만 고른다(`platform.visual.spec.ts:36-54`). 나머지 셸(헤더, 사이드바 틀, 플랫폼 라우트 `APP_HOME`·`EXAMPLES_PLATFORM` 링크, `src/contracts/routes.ts:21`, `:34`)은 계속 스크린샷 안에 있다(E1). 남은 것: 숨긴 절 4개의 모양은 이제 시각 계약 밖이다. 결정 D3 (a)로 정했고 spec 주석(`:23-32`)에 적혀 있다 | +| 1103/12-02 | 드릴이 merge 명령 88개 중 15개만 돎 | **고쳐짐** | 드릴이 사본의 `gates.json` merge stage를 순서대로 돈다(`scripts/lib/feature-scaffold-drill.ts:58-104`, `scripts/test-feature-scaffold.ts:101-102`). 제외 15개는 이유와 함께 한 목록이다(`feature-scaffold-drill.ts:26-46`). merge 밖으로 옮긴 명령의 제외는 거부한다(`:91-102`). 단위 테스트 6건(`tests/unit/feature-scaffold-drill.test.ts:14-82`)이 `gates/test_unit.log`에서 통과. 문구도 맞췄다(`docs/manual/reference/create-feature.md:3-4`, `scripts/create-feature.ts:1750`). 드릴은 이제 `verify:documentation`(FE-GATE-017, merge 밖)을 돌지 않는다. 대신 사본의 `test:unit`이 문서를 넣은 사본에서 같은 검사를 돈다(`tests/unit/documentation-readiness.test.ts:58-61`, 제외 조건 `scripts/lib/removal-fixture.ts:76-82`). 약화가 아니다 | +| 1103/12-03 (= 11-01) | a11y 게이트가 생성 기능 경로에서 오류 화면을 검사 | **대표 11-01, 영역 11이 판정** | 정적 확인만: spec이 descriptor 모양의 빈 목록으로 답하고(`tests/e2e/accessibility.spec.ts:44-58`) 목록 라우트에서 `alert` 0개를 단언한다(`:72-74`). 단건 조회 라우트는 실패 상태로 검사하고 annotation을 남긴다(`:75-80`) | +| 1103/12-04 | 금지 fixture가 fixture 전용 ESLint 규칙을 시험 | **고쳐짐** | fixture마다 그 계층의 운영 경로로 lint하고(`lintAs`), 거부는 지정한 규칙 id로만 센다(`scripts/lib/architecture-lint-fixtures.ts:39-82`, `:141-171`). fixture 전용 블록은 지워졌다(`eslint.config.ts` diff). 목록에 없는 fixture는 실패한다(`:128-130`). 지난 변이 M2와 같은 것(운영 `src/presentation/**`의 `no-restricted-globals`·`no-restricted-imports` 끔)을 단위 테스트가 매번 돌고 3개 fixture 실패를 단언한다(`tests/unit/architecture-lint-fixtures.test.ts:30-47`). 통과: `gates/test_unit.log`. 실제 게이트 출력: "3 allowed PASS, 9 forbidden rejected by the production rule for their layer"(`gates/check_architecture.log`) | +| 1103/12-05 | 문서 검사가 명령 안 경로·저장소 밖 링크·지운 심볼·1절 밖 문서를 안 봄 | **일부** | 고친 것: backtick 명령과 셸 블록 안 경로 인자(`scripts/verify-documentation-readiness.ts:243-266`), 짝 저장소 경로·링크(`:214-226`, `:305-316`). 테스트 `tests/unit/documentation-readiness.test.ts:150-209` 통과. 원장 N-06~N-08 행은 백틱 명령을 지우고 "V2와 함께 삭제"로 고쳤다(`docs/operations/adapter-remediation-ledger.md:91-93`). `ungated-scripts.json`의 시점 문장도 지웠다. 남은 것: 지운 심볼, 1절 밖 문서. 예: `docs/testing/frontend-platform-testing-strategy.md:769`가 아직 지운 `tests/integration/auth-recovery.test.ts`를 적는다. 고친 부분이 새 결함을 만들었다(12-02) | +| 1103/12-06 | 짝 백엔드 계약 기준이 문서 문장뿐 | **고쳐짐(D6 범위)** | pin 파일(`config/contracts/backend-contract-pin.json`, `45d2a478`)과 백엔드 답 표 사본(`config/contracts/backend-idempotency-answers.json`, 7행, `IDEMPOTENCY_COMPLETION_UNKNOWN` 포함). 단위 테스트가 두 방향으로 대조한다(`tests/unit/backend-contract-pin.test.ts:100-142`, 10건 통과). 표에 `refusedBeforeWrite: true`인 새 409 code를 더하면 기대값은 `NOT_APPLIED`이고 프론트는 `MAYBE_APPLIED`를 낸다(`src/adapters/http/backend-envelope.ts:345-349`). 그래서 그 테스트가 실패한다(코드 추적, E1). 남은 것: 백엔드가 움직인 것을 아는 장치는 게이트 밖 로컬 스크립트뿐이다(`scripts/check-backend-contract-drift.ts`, 이유 `config/ci/ungated-scripts.json:4-7`). 그 스크립트도 커밋된 이력만 본다(`:60`). 노트북 짝 백엔드는 pin에 있고 깨끗하다 | +| 1103/12-07 | 배포 슬롯·제품 게이트가 템플릿 `gates.json` 안에 | **고쳐짐** | 제품 소유 `config/ci/product-gates.json`(템플릿은 비워 둠). 로더가 슬롯을 채운 뒤 템플릿 규칙으로 다시 검사하고(`scripts/contracts/ci-gates.ts:590-597`), 기준선은 템플릿 몫만 센다(`:658`). 제품 게이트는 `PRODUCT-GATE-NNN`만, 별도 job(`scripts/generate-ci-workflow.ts` `renderProductGateJob`). 단위 테스트 11건 통과(`tests/unit/product-ci-overlay.test.ts`): 슬롯 채우기, 이중 채움 거부, 없는 script 거부, 템플릿 ID 거부, 템플릿 부분 workflow 바이트 불변. 남은 것: 생성 YAML은 여전히 템플릿이 추적하는 파일이고 제품 job이 끝에 붙는다. 동기화 때 YAML 충돌은 다시 생성해 푼다. 문서는 "a template sync does not meet it"라고만 적는다(`docs/operations/ci-quality-gates.md:365-368`) | +| 1103/12-08 | `check:scale:pr`이 커밋된 로그를 다시 씀 | **고쳐짐** | `.gitignore:15-17`이 `artifacts/**/*.log`를 무시하고, `529615dc`가 추적을 끊었다. `git ls-files artifacts`의 `.log` 0개. 그래서 어떤 실행도 추적 로그를 바꿀 수 없다. 오케스트레이터 로그의 모든 명령이 `dirty=0`(`gates/summary.txt`) | +| 1103/12-09 | coverage 증거 검사가 `branchesTrue`를 거절 | **고쳐짐** | 키 목록을 한 상수로 두고 두 검사기가 같이 쓴다(`scripts/lib/coverage-summary-metrics.ts`, `scripts/lib/ci-artifact-validator.ts:86-96`, `scripts/lib/risk-coverage.ts:640-656`). `merge-48/FE-GATE-005` rc=0(CI env, 133초) | +| 1101/12-03 | 디자인 규칙이 정해진 파일·형식만 봄 | **남음** | `check-design-system.ts`, `lib/design-system-rules.ts`가 `e40684b` 이후 커밋 0개. 그라디언트, TSX 인라인, `base.css` 재정의, feature 폴더 CSS는 그대로 범위 밖(E1) | +| 1101 FOLLOW-UP | `noUnusedParameters`, `no-deprecated` 없음 | **바뀜(그대로)** | `tsconfig.base.json:14`는 `noUnusedLocals`뿐. 손 목록 2개(`eslint.config.ts:53-68`). 사용처 판정은 영역 09·16 | +| 1101 FOLLOW-UP U-1 | Actions 꺼짐 | **미확인** | Gitea API를 부르지 않았다. README가 이제 "no status is not a pass"와 로컬 실행을 적는다(`README.md:327-330`) | +| 0929/12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 안 봄 | **남음** | 파일 커밋 0개. receiver 이름 정규식(`scripts/check-request-fanout.ts:23`), 같은 줄 `fanout-reviewed:`만 인정(`:108`) | +| 0929/12-03 | feature 안 layer 밖 폴더에 경계 규칙 없음 | **남음** | **변이(12-R3):** `src/features/reference-feature/support/direct-http.ts`(http adapter 배럴에서 `createContractHttpExecutor` import)와 그것을 import하는 `src/features/reference-feature/presentation/r12-probe-leak.ts`를 더했다. `check:architecture` arch-rc=0(그래프가 421 modules로 두 파일을 읽었다, 무변이 419), ESLint eslint-rc=0(`results/12/12-R3.log`). 무변이 대조: `gates/check_architecture.log` rc=0. 해당 규칙(`.dependency-cruiser.json:140` `concrete-adapters-compose-only-in-bootstrap`, `:302` `feature-and-app-roots-do-not-reach-adapters`)의 diff는 주석뿐이다. 그래프 회귀 fixture 29개에 이 경우가 없다 | +| 0929/12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | **남음** | `26ca2fdb`가 `config/ci/contract-baseline.json`(100/104)과 `tests/unit/ci-workflow-generation.test.ts:199-203`(100, 104)을 같이 고쳤다. 절차 문서에 테스트 갱신 단계가 없다(`docs/operations/ci-quality-gates.md:19-27`) | +| 0929/12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | **남음** | `package.json:182` `"dependency-cruiser": "18.1.0"`. 검사기는 자기 그래프뿐(`scripts/check-architecture.ts:103-105`) | +| 0929/12-06 | Vitest 폴더의 `*.spec.ts`를 게이트 안으로 셈 | **남음** | 파일 커밋 0개. `scripts/lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어로 판정). Vitest는 `*.test.*`만 돈다(`vitest.config.ts:45`) | +| 0929/12-07 | 예외 목록에 담당·재검토 시점 없음 | **남음** | 스키마가 `path|script`와 `reason`뿐(`scripts/lib/ungated-tests.ts:20-34`, `scripts/lib/ungated-scripts.ts:17-31`). 이번에 `check:backend-contract-drift` 항목이 늘었다 | + +요약: 1103 12번 9건 중 고쳐짐 7(12-01은 보존 조건 하나 미검증), 일부 1(12-05), 다른 영역 대표 1(12-03 → 11-01). 이월 10건 중 남음 8, 바뀜 1, 미확인 1. 틀리게 고쳐졌다고 본 항목은 없다. 다만 12-05의 수정이 새 결함 12-02를 만들었다. + +### 2.2 `e40684b` 이후 바뀐 검사의 약화 여부 + +| 바뀐 것 | 판정 | 근거 | +|---|---|---| +| 초기 JS 파일 상한 신설 25 → 26 → 32 (`config/performance/budgets.json:5`) | **정당, 기록됨. 약화 아님** | 상한은 `46dfe23f`가 새로 만든 검사다. 26은 두 수정 브랜치 통합으로 생긴 198 B 파일 하나(`1b8cb126` 본문), 32는 기능 하나가 공유 청크 하나를 떨어뜨리는 경우의 여유(`2fef27d5` 본문, 1103 X2 #4)다. 이유와 "넘으면 먼저 청크 그룹을 본다"가 `docs/operations/performance-evidence.md:169-178`에 있다. 템플릿 자신이 파일을 하나라도 늘리면 기록 대조가 실패한다: `config/scale/feature-shape-ceilings.json`의 `initialJavascript.files: 26`을 빌드와 허용 오차 0으로 비교한다(`scripts/scale/measure-feature-shape-growth.ts:238-243`, `tests/unit/feature-shape-growth.test.ts:150-165`, `gates/test_unit.log` 통과). 상한 초과 자체는 `check:bundle`의 자가 fixture(`scripts/check-bundle.ts:86-97`)와 `tests/unit/check-bundle-output.test.ts`(5건 통과)가 지킨다. 합계 바이트 예산 204,800 B는 그대로 | +| 화면 문구 i18n 규칙 예외에 `src/features/platform-examples-feature/presentation/**` 추가(`eslint.config.ts:915-921`) | **범위 동일** | 예제 화면이 `src/presentation/examples`(원래 `screenTextDirectories` 밖)에서 기능 폴더로 옮겨졌다(1103/09-04). 같은 코드에 같은 예외를 유지한다. 이 블록이 빠져도 일반 `no-restricted-syntax`(보안 선택자)는 그 파일에 그대로 걸린다 | +| 아키텍처 금지 fixture 전용 ESLint 블록 삭제 | **강화** | 1103/12-04. 운영 규칙으로 검사한다 | +| 제거 fixture가 문서 없는 사본에서 문서 테스트 2파일을 지움(`scripts/lib/removal-fixture.ts:62-82`, `:152-154`) | **이유 있음, 약화 아님** | 문서를 복사하지 않는 capability 드릴에서만이다. 원본의 `test:unit`은 그 두 파일을 계속 돈다 | +| `check:registries`가 읽지 못한 레지스트리를 참조·기준선 비교에서 뺌(`scripts/check-registries.ts:119-125`, `:408-413`) | **약화 아님** | 읽기 실패는 먼저 `failures`에 들어가 게이트가 실패한다. 같은 원인을 "삭제됨"으로 다시 세지 않을 뿐이다 | +| `check:architecture`가 pnpm 경유 요구를 없애고 ESLint API를 씀 | **약화 아님** | 같은 `eslint.config.ts`를 읽는다(`scripts/check-architecture.ts:202-218`) | +| CI 계약 기준선 owner `frontend-platform` → `DongHyeonka` | **검사 영향 없음** | 문서는 `CI_CONTRACT_BASELINE_OWNER=<팀>`을 예로 든다(`docs/operations/ci-quality-gates.md:24`). 관점 26에만 적는다 | +| 새 `skip`·`fixme`·`eslint-disable`·`@ts-ignore` | **0건** | `git diff e40684b..8a44226 -- src scripts tests eslint.config.ts`의 추가 줄 검색 | + +## 3. 이번 발견 (36.3) + +새 발견 3건: Medium 2 · Low 1 / P1 1 · P2 2 / 확인된 결함 3. High 이상 없음. + +### 3.1 발견 목록 + +| ID | 심각도·우선순위 | 성격 | 관련 관점 | 한 줄 | +|---|---|---|---|---| +| 12-01 | Medium · P1 | 확인된 결함 | 21, 19, 20, 8, 5 | FE-GATE-013의 호스트 전제(bwrap이 user namespace 안에서 네트워크를 만듦)가 runner 요구 목록과 사전 점검 어디에도 없어, 이 desktop에서는 사전 점검 PASS 뒤 `test:system` 18건이 bwrap 원문 오류로 실패한다 | +| 12-02 | Low · P2 | 확인된 결함 | 21, 17, 20, 23, 8 | `verify:documentation`이 짝 백엔드 참조를 pin 커밋이 아니라 옆 checkout의 작업 트리에서 찾아, 같은 커밋이 기계마다 다른 결과를 낸다 | +| 12-03 | Medium · P2 | 확인된 결함 | 21, 5, 26, 23, 10 | `CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 달라, 따르면 merge 명령 87개 중 10개만 돌고 7개 게이트와 `ci:gate`의 증거 검사가 빠진다 | + +### 12-01 FE-GATE-013의 호스트 전제가 runner 요구 목록과 사전 점검 어디에도 없어, 이 desktop에서는 사전 점검 PASS 뒤 `test:system` 18건이 bwrap 원문 오류로 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 19, 20, 8, 5 | +| 근거 | **전제:** provider sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로 provider를 띄운다(`scripts/run-and-validate-provider.ts:254-256`). `test:system`은 merge 게이트 FE-GATE-013의 첫 명령이다(`config/ci/gates.json:2011-2041`, merge stage `:2236-2256`). **사전 점검:** `scripts/check-system-test-prerequisites.ts`는 실행 파일 3개(`:15-19`), cgroup controller 파일(`:21-28`), `systemctl show-environment`(`:30-38`)만 본다. namespace를 만들어 보지 않는다. **실행(메인 세션, 같은 커밋 `8a44226`, desktop, 2026-11-05 10:29):** 게이트 로그 첫 줄이 "System test prerequisites: PASS"다. 이어서 "Tests 18 failed \| 96 passed (114)". 18건 모두 provider 테스트이고 오류는 "sandboxed external provider failed: exit=1, signal=none; sandbox reported: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted"다(`desktop:…/artifacts/quality/gates/FE-GATE-013.txt`, `artifacts/tests/system.xml`에 23회). FE-GATE-013 rc=1(`/tmp/claude-gates/8a44226-ci/summary.txt`). 오케스트레이터 merge-48(CI env)도 같다: snapshot `desktop:/tmp/claude-gates/r4/snap/artifacts/quality/gates/FE-GATE-013.txt`에서 "System test prerequisites: PASS" 뒤 114건 중 18건 실패. **호스트(ssh 읽기):** Ubuntu 24.04.4 LTS, `kernel.apparmor_restrict_unprivileged_userns = 1`, `/etc/apparmor.d/unprivileged_userns` 있음, bwrap 전용 profile 없음, bubblewrap 0.9.0(setuid 아님). **기록:** runner 요구 목록 세 곳이 bwrap·prlimit·systemd·cgroup v2만 적는다(`docs/operations/ci-quality-gates.md:181-185`, `docs/security/supply-chain.md:182-186`, `docs/testing/taxonomy.md:15`). `gates.json`과 workflow에도 호스트 조건 칸이 없다. merge job 14게이트가 같은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:37`, `:55`). README는 merge 게이트 14개를 로컬에서 돌리라고 하면서 008·009(브라우저)와 012(빌드)의 조건만 적는다(`README.md:326-338`). 이 조건을 아는 곳은 둘뿐이다. 하나는 원장의 "Host restriction discovered during this pass" 절이다(`docs/operations/adapter-remediation-ledger.md:531-546`). 한 호스트에서 `bwrap --unshare-net`이 `apparmor_restrict_unprivileged_userns = 1`로 실패했다는 일회성 기록이고, runner 요구로 적지 않았다. 다른 하나는 코드 주석이다(`scripts/run-and-validate-provider.ts:394-405`). 둘 다 runner를 준비하는 사람이 읽는 요구 목록이 아니다. 1103 README 14.5절 9·11회차는 "013은 desktop 환경 문제(사용자 결정 대기)"로 적었다 | +| 발생 조건 | 비특권 user namespace가 제한된 호스트에서 FE-GATE-013을 돌릴 때마다. 이 desktop이 그렇다. Ubuntu는 23.10부터 이 제한을 두었고 24.04에서 기본으로 켰다(외부 사실. 이 리뷰가 확인한 호스트는 desktop 한 대다). user namespace를 막은 컨테이너도 같다(추론) | +| 영향 | merge stage가 이 호스트에서 한 번도 초록이 될 수 없다. provider sandbox의 격리·cgroup·guardian 테스트 18건이 돌지 못한다. 운영자는 PASS 뒤 커널 netlink 문장을 보고 원인을 이력 문서에서 찾아야 한다. 템플릿을 받은 제품도 같은 호스트에서 같은 일을 겪는다 | +| 심각도·우선순위 | Medium · P1 — 사용자 피해는 없다. 적힌 요구를 모두 만족하는 호스트에서 merge 게이트가 항상 실패한다. 1103/11-02(runner에 글꼴 패키지가 없어 FE-GATE-008 실패, Medium·P1)와 같은 기준이다. 고치는 비용이 작다 | +| 통제·증거 | 목표 M3(사전 점검이 호스트 조건을 알아내고 이름을 댄다) / 확인: namespace 조건 M0(원장의 일회성 기록은 요구가 아니라 M1에도 못 미친다), 나머지 runner 조건 M1(문서)·M3(실행 파일·cgroup·bus 점검) · E3(메인 세션과 오케스트레이터 merge-48 게이트 실행, 같은 커밋) + 호스트 읽기 + E1 | +| 확실성과 남은 가정 | 실패 원인, PASS 출력, 문서 누락은 확정. AppArmor가 `unprivileged_userns` profile로 capability를 빼서 loopback 설정이 막힌다는 기전은 외부 사실이다. user namespace를 허용하는 호스트에서 18건이 통과하는지는 이번에 보지 않았다(원장은 그런 호스트에서 107/108이었다고 적는다, `adapter-remediation-ledger.md:545-547`, 주장) | +| 결정의 근거 | 확인한 사실: OPS-23이 bwrap의 원문 줄을 살려 원인을 보이게 했다(`run-and-validate-provider.ts:394-415`). 원장은 제한이 "세션 도중에 켜졌다"고 적고(`adapter-remediation-ledger.md:542-544`), 그 호스트의 기록으로 남겼다. 사전 점검과 요구 목록에 넣은 기록은 없다. 추론: 일시적인 호스트 상태로 보고 계약으로 올리지 않았다. 그러나 같은 desktop에서 이번에도 두 번(10:29, merge-48) 같은 실패가 났으므로 일시적 상태가 아니다 | +| 이해 비용 | runner를 준비하는 사람은 문서의 조건을 다 맞춘 뒤에도 실패를 보고, sysctl과 AppArmor를 스스로 찾아야 한다 | +| 최소 개선 방향 | (1) 사전 점검이 provider와 같은 플래그로 `bwrap --unshare-net … /bin/true`를 한 번 돌린다. 실패하면 sysctl 값과 함께 "unprivileged user namespaces are restricted: allow bwrap with an AppArmor profile or use a host that permits them"처럼 이유와 할 일을 적고 exit 1. (2) runner 요구 목록 세 곳에 이 조건 한 줄. (3) README merge 게이트 절에 013의 호스트 조건 한 줄 | +| 대안 비교 | (a) 현 상태: 비용 0, 매 실행 원인 추적. (b) 위 (1)~(3): 수십 줄, 실패가 사전 점검에서 이름과 함께 난다. (c) FE-GATE-013을 release stage로 옮김: PR마다 sandbox 검사를 잃는다. 보안 검사 약화라 버린다. (d) namespace가 없으면 provider 테스트를 skip: 거짓 초록이라 버린다. (b)가 가장 작다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. sandbox 플래그와 provider 테스트 114건은 그대로 둔다 | +| 비용·부작용 | 스크립트 10~20줄, 문서 3줄. probe 1회는 수 ms | +| 재검토 조건 | provider sandbox가 network namespace 말고 다른 격리로 바뀌면 probe를 바꾼다 | +| 완료 기준 | 이 desktop에서 `node scripts/check-system-test-prerequisites.ts`가 exit 1로 끝나고 user namespace 제한을 이름으로 적는다. 제한이 없는 호스트에서는 PASS. 요구 목록 세 곳에 조건이 있다 | +| 검증 방법 | desktop에서 사전 점검 실행. 허용 호스트(또는 bwrap AppArmor profile을 넣은 뒤)에서 `test:system` | +| 담당·기한·상태 | 미정 · 미정 · 신규. 호스트를 고칠지는 사용자 결정 대기이고, 조건을 적고 알리는 것은 템플릿 몫이다. 1101/13-03(영역 13, provider job의 runner 전제)과 원인이 겹친다. 이 항목은 merge 게이트의 사전 점검과 요구 목록만 센다. 영역 11의 같은 결함(1105/11-02)은 오케스트레이터가 README에서 이 항목으로 합친다 | + +### 12-02 `verify:documentation`이 짝 백엔드 참조를 pin 커밋이 아니라 옆 checkout의 작업 트리에서 찾아, 같은 커밋이 기계마다 다른 결과를 낸다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(1103/12-05 수정 `b4e4f98c`가 만들었다) | +| 관련 관점 | 21, 17, 20, 23, 8 | +| 근거 | **코드:** 짝 저장소 위치는 `cwd`의 부모다(`scripts/verify-documentation-readiness.ts:214-215`). 짝 경로는 그 작업 트리에서 찾는다. checkout이 없으면 `unverifiedLinks`로 넘기고 통과한다(`:312-313`, `:438-445`). checkout이 있는데 파일이 없으면 `missingPaths`로 실패한다(`:314-315`). pin(`config/contracts/backend-contract-pin.json:5`, `45d2a478`)은 읽지 않는다. `../`로 나가는 링크의 첫 폴더가 없으면 짝 저장소 이름이 틀려도 같은 "unverified" 가지로 간다(`:308-313`). **실행:** 오케스트레이터 `gates/verify_documentation.log`(desktop checkout, 로컬 env)가 rc=1이다. 5개 문서가 `../clean-architecture-backend-template/docs/web/http-contract.md`, `…/docs/manual/07-authorization.md`, `…/src/adapter/inbound/web-advanced/README.md`, `…/src/application-fileserver`를 "names paths that do not exist"로 적고 "FAIL_UNVERIFIED (failed: document references)". **원인(ssh 읽기):** desktop의 옆 checkout은 `ef947e5`(2026-09-16)이고 미커밋 변경이 있다. 그 트리에 위 4개 경로가 없다. 같은 커밋을 짝이 없는 임시 worktree에서 돌리면 PASS_SCOPED이고 "17 reference(s) into paired repositories not verified"를 찍는다(오케스트레이터 `results/00/00-R2-docs-nosibling.log`). 노트북 원본 checkout의 짝 백엔드는 pin에 있고, 이 리뷰 worktree는 부모가 `.claude/worktrees`라 짝이 없다. 같은 커밋이 놓인 곳에 따라 FAIL·PASS·PASS(17개 미확인)가 된다. **테스트도 이 의존을 피해 간다:** "Only this document is under test: other documents name paired-backend paths the stub checkout does not have"(`tests/unit/documentation-readiness.test.ts:179-180`). **주장:** `docs/README.md:44-47`은 "그 checkout이 옆에 있을 때만 확인"이라고 적고 어느 커밋인지는 적지 않는다 | +| 발생 조건 | 짝 백엔드를 pin과 다른 커밋으로 옆에 둔 checkout에서 `verify:documentation`(`CLAUDE.md` 목록, FE-GATE-017)을 돌릴 때 | +| 영향 | 사용자가 테스트용으로 정한 desktop에서 리뷰 게이트가 문서와 무관하게 실패한다. 옆 checkout이 pin보다 새로우면 pin에 없는 파일을 적어도 통과한다. 저장소 이름 오타는 "확인 못 함"으로 통과한다. CI는 영향이 없다(짝 checkout이 없어 unverified). merge 때의 문서 검사(`test:unit`의 `documentation-readiness.test.ts:58-61`)는 `/tmp` 사본에서 돌아 영향이 없다 | +| 심각도·우선순위 | Low · P2 — merge 게이트에는 영향이 없다. 리뷰와 개발 루프의 결과를 기계마다 다르게 만들고, 고치는 비용이 작다 | +| 통제·증거 | 목표 M3(pin 커밋의 트리를 확인) / 확인: 옆 checkout이 pin에 있을 때 M3, 다른 커밋일 때 M0(그 트리를 그대로 믿음) · E3(오케스트레이터 게이트 로그) + E1 | +| 확실성과 남은 가정 | 확정. 짝이 pin보다 새로운 경우(거짓 통과)는 실행하지 않았고 코드 추적이다(`:314-316`) | +| 결정의 근거 | 확인한 사실: 1103/12-05는 "옆에 있으면 확인, 없으면 unverified"를 골랐다(1103 12번 문서 5.2절 (b)). pin 파일은 다른 수정 브랜치(`ba2b4f4c`, 1103/12-06)에서 들어왔고 두 수정이 이어지지 않았다. 추론: 두 브랜치를 따로 만든 뒤 합쳤다 | +| 이해 비용 | 실패를 본 사람은 문서를 고치려다 옆 저장소의 커밋이 원인임을 찾아야 한다 | +| 최소 개선 방향 | (1) 옆 checkout에 pin 커밋이 있으면 `git -C <짝> cat-file -e :<경로>`로 pin 트리에서 찾는다. (2) pin 커밋이 없으면 실패 대신 "unverified (짝 HEAD ``, pin ``)"로 적는다. (3) 첫 폴더가 알려진 짝 저장소가 아닌 `../` 링크는 실패로 센다 | +| 대안 비교 | (a) 현 상태. (b) 위 (1)~(3): 수십 줄, 결과가 기계와 무관해진다. (c) 짝 HEAD가 pin과 다르면 전부 unverified: 더 단순하지만 다른 커밋에서는 아무것도 확인하지 못한다. (d) 짝 문서를 이 repo로 복사: 사본 동기화가 하나 더 생긴다. (b)를 권한다 | +| 단순화의 보존 조건 | 짝이 없을 때 PASS + unverified, 명령 안 경로 검사, 1103/12-05 테스트 4건은 그대로 | +| 비용·부작용 | 스크립트 수십 줄, stub 짝 저장소에 커밋 2개를 만드는 단위 테스트 | +| 재검토 조건 | 짝 문서를 패키지나 서브모듈로 가져오게 되면 그 판을 기준으로 바꾼다 | +| 완료 기준 | 짝이 `ef947e5`(pin 없음)인 desktop에서 PASS + unverified. 짝 HEAD가 pin 뒤에 있을 때 결과가 pin 트리와 같다. 저장소 이름 오타 링크는 실패한다 | +| 검증 방법 | 위 세 경우를 stub git 저장소로 만드는 단위 테스트. desktop에서 `verify:documentation` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 12-03 `CLAUDE.md`의 리뷰 게이트 목록이 merge stage와 달라, 따르면 merge 명령 87개 중 10개만 돌고 7개 게이트와 `ci:gate`의 증거 검사가 빠진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(리뷰 절차와 게이트 계약이 다르다) | +| 관련 관점 | 21, 5, 26, 23, 10 | +| 근거 | **목록:** `CLAUDE.md:23`이 명령 11개를 적는다. **계약:** merge stage는 14게이트, 명령 참조 88개(서로 다른 명령 87개, `build`가 011·012에 겹침)다(`config/ci/gates.json:2236-2256`). 목록은 그중 10개를 돈다. 하나도 돌지 않는 게이트가 7개다: FE-GATE-001(lockfile), 008(e2e·capability·storybook·시각), 009(a11y), 011(build·storybook), 012(bundle), 013(security, 12-01), 020(제거·생성 드릴). 003은 25개 중 1개, 010은 21개 중 3개다. 나머지 하나 `verify:documentation`은 merge 밖 FE-GATE-017이다. 이 게이트는 `workflow_dispatch`에 `stage=documentation`일 때만 돈다(`.gitea/workflows/quality-gates.yml:466`). **빠지는 단계:** 명령을 직접 돌리면 `ci:gate`가 하는 로그·증거 산출물 검증(`scripts/run-ci-gate.ts:217`), 음성 fixture 30개의 기대 실패 판정, workflow env(`README.md:340-349`)가 빠진다. 1103/12-09는 증거 검증에서만, 11-07·11-08은 CI env에서만 실패했다. **이력:** 1103 README 10.5절이 이 목록만 따르다 11-06·12-09(둘 다 Medium·P1)를 놓쳤다고 적었다. `CLAUDE.md`는 그 뒤에도 바뀌지 않았다(`git log e40684b..8a44226 -- CLAUDE.md` 0건, 마지막 `412b3d1f`). 이번 라운드는 오케스트레이터가 따로 merge stage를 돌려 메웠다(BRIEF §2). **두 번째 사본:** `README.md:336`도 14개 ID를 손으로 적는다(지금은 맞다) | +| 발생 조건 | 누군가 `CLAUDE.md`의 리뷰 절차를 그대로 따를 때. Actions가 꺼져 있어(`README.md:327-330`) 리뷰 실행이 유일한 게이트 실행일 때 특히 | +| 영향 | "게이트 통과"라고 적힌 리뷰에서 merge 게이트 7개는 아무도 돌리지 않았다. 지금 이 목록으로는 FE-GATE-013의 실패(12-01)가 보이지 않는다. 지난 라운드에는 항상 실패하는 merge 게이트 두 개가 리뷰를 통과했다 | +| 심각도·우선순위 | Medium · P2 — 런타임 피해는 없다. 항상 실패하는 merge 게이트를 리뷰마다 숨길 수 있고 실제로 숨겼다. 고치는 비용은 문서 몇 줄이다 | +| 통제·증거 | 목표 M3(리뷰 절차가 게이트 계약에서 목록을 얻는다) / 확인 M1(손 목록) · E1 + 지난 라운드 기록 + 이번 게이트 결과 대조 | +| 확실성과 남은 가정 | 확정 | +| 결정의 근거 | 확인한 사실: 목록은 2026-09 가이드 커밋 때 적은 것이다. 그 뒤 merge stage에 FE-GATE-020 등 게이트와 명령이 늘었다. 추론: 목록을 계약에서 뽑지 않아 따라가지 못했다 | +| 이해 비용 | 리뷰어는 목록과 `gates.json`을 직접 대조해야 빠진 게이트를 안다 | +| 최소 개선 방향 | (1) `CLAUDE.md` 2단계를 "merge stage `gateIds`를 workflow env로 `ci:gate` 하나씩, 그리고 `verify:documentation`"으로 바꾼다. (2) 더 낫게는 merge stage를 `gates.json`에서 읽어 도는 명령 하나(예: `ci:gate:stage merge`)를 두고 `CLAUDE.md`와 README가 그것을 가리킨다 | +| 대안 비교 | (a) 현 상태. (b) 문서만 고침: 다시 손 목록이 된다. (c) stage 실행 명령: 목록 사본이 0이 되고 계약이 바뀌면 따라간다. (d) `check:ci`가 README·`CLAUDE.md`의 목록을 계약과 대조: 문서 파싱이 늘어난다. (c)를 권한다 | +| 단순화의 보존 조건 | `ci:gate`의 첫 실패에서 멈추는 동작과 게이트별 로그 산출물은 그대로 | +| 비용·부작용 | 스크립트 수십 줄 또는 문서 두 곳. merge stage 전체는 이 desktop에서 게이트 시간 합 2,419초(약 40분, FE-GATE-020 1,156초 포함, `merge-48/summary.txt`) | +| 재검토 조건 | merge stage가 둘 이상의 job으로 나뉘거나, 리뷰가 실제 runner 결과를 읽게 되면 | +| 완료 기준 | `CLAUDE.md`와 README가 merge stage를 손으로 나열하지 않는다. 리뷰 절차를 따르면 merge stage 14게이트가 `ci:gate`로 돈다 | +| 검증 방법 | merge stage에 게이트 하나를 더한 사본에서 절차의 명령이 그것을 도는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 적용 제외 — 이 영역에 도메인 규칙이 없다 | — | — | - | +| 2 | 구조적 성숙도 | 적용 — 경계 강제 장치 | M3 / import 방향 M3(그래프 29 fixture), 운영 ESLint 계층 규칙 M3(1103/12-04), feature 안 layer 밖 폴더 M0 | E3 | P · 0929/12-03 남음(12-R3: 변이가 그래프·ESLint 모두 통과) | +| 3 | 변경 용이성 | 적용 | M3 / P | E3 | P · 기능 2개를 더해도 템플릿 골든을 다시 찍지 않는다(1103/12-01, 12-R1). 배포·제품 게이트는 overlay로 갔다(1103/12-07). 게이트 하나 변경은 여전히 기준선·테스트 상수를 같이 고친다(0929/12-04) | +| 4 | 인지 부하 | 적용 | — | E1 | P · `gates.json` 2,990줄, workflow 488줄. overlay는 5줄 파일이라 제품 쪽 부담은 줄었다 | +| **5** | 위험 가시성 | 적용 | M3 / P | E3 | P · FE-GATE-013 사전 점검이 PASS라고 한다(12-01). 리뷰 목록이 merge 게이트 7개를 빼고 "통과"라고 한다(12-03). 금지 fixture 출력은 이제 운영 규칙을 시험한 것이 맞다 | +| 6 | 실패 성숙도 | 적용 제외 — 런타임 실패 처리가 없는 영역 | — | — | - | +| 7 | 운영 성숙도 | 다른 영역 | — | — | > 영역 13 | +| 8 | 디버깅 가능성 | 적용 | M3 / P | E3 | P · 번들 실패가 넘은 한도와 초과량을 적는다(`check-bundle.ts:120-145`). 아키텍처 fixture 실패가 규칙과 경로를 적는다. bwrap 실패는 원문 netlink 문장뿐이다(12-01). 문서 검사 실패가 원인(옆 checkout 커밋)을 적지 않는다(12-02). fanout 메시지 그대로(0929/12-01) | +| 9 | 유지보수 성숙도 | 적용 | — | E1 | P · 로그 churn은 사라졌다(1103/12-08). 미사용 `dependency-cruiser`(0929/12-05). merge 게이트 목록 손 사본 두 곳(12-03) | +| 10 | 테스트 성숙도 | 적용 | M3 / P | E2 | P · 고친 검사마다 변이를 품은 단위 테스트가 있다(2.1절). 고아 `*.spec.ts`(0929/12-06). 리뷰 절차가 merge 명령 대부분을 돌지 않는다(12-03) | +| 11 | 데이터 성숙도 | 적용 제외 | — | — | - | +| 12 | 동시성 성숙도 | 적용 제외 | — | — | - | +| 13 | 확장성 | 일부 적용 | — | E2 | > 영역 09·15. 이 영역 몫: 초기 파일 상한 32(현재 26), 바이트 여유는 영역 15 | +| 14 | 성능 성숙도 | 적용 | — | 로컬만 | ? · runner가 없다. desktop에서 FE-GATE-020 1,156초(job 상한 45분의 43%, `merge-48`), 001은 이번 실행에서 579초(메인 세션 실행 3초, 원인 미확인) | +| 15 | 보안 성숙도 | 적용(workflow 범위) | M4 / M4 | E1 | O · `permissions: contents: read`, action 33개 모두 40자 SHA, `persist-credentials: false` 9곳, `pull_request_target` 0. 배포 secrets는 deploy 단계에만 렌더한다(`generate-ci-workflow.ts` `isStepScopedSecret`). provider sandbox 검증이 이 호스트에서 돌지 못한다(12-01) | +| 16 | 의존성 성숙도 | 적용 | M3 / P | E2 | P · 짝 백엔드 pin이 기계가 읽는 파일이 됐다(1103/12-06). 문서 검사는 그 pin을 쓰지 않는다(12-02). 미사용 `dependency-cruiser@18.1.0`(0929/12-05) | +| 17 | API / Contract | 적용 | M3 / P | E2 | P · 답 표와 Envelope 표를 두 방향으로 대조한다. 백엔드가 움직인 것은 게이트 밖 로컬 스크립트만 안다(1103/12-06 남은 것) | +| 18 | 배포 성숙도 | 다른 영역 | — | — | > 영역 13. 이 영역 몫: 배포 슬롯이 제품 overlay로 갔다(1103/12-07) | +| **19** | 설정 성숙도 | 적용 | M3 / P | E3 | P · runner 호스트 조건이 계약·문서에 다 적혀 있지 않다(12-01). 제품 CI 설정은 템플릿 파일 밖으로 나왔다(1103/12-07) | +| **20** | 개발자 경험 | 적용 | — | E3 | P · 사용자가 정한 테스트 호스트에서 `verify:documentation`과 FE-GATE-013이 변경과 무관하게 실패한다(12-02, 12-01). 로컬 게이트가 트리를 더럽히지 않는다(`dirty=0`) | +| **21** | Guardrail 성숙도 | 적용 | M3 / 로컬 P, 머지 시점 미확인 | E3 | P(로컬) · ?(머지 시점) · 지난 라운드 X의 원인(02-06 드릴 항상 실패, 11-06·12-09)은 이번 merge-48에서 FE-GATE-001~012·020 통과로 사라졌다. 13게이트가 통과하고 013만 이 호스트에서 실패한다. 남은 틈: 12-01(013은 이 호스트에서 항상 실패), 12-02, 12-03, 0929/12-03·12-06 | +| 22 | 추상화 성숙도 | 적용 | — | E1 | O · overlay는 허용 칸 셋(deploy script, bindings, 제품 게이트)으로 좁고 스키마로 막았다. 드릴 제외 목록은 이유를 값으로 든다 | +| **23** | 일관성 | 적용 | — | E1 | P · merge 게이트 목록이 계약·README·`CLAUDE.md` 세 곳이다(12-03). 문서 검사와 pin 테스트가 짝 백엔드 기준을 다르게 잡는다(12-02). coverage 키 목록은 한 상수가 됐다(1103/12-09) | +| 24 | 네이밍 / 의미 | 적용 | — | E3 | P · "System test prerequisites: PASS"가 sandbox를 띄울 수 없는 호스트에서도 나온다(12-01). "PASS_SCOPED"는 unverified를 같이 적어 정직하다 | +| 25 | 조직 확장성 | 적용(팀 하나라 구조만) | — | E2 | P · 기능 추가(12-R1로 시각 게이트까지 확인)·배포·제품 게이트가 템플릿 파일을 고치지 않는다(1103/12-01·12-07). 생성 YAML은 동기화 때 다시 생성해야 한다 | +| 26 | Ownership | 적용 | M1 / P | E1 | P · 예외 목록에 담당·재검토가 없다(0929/12-07). CI 기준선 owner가 팀이 아니라 개인 이름이다(`config/ci/contract-baseline.json:3`). 리뷰 절차 문서의 담당이 없다(12-03) | +| 27 | 삭제 가능성 | 적용 | M3 / P | E2 | P · 제거 드릴 셋이 문서 테스트 제외를 같은 상수로 쓴다. 1절 밖 문서에 지운 테스트 경로가 남았다(1103/12-05 남은 것) | +| 28 | 회복 가능성 | 적용 제외 — 이 영역에 복구 경로가 없다 | — | — | - | + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 셸 CSS 회귀가 기능 부분을 숨긴 시각 게이트에서 여전히 실패하는가(1103/12-01 완료 기준 둘째 절) | 12-R2 변이(헤더 위아래 padding)가 화면을 바꾸지 않았다. grid 행 높이 고정 + 가운데 정렬이라 렌더가 같다 | 배경색이나 사이드바 너비처럼 보이는 셸 속성 하나를 바꾸고 기능 1개 상태에서 `test:visual` | +| 짝 백엔드가 pin보다 새로울 때의 거짓 통과(12-02) | 그런 checkout이 없다 | stub git 저장소 단위 테스트 | +| user namespace를 허용하는 호스트의 `test:system` | 그런 호스트가 없다 | AppArmor bwrap profile을 넣은 호스트나 다른 runner에서 1회 | +| 실제 Gitea runner와 머지 시점 강제 | Actions 꺼짐(1101 U-1) | runner 1대와 PR 1건 | +| FE-GATE-001이 이번에 579초 걸린 이유 | 영역 밖(lockfile 설치), 로그만 봄 | 영역 13 또는 오케스트레이터 | + +## 6. 실행 기록 + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | load | +|---|---|---|---|---|---|---| +| `12-prereq` | `bash /tmp/claude-gates/r4/mut/12-prereq-cmd.sh`(호스트 probe, 사전 점검, provider 테스트 1건) | 없음 | — | **돌지 않음.** 잠금 대기 중 ssh가 끊기고(255), 이어 실험 실행이 닫혔다(BRIEF-2). restore 대상 없음 | — | — | +| `12-arch` | `bash …/12-arch-cmd.sh`(`check:architecture` 무변이·M2·M4·M5) | 명령 안에서 | — | **돌지 않음** | — | — | +| `12-misc` | `bash …/12-misc-cmd.sh`(문서 검사 probe, pin 변이, `check:scale:pr`, 고아 spec, overlay) | 명령 안에서 | — | **돌지 않음** | — | — | +| `12-visual` | `bash …/12-visual-cmd.sh` | `12-visual-mut.sh` | — | **돌지 않음** | — | — | +| 배치 `12-R1` (20:08:26) | `corepack pnpm -s test:visual` | `12-R1-two-features.sh`(`create:feature probe-feature`, `probe-write-feature --with-create --keyed`, `git add -N .`, 54파일) | visual-rc=0 | **6 passed**(11.3초), 골든 변경 없음. 기대대로 | 배치 | 3.42 | +| 배치 `12-R2` (20:08:40) | 같음 | `12-R2-two-features-shell-css.sh`(12-R1 + `.app-shell__header` padding `0.75rem 1.25rem` → `1rem 1.25rem`) | visual-rc=0 | **6 passed.** 기대(실패)와 다르다. 원인은 변이 쪽이다: 헤더 높이를 grid 행 `4.5rem`이 정하고(`shell.css:38`) 내용이 가운데 정렬이라(`:51`) 위아래 padding을 늘려도 렌더가 같다. 이 실행은 셸 회귀 검출의 증거가 아니다(리뷰어 실수) | 배치 | 2.87 | +| 배치 `12-R3` (20:08:54) | `check:architecture` + ESLint 2파일 | `12-R3-feature-support-leak.diff` | arch-rc=0, eslint-rc=0 | 둘 다 통과. 그래프가 421 modules(무변이 419)로 두 파일을 읽었다. 0929/12-03 남음 확인. 무변이 대조 `gates/check_architecture.log` | 배치 | 2.58 | +| ssh 읽기 | `sysctl …userns…`, `/etc/os-release`, `ls /etc/apparmor.d`, `ls -l /usr/bin/bwrap`, `dpkg -s bubblewrap`, 짝 백엔드 `git log -1`·파일 존재 | 없음 | 0 | 12-01·12-02 근거 | 없음 | 4~7 | + +끊긴 실험 4개는 desktop checkout을 건드리기 전에 끝났다(`/tmp/claude-gates/r4/exp/`에 `12-*.log` 없음). 배치 3개는 오케스트레이터가 돌렸고 각 실행 앞뒤로 checkout을 `8a44226`으로 되돌렸다(`results/12/summary.txt`: 셋 다 `restore=clean`, 마지막 `status=empty head=8a44226`). 배치 rc는 마지막 echo의 것이라 판정은 로그 안의 `visual-rc`·`arch-rc`·`eslint-rc`로 했다. 증거로 쓴 다른 실행: 오케스트레이터 `gates/`(로컬 env), `merge-48/`(CI env)와 그 snapshot, 짝 없는 `verify:documentation`(`results/00/00-R2-docs-nosibling.log`), 메인 세션 `/tmp/claude-gates/8a44226-ci/`(같은 커밋, 2026-11-05 10:02~10:31). 요청서는 `scratchpad/r4/requests/12.md`, 로그는 `scratchpad/r4/results/12/`. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 12-01 | Medium · P1 | 확인된 결함 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없어, 이 desktop에서 사전 점검 PASS 뒤 provider 테스트 18건이 bwrap 원문 오류로 실패한다 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` | +| 12-02 | Low · P2 | 확인된 결함 | `verify:documentation`이 짝 백엔드 참조를 pin이 아니라 옆 checkout 작업 트리에서 찾아 기계마다 결과가 다르다(desktop rc=1) | `scripts/verify-documentation-readiness.ts:214-215`, `:308-316` | +| 12-03 | Medium · P2 | 확인된 결함 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 달라 merge 명령 87개 중 10개만 돌고 7개 게이트와 증거 검사가 빠진다 | `CLAUDE.md:23`, `config/ci/gates.json:2236-2256` | diff --git a/docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md b/docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md new file mode 100644 index 00000000..f1dc59ae --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/13-build-release-supply-chain.md @@ -0,0 +1,218 @@ +# 영역 13 — 빌드·릴리스·설정·공급망 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `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/contracts/{ci-gates,product-ci-overlay}.ts`(배포 슬롯 부분), `scripts/generate-ci-workflow.ts`(배포 슬롯·제품 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`(배포 job), `.gitea/workflows/quality-gates.yml`(env, `immutable_build`~`production_gate`), `src/contracts/{env,deployment-admission}.ts` +> 깊게 본 관점: 15, 16, 18, 19, 21 +> 렌즈: 1103/11-08 수정(`b693600`)이 release 빌드 검사를 약하게 했는가 · 1103/13-01~05 수정 결과 · FE-GATE-013의 test:system 뒤 명령 +> 영역 판정(35.8): **조건부 사용 가능.** "빌드 → 공개 대상 승인 → 손으로 배포"는 그대로 써도 된다. 지난 라운드 P1 결함 1103/13-01은 고쳐졌다. 템플릿 자신의 nginx 예시를 실제 TLS로 띄워 확인했다(배치 13-R02). 같은 run에서 로컬 프로필로 다시 빌드한 release는 이제 FE-GATE-019가 FAIL한다. HTTP/1.1만 되거나 압축하지 않는 호스트도 FAIL한다. 예시 그대로의 호스트는 PASS한다. **배포 슬롯을 채워 CD로 쓰기 전에 두 가지를 알아야 한다.** release 단계 job(`immutable_build`)은 gate 로그를 올리지 않는다. 그래서 FE-GATE-015·027이 왜 실패했는지와 13-03 수정이 만든 advisory 경고가 실제 workflow에서 사라진다(13-01). 제품 merge 검사(`PRODUCT-GATE-*`)는 실패해도 같은 run의 release·배포를 막지 않는다(13-02). 운영 의존성 high advisory 2건은 결정 대기로 남았다(1103/13-03). provider 없이는 슬롯까지 가지 못하는 1101/13-03도 남았다. desktop에서는 provider sandbox가 아예 뜨지 않는다(merge-48 FE-GATE-013). + +ID 표기: 이 문서의 `13-NN`은 2026-11-05 라운드 ID다(라운드 밖에서는 `1105/13-NN`). 지난 라운드는 `1103/13-NN`, 그 전은 `1101/…`, `0929/…`다. + +## 0. 결론 + +- **11-08 수정(`b693600`)은 release 빌드 검사를 약하게 하지 않았다.** 검사 함수 `ciBuildEnvironmentFailures`는 그대로다(`scripts/lib/build-environment.ts:9-41`). workflow env(CI=true)에서 커밋 ID·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`가 없거나 틀리면 음성 실행 14개가 모두 실패했다. 빌드 자체, `build:release-candidate`, `verify:reproducible-build`, `ci:gate FE-GATE-015·013`이 포함된다(13-R01). "로컬" 표시(`CI !== "true"`)를 release job env나 생성 workflow에 넣으면 `check:ci`가 실패했다(13-R03·R04). 수정을 되돌리면 CI=true의 fixture 빌드가 `missing … VITE_COMMIT_SHA`로 멈췄다(13-R05). 수정된 상태는 CI=true merge 게이트에서 통과한다(merge-48 FE-GATE-005·008·020). +- **1103/13-01·13-02·13-04·13-05는 고쳐졌다(E3).** 실제 nginx 1.27.5에 예시 설정을 그대로 올렸다. 결과는 다음과 같다. 후보는 `PASS (live)`(55개 항목). 같은 run 로컬 재빌드는 `runtimeConfig build-fields` FAIL(`API_BASE_URL`, `APP_ENV`, `AUTH_MODE`, `TELEMETRY_*`). 비상 스위치만 바꾸면 PASS. `http2 on;`을 빼면 `alpn` FAIL(`http/1.1`). `gzip on;`을 빼면 `content-encoding` FAIL(13-R02). 고친 규칙을 하나씩 끄면 단위 테스트가 6개 모두 잡았다(13-R07~R12). +- **1103/13-03은 일부다.** dev advisory는 사라졌고 FE-GATE-027이 판정한다. 2026-11-05 20:09 기준 결과는 `POLICY_VIOLATION`이다. 운영 high 2건(`react-router@7.18.1` GHSA-qwww, `zod@4.4.3` GHSA-mrhx), 개발 moderate 2건이 나왔다(13-R01). 운영 2건은 결정 대기다. +- **새 발견 13-01(Medium·P1): `immutable_build`가 gate 로그를 올리지 않는다.** `ci:gate`는 명령 출력을 로그 파일에만 쓴다. 콘솔에는 한 줄만 남는다. 13-R01에서 FE-GATE-027 콘솔은 2줄이었다(`FE-GATE-027 release-admission: PASS`). advisory 경고 4줄은 로그 파일에만 있었다. FE-GATE-015가 실패할 때도 콘솔은 `FAIL` 한 줄이었다. 이유는 로그 파일에만 있었다. `immutable_build`는 그 파일을 올리지 않는다(`.gitea/workflows/quality-gates.yml:122-207`). +- **새 발견 13-02(Medium·P2): 제품 merge 검사가 release·배포를 막지 않는다.** `product_merge_gate` job에는 `needs` 관계가 없다(`scripts/generate-ci-workflow.ts:129-157`). job 그래프는 계약이 고정한다(`scripts/contracts/ci-gates.ts:926-933`). 그래서 제품이 그 연결을 더할 방법도 없다. +- **FE-GATE-013의 test:system 뒤 명령 7개는 CI env에서 모두 통과했다**(오케스트레이터 `013-rest`). FE-GATE-013 자체는 merge-48에서 rc=1이다. 원인은 `tests/system`의 provider sandbox다(`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`). desktop의 `kernel.apparmor_restrict_unprivileged_userns = 1` 때문이다. 이 영역 코드의 결함은 아니다. 다만 1101/13-03의 호스트 전제를 사용자의 배포 기계가 지금 만족하지 않는다는 사실을 보여 준다. +- **지난 이월 항목 중 0929/13-07·13-08·13-09는 고쳐졌다.** 0929/13-02·13-03·13-04·13-05·13-06·13-10, 1101/13-03, R-2는 남았다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 | +| 커밋·작업 상태·확인 시점 | `8a44226`. 노트북 worktree `happy-easley-233d07`(HEAD = 기준, 추적 파일 변경 없음)에서 읽기만 했다. 실행은 오케스트레이터가 desktop checkout(`8a44226`)에서 배치로 돌렸다. 매 항목 앞뒤로 기준 커밋으로 되돌렸고 12개 모두 `restore=clean`이다. 2026-11-05 19:20~20:40 | +| 목적과 지원 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker(기본 `null`). 사용자 목표: 짝 백엔드 템플릿과 빨리 출시하고 desktop 서버로 배포한다 | +| 필수 요구와 규모·운영 목표 | 수치 목표는 초기 JS 204,800 gzip B와 파일 32개(`config/performance/budgets.json:4-5`). 서빙 전제는 h2와 압축(`config/hosting/cache-policy.json:3-5`, `:29`) | +| 읽은 코드·구성 범위 | 머리의 경로 전체. 그 밖에 `vitest.config.ts:17-23`, `playwright.{visual,capabilities,dev}.config.ts`의 webServer env, `scripts/check-supply-chain-provider-fixtures.ts:55-90`. 주장 자료: `README.md:330-352`, `docs/operations/{ci-quality-gates,release-cache-rollback}.md`, `docs/architecture/static-delivery.md:30-62`, 커밋 본문 `b693600`, `cd7e784`, `4bce8bf3`, `2e12d2f0`, `4c4248aa`, `26ca2fdb`, `eeb6f92f`, `a144b575`, `1497e64c`, `7af8e366`, `e440ece9` | +| 수행한 테스트·실험 | 배치 13-R01~R12(요청 `scratchpad/r4/requests/13.md`, 결과 `scratchpad/r4/results/13/`). R01: CI env 음성 실행 14개와 FE-GATE-027 콘솔 확인. R02: 실제 nginx·실제 TLS로 live probe 6회. R03·R04: `check:ci` 변이 2개. R05·R06: 11-08 수정 되돌림 변이 2개. R07~R12: 이 영역 수정 규칙 변이 6개. 대조군은 오케스트레이터 게이트 로그다. 6절 | +| 확인하지 못한 범위·이유 | 실제 Gitea runner(콘솔·작업 디렉터리 정리·`needs` 처리), 채운 배포 슬롯, provider 실행, 실제 운영 호스트(인증서·CDN), advisory 도달 가능성. 5절 | +| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md`의 새 발견 5건과 그 문서가 남음·일부로 둔 이월 11건. README §12의 13-행, §10.3에서 13-02에 합친 15-05 뒷부분, §13의 11-08(이 영역 경로의 수정)도 본다. `git log e40684b..8a44226 -- <경로>` 19커밋. 지난 실험 결과는 증거로 쓰지 않았다 | + +### 1.1 오케스트레이터 게이트 결과 중 이 영역에 해당하는 것 (`8a44226`) + +| 게이트 | 결과 | 이 영역에 주는 의미 | +|---|---|---| +| `test:unit`(local env, `gates/test_unit.log`) | rc=0, 194파일 2,883건 | 통과한 파일: `hosting-probe` 37, `ci-workflow-generation` 426, `product-ci-overlay` 11, `env-registry-coverage` 4, `dependency-advisories` 5, `local-build-environment` 3, `build-environment` 4, `pnpm-install-policy` 2, `service-worker-build-output` 7, `deployment-admission` 25. 배치 변이 R05~R12의 대조군이다 | +| `check:ci`(local) | rc=0 | R03·R04의 대조군 | +| FE-GATE-005·008·020(CI=true, merge-48) | rc=0(133초·181초·1,156초) | 테스트가 띄우는 로컬 빌드가 CI=true에서 통과한다. 008 안의 결과: e2e 202, capability 66, storybook 1, visual 6 | +| FE-GATE-010(CI=true) | rc=0 | `check:ci` 포함 | +| FE-GATE-011·013(CI=true) | 로그 첫 줄 `derived SOURCE_DATE_EPOCH=1793840484 from HEAD` | merge-48은 `SOURCE_DATE_EPOCH`를 주지 않았다. `ci:gate`가 HEAD 시각으로 채웠다(2.3절 (a)) | +| FE-GATE-012(CI=true) | rc=0, `initial JS 202973 / 204800 gzip bytes, 26 / 32 files` | 여유 1,827 B | +| FE-GATE-013(CI=true) | **rc=1**, test:system 114건 중 18건 실패 | 실패 원인은 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`(provider sandbox, `tests/system/ci-runner/ci-artifact-contract.test.ts`)다. desktop은 `kernel.apparmor_restrict_unprivileged_userns = 1`이다. 영역 11·12 몫이다. 이 영역에서는 1101/13-03 근거로만 쓴다 | +| FE-GATE-013의 test:system 뒤 명령(CI env, `013-rest/`) | 7개 모두 rc=0 | `verify:reproducible-build`: `PASS (fca93d18…)`. `build:release-candidate`: `Supply chain: LOCAL PASS (562 dependencies); promotion=FAIL_UNVERIFIED`, secret scan PASS(1,613파일), 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 검출 | + +## 2. 지난 발견 재확인 + +### 2.1 2026-11-03 라운드(이 영역) 발견과 이 영역 경로의 수정 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/13-01 | FE-GATE-019가 run 이름만 대조하고 `config.json` 내용과 슬롯의 후보 사용을 보지 않는다 | **고쳐짐** | **코드.** probe가 받은 `/config.json`을 후보 `dist/config.json`과 비교한다. 비상 스위치 두 개 밖의 필드가 다르거나 읽을 수 없으면 FAIL이다(`scripts/lib/hosting-probe.ts:216-232`). 규칙은 `scripts/lib/runtime-config-switches.ts:11-27`에 있고 `check-release-admission.ts:112`도 같은 함수를 쓴다. 받은 entry script를 후보의 것과 비교한다(`hosting-probe.ts:208-215`). 후보는 `--release-root`에서 읽는다(`scripts/verify-hosting-headers.ts:107-116`). 슬롯에 deploy script가 있으면 세 가지가 있어야 한다: `promoted-release` download, extract, `CANDIDATE_ARCHIVE_SHA256`(`scripts/contracts/ci-gates.ts:1268-1299`). 제품 overlay는 이 단계를 템플릿이 채운다(`scripts/contracts/product-ci-overlay.ts:116-146`). **완료 기준 확인(13-R02).** 지난 라운드 E-2c를 실제 nginx로 재현했다. 같은 run 이름(`gitea-77-1`)의 로컬 프로필 재빌드는 후보와 `config.json` 하나만 달랐다. 그 재빌드를 올린 호스트는 FAIL했다(`runtimeConfig build-fields` 관측 `["API_BASE_URL","APP_ENV","AUTH_MODE","TELEMETRY_ENABLED","TELEMETRY_ENDPOINT"]`, rc=1). 후보는 PASS, 비상 스위치(`CAPABILITY_OVERRIDES.REALTIME`)만 바꾸면 PASS였다. **변이.** 비교를 끄면(13-R07) "fails a host whose config.json is not the candidate's"와 "…unreadable" 2건이 실패한다. 슬롯 입력 규칙을 끄면(13-R10) "rejects a slot that deploys without the promoted candidate"와 "…extracts the candidate without its digest" 2건이 실패한다. 남은 한계는 커밋 본문이 적은 대로다. deploy script가 받은 파일을 실제로 올리는지는 계약이 못 본다. 결과는 FE-GATE-019가 본다 | +| 1103/13-02 | HTTP/2·압축 전제가 호스팅 계약·probe에 없고 nginx 예시가 둘 다 켜지 않는다 | **고쳐짐** | **코드.** `transport.alpnProtocols: ["h2"]`, `hashedAsset.contentEncodings`(`config/hosting/cache-policy.json:3-5`, `:29`). probe가 TLS handshake에서 고른 프로토콜을 본다(`hosting-probe.ts:64-81`, `:233-251`). entry script의 `Content-Encoding`도 본다(`verify-hosting-headers.ts:163-175`). nginx 예시에 `http2 on;`, `gzip on;`, `gzip_types`가 있다(`docs/operations/release-cache-rollback.md:123-137`). **완료 기준 확인(13-R02).** 예시 그대로(포트·인증서 경로만 바꿈) 띄웠다. 결과: curl `/` HTTP/2, entry `content-encoding: gzip`, probe `alpn="h2"`, PASS. `http2 on;`만 빼면 `transport alpn` FAIL(관측 `http/1.1`). `gzip on;`만 빼면 `hashedAsset content-encoding` FAIL(관측 없음). **변이.** ALPN 판정을 끄면(13-R08) "fails a host that does not negotiate a declared protocol"이 실패한다. 압축 판정을 끄면(13-R09) "fails a hashed asset served without a declared content encoding"이 실패한다. **동작 변화.** HTTP/1.1 호스트는 이제 FAIL이고 문서에 적혀 있다(`release-cache-rollback.md:95-104`, `docs/architecture/static-delivery.md:57-62`). 선언을 HTTP/1.1로 바꿀 때 초기 청크를 묶었는지 보는 검사는 없다(M1, 4절 14번) | +| 15-05 뒷부분(→ 1103/13-02에 합침) | HTTP/2 서빙 전제를 확인하는 장치가 없다 | **고쳐짐** | 위 13-02와 같다. 앞부분(초기 파일 수 상한)은 영역 15 몫이다. 상한은 26 → 32로 올랐고(`config/performance/budgets.json:5`, `2fef27d5`) 그 근거로 이 전제를 든다 | +| 1103/13-03 | 취약점 판정이 운영 승격 provider에만 있고, lockfile이 자체 정책을 어기는데 merge·release에서 모른다 | **일부** | **고쳐진 것.** dev 의존성을 갱신했다(`package.json:171-192`, `eeb6f92f`). 기준선을 다시 승인했다(`config/security/dependency-baseline.approval.json:3-6`). FE-GATE-027이 `scan:dependency-advisories`를 돈다(`config/ci/gates.json:2205-2210`). 판정은 승격과 같은 `validateVulnerabilityReport`다(`scripts/lib/dependency-advisories.ts:152-176`). 항상 exit 0이다(`scripts/scan-dependency-advisories.ts:15-18`). `renovate.json`이 생겼다. 13-R01 실측: `POLICY_VIOLATION`, 운영 high 2건(GHSA-qwww-vcr4-c8h2 `react-router@7.18.1`, GHSA-mrhx-c7xc-m3w5 `zod@4.4.3`), 개발 moderate 2건(GHSA-3g3m-2fjr-6pw4 `glob@13.0.6`, GHSA-g3hv-75wg-m249 `minimatch@10.2.5`). 운영·개발 구분은 맞게 나왔다. 지난 라운드 44건에서 4건으로 줄었다. **남은 것.** (1) 운영 high 2건 그대로다(`package.json:160-161`, `pnpm-lock.yaml:2376`, `:2816`). 결정 대기로 적혀 있다(owner와 다른 reviewer 필요, zod 4.6.x는 약 +7 KB로 예산 초과, 재확인 2026-12-04, `docs/operations/ci-quality-gates.md:499-508`). (2) 신호가 실제 workflow에서 보이지 않는다. 원인은 새 13-01이다. 완료 기준 "release 단계 산출물에 advisory 수가 남는다"를 채우지 못한다. (3) renovate는 runner가 없어 동작하지 않는다(`renovate.json:4`). (4) merge 단계 신호는 없다. 비차단으로 고른 설계라 받아들인다 | +| 1103/13-04 | FE-REG-ENV 런타임 행의 `required`·`defaultValue`가 스키마와 다르다 | **고쳐짐** | 커버리지 테스트가 두 가지를 더 본다: 스키마가 읽지 않는 행, 행 값과 스키마의 대조(`tests/unit/env-registry-coverage.test.ts:44-64`). 5개 행을 맞췄다(`src/contracts/env.ts:62-69`). 변이(13-R12)로 `AUTH_MODE` 행 기본값을 지난 값 `"external"`로 되돌리면 실패한다. 메시지: `AUTH_MODE: row {"required":true,"defaultValue":"external"}, schema {"required":true,"defaultValue":null}` | +| 1103/13-05 | 슬롯 `secrets.*`가 job 전체 env로 렌더링된다 | **고쳐짐** | 배포 job의 `secrets.*`는 job env에서 빠지고(`scripts/generate-ci-workflow.ts:193`) deploy 단계 `env:`에만 들어간다(`:331-345`, 판정 `:376-378`). 변이(13-R11)로 판정을 끄면 "accepts a deployment job the slot allows"가 `expected ' env:\n CANDIDATE_ARCHIVE_SHA…' not to contain 'secrets.'`로 실패한다. 제품 overlay 경로는 같은 렌더러를 쓴다. 다만 `product-ci-overlay.test.ts`는 이 변이에서 통과했다. 그 경로의 secret 위치는 따로 단언하지 않는다 | +| 1103/11-08(영역 11 발견, 수정이 이 영역 경로) | CI=true가 테스트 안의 로컬 빌드까지 release 빌드로 검사한다 | **고쳐짐, 검사 약화 없음** | 아래 2.3절 | + +### 2.2 지난 영역 문서가 남음·일부로 둔 이월 항목 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1101/13-03 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고 provider 없는 배포 경로가 없다 | **남음** | provider job은 `runs-on: ubuntu-latest`다(`.gitea/workflows/quality-gates.yml:212`, `:258`). 배포 슬롯은 `promotion` 뒤에만 돈다(`scripts/contracts/ci-gates.ts:933`). provider 없이 배포하는 절은 없다(`docs/operations`·`README.md` grep). 새 사실: 사용자의 배포 대상 desktop에서 provider sandbox 시험이 뜨지 않는다. merge-48 FE-GATE-013의 test:system 18건이 `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 실패했다(`apparmor_restrict_unprivileged_userns = 1`). 이 기계에 runner를 붙이면 provider job도 같은 이유로 막힐 것으로 본다(추정, runner 미실행) | +| 0929/13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:18`의 `loadEnv`는 미선언 변수를 거절할 때만 쓴다. asset base는 `:174`에서 `process.env`로 읽는다. `generate-runtime-config.ts:59`, `:70-74`, `generate-build-manifest.ts:36-39`, `vite.service-worker.config.ts:58-59`도 `process.env`다. `.env.example:14`는 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다 | +| 0929/13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **남음**(Low, fail-closed) | route chunk를 `entry.name === runtime.moduleId`로 찾고 없으면 빌드가 멈춘다(`scripts/generate-build-manifest.ts:64-72`) | +| 0929/13-04(= R-3) | CSP가 여러 벌이고 내용 검사가 없다 | **남음** | 같은 CSP 문자열이 6곳에 있다: `config/hosting/security-headers.json:4`, `response-headers.fixture.json:7`, `:17`, `:27`, `:42`, nginx 예시 `release-cache-rollback.md:115`. `scripts/check-browser-security.ts`에는 CSP 내용 검사가 없다(grep 0건). live probe는 받은 CSP를 `security-headers.json`과 비교한다(`verify-hosting-headers.ts:176-186`). 13-R02 P1이 PASS했으므로 지금 nginx 예시 사본은 정책과 같다. 이 비교는 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`). 실제로는 react-dom 청크에 이름으로 묶여 실린다(`vite.config.ts:226-238`) | +| 0929/13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자가 있다 | **일부(남음)** | live probe가 루트가 아닌 URL을 거절한다(`scripts/lib/hosting-probe.ts:411-418`) | +| 0929/13-07(= R-5) | 청크 설정이 폐기 예정 `build.rollupOptions`에 있다 | **고쳐짐** | `vite.config.ts:192`, `vite.service-worker.config.ts:79`가 `rolldownOptions`를 쓴다(`e440ece9`). `rollupOptions`는 리뷰 문서·CHANGELOG 밖에서 0건이다 | +| 0929/13-08 | pnpm 설치 정책을 지키는 검사가 없다 | **고쳐짐** | `tests/unit/pnpm-install-policy.test.ts:15-36`(`1497e64c`)가 세 가지를 본다. `engineStrict`·`saveExact`가 `true`인지, `minimumReleaseAge`가 1,440분 이상인지, 예외가 정확한 버전만인지다. 통과(E2). 변이는 돌리지 않았다 | +| 0929/13-09 | README 변수 표에 staging·production의 `VITE_BUILD_ID` 필수 조건이 없다 | **고쳐짐** | `README.md:46`(`7af8e366`) | +| 0929/13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | `README.md:393-398`의 "unmodified checkout" 문구가 그대로다 | +| R-2 | 빌드 입력 기본값을 한 곳에서 정한다 | **남음** | 기본값이 네 곳에 흩어져 있다: `generate-runtime-config.ts:73`(`\|\|`)·`:74`(`??`), `generate-build-manifest.ts:36-38`(`??`), `vite.service-worker.config.ts:58-59`(`??`), `src/contracts/env.ts:173-174`(`\|\|`) | + +지난 라운드 판정이 틀렸다고 본 항목은 없다. + +### 2.3 1103/11-08 수정(`b693600`, 안내 `cd7e784`)의 약화 확인 + +| 확인 | 판정 | 근거 | +|---|---|---| +| 검사 자체가 바뀌었는가 | 아니다 | `b693600`은 `scripts/lib/build-environment.ts`에 26줄을 더했을 뿐이다. `ciBuildEnvironmentFailures`(`:9-41`)와 `ciCheckoutIdentityFailures`(`:90-111`)는 그대로다. 단위 테스트가 "CI job 자체 release 빌드는 계속 검사된다"를 따로 단언한다(`tests/unit/local-build-environment.test.ts:37-41`) | +| (a) CI=true에서 커밋 ID·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`가 없거나 틀린 release 빌드는 여전히 실패하는가 | **실패한다(E3, 13-R01)** | 같은 env의 대조군 빌드는 rc=0이었다. 음성 실행은 모두 rc=1이었다. **(1) 커밋 ID 없이 `build:release-candidate`:** 빌드 7단계에서 멈췄다(`missing required CI build environment: VITE_COMMIT_SHA`, `generate-build-manifest.ts:25`). **(2) 빌드 7단계에 값 하나씩 틀리게:** `VITE_COMMIT_SHA=local`, `SOURCE_DATE_EPOCH` 없음, `SOURCE_DATE_EPOCH=2026-11-05`, `CI_RUNNER_IMAGE` 없음·빈 값·`local/runner:latest`. 각각 "must be a full 40- or 64-character …", "missing … SOURCE_DATE_EPOCH", "must be non-negative epoch seconds", "missing … CI_RUNNER_IMAGE"(2회), "must end with an immutable @sha256 image digest"로 실패했다. **(3) 커밋 ID 없이 `verify:reproducible-build`:** "missing … VITE_COMMIT_SHA". **(4) `ci:gate FE-GATE-015`:** 커밋 ID 없음, epoch 형식 오류, 다른 epoch(`946684800`), 빈 이미지, 다른 커밋(40자리 0)이 각각 실패했다. 메시지는 순서대로 "missing …", "does not match … / must be non-negative", "does not match the checked-out commit timestamp", "missing … CI_RUNNER_IMAGE", "does not identify the checked-out commit"였다. **(5) `ci:gate FE-GATE-013`:** 커밋 ID 없이 실패했다. 예외 하나: `ci:gate`는 비어 있는 `SOURCE_DATE_EPOCH`를 HEAD 시각으로 채운다(`run-ci-gate.ts:82-85`). merge-48 로그 첫 줄 `derived SOURCE_DATE_EPOCH=1793840484 from HEAD`가 그 경우다. 이 동작은 `b693600` 전부터 있었다. 틀린 값은 채우지 않고 실패한다 | +| (b) "로컬" 표시를 release 경로에서 실수나 의도로 켤 수 있는가 | **release job에서는 켤 수 없다(E3, 13-R03·R04)** | "로컬" 표시는 `CI !== "true"`다(`build-environment.ts:12`). **함수로 켜는 길:** `localBuildEnvironment`·`LOCAL_BUILD_IDENTITY`를 쓰는 곳은 다섯 곳뿐이다: `tests/e2e/support/fixture-builds.ts:65`, `tests/e2e/support/service-worker-builds.ts:179`, `playwright.{visual,capabilities,dev}.config.ts`. FE-GATE-013·015 명령은 이 함수를 부르지 않는다. **env로 켜는 길:** `immutable_build` env에 `CI` 바인딩을 더했더니 `check:ci`가 `job environment binding drift: immutable_build`로 실패했다(R03). 생성 workflow의 `immutable_build`에 `CI: "false"`를 손으로 넣었더니 `generated workflow drift at byte 5473, line 134`로 실패했다(R04). 대조군 `check:ci`는 rc=0이다. `check:ci`는 FE-GATE-010에 있고, release job은 merge job 뒤에만 돈다(`ci-gates.ts:927-929`). 제품이 `CI`를 바인딩할 수 있는 곳은 배포 job 하나다(`product-ci-overlay.ts:28-37`). 그 job은 후보가 만들어지고 승격된 뒤에 돈다. 재빌드를 올리면 FE-GATE-019의 `config.json` 비교가 잡는다(13-R02 P2). 그래서 발견으로 세지 않는다 | +| (c) 테스트 쪽 로컬 빌드는 CI=true에서 통과하고, 수정이 그 이유인가 | **그렇다(E3, 13-R05·R06)** | 수정된 상태: merge-48(CI=true)에서 FE-GATE-005·008·020이 rc=0이다. 008의 visual 6건과 capability 66건은 `LOCAL_BUILD_IDENTITY` webServer로 돈다. 되돌린 상태: spawn 지점 둘을 `process.env`로 되돌리고 CI env로 돌렸다(R05). `service-worker-build-output`이 `scripts/build-frontend.ts failed for sw-profile-active` / `missing required CI build environment: VITE_COMMIT_SHA`로 멈췄다(7건 미실행). vitest가 `VITE_COMMIT_SHA`만 지우고 `CI`는 남기기 때문이다(`vitest.config.ts:22-23`). `localBuildEnvironment`가 `CI`를 남기게 바꾸면 "is not checked as a CI build …"가 CI 식별값 누락 5건을 보이며 실패한다(R06) | +| 테스트가 실제 경로를 덜 보게 됐는가 | 아니다 | 수정 전에도 fixture 빌드와 시각 골든 빌드는 release 빌드 검사를 통과하는 경로가 아니었다. CI=true에서는 멈췄다. 지금 그 검사를 시험하는 테스트는 `build-environment.test.ts:22-55`와 `local-build-environment.test.ts:37-41`이고, 위 (a)의 실행이 실제 경로를 보였다 | + +남는 작은 위험이 하나 있다. spawn 지점을 다시 `process.env`로 되돌리면 그것을 잡는 것은 CI=true로 도는 merge 게이트뿐이다. 개발자가 CI env 없이 돌리면 통과한다. README가 workflow env로 돌리라고 적었다(`README.md:340-352`). 발견으로 세지 않는다. + +## 3. 이번 발견 (36.3) + +새 발견은 2건이다. Medium 2. P1 1, P2 1. 확인된 결함 1, 구조적 위험 1. High 이상은 없다. + +### 13-01 `immutable_build`가 FE-GATE-015·027의 gate 로그와 기록을 올리지 않아, release 단계의 실패 이유와 advisory 경고가 실제 workflow에서 사라진다 + +| 필드 | 내용 | +|---|---| +| ID·제목 | 13-01(라운드 밖: `1105/13-01`) — 위 제목 | +| 성격 | 확인된 결함. 지난 라운드 전부터 있던 구성이다. 보고된 적은 없다. 1103/13-03 수정이 이 구성 위에 신호를 두면서 영향이 커졌다 | +| 관련 관점 | 8, 5, 7, 16, 18 | +| 근거 | **로그 경로.** `ci:gate`는 각 명령의 stdout·stderr를 모아(`scripts/run-ci-gate.ts:148-150`) 로그 파일 `artifacts/quality/gates/.txt`에만 쓴다(`:209-213`). 콘솔에는 한 줄만 쓴다: `FE-GATE-NNN name: PASS (…)` 또는 `FAIL`(`:243-249`). **실측(13-R01, CI env).** FE-GATE-027 콘솔은 2줄이었다: `$ node … run-ci-gate.ts FE-GATE-027`, `FE-GATE-027 release-admission: PASS (release-coherence)`. 같은 실행의 로그 파일에는 줄이 더 있었다: `Dependency advisories: POLICY_VIOLATION (production: … high 2 …)`(8행), `WARNING: the vulnerability policy (block at high) would refuse this lockfile at production promotion:`(11행), 해당 advisory 2줄(12·13행). FE-GATE-015를 커밋 ID 없이 돌렸을 때도 같았다. 콘솔은 `FE-GATE-015 release-coherence: FAIL` 한 줄이었다. 이유 `missing required CI build environment: VITE_COMMIT_SHA`는 로그 파일에만 있었다. **올리는 곳.** `merge_gate`·`release_gate`는 `artifacts/`를 `if: always()`로 올린다(`.gitea/workflows/quality-gates.yml:75-80`, `:114-119`). `immutable_build`의 단계는 checkout → setup-node → install → `ci:gate FE-GATE-015` → `ci:gate FE-GATE-027` → archive → 후보 upload다(`:122-207`). 계약도 이 단계 목록을 고정한다(`scripts/contracts/ci-gates.ts:947`). archive 멤버에 `artifacts/quality/gates/*`와 `artifacts/security/dependency-advisories.json`은 없다(`:150-200`). **주장과 차이.** 커밋 `26ca2fdb` 본문은 "gate 로그가 이미 release 단계 산출물이다"라고 적었다. 문서는 결과가 "gate log와 `artifacts/security/dependency-advisories.json`에 남는다"고 적는다(`docs/operations/ci-quality-gates.md:479-487`). 둘 다 업로드되지 않는다 | +| 발생 조건 | release 단계를 돌 때마다 생긴다(tag push 또는 dispatch `stage=release` 이상). advisory 경고는 항상 사라진다. 실패 이유는 FE-GATE-015(후보 빌드·로컬 증거)나 FE-GATE-027(공개 대상 승인)이 실패할 때 사라진다 | +| 영향 | 운영자는 "FE-GATE-027 release-admission: FAIL"만 본다. 거절 이유(`release admission refused: …`, `scripts/check-release-admission.ts:39-42`)는 보이지 않는다. 원인을 알려면 같은 커밋을 손으로 다시 돌려야 한다. advisory 경고는 아무도 보지 못한다. 1103/13-03(P1)을 고치려던 신호가 실제 workflow에서는 효과가 없다. provider를 붙인 프로젝트는 지난 라운드처럼 첫 승격에서야 안다 | +| 심각도·우선순위 | Medium · P1. 주요 진단 정보가 빠진 경우다(35.2의 Medium 예). 사용자 피해는 없다. P1로 둔 이유는 둘이다. 지난 라운드 P1(1103/13-03)의 수정이 이것 때문에 실제로 작동하지 않는다. 사용자 로드맵의 CD 경로(release → 승격 → 배포 슬롯)에서 첫 실패를 진단할 수 없다. 고치는 비용은 단계 하나다 | +| 통제·증거 | 로그 생성 M2 / release job 로그 보존 M0 · E3(13-R01: 같은 `ci:gate`의 콘솔과 로그 파일 비교) + E1(workflow 단계 목록) | +| 확실성과 남은 가정 | Gitea act_runner는 job 콘솔만 남기고 작업 디렉터리를 job 뒤에 지운다고 본다. 일반 동작이고 실제 runner에서 확인하지는 않았다. 작업 디렉터리를 남기는 runner 구성이면 파일이 남을 수 있다. 그래도 다음 job이 덮어쓴다 | +| 결정의 근거 | 확인한 사실: 다른 gate job은 모두 `artifacts/` upload 단계가 있다. `immutable_build`만 없다. 기록된 의도: `immutable_build`는 "정확한 후보 파일 집합"만 내보낸다(`:149` 단계 이름 `Archive and validate the exact candidate file set`). 리뷰어 추론: 후보 archive를 정확한 집합으로 두려는 의도와 gate 로그를 따로 올리는 일은 충돌하지 않는다. 이름이 다른 upload라면 후보 집합은 그대로다 | +| 이해 비용 | release 단계 실패를 조사하는 사람은 "로그는 `artifacts/quality/gates/`에 있다"는 문서를 보고 찾는다. 그 job의 산출물에는 없다 | +| 최소 개선 방향 | `immutable_build`에 `if: always()` upload 단계를 더한다. 대상은 `artifacts/quality/gates/FE-GATE-015.txt`, `FE-GATE-027.txt`, `artifacts/release/deployment-admission.json`, `artifacts/security/dependency-advisories.json`이다. 계약의 단계 목록(`ci-gates.ts:947`)과 전송 ID를 함께 고친다. 예: `immutable-gate-evidence`. 후보 archive 멤버는 바꾸지 않는다. 덧붙여 advisory `POLICY_VIOLATION` 한 줄을 `ci:gate` 콘솔에도 내보낸다 | +| 대안 비교 | (a) 현상 유지 — 13-03 신호가 계속 보이지 않는다. (b) upload 단계만 더한다 — 가장 작다. 사람이 산출물을 열어야 본다. (c) `ci:gate`가 실패한 명령의 마지막 N줄을 콘솔에도 쓴다 — 모든 job의 진단이 나아진다. 대신 로그 크기 상한과 secret 노출(`run-ci-gate.ts`는 provider 출력도 다룬다)을 다시 따져야 한다. (d) (b)에 advisory 한 줄을 콘솔에 더한다. 리뷰어 추천은 (d) | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. 후보 archive 멤버 집합과 `verify-ci-candidate-archive.ts` 검사는 그대로 둔다 | +| 비용·부작용 | workflow 단계 하나, 계약 단계 목록 한 줄, `ci-workflow-generation` 테스트 갱신, 계약 기준선 재기록 | +| 재검토 조건 | `ci:gate`가 콘솔 요약을 쓰게 바뀌거나, release job이 후보 archive와 같은 upload에 증거를 싣게 되면 다시 본다 | +| 완료 기준 | release 단계 run의 산출물에 FE-GATE-015·027 로그와 advisory 기록이 있다. FE-GATE-027이 실패한 run에서 그 산출물로 거절 이유를 읽을 수 있다 | +| 검증 방법 | `ci-workflow-generation.test.ts`에 "`immutable_build`는 gate 로그를 always upload한다"를 더한다. 실제 runner에서 `stage=release`를 1회 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음(신규) | + +### 13-02 제품 merge 검사(`PRODUCT-GATE-*`)가 실패해도 같은 run의 release·승격·배포가 진행되고, 제품이 그것을 막을 방법이 계약에 없다 + +| 필드 | 내용 | +|---|---| +| ID·제목 | 13-02(`1105/13-02`) — 위 제목 | +| 성격 | 구조적 위험. job 그래프는 코드로 확인했다. 실제 피해는 제품이 넣는 검사에 달려 있다 | +| 관련 관점 | 18, 21, 26, 3, 24 | +| 근거 | 제품 overlay의 `mergeGates`는 `product_merge_gate` job으로 렌더링된다. 이 job에는 `needs`가 없다. 다른 job도 이 job을 기다리지 않는다(`scripts/generate-ci-workflow.ts:129-157`). job 그래프는 계약이 고정한다. `release_gate`는 `merge_gate`만 기다린다. `immutable_build`는 `release_gate`만, `deployment`는 `immutable_build`·`promotion`만 기다린다(`scripts/contracts/ci-gates.ts:926-933`). 생성 workflow도 같다(`.gitea/workflows/quality-gates.yml:85`, `:124`, `:375`). 문서는 "Make that job a required check of the branch where it has to block a merge"라고만 적는다(`docs/operations/ci-quality-gates.md:377-378`). 브랜치 필수 검사는 PR merge를 막는다. dispatch run의 release·배포는 막지 않는다. 문서가 드는 예가 짝 백엔드 계약 검사다(`:371-372`). 커밋 `4c4248aa` 본문도 "제품 gate는 … readiness 공식 밖이다"라고 적는다 | +| 발생 조건 | 세 조건이 겹칠 때 생긴다. 제품이 `mergeGates`와 `deployment`를 둘 다 채운다. 제품 검사가 실패한다. 그 커밋으로 `workflow_dispatch stage=production`을 돌린다(tag push라면 release까지 간다). 템플릿 자신은 `mergeGates: []`라 해당하지 않는다(`config/ci/product-gates.json`) | +| 영향 | 제품 검사가 지키려던 것(예: 짝 백엔드 계약 일치)이 깨진 release가 운영 호스트에 올라간다. FE-GATE-019는 호스팅만 본다. 그래서 PASS한다. 사용자는 API 응답 해석 오류를 볼 수 있다(검사 종류에 따라 다르다). 템플릿 merge 게이트가 실패하면 release가 멈춘다. 제품 검사는 그렇지 않다. 이 비대칭 때문에 제품 개발자가 같은 보호를 기대하기 쉽다 | +| 심각도·우선순위 | Medium · P2. 지원 구성(제품 overlay)에서 배포 차단이 빠진다. 다만 제품이 두 칸을 채우고 빨간 run을 직접 dispatch해야 생긴다. 템플릿 자체에는 피해가 없다. 고치는 비용은 작다 | +| 통제·증거 | 템플릿 merge 게이트 → release 차단 M4(job 그래프) / 제품 merge 게이트 → release 차단 M0 · E1 | +| 확실성과 남은 가정 | Gitea가 `needs`를 GitHub Actions처럼 처리한다고 본다(실제 runner 미확인). 이 항목은 영역 12(1103/12-07 수정 `4c4248aa`)와 겹칠 수 있다. 같은 결함이면 오케스트레이터가 한 항목으로 합친다 | +| 결정의 근거 | 확인한 사실: overlay는 템플릿 gate ID·readiness를 건드리지 못하도록 따로 둔 job이다(`product-ci-overlay.ts:16-21`). 기록된 의도: 제품 gate를 계약 기준선과 readiness 밖에 둬 템플릿 동기화 충돌을 없앤다. 리뷰어 추론: readiness 밖에 두는 것과 release job이 그 결과를 기다리는 것은 별개다. `needs` 한 줄은 계약 기준선(gate 수·명령 수)을 바꾸지 않는다 | +| 이해 비용 | 제품 개발자는 "merge 검사"라는 이름을 보고 release도 막힌다고 가정한다. 막히지 않는다는 사실은 job 그래프를 읽어야 안다 | +| 최소 개선 방향 | `mergeGates`가 비어 있지 않으면 `release_gate`(또는 `immutable_build`)의 `needs`에 `product_merge_gate`를 더해 렌더링한다. overlay가 있을 때만 계약 그래프 검사(`ci-gates.ts:926-933`)가 그 연결 하나를 허용한다. 문서에 "제품 merge 검사가 실패하면 release 단계는 돌지 않는다"를 적는다 | +| 대안 비교 | (a) 현상 유지하고 문서에 "release를 막지 않는다"고 적는다 — 가장 싸다. 그래도 그래프가 고정이라 제품이 스스로 막을 방법이 없다. (b) `needs` 연결을 더한다 — 템플릿 게이트와 같은 보호다. 제품 gate가 불안정하면 release도 멈춘다. (c) overlay의 gate마다 `blocksRelease: true\|false`를 둔다 — 선택권을 주지만 칸이 하나 는다. 리뷰어 추천은 (b)다. 불안정한 검사가 생기면 (c)로 간다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다. `mergeGates`가 비어 있을 때 생성 workflow 바이트는 지금과 같아야 한다 | +| 비용·부작용 | 생성기 분기 하나, 계약 그래프 검사의 예외 하나, `product-ci-overlay.test.ts` 케이스 하나 | +| 재검토 조건 | 제품 gate를 readiness 공식에 넣는 방식으로 바꾸면 그쪽에서 다시 본다 | +| 완료 기준 | overlay에 gate 하나를 넣고 생성하면 release 쪽 job이 `product_merge_gate`를 기다린다. overlay를 비우면 workflow 바이트가 지금과 같다 | +| 검증 방법 | `product-ci-overlay.test.ts`에 "mergeGates가 있으면 release_gate가 product_merge_gate를 기다린다"를 더한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음(신규) | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이 영역이 깊게 본 관점이다. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | > 영역 09·12 | — | — | > — 빌드 단계 주석이 실제 순서와 맞다(`build-frontend.ts:10-39`) | +| 2 | 구조적 성숙도 | > 영역 12 | — | — | > | +| 3 | 변경 용이성 | 적용 | 목표 M2 / 확인 M2 | E1·E2 | P — 제품이 템플릿 파일을 고치지 않고 배포 job을 채운다(`product-ci-overlay.ts`). 제품 검사로 release를 막을 수는 없다(13-02) | +| 4 | 인지 부하 | 적용 | M1 | E1 | P — FE-GATE-019가 보는 것(이름·config·entry·ALPN·압축·Content-Type)이 문서 한 절에 모였다(`release-cache-rollback.md:82-104`). release job 실패 원인을 어디서 보는지는 알기 어렵다(13-01) | +| 5 | 위험 가시성 | 적용 | M3 / 일부 M0 | E3 | P — 빈 슬롯은 `UNVERIFIED`가 되고 advisory `POLICY_VIOLATION` 판정이 생겼다. 그 판정이 실제 workflow 콘솔과 산출물에 없다(13-01, 13-R01) | +| 6 | 실패 성숙도 | 적용 | M3 | E3 | O — 빌드 단계가 실패하면 즉시 멈추고 승인은 fail-closed다. CI 식별값 누락·형식 오류 14가지가 모두 실패한다(13-R01) | +| 7 | 운영 성숙도 | 적용(일부) | M1 | E1·E3 | P — 비상 스위치 절차와 probe가 같은 규칙을 쓰고, 스위치만 바꾼 호스트는 PASS한다(13-R02 P3). provider 없는 배포 경로가 없고 desktop에서 provider sandbox가 뜨지 않는다(1101/13-03). release 실패를 진단할 수 없다(13-01) | +| **8** | 디버깅 가능성 | 적용 | M2 / release job M0 | E3 | P — probe 실패는 표면·헤더·기대·관측으로 남는다(13-R02 출력). release job은 그 로그를 올리지 않는다(13-01). TLS·전송 실패는 `error.name`(`"Error"`, `"TypeError"`)만 남아 원인 코드가 없다(`hosting-probe.ts:165`, `:239`) | +| 9 | 유지보수 성숙도 | 적용 | M2 | E1 | P — `rolldownOptions` 이전이 끝났다(0929/13-07). CSP 6벌(0929/13-04)과 기본값 4곳(R-2)이 남았다 | +| 10 | 테스트 성숙도 | 적용 | M3 | E3 | P — 이 영역 수정의 규칙 6개를 하나씩 끄면 모두 단위 테스트가 실패한다(13-R07~R12). 11-08 수정 되돌림도 잡는다(R05·R06, R05는 CI env에서만). 실제 TLS·nginx를 쓰는 자동 테스트는 없다(13-R02는 일회성 실험이다). 제품 overlay 경로의 secret 위치는 따로 단언하지 않는다 | +| 11 | 데이터 성숙도 | > 저장소 영역 | — | — | > | +| 12 | 동시성 성숙도 | > 탭·저장소 영역 | — | — | > | +| 13 | 확장성 | > 영역 11·15 | — | — | > | +| 14 | 성능 성숙도 | 적용 | 예산 M3 / 서빙 전제 M3 | E3 | P(지난 P) — h2와 압축을 probe가 실제 nginx에서 확인한다(13-R02). 초기 JS는 202,973 / 204,800 B, 26 / 32파일(FE-GATE-012)이다. 선언을 HTTP/1.1로 바꿀 때 청크를 묶었는지는 문서로만 지킨다(M1). 파일 상한 32는 영역 15 | +| **15** | 보안 성숙도 | 적용 | M3 / 일부 M0 | E3 | P — 승인받지 않은 `config.json`을 내주면 FE-GATE-019가 FAIL한다(13-R02 P2). 슬롯 secret은 deploy 단계에만 간다(13-R11). 운영 high advisory 2건은 결정 대기다(1103/13-03) | +| **16** | 의존성 성숙도 | 적용 | 판정 M3(승격) / 신호 M2 / 갱신 M1 | E3 | P — advisory가 44건에서 4건으로 줄었다(13-R01). release 단계에서 advisory를 판정하고 pnpm 정책을 테스트한다(0929/13-08). 남은 것: 운영 2건, runner 안에 갇힌 신호(13-01), 동작하지 않는 renovate, SBOM `scheduler` 분류(0929/13-05) | +| 17 | API / Contract 성숙도 | 적용(설정 계약) | M3 | E3 | O — FE-REG-ENV 행과 스키마를 양방향으로 대조한다(1103/13-04, 13-R12) | +| **18** | 배포 성숙도 | 적용 | M3 / 일부 M0 | E3 | P(지난 P) — 슬롯은 후보만 받고, probe는 실제 호스트에서 후보 내용과 전송 전제를 본다(13-R02). 남은 것: 제품 검사가 배포를 막지 않는다(13-02), release 실패를 진단할 수 없다(13-01), provider 없이 슬롯에 갈 수 없다(1101/13-03), 하위 경로 배포는 PASS할 수 없다(0929/13-06) | +| **19** | 설정 성숙도 | 적용 | M3 | E3 | P — 호스트 `config.json`과 레지스트리 값을 대조한다. `.env*` 입력 갈림(0929/13-02)과 기본값 갈림(R-2)은 남았다 | +| 20 | 개발자 경험 | 적용 | M1 | E3 | P — nginx 예시를 그대로 쓰면 FE-GATE-019를 통과한다(13-R02 P1, 55개 항목). README가 workflow env로 merge 게이트를 돌리는 법을 적는다(`README.md:340-352`) | +| **21** | Guardrail 성숙도 | 적용 | M3·M4 | E3 | P — release job env와 workflow 바이트를 merge 게이트가 막는다(13-R03·R04). 제품 gate에서 release로 가는 연결은 없다(13-02) | +| 22 | 추상화 성숙도 | > 영역 09·12 | — | — | > | +| 23 | 일관성 | 적용 | M1 | E1 | P — 승인과 probe가 같은 비상 스위치 규칙을 쓴다. 빌드 변수 출처(0929/13-02)와 기본값(R-2) 갈림이 남았다 | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 | E1 | P — `product_merge_gate`와 "merge 검사"라는 이름이 release 보호까지 뜻하는 것처럼 읽힌다(13-02) | +| 25 | 조직 확장성 | - 1인 관리 전제 | — | — | - | +| **26** | Ownership 성숙도 | 적용 | M1 | E1 | P — advisory 2건의 결정 조건과 재확인 날짜가 적혀 있다(`ci-quality-gates.md:499-508`). 그 결정을 내릴 reviewer(owner와 다른 사람)가 1인 운영에는 없다. 선택 기능 결함 분류(0929/13-10)는 남았다 | +| 27 | 삭제 가능성 | > 영역 14 | — | — | > | +| 28 | 회복 가능성 | 적용 | M2 | E3 | P — 비상 스위치만 바꾼 호스트는 probe를 통과한다(13-R02 P3). 슬롯 배포 뒤 FE-GATE-019가 실패해도 자동으로 되돌리지 않는다(문서상 프로젝트 몫) | + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 실제 Gitea runner: `immutable_build` 콘솔과 작업 디렉터리 정리, `needs` 처리, 채운 슬롯 | runner 없음 | `stage=release`·`production` dispatch 1회 | +| desktop에 runner를 붙였을 때 provider job이 같은 sandbox 오류로 막히는가 | runner 미실행. 같은 오류는 test:system에서만 봤다 | host-mode runner에서 provider job 1회 | +| 실제 운영 호스트(공인 인증서, CDN·프록시 뒤)에서 ALPN·압축 판정 | 실험은 LAN IP와 일회용 CA로 했다 | 운영 호스트로 FE-GATE-019 1회 | +| `zod`·`react-router` advisory가 이 앱에서 실제로 닿는가 | 코드 경로를 끝까지 따라가지 않았다(지난 라운드와 같은 추정) | advisory 조건과 사용 지점 대조 | +| `.env*` 입력 갈림(0929/13-02) 재현 | 정적 확인만 | `.env.production.local`에 `VITE_BUILD_ID`만 두고 빌드 | +| `pnpm-install-policy` 변이 검출(0929/13-08) | 요청하지 않았다(작은 정적 테스트) | `pnpm-workspace.yaml`에서 `saveExact`를 지우고 테스트 | + +## 6. 실행 기록 + +이 영역이 직접 실행한 것은 없다. 배치는 오케스트레이터가 desktop checkout에서 돌렸다. 매 항목 앞뒤로 `8a44226`으로 되돌렸고 12개 모두 `restore=clean`이다. 마지막 상태는 `status=empty branch=fix/maturity-review-2026-11-03 head=8a44226`이었다. 잠금 대기는 배치라 따로 없다. + +| 이름 | 명령 · env | 변이 | rc | 결과 | 부하 | +|---|---|---|---|---|---| +| (취소) 13-ciid, 13-probe-live, 13-mut, 13-localtests | `exp.sh …` | 스크립트 안 | — / 93 | 1차는 잠금 대기 중 취소됐다(19:48). 2차는 `CLOSED`였다. 잠금을 잡지 못해 checkout을 건드리지 않았다 | 3~7 | +| 13-R01 | `bash /tmp/claude-gates/r4/mut/13-ciid-run.sh` · CIENV | - | 0(스크립트), 14초 | 대조군 빌드 rc=0. FE-GATE-027 콘솔 2줄, 로그에 `POLICY_VIOLATION`과 경고 4줄. 음성 실행 14개 모두 rc=1이고 이유가 기대와 같다(2.3절 (a)) | 2.46 | +| 13-R02 | `bash /tmp/claude-gates/r4/mut/13-probe-run.sh` · local | - | 0(스크립트), 12초 | nginx 1.27.5(docker `nginx:1.27-alpine`), TLS `IP:192.168.0.107`. 후보 빌드 rc=0, production ADMITTED. P1 PASS(55개), P2 FAIL `runtimeConfig build-fields`, P3 PASS, P4 FAIL `transport alpn`(`http/1.1`), P5 FAIL `hashedAsset content-encoding`, P6 PASS. 컨테이너는 지웠다 | 3.49 | +| 13-R03 | `corepack pnpm -s check:ci` · local | `13-b1-ci-binding-immutable-build.diff` | 1, 2초 | `root: job environment binding drift: immutable_build`(빈 값이라 `value: Too small`도 함께 나왔다). 대조군 `gates/check_ci.log` rc=0 | 3.11 | +| 13-R04 | 같음 · local | `13-b2-hand-edit-workflow.diff` | 1, 1초 | `CI contract failed: generated workflow drift at byte 5473, line 134` | 2.94 | +| 13-R05 | `node scripts/run-vitest.ts run tests/unit/service-worker-build-output.test.ts` · CIENV | `13-c1-spawn-sites-process-env.diff` | 1, 3초 | `scripts/build-frontend.ts failed for sw-profile-active` / `missing required CI build environment: VITE_COMMIT_SHA`. 7건 미실행. 대조군 merge-48 FE-GATE-005 rc=0 | 2.94 | +| 13-R06 | `node scripts/run-vitest.ts run tests/unit/local-build-environment.test.ts` · local | `13-c2-local-env-keeps-ci.diff` | 1, 1초 | "is not checked as a CI build, whatever CI identity the job has" 실패(누락 5건). 다른 2건 통과 | 2.94 | +| 13-R07 | `node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts` · local | `13-m1-config-compare-off.diff` | 1, 1초 | 2 failed / 37: "…config.json is not the candidate's", "…is unreadable" | 2.78 | +| 13-R08 | 같음 | `13-m3-alpn-off.diff` | 1, 1초 | 1 failed / 37: "fails a host that does not negotiate a declared protocol" | 2.78 | +| 13-R09 | 같음 | `13-m4-encoding-off.diff` | 1, 1초 | 1 failed / 37: "fails a hashed asset served without a declared content encoding" | 2.78 | +| 13-R10 | `node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts tests/unit/product-ci-overlay.test.ts` · local | `13-m5-slot-input-rule-off.diff` | 1, 4초 | 2 failed / 437: "rejects a slot that deploys without the promoted candidate", "rejects a slot that extracts the candidate without its digest". `product-ci-overlay`는 통과 | 2.78 | +| 13-R11 | 같음 | `13-m6-secret-step-scope-off.diff` | 1, 3초 | 1 failed / 437: "accepts a deployment job the slot allows"(`not to contain 'secrets.'`). `product-ci-overlay`는 통과 | 2.64 | +| 13-R12 | `node scripts/run-vitest.ts run tests/unit/env-registry-coverage.test.ts` · local | `13-m7-env-row-drift.diff` | 1, 1초 | 1 failed / 4: `AUTH_MODE: row {…"external"}, schema {…null}` | 2.91 | + +요청·패치·결과 파일은 `scratchpad/r4/requests/13.md`, `scratchpad/r4/13/patches/`, `scratchpad/r4/results/13/`에 있다. 변이 9개(R03~R12)는 모두 대조군이 통과하고 변이 실행이 기대한 이유로 실패했다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 13-01 | Medium·P1 | 확인된 결함 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. 그래서 release 실패 이유와 13-03 신호가 실제 workflow에서 사라진다 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249`, `scripts/contracts/ci-gates.ts:947` | +| 13-02 | Medium·P2 | 구조적 위험 | 제품 merge 검사가 실패해도 같은 run의 release·승격·배포가 진행된다. job 그래프가 고정이라 제품이 막을 수도 없다 | `scripts/generate-ci-workflow.ts:129-157`, `scripts/contracts/ci-gates.ts:926-933`, `docs/operations/ci-quality-gates.md:377-378` | diff --git a/docs/reviews/2026-11-05-maturity-review/14-template-product-docs.md b/docs/reviews/2026-11-05-maturity-review/14-template-product-docs.md new file mode 100644 index 00000000..d9ea86ce --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/14-template-product-docs.md @@ -0,0 +1,252 @@ +# 영역 14 — 템플릿 제품성·문서·DX·업데이트 전파 + +> 검토일 2026-11-05 · 기준 `8a44226` (브랜치 `fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> +> 경로: `README.md`, `CHANGELOG.md`, `PRODUCT.md`, `docs/`(특히 `docs/manual/`, `docs/architecture/`, `docs/testing/`), `recipes/`의 문서 주장, `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`, 루트 추적 파일. `docs/reviews/`는 이력이라 판정하지 않았다. 2026-11-03 README §13·§14는 코드와 대조할 주장으로만 읽었다. +> +> 깊게 본 관점: 9 유지보수, 17 API/Contract, 20 개발자 경험, 26 Ownership, 27 삭제 가능성, 30절 전체 +> +> 렌즈: ① 결정 D5(동기화 단위 순 요약)대로 `CHANGELOG.md` 미출시 절이 `e40684b..8a44226`과 맞는가. ② BREAKING 이행 안내가 두 다운스트림(tech-log `7a4e201a`, memento `d3810a0`)의 실제 모양과 맞는가. ③ 수정으로 새로 쓴 매뉴얼(01~04, reference)의 명령·경로·파일 이름·게이트 주장이 `8a44226`에서 참인가. ④ 이 영역의 수정이 검사를 약하게 만들지 않았는가. +> +> 영역 판정(35.8): **새 프로젝트를 복사해 시작하는 용도는 조건부 사용 가능**(04 문서 예시 하나를 고쳐 쓴다, 14-02). **이 미출시 묶음을 다운스트림에 전파하는 용도는 조건부 사용 가능**으로 올렸다. 지난 라운드의 막는 항목 둘(1103/14-01, 14-02)은 해시·[계약] 행·memento-web 숫자까지 맞게 고쳐졌다. 남은 조건은 셋이다. 예제 기능을 지운 제품은 문서 검사가 실패한다(14-01). "옮기기 전" 2단계의 템플릿 파일 목록이 두 제품이 실제로 고친 파일의 일부다(1103/14-02 잔여). 초기 파일 상한 숫자가 절 안에서 둘이다(1103/14-01 잔여). +> +> ID 표기: 이 문서의 새 발견은 `14-01`부터다. 라운드 밖에서는 `1105/14-NN`이다. 지난 라운드는 `1103/14-NN`, 그 전은 `1101/14-NN`, `0929/14-NN`이다. + +## 0. 결론 + +핵심은 둘이다. 지난 라운드에 "전파 보류"였던 CHANGELOG는 이제 범위와 맞는다. 새로 생긴 결함은 모두 서로 다른 브랜치에서 온 수정이 문서에서 만나지 못한 곳이다. + +```text +CHANGELOG 미출시 절 (752a61f → 8a44226, 비병합 348커밋) + 해시 148개 모두 범위 안 / 지난번 빠진 8커밋 모두 행 있음 / ! 커밋 13개 모두 BREAKING 행 + : 초기 파일 상한이 :107·:216은 26, :249와 budgets.json은 32 (1103/14-01 잔여) + : 알려진 제한은 f887817 기준, FE-GATE-017을 merge 게이트로 적음 (1103/14-01 잔여) + +BREAKING 이행 안내 + memento-web 숫자(descriptor 29, schemaId 42+1, isRecord)는 실제와 같다 (1103/14-02 일부 고쳐짐) + : "옮기기 전 2" 목록 = memento 고친 템플릿 src 26개 중 7개, tech-log 38개 중 11개 (1103/14-02 잔여) + : CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사가 실패한다 (14-01, 새) + +매뉴얼 + 01·02·03·reference의 오류 문구 70여 개를 코드와 대조: 모두 있다 + : 04 §3.2 설정 키 예시를 그대로 옮기면 check:types·test:unit 실패 (14-02, 새) + : 참조 기능 경로 26줄이 백틱에서 빠져 문서 검사 밖으로 나갔다 (14-03, 새, 검사 약화) +``` + +- 새 발견 3건: Medium 1(14-01), Low 2(14-02, 14-03). High·P1은 없다. +- 지난 라운드 영역 14 발견 6건 중 4건 고쳐짐(14-03, 14-04, 14-05, 14-06), 2건 일부(14-01, 14-02). 합친 04-05와 03-06(VD-23 부분)은 고쳐짐. +- 이월 항목 7건은 여전히 열려 있다(일부 4, 남음 3). 0929/14-01은 실행 로그 63개가 추적에서 빠져 일부로 바뀌었다. +- 지난 라운드 1103/14-04는 결함 판단은 맞았지만 게이트 이름이 틀렸다. FE-GATE-017은 merge 게이트가 아니다(`config/ci/gates.json:2298` documentation 단계, `.gitea/workflows/quality-gates.yml:466` 수동 실행). merge에서 같은 검사를 하는 것은 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts:58`이다. + +지금 이해하면 되는 것: + +1. 이 미출시 묶음은 다운스트림에 옮겨도 된다. 다만 tech-log는 예제 기능 폴더를 지우기 전에 14-01을 먼저 고쳐야 merge 게이트가 통과한다. +2. "옮기기 전" 2단계 목록에 없는 파일(memento의 HTTP 실행기 `if-match` 수정, tech-log의 `AppFailure.detail` 등)은 동기화 때 충돌이나 조용한 유지로 남는다. 제품 소유 자리가 없는 것도 있다. +3. 매뉴얼 04 §3.2 예시는 `defaultValue: null`을 더해 쓴다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 읽기만 한 저장소: `clean-architecture-backend-template`(`45d2a478`, pin과 같음), `tech-log-frontend`(`7a4e201a`), `memento-frontend`(`d3810a0`). 두 다운스트림 HEAD는 지난 라운드와 같다 | +| 커밋·작업 상태·확인 시점 | `8a44226`, 노트북 worktree(읽기만), desktop checkout(실험만, helper가 실행 뒤 되돌림), 2026-11-05 | +| 목적과 지원 실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 짝 백엔드 템플릿과 함께 쓴다. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 필수 요구와 규모·운영 목표 | 두 템플릿으로 서비스를 빨리 출시한다. 두 다운스트림이 이 템플릿을 복사해 쓰고 범위 단위로 동기화한다(memento merge, tech-log 3-way). 문서 규모 목표는 없다 | +| 지난 리뷰 뒤 바뀐 것 | `e40684b..8a44226` 비병합 172커밋, 병합 12커밋. 이 영역 경로를 고친 커밋 109개. 문서 195개 93,445줄(지난 177개 86,108줄), 그중 `docs/reviews/` 37,162줄. 매뉴얼 2,206줄(지난 1,620줄). 새 문서 `docs/manual/04-paired-backend-session.md`(298줄), 새 recipe `recipes/session-owners/` 2개 | +| 읽은 코드·구성 범위 | `CHANGELOG.md` 미출시 절 전체(`:14-276`), `README.md` 업데이트·CI·지울 파일 절, `PRODUCT.md`, `docs/README.md`, `docs/manual/` 전체, `starter-experience.md` 기능 추가·예제 절, VD-23 머리·배경, `api-contract-schema-mapper-and-server-state.md`·`backend-api-and-server-state-contract.md`의 상태 표와 6·6.1절. `scripts/verify-documentation-readiness.ts` 150~345행, `scripts/test-sample-removal.ts` 30~135·200~220·410~500행, `scripts/lib/removal-fixture.ts` 46~85행, `scripts/check-registries.ts`(84d6e52 diff), `src/contracts/env.ts`, `src/contracts/product-contracts.ts`, `tests/unit/env-registry-coverage.test.ts`, `tests/unit/documentation-readiness.test.ts` 1~60행, `config/ci/gates.json` 단계, `config/performance/budgets.json`. 두 다운스트림은 `git diff af3d8e6 HEAD`(읽기)와 memento-web 계약 파일 | +| 수행한 테스트·실험 | 정적: CHANGELOG 해시 위치·인용 대조(E-1, E-2), 매뉴얼 오류 문구 대조(E-3), 두 다운스트림 파일 목록(E-4), memento-web 모양 집계(E-5), 백틱 밖 경로 존재 확인(E-6). desktop 개별 실행 `14-docs`·`14-examples-drill`은 대기 중 취소돼 돌지 않았다(BRIEF-2). 배치 요청 14-R1·14-R3·14-R4·14-R5(`scratchpad/r4/requests/14.md`). 오케스트레이터 결과: `merge-48/FE-GATE-020`(CI env) | +| 게이트 결과(오케스트레이터, 같은 커밋) | `desktop:/tmp/claude-gates/r4/merge-48/summary.txt`: FE-GATE-020 rc=0 1,156초(CI env). 그 안의 `sample-removal.xml`은 31건 모두 통과이고 `documentation`·`lint`·`i18n`·`design-system`·`scaffold-documentation`이 들어 있다. `gates/summary.txt`(local env): `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration` rc=0. `test:unit`은 2,883건 통과이고 `documentation-readiness.test.ts` 19건, `registry-governance.test.ts` 11건, `env-registry-coverage.test.ts` 4건을 포함한다(`gates/test_unit.log`). `verify:documentation`은 로컬 rc=1이다. 실패 줄은 모두 짝 백엔드 경로이고 그때 백엔드 checkout이 pin이 아닌 `ef947e5`였다(4절 21번). 짝 저장소 없는 임시 worktree에서는 `PASS_SCOPED`, 17개 `not verified`다(`results/00/00-R2-docs-nosibling.log`) | +| 확인하지 못한 범위·이유 | 두 다운스트림에서 실제 병합 뒤 게이트(제품 repo는 읽기만), 다음 동기화 충돌 수 재측정(merge-tree가 쓰기 작업이라 하지 않았다), 깨끗한 환경 `install → dev`, 매뉴얼만 보는 기능 추가 재실험(X2), 목표 설계 문서 본문 전체, 04 §3.3·§4.3 코드 예시의 컴파일 | +| 이전 리뷰와 비교 가능한 범위 | 지난 라운드 영역 14 발견 6건, 합친 2건(04-05, 03-06 일부), 이월 7건과 FOLLOW-UP 1건을 이 커밋에서 다시 판정했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) | +|---|---|---|---| +| 1103/14-01 (+04-05) | CHANGELOG 미출시 절이 기준 커밋과 맞지 않는다 | **일부** | 고쳐진 것: ① 미출시 절 해시 148개가 모두 `752a61f..8a44226`에 있다. 범위 밖은 머리가 기준점이라고 적은 `752a61f`·`af3d8e6` 둘뿐이다(`CHANGELOG.md:27`, E-1). ② 지난 라운드가 빠졌다고 한 8커밋이 모두 행을 가진다: `ece944d`(`:130`), `d0414c8`(`:131`), `8469554`·`7d85589`(`:134`), `7c8cb19`(`:169`), `17fa8d1`(`:198`), `27f4523`(`:133`), `8a09c90`(`:237`), `e5b7b3e`(`:185`). ③ `752a61f..8a44226`의 `!` 커밋 13개가 모두 BREAKING 행에 있다(E-2). `e40684b..8a44226` 비병합 172커밋 중 해시로 인용된 것은 65개다. 나머지 107개는 리뷰 ID로 행에 들어갔거나 테스트·리뷰 기록뿐이다. ④ 알려진 제한에서 지난번 낡았던 9줄이 빠졌다. 남은 것: (a) 초기 파일 상한이 BREAKING 7단계(`:107`)와 [계약] 행(`:216`)은 "26개", 같은 절 `:249`는 "32"다. 코드는 32다(`config/performance/budgets.json:5`, `2fef27d`). 머리 규칙 "최종 상태만 적는다"(`:7`, `:26`)를 어긴다. `:216`이 인용한 `1b8cb12`(26으로 올림)는 범위 안에서 `2fef27d`가 다시 바꾼 중간 상태다. (b) 알려진 제한 머리가 "이 절을 쓴 끝 커밋(`f887817`)에서 사실인 것만"이다(`:258`). 범위 끝은 `8a44226`이다. `:270`의 여유 1,873 B는 기록 값이고, 지난 라운드 14.5절 10회차 빌드(202,975 B)로는 1,825 B다. (c) "옮긴 뒤 확인"이 "로컬 merge 게이트 14개" 아래에 `verify:documentation`(FE-GATE-017)을 둔다(`:112-118`). FE-GATE-017은 merge 단계가 아니다(`config/ci/gates.json:2298`). 남은 것은 모두 사람이 숫자를 읽으면 `check:bundle`이 바로 알려 준다. 새 발견으로 세지 않는다 | +| 1103/04-05 (→14-01) | handoff 결과 kind 변경(`17fa8d1`)의 [계약] 행 없음 | **고쳐짐** | `CHANGELOG.md:198`이 `1196b86`, `17fa8d1`을 함께 적는다. 알려진 제한에 `IDLE_TIMEOUT` 줄이 없다(`:256-276`) | +| 1103/14-02 | BREAKING 이행 안내가 두 다운스트림의 실제 모양과 다르다 | **일부** | 고쳐진 것: memento-web의 모양이 실제와 같다(E-5). `*-api-contract.ts`가 없다는 것, V2 칸 위치(`contracts/memento-feature-contract.ts:28-30`, `:295`), descriptor 29개, schemaId 42개와 `MementoProblem`, `isRecord` 검증기, `responseEnvelope` 0개, 쓰기의 `KEYED`·`IDEMPOTENT`·`NEVER`(`CHANGELOG.md:41`, `:72`, `:95`, `:97`). `ownsShell` → `CONTEXT_LAYOUT`(`:76`). tech-log 직접 조립 길(`:80`)과 그 한계(`:261`). 남은 것: (a) "옮기기 전" 2단계(`:37-39`)는 "제품이 고친 템플릿 파일을 뽑는다"며 memento 7개, tech-log 11개를 적는다. 실제로 `af3d8e6` 뒤 고친 템플릿 `src` 파일은 memento 23개(+템플릿 폴더 안 새 파일 3개), tech-log 38개다(E-4). 빠진 것 중 제품 소유 자리가 없는 것이 있다. memento: `src/adapters/http/http-contract-bridge.ts`·`http-execution-v3.ts`에 descriptor 헤더 `if-match`를 더했다(낙관적 동시성, `memento-http-contract-contribution.ts:390`, `:448`). 템플릿 bridge는 지금도 `headerEntries`가 있는 projection을 거절한다(`src/adapters/http/http-contract-bridge.ts:275`). 템플릿 HTTP 폴더 안의 `offset-upload.ts`와 배럴 export, `storage-keys.ts`의 `APP_NAMESPACE`, OPFS 이름 두 곳. tech-log: `AppFailure.detail`(`src/contracts/errors.ts`), `BoundMutation.identity`(`src/contracts/server-state.ts`), `deriveAsyncState`가 `null`을 빈 상태로 보는 것(`src/application/view-models/async-state.ts`), 라우팅 파일 7개. (b) 완료 기준(안내를 memento 모양에 그대로 적용하면 `check:registries` 통과)은 실행되지 않았다. CHANGELOG가 스스로 적는다(`:32`, `:260`). 영향은 동기화 때 충돌이나 제품 fork 유지로 드러나고 조용한 데이터 피해는 없다. 남은 것은 이 ID로 둔다 | +| 1103/14-03 (+03-06 VD-23 부분) | 목표 설계 문서의 상태 값과 401 규칙이 V2 삭제를 반영하지 않는다 | **고쳐짐**, 작은 잔여 | 완료 기준 셋을 확인했다. VD-23 머리가 `REMOVED (2026-11-03, 048f490·12f3bb7)`이고 V3 실행기를 `COMPOSED`로 적는다(`docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md:10-14`). 401 문장은 "401은 끝이다. 숨은 refresh-and-replay는 하지 않는다(정본 8.4, FRT-D016)"다(`:35-37`). 원장도 V2 행이 `REMOVED`다(`api-contract-schema-mapper-and-server-state.md:85`, `:101`). 6.1절은 `docs/README.md:35`이 현재 계약으로 링크한다. 검사기는 1절 링크 문서를 모두 읽으므로(`scripts/verify-documentation-readiness.ts:269-275`) 6.1절의 repo 경로도 검사된다. 없는 경로를 잡는 동작은 `tests/unit/documentation-readiness.test.ts:119`가 고정한다(E1·E2, 실행 요청 없음). 잔여: 같은 원장 본문 `:306-310`("동시 401 recovery는 … replay-safe operation만 … 한 번 재실행한다"), `:366`, `:863`("REST v2 local baseline은 … 연결됐다")이 V2 시절 서술로 남았다. 이 문서는 머리 `:3-8`에 정본 우선 안내가 있다. 코드는 정본대로다(`src/adapters/http/http-execution-v3.ts:794`). 새 발견으로 세지 않는다 | +| 1103/14-04 (+FOLLOW-UP 09-07) | 참조 기능을 지우면 매뉴얼·입구 문서가 문서 검사를 실패시키고 드릴은 그것을 보지 않는다 | **고쳐짐** | 드릴이 문서를 복사하고(`scripts/test-sample-removal.ts:209-214`, `scripts/lib/removal-fixture.ts:56-60`) `lint`·`verify:documentation`·`check:i18n`·`check:design-system`을 돈다(`:439-442`). 문서 검사 테스트를 fixture에서 지우던 두 줄이 없어졌다. 오케스트레이터 FE-GATE-020(CI env) `sample-removal.xml` 31건 통과, `documentation`과 `scaffold-documentation` 포함. 지난 라운드 실험 E-6의 재실행은 드릴 안의 `documentation` 검사가 대신한다. 지난 제목의 "merge 게이트 FE-GATE-017"은 틀린 이름이다(0절). 결함 판단은 그대로다. 같은 종류의 결함이 예제 기능에서 새로 생겼다(14-01). 고친 방법이 검사를 좁혔다(14-03) | +| 1103/14-05 | 정본 표와 결정표가 지운 메시지와 틀린 게이트 기대를 적는다 | **고쳐짐** | `git grep 'REST security profiles are incoherent\|cannot use the ANONYMOUS profile\|nothing requires the row' -- docs/manual docs/architecture README.md` 0건. `starter-experience.md:224`가 `tests/unit/env-registry-coverage.test.ts`를 적는다. `02-decision-tables.md:244-246`의 메시지가 코드(`src/contracts/external-contract-runtime.ts:410`, `src/contracts/rest-profiles.ts:210`)와 같다 | +| 1103/14-06 | `check:registries`가 조립 실패의 `reason`을 버리고 `removed` 증거를 연쇄로 요구한다 | **고쳐짐** | `84d6e52`: `loadErrorText`가 `(reason: …)`를 붙이고, 읽지 못한 레지스트리는 참조·기준선 비교를 건너뛴다(`scripts/check-registries.ts:125`, `:158-164`, `:410`). `tests/unit/registry-governance.test.ts:544-650`이 출력 두 줄(원인 포함, 연쇄 없음)을 그대로 단언한다. 오케스트레이터 `test:unit`에서 통과했다(E2). 이 테스트는 손으로 던진 오류를 쓴다. 실제 계약 조립 실패(14-R5, 참조 기능 `LIST_REFERENCE_RESOURCES`의 `authProfileId`를 `NOTICE_NOPE`로)에서 출력은 `missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable: reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId NOTICE_NOPE (reason: …같은 문구…)` 두 줄뿐이고 rc=1이다. `removed` 줄과 `is not an object registry` 줄은 없다. 완료 기준을 채웠다(E3). 남은 군더더기: 같은 줄이 두 번(FE-REG-API·FE-REG-SCHEMA가 같은 source) 나오고, 원인이 한 줄 안에 두 번 나온다(`f98d0c3`이 메시지에 원인을 넣은 뒤 `loadErrorText`가 `(reason: …)`를 또 붙인다). 진단 정확성에는 영향이 없다 | +| 1101/14-02 잔여 | 리뷰 ID 꼴이 섞인다 | **남음**(작은 잔여) | `CHANGELOG.md:148`, `:169` `(1101 README 14.3)`, `:149` `(1101 README 14.4, …)`, `:247` `1103 07 영역 P-07-06`. `tests/unit/changelog-review-ids.test.ts`의 정규식은 `NN-MM`·`F-N`만 본다 | +| 1101/14-07 | 문서 위치가 상태를 드러내지 않는다 | **남음**(일부 개선) | `docs/README.md:67`이 로드맵·capability-review를 여전히 "목표 설계"에 둔다. 6.1절은 "목표 설계" 문서 안의 절을 현재 계약으로 링크하는 방식으로 올렸다(`docs/README.md:35`, `backend-api-and-server-state-contract.md:11`). 한 문서 안에 현재 계약 절과 목표 설계 절이 섞인 구조는 그대로다 | +| 0929/14-01 | 실행 로그·작업 기록이 복사 대상에 섞인다 | **일부** | 추적 중인 `.log` 0개(지난 63개, `.gitignore:17`, `529615d`). `SPEC.md`·`tasks/`는 루트에 있고 이유가 "이 라운드가 쓰는 중"이다(`docs/README.md:85`). 2026-09-25 라운드는 끝났다 | +| 0929/14-02 | README 업데이트 절차가 범위 반영을 다루지 않는다 | **일부** | `README.md:363-366`이 "미출시 절은 한 동기화 범위다. 범위 전체를 받고 BREAKING 단계를 먼저 한다"고 적는다. 그러나 명령은 커밋 하나 `cherry-pick`(`:379`)과 `git diff`뿐이다. 두 제품이 실제로 쓰는 범위 merge·3-way 이식 명령은 없다. 두 기준점 형식(`.template-origin`, `template.lock.json`)은 CHANGELOG `:36`에만 있다 | +| 0929/14-03 | 제품이 고치는 템플릿 파일 목록이 없다 | **일부** | 제품 소유 자리가 넓어졌다(`src/contracts/product-contracts.ts`, `src/bootstrap/product-composition.ts`, `src/features/product-capabilities.ts`, `config/ci/product-gates.json`, 매뉴얼 03 C절). 남은 것의 근거는 1103/14-02 잔여 (a)와 같다. 거기서 센다 | +| 0929/14-05 | `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적는다 | **남음** | `docs/operations/ci-quality-gates.md:69` 그대로. 코드는 `release admission warning: FEATURE_OVERRIDES. … the override does nothing`를 낸다(`scripts/check-release-admission.ts:131-141`) | +| 0929/14-06 | 제품이 찾은 템플릿 결함 후보가 돌아오지 않는다 | **남음** | `README.md:393-398`의 분류 문단뿐이다. 다운스트림이 보낸 기록은 repo에 없다. 이번 라운드도 템플릿 리뷰가 다운스트림 코드를 직접 읽었다(1103/14-02 잔여) | +| FOLLOW-UP(09-25) 09-07 (→1103/14-04) | 제거 검사가 lint·`check:i18n`·문서를 건너뛴다 | **고쳐짐** | `scripts/test-sample-removal.ts:439-442`. e2e·visual은 설계상 드릴 밖이고 문서에 적혀 있다(`docs/manual/reference/create-feature.md:164`) | + +1101/14-01·03·04·05·06은 지난 라운드에 고쳐졌고 이번에 되돌아간 것이 없다. + +## 3. 이번 발견 (36.3) + +수: Critical 0 · High 0 · Medium 1 · Low 2. P1 0 · P2 2 · P3 1. 확인된 결함 2 · 구조적 위험 1. + +### 14-01 예제 기능을 지우라는 안내와 문서가 맞지 않는다 — `starter-experience.md`의 백틱 경로 세 개 때문에 지운 제품은 문서 검사(merge 게이트 FE-GATE-005 포함)가 실패하고, 안내한 드릴도 실패한다. `PRODUCT.md`는 반대로 지울 수 없다고 적는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 27, 30.5, 30.4, 9, 20, 10 | +| 근거 | **안내.** `b96d61d`(1103/09-04 조치)가 예제 화면 3개를 끌 수 있는 기능 `platform-examples-feature`로 옮겼다. `CHANGELOG.md:103`은 "예제를 지운 제품(tech-log)은 이 기능 폴더와 `src/contexts/platform-examples-context/`를 지운다"고 적는다. `docs/architecture/starter-experience.md:104-111`은 지우는 법과 드릴 명령(`:108`, `test:sample-removal -- --feature=platform-examples-feature`)을 적고, 세 경로를 백틱 경로로 적는다(`:105`, `:106`, `:111`). **검사.** `verify:documentation`은 `docs/README.md` 1절 문서의 백틱 경로가 있는지 본다(`scripts/verify-documentation-readiness.ts:294`, `:319-325`). 예외는 아직 없는 web worker 폴더 하나와 README의 지울 이력 목록뿐이다(`:161-165`, `:202-208`). merge 단계에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts:58`("passes the documents as they are")이 같은 스크립트를 이 repo의 코드에 대고 돈다. **실험 14-R1(E3).** 세 폴더를 지우고 돌렸다. `verify:documentation`: `docs/architecture/starter-experience.md names paths that do not exist: src/contexts/platform-examples-context, src/features/platform-examples-feature, tests/features/platform-examples-feature`, `FAIL_UNVERIFIED (failed: document references)`, rc=1. 같은 출력에 짝 백엔드 경로 줄도 있는데, 이것은 desktop의 백엔드 checkout이 pin이 아닌 `ef947e5`라서 생긴 환경 실패다(4절 21번). merge 게이트 쪽: `documentation-readiness.test.ts` "passes the documents as they are"가 위 세 경로만으로 실패했다(짝 저장소 없는 임시 사본, rc=1). 지우지 않은 `8a44226`에서는 같은 테스트가 통과한다(오케스트레이터 `gates/test_unit.log`, 19건). **드릴.** 안내한 드릴은 문서를 복사하고(`scripts/test-sample-removal.ts:209-214`) `verify:documentation`을 돈다(`:440`). 또 `src`·`tests`에서 기능 ID를 찾는다(`:417-426`). `tests/unit/hosting-probe.test.ts:248`이 `FEATURE_OVERRIDES: { "platform-examples-feature": false }`를 예시로 쓴다. 그래서 드릴은 `documentation`과 `fixture-id-residue` 두 검사에서 실패한다(E1 추론, 드릴은 시간이 커서 요청하지 않았다). 어느 게이트도 이 드릴을 돌리지 않는다(FE-GATE-020 명령은 `test:sample-removal` 기본값인 참조 기능뿐, `config/ci/gates.json` FE-GATE-020). **반대 주장.** `PRODUCT.md:33`은 "예제 라우트 4개(`/examples/platform`, `ui`, `states`, `auth`)와 홈은 기본 구성이고 제거 드릴이 없습니다"다. `b96d61d` 뒤 셋은 지울 수 있는 기능이다. `PRODUCT.md`는 1절 밖이라 검사되지 않는다 | +| 발생 조건 | 제품이 CHANGELOG 6단계나 `starter-experience.md`대로 예제 기능 폴더를 지울 때. 그 안내의 드릴로 지울 수 있는지 확인할 때. tech-log가 이 묶음을 동기화할 때(CHANGELOG가 tech-log를 이름으로 가리킨다) | +| 영향 | tech-log는 동기화 직후 FE-GATE-005(`test:unit`)가 실패한다. 통과하려면 템플릿 소유 문서 `starter-experience.md`를 고치거나 예제 폴더를 남겨야 한다. 고치면 다음 동기화마다 그 줄이 충돌한다(0929/14-03과 같은 원리). "지울 수 있다"의 증거로 안내한 드릴이 실패해 사람이 원인을 다시 찾는다. 디자인 도구가 읽는 `PRODUCT.md`는 지울 수 없다고 말한다. 데이터·보안 피해는 없다 | +| 심각도·우선순위 | Medium · P2 — 1103/14-04와 같은 기준이다. 게이트가 실패를 드러내므로 조용한 피해는 없다. 그러나 CHANGELOG가 직접 시킨 일이 merge 게이트를 깨고, "지울 수 있는 기능" 약속과 문서 유지가 부딪친다 | +| 통제·증거 | 목표 M3(문서가 지울 수 있다고 한 기능마다 그 제거 드릴이 게이트에서 돈다). 확인: 참조 기능 M3(FE-GATE-020), 예제 기능 M0(드릴을 도는 게이트 없음) · 문서 검사 실패 E3(14-R1). 드릴 실패 E1(추론). `PRODUCT.md` E1 | +| 확실성과 남은 가정 | 문서 검사와 merge 게이트 테스트의 실패는 실험으로 확인했다(14-R1). 드릴의 실패(`documentation`, `fixture-id-residue`)는 드릴 코드를 읽은 추론이다. tech-log가 실제로 폴더를 지울지는 tech-log의 결정이다. CHANGELOG가 그렇게 하라고 적었다. 드릴의 다른 실패(e2e·visual spec이 예제 화면을 연다)는 알려진 제한에 적혀 있고(`CHANGELOG.md:268`) 드릴 밖이다 | +| 결정의 근거 | 기록된 사실: 1103/14-04 조치(`c4d5870`, 게이트·드릴 브랜치 병합 `fbd8f7d`)는 참조 기능 경로만 백틱에서 뺐다. 예제 기능 이동(`b96d61d`)은 다른 수정 브랜치(예제 화면·시각·접근성, 병합 `83f4dd5`)에서 왔다. 리뷰어의 추론: 두 브랜치가 서로의 규칙을 보지 못했다. 선택 비교는 아래 대안 | +| 이해 비용 | 제품 개발자는 CHANGELOG → `starter-experience.md` → 문서 검사 출력 → `verify-documentation-readiness.ts` 예외 목록 순으로 읽어야 원인을 안다 | +| 최소 개선 방향 | ① `starter-experience.md:105`, `:106`, `:111`의 경로를 참조 기능과 같은 규칙(`CHANGELOG.md:225`)으로 백틱 없이 적거나 기능 ID로 적는다. ② `tests/unit/hosting-probe.test.ts:248`의 키를 고정 fixture ID로 바꾼다. ③ `PRODUCT.md:33`을 고친다. ④ 같은 일이 다음 기능에서 반복되지 않게 아래 (c)를 한다 | +| 대안 비교 | (a) 현 상태: 지운 제품마다 템플릿 문서를 고친다. (b) ①~③만: 싸다. 그러나 경로 검사가 또 좁아진다(14-03). (c) 검사기가 "설치된 기능의 폴더(`src/features/

/`, `tests/features//`, 그 context 폴더) 아래 경로는 그 폴더가 있을 때만 본다"를 규칙으로 갖는다: 있을 때는 지금처럼 잡고, 지운 뒤에는 통과한다. 14-03도 함께 풀린다. 지난 라운드 5.2절 (c)는 "지운 뒤에 독자가 끊긴 링크를 만난다"고 버렸지만, 지운 제품에서 그 예시는 어차피 쓸 수 없다. (d) FE-GATE-020에 `--feature=platform-examples-feature`를 더한다: 확실하지만 job 시간이 약 5분 는다(지금 1,156초). (c) + ②③ 권장, (d)는 기능이 셋 이상 지울 수 있게 되면 | +| 단순화의 보존 조건 | 플랫폼 경로(`src/presentation/…`, `src/contracts/…`)의 검사는 좁히지 않는다. 참조 기능을 지운 사본에서 문서 검사가 통과하는 지금 성질(1103/14-04)은 유지한다 | +| 비용·부작용 | ①~③ 문서 3곳·테스트 1줄. (c) 검사기 수십 줄과 테스트 | +| 재검토 조건 | 예제 화면을 다시 지울 수 없는 플랫폼 구성으로 되돌리면 이 발견은 `starter-experience.md`·CHANGELOG 문장 정정으로 바뀐다 | +| 완료 기준 | 세 폴더를 지운 사본에서 `verify:documentation`과 `documentation-readiness.test.ts`가 통과한다. `test:sample-removal -- --feature=platform-examples-feature`가 통과한다. `PRODUCT.md:33`이 코드와 같다 | +| 검증 방법 | 14-R1 재실행, `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` | +| 담당·기한·상태 | 미정 · tech-log 동기화 전 · 신규 | +| 재검증 결과 | 미실시 | + +### 14-02 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어, 그대로 옮기면 `check:types`(FE-GATE-003)와 `test:unit`(FE-GATE-005)이 실패한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 20, 19, 9 | +| 근거 | `docs/manual/04-paired-backend-session.md:127-130`의 `PRODUCT_ENV_REGISTRY` 두 행은 `{ phase: "runtime", classification: "public", required: false }`이고 `defaultValue`가 없다. 행 타입은 `defaultValue: unknown`을 필수 칸으로 가진다(`src/contracts/env.ts:37-42`). `env.ts:94-95`가 제품 행을 그 타입에 넣는다. `tests/unit/env-registry-coverage.test.ts:52-63`은 행의 `{ required, defaultValue }`를 스키마가 키 없을 때 내는 값(`.optional()`이면 `{ required: false, defaultValue: null }`)과 `isDeepStrictEqual`로 비교한다. 같은 매뉴얼 03 C절은 "기본값이 없으면 `defaultValue: null`"이라고 적는다(`03-outside-feature-folder.md:114`). `product-contracts.ts:9-13` 주석도 `defaultValue`를 쓴 예를 든다. 04는 `f3fd10f`(1103/09-03 조치)에서 썼고, 그때 타입에도 `defaultValue`가 이미 필수였다(`git show f3fd10f:src/contracts/env.ts`). **실험 14-R3·14-R4(E3).** 04 §3.2를 그대로 `product-contracts.ts`에 넣으면 `check:types:app`이 `src/contracts/env.ts(94,9): error TS2322 … Property 'defaultValue' is missing …`로, `env-registry-coverage`가 `OIDC_ISSUER: row {"required":false}, schema {"required":false,"defaultValue":null}`(`OIDC_CLIENT_ID`도 같다)로 실패했다(둘 다 rc=1). 대조로 두 행에 `defaultValue: null`만 더하면 둘 다 rc=0이다. 원인은 그 칸 하나다 | +| 발생 조건 | 짝 백엔드 `jwt` 모드로 처음 붙이는 제품이 04 §3.2를 복사할 때 | +| 영향 | 첫 시도에서 타입 검사와 unit 게이트가 실패한다. 실패 메시지가 칸 이름을 말하므로 고치기는 쉽다. 데이터·보안 영향은 없다 | +| 심각도·우선순위 | Low · P2 — 1103/14-05와 같은 기준이다. 매뉴얼 몇 줄의 어긋남이고 게이트가 잡는다. 다만 04는 짝 백엔드에 처음 붙이는 사람이 그대로 따라 하는 문서다 | +| 통제·증거 | 목표 M3(매뉴얼 코드 예시가 지금 타입·테스트를 통과한다). 확인: M0. `verify:documentation`은 설명·코드 블록을 검사하지 않는다(`docs/README.md:49`). recipe 테스트(`tests/recipes/session-owners-runtime.test.ts:48`)는 빈 제품 행으로 돈다 · E3(14-R3, 14-R4) | +| 확실성과 남은 가정 | 04의 다른 코드 예시(§3.3, §4.3)는 recipe 옵션 이름(`recipes/session-owners/oidc-pkce-session-owner.ts:46-66`, `cookie-session-owner.ts:70-82`)과 정적으로만 대조했다. 이름은 맞았다. 컴파일은 하지 않았다 | +| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추는 일이다 | +| 이해 비용 | 작다. 실패 메시지를 보고 03 문서나 `product-contracts.ts` 주석을 찾는다 | +| 최소 개선 방향 | ① 04 §3.2의 두 행에 `defaultValue: null`을 더한다. ② (선택) recipe 파일이 예시 행을 export하고 recipe 테스트가 그 행으로 조립한다. 매뉴얼은 그 export를 가리킨다. 예시가 한 곳에만 있게 된다 | +| 대안 비교 | ① 문장만: 싸다. 다음 타입 변경에서 다시 어긋날 수 있다. ② 예시를 코드로: 테스트가 예시를 지킨다. recipe에 예시 상수가 하나 는다. ①을 지금, ②는 04를 다시 고칠 때 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | ① 두 줄. ② 수십 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 04 §3.2를 그대로 옮긴 사본에서 `check:types:app`과 `env-registry-coverage`가 통과한다 | +| 검증 방법 | 14-R3 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 미실시 | + +### 14-03 참조 기능 경로 26줄을 백틱에서 빼서, 문서 검사가 그 경로를 더 보지 않는다 — 지금은 모두 있지만 참조 기능 파일 이름이 바뀌면 매뉴얼이 조용히 낡는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(이 영역 수정이 만든 검사 약화) | +| 관련 관점 | 21, 10, 9, 20 | +| 근거 | 1103/14-04 조치(`c4d5870`, `2f2426a`, `fd11d08`, `2c2d459`, `b6bfc9b`)가 참조 기능·참조 context 경로와 그 전용 script를 백틱 없이 다시 적었다. `git diff e40684b..8a44226 -- docs README.md`에서 백틱 안의 `reference-feature`·`reference-context`를 지운 줄이 26개다. 예: `docs/manual/01-add-a-feature.md:8`, `:151`, `:237`, `:374`, `:418`, `:419`, `:483`, `:514`, `:610`, `02-decision-tables.md`의 `CREATE_EFFECT` 줄, `backend-api-and-server-state-contract.md:269-270`. 검사기는 백틱 안·명령 안·링크의 경로만 본다(`scripts/verify-documentation-readiness.ts:294-300`). 규칙은 `CHANGELOG.md:225`에 적혀 있다. **지금 상태(E1, E-6).** 1절 문서에서 백틱 밖에 적힌 참조 기능 경로 14개와 샘플 전용 파일 11개는 `8a44226`에서 모두 있다. 그래서 지금은 피해가 없다. 지난 라운드 1103/14-04가 권한 방법 (b)의 비용이다 | +| 발생 조건 | 참조 기능 파일 이름이나 위치가 바뀔 때(예: `reference-routes.ts`를 옮김). 매뉴얼은 그 경로를 예제로 가리키지만 어느 게이트도 실패하지 않는다 | +| 영향 | 매뉴얼 독자가 없는 예제 경로를 따라간다. 매뉴얼이 약속한 "이 폴더 문서의 경로·명령·게이트 ID는 검사된다"(`docs/manual/README.md:85`)가 예제 경로에서는 성립하지 않는데, 그 사실이 독자에게 보이지 않는다 | +| 심각도·우선순위 | Low · P3 — 지금 낡은 경로는 없다. 생기면 문서 독자의 시간만 든다 | +| 통제·증거 | 목표 M3(참조 기능이 있을 때는 그 경로도 검사된다). 확인: 이 26줄은 M3 → M0 · E1 | +| 확실성과 남은 가정 | 26줄은 diff에서 센 값이다. 같은 줄에 경로가 둘 이상이면 경로 수는 더 많다 | +| 결정의 근거 | 기록된 판단: 지난 라운드 5.2절이 (b)를 고르고 (c)(검사기 예외)를 "독자가 끊긴 링크를 만난다"로 버렸다. 리뷰어의 추론: (c)를 "폴더가 있을 때만 본다"로 좁히면 그 반대 이유가 지운 제품에만 해당한다. 비교는 14-01 대안 (c) | +| 이해 비용 | 참조 기능을 고치는 사람이 매뉴얼을 `git grep`으로 직접 찾아 고쳐야 한다 | +| 최소 개선 방향 | 14-01 대안 (c)를 하고 26줄을 다시 백틱으로 적는다. (c)를 하지 않으면, 참조 기능 폴더가 있을 때 1절 문서의 `src/features/reference-feature/…` 꼴 문자열이 모두 있는지 보는 단위 테스트 하나 | +| 대안 비교 | 14-01과 같다 | +| 단순화의 보존 조건 | 참조 기능을 지운 사본에서 문서 검사가 통과하는 성질은 유지한다 | +| 비용·부작용 | (c)와 같다. 단위 테스트만이면 수십 줄 | +| 재검토 조건 | 참조 기능을 템플릿에서 빼거나 지울 수 없는 기본 구성으로 바꾸면 이 위험은 없어진다 | +| 완료 기준 | 참조 기능 파일 하나의 이름을 바꾸는 변이에서 그 경로를 적은 매뉴얼 줄 때문에 게이트가 실패한다. 참조 기능을 지운 사본에서는 통과한다 | +| 검증 방법 | 위 두 변이 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 미실시 | + +## 4. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | > 01~13 영역 | - | - | 이 영역은 문서·드릴 스크립트만 본다 | +| 2 | 구조적 성숙도 | > 09·12 영역 | M3 / M3 | E1 | 입구 문서의 폴더·규칙 설명은 지난 라운드처럼 검사된다(`verify-documentation-readiness.ts:102-150`) | +| 3 | 변경 용이성 | 적용 | M2 / M1 | E1 | P — 제품 소유 자리가 4파일 + `product-gates.json`으로 늘었다. 두 제품이 고친 템플릿 `src` 파일 26/38개 중 안내가 다루는 것은 7/11개다(1103/14-02 잔여) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | P — 문서 195개 93,445줄. 매뉴얼은 2,206줄로 늘었지만 한 경로(README → 01 → 02·03·04 → reference)다. 원장 본문에 V2 서술이 남아 정본 안내를 함께 읽어야 한다(1103/14-03 잔여) | +| 5 | 위험 가시성 | 적용 | M2 / M2 | E1 | P — 알려진 제한 17줄은 대부분 지금 사실이다. 머리가 `f887817` 기준이다. 다운스트림에 적용해 보지 않았다는 사실을 스스로 적는다(`CHANGELOG.md:32`, `:260`) | +| 6 | 실패 성숙도 | > 다른 영역 | - | - | - | +| 7 | 운영 성숙도 | > 11·13 영역 | - | - | - | +| 8 | 디버깅 가능성 | 적용 | M3 / M3 | E2(단위 테스트)·E3(14-R5) | O — `check:registries`가 조립 실패 원인을 적는다(1103/14-06). 문서 검사 실패가 문서·경로를 적는다 | +| 9 | 유지보수 성숙도 | **깊게 봄** | M3 / M1~M3 | E1 | P — 지운 V2 상태 값을 함께 고쳤다(1103/14-03). 다른 브랜치에서 온 수정이 문서에서 만나지 못했다(14-01, 1103/14-01 잔여 (a)) | +| 10 | 테스트 성숙도 | 적용 | M3 / M3(참조 기능) | E2(오케스트레이터 FE-GATE-020) | P — 참조 기능 제거 드릴이 문서·lint·i18n·디자인 게이트를 돈다. 예제 기능의 제거 드릴을 도는 게이트는 없다(14-01) | +| 11 | 데이터 성숙도 | - 이 영역에 데이터 경계가 없다 | - | - | - | +| 12 | 동시성 성숙도 | - 이 영역에 동시 실행 경로가 없다 | - | - | - | +| 13 | 확장성 | > 11·15 영역 | - | - | - | +| 14 | 성능 성숙도 | > 15 영역 | - | - | 문서 규모만 4번에 적었다 | +| 15 | 보안 성숙도 | > 다른 영역 | - | E1 | 04 문서의 보안 주장(토큰을 storage에 두지 않음, ID token 서명 미검사, 쿠키 host 제약)은 recipe 주석·코드와 같은 말을 한다. 동작은 09 영역 | +| 16 | 의존성 성숙도 | 적용(제품에게 템플릿은 의존성) | M2 / M1 | E1 | P — 태그 `v0.2.0` 뒤 348커밋이 태그 없이 쌓였다. 두 제품의 기준점 형식이 다르다(0929/14-02) | +| 17 | API / Contract 성숙도 | **깊게 봄** | M3 / M2 | E1 | P — BREAKING 행과 이행 순서가 범위와 맞는다(1103/14-01 고쳐진 부분). 초기 파일 상한 [계약] 숫자가 틀리다(잔여 (a)). 목록에 없는 제품 수정 중 제품 소유 자리가 없는 계약 변경이 있다(1103/14-02 잔여) | +| 18 | 배포 성숙도 | > 13 영역 | - | - | - | +| 19 | 설정 성숙도 | 적용 | M3 / M3 | E3(14-R3) | P — 제품 설정 키의 FE-REG-ENV 행은 테스트가 요구한다. 04 예시가 그 규칙을 어긴다(14-02). `FEATURE_OVERRIDES` "조용히 무시"(0929/14-05) | +| 20 | 개발자 경험 | **깊게 봄** | M3 / M2 | E1 | P — 매뉴얼 01·02·03·reference의 오류 문구 70여 개가 코드에 있다(E-3). 04 예시 하나가 게이트를 깬다(14-02). 생성 명령 출력 `Next:` 1~3과 매뉴얼이 같은 말을 한다(`scripts/create-feature.ts:1746-1756`). 매뉴얼만 보는 재실험은 이번에도 미실시 | +| 21 | Guardrail 성숙도 | 적용 | M3 / M0~M3 | E1 | P — 문서 경로 검사가 명령 안 경로·짝 저장소 참조까지 넓어졌다. 반대로 참조 기능 경로 26줄이 검사 밖으로 나갔다(14-03). 짝 저장소 참조는 CI에서 `not verified`다(`CHANGELOG.md:273`). 짝 저장소가 옆에 있으면 pin(`config/contracts/backend-contract-pin.json`, `45d2a478`)이 아니라 그 작업 트리를 본다(`scripts/verify-documentation-readiness.ts:305-317`). 그래서 결과가 개발자의 백엔드 checkout에 따라 바뀐다: 오케스트레이터 로컬 실행은 백엔드가 `ef947e5`였을 때 rc=1(`docs/web/http-contract.md`, `docs/manual/07-authorization.md`, `src/application-fileserver` 등이 없다고 적는다. `ef947e5`에는 실제로 없다), 짝 저장소 없는 임시 worktree는 `PASS_SCOPED`, 17개 `not verified`다(`results/00/00-R2-docs-nosibling.log`). 검사기는 12 영역 소관이라 여기서 발견으로 세지 않는다 | +| 22 | 추상화 성숙도 | > 09 영역 | - | - | - | +| 23 | 일관성 | 적용 | M1 / M1 | E1 | P — 리뷰 ID 꼴 넷이 섞였다(1101/14-02 잔여). 같은 문서 안 숫자 26/32(1103/14-01 잔여). `PRODUCT.md`와 `starter-experience.md`가 예제 제거를 반대로 적는다(14-01) | +| 24 | 네이밍 / 의미 성숙도 | 적용 | M1 / M1 | E1 | P — "merge 게이트 14개"에 FE-GATE-017을 넣는다(1103/14-01 잔여 (c)). 04 머리의 "백엔드 `bbe944bd` 기준"(`04-paired-backend-session.md:10`)은 pin `45d2a478`과 다르다. 두 커밋 사이 인증 설정 파일 변경은 없다(`git diff --stat bbe944bd 45d2a478 -- …/auth security.yml application-local.yml infra/keycloak` 0줄) | +| 25 | 조직 확장성 | 적용 | M2 / M1 | E1 | P — 두 제품의 모양을 템플릿 리뷰가 직접 읽어 안내를 맞춘다. 다운스트림 모양 fixture로 안내를 검증하는 장치는 없다(1103/14-02 대안 (B) 미실시) | +| 26 | Ownership 성숙도 | **깊게 봄** | M1 / M1 | E1 | P — 제품 소유 파일과 "고치지 않는다" 목록이 매뉴얼 03 C·D절에 있다. 다운스트림 결함 보고 경로는 기록이 없다(0929/14-06) | +| 27 | 삭제 가능성 | **깊게 봄** | M3 / M0~M3 | E2(오케스트레이터), E1 | P — 참조 기능 삭제는 드릴과 문서 검사를 함께 통과한다(1103/14-04, 오케스트레이터 FE-GATE-020). 예제 기능 삭제는 문서 검사와 그 드릴이 실패한다(14-01). 이력 삭제는 지난 라운드 실험 뒤 바뀐 것이 없다 | +| 28 | 회복 가능성 | > 다른 영역 | - | - | 동기화 되돌림(`git revert`, `README.md:391`)은 실행하지 않았다 | + +### 4.1 30절 템플릿 기준 + +| 절 | 판정 | 근거 | +|---|---|---| +| 30.1 최소 구성과 안전한 기본값 | P | 자리표시자 계약 신원은 staging·production 승인이 거절한다(`src/contracts/deployment-admission.ts:133`). 깨끗한 환경 실행은 이번에도 확인하지 못했다 | +| 30.2 옵션 조합의 수와 검증 책임 | P | 지울 수 있는 기능이 둘(참조, 예제)이 됐는데 드릴은 하나만 게이트에 있다(14-01) | +| 30.3 생성·복사 후 수정 권한 | P | 제품 소유 파일이 늘었다. 두 제품이 고친 템플릿 파일 중 일부는 옮길 자리가 없다(1103/14-02 잔여). 예제를 지운 제품은 템플릿 문서를 고쳐야 한다(14-01) | +| 30.4 버전과 업데이트 전파 | P | 미출시 절이 범위와 맞고 다운스트림 모양을 적는다. 남은 것: 숫자 하나, 기준 커밋 표기, 목록의 빈칸, 적용 실험 없음(2절) | +| 30.5 샘플 코드의 대표성 | P | 매뉴얼은 생성 명령으로 시작하고 참조 기능을 "있으면 더 볼 곳"으로 둔다. 그 경로는 검사 밖이다(14-03) | +| 30.6 도입·유지 비용 | P | 문서 195개 93,445줄, 이번 동기화 범위 348커밋. FE-GATE-020 한 번 1,156초(오케스트레이터) | +| 30.7 템플릿에서 졸업할 수 있는가 | P | `runtime: "zod"` 같은 닫힌 값과, 제품 자리가 없는 실행기 수정(`if-match`)이 제품을 템플릿 파일에 묶는다 | +| 30.8 배포 판단에 필요한 최소 증거 | P | "기능 추가": 오류 문구 대조 E1, 생성 드릴 E2(오케스트레이터). "선택 기능 분리": 참조 기능 E2, 예제 기능 E3(문서 검사 실패, 14-R1). "패치 전달": 안내와 실제 파일 대조 E1, 적용 실험 없음 | + +## 5. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 두 다운스트림의 실제 병합 뒤 게이트 | 제품 repo는 읽기만 했다 | 제품 sync 브랜치에서 병합하고 CHANGELOG만 보고 `check:types`·`check:registries`·`test:unit`까지 진행 | +| 다음 동기화 충돌 수(`8a44226` 기준) | `git merge-tree --write-tree`는 객체를 쓰는 작업이라 하지 않았다. 지난 라운드 값(memento 25, tech-log 76경로)은 `e40684b` 기준이다 | scratch clone에서 지난 라운드 E-5 재실행 | +| memento의 `if-match` 실행기 수정이 병합 뒤 남는지 | 템플릿은 `http-contract-bridge.ts`를 주석 2줄만 고쳤다. 자동 병합으로 memento 수정이 남을 것으로 추론했다 | memento clone에서 병합 | +| 예제 기능 제거 드릴(`test:sample-removal -- --feature=platform-examples-feature`) | 개별 실행이 취소됐고 시간이 커서 배치에 넣지 않았다. 실패는 문서 검사(14-R1)와 잔여 검사(`tests/unit/hosting-probe.test.ts:248`)로 추론했다 | 14-01을 고친 뒤 완료 기준으로 1회 | +| 매뉴얼만 보는 기능 추가(X2) | 지난 라운드 14.6절도 고친 뒤 다시 돌리지 않았다 | 깨끗한 clone에서 매뉴얼만 보는 에이전트 1회 | +| 04 §3.3·§4.3 코드 예시 컴파일 | recipe 옵션 이름만 대조했다 | recipe를 `src/bootstrap/`에 복사하고 예시를 붙여 `check:types:app` | +| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` | 새 clone이나 컨테이너에서 README 명령만 | +| 목표 설계 문서 본문 전체 | 약 3만 줄. 상태 줄과 검색 결과만 봤다 | `git grep -i -E 'v2|replay|mapper registry'` 후보를 코드와 대조 | +| 짝 백엔드가 pin에 있을 때의 `verify:documentation` | desktop 백엔드 checkout이 실행 시점에 `ef947e5`였다. 그때는 짝 백엔드 경로 여러 개가 없다고 실패했다. 짝 저장소 없는 실행은 통과했다 | 백엔드를 `45d2a478`에 두고 1회. 4절 21번(12 영역과 함께) | + +## 6. 실행 기록 + +정적 확인(노트북, 읽기만): + +| ID | 무엇을 | 어떻게 | 결과 | +|---|---|---|---| +| E-1 | CHANGELOG 해시 위치 | 미출시 절(`:14-277`) 백틱 해시 153개를 `git rev-parse`·`git merge-base --is-ancestor`로 `8a44226`, `752a61f`, `e40684b`와 대조 | 이 repo 해시 150개. 148개가 `752a61f..8a44226` 범위. 범위 밖 2개는 기준점 `752a61f`·`af3d8e6`. 나머지 3개는 다른 repo(`45d2a478`, `7a4e201a`, `d3810a0`) | +| E-2 | 범위 커밋과 행 대조 | `git log --no-merges e40684b..8a44226`(172개)와 인용 해시 비교, 커밋마다 `Refs:` 꼬리말 확인. `752a61f..8a44226`의 `type(scope)!:` 커밋과 본문에 `BREAKING`이 있는 커밋 | 해시 인용 65개. 인용 없는 107개는 리뷰 ID로 행에 있거나 테스트·리뷰 기록. `!` 커밋 13개 모두 BREAKING 행. 숫자 불일치 1건(26/32) | +| E-3 | 매뉴얼 오류 문구 | 01·02·03·reference의 백틱 메시지 고정 부분을 `src`·`scripts`·`eslint.config.ts`·`tests/unit`·`tests/e2e`·`.dependency-cruiser.json`에서 `git grep -F` | 약 70개 모두 있다(템플릿 문자열은 고정 부분으로) | +| E-4 | 두 다운스트림이 고친 템플릿 파일 | 각 repo에서 `git diff --name-status af3d8e6 HEAD -- src`(제품 기능·context 폴더 제외) | memento 수정 23, 템플릿 폴더 안 추가 3. tech-log 수정 38. CHANGELOG 목록 7, 11 | +| E-5 | memento-web 모양 | `memento-http-contract-contribution.ts`, `memento-feature-contract.ts` 집계 | descriptor 29(GET 16, 쓰기 13), 검증기 schemaId 42(+`MementoProblem`), `responseEnvelope` 0, `headerEntries` 2 operation(`if-match`) | +| E-6 | 백틱 밖 경로 | 1절 문서에서 백틱 없이 적은 참조 기능·예제 기능·샘플 전용 경로를 모아 존재 확인 | 참조 기능 14개, 샘플 전용 11개 모두 있다 | + +desktop 실행: 개별 실행 `14-docs`(S0~S6)와 `14-examples-drill`은 잠금 대기 중 19:55에 취소돼 돌지 않았다(BRIEF-2). desktop checkout에는 손대지 않았다. 필요한 것만 배치로 요청했다(`scratchpad/r4/requests/14.md`). 오케스트레이터가 2026-11-05 20:09에 차례로 돌렸다(부하 2.9~3.0, 각 1~2초). 각 실행 앞뒤로 checkout을 `8a44226`으로 되돌렸고 복구는 모두 clean이다. 로그: `scratchpad/r4/results/14/`. 표의 rc는 마지막 `echo`의 것이고, 명령별 rc는 로그의 `*-rc=` 줄이다. + +| 요청 | 명령 | 변이 | 발견 | 결과 | +|---|---|---|---|---| +| 14-R1 | `verify:documentation`, `run-vitest … documentation-readiness.test.ts -t "passes the documents as they are"` | `mut/14-R1-rm-examples.sh`(예제 기능·context·기능 테스트 삭제) | 14-01 | rc 0(마지막 echo). `verify-rc=1`: `starter-experience.md`의 세 경로 + 환경 탓 짝 백엔드 경로. `doc-test-rc=1`: "passes the documents as they are"가 세 경로로 실패. 복구 clean | +| 14-R3 | `check:types:app`, `run-vitest … env-registry-coverage.test.ts` | `requests/14-R3.diff`(04 §3.2 그대로) | 14-02 | `types-app-rc=1`(TS2322, `defaultValue` 없음, `src/contracts/env.ts:94`), `env-coverage-rc=1`(두 키 `row {"required":false}`). 복구 clean | +| 14-R4 | 같음 | `requests/14-R4.diff`(`defaultValue: null` 추가, 대조) | 14-02 | `types-app-rc=0`, `env-coverage-rc=0`(4건 통과). 복구 clean | +| 14-R5 | `check:registries` | `requests/14-R5.diff`(참조 기능 `authProfileId` → `NOTICE_NOPE`) | 1103/14-06 | `registries-rc=1`. 원인(`unknown authProfileId NOTICE_NOPE`)이 든 load 실패 두 줄뿐, `removed` 줄 없음. 복구 clean | + +요청하지 않은 것과 이유: 1103/14-03 검증(6.1절 경로 변이)은 검사기 코드와 `documentation-readiness.test.ts:119`로 충분하다. 1103/14-04 재실행은 오케스트레이터 FE-GATE-020의 `sample-removal.xml` `documentation` 항목이 대신한다. 예제 기능 제거 드릴은 약 5~10분이라 14-R1로 대신했다. 대조 실행은 오케스트레이터 게이트 로그(`gates/verify_documentation*.log`, `gates/test_unit.log`, `merge-48/FE-GATE-010.log`)를 쓴다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 14-01 | Medium·P2 | 확인된 결함 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | `docs/architecture/starter-experience.md:105-111`, `CHANGELOG.md:103`, `tests/unit/hosting-probe.test.ts:248`, `PRODUCT.md:33` | +| 14-02 | Low·P2 | 확인된 결함 | 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | `docs/manual/04-paired-backend-session.md:127-130`, `src/contracts/env.ts:37-42` | +| 14-03 | Low·P3 | 구조적 위험 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | `scripts/verify-documentation-readiness.ts:294-300`, `CHANGELOG.md:225`, `docs/manual/01-add-a-feature.md:8` | diff --git a/docs/reviews/2026-11-05-maturity-review/15-performance.md b/docs/reviews/2026-11-05-maturity-review/15-performance.md new file mode 100644 index 00000000..409b869d --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/15-performance.md @@ -0,0 +1,299 @@ +# 영역 15 — 성능 실측·최적화 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `vite.config.ts`, `config/performance/budgets.json`, `config/scale/feature-shape-{ceilings,growth}.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,classify-vite-bundle,lab-performance}.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/test-performance.ts`, `tests/unit/feature-shape-growth.test.ts`, 빌드 산출물과 `artifacts/performance/{bundle,lab}.json`(desktop에서만 빌드). 12 px 조사에 필요한 만큼 `index.html`, `src/bootstrap/main.tsx`, `src/presentation/{pages/home-page.tsx,layouts/app-shell.tsx,routes/app-router.tsx,examples/platform-overview-page.tsx}`, `src/presentation/styles/theme/{base,shell,pages}.css`, `tests/browser-capabilities/browser-files.spec.ts`도 읽었다. +> 깊게 본 관점: 14, 10, 21, 13 +> 렌즈: 지난 라운드 15-01~15-07 수정이 완료 기준까지 갔는가, 수정이 예산·상한·허용 오차를 느슨하게 했는가, 기능 하나를 더하면 예산이 얼마나 남는가, 1103/11-10의 12 px 늦은 성장이 제품의 layout shift인가, lab이 그 순간을 재는가 +> 영역 판정(35.8): **조건부 사용 가능.** 번들 게이트(FE-GATE-012)와 lab 게이트(FE-GATE-026)가 이 커밋에서 통과한다. 지난 라운드의 "release 단계 사용 보류"(1103/15-01)는 풀린다. 조건은 둘이다. (1) 초기 JS 여유가 1,873 B라 `--with-create` 기능 하나(976 B)를 넣으면 897 B가 남는다. 둘째 기능 전에 다운스트림이 예산을 정해야 한다. (2) lab은 플랫폼 화면 하나의 클릭 진입만 잰다. 기능 라우트 첫 진입은 같은 lab 조건에서 406 ms로 대상 화면(148 ms)의 2.7배인데 어느 게이트도 재지 않는다(15-04). lab CLS는 `/` 첫 화면만 보고, 스크롤바를 숨긴 채 잰다(15-01, 15-05). + +## 0. 결론 + +- **지난 발견 7건: 고쳐짐 6(15-01, 15-03~15-07), 일부 1(15-02).** 15-02는 `CHANGELOG.md:107`·`:216`이 초기 파일 예산을 26개로 적어 남았다(실제 32). 이월은 1101/15-01(여유가 작다)·1101/15-03(CSS·라우트 합 예산)·1101/15-04(테스트 시간)·0929/11-04(lab 부하 가드)가 남음이다. 틀린 발견은 없다. +- **lab 게이트가 통과한다.** `test:performance -- --runs=5`(15-lab): 상호작용 중앙값 146 ms(표본 155·146·143·148·146), LCP 2,032 ms, CLS 0. 부하 6.06 → 5.01, i5-10400F. 플랫폼 구성 화면의 제목은 실행부 표보다 300 ms(lab 조건), 1.2초(Fast 3G) 먼저 나온다(15-platform-shift). 기능 하나를 더해도 154 ms로 통과한다(15-feature). +- **번들: 202,927 / 204,800 B(99.1%), 초기 파일 26 / 32개.** 기록(`feature-shape-ceilings.json:42-43`)과 바이트까지 같다. `create:feature --with-create --keyed` 기능 하나(새 context)가 +976 B를 쓰고 897 B가 남는다. 파일 수는 26 그대로다. 파일 상한 25 → 26 → 32는 근거가 있고, 템플릿 자신의 파일 수는 기록의 `files`가 정확히 막으므로 약해진 검사가 아니다(2.1절). 이 영역 diff에서 느슨해진 단언·skip·상한은 찾지 못했다. 단 기록 대조의 허용 오차 1%(2,029 B)가 남은 여유보다 크다(15-02). +- **12 px 늦은 성장은 라우트 로딩 화면(280 px)이 홈 화면(660 px)으로 바뀌는 순간이다.** 앱 셸의 최소 높이(본문 행 648 px)를 홈 내용이 12 px 넘는다. dev server만이 아니라 `vite preview` 제품 빌드에서도, chromium·firefox·webkit 모두에서 같은 값으로 난다. **스크롤바를 숨긴 조건(게이트와 같은 조건)에서는 layout shift가 아니다.** 화면에 있던 요소는 움직이지 않고, Chromium `layout-shift`는 preview 8회 모두 0건이다. lab은 이 순간(lab 조건 약 2.0초)을 networkidle(약 2.25초) 전에 관찰 구간 안에서 본다. **다만 실제 스크롤바를 켜면 작은 shift가 된다.** 창이 홈 내용(732 px)보다 낮으면(1280×720, 1366×657) 이 순간 세로 스크롤바가 생겨 너비가 15 px 줄고, header 오른쪽 세션 영역이 15 px 왼쪽으로 밀린다. CLS 0.00022~0.00023, 12회 모두. 1920×960은 0이다(15-R2). 게이트의 Playwright는 모두 스크롤바를 숨겨 이것을 못 본다. 새 발견 15-05(2.2절). +- **dev server만의 shift가 하나 있다.** dev chromium에서 부팅 셸이 스타일 없이 그려졌다가 CSS가 들어오며 0.00625 shift가 난다(JS가 `theme.css`를 넣음). 제품 빌드는 0이다. +- **새 15-01(Low·P3).** lab 대상 화면은 제목을 그린 뒤 약 30~100 ms에 릴리스 신원 칸이 1칸 → 4칸이 되며 아래 내용을 21 px 민다(shift 0.00461). lab은 클릭 뒤 500 ms 안이라 CLS에서 빼고 0을 낸다. deep link 8회와 Fast 3G 클릭 3회에서는 CLS에 들어간다. lab은 `/`만 직접 열므로 다른 라우트의 CLS는 어느 게이트도 보지 않는다. +- **새 15-04(Low·P2).** lab은 플랫폼 화면 하나만 잰다. 같은 시계로 기능 라우트(`EXAMPLES_UI`)를 재면 중앙값 406 ms(403~410)이고, 대상 화면은 148 ms(144~150)다(15-R1). 기능 라우트는 context 라우트 모듈을 받은 뒤 페이지 청크를 받는 두 번의 요청 묶음을 거친다. 1103/15-01이 플랫폼 화면에서 없앤 모양이 기능 라우트에는 남아 있고, 어느 게이트도 보지 않는다. +- **새 15-02·15-03·15-05(Low·P3).** 기록 대조 허용 오차가 여유보다 크다(15-02). 측정용 빌드 입력 목록 두 벌(15-03, 지난 README 14.7의 남은 문제). 홈 첫 렌더의 스크롤바 shift를 lab이 못 본다(15-05). +- 새 발견: Low 5. P2 1 · P3 4. 확인된 결함 2 · 구조적 위험 3. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` 영역 15(성능 실측·최적화) | +| 커밋·작업 상태·확인 시점 | `8a4422624e81e5d13a3809e212e826ff75aac62b`. 노트북 worktree(HEAD = 기준, 추적 파일 변경 없음, untracked `AGENTS.md`는 무시)에서 읽기만 했다. 실행은 desktop checkout에서 공유 잠금 helper(`/tmp/claude-gates/r4/exp.sh`)로만 했다. 측정 스크립트는 helper의 변이 단계에서 `scripts/r4-15-*.mjs`로 복사했고 helper가 끝에 지웠다(모든 실행 `restored: clean at 8a442262`). 2026-11-05 19:30~20:40. 19:48에 helper가 닫혀(BRIEF-2) 직접 실행은 4개만 돌았다. 나머지 둘은 배치 요청 15-R1·15-R2(`scratchpad/r4/requests/15.md`)로 넘겼고, 오케스트레이터가 20:09~20:11에 돌렸다(둘 다 rc 0, restore clean) | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 운영 서빙은 HTTP/2 이상이 전제다(`config/hosting/cache-policy.json:4`, 13-02) | +| 필수 요구와 규모·운영 목표 | `config/performance/budgets.json:3-12`: 초기 JS 204,800 gzip B, 초기 JS 파일 32개, lazy 청크 파일당 122,880 B, lab LCP 2,500 ms·CLS 0.1·이름 붙은 상호작용 200 ms. 기능 하나 +1 KiB·context 하나 +512 B(`tests/unit/feature-shape-growth.test.ts:157-160`). field p75는 표본 기준이 미정이라 설계대로 `FAIL_UNVERIFIED` | +| 실행 환경 | desktop: Intel Core i5-10400F(논리 CPU 12), Node v24.14.0, Playwright 1.62.0, Chromium 151.0.7922.34, Playwright 번들 Firefox·WebKit. 부하(1분 loadavg)는 6절에 실행마다 적었다(1.5~6.5). desktop 실행: `15-lab`, `15-growth`, `15-feature`, `15-platform-shift`(직접), `15-R1`(기능 라우트 진입), `15-R2`(실제 스크롤바)(오케스트레이터 배치) | +| 읽은 코드·구성 범위 | 머리말 경로. `git diff e40684b..8a44226`로 이 영역 커밋 16개(`d549ceb`, `46dfe23`, `af6d0a9`, `9f9e459`, `c9e7bab`, `1b8cb12`, `f887817`, `2fef27d`, `7f9a515`, `799ab7f`, `e440ece`, `c15345c`, `2c2d459`과 합친 커밋)를 읽었다. `config/ci/gates.json`의 FE-GATE-005·012·026과 stage, `tests/unit/{check-bundle-output,build-environment-bundle,product-feature-selection-build}.test.ts`, `docs/operations/performance-evidence.md`, `docs/architecture/static-delivery.md:43-58`, `CHANGELOG.md` 미출시 절의 예산 문장 | +| 수행한 테스트·실험 | 6절. 요약: 기준 빌드 + `check:bundle` + `test:performance -- --runs=5`(15-lab). `create:feature bulletin-feature --with-create --keyed` 뒤 같은 세 단계(15-feature). 홈 첫 화면의 높이·크기 변화와 layout shift를 dev server와 `vite preview`, 세 엔진에서 추적(15-growth). lab 대상 화면이 제목 뒤에 채워질 때의 layout shift(15-platform-shift). lab과 같은 시계로 기능 라우트 첫 진입(15-R1). 실제 스크롤바를 켠 Chromium에서 첫 화면 shift(15-R2). 오케스트레이터 게이트 로그(`desktop:/tmp/claude-gates/r4/gates/test_unit.log`)에서 이 영역 테스트 결과와 시간을 읽었다 | +| 확인하지 못한 범위·이유 | 5절 | +| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/15-performance.md`(기준 `e40684b`)와 그 README 12·13·14절. 지난 수치는 비교에만 썼다. 바이트는 결정적이라 비교한다. 시간은 호스트가 다르다(지난 라운드 영역 측정은 Core Ultra 7 155H, 이번은 i5-10400F). 그래서 lab 시간은 지난 값과 직접 비교하지 않는다 | + +## 2. 지난 발견 재확인 + +README 14.4는 15-02~15-07을 "고침"으로 적는다. 주장으로만 읽고 현재 코드와 이번 실행으로 다시 판정했다. + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 1103/15-01 | lab 게이트 FE-GATE-026이 실패한다. 측정 화면의 route module이 모든 기능 실행부를 기다린 뒤 그린다 | **고쳐짐** | route module이 페이지를 바로 돌려준다(`src/presentation/examples/platform-overview-page.tsx:662-664`). 실행부가 있어야 아는 칸만 Suspense 두 곳 뒤에서 채운다(`:468-480`, `:526-528`). 조립 모듈도 dynamic import다(`:641-659`). 15-lab: **PASS**, 상호작용 중앙값 146 ms(표본 155·146·143·148·146), LCP 2,032 ms, CLS 0(부하 6.06 → 5.01). 기능 하나를 더한 15-feature도 PASS 154 ms(147~158). 제목이 실행부를 기다리지 않는다(완료 기준 둘째): 15-platform-shift에서 클릭 → 제목 145~150 ms, 클릭 → 오퍼레이션 표 446~451 ms(lab 조건). Fast 3G에서는 674~684 ms와 1,873~1,885 ms다. 남은 것: FE-GATE-026은 여전히 release stage에만 있다(`config/ci/gates.json:2267`). 이번 라운드에서 `d99301b` 대조 A/B는 하지 않았다(수정 커밋 `d549ceb` 본문의 A/B: `d99301b` 107·106 ms, 수정 136·134 ms) | +| 1103/15-02 | 성능 기준선 숫자가 현재 빌드와 다르고 같은 파일 안에서도 다르다 | **일부** | 기록은 `config/scale/feature-shape-ceilings.json:41-46` 한 곳이다. 15-lab 빌드는 202,927 B·26개로 기록과 바이트까지 같다. `feature-shape-growth.test.ts:161-165`가 빌드와 대조하고, `performance-evidence.md:22-38`·`static-delivery.md:43-46`은 숫자 대신 그 칸을 가리킨다. **남은 것:** `CHANGELOG.md:107`(BREAKING 이행 7번)과 `:216`이 "예산은 gzip 204,800 B와 초기 파일 26개"라고 적는다. 상한은 32다(`budgets.json:5`, `2fef27d`가 올리며 CHANGELOG를 고치지 않았다). `performance-evidence.md:170-171`도 "템플릿 그대로의 수(26)"를 손으로 적는다(지금은 맞다). 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 채우지 못한다. 기록 대조의 허용 오차는 새 발견 15-02 | +| 1103/15-03 | 예산을 넘으면 `check:bundle`이 무엇이 얼마나 넘었는지 말하지 않는다 | **고쳐짐** | 예산 실패와 manifest 무결성 실패를 다른 문장으로 쓴다(`scripts/check-bundle.ts:120-143`). 넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다(`scripts/lib/performance-budgets.ts:44-63`). `tests/unit/check-bundle-output.test.ts:80-126`이 초기 바이트·lazy·파일 수·무결성 네 경우의 stderr를 본다. 이번에 넘는 빌드를 직접 만들지는 않았다(E1 + 테스트 존재) | +| 1103/15-04 | 기능당 1 KiB 상한 여유가 40 B이고 context 비용이 섞였다 | **고쳐짐** | 복사본 0·1·2개를 재서 기능 하나와 context 하나를 나눈다(`scripts/scale/measure-feature-shape-growth.ts:214-225`). 기능 1 KiB·context 512 B로 따로 막고 실패 메시지에 잰 값을 넣는다(`feature-shape-growth.test.ts:157-160`). 기록 768 B·233 B라 여유는 256 B·279 B다. 테스트 시간 상한 120 → 180초(`:166`)는 빌드가 2번에서 3번이 된 만큼이다. 약해진 검사로 보지 않는다 | +| 1103/15-05 | 초기 JS 파일 수 상한이 없고 HTTP/2 전제를 확인하지 않는다 | **고쳐짐** | `budgets.json:5` `initialJsFiles` 32. `check-bundle.ts:52`가 세고 자가 검사 fixture가 있다(`:86-97`). HTTP/2 부분은 13-02로 합쳐졌고 production probe가 ALPN을 본다(`scripts/lib/hosting-probe.ts:233-249`, 영역 13 판정). 상한 변경의 근거는 2.1절 | +| 1103/15-06 | build id만 바뀌어도 초기 JS의 49.4%가 캐시에서 버려진다 | **고쳐짐** | react-dom·scheduler 그룹(`vite.config.ts:235-239`). 15-lab 빌드에서 `react-dom-CQa5bBdz.js` 56,515 B가 따로 있다. 코드가 바뀐 15-feature 빌드에서도 같은 이름이다. `tests/unit/build-environment-bundle.test.ts:84-91`이 build id만 다른 두 빌드에서 이름이 같은지 본다. 커밋이 적은 "바뀌는 초기 JS 44,297 B(22.0%)"는 다시 재지 않았다(두 build id 비교를 하지 않음) | +| 1103/15-07 | react-router 개발 빌드가 운영 번들에 들어간다 | **고쳐짐** | build일 때만 `react-router`·`react-router/dom`을 같은 패키지의 `dist/production`으로 보낸다. 파일이 없으면 빌드를 멈춘다(`vite.config.ts:155-170`, `:180`). `build-environment-bundle.test.ts:96-100`이 개발 경고 문구가 없는지 본다. 라우터 청크 30,767 → 30,157 B(15-lab `chunk-3WDNQUW5`). dev server와 capability e2e는 개발 빌드를 그대로 쓴다(의도, `:179`) | +| 13-02 (15-05 뒷부분이 합쳐짐) | HTTP/2·압축 전제가 호스팅 계약과 probe에 없다 | 영역 13 | 위 15-05 행. 이 영역은 상한 32의 근거로만 썼다 | +| 1101/15-01 (지난 문서 "남음: 여유가 작다") | 초기 JS 여유가 작다 | **남음** | 여유 1,873 B(15-lab). 지난 라운드 2,952 B보다 1,079 B 줄었다. 그사이 1103/15-06·15-07 수정은 바이트를 줄였고(−305 B, −613 B, `af6d0a9`·`9f9e459` 본문), 1103 조치 브랜치 열 개가 합쳐지며 늘었다(`f887817` 본문). `--with-create` 기능 하나를 더하면 897 B가 남는다(2.1절) | +| 1101/15-03 | 예산이 CSS를 빼고, lazy는 파일 단위만 본다 | **남음** | `check-bundle.ts:37-45`는 JS만 센다. `performance-evidence.md:68`이 그렇게 적는다. CSS 1개 8,791 B gzip(15-lab, 지난 8,766 B). README 14.4 마지막 단락도 남겼다고 적는다. 라우트 진입 하나가 받는 lazy 합계를 보는 검사도 없다. lazy는 기능 하나로 27 → 39파일, 38,880 → 46,552 B가 됐다(15-feature). 라우트 하나의 요청(15-R1, lab 조건): 플랫폼 구성 화면은 제목 전 4파일 7,037 B, 제목 뒤 6파일. 기능 라우트 `EXAMPLES_UI`는 제목 전 6파일 8,199 B다. 이 합을 보는 예산은 없다 | +| 1101/15-04 (+1101 T1·T2·T4) | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | **남음** | `tests/setup.ts:1-2`는 여전히 모든 파일에 jest-dom·RTL을 싣는다. `tests/unit/service-worker-runtime.test.ts:2006-2022`는 여전히 진짜 시간으로 기다린다(상한 10초). FE-GATE-005는 여전히 `test-unit`과 `test-coverage`를 둘 다 돈다(`config/ci/gates.json` FE-GATE-005 `commandIds`). 시간은 오케스트레이터 `test:unit`(로컬 env, 부하 3.24) 로그로만 봤다: 194파일 2,883건 22.6초, 파일마다 도는 setup의 합 44초, 가장 느린 파일 `documentation-readiness` 17.0초·`product-extension-typecheck` 11.0초(6절). 자식 프로세스를 띄우는 파일의 비율은 다시 재지 않았다 | +| 0929/11-04 | lab 판정이 호스트 부하로 뒤집힌다 | **코드 남음** | `scripts/test-performance.ts:175`, `:188-191`은 부하를 기록만 한다. 이번 두 lab 실행은 부하 2~6에서 표본 범위가 12 ms 안이었다. 판정이 흔들릴 조건은 재지 않았다 | +| 0929/11-05 | 기능 규모 기준선에 소스 커밋이 없다 | **고쳐짐**(필드) | `config/scale/feature-shape-growth.json:16`. 그 값(203,816 B)은 그 커밋의 측정 기록이고, 지금 기준선은 15-02 수정으로 `feature-shape-ceilings.json`의 `initialJavascript`가 맡는다 | +| README 14.7 "`BUILD_INPUTS` 두 벌" | 초기 JS 측정용 빌드 입력 목록이 두 파일에 있다 | **남음** → 새 발견 15-03 | `scripts/scale/measure-feature-shape-growth.ts:40-49`와 `tests/unit/product-feature-selection-build.test.ts:22-31`이 같은 8줄이다. 지난 라운드에는 발견 ID가 없었다 | + +### 2.1 예산 변경의 근거와 남은 여유 + +| 시점 | 초기 JS gzip B | 초기 파일 / 상한 | 근거 | +|---|---:|---|---| +| `e40684b`(지난 라운드) | 201,848 | 25 / 없음 | 지난 문서 6절 | +| `46dfe23` | — | 25 / **25** | 15-05. 상한을 그 브랜치의 수로 뒀다 | +| `1b8cb12` | — | 26 / **26** | 15-01 수정이 조립 모듈을 dynamic import로 바꾸자, 그 모듈과 초기 그래프가 함께 쓰는 `installed-product-manifest`가 따로 떨어졌다. 15-lab 빌드에도 `installed-product-manifest-*.js` 199 B가 초기 파일로 있다. 근거가 맞다 | +| `2fef27d` | — | 26 / **32** | 매뉴얼 검색 폼 예제를 따른 기능 하나가 공유 청크 하나를 떨어뜨려 27 > 26이 됐다(README 14.6 X2 #4) | +| `8a44226`(15-lab) | **202,927** / 204,800 | **26** / 32 | 여유 1,873 B | +| + `create:feature bulletin-feature --with-create --keyed`(15-feature, 새 context) | **203,903** / 204,800 | **26** / 32 | +976 B, 여유 **897 B**. lazy 27 → 39파일, 38,880 → 46,552 B | + +- **26 → 32는 약해진 검사가 아니다.** 템플릿 자신의 파일 수는 기록의 `files`가 정확히(허용 오차 0) 막는다(`measure-feature-shape-growth.ts:238-243`). 템플릿 변경이 초기 파일을 하나라도 늘리면 `test:unit`이 실패하고, 기록을 다시 쓴 diff에 남는다. 32의 여유 6은 다운스트림 기능이 공유 청크를 떨어뜨릴 때만 쓰인다. HTTP/2가 production probe로 강제되므로(13-02) 파일 하나의 비용은 작다(지난 라운드 측정). 바이트 예산 204,800 B는 그대로다. +- **기능 하나를 더하면 거의 다 쓴다.** `--with-create` 기능 하나(새 context)가 976 B를 쓴다. 기록의 기능 768 B + context 233 B = 1,001 B와 비슷하다. 남은 897 B로는 같은 context에 기능 하나(768 B 안팎)가 더 들어갈 수도 있고, 새 context면 넘는다(둘째 기능은 재지 않았다). CHANGELOG의 운영 의존성 advisory 항목은 zod를 고치는 버전이 초기 JS를 약 7 KB 늘린다고 적는다(`CHANGELOG.md:271`, 이번에 재지 않음). 그 갱신은 지금 예산으로는 들어가지 않는다(13-03 결정 대기). +- 기능을 더해도 초기 파일 수는 26 그대로다. 생성 기능의 지연 페이지는 공유 청크를 떨어뜨리지 않았다. lab도 PASS(154 ms)다. + +### 2.2 12 px 늦은 성장(1103/11-10) — 무엇이 자라는가 + +**결론: 홈 화면이 라우트 로딩 화면을 대신 그리는 순간이다. 제품 빌드에서도, 세 엔진 모두에서 같은 12 px로 난다. 스크롤바를 숨긴 조건에서는 layout shift가 아니다(Chromium CLS 0). 실제 스크롤바가 있으면 그 순간 스크롤바가 생겨 header가 15 px 밀리는 작은 shift(CLS 0.0002)가 된다(15-05).** dev server만의 현상이 아니다. 다만 dev에서는 load 이벤트와 그 순간의 간격이 엔진마다 달라 firefox에서 클릭과 겹쳤다. + +흐름은 이렇다(15-growth, 1280×720, 세 엔진 같은 값). + +``` +index.html 부팅 셸 "불러오는 중"(#root 안 192 px) + → load 이벤트 (entry가 앱 그래프를 dynamic import하므로 앱을 기다리지 않는다, src/bootstrap/main.tsx:14) + → AppShell + RouteLoadingSurface(div.ui-page.route-loading, 280 px) 문서 720 px + → HomePage(section.ui-page, 660 px)가 로딩 화면을 대신한다 문서 732 px +``` + +- 왜 12 px인가. `.app-shell`은 `min-height: 100vh`이고 header 4.5rem, 본문 행은 sidebar 높이 `calc(100vh - 4.5rem)`으로 648 px다(`src/presentation/styles/theme/shell.css:35-43`, `:157-161`). 로딩 화면(280 px)은 그 안에 들어간다. 홈 내용은 660 px라 행이 648 → 660이 되고, 문서가 720 → 732가 된다. 내용은 380 px 늘었지만 문서 밖으로 보이는 것은 12 px다. +- 바뀐 요소는 매번 같은 프레임의 9개뿐이다: `html`·`body`·`#root`·`.app-shell` 720 → 732, `main#main-content` 648 → 660, 로딩 화면과 그 자식 4개가 0이 됨. 그 뒤로는 높이가 바뀌는 요소가 없다. 글꼴 교체는 없다(웹 글꼴 없음, `--font-sans`는 시스템 글꼴, `src/presentation/design-system/tokens/semantic.css:33`). 런타임 요약 줄은 "확인하고 있습니다" → "빌드 … · 릴리스 …"로 바뀌지만 한 줄 그대로다. i18n 문구는 부팅 때 이미 있다. +- 시각(navigation 시작부터 `performance.now()`, 첫 dev 실행인 warm-up은 뺐다): + +| 실행 | 횟수 | load 이벤트 | 로딩 화면 | 홈 화면(+12 px) | +|---|---:|---:|---:|---:| +| preview chromium | 5 | 16~22 ms | 95~163 ms | 394~421 ms | +| preview firefox | 3 | 38~209 ms | 112~395 ms | 417~704 ms | +| preview webkit | 3 | 17~28 ms | 455~473 ms | 697~708 ms | +| preview chromium, lab 조건(CPU 4×, 40 ms, 200 KB/s) | 3 | 206~209 ms | 1,721~1,740 ms | 1,995~2,018 ms(networkidle 2,238~2,258 ms) | +| dev chromium | 5 | 22~36 ms | 400~414 ms | 691~734 ms | +| dev firefox | 3 | **390~411 ms** | 431~453 ms | **732~760 ms** | +| dev webkit | 3 | 75~78 ms | 728~741 ms | 965~979 ms | + +- 11-10과 맞춰 보면: capability test는 `goto("/")`(load까지) 뒤에 dev 모듈을 import하고 버튼을 붙여 누른다. dev firefox에서는 load가 400 ms 근처라, 그 뒤 수백 ms 안에 홈이 그려진다. 클릭이 그 창에 걸렸다. chromium dev는 load가 30 ms 근처라 클릭이 홈보다 훨씬 먼저 끝난다. 이것이 firefox에서만 떨어진 이유로 보인다(추론, 클릭 시각은 재지 않았다). body 744 → 756은 문서 720 → 732에 test가 붙인 한 줄(24 px)을 더한 값이다. +- **layout shift인가.** 스크롤바를 숨긴 조건(게이트와 같은 조건)에서는 아니다. 화면에 있던 요소가 움직이지 않는다. header·sidebar는 그대로이고, 로딩 화면은 지워지고 홈 내용은 새로 나타난다. Chromium `layout-shift` entry(buffered)는 preview 5회 + lab 조건 3회 모두 0건이다. 문서 아래에 붙인 요소(test의 버튼)만 밀린다. firefox·webkit은 `layout-shift`가 없어 ResizeObserver 추적으로 같은 변화를 확인했다. +- dev server에만 있는 것이 하나 있다. dev chromium에서는 실행마다 layout shift 1건(0.00625)이 t = 26~37 ms(warm-up은 224 ms)에 난다. source는 `body`가 (8, 8, 1264×24) → (0, 0, 1280×720)이다. 부팅 셸이 24 px → 192 px가 되는 순간이다(세 엔진 dev 모두). dev는 `theme.css`를 JS 모듈이 넣으므로(`src/bootstrap/main.tsx:1`) 부팅 셸이 스타일 없이 한 번 그려진다. preview는 처음부터 192 px이고 shift가 0건이다. 제품 영향은 없다. +- **lab이 이 순간을 재는가.** 잰다. lab은 `networkidle`까지 기다린 뒤 클릭한다(`scripts/test-performance.ts:148-152`). lab 조건에서 홈이 그려지는 시각(약 2.0초)은 networkidle(약 2.25초)보다 앞이다. 그래서 첫 화면의 shift는 lab CLS 관찰 구간 안에 있다. lab CLS 0은 이 순간을 놓친 값이 아니라 shift가 없다는 값이다. 다만 lab이 보지 못하는 것이 셋 있다. (1) headless Chromium은 스크롤바를 숨긴다. 홈이 그려질 때 세로 스크롤바가 생기면 실제 브라우저(일반 스크롤바)에서는 너비가 줄어 header 오른쪽 요소가 가로로 밀릴 수 있다. 15-R2(Chromium, `--hide-scrollbars`를 뺌, 창 셋 × 지연 없음·lab 조건 × 3회)가 확인했다. 1280×720과 1366×657에서는 홈이 그려지는 프레임에 `clientWidth`가 1280 → 1265, 1366 → 1351로 줄고 `div.app-shell__session`이 x 802 → 787(888 → 873)로 밀린다. layout shift 1건, CLS 0.00023·0.00022, 12회 모두 같다. 1920×960은 홈(732 px)이 창 안에 들어가 6회 모두 0이다. lab과 모든 게이트의 Playwright Chromium은 스크롤바를 숨기므로 이것을 못 본다(새 발견 15-05). (2) firefox·webkit에는 lab이 없다. (3) 클릭 뒤 500 ms 안의 shift는 정의상 CLS에서 빠진다(`hadRecentInput`, `:114`). 이 영향은 3절 15-01에서 본다. +- **어떤 test·게이트가 첫 화면의 늦은 성장을 잡는가.** CLS가 되는 성장은 lab(release 단계, Chromium, 스크롤바 숨김)만 잡는다. 성장 자체는 사용자에게 해가 없다. 사용자에게 보이는 부분은 스크롤바가 생기며 header가 밀리는 15 px이고, 그것은 어느 게이트도 잡지 않는다(15-05). 해가 된 곳은 앱 흐름 뒤에 요소를 붙인 test였고, 11-10 수정(`browser-files.spec.ts:3-17`, 고정 층)이 그 두 test를 고쳤다. `goto` 뒤 load를 "앱이 그려졌다"로 쓰면 안 된다는 점은 남는다. load는 앱 그래프를 기다리지 않는다(`main.tsx:14`). 첫 화면이 그려졌다는 신호로는 라우트 heading(`h1[data-route-heading]`, 시각 테스트의 `expectRouteHeading`, `tests/visual/platform.visual.spec.ts:13-15`)이 있다. 다른 capability spec이 body에 요소를 붙이지 않는다는 것은 11-10 수정 커밋 본문의 grep 주장이다(이번에 다시 보지 않았다, 영역 11). + +## 3. 이번 발견 (36.3) + +새 발견 5건: Low 5. P2 1 · P3 4. 확인된 결함 2 · 구조적 위험 3. High 이상과 P1은 없다. + +### 15-01 lab 대상 화면이 그린 뒤 릴리스 신원 칸을 늘려 아래 내용을 21 px 민다. lab은 그 shift를 클릭 입력 창 안이라 빼고, `/` 밖의 라우트 CLS는 어느 게이트도 보지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 14, 21, 10, 5 | +| 근거 | 15-platform-shift(preview, Chromium, 1280×720, 16회). 매번 layout shift 1건, 값 0.00461. source는 `section[aria-labelledby=platform-summary-title]`(y 495 → 516)과 `section[platform-release-title] > dl.platform-metric-grid > div.platform-metric > dd`다. 원인: 릴리스 신원 칸은 `getReleaseSummary()`가 effect에서 끝날 때까지 "상태: 런타임 정보를 확인하고 있습니다." 한 칸만 그린다. 끝나면 빌드·릴리스·설정 스키마·다이제스트 네 칸을 hint 줄과 함께 그린다(`src/presentation/examples/platform-overview-page.tsx:378-393`, `:422-454`). hint 한 줄만큼 grid 행이 커지고 그 아래 모든 section이 내려간다. 시각(클릭 기준): 지연 없음 제목 20~26 ms·shift 51~53 ms, lab 조건 제목 145~150 ms·shift 218~223 ms, Fast 3G 제목 674~684 ms·shift 748~754 ms. lab은 클릭 뒤 500 ms 안의 shift를 `hadRecentInput`으로 뺀다(`scripts/test-performance.ts:111-118`). 그래서 lab 조건에서는 CLS 0이다. Fast 3G 클릭(3회)과 deep link(8회, 지연 없음·lab·Fast 3G)는 입력 창 밖이라 CLS 0.00461로 셌다. lab은 `/`를 열고 클릭으로만 들어간다(`:148-152`). 그래서 대상 화면의 CLS는 구조적으로 잴 수 없다. 이 칸은 `c6da0336`(2026-08-01)부터 같다. 15-01 수정(`d549ceb`)이 더한 Suspense 두 곳은 shift를 더하지 않았다(16회 모두 shift 1건뿐, 오퍼레이션 표는 제목 뒤 약 300 ms) | +| 발생 조건 | 플랫폼 구성 화면을 직접 열거나 새로 고칠 때. 느린 회선에서 클릭으로 들어갈 때(제목이 클릭 뒤 500 ms보다 늦을 때) | +| 영향 | 제목이 보인 뒤 약 30~100 ms에 아래 내용이 21 px 내려간다(지연 없음 약 30 ms, Fast 3G 약 75 ms, lab 조건 약 70~100 ms). CLS 0.0046은 예산 0.1의 4.6%다. 더 큰 영향은 측정 쪽이다. 다운스트림의 화면이 그린 뒤 채워지며 밀어도, 그 화면이 `/`가 아니면 lab CLS는 0을 낸다 | +| 심각도·우선순위 | Low · P3 — 값이 작고 예제 화면이다. lab CLS가 `/`만 본다는 점은 기록해 둔다 | +| 통제·증거 | 목표 M3(lab이 대상 화면의 CLS를 검출) / 확인 M3(`/` 첫 화면만), 대상 화면 M0 · E3(16회) + E1 | +| 확실성과 남은 가정 | Chromium만 쟀다(다른 엔진에는 API가 없다). 실제 스크롤바와 다른 창 크기에서는 재지 않았다. 사용자가 21 px 이동을 알아채는지는 판단하지 않았다 | +| 결정의 근거 | 적용 제외 — 칸 수를 미리 맞추는 표시 결함이다. lab 측정 범위는 아래 대안 비교에 적었다 | +| 이해 비용 | lab이 CLS 0을 내니 화면을 고친 사람은 shift가 없다고 믿는다. 클릭 뒤 500 ms 규칙을 알아야 0의 뜻을 안다 | +| 최소 개선 방향 | (1) 릴리스 신원 칸이 처음부터 네 칸 모양(같은 label·hint 줄, 값만 "확인 중")을 그린다. (2) lab이 대상 라우트를 한 번 직접 열어 그 CLS도 `lab.json`에 남긴다 | +| 대안 비교 | (a) 현상 유지: 값이 작다. 다음 회귀도 lab이 0으로 본다. (b) 네 칸 자리 표시(권장, 화면 한 파일). (c) 릴리스 요약을 동기로 읽음: 부팅 때 이미 가진 값이지만 `getReleaseSummary()`가 비동기 포트 계약이라 포트를 바꿔야 한다. (d) lab deep link 표본 추가: run마다 navigation 하나(lab 조건 약 2초)가 늘고, 같은 종류의 회귀를 잡는다 | +| 단순화의 보존 조건 | lab 상호작용 시계(클릭 → 대상 heading)와 중앙값 판정. 릴리스 칸의 `aria-live="polite"`(`:422`) | +| 비용·부작용 | (b)는 몇 줄. (d)는 FE-GATE-026 시간 +10~20초 | +| 재검토 조건 | field CLS 데이터가 생기면 lab deep link 표본의 필요를 다시 본다 | +| 완료 기준 | `/examples/platform`을 직접 열면 layout shift가 0건이다. `lab.json`에 대상 라우트를 직접 연 CLS가 있다 | +| 검증 방법 | 15-platform-shift와 같은 방법(`scratchpad/r4/a15/r4-15-platform-shift.mjs`) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-02 초기 JS 기록 대조의 허용 오차(1%, 2,029 B)가 남은 여유(1,873 B)보다 크다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 9, 21, 5, 13 | +| 근거 | `initialJavascriptRecordDrift`는 합계를 1%까지 같다고 본다(`scripts/scale/measure-feature-shape-growth.ts:238-246`). 주석은 그 이유로 "build id로 합계가 수십 바이트 움직인다"를 든다(`:227-233`). 1%는 202,927 B의 2,029 B다. 여유는 1,873 B다(15-lab). 단위 테스트는 기록 201,500 B와 빌드 200,000 B(1,500 B 차이)를 "같음"으로 고정한다(`tests/unit/feature-shape-growth.test.ts:176-178`, `toEqual([])`). build id 차이는 수십 B 규모다. README 14.5 10회차는 `8a3b16a`와 `37c63e8`의 차이를 6 B(커밋 ID)로 적었고, 그 desktop 게이트의 202,975 B와 15-lab의 202,927 B도 48 B 차이다. 문서는 여유를 그 기록으로 계산하라고 한다(`docs/operations/performance-evidence.md:37-38`). `CHANGELOG.md:107`·`:270`은 "여유는 1,873 B"를 적는다 | +| 발생 조건 | 템플릿 변경이 초기 JS를 2 KB 안에서 늘리거나 줄이고 기록을 다시 쓰지 않을 때. 이 영역의 기능 하나(+976 B, 0.48%)도 합계 칸만으로는 걸리지 않는다 | +| 영향 | 기록과 그것을 인용한 문서가 "여유 1,873 B"라고 말하는 동안 실제 여유는 0일 수 있다. 실제 초과는 FE-GATE-012가 막으므로 배포 피해는 없다. 계획 숫자만 틀린다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 목표 M3(기록이 여유보다 작은 오차로 맞음) / 확인 M3(2,029 B 단위) · E1 + E3(15-lab 바이트) | +| 확실성과 남은 가정 | 기능 하나를 더했을 때 `files`·기능·context 칸의 10% 오차로 테스트가 실패하는지는 재지 않았다(이 경우 생성 명령 `Next:` 3번이 기록을 다시 쓰라고 한다). 템플릿 변경이 실제로 2 KB 안에서 기록을 낡게 둔 사례는 아직 없다(지금은 0 B 차이) | +| 결정의 근거 | 15-02 수정 커밋 `c9e7bab`이 지난 리뷰의 완료 기준(1%)을 그대로 썼다. 지난 리뷰는 여유가 2,952 B일 때 그 숫자를 정했다. 리뷰어 추론: 여유가 줄면서 1%가 여유보다 커졌다 | +| 이해 비용 | 기록을 믿는 사람은 기능 두 개가 더 들어간다고 계산한다 | +| 최소 개선 방향 | 합계 허용 오차를 바이트로 둔다. build id 차이(수십 B)를 넘고 기능 하나(약 768 B)보다 작은 값, 예: 256 B | +| 대안 비교 | (a) 현상 유지. (b) 바이트 상한(권장, 한 줄). (c) 여유 자체를 기록하고 대조: 예산이 바뀔 때마다 같이 바뀌어 더 낡기 쉽다 | +| 단순화의 보존 조건 | CI와 로컬 build id 차이로 테스트가 흔들리지 않는다 | +| 비용·부작용 | 초기 JS를 수백 바이트 움직이는 템플릿 변경마다 기록을 다시 써야 한다. 그게 목적이다 | +| 재검토 조건 | 예산이나 기준선이 크게 바뀌어 여유가 10 KB 이상이 되면 비율로 돌아가도 된다 | +| 완료 기준 | 초기 JS를 300 B 늘린 템플릿 변경에서 기록을 다시 쓰기 전까지 `test:unit`이 실패한다 | +| 검증 방법 | 셸 문구 하나를 늘리는 변이로 `feature-shape-growth.test.ts`를 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-03 초기 JS 측정용 빌드 입력 목록(`BUILD_INPUTS`)이 두 파일에 같은 내용으로 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 9, 23, 3, 10 | +| 근거 | `scripts/scale/measure-feature-shape-growth.ts:40-49`와 `tests/unit/product-feature-selection-build.test.ts:22-31`이 같은 8개 경로를 따로 적는다. 둘 다 그 목록을 임시 폴더에 복사하고 vite build를 돈다. `c15345c`가 `vite.config.ts`에 새 import를 더하자 두 목록 모두 낡아 `test:unit` 두 파일과 제거 드릴 셋이 "Could not resolve"로 실패했다. `7f9a515`가 두 곳을 같이 고쳤고, `799ab7f`가 다시 두 곳에서 지웠다. 그 커밋 본문이 합치는 것을 "남은 문제"로 적었고 README 14.7에도 있다. 지난 라운드에는 발견 ID가 없었다 | +| 발생 조건 | `vite.config.ts`나 빌드가 읽는 루트 파일이 새 로컬 파일을 import할 때 | +| 영향 | 조용히 틀리지는 않는다. 빌드가 실패해 바로 보인다. 다만 고칠 곳이 둘이고, 오류 메시지는 한 곳만 가리킨다. 다운스트림이 vite 설정을 나눌 때 같은 실패를 만난다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 목표 M2(한 곳에 정의) / 확인 M1(커밋 본문의 남은 문제) · E1(두 파일) + 커밋 기록 | +| 확실성과 남은 가정 | 지금 두 목록은 같다(갈라진 사본은 아니다). `scripts/lib/removal-fixture.ts:25-39`의 목록은 제거 드릴용 전체 사본이라 목적이 달라 세지 않았다 | +| 결정의 근거 | 적용 제외 — 같은 상수를 한 모듈에서 내보내면 되는 중복이다 | +| 이해 비용 | vite 설정을 바꾸는 사람이 두 테스트 파일을 찾아야 한다 | +| 최소 개선 방향 | `scripts/lib/`에 목록 하나를 두고 두 파일이 import한다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 두 테스트가 같은 입력으로 빌드한다. 측정 스크립트가 테스트 파일을 import하지 않는다 | +| 비용·부작용 | 파일 하나 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `git grep -n "const BUILD_INPUTS"`가 한 곳이다 | +| 검증 방법 | `vite.config.ts`에 로컬 import 하나를 더하는 변이로 한 곳만 고치면 두 테스트가 통과하는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규(README 14.7 남은 문제) | + +### 15-04 lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입(lab 조건 406 ms, 요청 두 묶음)은 어느 게이트도 재지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 21, 13, 10 | +| 근거 | lab 대상은 `ROUTE_REGISTRY.EXAMPLES_PLATFORM` 하나다(`scripts/test-performance.ts:46`). 플랫폼 라우트이고 기능 라우트가 아니다(`src/contracts/routes.ts:33-45`). 15-01 수정 뒤 이 화면은 기능 실행부를 기다리지 않고 그린다(`platform-overview-page.tsx:662-664`). 그래서 lab 수치는 기능이 늘어도 거의 그대로다(15-lab 146 ms → 기능 하나 더한 15-feature 154 ms). 기능 라우트는 처음 들어갈 때 그 기능의 실행부와 페이지 청크를 받는다(`src/features/installed-feature-runtime-registries.ts:23-24` 주석). `CHANGELOG.md:269`(알려진 제한)는 "기능 라우트 첫 진입(실행부 청크, 약 430 ms)은 어느 게이트도 재지 않는다"고 적는다. 15-R1(lab과 같은 시계와 throttle, `vite preview`, 번갈아 5회): 기능 라우트 `EXAMPLES_UI`(`platform-examples-feature`) 중앙값 **406 ms**(403·405·406·406·410), lab 대상 `EXAMPLES_PLATFORM` 148 ms(144·146·148·150·150). 기능 라우트의 요청은 두 묶음이다. 클릭 뒤 39~95 ms에 context 라우트 모듈(`context-routes`, 830 B)과 기능 실행부(177 B), 그 뒤 98~204 ms에 페이지 청크(`ui-gallery-page`, 5,893 B)와 공유 청크 셋(1,299 B)이다. 제목 전 6파일 8,199 B. 첫 묶음이 끝나야 둘째 묶음의 이름을 안다: `ContextRouteGateway`가 effect에서 `routeModule.loadRoutes()`를 기다린 뒤 라우트를 그리고(`src/presentation/routes/app-router.tsx:510-538`), 그때 페이지 lazy 청크를 받는다. 기능 실행부는 첫 묶음에 같이 받도록 이미 맞춰져 있다(`:522-530`). 나머지 약 200 ms는 CPU 4× 조건의 렌더로 보인다(나누어 재지 않음) | +| 발생 조건 | 다운스트림의 화면은 모두 기능 라우트다. 템플릿 안에서는 `platform-examples-feature`의 예제 화면과 참조 기능 화면이다 | +| 영향 | 템플릿의 유일한 상호작용 예산(200 ms)이 제품 화면을 보지 않는다. 지금 기능 라우트 진입은 그 값의 2배다. 1103/15-01이 플랫폼 화면에서 없앤 "요청 묶음 하나 더"가 기능 라우트에는 구조로 남아 있다. 기능 실행부·페이지가 커지거나 왕복이 더 늘어도 모든 게이트가 통과한다 | +| 심각도·우선순위 | Low · P2 — 기능 결함은 아니다. 406 ms는 lab 조건(CPU 4×, 200 KB/s) 값이고, 예산은 이름 붙은 라우트 하나에만 적용되므로 계약 위반도 아니다. CHANGELOG에 알려진 제한으로 적혀 있다(M1). 그러나 제품을 만드는 경로의 성능을 템플릿 게이트가 보지 않으므로 P2다 | +| 통제·증거 | 목표 M3(제품 화면 하나 이상을 lab이 잰다) / 확인 M1(CHANGELOG 제한 문장), 게이트 M0 · E3(15-R1, 5회 번갈아) + E1 | +| 확실성과 남은 가정 | 기능 라우트 하나(예제 화면)만 쟀다. 생성 기능 목록 라우트는 세션과 백엔드 응답이 필요해 재지 않았다. 406 ms를 왕복·다운로드·렌더로 나누지 않았다. CHANGELOG의 430 ms와 가깝다 | +| 결정의 근거 | 기록된 의도: 1103/15-01의 대안 비교는 "lab 대상 라우트 변경"을 회귀를 숨긴다는 이유로 버렸다. 대상을 바꾸지 않고 하나를 더하는 선택은 비교되지 않았다(리뷰어 확인). 리뷰 기록 README 14.7은 이것을 "새 관찰"로만 적었다 | +| 이해 비용 | 다운스트림 담당자는 lab PASS를 제품 화면 진입이 200 ms 안이라는 뜻으로 읽기 쉽다 | +| 최소 개선 방향 | lab이 이름 붙은 상호작용을 하나 더 잰다. 내비게이션에 있는 첫 기능 라우트(`ROUTE_FEATURE_OWNER`가 있는 것)를 같은 시계로 재고 `lab.json`에 따로 남긴다. 처음에는 기록만 하고, 예산은 값을 본 뒤 정한다. 두 묶음을 하나로 줄이는 것(context 라우트 모듈을 받을 때 그 라우트의 페이지 청크도 같이 받기)은 그다음 별도 결정이다 | +| 대안 비교 | (a) 현상 유지 + CHANGELOG의 제한 문장. (b) 기능 라우트 표본 추가(권장): run마다 navigation 하나, FE-GATE-026 +10~15초. (c) 진입한 URL의 페이지 청크를 context 라우트 모듈과 같은 묶음에서 받기: 둘째 묶음(약 100 ms)을 없앨 것으로 보이나 측정 없이는 판단하지 않는다. 라우트 표와 페이지 청크의 대응을 gateway가 알아야 한다. (d) hover·idle 프리페치: 키보드·직접 진입에는 효과가 작다(1103/15-01 대안 비교와 같다). (e) `budgets.json`에 라우트별 예산: 표가 늘고 다운스트림이 채워야 한다 | +| 단순화의 보존 조건 | 기존 대상 라우트의 측정과 예산을 그대로 둔다(회귀 비교가 이어진다) | +| 비용·부작용 | (b)는 스크립트 수십 줄과 lab 시간 | +| 재검토 조건 | field INP·라우트 전환 데이터가 생기면 lab 표본의 필요를 다시 본다 | +| 완료 기준 | `lab.json`에 기능 라우트 하나의 클릭 → heading 시간이 표본과 함께 있다 | +| 검증 방법 | 15-R1과 같은 방법(`scratchpad/r4/a15/r4-15-route-entry.mjs`). 기능 실행부에 지연 import 하나를 더하는 변이로 lab의 새 값이 느는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-05 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다. 게이트는 스크롤바를 숨긴 Chromium으로만 재서 보지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 14, 10, 21 | +| 근거 | 2.2절의 12 px 성장(로딩 화면 → 홈, 문서 720 → 732 px)이 원인이다. 15-R2(Chromium 151, `ignoreDefaultArgs: ["--hide-scrollbars"]`, preview, 창 셋 × 지연 없음·lab 조건 × 3회): 1280×720에서 `clientWidth` 1280 → 1265, `div.app-shell__session` x 802 → 787, layout shift 1건 0.00023(6/6). 1366×657에서 1366 → 1351, x 888 → 873, 0.00022(6/6). 1920×960은 홈이 창 안이라 0(6/6). shift 시각은 홈이 그려지는 프레임(지연 없음 400~414 ms, lab 조건 1,997~2,031 ms)과 같다. `html`·`body`에 `scrollbar-gutter`나 `overflow-y` 지정이 없다(`src/presentation/styles/theme/base.css:1-71`). lab은 Playwright 기본 실행이라 스크롤바를 숨긴다(`scripts/test-performance.ts:186`, `chromium.launch()`). 게이트의 다른 Playwright 설정도 같다 | +| 발생 조건 | 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 창 높이가 홈 내용(732 px)보다 낮을 때 첫 화면. Windows와 많은 Linux 데스크톱의 기본값이다. 다른 화면도 로딩 화면이 창 안에 들고 내용이 창보다 길면 같다(재지 않음) | +| 영향 | 첫 화면이 그려지는 순간 header 오른쪽(테마·언어 선택, 세션 상태, 로그인 버튼)이 15 px 왼쪽으로 움직인다. CLS 0.0002는 예산의 0.2%다. 게이트가 이 종류의 shift를 볼 방법이 없다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 목표 M3(첫 화면 shift를 실제 브라우저 조건으로 검출) / 확인 M0(스크롤바 조건) · E3(18회) | +| 확실성과 남은 가정 | Chromium Linux의 15 px 스크롤바만 쟀다. Windows 스크롤바 폭(약 17 px)과 Firefox는 재지 않았다. macOS 기본 overlay 스크롤바에서는 나지 않을 것으로 본다(추론) | +| 결정의 근거 | 적용 제외 — 스크롤바 자리를 미리 잡는 CSS 한 줄로 끝나는 표시 결함이다 | +| 이해 비용 | 낮다 | +| 최소 개선 방향 | `html { scrollbar-gutter: stable; }`(base.css). lab은 스크롤바를 켠 실행(`--hide-scrollbars` 제외)으로 바꾸거나 한 표본을 더한다 | +| 대안 비교 | 적용 제외 — 대안(`overflow-y: scroll`)은 항상 스크롤바를 그려 짧은 화면에서도 보인다. 차이가 작아 비교하지 않는다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 스크롤바 폭만큼 오른쪽 여백이 늘 생긴다(내용이 짧아도). 시각 골든(`tests/visual/`)은 스크롤바를 숨긴 실행이라 바뀌지 않을 것으로 본다(미확인) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 15-R2와 같은 실행에서 1280×720·1366×657의 layout shift가 0건이다 | +| 검증 방법 | `scratchpad/r4/a15/r4-15-scrollbar.mjs` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 28개 관점 판정 (36.2) + +표기: O 충족 / P 부분 충족 / X 미충족 / ? 미검증 / - 적용 제외 / > 다른 영역. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | 일부 적용(성능 스크립트) | M2 / M2 | E1, E2(게이트 로그) | **O** — 판정기(`performance-budgets.ts`)와 CLI가 나뉘고, 실패 출력이 넘은 한도를 말한다. 측정 스크립트들의 이 영역 테스트 6개가 통과한다(`gates/test_unit.log`) | +| 2 | 구조적 성숙도 | 일부 적용(청크 구성) | M3 / M3 | E3 | **O** — react-dom 그룹, `feature-declarations`·`feature-platform` 그룹. 생성 기능 하나를 더해도 초기 파일 26개 그대로(15-feature) | +| 3 | 변경 용이성 | 적용 | — / — | E3 | **P** — 생성 기능 하나는 예산 수정 없이 들어간다. 둘째는 예산 결정이 필요하다(2.1절). 빌드 입력 목록 두 벌(15-03) | +| 4 | 인지 부하 | 적용 | M1 / M1 | E1 | **P** — 기준선이 한 곳(`initialJavascript`)이 됐다. CHANGELOG의 파일 예산 26은 틀렸다(1103/15-02 일부). lab CLS 0의 뜻을 알려면 500 ms 입력 규칙을 알아야 한다(15-01) | +| 5 | 위험 가시성 | 적용 | M3 / M2 | E3 | **P** — lab 실패는 고쳐졌지만 여전히 release 단계에서만 돈다. lab CLS가 `/` 밖을 보지 않는다(15-01). 기록 오차가 여유보다 크다(15-02) | +| 6 | 실패 성숙도 | 다른 영역(06·09) | — | — | **>** 부트 실패 화면 청크는 react-dom과 분리된 뒤에도 앱 그래프 없이 그려진다는 주장(`af6d0a9` 본문)은 영역 09·13 | +| 7 | 운영 성숙도 | 일부 적용 | M2 / M2 | E3 | **P** — `lab.json`에 CPU·부하·표본·클릭 이벤트 길이가 남는다. field는 설계대로 `FAIL_UNVERIFIED` | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E1, E2 | **O** — `check:bundle`이 측정값·한도·초과량을 쓴다(1103/15-03 고쳐짐). 기능당 비용 실패가 잰 값을 말한다 | +| 9 | 유지보수 성숙도 | 적용 | M3 / M2 | E1 | **P** — 기록과 빌드를 대조하지만 오차가 크고(15-02), CHANGELOG 숫자는 손으로 적혀 이미 틀렸다(1103/15-02). 목록 두 벌(15-03) | +| 10 | 테스트 성숙도 (깊게) | 적용 | M3 / M3 | E2, E3 | **P** — 이 영역 테스트는 merge에서 돌고 통과한다(feature-shape-growth 7건 5.3초, check-bundle-output 5건, build-environment-bundle 2건). lab은 대상 화면의 CLS를 볼 수 없고(15-01), 기능 라우트를 재지 않으며(15-04), 스크롤바를 숨긴 조건만 잰다(15-05). 빠른 계층 시간은 그대로다: unit 194파일 2,883건 22.6초, 파일 setup 합 44초(1101/15-04 남음) | +| 11 | 데이터 성숙도 | 적용 제외 | — | — | **-** 이 영역에 저장 데이터가 없다 | +| 12 | 동시성 성숙도 | 다른 영역(03·05) | — | — | **>** | +| 13 | 확장성 (깊게) | 적용 | M3 / M3(초기 JS) | E3 | **P** — 생성 기능 하나 +976 B, 파일 증가 0, lazy +12파일. lab 대상 화면은 기능 수와 거의 무관하다(146 → 154 ms). 여유로는 기능 하나 남짓이다 | +| 14 | 성능 성숙도 (깊게) | 적용 | M3 / 번들 M3(merge), lab M3(release, `/`와 대상 화면 하나) | E3 | **P** — 초기 JS 99.1%, lab PASS(146 ms, LCP 2,032, CLS 0). 12 px 성장은 shift가 아니다(2.2절). 대상 화면 deep link CLS 0.0046(15-01). 기능 라우트 진입 406 ms, 게이트 없음(15-04). 실제 스크롤바에서 홈 첫 렌더 CLS 0.0002(15-05). CSS 예산 없음(1101/15-03). field 미검증 | +| 15 | 보안 성숙도 | 다른 영역(13) | — | — | **>** zod advisory를 고치는 버전이 초기 JS 약 +7 KB라 예산을 넘는다는 주장(`CHANGELOG.md:271`)은 13-03 결정 대기. 이 영역은 재지 않았다 | +| 16 | 의존성 성숙도 | 일부 적용 | M2 / M3 | E2, E3 | **O** — react-router 운영 빌드(1103/15-07). 업그레이드로 경로가 바뀌면 빌드가 멈춘다(`vite.config.ts:163-168`) | +| 17 | API / Contract 성숙도 | 다른 영역(07) | — | — | **>** | +| 18 | 배포 성숙도 | 적용 | M3 / M3 | E3 | **O** — release 단계 lab 게이트가 통과한다. build id만 바뀐 release에서 react-dom 청크 이름이 유지된다(테스트 존재, 바이트 비교는 미검증). HTTP/2 전제는 production probe(13-02, 영역 13) | +| 19 | 설정 성숙도 | 적용 | M2 / M2 | E1 | **O** — 예산은 `budgets.json` 한 곳, 기준선은 `feature-shape-ceilings.json` 한 곳 | +| 20 | 개발자 경험 (깊게) | 적용 | M2 / M2 | E3 | **P** — 생성 명령이 기록 재작성을 안내한다(`Next:` 3번). 예산 실패 메시지가 원인을 말한다. CHANGELOG 이행 7번의 파일 예산 숫자가 틀렸다 | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3(번들 merge), lab은 release만 | E3 | **P** — 상한 25 → 26 → 32는 근거가 있고 템플릿 쪽은 기록의 `files`가 정확히 막는다(2.1절). 기록 오차 1%(15-02), lab의 CLS·라우트·스크롤바 범위(15-01, 15-04, 15-05) | +| 22 | 추상화 성숙도 | 다른 영역(16) | — | — | **>** | +| 23 | 일관성 | 일부 적용 | — | E1 | **P** — 같은 목록 두 벌(15-03). dev와 build가 다른 라우터 빌드를 쓰는 것은 의도이고 주석이 있다(`vite.config.ts:179`) | +| 24 | 네이밍 / 의미 성숙도 | 일부 적용 | — | E3 | **P** — react-router 청크는 여전히 자동 이름(`chunk-3WDNQUW5`)이다. 문서는 "청크 이름으로 판단하지 않는다"고 적는다(`performance-evidence.md:42`) | +| 25 | 조직 확장성 | 다른 영역(12) | — | — | **>** | +| 26 | Ownership 성숙도 | 다른 영역(14) | — | — | **>** 예산 결정은 다운스트림 몫이라고 문서에 있다(`performance-evidence.md:17-20`) | +| 27 | 삭제 가능성 | 다른 영역(14) | — | — | **>** lab 대상이 끌 수 없는 플랫폼 라우트다(09-04 결정 대기) | +| 28 | 회복 가능성 | 다른 영역(06) | — | — | **>** | + +## 5. 미검증 + +| 범위 | 이유 | 확인 방법 | +|---|---|---| +| 기능 라우트 진입 406 ms의 구성(왕복·다운로드·렌더) | 15-R1은 합계와 요청 시각만 남긴다 | CDP trace 또는 CPU throttle 없이 다시 잼 | +| 생성 기능 라우트의 첫 진입 | 세션과 백엔드 응답이 필요하다 | MSW나 짝 백엔드를 붙인 lab | +| 스크롤바 shift의 Firefox·Windows 조건 | 15-R2는 Linux Chromium만이다 | — | +| `d99301b`와의 lab A/B | 이번 brief는 lab 1회만 요구한다. 수정 커밋 `d549ceb` 본문의 A/B만 있다 | 지난 라운드 6절 방법 | +| build id만 다른 두 빌드의 바뀐 초기 JS(44,297 B 주장) | 두 build id 빌드를 비교하지 않았다. 이름 유지는 테스트가 본다 | `VITE_BUILD_ID`만 다른 두 빌드 | +| 예산을 넘는 실제 빌드의 `check:bundle` 출력 | 넘는 빌드를 만들지 않았다. fixture 테스트는 게이트 로그에서 통과 | 기능 둘을 더한 빌드 | +| 기능 둘째의 비용과 남는 여유 | 하나만 더했다 | 같은 context·새 context로 하나씩 | +| CI env(`CI=true`, CI build id)에서의 lab | 로컬 env로만 돌렸다. merge-48에는 FE-GATE-026이 없다(release 단계) | `CIENV=1` lab 1회 | +| firefox·webkit의 lab 수치 | lab은 Chromium만이다. 두 엔진에는 `layout-shift` API도 없다 | — | +| 11-10 실패 run의 클릭 시각 | 재현 run을 다시 돌리지 않았다. firefox에서만 겹친 이유는 시각표로 한 추론이다 | 진단 branch의 event 기록에 `performance.now()` 추가 | +| 다른 capability spec이 body에 요소를 붙이지 않는다는 주장 | 11-10 수정 커밋 본문의 grep 주장이다. 영역 11 | `git grep "document.body.append" tests/` | +| field CLS·INP | 입력이 없다(설계대로 `FAIL_UNVERIFIED`) | — | +| 오케스트레이터 merge-48의 FE-GATE-012 결과 | 이 문서를 쓸 때 001~004·020만 끝나 있었다 | `merge-48/FE-GATE-012.log` | + +## 6. 실행 기록 + +모든 실행은 desktop에서 helper로 했다. 바이트는 `check:bundle`과 같은 계산이다(`classifyViteJavascript` + Node `gzipSync` 기본 수준). 부하는 1분 loadavg다. 측정 스크립트(`r4-15-*.mjs`)는 리뷰어 scratchpad `r4/a15/`에 있다(커밋하지 않음). + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 | +|---|---|---|---|---|---|---| +| `15-lab` | `pnpm build` → `pnpm check:bundle` → `r4-15-summary.mjs bundle` → `pnpm test:performance -- --runs=5` → `r4-15-summary.mjs lab` | 측정 스크립트 복사만 | 0(19초) | `Bundle budget: PASS (initial JS 202927 / 204800 gzip bytes, 26 / 32 files)`. lazy 27파일 38,880 B(최대 8,566), CSS 8,791 B. 초기 파일: react-dom 56,515, feature-platform 39,297, boot 39,067, react-router(`chunk-3WDNQUW5`) 30,157, i18n 7,957, server-state-scope-provider 6,171, render-boot-failure 4,280, feature-declarations 3,256, react 3,157, 그 밖 17개 13,070. `Lab performance: PASS, median of 5 (LCP 2032ms, CLS 0, interaction 146ms [143-155])`, 표본 155·146·143·148·146, LCP 2,036·2,032·2,032·2,028·2,020, 클릭 event 16~24 ms. `restored: clean at 8a442262` | 435초 | 시작 6.51, lab 전후 6.06 → 5.01 | +| `15-growth` | `pnpm build` → `r4-15-growth-probe.mjs preview 3` → `r4-15-growth-probe.mjs dev 3` | 측정 스크립트 복사만 | 0(111초) | 2.2절. preview: chromium 5회(ResizeObserver 3·무계측 2) + lab 조건 3회, firefox 3회, webkit 3회. dev: 세 엔진 warm-up 1회 + 3회, chromium 무계측 2회. 모든 run에서 문서 720 → 732, 홈이 로딩 화면을 대신하는 프레임 하나. Chromium shift: preview 0건(8회), dev 매번 1건 0.00625(부팅 셸 스타일). 상세 `desktop:/tmp/claude-gates/r4/exp/15-growth-{preview,dev}.json`. `restored: clean at 8a442262` | 453초 | 5.01 → 2.96(preview), 2.75(dev 끝) | +| `15-feature` | `pnpm create:feature bulletin-feature --with-create --keyed` → `pnpm build` → `pnpm check:bundle` → 요약 → `pnpm test:performance -- --runs=5` → 요약 | 생성 명령(`git status --short` 9줄) | 0(20초) | `initial JS 203903 / 204800 gzip bytes, 26 / 32 files`(+976 B, 여유 897 B). lazy 39파일 46,552 B. `Lab performance: PASS ... (LCP 2020ms, CLS 0, interaction 154ms [147-158])`. `restored: clean at 8a442262` | 559초 | 2.75, lab 전후 2.69 → 2.16 | +| `15-platform-shift` | `pnpm build` → `r4-15-platform-shift.mjs 3` | 측정 스크립트 복사만 | 0(94초) | 15-01 근거. 지연 없음·lab·Fast 3G × 클릭·deep link, 16회 모두 shift 1건 0.00461. 셈에 들어간 것: deep link 8/8, Fast 3G 클릭 3/3, 나머지 클릭 0/5(입력 창). `restored: clean at 8a442262` | 722초 | 6.80 → 2.58 | +| `15-R1`(배치, 오케스트레이터) | `pnpm build` → `r4-15-route-entry.mjs 5` | 측정 스크립트 복사만 | 0(43초) | lab 조건, 번갈아 5회. `SUMMARY EXAMPLES_PLATFORM median 148 samples 144,146,148,150,150`, `SUMMARY EXAMPLES_UI median 406 samples 403,405,406,406,410`. 플랫폼: 제목 전 4파일 7,037 B, 제목 뒤 6파일(`installed-feature-runtime-registries` 130 ms~, `feature-runtime`·`reference-*` 233 ms~). 기능 라우트: 39~95 ms `context-routes` 830 B·`feature-runtime` 177 B, 98~204 ms `ui-gallery-page` 5,893 B·공유 셋 1,299 B. restore clean. 처음 요청한 `15-route-entry`는 helper가 닫히며 시작 전에 취소됐다 | 배치 | 3.00 → 2.14 | +| `15-R2`(배치, 오케스트레이터) | `r4-15-scrollbar.mjs 3`(15-R1이 만든 `dist/` 재사용, 로그에 `reuse-dist-from-15-R1`) | 측정 스크립트 복사만 | 0(54초) | 15-05 근거. 1280×720 6/6 shift 0.00023, 1366×657 6/6 0.00022, 1920×960 6/6 0. restore clean. 처음 요청한 `15-scrollbar`는 시작 전에 취소됐다 | 배치 | 2.14 → 1.30 | + +오케스트레이터 게이트 결과(인용, 이 문서를 쓸 때 채워지는 중): `gates/summary.txt`에서 `test:unit rc=0 25s load 3.24`. 그 로그의 끝은 194파일 2,883건 통과, Duration 22.61초(setup 합 43.97초, tests 합 130.90초)다. 이 영역 파일: `feature-shape-growth` 7건 5,317 ms, `build-environment-bundle` 2건 3,791 ms, `check-bundle-output` 5건 3,183 ms, `product-feature-selection-build` 1건 1,494 ms, `lab-performance` 5건 977 ms, `performance-budgets` 3건 9 ms. 가장 느린 unit 파일은 `documentation-readiness` 17.0초, `product-extension-typecheck` 11.0초, `ci-workflow-generation` 7.5초, `security-promotion-staging` 6.7초, `service-worker-build-output` 6.3초, `risk-coverage` 6.1초다. `merge-48/summary.txt`는 FE-GATE-020 rc=0 1,156초, 001 rc=0 579초, 002·003 rc=0이었다. FE-GATE-012는 아직 없었다. + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 15-01 | Low·P3 | 확인된 결함 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다(shift 0.0046). lab은 클릭 입력 창이라 0을 내고 `/` 밖의 CLS는 아무도 보지 않는다 | `src/presentation/examples/platform-overview-page.tsx:422-454`, `scripts/test-performance.ts:111-118`, `:148-152` | +| 15-02 | Low·P3 | 구조적 위험 | 초기 JS 기록 대조 허용 오차 1%(2,029 B)가 남은 여유(1,873 B)보다 크다 | `scripts/scale/measure-feature-shape-growth.ts:227-246` | +| 15-03 | Low·P3 | 구조적 위험 | 측정용 빌드 입력 목록이 두 파일에 같은 내용으로 있다 | `scripts/scale/measure-feature-shape-growth.ts:40-49`, `tests/unit/product-feature-selection-build.test.ts:22-31` | +| 15-04 | Low·P2 | 구조적 위험 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 lab 조건 406 ms(요청 두 묶음)인데 어느 게이트도 재지 않는다 | `scripts/test-performance.ts:46`, `src/presentation/routes/app-router.tsx:510-538`, `CHANGELOG.md:269` | +| 15-05 | Low·P3 | 확인된 결함 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다(CLS 0.0002). 게이트는 스크롤바를 숨긴 Chromium이라 못 본다 | `src/presentation/styles/theme/base.css:1-71`, `scripts/test-performance.ts:186` | diff --git a/docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md b/docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md new file mode 100644 index 00000000..74951997 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/16-structure-patterns.md @@ -0,0 +1,276 @@ +# 영역 16 — 폴더 구조·리팩토링·기능 개발 패턴 + +> 검토일 2026-11-05 · 기준 `8a44226`(`fix/maturity-review-2026-11-03`) · 가이드 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: repo 구조 전체, `src/features/reference-feature/`, `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `docs/manual/`, `docs/architecture/` +> 깊게 본 관점: 2, 3, 4, 9, 22, 23, 24, 27 +> 렌즈: 템플릿의 핵심 약속 — 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 고치지 않고, merge 게이트를 통과한다. 매뉴얼의 예시 이름 그대로 `create:feature invoice-feature --with-create --keyed`(새 context)를 만들었다. 한 번은 지난 라운드 변이를 다시 넣었고(`16-mut`), 한 번은 CI가 생성 기능으로 돌지 않는 단계(브라우저 게이트, 11단계 제거 드릴, 둘째 기능의 예산)를 돌렸다(배치 16-R1). +> 영역 판정(35.8): **조건부 사용 가능.** 생성 명령 하나로 만든 쓰기 기능이 손 수정 없이 merge 명령을 통과한다. 비브라우저 명령은 오케스트레이터 merge-48 FE-GATE-020(`feature scaffold: PASS (77 checks)`), 브라우저 게이트는 16-R1(FE-GATE-008·009 rc=0, workflow env)에서 봤다. 지난 라운드 16 발견 9건 중 6건이 고쳐졌고 3건이 일부 남았다. 조건은 다섯이다. (1) 생성 명령이 다시 쓴 `public/release-manifest.json`과(참조 기능이 있는 동안) 초기 JS 기록을 기능과 함께 커밋한다. 병렬 기능 브랜치는 이 줄에서 충돌한다(16-01). (2) 매뉴얼 예시 이름(`invoice-feature`, `notice-feature`)이나 템플릿 테스트에 나오는 이름(`orders-feature`, `shop-feature` 등)으로 기능을 만들지 않는다. 11단계 제거 드릴이 템플릿 테스트의 글자를 잔여로 잡아 실패한다(16-04). (3) 쓰기 기능 셋째부터는 예산 결정이 먼저다. 둘을 더하면 초기 JS 여유가 277 B다(16-R1, 1101/15-01). (4) 템플릿 변경이 생성 기능의 브라우저 경로를 깨도 CI는 모른다(16-03). (5) 뮤테이션 정책 ID는 `commandMutationIdentity`로 받고, 읽기만 있는 계약 기여에서는 생성된 gateway 테스트를 지우지 않는다(1103/16-05·16-01 일부). + +## 0. 결론 + +- **지난 16 발견 9건: 고쳐짐 6, 일부 3.** 고쳐짐: 16-02(제품 기능 제거 드릴), 16-03 앞부분(접근성 spec 기능별 수정), 16-04(스키마 메타 설명 칸), 16-07(KEYED 쓰기 값), 16-08(낡은 문장 다섯), 16-09(dev server 부팅). 일부: 16-01(Envelope 누락), 16-05(뮤테이션 ID), 16-06(읽지 않는 칸). 틀린 발견은 없다. 1101·0929 이월 셋(16-05, 16-06, 12-03)은 그대로 남았다. +- **변이로 확인한 것(`16-mut`, restored clean).** 생성 기능에서 `responseEnvelope` 줄 하나를 지우자 계약 조립이 operation 이름과 고칠 방법을 말하며 거절했다. `check:registries` rc=1, 기능 테스트 4파일 실패. 세 줄을 다 지워도 쓰기의 `refusedBeforeWrite`가 Envelope를 요구해 조립이 거절했다. `check:types`는 rc=0이었다. 스키마 메타 세 변이(`direction`, `boundary`, `unknownFieldPolicy`)는 각각 `tests/unit/schema-metadata-policy.test.ts`가 잡았다. 셋 다 `check:registries`는 통과했다. +- **매뉴얼을 글자 그대로 따르면 마지막 단계에서 막힌다(16-04, Low·P2).** `create:feature invoice-feature`(01:94) 뒤 11단계 `test:sample-removal -- --feature=invoice-feature`(01:626)가 rc=1로 끝났다(16-R1, 198초). 타입·테스트·커버리지·CI 계약·빌드 검사는 모두 통과했다. 실패는 잔여 검사 하나였다: `fixture-id-residue: residue: tests/unit/create-feature.test.ts`. 그 템플릿 테스트가 예시 ID `invoice-feature`를 53번 쓴다. 잔여 검사는 기능 ID를 `src`·`tests` 전체에서 대소문자 무시 부분 문자열로 찾는다(`scripts/test-sample-removal.ts:113-120`, `:417-425`). 오류 안내는 "그 파일을 고친다"다(`docs/manual/reference/errors.md:197`). 그 파일은 템플릿 소유다. 지난 X2 #1(예시 이름 `notice-feature`와 타입 검사 탐침 충돌)과 같은 종류다. `notice-feature`도 지금 템플릿 테스트에 있다(`tests/unit/registry-governance.test.ts:637`). +- **템플릿 소유 파일을 손으로 고칠 곳은 없다(제거 드릴 실패 제외).** 다만 생성 명령이 추적 파일 `public/release-manifest.json`을 다시 쓴다(`setDigest`와 `packages` 줄). 참조 기능이 있는 동안은 `config/scale/feature-shape-ceilings.json`도 명령으로 다시 써야 한다. 03 문서와 정본 표는 이 둘을 말하지 않는다. 둘째 기능은 같은 `setDigest` 줄을 또 바꿨다(16-R1). 기능 브랜치 둘은 이 줄에서 충돌한다(16-01, Low·P2). +- **생성 기능을 설치하고 브라우저 게이트를 돌렸다(16-R1, workflow env).** FE-GATE-008 rc=0(e2e 211 통과·3 skip, capability 66, storybook 1, visual 6). dev server를 쓰는 capability e2e가 그대로 부팅했다(1103/16-09 고쳐짐). FE-GATE-009 rc=0(69 통과). 생성 라우트 셋이 세 엔진에서 spec 수정 없이 axe를 통과했다(1103/16-03 고쳐짐). 다만 CI는 이 상태를 돌지 않는다(16-03, Low·P2). +- **생성기의 쓰기 slice가 짝 백엔드의 기본 경로 예시가 됐다.** 지난 라운드 5.3절 권고 (c)가 들어왔다(`2ec9d56`). 대신 백엔드 생성기 템플릿의 사실 넷(경로 복수형, 이름 상한 100, 오류 code, 검사 순서)을 프론트 문자열로 옮겼다. 지금은 같다. 짝 계약 pin과 drift 검사는 `http-contract.md` 하나만 본다(16-02, Low·P3). +- **약해진 검사는 찾지 못했다.** 참조 라우팅 테스트를 참조 기능 라우트로 좁힌 것(`e8c4197`)은 테스트 대상이 같다. 초기 파일 상한 26 → 32(`2fef27d`, X2 #4)는 15 영역이 근거와 함께 판정했다. +- **이번 발견.** Low 4 · P2 3 · P3 1 · 구조적 위험 3 · 확인된 결함 1. 다른 영역과 같은 결함은 2.4절에 증거만 붙였다(15-03 `BUILD_INPUTS` 두 벌, 1101/15-01 초기 JS 여유, 11-01). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template` | +| 커밋·작업 상태·확인 시점 | `8a44226`. 코드 읽기는 노트북 worktree(HEAD = 기준, 읽기만). 실행은 desktop checkout(같은 커밋)에서 두 번: helper로 `16-mut`(19:41), 오케스트레이터 배치로 16-R1(20:15). 둘 다 restore clean. 2026-11-05 19:20~20:40 | +| 목적과 지원 실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 필수 요구와 규모·운영 목표 | 짝 백엔드(`clean-architecture-backend-template` `45d2a478`, 읽기만)와 짝으로 쓴다. 생성 명령과 매뉴얼로 기능을 더하고, 템플릿 소유 파일을 고치지 않고, merge 게이트를 통과한다. 기능 수 증가 외 정량 목표 없음 | +| 읽은 코드·구성 범위 | `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/removal-fixture.ts`, `scripts/write-dev-release-manifest.ts`, `scripts/scale/measure-feature-shape-growth.ts`, `scripts/check-backend-contract-drift.ts`, `tests/unit/{dev-release-manifest,feature-shape-growth,schema-metadata-policy,product-feature-selection-build,a11y-api-answers,product-extension-typecheck}.test.ts`, `tests/e2e/accessibility.spec.ts`, `tests/e2e/support/installed-api-answers.ts`, `src/contracts/external-contract-runtime.ts`(응답 모양 조립 검사), `src/contracts/server-state.ts`, `src/adapters/http/http-execution-v3.ts`(intent 검증), `src/adapters/http/http-effect-certainty.ts`, `docs/manual/` 전체, `docs/architecture/starter-experience.md` "Adding a feature", `docs/architecture/layers.md`, `public/release-manifest.json`, `config/scale/feature-shape-ceilings.json`, `config/contracts/backend-contract-pin.json`, `config/ci/gates.json`, `CHANGELOG.md` 미출시 절의 남은 것. 백엔드 `scripts/new-feature.sh`와 `scripts/feature-scaffold/templates/`의 create use case·controller·aggregate 템플릿. `git diff e40684b..8a44226`의 이 영역 경로 | +| 수행한 테스트·실험 | `16-mut`: 생성 1번, 변이 5개(6절). 16-R1(workflow env, 450초): 생성 1번 → `ci:gate FE-GATE-008`, `ci:gate FE-GATE-009` → 11단계 `test:sample-removal -- --feature=invoice-feature` → 둘째 기능 `order-feature` 생성, manifest diff, `build`, `check:bundle`. 오케스트레이터 결과 인용: `merge-48/`(CI=true, FE-GATE-020·001~009 rc=0), `gates/`(로컬 env). 다른 영역 실행 인용: `15-lab`, `15-feature`, `11-R8b`, `12-R3`(같은 커밋, restore clean) | +| 확인하지 못한 범위·이유 | FE-GATE-013, 실제 Gitea 러너, 실제 짝 백엔드 연결, 두 브랜치의 실제 `git merge`, 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식)은 하지 않았다(5절). 생성 기능 설치 상태의 FE-GATE-001~007·010~012는 다시 돌리지 않고 merge-48 FE-GATE-020의 생성 드릴(같은 명령, `--with-create --keyed` 기능)을 인용했다 | +| 이전 리뷰와 비교 가능한 범위 | `docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md`의 16-01~16-08, README §13의 16-09, §10.3에서 11-01로 합친 16-03 뒷부분, 지난 영역 문서 2절의 "남음" 이월, README §14.6 X2 막힘 7건, §14.7 남은 문제. 지난 실행 결과는 증거로 쓰지 않았다 | +| 실행 중 부하 | 리뷰어 15명과 게이트 실행이 잠금 하나를 나눠 썼다. `16-mut`은 잠금을 579초 기다렸고 시작 부하 2.16이었다. 16-R1은 시작 부하 3.26, FE-GATE-008 중 14.09였다. 이 영역 결론은 실행 시간에 기대지 않는다 | + +## 2. 지난 발견 재확인 + +README §14.4의 상태는 주장으로 보고, 이번 커밋의 코드와 `16-mut`·16-R1로 다시 판정했다. + +### 2.1 1103 영역 16 발견 (README §12·§13, §10.3 합친 것 포함) + +| 지난 ID | 내용 | 상태 | 근거 (`8a44226`) | +|---|---|---|---| +| 1103/16-01 | Envelope를 operation마다 선언하고, 빠뜨려도 게이트와 MSW 시나리오 테스트가 통과한다 | **일부** | 고친 것: 계약 조립이 한 기여 안에서 응답 모양이 다른 operation을 거절한다(`src/contracts/external-contract-runtime.ts:655-669`, 호출 `:1031`). 쓰기의 `refusedBeforeWrite`는 Envelope를 요구한다(`:627-629`). 생성기는 모든 operation에 줄을 쓴다(`scripts/create-feature-write-slice.ts:269`, `:323`). `16-mut` M1(줄 하나 삭제): `check:registries` rc=1, `invoice-feature/INVOICE_GET_ITEM: responseEnvelope NONE, but INVOICE_LIST_ITEMS in the same contribution reads ENVELOPE_V1; ...`, 기능 테스트 4파일 실패. M2(세 줄 모두 삭제): `check:types` rc=0, `check:registries` rc=1(`INVOICE_CREATE_ITEM: refusedBeforeWrite needs responseEnvelope ENVELOPE_V1`), gateway 테스트 11건이 `SCHEMA_MISMATCH`로 실패. 남은 것: 읽기만 있는 기여(기본 생성 판)나 `refusedBeforeWrite` 없는 쓰기에서 줄을 모두 빼면 조립은 통과하고 손글씨 gateway 테스트만 잡는다(코드 추론, 실행 안 함). 매뉴얼이 "못 잡음"으로 적는다(`docs/manual/01-add-a-feature.md:213`). 지난 완료 기준("줄을 지우면 `check:types` 실패")은 충족하지 않았다. 지난 대안 (d)를 고른 이유는 커밋 본문에 있다(`3f7e10c`) | +| 1103/16-02 | 제품 기능 제거 드릴이 시작 3초 만에 CI 기준선 오류로 끝난다 | **고쳐짐** | 빈 목록 사유(`scripts/lib/removal-fixture.ts:468-476`). 이 길을 merge 게이트가 돈다: `test:feature-scaffold`가 생성 기능을 `--feature`로 지운다(`scripts/test-feature-scaffold.ts:104`). 오케스트레이터 merge-48 FE-GATE-020 rc=0(1,156초, CI=true): `scaffold-feature removal: PASS (17 checks, no fixture IDs)`. 16-R1의 `invoice-feature`(`--with-create --keyed`) 제거는 기준선·타입·테스트·커버리지(`Risk coverage: PASS`)·CI 계약 검사를 모두 통과하고 잔여 검사에서만 실패했다. 원인은 다른 결함이다(새 16-04: 잔여 검사가 템플릿 테스트의 예시 이름을 잡는다). 이 발견의 원인(빈 사유)은 다시 나오지 않았다 | +| 1103/16-03 | 공유 접근성 spec이 기능마다 수정을 요구하고, Envelope 기능에는 오류 화면만 검사한다 | **고쳐짐(앞부분)**. 뒷부분은 11-01로 합침 | 경로 파라미터를 이름과 상관없이 `a11y-1`로 바꾼다(`tests/e2e/accessibility.spec.ts:30-38`). API 답은 설치된 descriptor에서 만든다(`tests/e2e/support/installed-api-answers.ts:35-63`). 그래서 기능을 더해도 spec을 고치지 않는다. 상세 라우트는 실패 상태로 검사하고 annotation을 남긴다(`accessibility.spec.ts:72-82`, 매뉴얼 01:426). 16-R1: 생성 기능을 설치하고 spec을 고치지 않은 채 FE-GATE-009 rc=0. `/invoice`, `/invoice/items/a11y-1`, `/invoice/new`가 chromium·firefox·webkit에서 통과했고, `review:a11y-manual -- --format-only`는 `13 routes` PASS였다. 11-R8b(11 영역): 생성 목록 페이지의 빈 상태에만 이름 없는 button을 넣자 `/sample`만 세 엔진에서 실패했다. 목록 라우트가 빈 상태로 axe 검사된다는 뜻이다 | +| 1103/16-04 | 스키마 메타 행을 손으로 다시 적고, 틀려도 아무 검사가 잡지 않는다 | **고쳐짐** | `tests/unit/schema-metadata-policy.test.ts:126-171`이 `boundary`·`direction`·`unknownFieldPolicy`를 설치된 descriptor·라우트·zod 검증기와 대조한다(`test:unit`, FE-GATE-005). 완료 기준("E-4 세 변이가 각각 실패")을 생성 기능으로 다시 했다(`16-mut` M3a~c): 셋 다 `check:registries` rc=0, 그 테스트가 각각 `InvoiceItemListPayload: row REQUEST, used as RESPONSE`, `row api-request, used as api-response`, `row STRIP_UNKNOWN, validator REJECT_UNKNOWN`으로 실패. 변이 전 같은 명령은 rc=0. 행은 여전히 손으로 쓴다(지난 대안 (c) 대조를 골랐다) | +| 1103/16-05 | 뮤테이션 정책 `operationId`가 자유 문자열이다 | **일부** | 고친 것: `commandMutationIdentity(_CONTRACT)`(`src/contracts/server-state.ts:281-300`)를 쓰기 slice(`scripts/create-feature-write-slice.ts:505`)와 참조 기능(`src/features/reference-feature/presentation/use-reference-feature.ts:60`)이 쓴다. 상수 이름 오타는 tsc가 잡는다. 남은 것: `BoundMutation.operationId`가 여전히 `string`이다(`server-state.ts:305`). 손으로 쓴 문자열의 오타는 통과한다(매뉴얼 01:492 "못 잡음"). 위반 이름도 그대로다. ID가 다르면 KEYED는 `MISSING_IDEMPOTENCY_KEY`, 키 없는 쓰기는 `UNEXPECTED_IDEMPOTENCY_KEY`다(`src/adapters/http/http-execution-v3.ts:491-498`) | +| 1103/16-06 | 반드시 채우는 칸 중 아무도 읽지 않는 칸이 있다 | **일부** | 쿼리 `owner`·`operationId`, 뮤테이션 `owner`는 `@deprecated` 선택 칸이 됐다(`server-state.ts:178-184`, `:308-311`). 생성기는 쿼리에 이 칸을 쓰지 않는다. 남은 것: 라우트 계약 `title`·`navigationLabel`은 화면이 읽지 않는데 생성기가 채운다(`scripts/create-feature.ts:582-583`, `scripts/create-feature-write-slice.ts:128-129`). 매뉴얼이 "화면이 읽지 않는다"고 적는다(01:402) — M1 | +| 1103/16-07 | 짝 백엔드 KEYED 쓰기 값 넷을 매뉴얼이 정하지 않는다 | **고쳐짐** | 02 결정표 3절이 NEVER·KEYED 두 경우의 값과 이유를 준다(`docs/manual/02-decision-tables.md:99-127`). `--keyed`가 같은 값을 쓴다(`scripts/create-feature-write-slice.ts:225-250`, `:291-307`). 호출 문맥 `intent`는 생성된 `CommandContext`가 필수로 받는다(01:326). 하네스 재시도 상한은 앱 기본값 2다(`scripts/create-feature.ts:1491-1497`). `classifyStatus`의 근거(401·403·429가 use case 전)는 백엔드 템플릿과 맞다(`Create__Feature__UseCase.java.tmpl`의 `@RequiresPermission`, 검사 뒤 `tx.inWrite`). `operationIdentityField`를 실행기가 읽지 않는 것은 1101/07-07(07 영역) 그대로다 | +| 1103/16-08 | 기능 추가 문서의 낡은 문장 다섯 | **고쳐짐** | ① 테스트 셋(01:35) ② 400 `VALIDATION_FAILED`(01:508) ③ `context-route-roots.test.ts`는 fixture만(01:78) ④ 인증 프로필 오타에 통과하는 게이트(01:296) ⑤ `NoRequest`(`docs/architecture/starter-experience.md:244-245`). 이 수정 뒤에 생긴 다른 낡은 문장은 새 16-01에 적었다 | +| 1103/16-09 | dev server가 고정된 contract set을 내주어 기능 추가 직후 `pnpm dev`가 부팅하지 못한다 | **고쳐짐**(방식이 새 16-01을 만듦) | `create:feature`가 생성 뒤 `scripts/write-dev-release-manifest.ts`를 돌린다(`scripts/create-feature.ts:1787-1796`). `16-mut`에서 `public/release-manifest.json`의 `packages`에 `@org-contracts/invoice`가 들어갔다. 낡으면 `tests/unit/dev-release-manifest.test.ts:17-27`이 다시 쓰는 명령을 말하며 실패한다(M3). 16-R1: 생성 기능을 설치한 채 FE-GATE-008 rc=0. dev server를 쓰는 capability e2e 66건이 세 엔진에서 통과했고 `Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)`였다. 지난 라운드의 38건 실패가 사라졌다 | + +### 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`, `src/application/ports/telemetry-port.ts:5`. 매뉴얼은 "쓰지 않는다"로만 막는다(01:334, `docs/manual/reference/patterns.md:128`) ③ `adapters` 두 뜻 ④ 폐기 재수출 `src/application/result.ts:9`. 넷 다 그대로다 | +| 1101/16-06 (R-8) | 기능 `contracts/`가 와이어 계약·문구·뷰 타입을 함께 담는다 | **남음** | 생성기가 `contracts/-message-catalog.ts`, `contracts/-mapper.ts`를 쓴다(`docs/manual/reference/create-feature.md:50-53`, `16-mut` 생성 목록) | +| 0929/12-03 | 기능 안 다섯 폴더 밖 폴더와 `contracts/`를 거친 어댑터 import에 규칙이 없다 | **남음** | `docs/architecture/layers.md`의 규칙 표에 기능 `contracts/`나 다른 폴더를 막는 행이 없다. 매뉴얼이 "못 잡음"으로 적는다(01:387) — M1. 12 영역 12-R3: 기능 안 `support/direct-http.ts`가 http 어댑터 barrel을 import하고 presentation이 그 파일을 import해도 `check:architecture` rc=0, eslint rc=0 | +| 0929/08-06 → 1103/16-06 | 라우트 이름이 계약과 catalog 두 곳 | **일부** | 위 1103/16-06 행 | +| README §14.7 | `BUILD_INPUTS` 두 벌 | **남음** | 15 영역이 새 1105/15-03으로 셌다. 이 영역은 세지 않는다(2.4절) | + +### 2.3 지난 라운드 X2 막힘 7건 (README §14.6) + +| # | 지난 막힘 | §14.6 주장 | 이번 확인 | +|---|---|---|---| +| 1 | 타입 검사 탐침이 매뉴얼 예시 이름(`notice-feature`)과 겹쳐 FE-GATE-005 실패 | 고침 `235143c` | 탐침 이름이 `typecheck-probe-*`다(`tests/unit/product-extension-typecheck.test.ts:85-86`). 생성 기능(`scaffold-*`)이 든 드릴의 FE-GATE-005 명령 통과(merge-48 FE-GATE-020). 그 탐침은 고쳐졌다. 같은 종류(매뉴얼 예시 이름이 템플릿 테스트와 겹침)가 제거 드릴에서 다시 나왔다: 새 16-04 | +| 2 | 초기 JS 기록을 다시 쓰면 제거 드릴이 실패, 안 쓰면 FE-GATE-005 실패 | 고침 `72c6e9d` | 드릴이 지운 뒤 기록을 다시 쓴다(`scripts/test-sample-removal.ts:399-413`). 생성 드릴도 다시 쓴다(`scripts/test-feature-scaffold.ts:72-91`). 둘 다 merge-48 FE-GATE-020에서 통과. 남은 것: 다운스트림이 이 추적 파일을 기능마다 커밋한다(16-01) | +| 3 | 기능 생성 직후 dev server가 `CONTRACT_SET_PACKAGE_MISSING` | 고침 `799ab7f`(16-09) | 생성 명령이 manifest를 다시 쓴다(`16-mut`, 16-R1 diff). 설치 상태에서 dev server capability e2e 66건 통과(16-R1 FE-GATE-008). 남은 것: 추적 파일 공유(16-01) | +| 4 | 검색 폼 예제가 초기 파일 상한 26을 넘김 | 고침 `2fef27d`(상한 32) | 상한을 올린 변경이다. 15 영역이 약해진 검사가 아니라고 판정했다(템플릿 자신의 파일 수는 기록이 정확히 막는다) | +| 5 | 매뉴얼이 "드릴은 `check:bundle`을 돌리지 않는다" | 고침 `72b8ab1` | 01:667, `docs/manual/reference/create-feature.md:164`가 "돈다"로 맞다 | +| 6 | 로컬 FE-GATE-013에 `VITE_COMMIT_SHA` 안내 없음 | 고침 `72b8ab1` | 01:669, 생성 출력(`scripts/create-feature.ts:1752`). 실행하지 않았다 | +| 7 | 깨끗한 base에서 FE-GATE-020 드릴 셋 실패 | 고침 | merge-48 FE-GATE-020 rc=0: optional-recipe·browser-file-storage·realtime 제거 PASS | + +이번 실행(`16-mut`, 16-R1)을 지난 X2와 같은 기준으로 세면 이렇다. + +| 셈 | 결과 | +|---|---| +| 손으로 고친 템플릿 파일 | 0개 | +| 생성 명령이 바꾼 추적 파일 | 1개(`public/release-manifest.json`). `Next:` 3번을 따르면 1개가 더 바뀐다(`config/scale/feature-shape-ceilings.json`, 16-R1은 이 단계를 생성 드릴에 맡기고 생략) | +| 원인을 모르는 실패 | 0건 | +| 매뉴얼대로 했는데 실패한 단계 | 1건: 11단계 제거 드릴(16-04). 문구는 원인 파일을 말한다. 고치라는 곳이 템플릿 소유 테스트라 매뉴얼로는 풀 수 없다. 다른 이름을 고르면 피한다 | +| merge 게이트 | 브라우저 둘(FE-GATE-008·009)은 16-R1에서 rc=0. 나머지는 merge-48 FE-GATE-020의 생성 드릴로 갈음 | + +지난 X2(막힘 7건, 91분 중 약 45분이 원인 추적)와 비교하면 생성 뒤 단계에서 막힌 곳은 1건이다. 다만 이번에는 3~8단계의 손 작업을 하지 않았으므로 같은 셈이 아니다(5절). + +### 2.4 다른 영역 발견에 이 영역이 더한 증거 + +같은 결함을 다시 세지 않는다. + +| 발견 | 이 영역이 더한 증거 | +|---|---| +| 1105/15-03 `BUILD_INPUTS` 두 벌 | 두 목록은 이번 라운드에 두 번 함께 고쳐졌다. `7f9a515`가 두 목록에 같은 줄을 더했고(본문: "두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 범위 밖"), `799ab7f`가 두 목록에서 그 줄을 뺐다. 한쪽만 고쳤을 때의 증상은 생성 명령 `Next:` 3번(초기 JS 기록)이 원인을 말하지 않는 `Could not resolve`로 실패하는 것이다(`7f9a515` 본문) | +| 1101/15-01 초기 JS 여유가 작다(15 영역 "남음") | 생성 명령의 약속 쪽에서 본 영향이다. 템플릿 202,927 B(`15-lab`). 쓰기 기능 하나(새 context) 203,903 B, 여유 897 B(`15-feature`, 로컬 env). 16-R1(workflow env): 쓰기 기능 둘(각각 새 context) 204,523 / 204,800 B, `Bundle budget: PASS`, 여유 **277 B**, 파일 26 / 32. 문서 작성 중 "둘째에서 넘는다"고 추론했으나 틀렸다. 둘째 기능은 약 620 B를 더했다(두 측정의 env와 기능 이름이 달라 대략이다). 셋째는 넘는다(추론: 둘째의 증가분이 남은 여유보다 크다). 넘으면 고를 길은 템플릿 소유 `config/performance/budgets.json` 수정, 참조 기능·예제 기능 제거, 기존 context에 넣기다. 매뉴얼은 "넘으면 예산을 올리기 전에 팀이 정한다"만 적는다(01:666). 03 문서는 `budgets.json`을 A~D 어디에도 두지 않는다 | +| 1103/16-03 뒷부분 → 11-01 | 16-R1 FE-GATE-009: 생성 목록 라우트 `/invoice`가 세 엔진에서 경고 상자 없이 axe를 통과했다(`accessibility.spec.ts:72-74`의 단언). 11-R8b가 빈 상태에 넣은 결함을 axe가 잡는 것을 보였다 | + +## 3. 이번 발견 (36.3) + +집계: Low 4 · P2 3 · P3 1 · 구조적 위험 3 · 확인된 결함 1. High 이상과 P1은 없다. + +| ID | 제목 | 성격 | 심각도·우선순위 | 관련 관점 | +|---|---|---|---|---| +| 16-01 | 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀌고, 문서는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | 구조적 위험 | Low · P2 | 25, 3, 9, 20, 23, 27 | +| 16-02 | 쓰기 slice가 짝 백엔드 생성기 템플릿의 사실을 손으로 옮겼는데, 짝 계약 pin은 `http-contract.md`만 대조한다 | 구조적 위험 | Low · P3 | 17, 9, 21, 23 | +| 16-03 | 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 | 구조적 위험 | Low · P2 | 10, 21, 20, 5 | +| 16-04 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트에 나오는 이름을 잔여로 잡아, 매뉴얼 예시 이름(`invoice-feature`)으로 만든 기능은 11단계가 실패한다 | 확인된 결함 | Low · P2 | 27, 20, 21, 24, 8 | + +### 16-01 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다 — 정본 표와 03 문서가 이를 말하지 않고, 기능 브랜치 둘이 같은 줄을 바꿔 충돌한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (문서 불일치 포함) | +| 관련 관점 | 25, 3, 9, 20, 23, 27 | +| 근거 | ① dev manifest: `create:feature`가 생성 뒤 `scripts/write-dev-release-manifest.ts`를 돌려 추적 파일 `public/release-manifest.json`의 `contractSet`을 다시 쓴다(`scripts/create-feature.ts:1787-1796`, `scripts/write-dev-release-manifest.ts:17-21`). 출력이 "commit it with the feature"라고 한다(`create-feature.ts:1754`). 1103/16-09를 고친 `799ab7f`의 방식이다. ② 초기 JS 기록: 참조 기능이 설치돼 있는 동안 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`를 명령으로 다시 써서 같은 커밋에 넣어야 한다(`create-feature.ts:1753`, 매뉴얼 01:668). 안 쓰면 `tests/unit/feature-shape-growth.test.ts:160-165`가 실패한다. ③ 실행 `16-mut`: 생성 직후 폴더 밖 변경은 새 파일 4개(context 선언, a11y 기록 3)와 수정 1개 `M public/release-manifest.json`이다. diff는 `setDigest` 한 줄(`sha256:ad6a…` → `sha256:d9af…`)과 `packages: []` → `@org-contracts/invoice` 항목이다. ④ 문서: 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘이다"(context 선언, a11y 기록)라고 적는다(`docs/manual/03-outside-feature-folder.md:22-30`). 03이 정본으로 가리키는 표(`docs/architecture/starter-experience.md:215-226`)에도 두 파일이 없다. 매뉴얼 01 1단계의 "명령이 하는 일"(01:99-107)은 manifest 재작성을 말하지 않는다. 03의 "기능을 지울 때"는 dev manifest만 말하고 초기 JS 기록은 말하지 않는다(03:185). ⑤ 충돌: `setDigest`는 설치된 패키지 집합 전체의 해시 한 줄이고 `packages`는 배열 하나다. 기능을 하나씩 더한 두 브랜치는 둘 다 이 줄을 다른 값으로 바꾼다. 초기 JS 기록의 `gzipBytes`도 그렇다. 16-R1에서 둘째 기능(`order-feature`)을 더하자 같은 `setDigest` 줄이 다시 바뀌었고(`sha256:d9af…` → `sha256:4a87…`), `packages` 배열 끝에 항목이 붙었다. ⑥ 다시 쓰기가 실패하면 명령은 만든 기능 파일을 지우지 않고 멈춘다(`create-feature.ts:1793-1796`). 생성기 거절 때는 지운다(`:1781-1785`) | +| 발생 조건 | 기능 브랜치 둘을 병렬로 만들어 합칠 때. 참조 기능이 남은 다운스트림이 초기 JS를 바꾸는 템플릿 변경을 받을 때(기록은 템플릿 변경마다 다시 찍힌다: `1b8cb12`, `f887817`). 03 문서나 정본 표만 보고 커밋할 파일을 고를 때 | +| 영향 | 병렬 기능 브랜치의 둘째 merge가 텍스트 충돌로 멈춘다. 손으로 합친 값이 틀리면 `test:unit`이 다시 쓰는 명령을 말하며 실패한다(`tests/unit/dev-release-manifest.test.ts:23-26`). 사용자 피해와 데이터 위험은 없다. 지난 라운드 강점 "기능 하나가 템플릿 소유 파일을 건드리지 않는다"(1103 6.5절)가 이제 "손으로는 건드리지 않는다"로 줄었다 | +| 심각도·우선순위 | Low · P2 — 피해가 없고 낡은 값은 검사가 잡는다. 다만 기능이 늘 때마다, 브랜치가 둘 이상일 때마다 반복되는 비용이고 문서가 그 처리를 말하지 않는다 | +| 통제·증거 | 목표 M3(낡은 값 검출) + 기능마다 바뀌는 공유 줄 없음. 확인 M3(두 test:unit 검사) · 문서 M0(03 A절·정본 표에 없음) · E3(`16-mut`, 16-R1 둘째 기능 diff) | +| 확실성과 남은 가정 | 파일이 바뀌는 것은 실행으로 봤다. 두 브랜치 merge 충돌은 실제 `git merge`로 재현하지 않았다. 같은 JSON 줄을 두 브랜치가 다른 값으로 바꾸는 구조에서 판단했다(추론, 확실성 높음) | +| 결정의 근거 | 확인한 사실: dev 전용 미들웨어(서빙 중에 설치된 기능으로 manifest를 냄)는 capability e2e를 불안정하게 만들어 지웠다(`799ab7f` 본문, 1103 README §14.5 7회차). 커밋은 "레지스트리 기준선과 같은 방식"이라고 적는다. 리뷰어 추론: 레지스트리 기준선은 더하기만 하는 기능에서는 바뀌지 않게 설계됐다(03:122). dev manifest와 초기 JS 기록은 기능마다 바뀐다. 같은 방식이 아니다 | +| 이해 비용 | 기능 작성자가 출력 `Next:` 3번과 마지막 줄을 읽어야 두 파일을 안다. 03 문서·정본 표만 보는 사람은 모른다. 충돌하면 어느 명령으로 다시 만드는지는 test:unit 실패 문구에만 있다 | +| 최소 개선 방향 | (1) 03 A절, 정본 표, 01 1단계 흐름에 두 파일을 적는다: 누가 쓰나, 언제 커밋하나, 충돌하면 어느 명령으로 다시 만드나. (2) 충돌 자체를 없애려면 아래 (b)·(d) | +| 대안 비교 | (a) 현상 유지 + 문서: 가장 싸다. 충돌은 남는다. (b) dev manifest를 생성 파일로 두고(`.gitignore`) `dev` 스크립트와 dev server를 쓰는 Playwright 설정 앞에서 만든다(`generate:feature-index`처럼): 커밋 줄이 사라진다. 서빙 중이 아니라 시작 전에 쓰므로 미들웨어의 불안정과 다르다. (c) dev 부팅에서 contract set 검사를 끈다: `799ab7f`가 버린 대안이다(검사 조건이 dev만 달라진다). (d) 초기 JS 기록은 템플릿 자신의 값만 담고, 대조할 때 설치된 제품 기능을 빼고 잰다: 다운스트림이 다시 찍지 않는다. (b)+(d) 권장. 빠르게는 (a) 먼저 | +| 단순화의 보존 조건 | dev server와 build가 같은 contract set 검사를 한다(`src/bootstrap/load-release-manifest.ts`). build의 manifest는 지금처럼 `scripts/generate-build-manifest.ts`에서 온다. 초기 JS 예산 검사(FE-GATE-012)와 기능당 1 KiB 상한은 그대로다 | +| 비용·부작용 | (b)는 `dev`와 Playwright webServer 명령 앞에 단계 하나, `tests/unit/dev-release-manifest.test.ts` 변경. (d)는 측정 스크립트 수정 | +| 재검토 조건 | dev server가 서빙 중에 contract set을 안정적으로 낼 수 있게 되면 (b) 대신 그쪽을 다시 본다 | +| 완료 기준 | 기능 하나를 더한 커밋에 템플릿 추적 파일이 없다. 또는 03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다 | +| 검증 방법 | `create:feature` 뒤 `git status --short`에서 폴더 밖 수정 파일을 센다. 기능을 하나씩 더한 두 브랜치를 합친다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음 | + +### 16-02 쓰기 slice가 짝 백엔드 생성기 템플릿의 사실을 손으로 옮겼는데, 짝 계약 pin은 `http-contract.md`만 대조한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (다른 repo의 사본, 지금은 같다) | +| 관련 관점 | 17, 9, 21, 23 | +| 근거 | `--with-create`(`2ec9d56`)가 백엔드 `scripts/new-feature.sh`와 `scripts/feature-scaffold/templates/`의 사실을 문자열로 옮겼다. ① 경로 복수형 규칙: 프론트 `scripts/create-feature.ts:126-134`, 백엔드 `scripts/new-feature.sh:58-63`. ② 이름 상한 100: 프론트 `scripts/create-feature-write-slice.ts:58-59`, 백엔드 `__Feature__.java.tmpl:17`. ③ code `_INVALID`·`_NOT_FOUND`: 프론트 `create-feature-write-slice.ts:83-84`, 백엔드 `__Feature__ControllerTest.java.tmpl:68, 91`, `__Feature__ErrorCode.java.tmpl:12`. ④ 201과 `refusedBeforeWrite`·`classifyStatus`의 근거(검사 순서): 프론트 `create-feature-write-slice.ts:291-307`, 백엔드 `__Feature__Controller.java.tmpl:58`, `Create__Feature__UseCase.java.tmpl`의 `handle`. 백엔드 `45d2a478`과 지금 모두 같다. 그러나 pin은 `docs/web/http-contract.md` 하나를 본다(`config/contracts/backend-contract-pin.json:6-7`). drift 검사도 그 파일의 diff만 본다(`scripts/check-backend-contract-drift.ts:40`, `:60`). 그 검사는 게이트 밖이다(`CHANGELOG.md:265`) | +| 발생 조건 | 백엔드가 생성기 템플릿(이름 규칙, 오류 code, 상한, use case 순서)을 바꿀 때 | +| 영향 | 생성 기능이 백엔드 생성 기능과 다른 경로·상한·code를 쓴다. 경로가 다르면 404다. code가 다르면 쓰기 전 거절이 결과 불명으로 간다(`refusedBeforeWrite`에 없는 code). 정확성은 결과 불명 쪽으로 안전하게 기운다 | +| 심각도·우선순위 | Low · P3 — 지금 갈라지지 않았고, 틀리면 안전한 쪽이다 | +| 통제·증거 | 목표 M3(백엔드 템플릿 변경 신호). 확인 M1(주석이 백엔드 파일을 가리킨다) · E1(두 repo 정적 대조) | +| 확실성과 남은 가정 | 네 사실이 같은 것은 두 repo를 읽어 확인했다. 백엔드가 이 템플릿을 얼마나 자주 바꾸는지는 보지 않았다 | +| 결정의 근거 | 확인한 사실: D6(1103 README §14.2)은 짝 계약 기준점을 "pin 파일 + 답 표 대조 + 로컬 drift 검사"로 정했고 범위는 `http-contract.md`였다. 쓰기 slice는 그 뒤에 들어왔다. 리뷰어 추론: pin의 `document`를 목록으로 넓히면 같은 장치로 덮인다 | +| 이해 비용 | 백엔드 생성기를 바꾸는 사람이 프론트 생성기의 네 곳을 알아야 한다 | +| 최소 개선 방향 | pin에 백엔드 생성기 템플릿 파일 넷을 비교 대상으로 더한다. drift 검사가 pin 뒤에 그 파일이 바뀌면 알린다 | +| 대안 비교 | (a) 현상 유지(주석만). (b) pin 대상 확대: 기존 장치 재사용, 파일 목록만 는다. (c) 백엔드가 생성기 사실을 JSON으로 내고 프론트가 읽는다: 두 repo 변경. (b) 권장 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 | +| 비용·부작용 | pin 몇 줄과 drift 검사의 파일 목록 처리 | +| 재검토 조건 | 백엔드 생성기가 계약 패키지(`@org-contracts/*`)를 내게 되면 그 패키지가 정본이 되고 이 사본은 사라진다 | +| 완료 기준 | 백엔드 생성기 템플릿의 네 사실 중 하나가 바뀌면 프론트 drift 검사가 알린다 | +| 검증 방법 | 백엔드 사본에서 `NAME_MAX_LENGTH`를 바꾸고 drift 검사를 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음 | + +### 16-03 생성 기능을 설치한 상태로 브라우저 merge 게이트를 도는 장치가 없다 — 지난 라운드 16-09도 이 틈에서 사람이 찾았다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (검사 공백) | +| 관련 관점 | 10, 21, 20, 5 | +| 근거 | ① 생성 드릴(FE-GATE-020)은 merge 명령을 `config/ci/gates.json`에서 뽑아 돌지만, 브라우저 명령(`test:e2e`, `test:browser-capabilities`, `test:storybook`, `test:visual`, `test:a11y`, 그 증거 검사)은 뺀다(`scripts/lib/feature-scaffold-drill.ts:18-37`). 이유는 "FE-GATE-020 job에 브라우저가 없다"이고, 생성 라우트는 "1103/12-01과 12-03으로 리뷰했다"고 적는다(`:18-21`). ② 그래서 CI의 FE-GATE-008·009(merge-48 rc=0)는 템플릿 원래 상태만 본다. 매뉴얼 README도 "브라우저 게이트는 드릴 밖"이라고 적는다(`docs/manual/README.md:5`). ③ 이 틈의 실제 사례: 1103/16-09(기능 생성 직후 dev server 부팅 실패, dev server를 쓰는 capability e2e 38건 실패)는 게이트가 아니라 매뉴얼 재실험(X2 #3)이 찾았다(1103 README §13). 고친 뒤 `tests/unit/dev-release-manifest.test.ts`가 그 원인 하나를 test:unit으로 막는다. 같은 종류(브라우저에서만 드러나는 생성 기능 결함)는 여전히 CI가 보지 않는다. 예: a11y spec의 descriptor 답(`tests/e2e/support/installed-api-answers.ts`), 시각 골든의 기능 링크 가리기(12-01) ④ 지금은 통과한다. 16-R1(workflow env)에서 생성 기능을 설치하고 FE-GATE-008 rc=0(e2e 211 통과·3 skip, capability 66, storybook 1, visual 6), FE-GATE-009 rc=0(69 통과, 생성 라우트 3 × 엔진 3)이었다. 통과를 지키는 장치가 CI에 없다는 것이 이 발견이다 | +| 발생 조건 | 템플릿 변경이 생성 기능의 화면·접근성·dev server 경로만 깨뜨릴 때 | +| 영향 | 그 변경은 merge 게이트를 통과하고, 다운스트림이 기능을 더한 뒤 처음 드러난다. 사용자 피해는 없다(다운스트림의 자기 게이트가 잡는다) | +| 심각도·우선순위 | Low · P2 — 피해는 없고 다운스트림 게이트가 결국 잡는다. 다만 생성 명령의 약속("모든 merge 게이트를 통과")을 템플릿이 스스로 지키는 장치가 이 두 게이트에 없다 | +| 통제·증거 | 목표 M3(생성 기능 설치 상태의 브라우저 게이트를 CI가 돈다). 확인 M1(제외 이유와 문서) · E1(드릴 코드), 지금 통과는 E3(16-R1) | +| 확실성과 남은 가정 | 제외 목록과 CI matrix는 코드로 확인했다. 12 영역(게이트·CI)과 겹칠 수 있다. 합칠 때는 12 영역을 대표로 한다 | +| 결정의 근거 | 확인한 사실: 1103/12-02 수정이 드릴을 merge 단계 전체로 넓혔고, 브라우저만 이유와 함께 뺐다. FE-GATE-020 job은 `browser: false`다(`.gitea/workflows/quality-gates.yml:56`). 리뷰어 추론: FE-GATE-008 job은 브라우저가 있으므로 그 job에서 생성 기능 하나를 설치한 복사본으로 a11y·capability 일부를 돌릴 수 있다 | +| 이해 비용 | 템플릿 변경자가 생성 기능을 손으로 만들어 브라우저 게이트를 돌려야 그 경로를 본다 | +| 최소 개선 방향 | FE-GATE-008 또는 009에 "생성 기능 하나 설치 + `test:a11y -g <생성 라우트>` + dev server capability 한 spec" 단계를 더한다. 또는 FE-GATE-020 job에 브라우저를 주고 드릴의 브라우저 제외를 줄인다 | +| 대안 비교 | (a) 현상 유지 + 문서. (b) FE-GATE-009에 생성 기능 라우트만 도는 짧은 단계: 시간이 적다. (c) FE-GATE-020 job에 브라우저: 드릴 시간(지금 1,156초)이 더 는다(job 상한 45분, `CHANGELOG.md:273`). (b) 권장 | +| 단순화의 보존 조건 | 적용 제외 — 단순화 제안이 아니다 | +| 비용·부작용 | (b)는 생성 1회 + 라우트 3개 a11y + spec 하나. 분 단위 | +| 재검토 조건 | merge job의 브라우저 구성이 바뀌거나, 생성 판이 화면을 더 만들 때 | +| 완료 기준 | 생성 기능을 설치한 상태의 a11y·dev server 경로를 merge 게이트 하나가 돈다 | +| 검증 방법 | a11y spec의 descriptor 답을 일부러 틀리게 바꾼 템플릿 변경이 merge 게이트에서 실패한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음 | + +### 16-04 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트에 나오는 이름을 잔여로 잡는다 — 매뉴얼 예시 이름 `invoice-feature`로 만든 기능은 11단계가 실패하고, 안내는 템플릿 파일 수정이다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (검사의 거짓 양성) | +| 관련 관점 | 27, 20, 21, 24, 8 | +| 근거 | ① 매뉴얼은 예시 ID로 `invoice-feature`를 쓴다(1단계 `corepack pnpm create:feature invoice-feature`, 01:94. 11단계 `corepack pnpm test:sample-removal -- --feature=invoice-feature`, 01:626). ② 실행 16-R1(workflow env): 그 이름으로 만든 `--with-create --keyed` 기능의 11단계가 rc=1, 198초. 기준선 재작성, 타입, 테스트, 커버리지(`Risk coverage: PASS (418/418 production modules, 72 thresholds)`), CI 계약(`27 gates ... PASS`)은 통과했다. 실패는 `invoice-feature removal failed: fixture-id-residue: residue: tests/unit/create-feature.test.ts` 하나다. ③ 원인: 제품 기능의 잔여 패턴은 기능 ID와 폴더 이름의 대소문자 무시 부분 문자열이고(`scripts/test-sample-removal.ts:113-120`), 복사본의 `src`·`tests` 모든 파일의 경로와 내용에 건다(`:415-425`). 템플릿 소유 `tests/unit/create-feature.test.ts`가 `invoice-feature`를 53번 쓴다(생성 명령 단위 테스트의 예시 ID). ④ 같은 충돌이 나는 이름: 매뉴얼의 다른 예시 `notice-feature`(`tests/unit/registry-governance.test.ts:637`), `orders-feature`·`drafts-feature`(`tests/unit/create-feature.test.ts:27`), `shop-feature`·`home-feature`(`tests/architecture/context-route-roots.test.ts:59, 98`). 경계 없는 부분 문자열이라 `-feature`를 붙이지 않은 짧은 ID(예: `items`, `shop`)는 더 많은 파일에 걸린다(코드 추론). ⑤ 오류 안내는 "그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다"다(`docs/manual/reference/errors.md:197`). 그 파일은 템플릿 소유라, 따르면 템플릿 파일을 고치게 된다. ⑥ 생성 명령은 이 이름을 거절하지 않는다. 생성 드릴의 이름(`scaffold-feature`)은 템플릿 테스트에 없어 FE-GATE-020은 통과한다 | +| 발생 조건 | 매뉴얼 예시 이름이나 템플릿 테스트·fixture에 나오는 이름으로 기능을 만들고 11단계를 돌릴 때 | +| 영향 | 문서화된 제거 확인이 기능과 무관한 이유로 실패한다. 다른 검사는 다 통과했으므로 실제 잔여는 없다. 사용자는 이름을 바꾸거나(0단계는 "나중에 바꾸기 어렵다"고 적는다, 01:66) 템플릿 테스트를 고친다. 사용자 피해는 없고 merge 게이트도 막지 않는다 | +| 심각도·우선순위 | Low · P2 — 제품 기능의 제거 드릴은 merge 게이트가 아니고, 실패 문구가 원인 파일을 말한다. 다만 매뉴얼 예시를 그대로 따른 사람이 마지막 단계에서 막히고, 같은 종류가 지난 X2 #1(예시 이름과 타입 검사 탐침 충돌)에 이어 두 번째다 | +| 통제·증거 | 목표 M3(잔여 검사가 실제 잔여만 잡는다). 확인 M2(검사는 돌지만 템플릿 파일을 잔여로 셈) · E3(16-R1) | +| 확실성과 남은 가정 | `invoice-feature`는 실행으로 확인했다. 다른 이름은 `git grep`과 잔여 패턴 코드로 판단했다 | +| 결정의 근거 | 적용 제외 — 검사 범위를 좁히는 단순 수정이다. 고를 것은 범위뿐이다(아래) | +| 이해 비용 | 실패를 본 사람이 잔여 패턴이 부분 문자열이고 템플릿 테스트도 훑는다는 것을 코드에서 알아야 한다 | +| 최소 개선 방향 | 제품 기능의 잔여 검사를 "제거 전에 그 기능 ID를 담지 않던 파일"으로 좁힌다. 예: 드릴이 지우기 전에 같은 패턴으로 한 번 훑어 이미 걸리는 템플릿 파일을 제외 목록으로 잡는다. 함께 템플릿 테스트의 예시 ID를 예약 접두어(`typecheck-probe-*`처럼)로 바꾸고, 매뉴얼 예시는 그 접두어와 겹치지 않게 둔다. 생성 명령이 템플릿 테스트에 나오는 ID를 경고할 수도 있다 | +| 대안 비교 | 적용 제외 — 단순 결함 수정 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 드릴 수십 줄, 테스트 예시 ID 교체 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `create:feature invoice-feature --with-create --keyed` 뒤 `test:sample-removal -- --feature=invoice-feature`가 rc=0이다. 기능 ID를 담은 파일 하나를 `src/contracts/`에 남긴 변이에서는 여전히 실패한다 | +| 검증 방법 | 16-R1을 다시 돌린다. 잔여 하나를 일부러 남긴 변이를 더한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 재검증 결과 | 해당 없음 | + +## 4. 28개 관점 판정 (36.2) + +판정: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. + +| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | > 07·09. 생성 기능은 도메인 규칙이 없어 `domain/`을 만들지 않는다 | — | E1 | > | +| **2** | **구조적 성숙도** | 적용(깊게) | M4 / M3 | E2 | **P** — 기능 경계 규칙이 생성 기능에도 돈다(드릴의 `check:architecture`, merge-48 FE-GATE-020). 기능 `contracts/`와 다섯 폴더 밖 폴더를 거친 어댑터 접근은 규칙이 없다(0929/12-03, 1101/16-06 남음). 오류 경계·`TelemetryPort` 두 벌(1101/16-05 남음) | +| **3** | **변경 용이성** | 적용(깊게) | M3 / M3 | E3 | **P** — 손으로 다시 적는 칸 넷 중 둘이 검사를 얻었다(Envelope 섞임 거절, 스키마 메타 대조, `16-mut`). 뮤테이션 정책은 helper가 생겼다. 대신 기능마다 다시 쓰는 추적 파일 둘이 생겼다(16-01) | +| **4** | **인지 부하** | 적용(깊게) | M1 / M1 | E1 | **P** — KEYED 쓰기 값 넷이 02 결정표와 `--keyed`로 정해졌다(1103/16-07). 생성 뒤 할 일(a11y 서명, merge 게이트, 초기 JS 기록, manifest 커밋)이 출력 `Next:`에만 모여 있고 03 문서와 다르다(16-01) | +| 5 | 위험 가시성 | 적용 | M3 / M3 | E3 | P — Envelope 줄 하나 누락과 쓰기의 전부 누락은 조립이 거절한다(`16-mut` M1·M2). 읽기만 있는 기여의 전부 누락은 생성 gateway 테스트만 잡는다(1103/16-01 일부) | +| 6 | 실패 성숙도 | > 03·07 | — | E1 | > — 생성 KEYED 작성의 409·503·400 경로 테스트가 생성된다(`scripts/create-feature-write-slice.ts:864-994`) | +| 7 | 운영 성숙도 | - 이 영역 밖 | — | — | - | +| 8 | 디버깅 가능성 | 적용 | M2 / M2 | E3 | P — 조립 거절이 두 operation과 고칠 방법을 말하고 `check:registries`가 그 이유를 싣는다(`16-mut`). 제거 드릴의 잔여 실패는 파일을 말하지만, 안내가 템플릿 파일 수정을 가리킨다(16-04). 뮤테이션 ID 불일치는 여전히 `MISSING_IDEMPOTENCY_KEY`·`UNEXPECTED_IDEMPOTENCY_KEY`다(1103/16-05 일부) | +| **9** | **유지보수 성숙도** | 적용(깊게) | M1 / M1 | E1 | **P** — 같은 내용 사본: 백엔드 생성기 사실의 프론트 사본(16-02), `BUILD_INPUTS` 두 벌(15-03). 1101/16-05의 두 벌 넷 그대로. 기능 모양의 원본이 셋이다(`create-feature.ts` 1,813줄 + `create-feature-write-slice.ts` 1,044줄, 참조 기능). FE-GATE-020이 생성 결과를 merge 명령으로 돌려 컴파일·테스트 drift를 잡는다 | +| 10 | 테스트 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 생성 쓰기 기능이 비브라우저 merge 명령과 기능 제거를 FE-GATE-020에서 돈다. 설치 상태의 브라우저 게이트는 지금 통과하지만(16-R1) CI가 돌지 않는다(16-03). 제품 기능 제거의 잔여 검사가 거짓 양성을 낸다(16-04) | +| 11 | 데이터 성숙도 | > 05 | — | — | > | +| 12 | 동시성 성숙도 | > 03 | — | — | > — 생성 뮤테이션 정책은 `REJECT_WHILE_ACTIVE` | +| 13 | 확장성 | 적용(기능 수 축) | M3 / M3 | E3 | P — 기능당 초기 JS를 기록과 상한으로 막는다. 쓰기 기능 둘(각각 새 context)이 204,523 / 204,800 B로 들어가고 여유 277 B가 남는다(16-R1). 셋째부터 예산 결정이 필요하다(추론, 1101/15-01, 15 영역) | +| 14 | 성능 성숙도 | > 15 | — | E3 | > — 번들 게이트는 15 영역 | +| 15 | 보안 성숙도 | > 03·13 | — | — | > | +| 16 | 의존성 성숙도 | > 12·13 | — | — | > | +| 17 | API / Contract | 적용 | M4 / M3 | E3 | P — operation은 descriptor 한 곳, FE-REG-API는 투영, 한 기여 안 응답 모양 섞임은 조립이 거절한다. 스키마 메타 설명 칸은 test:unit이 대조한다(`16-mut` M3). 백엔드 생성기 사실의 사본은 기계 대조가 없다(16-02) | +| 18 | 배포 성숙도 | > 13 | — | — | > | +| 19 | 설정 성숙도 | 적용(일부) | M1 / M1 | E1 | O — 앱 `MAX_RETRY_ATTEMPTS`가 `retryBudget`을 덮는다는 사실과 하네스 값이 02 결정표에 있다(`02-decision-tables.md:121-127`) | +| 20 | 개발자 경험 | 적용 | M3 / M2 | E3 | P — 생성 명령 하나로 쓰기 기능이 손 수정 없이 merge 명령(브라우저 둘 포함, 16-R1)을 통과한다. 매뉴얼 예시 이름을 그대로 쓰면 11단계가 실패한다(16-04). 생성 뒤 커밋할 추적 파일과 충돌 처리가 문서에 없다(16-01) | +| 21 | Guardrail 성숙도 | 적용 | M3 / M3(부분) | E3 | P — 새로 잡는 것: Envelope 섞임과 쓰기의 Envelope 누락, 스키마 메타 설명 칸, 낡은 dev manifest·초기 JS 기록, 제품 기능 제거. 아직 통과하는 것: 읽기만 있는 기여의 Envelope 전부 누락, 손으로 쓴 뮤테이션 ID, 기능 안 폴더 우회(0929/12-03, 12-R3 rc=0), 생성 기능의 브라우저 경로(16-03). 거짓 양성: 제거 드릴 잔여 검사(16-04) | +| **22** | **추상화 성숙도** | 적용(깊게) | M3 / M3 | E3 | **P** — `commandMutationIdentity`는 descriptor에서 두 값을 받는 작고 맞는 helper다. 스키마 메타는 투영 대신 대조를 골라 칸이 남았다. 읽지 않는 라우트 `title`·`navigationLabel` 칸이 남았다(1103/16-06 일부) | +| **23** | **일관성** | 적용(깊게) | M1 / M1 | E1 | **P** — 쓰기 slice가 Envelope 모양의 완성 예시가 됐다(지난 5.3 권고 (c)). 참조 기능은 problem details 모양으로 남았다(의도, 01:229-237). 03 문서·정본 표가 생성 명령이 바꾸는 파일을 다르게 말한다(16-01) | +| **24** | **네이밍 / 의미** | 적용(깊게) | M1 / M1 | E1 | **P** — 뮤테이션 ID 불일치의 위반 이름(1103/16-05 일부). `typecheck-probe-*`는 주석으로만 예약됐다(`tests/unit/product-extension-typecheck.test.ts:28-29`). 매뉴얼 예시 이름이 템플릿 테스트의 이름과 겹친다(16-04). 1101/16-05의 같은 이름 두 타입 그대로 | +| 25 | 조직 확장성 | 적용(구조 준비, 팀 1개) | M3 / M2 | E3 | P — 손으로 고치는 템플릿 파일은 없다. 지난 라운드 예외(접근성 spec 수정)는 사라졌다. 대신 기능마다 다시 쓰는 추적 파일 둘이 병렬 브랜치의 충돌 자리다(16-01) | +| 26 | Ownership | > 14 | — | — | > | +| **27** | **삭제 가능성** | 적용(깊게) | M3 / M2 | E3 | **P** — 제품 기능 제거 드릴이 동작하고 merge 게이트가 돈다(merge-48 FE-GATE-020 `scaffold-feature removal: PASS (17 checks)`, 지난 X 해소). 매뉴얼 예시 이름의 쓰기 기능은 다른 검사를 다 통과하고 잔여 검사의 거짓 양성으로 실패했다(16-R1, 16-04). 폴더 밖 잔여(a11y 기록, 기능 전용 e2e spec)는 드릴이 잡지 않고 03 손 목록에 있다(03:176-185). 그 목록은 초기 JS 기록을 말하지 않는다(16-01) | +| 28 | 회복 가능성 | > 06·02 | — | — | > | + +집계(이 영역): O 1 · P 16 · X 0 · ? 0 · > 10 · - 1. 지난 라운드 X 1개(27)는 P가 됐다. + +## 5. 미검증 + +| 항목 | 이유 | 확인 방법 | +|---|---|---| +| 읽기만 있는 기여에서 Envelope 줄을 모두 지운 경우(1103/16-01 남은 부분) | 코드로 판단했다(`external-contract-runtime.ts:627-669`의 두 검사 모두 걸리지 않는다). 요청하지 않았다 | 기본 생성 판(GET 하나)에서 그 줄을 지우고 `check:registries`와 기능 테스트 | +| FE-GATE-013(생성 기능 설치 상태) | `test:system`은 오케스트레이터가 따로 다룬다. 생성 기능과 무관한 전제(bubblewrap, cgroup)다 | 실제 CI 러너에서 생성 기능 브랜치로 FE-GATE-013 | +| 실제 Gitea 러너의 merge job | desktop에서 workflow env를 준 것뿐이다 | 러너에서 생성 기능 PR 하나 | +| 두 기능 브랜치의 실제 `git merge` 충돌(16-01) | git 상태를 바꾸는 실행을 하지 않았다. diff 구조로 판단했다 | 임시 clone에서 기능을 하나씩 더한 두 브랜치를 합친다 | +| 매뉴얼만 보는 사람·에이전트의 재실험(X2 방식) | 이번 실행은 리뷰어가 생성 뒤 단계를 돈 것이다. 3~8단계 손 작업(계약을 실제 백엔드에 맞추기)은 하지 않았다. 1103 README §14.6도 "막힘 0"을 같은 방법으로 다시 재지 않았다 | 매뉴얼만 보는 에이전트가 생성 기능을 실제 계약으로 바꾸고 막힘을 센다 | +| 실제 짝 백엔드 연결 | 백엔드를 띄우지 않았다. 생성 테스트의 손글씨 Envelope 본문과 백엔드 템플릿 코드를 대조했다 | 백엔드 `new-feature.sh Invoice`와 프론트 생성 기능을 같이 띄운다 | + +## 6. 실행 기록 + +| 이름 | 명령 | 변이 | rc | 결과 | 잠금 대기 | 부하 | +|---|---|---|---|---|---|---| +| `16-mut` | `bash /tmp/claude-gates/r4/mut/16-mut-cmd.sh`(상태마다 `corepack pnpm -s check:registries`, `node scripts/run-vitest.ts run tests/features/invoice-feature tests/unit/schema-metadata-policy.test.ts`, M2에서 `check:types`) · env: local | `16-gen-norecord.sh`: `create:feature invoice-feature --with-create --keyed`, `git add -A` | 0(73초) | 변이 전: registries rc=0(`11 registries PASS; compatibility=additive`), vitest 5파일 통과. M1 줄 하나 삭제: registries rc=1 `responseEnvelope NONE, but INVOICE_LIST_ITEMS ...`, vitest 4파일 실패. M2 세 줄 삭제: `check:types` rc=0, registries rc=1 `refusedBeforeWrite needs responseEnvelope ENVELOPE_V1`, gateway 11건·페이지 7건 실패(`SCHEMA_MISMATCH` 4, `SUCCESS_SCHEMA_INVALID` 2). M3a `direction`: registries rc=0, `InvoiceItemListPayload: row REQUEST, used as RESPONSE`. M3b `boundary`: registries rc=0, `row api-request, used as api-response`. M3c `unknownFieldPolicy`: registries rc=0, `row STRIP_UNKNOWN, validator REJECT_UNKNOWN`. **restored: clean at 8a442262** | 579초 | 시작 2.16 | +| (취소) 첫 묶음 4개 | `16-feat-fast` 외 | — | — | 19:31에 잠금 대기 중 내가 멈췄다. 잠금을 잡지 않아 checkout을 건드리지 않았다 | — | — | +| (취소) `16-feat-fast`, `16-feat-browser`, `16-feat-build`, `16-two-features` | merge 게이트 `ci:gate`, 제거 드릴, 둘째 기능 예산 | `16-gen.sh` | — | 잠금 대기 중 `Killed`, 뒤 호출은 `CLOSED`(exp.sh 닫힘). 잡은 적 없다. 배치 요청 16-R1로 바꿨다 | — | — | +| 16-R1 (오케스트레이터 배치) | `bash /tmp/claude-gates/r4/mut/16-R1.sh` · env: CIENV. 안의 단계: `RECORD=0 bash 16-gen.sh`(`create:feature invoice-feature --with-create --keyed`, `git add -A`) → `corepack pnpm -s ci:gate FE-GATE-008` → `ci:gate FE-GATE-009` → `corepack pnpm -s test:sample-removal -- --feature=invoice-feature` → `create:feature order-feature --with-create --keyed`, `git diff -- public/release-manifest.json`, `corepack pnpm -s build`, `corepack pnpm -s check:bundle` | — (생성이 첫 단계) | 0(450초) | 생성: 폴더 밖 새 파일 4, 수정 `M public/release-manifest.json`. FE-GATE-008 rc=0 186초(e2e 211 통과·3 skip, capability 66, `Browser capability evidence: PASS (22 cases x 3 engines, zero skipped)`, storybook 1, visual 6). FE-GATE-009 rc=0 60초(69 통과, `/invoice`·`/invoice/items/a11y-1`·`/invoice/new` × 3 엔진, `Manual accessibility record format: PASS (13 routes ...)`). 제거 드릴 rc=1 198초: `fixture-id-residue: residue: tests/unit/create-feature.test.ts`(다른 검사는 통과). 둘째 기능: `setDigest` 줄 다시 바뀜, `packages`에 `@org-contracts/order`. build rc=0, `Bundle budget: PASS (initial JS 204523 / 204800 gzip bytes, 26 / 32 files)`. **restore clean**(8a44226) | 배치 | 시작 3.26, FE-GATE-008 중 14.09 | + +인용한 다른 실행(같은 커밋): + +| 출처 | 내용 | +|---|---| +| 오케스트레이터 `merge-48`(CI=true) | FE-GATE-020 rc=0 1,156초: `reference-feature removal: PASS (31 checks)`, `scaffold-feature removal: PASS (17 checks)`, `feature scaffold: PASS (77 checks)`, optional-recipe·browser-file-storage·realtime 제거 PASS. FE-GATE-001~012 rc=0. FE-GATE-013 rc=1(오케스트레이터가 판정. 이 영역 경로와 무관) | +| 오케스트레이터 `gates/`(로컬 env) | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`check:adapter-inventory` rc=0. `verify:documentation` rc=1: desktop의 짝 백엔드 사본이 `ef947e5`라 `../clean-architecture-backend-template/docs/web/http-contract.md`가 없다(`docs/manual/01·02·04·README`가 이름을 든다). 이 영역 결함이 아니다(1103/12-05 소관, 오케스트레이터가 판정) | +| 영역 15 `15-lab`, `15-feature` | 템플릿 202,927 / 204,800 B, 26 / 32 파일. `create:feature bulletin-feature --with-create --keyed`(새 context) 뒤 203,903 B(+976 B, 여유 897 B), 26 파일. 둘 다 restored clean | +| 영역 12 `12-R3`, 영역 11 `11-R8b` | 12-R3: 기능 안 `support/` 폴더를 거친 어댑터 import에 `check:architecture` rc=0, eslint rc=0(0929/12-03 남음). 11-R8b: 생성 목록 빈 상태에만 이름 없는 button을 넣자 `/sample`만 세 엔진 실패, 상세·작성 통과(목록이 빈 상태로 검사됨). 둘 다 restore clean | + +## 7. 새 발견 요약 + +| ID | 심각도·우선순위 | 성격 | 한 줄 | file:line | +|---|---|---|---|---| +| 16-01 | Low · P2 | 구조적 위험 | 기능 하나를 더하면 추적 파일 `public/release-manifest.json`(자동)과 초기 JS 기록(명령)이 바뀌고, 03 문서·정본 표는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | `scripts/create-feature.ts:1753-1754, 1787-1796`, `docs/manual/03-outside-feature-folder.md:22`, `docs/architecture/starter-experience.md:215-226` | +| 16-02 | Low · P3 | 구조적 위험 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 손으로 옮겼고, pin·drift 검사는 `http-contract.md`만 본다 | `scripts/create-feature-write-slice.ts:58-59, 83-84`, `config/contracts/backend-contract-pin.json:6-7`, `scripts/check-backend-contract-drift.ts:60` | +| 16-03 | Low · P2 | 구조적 위험 | 생성 기능을 설치한 상태로 브라우저 merge 게이트(FE-GATE-008·009)를 도는 장치가 없다 | `scripts/lib/feature-scaffold-drill.ts:18-37` | +| 16-04 | Low · P2 | 확인된 결함 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡아, 매뉴얼 예시 이름 `invoice-feature`로 만든 기능의 11단계가 실패한다. 안내는 템플릿 파일 수정이다 | `scripts/test-sample-removal.ts:113-120, 415-425`, `tests/unit/create-feature.test.ts:53`, `docs/manual/01-add-a-feature.md:94, 626`, `docs/manual/reference/errors.md:197` | diff --git a/docs/reviews/2026-11-05-maturity-review/README.md b/docs/reviews/2026-11-05-maturity-review/README.md new file mode 100644 index 00000000..a7a28da9 --- /dev/null +++ b/docs/reviews/2026-11-05-maturity-review/README.md @@ -0,0 +1,507 @@ +# 성숙도 리뷰 — 2026-11-05 (4라운드) + +> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 대상: `8a44226`(= main `409d72e` 트리. 메인 세션이 `git diff --quiet`로 같은 트리임을 확인했다). 이 커밋은 2026-11-03 리뷰의 조치(README 14절)를 모두 담는다. 영역은 2026-11-03 리뷰의 16개를 그대로 썼다. 영역 에이전트는 노트북 worktree에서 코드를 읽었다. 실행은 모두 desktop checkout 하나에서 했다(10.4절). 이 문서는 오케스트레이터가 결과를 모은 것이다. 새 P1 세 건은 오케스트레이터가 코드를 직접 다시 읽었다. 리뷰 중 코드는 고치지 않았다. +> +> 메인 세션이 따로 물은 네 가지(§14.4 건수, 11-10의 12 px 늘어남, 11-08·11-09·11-10 수정이 검사를 약하게 했는지, FE-GATE-013의 user namespace 전제)의 답은 3절에 있다. + +## 0. 평가 전제 (가이드 0.1) + +| 전제 | 기록 | 판정에 미치는 영향 | +|---|---|---| +| 사용 목적 | 프론트엔드 템플릿(reference implementation). 짝 백엔드 템플릿과 함께 써서 desktop 서버에 서비스를 빨리 출시하는 시작점(`PRODUCT.md`) | 다운스트림이 그대로 복제하는 기본값과 문서가 판정 대상이다 | +| 사용자와 팀 | 작성자 1명 + AI 세션. 다운스트림 2개(tech-log, memento) | 템플릿 파일을 고쳐야 하는 지점은 동기화 비용이 된다 | +| 지원 실행 형태 | 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | 서버 메모리 상태·다중 인스턴스 경쟁은 적용 제외. 탭 사이 경쟁은 적용 | +| 데이터와 권한 | 세션(짝 백엔드 인증), 선택형 OPFS 개인 파일, 공개 캐시. 관리자·테넌트 기능 없음 | 로그아웃·계정 삭제 뒤 남는 데이터가 주된 피해 경로다 | +| 규모 목표 | 기능 수 증가 축만 있다. 초기 JS 204,800 B(gzip), 초기 파일 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 등). 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)에서 항상 실패하고, 사전 점검은 PASS를 낸다(12-01) | +| `create:feature`로 기능을 더하고 템플릿 CI로 머지 | 조건부 사용 가능 | 쓰기 기능 하나를 더해도 FE-GATE-008·009가 수정 없이 통과했다(16-R1). 다만 기능에 제품 capability를 주면 FE-GATE-005가 항상 실패한다(09-01, 두 다운스트림 모두 해당). 매뉴얼 예시 이름(`invoice-feature`)으로 만든 기능은 제거 드릴이 실패한다(16-04) | +| 다운스트림(tech-log·memento)에 이 묶음 전파 | 조건부 사용 가능 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사가 실패한다(14-01). 이행 안내가 실제 변경의 일부만 다룬다(1103/14-02 일부) | +| 짝 백엔드에 붙는 쓰기 폼 | 조건부 사용 가능 | 선언한 업무 거절은 다시 저장할 수 있다(1103/03-01). 거절 이유가 안 보이고, 회복 필요 응답 뒤 재전송 버튼이 남는다(1103/03-01 일부, Medium·P2). hook을 직접 쓰면 키 없는 쓰기를 같은 입력으로 다시 보낸다(0929/03-03 일부, Medium·P2) | +| 짝 백엔드와 파일 업로드 | 조건부 사용 가능 | 빈 파일 거절(202 `REJECTED`)을 스키마 불일치로 읽는다(01-01). 504 `TRANSFER_TIMEOUT` 뒤 재시도가 파일을 둘 만들 수 있다(01-02). 실제 짝 백엔드로 올려 본 적이 없다 | +| 짝 백엔드 인증에 세션 붙이기 | 조건부 사용 가능 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(09-02). 실제 Keycloak·Redis 연동 미확인(1103/09-03 일부) | +| OPFS에 개인 파일 저장 | **사용 보류** | 계정 삭제 purge가 다른 탭이 저장 중인 파일을 놓치고 "다 지웠다"고 보고한다(1103/05-01 일부, 개인 파일 제품에 P1). 지난 §14.4의 "고침"은 틀렸다 | +| release 단계(`RELEASE_READY`)까지 | 조건부 사용 가능 | lab 게이트 통과(146 ms). release job이 gate 로그를 올리지 않아 실패 이유와 의존성 advisory 신호가 실제 run에서 사라진다(13-01). advisory 2건은 결정 대기(1103/13-03) | +| 배포 슬롯을 채워 자동 배포 | 조건부 사용 가능 | 제품 merge 검사가 실패해도 같은 run의 release·배포가 진행된다(13-02). 13-01·13-03 | +| 빌드 → 공개 대상 승인 → 손으로 배포 | 사용 가능 | 실제 nginx 1.27.5에 템플릿 예시 그대로 FE-GATE-019가 후보를 통과시키고, 같은 run 재빌드·`http2`·`gzip` 누락을 거절한다(13-R02) | +| 짝 백엔드 Envelope 조회 화면 | 사용 가능 | `meta.page`를 넘긴다(1103/03-02 일부: bulk만 미지원) | +| opt-in realtime(SSE·WS)·bounded polling | 조건부 사용 가능 | poll 1회 = 요청 1회(04-R1). 결정 대기 0929/04-03, SSE EOF 0929/04-02 | +| SW `ACTIVE`·Web Push | 조건부 사용 가능 | Firefox quarantine 아직 필요(06-R11). 06 영역 Low 3건 | +| 셸·디자인 시스템·읽기 화면 | 사용 가능 | 08 영역 Low 4건 | + +## 2. 차단 항목 (36.5-3) + +### 2.1 새 High — 없음 + +### 2.2 새 P1 (3건, 모두 Medium) + +| ID | 내용 | 위치 | 재확인 | +|---|---|---|---| +| [09-01](09-app-core.md) | 1103/09-02 수정이 더한 제품 확장 타입 검사 탐침이 복사본의 `product-contracts.ts`·`product-composition.ts`를 탐침 내용으로 통째로 덮어쓴다. 기능에 제품 capability를 주는 다운스트림에서는 FE-GATE-005가 항상 실패한다 | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` | **오케스트레이터 확인.** `product-capabilities.ts`는 덧붙이지만(`:185`) 나머지 둘은 `PRODUCT_CONTRACTS`·`PRODUCT_COMPOSITION` 상수로 바꾼다(`:186-187`). `composeProduct`가 `typecheckProbeSettings`만 돌려주므로 제품 capability가 빠진다. 에이전트 실험 09-probe-downstream: 같은 상태에서 tsc app·node·test는 rc=0, 탐침만 TS2741(`runtime-adapters.ts(695,5)`) | +| [12-01](12-guardrails-ci.md) (+ [11-02](11-tests-browser-release-scale.md)) | FE-GATE-013이 비특권 user namespace(bwrap `--unshare-net`)를 전제하는데 러너 요구 목록·gate 정의·사전 점검 어디에도 없다. 이 desktop에서 사전 점검은 PASS를 내고 provider test 18건이 bwrap 원문 오류로 실패한다 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` | **오케스트레이터 확인 + 실행.** 사전 점검은 실행 파일·cgroup·systemd bus만 보고 bwrap을 한 번도 실행하지 않는다. 요구 목록(`ci-quality-gates.md:181-185`)은 bwrap·`--size` 지원·cgroup을 적지만 user namespace·네트워크 namespace는 없다. 유일한 기록은 2026-08-15 운영 원장의 한 번 관찰 메모다(`docs/operations/adapter-remediation-ledger.md:531-546`). merge-48 FE-GATE-013: 18 failed / 96 passed (114), 12건 `bwrap: loopback: Failed RTM_NEWADDR`, 6건은 그 provider를 기다린 시간 초과. desktop `kernel.apparmor_restrict_unprivileged_userns = 1`. 11-R10: repo 없이도 `bwrap --unshare-net /bin/true`가 같은 오류 | +| [13-01](13-build-release-supply-chain.md) | release 단계 job `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. `ci:gate`는 명령 출력을 로그 파일에만 쓰므로 실제 run에서는 release 실패 이유와 1103/13-03의 advisory 신호가 사라진다 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249` | **오케스트레이터 확인 + 배치 실행.** 다른 gate job은 `if: always()`로 `artifacts/`를 올린다(`quality-gates.yml:114-120`). `immutable_build`의 upload는 후보 tar 하나뿐이고 성공 경로에만 있다(`:202-207`). 13-R01: FE-GATE-027 console은 2줄(PASS), `POLICY_VIOLATION`과 경고 4줄은 로그 파일에만 있었다 | + +세 건 모두 "사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다"는 지난 라운드 기준(1103 README 2.3절, 02-06)으로 Medium·P1이다. + +### 2.3 이월 항목 중 남은 큰 것 + +| ID | 지난 등급 | 지금 | 남은 부분의 등급 | +|---|---|---|---| +| 1103/05-01 | Medium·P2 (OPFS 개인 파일 제품 P1) | 일부. 지난 §14.4 "고침"은 틀렸다 | Medium·P2, OPFS 개인 파일 제품 P1 | +| 1103/03-01 (= 08-01) | High·P1 | 일부. 완료 기준 넷은 충족 | Medium·P2 (거절 이유 표시, 회복 필요 응답 뒤 재전송 버튼) | +| 0929/03-03 | High·P1 | 일부. 버튼·hook 재전송은 막혔다 | Medium·P2 (같은 입력 재제출. 템플릿 폼은 막는다. 오케스트레이터가 `application-query.ts:557-561`, `:590-596`, `use-app-form.ts:325`를 읽어 확인) | +| 1103/01-01 | High·P1 | 일부. client와 문서는 들어왔다 | 미검증(실제 짝 백엔드 업로드) + 새 01-01·01-02(Medium·P2) | +| 1103/13-03 | Medium·P1 | 일부, 결정 대기 | Medium·P1 그대로 | +| 1103/09-04, 1103/03-07 | Medium·P2, Low·P3 | 결정 대기 | 그대로 | + +### 2.4 심각도 조정과 합침 + +| ID | 영역 제안 | 최종 | 이유 | +|---|---|---|---| +| 12-01 + 11-02 | 12: Medium·P1, 11: Low·P3 | 12-01 Medium·P1 하나 | 같은 사전 점검(`check-system-test-prerequisites.ts:15-38`)과 같은 실패. 11 영역은 "desktop만의 조건"으로 낮췄다. 하지만 이 desktop은 사용자 목표의 배포 서버이고, 러너 요구 목록에 이 조건이 없어 어떤 러너가 해당하는지 알 수 없다. 메인 세션의 정지 기준(merge 14개 통과)을 직접 막는다 | +| 01-02 | Medium·P2 | 그대로 | 결과 불명 쓰기의 재실행(가이드 35.2 High 예시)과 모양이 같다. 그러나 백엔드가 `TRANSFER_TIMEOUT`을 `retryable=true`, `ambiguous=false`로 선언한다(`BlockingTransferExecutor.java:64-79`, `FileserverFailureContext.java:13-20`). client는 백엔드 선언을 따른다. 남는 위험의 주인은 두 repo 계약이다 | +| 0929/03-03 남은 부분 | High·P1 → Medium·P2 (03 영역) | Medium·P2 | 템플릿이 그리는 경로(폼·페이지)는 모두 막는다. 남은 길은 제품이 hook을 직접 부를 때뿐이다 | + +## 3. 메인 세션이 물은 네 가지 + +### 3.1 §14.4 "그 밖의 81건" + +- 1103 색인은 95건이다. 2절 차단 항목에만 있는 0929/03-03을 더하면 96건이다. §14.4가 ID로 적은 것은 35건이다. 그래서 나머지는 81건이 아니라 **61건**이다. 81은 셈이 틀렸다. +- 96건 전부를 ID별로 다시 판정했다(13절 표). **고쳐짐 74 · 일부 22 · 남음 0.** +- §14.4가 "고침"이라 적었지만 지금 "일부"인 것이 **13건**이다. 01-01, 03-01, 0929/03-03, 05-01, 11-01, 11-02, 11-03, 11-04, 14-01, 14-02, 15-02, 16-01, 16-05. + - 이 중 05-01·14-01·14-02·16-01·16-05·11-03·11-04 7건은 "그 밖의 61건"에 들어 있었다. 61건 중 54건은 고쳐졌다. + - 11-02·11-03·11-04는 코드는 들어왔지만 완료 기준 실행이 없다. 가이드 35.6에 따라 "일부"로 둔다. +- §14.4가 "일부"라고 한 9건은 지금도 일부다. 03-02, 03-07, 07-04, 09-03, 09-04, 09-05, 12-05, 13-03, 16-06. +- 지난 판정이 틀렸던 것이 하나 더 있다. 1103/14-04는 FE-GATE-017을 merge 게이트라고 적었지만 문서 단계 게이트다. 결함 자체는 맞았다(14 영역). + +### 3.2 11-10의 12 px 늘어남 — 첫 화면의 layout shift인가 (15 영역) + +- **무엇이 늘어나나.** 라우트 로딩 화면(280 px)이 홈 화면(660 px)으로 바뀐다. 셸 내용 줄이 648 px라 문서 높이가 720 → 732 px가 된다. dev server와 production build(`vite preview`), 세 엔진 모두 같다. +- **스크롤바를 숨긴 조건(모든 게이트의 Chromium)에서는 layout shift가 아니다.** preview 8회에서 `layout-shift` 항목 0건. Firefox·WebKit ResizeObserver 기록에서도 화면에 보이는 것이 움직이지 않는다. 늘어난 부분은 화면 아래다. +- **실제 스크롤바가 있으면 작은 shift가 있다.** 홈 첫 렌더가 세로 스크롤바를 만들어 header가 15 px 밀린다. CLS 0.0002(1280×720, 1366×657). 1920×960에서는 0이다(15-R2). → **새 15-05(Low·P3).** +- **관점 10·21: 어떤 게이트도 이것을 보지 못한다.** 게이트의 Chromium은 스크롤바를 숨긴다. lab은 `/`의 CLS만 재고, 클릭 뒤 500 ms 안의 shift를 뺀다. lab 대상 화면 자체도 제목 뒤 21 px를 민다(CLS 0.0046, 새 15-01 Low·P3). dev에서만 스타일 없는 부팅 셸이 0.00625 shift를 낸다(production에는 없다). +- 결론: 사용자에게 보이는 첫 화면 문제는 작다(Low). 11-10 test 실패의 원인은 test가 그리는 중인 앱 뒤에 버튼을 붙인 것이었다. 지금 고정 층 수정으로 막혔다(3.3절). + +### 3.3 11-03 뒤 수정이 검사를 약하게 했나 (변이로 확인) + +| 수정 | 확인 | 결과 | +|---|---|---| +| 11-08 `b693600` 로컬 빌드 환경 | 13-R01: CI=true에서 `VITE_COMMIT_SHA`·`SOURCE_DATE_EPOCH`·`CI_RUNNER_IMAGE`를 빼거나 틀린 값으로 준 release 빌드·gate 14가지 | **약화 없음.** 14가지 모두 기대한 문구로 실패. release job에 `CI` 바인딩을 넣거나 생성 workflow를 손으로 고치면 `check:ci`가 거절(13-R03·R04). 수정을 되돌리면 CI=true 테스트가 실패(13-R05·R06). 로컬 빌드 표시는 test helper와 Playwright 설정만 쓴다 | +| 11-09 `aad005c` preload 사용 검사 | 11-R1(검사가 실패를 돌려주지 않게), R2(평가 표시 제거), R4(대조 probe), R5(허용 spec 넷 안에 안 쓴 preload 하나) | **검사는 실패해야 할 때 실패한다.** R1·R2·R5 모두 실패, R4 대조는 세 엔진 모두 probe 실패. WebKit 무시는 정확한 문구 하나뿐이다. **약한 곳 둘:** strict fixture가 그 결과를 버려도 커밋된 test가 하나도 실패하지 않는다(11-R3, 새 11-01 Low·P2). SW가 페이지를 제어하면 허용 규칙이 preload 검사를 모두 끈다(06-R9에서 158줄 모두 ALLOWED, 새 06-03 Low·P3). 지금 워커 결함을 가리지는 않는다(06-R10) | +| 11-10 `ee37dd8` 고정 층 | 11-R6(수정 + mousedown 때 앱 400 px 늘림), R7(수정 되돌림 + 같은 늘림) | **약화 없음.** R6 통과, R7 실패(RED가 돌아온다). 고정 층은 test가 붙이는 control에만 쓰이고 제품 화면 검사는 그대로다 | +| 그 밖의 수정 | 영역별 `git diff e40684b..8a44226` | 약해진 검사 한 건: 1103/14-04 수정이 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다(새 14-03 Low·P3). 초기 파일 상한 25 → 26 → 32는 이유가 기록됐고 템플릿 자신의 파일 수는 정확히 대조한다(12·15 영역) | + +### 3.4 FE-GATE-013의 user namespace 전제는 위험으로 적혀 있나 + +**적혀 있지 않다.** 러너 요구 목록(`docs/operations/ci-quality-gates.md:181-185`), `config/ci/gates.json`의 FE-GATE-013 정의, 생성 workflow, 사전 점검(`scripts/check-system-test-prerequisites.ts:15-38`) 어디에도 없다. 운영 원장에 한 호스트에서 본 일로만 남아 있다(`docs/operations/adapter-remediation-ledger.md:531-546`, "16 of the 108 provider tests cannot run here"). 위험으로 올린 기록이 아니다. → 12-01(Medium·P1, 2.2절). + +## 4. 새 발견 건수 — 지난 라운드와 비교 + +| 구분 | 이번(2026-11-05) 새 발견 | 2026-11-03 리뷰 당시 | 2026-11-03 최종 색인(리뷰 뒤 추가 7건 포함) | +|---|---|---|---| +| 합계 | **48** | 88 | 95 | +| 심각도 | High 0 · **Medium 11** · Low 37 | High 2 · Medium 34 · Low 52 | High 2 · Medium 41 · Low 52 | +| 우선순위 | **P1 3** · P2 15 · P3 30 | P1 12 · P2 38 · P3 38 | P1 19 · P2 38 · P3 38 | +| 성격 | 확인된 결함 25 · 구조적 위험 19 · 개선 제안 4 | 확인된 결함 55 · 구조적 위험 23 · 개선 제안 10 | 확인된 결함 62 · 구조적 위험 23 · 개선 제안 10 | + +- 2026-11-03은 이 밖에 이월 0929/03-03을 High·P1로 올렸다(색인 밖). +- 이번 48건은 영역 문서 47건에서 같은 결함 1건(11-02 → 12-01)을 합치고, 오케스트레이터 발견 2건(12-04, 10-03, 14절)을 더한 수다. +- 이번 새 발견 중 영역 문서가 원인을 지난 라운드 수정으로 짚은 것: 01-01~01-04(새 Fileserver client), 02-01~02-04, 03-01, 04-01·04-02, 07-01(D6 pin), 08-03·08-04, 09-01~09-03, 10-01, 11-01, 12-02, 14-03, 16-01. + +## 5. 확인된 강점 (36.5-2) + +- **merge 게이트 13/14가 CI env에서 통과했다**(desktop, run 48). FE-GATE-005: unit 2,883·coverage 3,869건. FE-GATE-008: e2e 202(3 skip)·capability 66·storybook 1·visual 6. FE-GATE-012: 초기 JS 202,973 / 204,800 B, 26 / 32 파일. FE-GATE-020: 제거·생성 드릴 모두 PASS. FE-GATE-013의 test:system 뒤 명령 7개도 모두 rc=0. +- **지난 High 세 건의 핵심 경로가 변이로 지켜진다.** 03 영역 변이 19개 전부 검출(지난 라운드 생존 M1·M3·M6·M7 포함). 생성한 NEVER 쓰기 기능에서도 선언 누락·재전송 가드 변이가 잡힌다(03-R02). +- **수정을 지키는 테스트가 실제로 잡는다.** 02 영역 수정 규칙 변이 23/23, 05 영역 10/10, 06 영역 7/7, 07 영역 26종, 08 영역 5종, 13 영역 음성 실행 14가지가 기대대로 실패했다. +- **lab 게이트가 다시 통과한다.** 상호작용 중앙값 146 ms(지난 227 ms), LCP 2,032 ms, CLS 0(1103/15-01 고쳐짐). +- **기능 추가 경로가 브라우저 게이트까지 닿는다.** `--with-create --keyed` 기능 하나를 넣고 FE-GATE-008·009가 수정 없이 통과했다. 쓰기 기능 둘도 초기 JS 예산 안에 든다(204,523 / 204,800 B, 16-R1). +- **실제 nginx에서 호스팅 계약이 동작한다.** 템플릿 예시 그대로 FE-GATE-019가 후보를 통과시키고 같은 run 재빌드, `http2 on;`·`gzip on;` 누락을 각각 거절했다(13-R02). + +## 6. 반복되는 원인 (36.5-4) + +1. **수정을 템플릿 원래 상태나 작은 입력으로만 확인했다.** 1103/05-01 수정 테스트는 객체 0~1개만 쓴다. 3개 이상이면 놓친다. 09-01 탐침은 제품 파일이 비어 있는 템플릿에서만 맞다. 16-04는 템플릿 테스트의 글자가 제품 기능 이름과 부딪친다. 14-01은 예제 기능을 지운 상태를 아무 게이트도 돌지 않는다. 16-03은 기능을 설치한 상태로 브라우저 게이트를 도는 장치가 없다. 지난 라운드 원인 2가 모양을 바꿔 남았다. +2. **두 템플릿 사이 사실을 손으로 옮긴다.** Fileserver client의 효과 표(01-02), 202 `REJECTED`(01-01), 답 표 JSON(07-01), 생성기의 백엔드 사실 넷(16-02), rate-limit 503(03-02). pin과 drift 검사는 `http-contract.md` 글자만 비교하고 게이트 밖이다. +3. **게이트가 실행 환경을 말없이 가정한다.** user namespace(12-01), 옆 백엔드 checkout(12-02), 고정 출력 경로·포트(12-04), 숨긴 스크롤바(15-05). 가정이 깨지면 원인 없는 실패나 기계마다 다른 결과가 나온다. +4. **실패 이유가 남지 않는다.** release job 로그(13-01), scope closer 던짐(02-01), poll `execute` 던짐(04-02), 사전 점검 PASS 뒤 원문 bwrap 오류(12-01). +5. **수정이 새 결함을 만든다.** 4절 끝 목록. 수정 커밋마다 "이 변경이 무엇을 새로 가정하는가"를 묻는 단계가 없었다. + +## 7. 결정이 필요한 것 + +| 번호 | 결정 | 선택지 | 관련 | 결정할 사람 | +|---|---|---|---|---| +| D1 | 운영 advisory 2건 | zod 4.6.x(+약 7 KB, 예산 초과) / react-router 갱신 / 위험 수용과 재검토일 | 1103/13-03, 13-01 | 프론트 소유자 + reviewer | +| D2 | 플랫폼 구성 화면 | (가) 플랫폼 진단 화면으로 인정 (나) 기능으로 옮기고 라우트 청크 병렬화 뒤 재측정 | 1103/09-04 | 프론트 소유자 | +| D3 | 백엔드 생성기 목록 GET | 백엔드에 추가 / 프론트 생성기에서 제외 | 1103/03-07 | 두 repo 소유자 | +| D4 | FE-GATE-013 러너 전제 | (가) 러너 요구에 비특권 user namespace를 적고 사전 점검이 bwrap을 실제로 돌린다 (나) 샌드박스 방식을 바꾼다 | 12-01 | 프론트 소유자 | +| D5 | 제품 merge 검사와 release의 관계 | 제품 gate를 release `needs`에 묶는 칸을 연다 / 문서로 제한 명시 | 13-02 | 프론트 소유자 | +| D6 | 실행 격리 | 실행별 출력 디렉터리 + 빈 포트 / "한 checkout 한 실행"을 문서로 명시 | 12-04 | 프론트 소유자 | + +## 8. 미검증 (36.5-5) + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 실제 Gitea 러너 결과 | Actions가 꺼져 있다(U-1). 이번 결과는 desktop에 workflow env를 준 것이다. `CI_RUNNER_IMAGE`는 형식만 맞춘 값이다 | runner 1대와 PR 1건 | +| 실제 짝 백엔드 연동(업로드, 세션) | 백엔드는 읽기만 했다 | 백엔드를 띄워 업로드·로그인·401 한 번씩 | +| 셸 CSS 변경을 시각 계약이 여전히 잡는가 | 12-R2 변이(header padding)가 grid 높이 고정 때문에 화면을 바꾸지 않았다 | 화면이 바뀌는 CSS 변이로 다시 | +| `test:system` 완료 기준(1103/11-03·11-04) | desktop 호스트가 user namespace를 막는다(12-01) | user namespace를 허용하는 호스트에서 한 번 | +| 빈 러너의 시각 글꼴(1103/11-02) | 러너가 없다 | runner 1대 | +| 매뉴얼만 보는 기능 추가 재실험(X2) | 이번 범위 밖 | 매뉴얼만 받은 에이전트 1회 | +| 10 영역 변이 C, 부하 중 EOF 대조 | 19:55에 줄에서 취소됐다 | 배치 1항목 | + +## 9. 개선 순서 (36.5-6) + +| 순서 | 항목 | 최소 변경 | 완료 기준 | +|---|---|---|---| +| 1 | 09-01 | 탐침이 제품 파일을 덮지 않고 복사본의 실제 내용에 덧붙이거나, 탐침 전용 경로로 조립한다 | 제품 capability를 쓰는 기능이 있는 복사본에서 FE-GATE-005 통과 | +| 1 | 12-01 | 사전 점검이 provider와 같은 bwrap 옵션으로 `/bin/true`를 돌려 실패하면 원인과 함께 멈춘다. 러너 요구 목록에 user namespace를 적는다(D4) | desktop에서 사전 점검이 "user namespace" 문구로 실패한다. 허용 호스트에서 114/114 | +| 1 | 13-01 | `immutable_build`에 `if: always()` gate 로그 upload를 더한다 | release gate 실패가 업로드된 로그에 남는다 | +| 1 | 1103/05-01 남은 부분 | purge가 journal 집계와 객체 목록을 같은 잠금 아래에서 다시 대조하거나 끝난 뒤 한 번 더 센다. 객체 3개 이상 테스트 | 객체 3·8개 + 다른 탭 put에서 `COMPLETED`가 나오지 않는다 | +| 2 | 12-04, 12-03 | 실행별 출력·포트 격리. CLAUDE.md 리뷰 게이트 목록을 merge stage `gateIds`로 바꾼다 | 한 checkout에서 두 게이트가 동시에 통과 | +| 2 | 14-01, 16-04, 16-03 | 예제 기능 제거 상태와 기능 설치 상태를 드릴로 돈다 | CHANGELOG 6단계 뒤 문서 검사 통과, 매뉴얼 예시 이름으로 제거 드릴 통과 | +| 2 | 01-01, 01-02, 09-02 | 짝 백엔드 실제 응답으로 client 판정을 맞춘다. 쿠키 recipe가 `onCredentialRejected`를 잇는다 | 백엔드를 띄운 업로드·401 시나리오 | +| 2 | 1103/03-01·0929/03-03 남은 부분 | 거절 문구 자리, 회복 필요 응답 뒤 버튼 제거, hook 재제출 가드 | 08-R1 A5·03-R01 X1이 막힌다 | +| 3 | 나머지 P2·P3 | 영역 문서 | 영역 문서 완료 기준 | + +## 10. 재검토 조건 (36.5-7) + +- Gitea Actions를 켤 때. 12-01의 러너 전제와 13-01의 로그를 실제로 본다. +- 짝 백엔드가 Fileserver 응답·멱등 답 표·생성기를 바꿀 때(01-01, 01-02, 07-01, 16-02). +- 다운스트림에 이 묶음을 동기화할 때(14-01, 1103/14-02, 09-01). +- 제품이 OPFS에 개인 파일을 둘 때(1103/05-01). + +## 11. 리뷰 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 저장소·프로젝트 | `clean-architecture-frontend-template`. 짝 백엔드 `clean-architecture-backend-template`은 노트북 `45d2a478`(pin과 같음)을 읽기만 했다 | +| 커밋·작업 상태·확인 시점 | `8a44226`(= main `409d72e` 트리), 브랜치 `fix/maturity-review-2026-11-03`. 2026-11-05 19:20~21:00. 노트북 worktree는 이 커밋에서 깨끗했다(추적 안 된 `AGENTS.md` 하나는 리뷰와 무관). desktop checkout도 같은 커밋에서 시작해 끝에 `git status`가 비었다 | +| 목적과 지원 실행 구성 | 0절 | +| 필수 요구와 규모·운영 목표 | 0절 | +| 읽은 코드·구성 범위 | `src/`, `tests/`, `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정(영역 표 11.2). 짝 백엔드의 Fileserver·HTTP 계약·멱등·생성기·인증 문서와 코드 일부 | +| 수행한 테스트·실험 | 11.1절 게이트. 영역 에이전트의 개별 실행 15건(10.4절 전환 전), 배치 78항목. 3엔진 Playwright, 변이, 생성 명령으로 기능 추가, 실제 nginx(docker) probe, lab 측정 | +| 확인하지 못한 범위·이유 | 8절 | +| 이전 리뷰와 비교 가능한 범위 | 2026-11-03 리뷰의 96건 전부(13절)와 각 영역의 0929·1101 이월 항목. 이전 실행 결과는 증거로 쓰지 않았다. 메인 세션의 8a44226 실행도 다시 돌렸다(11.1절) | + +실행 환경: 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 게이트 실행 결과 (오케스트레이터, `8a44226`, desktop) + +merge stage 14개, workflow env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID=gitea-48-1`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest 형식). 시간은 잠금 대기를 포함한다. + +| 게이트 | 결과 | 시간 | +|---|---|---| +| FE-GATE-020 | 통과(제거·생성 드릴 모두 PASS) | 1,156초 | +| FE-GATE-001 | 통과 | 579초(대부분 잠금 대기) | +| FE-GATE-002 | 통과 | 35초 | +| FE-GATE-003 | 통과 | 53초 | +| FE-GATE-004 | 통과 | 13초 | +| FE-GATE-005 | 통과(unit 2,883, coverage 3,869) | 133초 | +| FE-GATE-006 | 통과 | 14초 | +| FE-GATE-007 | 통과 | 29초 | +| FE-GATE-008 | 통과(e2e 202·3 skip, capability 66, storybook 1, visual 6) | 181초 | +| FE-GATE-009 | 통과 | 54초 | +| FE-GATE-010 | 통과 | 66초 | +| FE-GATE-011 | 통과 | 9초 | +| FE-GATE-012 | 통과(초기 JS 202,973 / 204,800 B, 26 / 32 파일) | 13초 | +| FE-GATE-013 | **실패** — `test:system` 18 failed / 96 passed(114). 18건 모두 호스트 원인(12-01). 뒤 명령 7개(`verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, 공급망 fixture 둘, 보안 fixture, `check:browser-security`)는 따로 돌려 모두 rc=0 | 84초 | + +CLAUDE.md 목록, local env(CI 값 없음): + +| 명령 | 결과 | +|---|---| +| `check:architecture`, `check:types`, `lint` | 통과 | +| `test:unit` / `test:component` / `test:integration` / `test:contract` / `test:runtime-schema` | 통과 — 2,883 / 270 / 189 / 24 / 56 | +| `verify:documentation` | **실패(환경 조건)** — desktop의 옆 백엔드 checkout이 `ef947e5`이고 커밋 안 한 변경이 있어 pin `45d2a478`과 다르다. 그 트리에 없는 경로 5개 문서. 옆 checkout이 없는 임시 worktree에서 node로 직접 돌리면 `PASS_SCOPED`(짝 repo 참조 17개 미검증). 기계마다 결과가 다른 것 자체는 12-02 | +| `check:adapter-inventory`, `check:ci` | 통과 | + +메인 세션이 같은 커밋에서 낸 결과(001~012·020 통과, 013의 test:system 18/114 실패, 나머지 7개 통과)와 같다. 그 결과를 가져다 쓰지 않고 다시 돌렸다. + +### 11.2 영역 분할 (2026-11-03 README 10.2절 재사용) + +| 번호 | 영역 | 문서 | 새 발견 | +|---|---|---|---| +| 01 | adapters: browser-transfer | [01-adapters-browser-transfer.md](01-adapters-browser-transfer.md) | 4 | +| 02 | adapters: browser-files·cache·cross-context | [02-adapters-browser-files-cache.md](02-adapters-browser-files-cache.md) | 4 | +| 03 | adapters: http·state | [03-adapters-http-state.md](03-adapters-http-state.md) | 2 | +| 04 | adapters: realtime | [04-adapters-realtime.md](04-adapters-realtime.md) | 3 | +| 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) | 3 | +| 07 | contracts | [07-contracts.md](07-contracts.md) | 2 | +| 08 | presentation | [08-presentation.md](08-presentation.md) | 4 | +| 09 | app core·bootstrap·features | [09-app-core.md](09-app-core.md) | 3 | +| 10 | tests: 빠른 계층 | [10-tests-fast-layers.md](10-tests-fast-layers.md) | 2 (+ 10-03 오케스트레이터) | +| 11 | tests: 브라우저·릴리스·규모 | [11-tests-browser-release-scale.md](11-tests-browser-release-scale.md) | 2 (11-02는 12-01로 합침) | +| 12 | guardrails·CI | [12-guardrails-ci.md](12-guardrails-ci.md) | 3 (+ 12-04 오케스트레이터) | +| 13 | build·release·supply chain | [13-build-release-supply-chain.md](13-build-release-supply-chain.md) | 2 | +| 14 | 템플릿·제품 문서 | [14-template-product-docs.md](14-template-product-docs.md) | 3 | +| 15 | 성능 실측·최적화 | [15-performance.md](15-performance.md) | 5 | +| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | [16-structure-patterns.md](16-structure-patterns.md) | 4 | + +### 11.3 합친 중복 + +| 대표 | 같은 결함 | 이유 | +|---|---|---| +| 12-01 | 11-02 | 같은 사전 점검과 같은 18건 실패. 11은 test 쪽, 12는 러너 요구 쪽을 봤다 | + +관련은 있지만 따로 센 것: 07-01과 16-02(둘 다 pin이 `http-contract.md`만 본다. 07-01은 답 표 JSON, 16-02는 생성기가 옮긴 사실 넷으로 결함 위치가 다르다). 15-03은 지난 §14.7 "남은 문제"에 적혀 있었지만 색인에 없던 것이라 새 발견으로 셌다. + +### 11.4 실행 방식과 안전 사항 + +- 처음에는 영역 에이전트가 desktop checkout 하나에서 공유 잠금 아래 각자 실행했다(helper `exp.sh`: 잠금, 시작 전 깨끗함 확인, 끝난 뒤 되돌림). 19:40에 30여 개 실행이 잠금 줄에 섰다. 메인 세션과 사용자의 결정("필요할 때만, 묶어서, 실행마다 환경을 되돌린다")에 따라 19:55에 줄에 선 32건을 취소하고 helper를 닫았다. 취소된 실행은 잠금을 얻지 못해 checkout을 건드리지 않았다. 그 전에 끝난 실행 15건은 모두 `restored: clean`을 찍었다. +- 그 뒤 리뷰어는 코드와 게이트 출력(읽기 전용 snapshot `desktop:/tmp/claude-gates/r4/snap/`)만으로 판정하고, 더 필요한 실험을 목록으로 냈다. 오케스트레이터가 게이트가 끝난 뒤 78항목을 두 묶음으로 하나씩 돌렸다. 항목마다 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지웠다(node_modules 유지). 78항목 모두 `restore=clean`, 끝에 `git status` 비어 있음, branch `fix/maturity-review-2026-11-03`, head `8a44226`. +- 같은 변이는 한 번만 돌렸다. 08-R4는 03-R07과 같은 변이라 그 결과를 썼다. 15-R2는 바로 앞 15-R1이 만든 `dist/`를 썼다. +- 이 방식이 필요했던 이유가 템플릿 결함이다(12-04). + +### 11.5 오케스트레이터 자신의 실수 + +| 실수 | 결과 | 원인 | +|---|---|---| +| 처음에 영역 에이전트 16개가 각자 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 같은 빌드·테스트 중복. 32건 취소 | 실행 비용을 영역마다 따로 셈했다. 공용 출력 경로 때문에 병렬이 불가능하다는 것을 먼저 보지 않았다 | +| `verify:documentation`을 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌렸다 | pnpm이 node_modules 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효. 배치에서 node로 직접 다시 돌렸다(00-R2) | 연결한 node_modules를 pnpm이 자기 것으로 보지 않았다 | +| 취소 통지에서 16 영역의 `16-mut`도 취소됐다고 적었다 | 실제로는 19:41에 돌아 `restored: clean`이었다(16 영역이 정정) | 취소 목록을 프로세스 이름으로만 셌다 | +| 배치 진행 감시(Monitor)가 30분 동안 아무것도 알리지 않았다 | 진행은 직접 조회로 확인했다 | awk 입력 버퍼링 | + +## 12. 28개 관점 판정 (36.2) + +판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 한 영역이라도 X면 X다(35.7절). 이번에는 X를 준 영역이 없다. 21번만 오케스트레이터가 X로 판정했다. 각 영역의 목표·확인 통제와 증거는 영역 문서 4절에 있다. + +| 번호 | 관점 | 영역 01~16 | 종합 | 종합 판정의 근거·잔여 위험 | +|---|---|---|---|---| +| 1 | 코드 성숙도 | `OPPOPPOPP>>->>O>` | P | 판정 규칙이 한 모듈과 선언 목록으로 모였다(03). 1103/05-01 purge 집계 시점, 08-04 저장 버튼 | +| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>OP` | P | `check:architecture` 통과. 0929/12-03(층 밖 폴더로 adapter에 닿음)은 12-R3에서 여전히 통과한다 | +| 3 | 변경 용이성 | `OOPPPPOPPPPPPPPP` | P | 09-01 제품 확장 지점 탐침, 16-01 기능마다 추적 파일 둘 변경, 13-02 제품 gate를 release에 묶을 자리 없음 | +| 4 | 인지 부하 | `PPPPPPOPPPPPPPPP` | P | 짝 백엔드 사실이 여러 손 사본에 흩어졌다(6절 원인 2) | +| 5 | 위험 가시성 | `PPPPPPOPPPPPPPPP` | P | 13-01 release 실패 이유가 사라진다. 12-01 전제가 적혀 있지 않다. 15-04 기능 라우트 첫 진입을 아무도 재지 않는다 | +| 6 | 실패 성숙도 | `PPPPPPOPPPO-O>>>` | P | 1103/03-01 고쳐짐. 01-01 202 `REJECTED` 오판, 04-02 던짐을 서버 장애로 봄 | +| 7 | 운영 성숙도 | `PPPPPP>>P-P>P>P-` | P | 13-01, 02-01 진단 없음 | +| 8 | 디버깅 가능성 | `PPOPPPPPPOPPPOOP` | P | 12-01 원인 없는 18건, 02-01, 01-03 `traceId` 버림, 09-03 원인 중복 | +| 9 | 유지보수 성숙도 | `PPPPPPOPPPPPPPPP` | P | 14-01·1103/14-01 낡은 문장, 04-03 VD-28, 15-03 중복 목록 | +| 10 | 테스트 성숙도 | `PPOPPPPPPPPPPPPP` | P | 변이 검출이 크게 늘었다(5절). 남은 틈: 11-01 fixture 결과 버림, 04-01, 10-02, 02-04, 1103/05-01 테스트가 객체 0~1개만 씀 | +| 11 | 데이터 성숙도 | `OP-OPO>-P>-->-->` | P | 1103/05-01 계정 삭제 purge 누락(OPFS 개인 파일 제품에는 사용 보류) | +| 12 | 동시성 성숙도 | `POPOPO-PPOP->->>` | P | 1103/05-01 다른 탭 put, 0929/03-03 같은 입력 재제출, 12-04 한 checkout 두 실행 | +| 13 | 확장성 | `PO>P?PO>P>P>>>PP` | P | 쓰기 기능 둘이 예산 안(277 B 남음). 15-02 대조 허용치가 여유보다 크다 | +| 14 | 성능 성숙도 | `PP>P?P>O>P>?P>P>` | P | lab 146 ms 통과. 15-04 기능 라우트 첫 진입 406 ms 미측정, 15-01·15-05 작은 shift | +| 15 | 보안 성숙도 | `OPOOPOOPPO>OP>>>` | P | 1103/13-03 advisory 결정 대기, 05-01 저장 키, 09-02 401 미전달 | +| 16 | 의존성 성숙도 | `O->O-P>>->PPPPO>` | P | 1103/13-03, 13-01로 advisory 신호가 안 보임 | +| 17 | API / Contract 성숙도 | `PPPPPPPPPP>POP>P` | P | 01-01·01-02 Fileserver 판정, 07-01 답 표 미대조, 16-02, 03-01·03-02 | +| 18 | 배포 성숙도 | `OP>PPP>O>>P>P>O>` | P | 실제 nginx probe 통과(13-R02). 13-02 제품 gate가 배포를 막지 못함 | +| 19 | 설정 성숙도 | `PPPPPPPPOPPPPPOO` | P | 14-02 매뉴얼 설정 예시 실패, 1103/07-04 | +| 20 | 개발자 경험 | `P>PP>PPPPPPPPPPP` | P | 기능 추가가 브라우저 게이트까지 통과(16-R1). 12-04 병렬 실행 불가, 16-04 예시 이름 충돌, 14-02 | +| 21 | Guardrail 성숙도 | `PPPPPPPOPPPPPPPP` | **X** | **오케스트레이터 판정.** 영역은 모두 P다. 그러나 merge 게이트 둘이 지원 구성에서 코드와 무관하게 틀린 답을 낸다. FE-GATE-005는 제품 capability를 쓰는 다운스트림에서 항상 실패한다(09-01, 두 다운스트림 해당). FE-GATE-013은 사전 점검 PASS 뒤 호스트 원인으로 실패한다(12-01, 직접 재현). 지난 라운드에 같은 모양(02-06)으로 X를 줬다. 13-02(제품 gate가 release를 막지 못함), 11-01(fixture 결과 버림이 안 잡힘)도 이 관점이다 | +| 22 | 추상화 성숙도 | `OPPPPOOPPPPO>>>P` | P | 04-02 poll `execute` 계약, 1103/04-01 남은 틈(descriptor 미전달) | +| 23 | 일관성 | `PPOPPPPPPPPPPPPP` | P | 01-02 Fileserver 효과 표가 V3 표와 다르다 | +| 24 | 네이밍 / 의미 성숙도 | `PPPPPPPPPOPPPPPP` | P | 08-02 "변경됨으로 확인" 뒤 무안내, 04-02 `PROVIDER_UNAVAILABLE` 뜻 | +| 25 | 조직 확장성 | `-->-?-OPP->P-P>P` | P | 16-01 기능 브랜치끼리 같은 줄 충돌, 12-04 | +| 26 | Ownership 성숙도 | `P>P-?PP?>PPPPP>>` | P | 1103/01-01 백엔드 매뉴얼 몫, 13-02 | +| 27 | 삭제 가능성 | `POOOPOO>PPPP>P>P` | P | 14-01 예제 기능 제거 뒤 문서 검사 실패, 16-04 제거 드릴의 이름 충돌, 10-01 샘플과 함께 사라지는 플랫폼 테스트 | +| 28 | 회복 가능성 | `PPPPPP-PP-P-P>>>` | P | 02-02 rollback 대상 회복 길 없음, 1103/03-01 회복 필요 응답 뒤 재전송 버튼 | + +## 13. 지난 발견 상태 (96건, `8a44226`) + +1103 색인 95건 + 차단 항목에만 있던 0929/03-03. "1103 §14.4"는 지난 README 14.4절의 판정이다("그 밖의 81건"은 고침으로 셌다). **(판정 정정)**은 §14.4가 고침이라 했지만 지금 일부인 것이다. 근거는 링크한 영역 문서 2절에 있다. 각 영역 문서 2절에는 1101·0929 이월 항목도 있다. + +| ID | 지난 심각도·우선순위 | 1103 §14.4 | 지금 상태 | 남은 것·근거 | +|---|---|---|---|---| +| [1103/01-01](01-adapters-browser-transfer.md) | High·P1 | 고침 | 일부 **(판정 정정)** | Fileserver client와 문서는 들어왔다. 백엔드 매뉴얼에 안내가 없고, 실제 짝 백엔드로 올려 보지 않았다. MSW가 백엔드 문서에서 와서 202 `REJECTED`를 놓쳤다(새 01-01). 남은 결함은 새 01-01·01-02로 센다 | +| [1103/03-01](03-adapters-http-state.md) | High·P1 | 고침 | 일부 **(판정 정정)** | 완료 기준 넷은 충족했다(영역 03 변이 19개 검출). 폼 쪽(08 영역): 선언한 거절의 이유가 화면에 안 보이고 기능이 문구를 더할 자리가 없다. KEYED 쓰기에서 500 `IDEMPOTENCY_RECOVERY_REQUIRED` 뒤 재전송 버튼이 남아 같은 키를 끝없이 보낸다. 남은 부분 Medium·P2 | +| [1103/02-06](02-adapters-browser-files-cache.md) | Medium·P1 | 고침 | 고쳐짐 | FE-GATE-020 rc=0(merge-48). 06-05 포함 | +| [1103/09-02](09-app-core.md) | Medium·P1 | 고침 | 고쳐짐 | 수정(탐침)이 새 09-01을 만들었다 | +| [1103/09-03](09-app-core.md) | Medium·P1 | 일부 | 일부 | 실제 Keycloak·Redis 연동 미확인. 백엔드 realm에 public client가 없다. 쿠키 recipe로 이으면 401이 owner에 안 닿는다(새 09-02) | +| [1103/11-02](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | 코드는 들어왔다. 빈 러너에서 FE-GATE-008 완료 기준을 돌리지 않았다 | +| [1103/11-06](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | | +| [1103/11-07](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | | +| [1103/11-08](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 검사 약화 없음(13-R01·R03~R06, 3절) | +| [1103/11-09](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 변이 R1·R2·R4·R5 검출. 검사 약화 없음(3절) | +| [1103/11-10](11-tests-browser-release-scale.md) | Medium·P1 | 고침 | 고쳐짐 | 400 px 재현: 수정 있음 통과(R6), 되돌림 실패(R7) | +| [1103/16-09](16-structure-patterns.md) | Medium·P1 | 고침 | 고쳐짐 | 수정 방식이 새 16-01을 만들었다 | +| [1103/12-01](12-guardrails-ci.md) | Medium·P1 | 고침 | 고쳐짐 | 기능 2개로 `test:visual` 6/6(12-R1). 셸 CSS 변경이 여전히 실패하는지는 미검증(12-R2 변이가 화면을 안 바꿈) | +| [1103/12-09](12-guardrails-ci.md) | Medium·P1 | 고침 | 고쳐짐 | FE-GATE-005 rc=0(merge-48) | +| [1103/13-01](13-build-release-supply-chain.md) | Medium·P1 | 고침 | 고쳐짐 | | +| [1103/13-03](13-build-release-supply-chain.md) | Medium·P1 | 일부 | 일부 | 결정 대기: 운영 high 2건(zod GHSA-mrhx, react-router GHSA-qwww). 그 신호가 실제 run에서 안 보인다(새 13-01) | +| [1103/14-01](14-template-product-docs.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | 초기 파일 상한이 `CHANGELOG.md:107`·`:216`은 26, 예산 파일은 32. 알려진 제한이 `f887817` 기준. FE-GATE-017을 merge 게이트로 적는다 | +| [1103/14-02](14-template-product-docs.md) | Medium·P1 | 고침 | 일부 **(판정 정정)** | "옮기기 전" 목록이 memento 템플릿 src 변경 26개 중 7개, tech-log 38개 중 11개만 다룬다. 제품 소유 자리가 없는 변경(memento `if-match`)이 있다 | +| [1103/15-01](15-performance.md) | Medium·P1 | 고침 | 고쳐짐 | lab 146 ms(지난 227 ms) | +| [1103/01-02](01-adapters-browser-transfer.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/02-01](02-adapters-browser-files-cache.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/03-02](03-adapters-http-state.md) | Medium·P2 | 일부 | 일부 | bulk `results`는 지원하지 않는다(문서화) | +| [1103/03-03](03-adapters-http-state.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/04-01](04-adapters-realtime.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/04-02](04-adapters-realtime.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/05-01](05-adapters-storage-kernel.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 다른 탭의 새 파일 put이 purge의 목록과 journal 집계(`opfs-byte-store-adapter.ts:821`→`:899`) 사이에 끝나면 놓치고 `COMPLETED`를 낸다. 객체 3·8개에서 메모리 20/20, Chromium 6/6. 테스트는 객체 0~1개만 쓴다. Medium·P2(OPFS에 개인 파일을 두는 제품은 P1) | +| [1103/07-01](07-contracts.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/09-01](09-app-core.md) | Medium·P2 | 고침 | 고쳐짐 | 수정이 새 09-02를 만들었다 | +| [1103/09-04](09-app-core.md) | Medium·P2 | 일부 | 일부 | 결정 대기(`EXAMPLES_PLATFORM`). 예제 기능을 빼면 브라우저 spec 8개 수정 | +| [1103/09-05](09-app-core.md) | Medium·P2 | 일부 | 일부 | SW `blockers`·`observe` 연결이 템플릿 파일에 남았다 | +| [1103/09-06](09-app-core.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/10-01](10-tests-fast-layers.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/10-02](10-tests-fast-layers.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/11-01](11-tests-browser-release-scale.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 목록 라우트는 완료 기준 충족(11-R8b·R8c). 상세 라우트는 실패 화면으로 검사되는데 `a11y.json`은 passed | +| [1103/12-02](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/12-06](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/12-07](12-guardrails-ci.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/13-02](13-build-release-supply-chain.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/14-03](14-template-product-docs.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/14-04](14-template-product-docs.md) | Medium·P2 | 고침 | 고쳐짐 | 지난 판정 정정: FE-GATE-017은 merge가 아니라 문서 단계다. 결함 자체는 맞았다 | +| [1103/16-01](16-structure-patterns.md) | Medium·P2 | 고침 | 일부 **(판정 정정)** | 읽기만 있는 기여나 `refusedBeforeWrite` 없는 쓰기에서 Envelope 줄을 모두 빼면 조립이 통과한다(코드 추론). 지난 완료 기준("줄을 지우면 `check:types` 실패")은 충족하지 않았다 | +| [1103/16-02](16-structure-patterns.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/16-03](16-structure-patterns.md) | Medium·P2 | 고침 | 고쳐짐 | | +| [1103/03-04](03-adapters-http-state.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/05-04](05-adapters-storage-kernel.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/08-02](08-presentation.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/09-07](09-app-core.md) | Low·P2 | 고침 | 고쳐짐 | 수정이 새 09-03을 만들었다 | +| [1103/10-04](10-tests-fast-layers.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/11-03](11-tests-browser-release-scale.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | 코드는 들어왔다. desktop에서는 호스트 원인(12-01)으로 `test:system` 완료 기준을 돌릴 수 없다 | +| [1103/11-05](11-tests-browser-release-scale.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/12-04](12-guardrails-ci.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/14-05](14-template-product-docs.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/15-02](15-performance.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | `CHANGELOG.md:107`·`:216`이 파일 상한을 26으로 적는다(14-01과 같은 줄) | +| [1103/15-03](15-performance.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/16-04](16-structure-patterns.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/16-05](16-structure-patterns.md) | Low·P2 | 고침 | 일부 **(판정 정정)** | `BoundMutation.operationId`가 아직 `string`이다(`server-state.ts:305`) | +| [1103/16-07](16-structure-patterns.md) | Low·P2 | 고침 | 고쳐짐 | | +| [1103/01-03](01-adapters-browser-transfer.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/02-02](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/02-03](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/02-04](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/02-05](02-adapters-browser-files-cache.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/03-05](03-adapters-http-state.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/03-06](03-adapters-http-state.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/03-07](03-adapters-http-state.md) | Low·P3 | 일부 | 일부 | 결정 대기(백엔드 목록 GET) | +| [1103/04-04](04-adapters-realtime.md) | Low·P3 | 고침 | 고쳐짐 | 수정이 새 04-01·04-02를 만들었다 | +| [1103/04-06](04-adapters-realtime.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/05-02](05-adapters-storage-kernel.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/05-03](05-adapters-storage-kernel.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/06-01](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/06-02](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/06-03](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/06-04](06-adapters-service-worker-push.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/07-02](07-contracts.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/07-03](07-contracts.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/07-04](07-contracts.md) | Low·P3 | 일부 | 일부 | 부팅 오류 `CONFIG_SECRET_NAME_REJECTED`에 키 이름이 없다 | +| [1103/08-03](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/08-04](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/08-05](08-presentation.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/09-08](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/09-09](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/09-10](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/09-11](09-app-core.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/11-04](11-tests-browser-release-scale.md) | Low·P3 | 고침 | 일부 **(판정 정정)** | 11-03과 같다 | +| [1103/12-05](12-guardrails-ci.md) | Low·P3 | 일부 | 일부 | 지운 심볼 이름과 docs/README.md 1절 밖 문서는 검사하지 않는다 | +| [1103/12-08](12-guardrails-ci.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/13-04](13-build-release-supply-chain.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/13-05](13-build-release-supply-chain.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/14-06](14-template-product-docs.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/15-04](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/15-05](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/15-06](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/15-07](15-performance.md) | Low·P3 | 고침 | 고쳐짐 | | +| [1103/16-06](16-structure-patterns.md) | Low·P3 | 일부 | 일부 | 라우트 계약 `title`·`navigationLabel`을 화면이 읽지 않는다 | +| [1103/16-08](16-structure-patterns.md) | Low·P3 | 고침 | 고쳐짐 | | +| [0929/03-03](03-adapters-http-state.md) | High·P1 | 고침 | 일부 **(판정 정정)** | 재전송 버튼과 hook은 키 없는 intent를 거절한다. 남은 것: 같은 입력을 다시 제출하면 hook이 키 없는 결과 불명 intent를 키 없이 다시 보낸다(`application-query.ts:557-561`, `:590-596`, 실험 X1 `keys=[null,null]`). 템플릿 폼(`use-app-form.ts:325`)과 페이지만 막는다. 손으로 만든 `AsyncState`는 버튼을 그린다(X3). 남은 부분 Medium·P2 | + +합계: 고쳐짐 74 · 일부 22 · 남음 0. 판정 정정 13건. + +## 14. 오케스트레이터 발견 + +메인 세션이 기록하라고 정한 두 가지다(2026-11-05 지시). 영역 문서가 없으므로 36.3 양식을 여기에 적는다. + +### 12-04 빌드·게이트가 고정 출력 경로와 고정 포트를 써서, 한 checkout에서 두 실행이 부딪힌다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 20, 25, 12, 10, 21 | +| 근거 | **포트:** e2e preview 4173(`playwright.config.ts:13`, `:19-21`), visual preview 4174(`playwright.visual.config.ts:34`, `:59-61`), capability dev server도 4174(`playwright.capabilities.config.ts:26`, `:37-39`), storybook 6006(`playwright.storybook.config.ts`), dev 5173. 넷 모두 `reuseExistingServer: false`라 두 번째 실행은 시작하지 못한다. dev 설정만 `reuseExistingServer: true`라 5173에 다른 서버가 떠 있으면 조용히 그 서버를 검사한다(`playwright.dev.config.ts:19-20`). **출력:** 빌드는 `dist/`를 비우고 다시 쓴다(`scripts/build-frontend.ts:18`, emptyOutDir). Playwright 결과는 `artifacts/tests/*/results`(`playwright.config.ts:6` 등), gate 로그는 `artifacts/quality/gates/FE-GATE-.txt`(`scripts/create-feature.ts:1752`)에 고정이다. `scripts/` 54개 파일이 `artifacts/` 고정 경로를 쓴다. 일부 테스트는 이미 임시 출력 경로를 쓴다(`tests/unit/build-environment-bundle.test.ts:33`). **실행(00-R1):** 다른 preview가 4173을 잡은 상태에서 e2e를 시작하자 `http://127.0.0.1:4173 is already used`로 rc=1. **리뷰 중 실제로 일어남:** 이 리뷰는 한 checkout에서 실행을 하나씩만 돌려야 해서 공유 잠금을 썼고, 19:40에 30여 건이 줄을 섰다(11.4절) | +| 발생 조건 | 한 checkout에서 두 실행이 겹칠 때. IDE 테스트와 터미널 게이트, 두 에이전트, 같은 기계의 두 worktree(포트만 충돌) | +| 영향 | 두 번째 실행이 포트 충돌로 실패한다. 겹친 빌드가 앞 실행의 `dist/`를 지워 앞 실행이 다른 빌드를 검사하거나, 증거 파일이 섞인다. CI 러너는 job마다 따로라 영향이 없다. 다운스트림의 로컬 개발과 에이전트 병렬 작업이 직렬이 된다 | +| 심각도·우선순위 | Medium · P2 — 사용자 피해는 없다. 변경·검증 비용을 반복해서 올린다(35.2 Medium). 출시를 막지는 않는다 | +| 통제·증거 | 목표 M2 / 확인 M0(실행 격리 장치 없음) · E3(00-R1) + E1 | +| 확실성과 남은 가정 | 포트 충돌은 실행으로 확인했다. 겹친 빌드가 앞 실행의 결과를 바꾸는 경우는 코드로만 확인했다 | +| 결정의 근거 | 고정 경로는 문서·게이트·증거 검사가 같은 파일을 찾게 한다. 그 대가로 실행 하나만 허용한다. 이 선택은 어디에도 적혀 있지 않다 | +| 최소 개선 방향 | 실행마다 출력·artifact 디렉터리를 따로 쓴다(임시 폴더 또는 run ID). 서버는 빈 포트를 고르고 Playwright `baseURL`에 env로 넘긴다. dev 설정의 `reuseExistingServer`를 끈다 | +| 대안 비교 | (a) 현상 유지 + "한 checkout에 한 실행"을 매뉴얼·README에 적는다: 비용 0, 병렬 불가는 그대로. (b) 포트만 빈 포트로: 충돌은 사라지지만 `dist/`·`artifacts/` 덮어쓰기가 남는다. (c) 출력·포트 모두 격리: 증거 경로를 읽는 검사(`ci:gate`, `check:test-evidence` 등)를 함께 바꿔야 한다 | +| 비용·부작용 | (c)는 증거 경로를 쓰는 스크립트 54개 파일과 workflow upload 경로를 손봐야 한다 | +| 재검토 조건 | 다운스트림이 병렬 에이전트나 IDE 테스트를 쓰기 시작할 때 | +| 완료 기준 | 한 checkout에서 FE-GATE-008과 FE-GATE-005(또는 FE-GATE-008 둘)를 동시에 돌려 둘 다 통과하고, 각자의 증거 파일이 섞이지 않는다 | +| 검증 방법 | 동시 실행 드릴 1회 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 10-03 판정 규칙의 변이 실험을 리뷰어가 손으로 만들고 checkout 전체를 잠가 돌린다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 10, 21, 20 | +| 근거 | 이번 라운드 변이는 모두 리뷰어가 sed·패치·스크립트로 만들었다. 02 영역 31개, 03 영역 19개, 07 영역 26종, 10 영역 20종, 13 영역 10개 등. 실행마다 checkout 전체를 잠그고 되돌렸다(11.4절, 12-04 때문). 같은 규칙의 변이를 라운드마다 다시 쓴다. 0929/10-04의 §10.8 검사 변이 L01은 네 라운드째 살아남는다(10 영역). 변이 결과는 리뷰 문서에만 남고 회귀를 지키지 않는다 | +| 발생 조건 | 리뷰나 수정 때 판정 규칙의 테스트 강도를 확인할 때마다 | +| 영향 | 리뷰 시간의 큰 몫이 변이 준비와 잠금 대기다. 결과를 라운드 사이에 비교할 수 없다 | +| 심각도·우선순위 | Low · P3 — 계약 위반은 아니다. 효과와 비용을 비교해 고를 개선이다 | +| 통제·증거 | 목표 M3 / 확인 M1(손 실험) · E3 | +| 최소 개선 방향 | 실행마다 sandbox 사본을 만드는 변이 도구(예: Stryker, vitest runner)를 판정 규칙 모듈에 한정해 들인다. 예: `backend-envelope.ts`, `http-execution-v3.ts` 판정부, `application-query.ts` 재전송, `public-response-cache-adapter.ts` 판정. 처음에는 merge 게이트가 아닌 수동·nightly로 돈다 | +| 대안 비교 | (a) 현상 유지: 리뷰마다 손 변이. (b) 변이 목록을 스크립트로 커밋해 다시 쓴다: 도구 없이 재현은 되지만 격리는 없다. (c) 변이 도구: 격리·재현·점수가 생기고, dev 의존성과 실행 시간이 든다 | +| 비용·부작용 | dev 의존성 추가(공급망 증거, `dependency-change-evidence.json`), 실행 시간, 생존 변이 관리. 구조 변경이라 이번 라운드에는 고치지 않는다 | +| 재검토 조건 | 다음 리뷰가 같은 변이를 다시 쓸 때 | +| 완료 기준 | 판정 규칙 모듈 하나에서 도구가 돌고, 생존 변이 목록이 리뷰 문서 대신 도구 출력으로 나온다 | +| 담당·기한·상태 | 미정 · 미정 · 신규(이번 라운드 조치 안 함) | + +## 15. 새 발견 색인 (48건) + +심각도·우선순위 순. 영역 문서에 36.3 양식이 있다(12-04·10-03은 14절). + +| ID | 심각도·우선순위 | 성격 | 내용 | 관련 관점 | 위치 | 합친 것 | +|---|---|---|---|---|---|---| +| [09-01](09-app-core.md) | Medium·P1 | 확인된 결함 | 제품 확장 타입 검사 탐침이 제품 소유 파일 둘을 덮어써, 기능이 제품 capability를 쓰는 다운스트림에서 FE-GATE-005가 실패한다 | 10, 21, 25, 3, 20, 13(제품 수 축) (30.3, 30.4) | `tests/unit/product-extension-typecheck.test.ts:41-83`, `:181-193`; `src/bootstrap/runtime-adapters.ts:689-697` | | +| [12-01](12-guardrails-ci.md) | Medium·P1 | 확인된 결함 | FE-GATE-013의 user namespace 전제가 요구 목록·사전 점검에 없어, 이 desktop에서 사전 점검 PASS 뒤 provider 테스트 18건이 bwrap 원문 오류로 실패한다 | 21, 19, 20, 8, 5 | `scripts/check-system-test-prerequisites.ts:15-38`, `scripts/run-and-validate-provider.ts:254-256`, `docs/operations/ci-quality-gates.md:181-185` | 11-02(같은 결함, 영역 11) | +| [13-01](13-build-release-supply-chain.md) | Medium·P1 | 확인된 결함 | `immutable_build`가 FE-GATE-015·027의 gate 로그와 advisory 기록을 올리지 않는다. 그래서 release 실패 이유와 13-03 신호가 실제 workflow에서 사라진다 | 8, 5, 7, 16, 18 | `.gitea/workflows/quality-gates.yml:122-207`, `scripts/run-ci-gate.ts:148-150`, `:209-213`, `:243-249`, `scripts/contracts/ci-gates.ts:947` | | +| [01-01](01-adapters-browser-transfer.md) | Medium·P2 | 확인된 결함 | Fileserver client가 짝 백엔드의 202 `REJECTED`(빈 파일 하나로 닿음)를 `SCHEMA_MISMATCH`로 읽고, 매뉴얼은 202를 "아직 검사 중"으로 적는다 | 17, 6, 8, 20, 10, 24 | `src/adapters/http/fileserver-upload.ts:194`, `:624-631`; `docs/manual/02-decision-tables.md:311`; 백엔드 `FileUploadController.java:195-200`, `FinalizeUploadApplicationUseCase.java:300-343` | | +| [01-02](01-adapters-browser-transfer.md) | Medium·P2 | 구조적 위험 | 504 `TRANSFER_TIMEOUT`을 `NOT_APPLIED`·5초 뒤 재시도로 주지만 백엔드는 작업 단계와 상관없이 낸다. 효과 표가 V3 표·계약 문서 6.1과 갈라졌고 pin 밖이다 | 6, 28, 17, 23, 9, 21, 5 | `src/adapters/http/fileserver-upload.ts:154-170`, `:691-704`; `src/adapters/http/backend-envelope.ts:249-254`; 백엔드 `BlockingTransferExecutor.java:64-79` | | +| [02-01](02-adapters-browser-files-cache.md) | Medium·P2 | 확인된 결함 | 제품 scope closer가 던지면 scope가 진단 없이 `FAILED`로 멈추고 `label`은 쓰이지 않는다 | 8, 7, 5, 17, 6 | `src/bootstrap/runtime-adapters.ts:409-423`, `src/adapters/query-cache/server-state-scope-runtime.ts:136-171`, `src/bootstrap/product-composition-contract.ts:100-103` | | +| [09-02](09-app-core.md) | Medium·P2 | 확인된 결함 | Redis session 모드를 recipe·매뉴얼대로 이으면 서버 401이 세션 owner에 닿지 않는다(1103/09-01 수정과 1103/09-03 recipe 불일치) | 6, 28, 15, 17, 22, 4, 5, 10, 9 (32 세션 만료, 30.5) | `src/bootstrap/runtime-adapters.ts:583-591`; `recipes/session-owners/cookie-session-owner.ts:33`, `:179`; `docs/manual/04-paired-backend-session.md:186`, `:238-249` | | +| [12-03](12-guardrails-ci.md) | Medium·P2 | 확인된 결함 | `CLAUDE.md` 리뷰 게이트 목록이 merge stage와 달라 merge 명령 87개 중 10개만 돌고 7개 게이트와 증거 검사가 빠진다 | 21, 5, 26, 23, 10 | `CLAUDE.md:23`, `config/ci/gates.json:2236-2256` | | +| [12-04](#14-오케스트레이터-발견) | Medium·P2 | 확인된 결함 | 빌드·게이트가 고정 출력 경로(`dist/`, `artifacts/`)와 고정 포트(4173·4174·5173·6006)를 써서, 한 checkout에서 두 실행이 부딪힌다 | 20, 25, 12, 10, 21 | `playwright.config.ts:6`, `:13`, `:19-21`; `playwright.visual.config.ts:34`, `:59-61`; `playwright.capabilities.config.ts:26`, `:37-39`; `playwright.dev.config.ts:19-20`; `scripts/build-frontend.ts:18` | | +| [13-02](13-build-release-supply-chain.md) | Medium·P2 | 구조적 위험 | 제품 merge 검사가 실패해도 같은 run의 release·승격·배포가 진행된다. job 그래프가 고정이라 제품이 막을 수도 없다 | 18, 21, 26, 3, 24 | `scripts/generate-ci-workflow.ts:129-157`, `scripts/contracts/ci-gates.ts:926-933`, `docs/operations/ci-quality-gates.md:377-378` | | +| [14-01](14-template-product-docs.md) | Medium·P2 | 확인된 결함 | CHANGELOG 6단계대로 예제 기능을 지우면 문서 검사(FE-GATE-005 포함)와 안내한 드릴이 실패하고, `PRODUCT.md`는 지울 수 없다고 적는다 | 27, 30.5, 30.4, 9, 20, 10 | `docs/architecture/starter-experience.md:105-111`, `CHANGELOG.md:103`, `tests/unit/hosting-probe.test.ts:248`, `PRODUCT.md:33` | | +| [11-01](11-tests-browser-release-scale.md) | Low·P2 | 구조적 위험 | preload 검사 증명 spec이 tracker만 증명해서, strict fixture가 그 결과를 버려도(11-R3, 9건 통과·안 쓴 preload probe 통과) 커밋된 test가 실패하지 않는다. 3번 test는 지연시킬 청크가 없으면 조용히 평범한 방문이 된다 | 10, 21, 5 | `tests/support/browser/strict-browser-test.ts:62`, `tests/e2e/preload-use.spec.ts:45-46`, `:105-126` | | +| [12-02](12-guardrails-ci.md) | Low·P2 | 확인된 결함 | `verify:documentation`이 짝 백엔드 참조를 pin이 아니라 옆 checkout 작업 트리에서 찾아 기계마다 결과가 다르다(desktop rc=1) | 21, 17, 20, 23, 8 | `scripts/verify-documentation-readiness.ts:214-215`, `:308-316` | | +| [14-02](14-template-product-docs.md) | Low·P2 | 확인된 결함 | 매뉴얼 04 §3.2의 제품 설정 키 예시에 `defaultValue`가 없어 `check:types`·`test:unit`이 실패한다 | 20, 19, 9 | `docs/manual/04-paired-backend-session.md:127-130`, `src/contracts/env.ts:37-42` | | +| [15-04](15-performance.md) | Low·P2 | 구조적 위험 | lab은 플랫폼 화면 하나만 잰다. 기능 라우트 첫 진입은 lab 조건 406 ms(요청 두 묶음)인데 어느 게이트도 재지 않는다 | 14, 21, 13, 10 | `scripts/test-performance.ts:46`, `src/presentation/routes/app-router.tsx:510-538`, `CHANGELOG.md:269` | | +| [16-01](16-structure-patterns.md) | Low·P2 | 구조적 위험 | 기능 하나를 더하면 추적 파일 `public/release-manifest.json`(자동)과 초기 JS 기록(명령)이 바뀌고, 03 문서·정본 표는 이를 말하지 않으며, 기능 브랜치 둘이 같은 줄에서 충돌한다 | 25, 3, 9, 20, 23, 27 | `scripts/create-feature.ts:1753-1754, 1787-1796`, `docs/manual/03-outside-feature-folder.md:22`, `docs/architecture/starter-experience.md:215-226` | | +| [16-03](16-structure-patterns.md) | Low·P2 | 구조적 위험 | 생성 기능을 설치한 상태로 브라우저 merge 게이트(FE-GATE-008·009)를 도는 장치가 없다 | 10, 21, 20, 5 | `scripts/lib/feature-scaffold-drill.ts:18-37` | | +| [16-04](16-structure-patterns.md) | Low·P2 | 확인된 결함 | 제품 기능 제거 드릴의 잔여 검사가 템플릿 테스트의 글자를 잔여로 잡아, 매뉴얼 예시 이름 `invoice-feature`로 만든 기능의 11단계가 실패한다. 안내는 템플릿 파일 수정이다 | 27, 20, 21, 24, 8 | `scripts/test-sample-removal.ts:113-120, 415-425`, `tests/unit/create-feature.test.ts:53`, `docs/manual/01-add-a-feature.md:94, 626`, `docs/manual/reference/errors.md:197` | | +| [01-03](01-adapters-browser-transfer.md) | Low·P3 | 확인된 결함 | Fileserver client가 실패 Envelope의 `traceId`를 버린다 | 8, 23, 7 | `src/adapters/http/fileserver-upload.ts:638-640` | | +| [01-04](01-adapters-browser-transfer.md) | Low·P3 | 확인된 결함 | Fileserver client 규칙 셋(5xx 두 code, 바이트 비례 deadline, 읽기 전 크기 거절)을 테스트가 고정하지 않는다 | 10, 21, 6, 14 | `src/adapters/http/fileserver-upload.ts:163-170`, `:211-215`, `:424-428` | | +| [02-02](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | 계속 읽히지 않는 캐시 본문은 다시 stage해도 고쳐지지 않고 rollback 대상은 회복 길이 없다 | 28, 6, 24, 11, 18 | `src/adapters/cache-storage/public-response-cache-adapter.ts:492-497`, `:1083-1088`, `:1139-1144` | | +| [02-03](02-adapters-browser-files-cache.md) | Low·P3 | 확인된 결함 | 세션 레시피 주석이 매뉴얼이 막는 보강 방식을 가리키고 capability 전달은 테스트 밖이다 | 9, 20, 17, 10 | `recipes/frontend-capabilities/browser-file-session-capability.ts:21-30`, `tests/recipes/browser-file-session-capability.test.ts:142` | | +| [02-04](02-adapters-browser-files-cache.md) | Low·P3 | 구조적 위험 | 1103/02-02의 손상 code 목록 경계 변이 5개가 살아남는다 | 10, 28, 6 | `src/adapters/cache-storage/public-response-cache-adapter.ts:1083-1088`, `tests/unit/public-response-cache-repair.test.ts:236-263`, `:320` | | +| [03-01](03-adapters-http-state.md) | Low·P3 | 구조적 위험 | `refusedBeforeWrite`가 6.1절의 "쓰기 뒤 가능" 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*`, `LOCK_ACQUISITION_TIMEOUT`)도 받는다 | 21, 6, 17, 5 | `src/contracts/external-contract-runtime.ts:608-646`, `src/adapters/http/backend-envelope.ts:317-327` | | +| [03-02](03-adapters-http-state.md) | Low·P3 | 개선 제안 | 백엔드 §4의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`이 답 표 밖이라 생성 쓰기에서 결과 불명이 된다 | 17, 6, 28, 9 | `config/contracts/backend-idempotency-answers.json`, `src/adapters/http/backend-envelope.ts:246-269`, `scripts/create-feature-write-slice.ts:298` | | +| [04-01](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | 서버 끊김 kind 변경 뒤 0929/04-01 회귀 테스트가 transport `OFFLINE` 경로를 지나지 않는다. 지운 두 줄을 되살려도 realtime 테스트가 모두 통과한다(04-R4) | 10, 21, 6, 28 | `tests/unit/realtime/realtime-reconnect-coordinator.test.ts:2095-2198`, `src/adapters/realtime/reconnect-coordinator.ts:111-117` | | +| [04-02](04-adapters-realtime.md) | Low·P3 | 구조적 위험 | poll `execute`의 던짐을 서버 장애로 보고 재시도해 조합 결함이 서버 장애·예산 소진으로 보인다 | 8, 24, 6, 7 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts:322-328`, `tests/unit/realtime/bounded-poll-coordinator.test.ts:906-948` | | +| [04-03](04-adapters-realtime.md) | Low·P3 | 확인된 결함 | VD-28·설계 3절이 지운 V2 poll 예산·`REST QUERY`로 poll 규칙을 적는다 | 9, 24, 17 | `docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md:117-118`, `:441-444` | | +| [05-01](05-adapters-storage-kernel.md) | Low·P3 | 확인된 결함 | OIDC PKCE recipe가 Web Storage 키를 registry 밖에서 글자 그대로 만들어 `APP_NAMESPACE`를 바꾸면 갈라진다 | 23, 17, 15, 9, 21 | `recipes/session-owners/oidc-pkce-session-owner.ts:43-44`, `src/contracts/storage-keys.ts:179-185`, `docs/contracts/compatibility.md:31` | | +| [06-01](06-adapters-service-worker-push.md) | Low·P3 | 확인된 결함 | 사전 캐시 수집이 `assets/` 밖 public 파일(`apple-touch-icon.png` 등)도 해시 자산으로 넣는다 | 18, 23, 5, 21 | `scripts/generate-service-worker-assets.ts:57-64`, `src/contracts/service-worker.ts:116` | | +| [06-02](06-adapters-service-worker-push.md) | Low·P3 | 구조적 위험 | 확장자별 MIME probe가 redirect 뒤 200을 통과시키고, 워커 없는 빌드에도 돈다. live 호출 줄을 지워도 테스트가 통과한다 | 21, 18, 10 | `scripts/lib/hosting-probe.ts:276-315`, `scripts/verify-hosting-headers.ts:119-120` | | +| [06-03](06-adapters-service-worker-push.md) | Low·P3 | 개선 제안 | SW 제어 아래 route import를 지키는 test가 없다. 11-09 허용으로 그 아래 preload 검사도 모두 꺼진다(허용이 워커 결함을 가리지는 않음) | 10, 28, 21 | `tests/e2e/service-worker-update.spec.ts:45-52`, `:267-276` | | +| [07-01](07-contracts.md) | Low·P3 | 구조적 위험 | 짝 백엔드 답 표 JSON이 pin한 백엔드 문서와 같은지 아무 검사도 보지 않고, 백엔드 변경은 게이트 밖 drift 스크립트만 알린다(desktop에서 비교 불가, worktree에서 skipped rc=0, 매뉴얼에 없음) | 17, 21, 10, 20, 26 | `tests/unit/backend-contract-pin.test.ts:76-79`, `scripts/check-backend-contract-drift.ts:30, 40-45, 60`, `config/contracts/backend-contract-pin.json:7` | | +| [07-02](07-contracts.md) | Low·P3 | 개선 제안 | 응답 스키마를 행과 함께 strict로 좁히는 변경이 FE-REG-SCHEMA에서 behavior-change로 통과하고 관련 테스트 25파일이 모두 통과한다(07-R1) | 17, 21, 23 | `config/contracts/registry-governance.json:288`, `scripts/lib/registry-compatibility.ts:346-351`, `tests/unit/schema-metadata-policy.test.ts:154-165` | | +| [08-01](08-presentation.md) | Low·P3 | 확인된 결함 | 실패 상태의 복구 버튼을 키보드로 누르면 일이 끝난 뒤 버튼이 사라지며 포커스가 `body`로 떨어진다 | 1, 6, 10, 28 | `src/presentation/forms/use-app-form.ts:91-101`, `:176-195`; `src/features/reference-feature/presentation/reference-resource-form-page.tsx:141-183` | | +| [08-02](08-presentation.md) | Low·P3 | 확인된 결함 | 생성 기능 폼이 "변경됨으로 확인" 뒤 아무것도 보이지 않고 입력을 비운다 | 24, 23, 20, 28 | `scripts/create-feature-write-slice.ts:703-721`, `:714` | | +| [08-03](08-presentation.md) | Low·P3 | 확인된 결함 | 홈 시작 링크가 런타임에 꺼진 기능의 라우트를 가리킨다(`b96d61d8`) | 23, 1, 10 | `src/presentation/pages/home-page.tsx:21-23` vs `src/presentation/layouts/app-shell.tsx:196-202` | | +| [08-04](08-presentation.md) | Low·P3 | 확인된 결함 | 다른 저장이 진행 중일 때 저장 버튼이 켜져 있지만 눌러도 반응이 없다(`2d5d41f8`) | 1, 24, 6 | `src/features/reference-feature/presentation/reference-resource-form-page.tsx:52-68`, `:124-131` | | +| [09-03](09-app-core.md) | Low·P3 | 확인된 결함 | 계약 조립 오류의 원인이 `check:registries` 출력에 두 번 나온다 | 8, 20, 23 | `src/contracts/external-contract-runtime.ts:293`; `scripts/check-registries.ts:158-163` | | +| [10-01](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 1103 수정이 더한 플랫폼 규칙 테스트 둘(`MAX_RETRY_ATTEMPTS` 전달, 복구 중 세션 대기)이 참조 샘플에 기대어, 샘플을 지우면 함께 사라지고 제거 드릴은 알리지 않는다 | 10, 27, 21, 3, 19 | `tests/features/reference-feature/reference-runtime-composition.test.ts:163-204`, `tests/unit/navigation-policy.test.ts:40-56`, `scripts/test-sample-removal.ts:130-161` | | +| [10-02](10-tests-fast-layers.md) | Low·P3 | 구조적 위험 | 실행기가 interaction signal에 단 abort listener 정리는 지워도 모든 테스트가 통과한다(호출자·scope 쪽만 고정) | 10, 12, 14, 21 | `src/adapters/http/http-execution-v3.ts:663`, `tests/unit/http-execution-v3.test.ts:764-805` | | +| [10-03](#14-오케스트레이터-발견) | Low·P3 | 개선 제안 | 판정 규칙의 변이 실험을 리뷰어가 손으로 만들고 checkout 전체를 잠가 돌린다. 실행마다 사본을 따로 쓰는 변이 도구(예: Stryker)로 옮길 수 있다 | 10, 21, 20 | 이번 라운드 6.3절, `docs/reviews/2026-11-05-maturity-review/*.md` 6절 | | +| [14-03](14-template-product-docs.md) | Low·P3 | 구조적 위험 | 참조 기능 경로 26줄을 백틱에서 빼 문서 검사 밖으로 냈다 | 21, 10, 9, 20 | `scripts/verify-documentation-readiness.ts:294-300`, `CHANGELOG.md:225`, `docs/manual/01-add-a-feature.md:8` | | +| [15-01](15-performance.md) | Low·P3 | 확인된 결함 | lab 대상 화면이 그린 뒤 릴리스 칸을 늘려 21 px 민다(shift 0.0046). lab은 클릭 입력 창이라 0을 내고 `/` 밖의 CLS는 아무도 보지 않는다 | 14, 21, 10, 5 | `src/presentation/examples/platform-overview-page.tsx:422-454`, `scripts/test-performance.ts:111-118`, `:148-152` | | +| [15-02](15-performance.md) | Low·P3 | 구조적 위험 | 초기 JS 기록 대조 허용 오차 1%(2,029 B)가 남은 여유(1,873 B)보다 크다 | 9, 21, 5, 13 | `scripts/scale/measure-feature-shape-growth.ts:227-246` | | +| [15-03](15-performance.md) | Low·P3 | 구조적 위험 | 측정용 빌드 입력 목록이 두 파일에 같은 내용으로 있다 | 9, 23, 3, 10 | `scripts/scale/measure-feature-shape-growth.ts:40-49`, `tests/unit/product-feature-selection-build.test.ts:22-31` | | +| [15-05](15-performance.md) | Low·P3 | 확인된 결함 | 홈 첫 렌더가 세로 스크롤바를 만들어 header를 15 px 민다(CLS 0.0002). 게이트는 스크롤바를 숨긴 Chromium이라 못 본다 | 14, 10, 21 | `src/presentation/styles/theme/base.css:1-71`, `scripts/test-performance.ts:186` | | +| [16-02](16-structure-patterns.md) | Low·P3 | 구조적 위험 | 쓰기 slice가 백엔드 생성기 템플릿의 사실 넷을 손으로 옮겼고, pin·drift 검사는 `http-contract.md`만 본다 | 17, 9, 21, 23 | `scripts/create-feature-write-slice.ts:58-59, 83-84`, `config/contracts/backend-contract-pin.json:6-7`, `scripts/check-backend-contract-drift.ts:60` | | -- 2.54.0 From 397664e4397a9594eefcdf02a59494c02e01fd19 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:05:52 +0900 Subject: [PATCH 2/5] =?UTF-8?q?test(features):=20=EC=A0=9C=ED=92=88=20?= =?UTF-8?q?=ED=99=95=EC=9E=A5=20=ED=83=80=EC=9E=85=20=EA=B2=80=EC=82=AC=20?= =?UTF-8?q?=ED=83=90=EC=B9=A8=EC=9D=B4=20=EC=A0=9C=ED=92=88=20=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=EC=9D=84=20=EB=8D=AE=EC=96=B4=EC=93=B0=EC=A7=80=20?= =?UTF-8?q?=EC=95=8A=EA=B3=A0=20=EB=8D=A7=EB=B6=99=EC=9D=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 tests/unit/product-extension-typecheck.test.ts(1103/09-02 탐침)는 저장소 복사본의 src/contracts/product-contracts.ts와 src/bootstrap/product-composition.ts를 탐침 내용으로 통째로 바꿔 쓴다. 탐침의 composeProduct는 typecheckProbeSettings 하나만 돌려준다. 제품이 자기 capability를 product-composition.ts에서 만들고 자기 기능의 needs에 적으면, 복사본에서는 그 값이 사라져 app 프로그램이 src/bootstrap/runtime-adapters.ts에서 TS2741로 실패한다. memento와 tech-log 모두 제품 capability를 쓰므로, 동기화 직후 FE-GATE-005가 코드와 무관하게 실패한다(리뷰 실험 09-probe-downstream). 고른 방법 - 탐침은 복사본의 product-contracts.ts·product-composition.ts를 같은 폴더의 typecheck-probe-product-contracts.ts· typecheck-probe-product-composition.ts로 옮긴다. 새 파일은 옮긴 모듈을 export *로 다시 내보낸다. 그리고 런타임 설정 필드, env 행, composeProduct 결과와 그 capabilities를 펼친 뒤 탐침의 키·행·capability만 더한다. 인증 프로필, credential provider, 선택 칸, session owner, 제품이 더한 다른 export는 그대로 남는다. - capability 타입은 저장소가 아니라 복사본의 product-capabilities.ts 끝에 덧붙인다. - 같은 함수로 "제품 capability를 기능에 주는 다운스트림"을 먼저 만들고 그 위에 탐침을 올리는 케이스를 더했다(describe 1105/09-01). 다운스트림 흉내도 덧붙이는 방식이라, 실제 다운스트림에서 이 테스트를 돌려도 그 제품의 파일을 지우지 않는다. 이름은 예약 접두사 typecheck-probe-downstream-*를 쓴다. - 예약 이름 검사는 기능 폴더에 더해 context 폴더와 옮길 파일 이름도 본다. 버린 대안 - 제품 파일이 출하 상태가 아니면 탐침을 건너뛴다(리뷰의 (나)). 다운스트림 상태의 타입 경로 확인을 잃고, 건너뛰기로 검사를 약하게 한다. - 다운스트림 흉내를 제품 파일 전체를 새로 쓰는 방식으로 만든다. 실제 다운스트림에서 이 테스트를 돌리면 그 제품의 capability를 지워 같은 TS2741이 다시 난다. 위험·한계 - 제품 파일의 export 이름(composeProduct, composeProductSessionOwner, PRODUCT_*)에 기댄다. 템플릿이 그 이름을 import하므로 계약이다. - credentialProviders와 인증 프로필은 Record라 빠져도 tsc가 모른다. 펼쳐서 남기지만 테스트로 증명하지는 않는다. - 탐침 context는 여전히 소유 앱을 template-app으로 고정한다. 앱 id를 바꾼 제품에서는 생성기가 멈출 수 있다(리뷰 09-01의 남은 가정, 실행 안 함). 이 커밋 범위 밖이다. - 케이스가 하나 늘어 이 파일의 tsc 실행이 3회에서 6회가 된다. 케이스별 제한 시간 120초는 그대로다. - 결함이 테스트 파일 안의 탐침에 있어서, 표준 RED 구성(커밋의 테스트 + 부모의 비테스트 파일)은 GREEN과 같다. RED는 커밋 위에 탐침을 부모처럼 덮어쓰게 되돌리는 patch를 적용해 본다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/product-extension-typecheck.test.ts, check:types, lint. RED patch를 적용하면 1105/09-01 케이스만 TS2741로 실패해야 한다. - 이 노트북에서는 실행하지 않았다. Refs: 1105/09-01 --- .../unit/product-extension-typecheck.test.ts | 296 ++++++++++++------ 1 file changed, 203 insertions(+), 93 deletions(-) diff --git a/tests/unit/product-extension-typecheck.test.ts b/tests/unit/product-extension-typecheck.test.ts index c12f3b0b..1d1319f9 100644 --- a/tests/unit/product-extension-typecheck.test.ts +++ b/tests/unit/product-extension-typecheck.test.ts @@ -1,6 +1,6 @@ import { spawnSync } from "node:child_process"; import { existsSync } from "node:fs"; -import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; @@ -23,72 +23,131 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture. * - a product runtime-config key with a `.default()`, which the template's * own tests must not have to spell out. * - * Only product-owned files and the feature's own directory are written. + * Only product-owned files, the product files kept next to them and the + * probe's own feature and context directories are written. * * The probe's names (`typecheck-probe-*`) are reserved for it: they are not - * the manual's example names, which a product may well use (1103 X2 #1). The - * capability type is appended to the product's own declaration, which a - * TypeScript interface merges, so a product that already declares - * capabilities keeps them. + * the manual's example names, which a product may well use (1103 X2 #1). + * + * 1105/09-01. The probe adds to the product's files and keeps everything they + * already declare and build. The capability type is appended to the + * product's own declaration, which a TypeScript interface merges. The + * product's `product-contracts.ts` and `product-composition.ts` move to + * `-product-*.ts` beside themselves; the probe's files re-export them + * and add only the probe's key, env row and capability on top. Writing those + * two files from scratch dropped the capabilities a product builds for its + * own features, so in such a product the app program failed with TS2741 in + * `src/bootstrap/runtime-adapters.ts`. */ +const PRODUCT_CAPABILITIES_FILE = "src/features/product-capabilities.ts"; +const PRODUCT_CONTRACTS_FILE = "src/contracts/product-contracts.ts"; +const PRODUCT_COMPOSITION_FILE = "src/bootstrap/product-composition.ts"; + +/** Every name one extension adds, derived from one reserved name. */ +function productExtension(name: string, camelName: string, constantName: string) { + return Object.freeze({ + featureId: `${name}-feature`, + contextId: `${name}-context`, + routePath: `${name}/*`, + messageKey: `${camelName}.title`, + capability: `${camelName}Settings`, + configKey: `${constantName}_PAGE_SIZE`, + keptContracts: `src/contracts/${name}-product-contracts.ts`, + keptComposition: `src/bootstrap/${name}-product-composition.ts`, + }); +} + +type ProductExtension = ReturnType; + +/** The probe itself. */ +const PROBE = productExtension("typecheck-probe", "typecheckProbe", "TYPECHECK_PROBE"); + +/** + * 1105/09-01. Stands in for a downstream's own capability and the feature that + * needs it. It is added the same way, so in a downstream it lands on top of + * the downstream's real product files too. + */ +const DOWNSTREAM = productExtension( + "typecheck-probe-downstream", + "typecheckProbeDownstream", + "TYPECHECK_PROBE_DOWNSTREAM", +); + /** Appended to the product's own `product-capabilities.ts`. */ -const PRODUCT_CAPABILITY_TYPES = ` +function capabilityType(extension: ProductExtension): string { + return ` export interface ProductFeaturePlatformCapabilities { - readonly typecheckProbeSettings: Readonly<{ pageSize(): number }>; + readonly ${extension.capability}: Readonly<{ pageSize(): number }>; } `; +} -const PRODUCT_CONTRACTS = `import { z } from "./zod.ts"; +/** Replaces `product-contracts.ts`; the product's own is kept beside it. */ +function productContracts(extension: ProductExtension): string { + const kept = `./${path.posix.basename(extension.keptContracts)}`; + return `import { + PRODUCT_ENV_REGISTRY as KEPT_PRODUCT_ENV_REGISTRY, + PRODUCT_RUNTIME_CONFIG_FIELDS as KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS, +} from "${kept}"; +import { z } from "./zod.ts"; + +/** + * Product-owned. Filled by the 1103/09-02 typecheck fixture on top of the + * product's own file, kept as ${kept} (1105/09-01). + */ +export * from "${kept}"; -/** Product-owned. Filled by the 1103/09-02 typecheck fixture. */ export const PRODUCT_RUNTIME_CONFIG_FIELDS = Object.freeze({ - TYPECHECK_PROBE_PAGE_SIZE: z.int().min(1).max(100).default(20), + ...KEPT_PRODUCT_RUNTIME_CONFIG_FIELDS, + ${extension.configKey}: z.int().min(1).max(100).default(20), }); export const PRODUCT_ENV_REGISTRY = Object.freeze({ - TYPECHECK_PROBE_PAGE_SIZE: { + ...KEPT_PRODUCT_ENV_REGISTRY, + ${extension.configKey}: { phase: "runtime", classification: "public", required: false, defaultValue: "20", }, } as const); - -export const PRODUCT_REST_AUTH_PROFILES = Object.freeze({}); `; - -const PRODUCT_COMPOSITION = `import type { - ProductComposition, - ProductCompositionContext, - ProductSessionOwner, - ProductSessionOwnerContext, -} from "./product-composition-contract.ts"; - -/** Product-owned. Filled by the 1103/09-02 typecheck fixture. */ -export function composeProductSessionOwner( - context: ProductSessionOwnerContext, -): ProductSessionOwner { - return null; } +/** Replaces `product-composition.ts`; the product's own is kept beside it. */ +function productComposition(extension: ProductExtension): string { + const kept = `./${path.posix.basename(extension.keptComposition)}`; + return `import type { + ProductComposition, + ProductCompositionContext, +} from "./product-composition-contract.ts"; +import { composeProduct as composeKeptProduct } from "${kept}"; + +/** + * Product-owned. Filled by the 1103/09-02 typecheck fixture on top of the + * product's own file, kept as ${kept} (1105/09-01). + */ +export * from "${kept}"; + export function composeProduct(context: ProductCompositionContext) { - const pageSize = context.config.TYPECHECK_PROBE_PAGE_SIZE; + const product = composeKeptProduct(context); + const pageSize = context.config.${extension.configKey}; return { + ...product, capabilities: { - typecheckProbeSettings: Object.freeze({ pageSize: () => pageSize }), + ...product.capabilities, + ${extension.capability}: Object.freeze({ pageSize: () => pageSize }), }, - credentialProviders: {}, } satisfies ProductComposition; } `; +} -const FEATURE_ID = "typecheck-probe-feature"; -const CONTEXT_ID = "typecheck-probe-context"; +function featureModule(extension: ProductExtension): string { + return `import { defineFeatureModule } from "../feature-module.ts"; -const FEATURE_MODULE = `import { defineFeatureModule } from "../feature-module.ts"; - -export const FEATURE_MODULE_ID = "${FEATURE_ID}"; -export const FEATURE_CONTEXT_ID = "${CONTEXT_ID}"; +export const FEATURE_MODULE_ID = "${extension.featureId}"; +export const FEATURE_CONTEXT_ID = "${extension.contextId}"; export const FEATURE_MODULE = defineFeatureModule({ id: FEATURE_MODULE_ID, @@ -106,54 +165,59 @@ export const FEATURE_MODULE = defineFeatureModule({ }, routes: {}, // Both locales: with the sample features removed (test:sample-removal) - // this is the only catalog the message key types come from. + // the probe's catalogs are the only ones the message key types come from. messages: { - "ko-KR": { "typecheckProbe.title": "타입 검사 탐침" }, - "en-US": { "typecheckProbe.title": "Typecheck probe" }, + "ko-KR": { "${extension.messageKey}": "타입 검사 탐침" }, + "en-US": { "${extension.messageKey}": "Typecheck probe" }, }, loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME, } as const); `; +} -const FEATURE_RUNTIME = `import { defineFeatureAdapterContribution } from "../feature-adapter-contribution.ts"; +function featureRuntime(extension: ProductExtension): string { + return `import { defineFeatureAdapterContribution } from "../feature-adapter-contribution.ts"; import { defineFeatureRuntime } from "../feature-module.ts"; type TypecheckProbeInput = Readonly<{ pageSize(): number }>; declare module "../../application/ports/in/application-api.ts" { interface ApplicationFeatureInputs { - "${FEATURE_ID}": TypecheckProbeInput; + "${extension.featureId}": TypecheckProbeInput; } } export const FEATURE_RUNTIME = defineFeatureRuntime({ - featureId: "${FEATURE_ID}", + featureId: "${extension.featureId}", schemas: {}, adapters: [ defineFeatureAdapterContribution({ - featureId: "${FEATURE_ID}", - needs: ["typecheckProbeSettings"] as const, - createInput: ({ typecheckProbeSettings }) => + featureId: "${extension.featureId}", + needs: ["${extension.capability}"] as const, + createInput: ({ ${extension.capability} }) => Object.freeze({ - featureId: "${FEATURE_ID}", - input: Object.freeze({ pageSize: () => typecheckProbeSettings.pageSize() }), + featureId: "${extension.featureId}", + input: Object.freeze({ pageSize: () => ${extension.capability}.pageSize() }), }), }), ], contractContributions: [], } as const); `; +} const CONTEXT_ROUTES = `import type { RouteObject } from "react-router-dom"; export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze([]); `; -const CONTEXT_MODULE = `export const CONTEXT_MODULE_ID = "${CONTEXT_ID}"; +function contextModule(extension: ProductExtension): string { + return `export const CONTEXT_MODULE_ID = "${extension.contextId}"; export const CONTEXT_APP_ID = "template-app"; -export const CONTEXT_ROUTE_PATH = "typecheck-probe/*"; +export const CONTEXT_ROUTE_PATH = "${extension.routePath}"; export const CONTEXT_MAX_FEATURES = 1; `; +} const roots: string[] = []; @@ -161,53 +225,99 @@ afterAll(async () => { await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); }); -describe("1103/09-02 a product filled through its own files typechecks", () => { - it("passes the app, node and test programs", async () => { - const root = await mkdtemp(path.join(tmpdir(), "product-extension-typecheck-")); - roots.push(root); - // The repository's one copy-target list for a fixture copy. A removal - // drill runs this test in a copy that has already lost some of them - // (test:optional-recipe-removal deletes recipes/). - expect(existsSync(path.resolve("src/features", FEATURE_ID)), FEATURE_ID).toBe(false); - for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) { - if (!existsSync(path.resolve(entry))) continue; - await cp(path.resolve(entry), path.join(root, entry), { - recursive: true, - filter: (source) => !source.includes(`${path.sep}.generated`), - }); - } - await linkFixtureNodeModules(root); - const shipped = await readFile(path.resolve("src/features/product-capabilities.ts"), "utf8"); - const files: Readonly> = { - "src/features/product-capabilities.ts": `${shipped}${PRODUCT_CAPABILITY_TYPES}`, - "src/contracts/product-contracts.ts": PRODUCT_CONTRACTS, - "src/bootstrap/product-composition.ts": PRODUCT_COMPOSITION, - [`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE, - [`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE, - [`src/features/${FEATURE_ID}/feature-runtime.ts`]: FEATURE_RUNTIME, - [`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES, - }; - for (const [file, content] of Object.entries(files)) { - await mkdir(path.dirname(path.join(root, file)), { recursive: true }); - await writeFile(path.join(root, file), content); - } +async function copyRepository(): Promise { + const root = await mkdtemp(path.join(tmpdir(), "product-extension-typecheck-")); + roots.push(root); + // The repository's one copy-target list for a fixture copy. A removal + // drill runs this test in a copy that has already lost some of them + // (test:optional-recipe-removal deletes recipes/). + for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) { + if (!existsSync(path.resolve(entry))) continue; + await cp(path.resolve(entry), path.join(root, entry), { + recursive: true, + filter: (source) => !source.includes(`${path.sep}.generated`), + }); + } + await linkFixtureNodeModules(root); + return root; +} - const generated = spawnSync( - process.execPath, - [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], +async function writeFiles(root: string, files: Readonly>): Promise { + for (const [file, content] of Object.entries(files)) { + await mkdir(path.dirname(path.join(root, file)), { recursive: true }); + await writeFile(path.join(root, file), content); + } +} + +/** + * Adds one capability, its runtime-config key and a feature that needs it to + * the copy, keeping whatever the copy's product files already hold. + */ +async function addProductExtension(root: string, extension: ProductExtension): Promise { + // The extension's names are reserved for this file: a product that took one + // fails here, by name, instead of with a TS error in the copy. + for (const owned of [ + `src/features/${extension.featureId}`, + `src/contexts/${extension.contextId}`, + extension.keptContracts, + extension.keptComposition, + ]) { + expect(existsSync(path.join(root, owned)), owned).toBe(false); + } + await rename(path.join(root, PRODUCT_CONTRACTS_FILE), path.join(root, extension.keptContracts)); + await rename( + path.join(root, PRODUCT_COMPOSITION_FILE), + path.join(root, extension.keptComposition), + ); + const capabilities = await readFile(path.join(root, PRODUCT_CAPABILITIES_FILE), "utf8"); + await writeFiles(root, { + [PRODUCT_CAPABILITIES_FILE]: `${capabilities}${capabilityType(extension)}`, + [PRODUCT_CONTRACTS_FILE]: productContracts(extension), + [PRODUCT_COMPOSITION_FILE]: productComposition(extension), + [`src/contexts/${extension.contextId}/context-module.ts`]: contextModule(extension), + [`src/features/${extension.featureId}/feature-module.ts`]: featureModule(extension), + [`src/features/${extension.featureId}/feature-runtime.ts`]: featureRuntime(extension), + [`src/features/${extension.featureId}/context-routes.ts`]: CONTEXT_ROUTES, + }); +} + +/** Generates the copy's indexes and runs the three programs of `check:types`. */ +function expectTypecheckPasses(root: string): void { + const generated = spawnSync( + process.execPath, + [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], + { encoding: "utf8" }, + ); + expect(generated.stderr).toBe(""); + expect(generated.status).toBe(0); + + for (const project of ["tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json"]) { + const typecheck = spawnSync( + path.resolve("node_modules/.bin/tsc"), + ["--project", path.join(root, project)], { encoding: "utf8" }, ); - expect(generated.stderr).toBe(""); - expect(generated.status).toBe(0); + expect(typecheck.stdout + typecheck.stderr, project).toBe(""); + expect(typecheck.status, project).toBe(0); + } +} - for (const project of ["tsconfig.app.json", "tsconfig.node.json", "tsconfig.test.json"]) { - const typecheck = spawnSync( - path.resolve("node_modules/.bin/tsc"), - ["--project", path.join(root, project)], - { encoding: "utf8" }, - ); - expect(typecheck.stdout + typecheck.stderr, project).toBe(""); - expect(typecheck.status, project).toBe(0); - } +describe("1103/09-02 a product filled through its own files typechecks", () => { + it("passes the app, node and test programs", async () => { + const root = await copyRepository(); + await addProductExtension(root, PROBE); + expectTypecheckPasses(root); + }, 120_000); +}); + +describe("1105/09-01 the probe keeps what the product's own files build", () => { + // The copy first becomes a downstream whose own product-composition.ts + // builds a capability for its own feature, as memento and tech-log do + // (CHANGELOG.md, `composeProduct(context)`). The probe must not take it away. + it("passes when a product feature needs a product capability", async () => { + const root = await copyRepository(); + await addProductExtension(root, DOWNSTREAM); + await addProductExtension(root, PROBE); + expectTypecheckPasses(root); }, 120_000); }); -- 2.54.0 From 9655958bdae9199f4ea84684eddb803da3262762 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:06:59 +0900 Subject: [PATCH 3/5] =?UTF-8?q?fix(ci):=20test:system=20=EC=82=AC=EC=A0=84?= =?UTF-8?q?=20=EC=A0=90=EA=B2=80=EC=9D=B4=20bwrap=20namespace=EB=A5=BC=20?= =?UTF-8?q?=EC=8B=A4=EC=A0=9C=EB=A1=9C=20=EB=A7=8C=EB=93=A4=EC=96=B4=20?= =?UTF-8?q?=EB=B3=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid --unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가 아니므로 비특권 user namespace가 있어야 한다. 사전 점검 (scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트 (Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를 낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간 초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도 없고 운영 원장의 일회성 메모에만 있다. 고른 방법: - 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한 번 띄운다. 실패하면 "this host does not allow unprivileged user and network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값, 고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1. 기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다. - 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고 run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이 갈라지면 점검이 다른 것을 시험하게 된다. - 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access· readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다. - config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다. gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의 runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로 그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty 규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가 아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선 재기록 불필요). - 요구 목록 세 곳(docs/operations/ci-quality-gates.md, docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge 게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를 두었다. 버린 대안: - namespace가 없으면 provider 테스트를 skip: 거짓 초록이다. - FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다. - probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope 안과 밖의 결과가 같았다. 직접 실행이 더 단순하다. - workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직 없다. 주석이 지금 가능한 가장 작은 표시다. 위험·한계: - probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른 옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로 실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다. - 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만 한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서 이유와 함께 실패한다. - gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과 제품 overlay는 그대로 통과한다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts - corepack pnpm check:ci, check:types, lint, verify:documentation - desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과 namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지 Refs: 1105/12-01, 1105/11-02 --- .gitea/workflows/quality-gates.yml | 2 + README.md | 5 +- config/ci/gates.json | 6 +- docs/operations/ci-quality-gates.md | 40 ++++ docs/security/supply-chain.md | 10 +- docs/testing/taxonomy.md | 7 +- scripts/check-system-test-prerequisites.ts | 179 ++++++++++++++---- scripts/contracts/ci-gates.ts | 8 + scripts/generate-ci-workflow.ts | 24 ++- scripts/lib/provider-sandbox-namespaces.ts | 18 ++ scripts/run-and-validate-provider.ts | 3 +- .../ci-workflow-generation.test.ts.snap | 2 + tests/unit/ci-workflow-generation.test.ts | 30 +++ tests/unit/system-test-prerequisites.test.ts | 125 ++++++++++++ 14 files changed, 413 insertions(+), 46 deletions(-) create mode 100644 scripts/lib/provider-sandbox-namespaces.ts create mode 100644 tests/unit/system-test-prerequisites.test.ts diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 3841d543..796ff2cc 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -34,6 +34,8 @@ jobs: merge_gate: name: "${{ matrix.gate }} / ${{ matrix.name }}" if: ${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }} + # FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers + # FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs runs-on: ubuntu-latest timeout-minutes: 45 strategy: diff --git a/README.md b/README.md index be85eada..6a0f27e3 100644 --- a/README.md +++ b/README.md @@ -328,7 +328,10 @@ tags. The Git host of this repository may not have Actions enabled, so a pull request can show no gate status at all; no status is not a pass. Until the host runs the workflow and marks the merge gates as required checks, run the 14 merge gates locally before merging (FE-GATE-008 and 009 need Playwright -browsers; FE-GATE-012 builds the app first). Product checks listed in +browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where +bubblewrap may create unprivileged user and network namespaces, which Ubuntu +23.10 and later refuse by default — its first step says so, and +`docs/operations/ci-quality-gates.md` lists the fixes). Product checks listed in `config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own `product_merge_gate` job: diff --git a/config/ci/gates.json b/config/ci/gates.json index 46a4d27f..f32e169e 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -2036,7 +2036,11 @@ "artifact-artifacts-security-supply-chain-fixtures-json", "artifact-artifacts-security-supply-chain-provider-fixtures-json" ], - "retentionClassId": "release-coherence" + "retentionClassId": "release-coherence", + "hostRequirements": [ + "Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers", + "unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs" + ] }, { "id": "FE-GATE-014", diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 2fbbbfc7..1171b76e 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -188,6 +188,46 @@ trust/archive/path 같은 host-side preflight 실패는 raw report 생성 전에 만든 뒤 scope 안에서만 확정할 수 있으며, 이 단계의 실패는 해당 inode를 identity-bound cleanup하고 fail closed한다. +**비특권 user namespace (1105/12-01).** runner는 비특권 process가 bubblewrap으로 +user namespace와 network namespace를 만들 수 있게 허용해야 한다. provider +sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로 +뜬다(`scripts/lib/provider-sandbox-namespaces.ts`). bubblewrap은 setuid가 아니므로 +이 옵션마다 비특권 user namespace가 필요하다. 이 조건은 provider job과 merge +게이트 FE-GATE-013(`test:system`의 provider 테스트) 둘 다에 걸린다. +`config/ci/gates.json`의 FE-GATE-013 `hostRequirements`에 같은 조건이 있고, +생성 workflow는 그것을 merge job의 `runs-on` 옆 주석으로 보여 준다. + +- Ubuntu 23.10부터는 `kernel.apparmor_restrict_unprivileged_userns=1`이 + 기본이다(24.04도 같다). `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor + profile이 없으면 bwrap이 + `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝난다. +- `test:system`은 먼저 `scripts/check-system-test-prerequisites.ts`를 돈다. 이 + 검사는 provider와 같은 namespace 옵션으로 bwrap에서 `/bin/true`를 한 번 + 띄운다. 실패하면 "this host does not allow unprivileged user and network + namespaces"와 bwrap의 stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로 + 멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로 + 실패했다(2026-11-05 desktop에서 114건 중 18건). +- 고치는 방법은 셋 중 하나다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 + 소유자가 고른다. + 1. `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile을 둔다. Ubuntu + 문서가 안내하는 형태는 아래와 같다. `/etc/apparmor.d/bwrap`에 두고 + `sudo apparmor_parser -r /etc/apparmor.d/bwrap`으로 읽게 한다. + 2. 직접 관리하는 호스트라면 sysctl + `kernel.apparmor_restrict_unprivileged_userns=0`으로 제한을 끈다. 이 설정이 + 없는 커널에서는 `kernel.unprivileged_userns_clone=1`이 같은 역할이다. + 3. 비특권 user namespace를 허용하는 다른 runner에서 FE-GATE-013과 provider + job을 돌린다. + +```text +abi , +include + +profile bwrap /usr/bin/bwrap flags=(unconfined) { + userns, + include if exists +} +``` + 각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에 실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`, `pids.max=64`, `cpu.max="100000 100000"`을 확인한다. 내부 process에는 core 0, diff --git a/docs/security/supply-chain.md b/docs/security/supply-chain.md index 1c9c505f..b41673df 100644 --- a/docs/security/supply-chain.md +++ b/docs/security/supply-chain.md @@ -183,7 +183,15 @@ External provider supervision is fail-closed and requires a Linux runner with executable `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`, and `/usr/bin/systemctl`, bubblewrap support for `--size`, an active user bus, a systemd user manager version 254 or newer, unified cgroup v2, and delegated -memory, pids, and CPU controllers. Executable access, user-manager/version, +memory, pids, and CPU controllers. The runner must also let an unprivileged +process create user and network namespaces with bubblewrap: the sandbox runs +`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`, and Ubuntu +23.10 and later refuse that while +`kernel.apparmor_restrict_unprivileged_userns=1` unless `/usr/bin/bwrap` has +an AppArmor profile that allows `userns` (1105/12-01). The same holds for +FE-GATE-013, whose `test:system` probes it first +(`scripts/check-system-test-prerequisites.ts`); the fixes are in +`docs/operations/ci-quality-gates.md`. Executable access, user-manager/version, trust, archive, and path failures are rejected before raw creation. Bubblewrap `--size` acceptance and effective delegated controller values can only be verified after the owned raw inode exists inside a new scope; failures there diff --git a/docs/testing/taxonomy.md b/docs/testing/taxonomy.md index f3a199e9..1bb5b9da 100644 --- a/docs/testing/taxonomy.md +++ b/docs/testing/taxonomy.md @@ -12,7 +12,7 @@ Each gate is blocking in its declared scope. Failures are not downgraded with | capability contract | `pnpm test:contract` | reusable capability consumer contracts | `artifacts/tests/contract.xml` | | component | `pnpm test:component` | React/hook/UI behavior | `artifacts/tests/component.xml` | | integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, composed browser-runtime boundaries, child-process/filesystem/IPC integration | `artifacts/tests/integration.xml` | -| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls | `artifacts/tests/system.xml` | +| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls, where bubblewrap may create unprivileged user and network namespaces | `artifacts/tests/system.xml` | | end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` | | accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` | @@ -60,6 +60,11 @@ start the CI-runner suite. The system suite additionally runs `scripts/check-system-test-prerequisites.ts` and fails with one prerequisite report when the CI-runner host does not provide its required Linux facilities. +Besides the executables, cgroup v2 and the systemd bus, it runs bubblewrap once +with the provider sandbox's namespace options on `/bin/true`, so a host that +refuses unprivileged user namespaces (Ubuntu 23.10 and later with +`kernel.apparmor_restrict_unprivileged_userns=1`) fails there by name instead of +in the provider tests (1105/12-01, `docs/operations/ci-quality-gates.md`). ## Development paths diff --git a/scripts/check-system-test-prerequisites.ts b/scripts/check-system-test-prerequisites.ts index c43e32fe..50462fc7 100644 --- a/scripts/check-system-test-prerequisites.ts +++ b/scripts/check-system-test-prerequisites.ts @@ -1,55 +1,154 @@ import { constants } from "node:fs"; import { access, readFile } from "node:fs/promises"; import { spawnSync } from "node:child_process"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; -const failures: string[] = []; +import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "./lib/provider-sandbox-namespaces.ts"; -async function requireExecutable(path: string, label: string): Promise { - try { - await access(path, constants.X_OK); - } catch { - failures.push(`${label} is required at ${path}`); - } -} +/** What the check reads from the host; a test passes a fake. */ +export type SystemTestHost = Readonly<{ + /** Resolves when `target` is executable, rejects otherwise. */ + access(target: string): Promise; + readFile(target: string): Promise; + spawn( + command: string, + args: readonly string[], + timeoutMs: number, + ): Readonly<{ status: number | null; stderr: string; error?: Error | undefined }>; +}>; -await Promise.all([ - requireExecutable("/usr/bin/bwrap", "bubblewrap"), - requireExecutable("/usr/bin/systemctl", "systemctl"), - requireExecutable("/usr/bin/tar", "tar"), +export const nodeSystemTestHost: SystemTestHost = Object.freeze({ + access: async (target: string) => access(target, constants.X_OK), + readFile: async (target: string) => readFile(target, "utf8"), + spawn: (command: string, args: readonly string[], timeoutMs: number) => { + const result = spawnSync(command, [...args], { encoding: "utf8", timeout: timeoutMs }); + return { status: result.status, stderr: result.stderr ?? "", error: result.error }; + }, +}); + +const BWRAP = "/usr/bin/bwrap"; +const SYSTEMCTL = "/usr/bin/systemctl"; + +/** + * 1105/12-01. The provider sandbox's own namespace options on /bin/true. The + * check used to see only that /usr/bin/bwrap was executable, so a host that + * refuses unprivileged user namespaces passed it and then failed 18 provider + * tests with `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. + */ +export const NAMESPACE_PROBE_ARGUMENTS: readonly string[] = Object.freeze([ + ...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS, + "--ro-bind", "/", "/", + "--", "/bin/true", ]); -try { - const controllers = await readFile("/sys/fs/cgroup/cgroup.controllers", "utf8"); - if (controllers.trim().length === 0) { - failures.push("cgroup v2 controllers are unavailable"); +/** Host settings that decide whether an unprivileged process may create user namespaces. */ +const USER_NAMESPACE_SETTINGS = Object.freeze([ + ["kernel.apparmor_restrict_unprivileged_userns", "/proc/sys/kernel/apparmor_restrict_unprivileged_userns"], + ["kernel.unprivileged_userns_clone", "/proc/sys/kernel/unprivileged_userns_clone"], + ["user.max_user_namespaces", "/proc/sys/user/max_user_namespaces"], +] as const); + +const PROBE_TIMEOUT_MS = 5_000; +const MAX_REPORTED_STDERR_LINES = 4; + +export async function findSystemTestPrerequisiteFailures( + host: SystemTestHost = nodeSystemTestHost, +): Promise { + const failures: string[] = []; + const executable = new Map(); + for (const [target, label] of [ + [BWRAP, "bubblewrap"], + [SYSTEMCTL, "systemctl"], + ["/usr/bin/tar", "tar"], + ] as const) { + try { + await host.access(target); + executable.set(target, true); + } catch { + executable.set(target, false); + failures.push(`${label} is required at ${target}`); + } } -} catch { - failures.push("cgroup v2 is required at /sys/fs/cgroup/cgroup.controllers"); -} -if (!failures.some((failure) => failure.includes("systemctl"))) { - const probe = spawnSync("/usr/bin/systemctl", ["show-environment"], { - encoding: "utf8", - timeout: 3_000, - }); - if (probe.error || probe.status !== 0) { - failures.push("a reachable systemd manager bus is required"); + try { + const controllers = await host.readFile("/sys/fs/cgroup/cgroup.controllers"); + if (controllers.trim().length === 0) { + failures.push("cgroup v2 controllers are unavailable"); + } + } catch { + failures.push("cgroup v2 is required at /sys/fs/cgroup/cgroup.controllers"); } + + if (executable.get(SYSTEMCTL)) { + const probe = host.spawn(SYSTEMCTL, ["show-environment"], 3_000); + if (probe.error || probe.status !== 0) { + failures.push("a reachable systemd manager bus is required"); + } + } + + if (executable.get(BWRAP)) { + const probe = host.spawn(BWRAP, NAMESPACE_PROBE_ARGUMENTS, PROBE_TIMEOUT_MS); + if (probe.error || probe.status !== 0) { + failures.push(await namespaceFailure(host, probe)); + } + } + return failures; } -if (failures.length > 0) { - process.stderr.write( - [ - "System/CI-runner test prerequisites are unavailable:", - ...failures.map((failure) => ` - ${failure}`), - "", - "Run test:unit/test:contract/test:component/test:integration for the", - "developer loop. test:system is intentionally reserved for a compatible", - "Linux CI-runner host.", - "", - ].join("\n"), - ); - process.exit(1); +async function namespaceFailure( + host: SystemTestHost, + probe: ReturnType, +): Promise { + const settings: string[] = []; + for (const [name, file] of USER_NAMESPACE_SETTINGS) { + try { + settings.push(`${name} = ${(await host.readFile(file)).trim()}`); + } catch { + // Absent on this kernel; the others still say what the host allows. + } + } + const stderr = probe.stderr + .split("\n") + .map((line) => line.trim()) + .filter((line) => line.length > 0) + .slice(0, MAX_REPORTED_STDERR_LINES); + const outcome = probe.error + ? `did not finish: ${probe.error.message}` + : `exited ${String(probe.status)}`; + return [ + "this host does not allow unprivileged user and network namespaces, which the provider " + + `sandbox needs (bwrap ${PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS.join(" ")}).`, + ` probe: ${BWRAP} ${NAMESPACE_PROBE_ARGUMENTS.join(" ")} ${outcome}`, + ...(stderr.length > 0 ? stderr.map((line) => ` bwrap stderr: ${line}`) : [" bwrap stderr: (empty)"]), + ...(settings.length > 0 ? [` host settings: ${settings.join(", ")}`] : []), + " To fix, do one of these:", + " - give /usr/bin/bwrap an AppArmor profile that allows `userns` (Ubuntu 23.10 and later),", + " - on a host you own, set sysctl kernel.apparmor_restrict_unprivileged_userns=0", + " (or kernel.unprivileged_userns_clone=1 where that setting exists),", + " - run FE-GATE-013 on another runner that allows them.", + " Runner requirements: docs/operations/ci-quality-gates.md.", + ].join("\n"); } -process.stdout.write("System test prerequisites: PASS\n"); +export function formatSystemTestPrerequisiteReport(failures: readonly string[]): string { + return [ + "System/CI-runner test prerequisites are unavailable:", + ...failures.map((failure) => ` - ${failure}`), + "", + "Run test:unit/test:contract/test:component/test:integration for the", + "developer loop. test:system is intentionally reserved for a compatible", + "Linux CI-runner host.", + "", + ].join("\n"); +} + +const isCli = process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); +if (isCli) { + const failures = await findSystemTestPrerequisiteFailures(); + if (failures.length > 0) { + process.stderr.write(formatSystemTestPrerequisiteReport(failures)); + process.exit(1); + } + process.stdout.write("System test prerequisites: PASS\n"); +} diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index 73d05af5..5111a329 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -290,6 +290,14 @@ const gateSchema = z evidenceArtifactIds: z.array(id).min(1).max(128), retentionClassId: id, requiresEnvironment: z.array(z.string().max(128).regex(/^[A-Z][A-Z0-9_]*$/u)).max(32).optional(), + /** + * 1105/12-01. What the runner host must provide for the gate to pass, one + * line each. The workflow shows them as comments beside the job's + * `runs-on`; a line cannot hold a line break, so it cannot leave the + * comment. They describe the runner, not the gate's commands or evidence, + * so the reviewed gate shape (canonicalGateShapeSha256) leaves them out. + */ + hostRequirements: z.array(nonEmpty.max(512)).min(1).max(8).optional(), }) .strict(); diff --git a/scripts/generate-ci-workflow.ts b/scripts/generate-ci-workflow.ts index 0f8fdaa5..00a38cc3 100644 --- a/scripts/generate-ci-workflow.ts +++ b/scripts/generate-ci-workflow.ts @@ -167,7 +167,11 @@ function renderJob( if (job.needs.length > 1) lines.push(` needs: [${job.needs.map(yamlKey).join(", ")}]`); const condition = renderCondition(job.condition); if (condition) lines.push(` if: ${condition}`); - lines.push(" runs-on: ubuntu-latest", ` timeout-minutes: ${job.timeoutMinutes}`); + lines.push( + ...renderHostRequirements(job, index), + " runs-on: ubuntu-latest", + ` timeout-minutes: ${job.timeoutMinutes}`, + ); if (job.kind === "immutable") { const archive = job.steps.find((step) => step.kind === "archive-candidate"); if (!archive || archive.kind !== "archive-candidate") throw new TypeError("immutable job lacks archive step"); @@ -214,6 +218,24 @@ function renderJob( return lines; } +/** + * 1105/12-01. A gate's host requirements (`hostRequirements` in + * config/ci/gates.json) sit as comments beside the runner label of the job + * that runs the gate, where whoever picks the runner reads them. FE-GATE-013 + * needs unprivileged user namespaces, and that was written nowhere a runner + * is chosen. The contract keeps line breaks out of each requirement. + */ +function renderHostRequirements( + job: CiWorkflowJob, + index: ReturnType, +): string[] { + return job.gateIds.flatMap((gateId) => + (index.gates.get(gateId)?.hostRequirements ?? []).map( + (requirement) => ` # ${gateId} runner requirement: ${requirement}`, + ), + ); +} + function renderStep( job: CiWorkflowJob, step: CiWorkflowStep, diff --git a/scripts/lib/provider-sandbox-namespaces.ts b/scripts/lib/provider-sandbox-namespaces.ts new file mode 100644 index 00000000..618474fa --- /dev/null +++ b/scripts/lib/provider-sandbox-namespaces.ts @@ -0,0 +1,18 @@ +/** + * 1105/12-01. The namespaces the provider sandbox asks bubblewrap for + * (scripts/run-and-validate-provider.ts). bubblewrap is not setuid, so each of + * them is an unprivileged user namespace plus the namespace named, and + * `--unshare-net` also brings up loopback inside it. + * + * scripts/check-system-test-prerequisites.ts probes the host with this same + * list. A host that refuses them (Ubuntu 24.04 with + * kernel.apparmor_restrict_unprivileged_userns=1 and no AppArmor profile for + * bwrap) then fails the prerequisite check by name, instead of passing it and + * failing the provider tests with a raw netlink error. + */ +export const PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS: readonly string[] = Object.freeze([ + "--unshare-pid", + "--unshare-ipc", + "--unshare-uts", + "--unshare-net", +]); diff --git a/scripts/run-and-validate-provider.ts b/scripts/run-and-validate-provider.ts index 09511f4a..268318ab 100644 --- a/scripts/run-and-validate-provider.ts +++ b/scripts/run-and-validate-provider.ts @@ -30,6 +30,7 @@ import { type ProviderGuardianLease, } from "./lib/provider-guardian-client.ts"; import { createProviderOutputLimiter } from "./lib/provider-output-limiter.ts"; +import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "./lib/provider-sandbox-namespaces.ts"; import { providerProcessTraceEnvironment, traceOwnProviderProcess, @@ -253,7 +254,7 @@ async function runProviderInSandbox( const cpuSeconds = providerCpuSeconds(); const bwrapArguments = [ "--die-with-parent", "--new-session", "--as-pid-1", - "--unshare-pid", "--unshare-ipc", "--unshare-uts", "--unshare-net", + ...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS, "--dev", "/dev", "--remount-ro", "/dev", "--proc", "/proc", "--remount-ro", "/proc", "--size", String(PROVIDER_TMP_BYTES), "--tmpfs", "/tmp", diff --git a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap index a7f51531..6b84e76f 100644 --- a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap +++ b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap @@ -37,6 +37,8 @@ jobs: merge_gate: name: "\${{ matrix.gate }} / \${{ matrix.name }}" if: \${{ gitea.event_name != 'workflow_dispatch' || inputs.stage != 'documentation' }} + # FE-GATE-013 runner requirement: Linux with executable /usr/bin/bwrap (with --size), /usr/bin/prlimit, /usr/bin/systemd-run, /usr/bin/systemctl and /usr/bin/tar, an active systemd user manager 254 or newer, and unified cgroup v2 with delegated memory, pids and cpu controllers + # FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs runs-on: ubuntu-latest timeout-minutes: 45 strategy: diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts index be94a2c0..03d8ad2d 100644 --- a/tests/unit/ci-workflow-generation.test.ts +++ b/tests/unit/ci-workflow-generation.test.ts @@ -1698,6 +1698,36 @@ describe("CI workflow generation", () => { expect(workflow).toMatch(/^on:\n {2}push:\n {4}branches: \[main, develop\]$/mu); }); + // 1105/12-01. The provider sandbox in FE-GATE-013 needs unprivileged user + // and network namespaces. No runner requirement said so, and a host that + // refuses them failed 18 provider tests after the prerequisite check passed. + it("states FE-GATE-013's runner requirements beside the runner label of the job that runs it", async () => { + const contract = await loadCiGateContract(process.cwd()); + const requirements = indexCiGateContract(contract).gates.get("FE-GATE-013")?.hostRequirements ?? []; + expect(requirements.join("\n")).toMatch(/unprivileged user and network namespaces/u); + expect(requirements.join("\n")).toContain("--unshare-net"); + expect(requirements.join("\n")).toContain("kernel.apparmor_restrict_unprivileged_userns"); + expect(requirements.join("\n")).toContain("scripts/check-system-test-prerequisites.ts"); + + const workflow = renderCiWorkflow(contract); + const merge = workflow.slice(workflow.indexOf(" merge_gate:\n"), workflow.indexOf(" release_gate:\n")); + const header = merge.slice(0, merge.indexOf(" runs-on: ubuntu-latest\n")); + expect(header.split("\n").filter((line) => line.startsWith(" # "))).toEqual( + requirements.map((requirement) => ` # FE-GATE-013 runner requirement: ${requirement}`), + ); + expect(workflow.match(/ runner requirement: /gu)).toHaveLength(requirements.length); + }); + + it("rejects a runner requirement that would leave its workflow comment (1105/12-01)", async () => { + const contract = JSON.parse( + JSON.stringify(await loadCiGateContract(process.cwd())), + ) as Record; + contract.gates.find((gate: Record) => gate.id === "FE-GATE-013").hostRequirements = [ + "namespaces\n runs-on: self-hosted", + ]; + expect(() => parseCiGateContract(contract)).toThrow(/line-break characters are forbidden/u); + }); + // 12-02 / 13-01: immutable_build owns FE-GATE-015 and FE-GATE-027, but only // the first gate of a non-matrix job was ever rendered, so release admission // never ran in CI. diff --git a/tests/unit/system-test-prerequisites.test.ts b/tests/unit/system-test-prerequisites.test.ts new file mode 100644 index 00000000..3ff28dc4 --- /dev/null +++ b/tests/unit/system-test-prerequisites.test.ts @@ -0,0 +1,125 @@ +import { readFile } from "node:fs/promises"; + +import { describe, expect, it } from "vitest"; + +import { + findSystemTestPrerequisiteFailures, + formatSystemTestPrerequisiteReport, + NAMESPACE_PROBE_ARGUMENTS, + type SystemTestHost, +} from "../../scripts/check-system-test-prerequisites.ts"; +import { PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS } from "../../scripts/lib/provider-sandbox-namespaces.ts"; + +type SpawnCall = Readonly<{ command: string; args: readonly string[] }>; +type SpawnResult = ReturnType; + +const RTM_NEWADDR = "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted"; + +/** A host that has every prerequisite, except what `bwrap` and `files` say. */ +function fakeHost( + bwrap: SpawnResult, + files: Readonly> = {}, +): { host: SystemTestHost; calls: SpawnCall[] } { + const calls: SpawnCall[] = []; + const host: SystemTestHost = { + access: async () => undefined, + readFile: async (target) => { + if (target === "/sys/fs/cgroup/cgroup.controllers") return "cpuset cpu io memory pids\n"; + const content = files[target]; + if (content === undefined) throw new Error(`ENOENT: ${target}`); + return content; + }, + spawn: (command, args) => { + calls.push({ command, args }); + if (command === "/usr/bin/systemctl") return { status: 0, stderr: "" }; + if (command === "/usr/bin/bwrap") return bwrap; + throw new Error(`unexpected spawn: ${command}`); + }, + }; + return { host, calls }; +} + +// 1105/12-01. The check looked only for the bwrap executable, so a host that +// refuses unprivileged user namespaces printed PASS and then failed 18 +// provider tests with bwrap's raw netlink error. +describe("system test prerequisites (1105/12-01)", () => { + it("passes when bubblewrap creates the provider sandbox's namespaces", async () => { + const { host, calls } = fakeHost({ status: 0, stderr: "" }); + + expect(await findSystemTestPrerequisiteFailures(host)).toEqual([]); + + const probes = calls.filter(({ command }) => command === "/usr/bin/bwrap"); + expect(probes).toHaveLength(1); + expect(probes[0]?.args).toEqual(NAMESPACE_PROBE_ARGUMENTS); + expect(probes[0]?.args.at(-1)).toBe("/bin/true"); + }); + + it("probes with exactly the namespace options the provider sandbox uses", async () => { + expect(PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS).toEqual([ + "--unshare-pid", + "--unshare-ipc", + "--unshare-uts", + "--unshare-net", + ]); + expect(NAMESPACE_PROBE_ARGUMENTS.slice(0, PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS.length)).toEqual( + PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS, + ); + // The provider takes the list from the same module instead of its own copy. + const provider = await readFile("scripts/run-and-validate-provider.ts", "utf8"); + expect(provider).toContain("...PROVIDER_SANDBOX_NAMESPACE_ARGUMENTS,"); + expect(provider).not.toMatch(/"--unshare-/u); + }); + + it("fails with the namespace restriction, bwrap's stderr and what to do when bwrap cannot set up loopback", async () => { + const { host } = fakeHost( + { status: 1, stderr: `${RTM_NEWADDR}\n` }, + { "/proc/sys/kernel/apparmor_restrict_unprivileged_userns": "1\n" }, + ); + + const failures = await findSystemTestPrerequisiteFailures(host); + + expect(failures).toHaveLength(1); + const failure = failures[0] ?? ""; + expect(failure).toMatch(/^this host does not allow unprivileged user and network namespaces/u); + expect(failure).toContain("--unshare-net"); + expect(failure).toContain(`bwrap stderr: ${RTM_NEWADDR}`); + expect(failure).toContain("kernel.apparmor_restrict_unprivileged_userns = 1"); + expect(failure).toMatch(/AppArmor profile/u); + expect(failure).toMatch(/sysctl kernel\.apparmor_restrict_unprivileged_userns=0/u); + expect(failure).toMatch(/another runner/u); + expect(formatSystemTestPrerequisiteReport(failures)).toContain( + " - this host does not allow unprivileged user and network namespaces", + ); + }); + + it("fails the same way when the probe cannot run to the end", async () => { + const { host } = fakeHost({ status: null, stderr: "", error: new Error("spawnSync /usr/bin/bwrap ETIMEDOUT") }); + + const failures = await findSystemTestPrerequisiteFailures(host); + + expect(failures).toHaveLength(1); + expect(failures[0]).toMatch(/^this host does not allow unprivileged user and network namespaces/u); + expect(failures[0]).toContain("did not finish: spawnSync /usr/bin/bwrap ETIMEDOUT"); + }); + + it("keeps the executable, cgroup v2 and systemd bus checks, and probes bwrap only when it is there", async () => { + const calls: SpawnCall[] = []; + const host: SystemTestHost = { + access: async (target) => { + if (target === "/usr/bin/bwrap") throw new Error(`EACCES: ${target}`); + }, + readFile: async () => "\n", + spawn: (command, args) => { + calls.push({ command, args }); + return { status: 1, stderr: "Failed to connect to bus" }; + }, + }; + + expect(await findSystemTestPrerequisiteFailures(host)).toEqual([ + "bubblewrap is required at /usr/bin/bwrap", + "cgroup v2 controllers are unavailable", + "a reachable systemd manager bus is required", + ]); + expect(calls.map(({ command }) => command)).toEqual(["/usr/bin/systemctl"]); + }); +}); -- 2.54.0 From 629c713ce4fefa4ce8a7a9c73c55e79b8031905d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:12:30 +0900 Subject: [PATCH 4/5] =?UTF-8?q?fix(ci):=20immutable=5Fbuild=EA=B0=80=20gat?= =?UTF-8?q?e=20=EB=A1=9C=EA=B7=B8=EC=99=80=20advisory=20=EA=B8=B0=EB=A1=9D?= =?UTF-8?q?=EC=9D=84=20=ED=95=AD=EC=83=81=20=EC=98=AC=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-.txt에만 쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release 단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서 실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는 artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner 작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로 올린다. 고른 방법: - config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다. transfer ID는 immutable-gate-evidence, 이름은 immutable-gate-evidence--, always: true. 대상은 FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다. FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도 없으므로 같이 올린다. - 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의 단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며 경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야 한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께 따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를 scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그 상수를 쓴다. - 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는 그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다. 버린 대안: - immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가 두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다. - ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔 한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을 다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다. 위험·한계: - checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도 if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다. merge·release job의 upload도 같은 동작이다. - 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지 못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다. - 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다. 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts - corepack pnpm check:ci, check:types, lint, verify:documentation Refs: 1105/13-01, 1103/13-03 --- .gitea/workflows/quality-gates.yml | 14 +++ config/ci/gates.json | 15 +++ docs/operations/ci-quality-gates.md | 12 ++- scripts/contracts/ci-gates.ts | 46 +++++++- scripts/lib/dependency-advisories.ts | 6 ++ scripts/scan-dependency-advisories.ts | 7 +- .../ci-workflow-generation.test.ts.snap | 14 +++ tests/unit/ci-workflow-generation.test.ts | 101 +++++++++++++++++- 8 files changed, 210 insertions(+), 5 deletions(-) diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 796ff2cc..35af29d9 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -207,6 +207,20 @@ jobs: name: "release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}" path: ".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz" if-no-files-found: error + - name: Upload immutable gate evidence + if: always() + uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 + with: + name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}" + path: | + artifacts/quality/gates/FE-GATE-015.txt + artifacts/release/release-candidate.json + artifacts/release/verification.json + artifacts/security/supply-chain-coherence.json + artifacts/quality/gates/FE-GATE-027.txt + artifacts/release/deployment-admission.json + artifacts/security/dependency-advisories.json + if-no-files-found: error vulnerability_provider: name: external-vulnerability-provider diff --git a/config/ci/gates.json b/config/ci/gates.json index f32e169e..31175c46 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -2508,6 +2508,21 @@ "paths": [ ".release/release-candidate-${{ gitea.run_id }}-${{ gitea.run_attempt }}.tar.gz" ] + }, + { + "kind": "upload", + "transferId": "immutable-gate-evidence", + "name": "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}", + "paths": [ + "artifacts/quality/gates/FE-GATE-015.txt", + "artifacts/release/release-candidate.json", + "artifacts/release/verification.json", + "artifacts/security/supply-chain-coherence.json", + "artifacts/quality/gates/FE-GATE-027.txt", + "artifacts/release/deployment-admission.json", + "artifacts/security/dependency-advisories.json" + ], + "always": true } ] }, diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 1171b76e..511689b1 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -163,7 +163,12 @@ Release tier의 `immutable_build`는 `dist`의 hidden `.vite` entries, raw 번 생성해 run ID/attempt로 구분된 archive로 게시한다. Raw lock bytes의 SHA-256은 dependency inventory와 candidate manifest 양쪽의 `lockfileSha256`과 같아야 한다. Producer는 게시 전에 manifest가 선언한 exact member set과 각 byte digest를 -검증하고 archive SHA-256을 job output으로 고정한다. Vulnerability/provenance +검증하고 archive SHA-256을 job output으로 고정한다. 같은 job은 마지막 단계에서 +FE-GATE-015·027의 gate log와 evidence, `scan:dependency-advisories` 기록을 후보와 +다른 이름(`immutable-gate-evidence--`)으로 성공·실패와 상관없이 +올린다(1105/13-01). `ci:gate`는 명령 출력을 gate log에만 쓰고 콘솔에는 한 줄만 +남기므로, release 단계의 실패 이유는 이 산출물에서 읽는다. 후보 archive의 member +set은 그대로다. Vulnerability/provenance provider job은 같은 archive를 각각 내려받아 output SHA-256과 exact member set을 확인한 뒤 checkout과 분리된 root에만 추출하고, `CANDIDATE_LOCKFILE_PATH`와 `CANDIDATE_DIST_SHA256`를 외부 command에 전달한다. Provider command 실행 후에는 @@ -525,6 +530,11 @@ Repository variables required by higher tiers: findings) or `UNVERIFIED` (no registry). It never fails the gate, because an advisory database that changes under unchanged code would break releases; the signed verdict of the vulnerability provider still decides promotion. + The job console shows only one PASS/FAIL line per gate, so the + immutable_build job uploads both gates' logs and evidence and this record as + the run artifact `immutable-gate-evidence--`, whether the job + passed or failed (1105/13-01). Read why FE-GATE-015 or FE-GATE-027 failed, + and the advisory status, there. `renovate.json` opens security update PRs once a Renovate runner is attached; a dependency update re-approves the dependency baseline in the same change (`update:dependency-baseline`). diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index 5111a329..ae02aedb 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -4,6 +4,7 @@ import path from "node:path"; import { z } from "zod"; +import { DEPENDENCY_ADVISORIES_RECORD_PATH } from "../lib/dependency-advisories.ts"; import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts"; import { RELEASE_CANDIDATE_EVIDENCE_PATHS, @@ -952,7 +953,7 @@ function validateContractSemantics( const expectedStepKinds: Readonly> = { merge_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"], release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"], - immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"], + immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"], vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"], provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"], promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"], @@ -1150,6 +1151,29 @@ function validateContractSemantics( validateCanonicalStepFields(contract, issue); } +const IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID = "immutable-gate-evidence"; + +/** + * 1105/13-01. What immutable_build uploads besides the candidate: the log and + * evidence artifacts of each gate it runs, in gate order, then the advisory + * record of scan:dependency-advisories (FE-GATE-027), which is not a gate + * evidence artifact because it never blocks. + */ +function immutableGateEvidencePaths( + contract: Pick, "artifacts" | "gates">, + immutable: Pick, "gateIds">, +): string[] { + const paths = immutable.gateIds.flatMap((gateId) => { + const gate = contract.gates.find(({ id }) => id === gateId); + return gate + ? [gate.logArtifactId, ...gate.evidenceArtifactIds].flatMap((artifactId) => + contract.artifacts.filter(({ id }) => id === artifactId).map(({ path: artifactPath }) => artifactPath), + ) + : []; + }); + return [...new Set([...paths, DEPENDENCY_ADVISORIES_RECORD_PATH])]; +} + function validateCanonicalStepFields( contract: z.infer, issue: (message: string, path?: PropertyKey[]) => void, @@ -1168,6 +1192,26 @@ function validateCanonicalStepFields( ) { issue("immutable archive and upload fields must remain linked"); } + // 1105/13-01. ci:gate writes command output only to the gate log and prints + // one PASS/FAIL line, and this job uploaded only the candidate, on success. + // Why FE-GATE-015 or FE-GATE-027 failed, and the advisory record FE-GATE-027 + // writes, went with the runner's workspace. A separate transfer, always and + // last, carries them; the candidate archive's member set stays as it is. + const gateEvidence = immutable?.steps.find( + (step) => step.kind === "upload" && step.transferId === IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID, + ); + if ( + !immutable || + gateEvidence?.kind !== "upload" || + gateEvidence.always !== true || + immutable.steps.at(-1) !== gateEvidence || + JSON.stringify(gateEvidence.paths) !== JSON.stringify(immutableGateEvidencePaths(contract, immutable)) + ) { + issue( + "immutable_build must upload its gates' logs and evidence and the dependency advisory record " + + `as ${IMMUTABLE_GATE_EVIDENCE_TRANSFER_ID}, with always, as its last step`, + ); + } const providerExpectations = { vulnerability_provider: { diff --git a/scripts/lib/dependency-advisories.ts b/scripts/lib/dependency-advisories.ts index 083540be..ffcd91ee 100644 --- a/scripts/lib/dependency-advisories.ts +++ b/scripts/lib/dependency-advisories.ts @@ -1,5 +1,11 @@ import { validateVulnerabilityReport } from "./supply-chain.ts"; +/** + * Where scan:dependency-advisories writes its record. 1105/13-01: the + * immutable_build job uploads it on every outcome (scripts/contracts/ci-gates.ts). + */ +export const DEPENDENCY_ADVISORIES_RECORD_PATH = "artifacts/security/dependency-advisories.json"; + /** * 1103/13-03. The vulnerability verdict belongs to the external provider of * the production promotion (signed, independent of the build). Without a diff --git a/scripts/scan-dependency-advisories.ts b/scripts/scan-dependency-advisories.ts index dc5a8fdf..14621e2e 100644 --- a/scripts/scan-dependency-advisories.ts +++ b/scripts/scan-dependency-advisories.ts @@ -2,7 +2,10 @@ import { spawnSync } from "node:child_process"; import { createHash } from "node:crypto"; import { mkdir, readFile, writeFile } from "node:fs/promises"; -import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts"; +import { + DEPENDENCY_ADVISORIES_RECORD_PATH, + summarizeDependencyAdvisories, +} from "./lib/dependency-advisories.ts"; /** * 1103/13-03. Release-stage signal for known dependency advisories @@ -17,7 +20,7 @@ import { summarizeDependencyAdvisories } from "./lib/dependency-advisories.ts"; * result is UNVERIFIED, not PASS. The signed verdict of the vulnerability * provider stays the only one that decides a promotion. */ -const RECORD_PATH = "artifacts/security/dependency-advisories.json"; +const RECORD_PATH = DEPENDENCY_ADVISORIES_RECORD_PATH; const [policy, exceptions, lockfile] = await Promise.all([ readFile("config/security/vulnerability-policy.json", "utf8").then((text) => JSON.parse(text) as Record), diff --git a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap index 6b84e76f..a64963d1 100644 --- a/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap +++ b/tests/unit/__snapshots__/ci-workflow-generation.test.ts.snap @@ -210,6 +210,20 @@ jobs: name: "release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}" path: ".release/release-candidate-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}.tar.gz" if-no-files-found: error + - name: Upload immutable gate evidence + if: always() + uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 + with: + name: "immutable-gate-evidence-\${{ gitea.run_id }}-\${{ gitea.run_attempt }}" + path: | + artifacts/quality/gates/FE-GATE-015.txt + artifacts/release/release-candidate.json + artifacts/release/verification.json + artifacts/security/supply-chain-coherence.json + artifacts/quality/gates/FE-GATE-027.txt + artifacts/release/deployment-admission.json + artifacts/security/dependency-advisories.json + if-no-files-found: error vulnerability_provider: name: external-vulnerability-provider diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts index 03d8ad2d..f5ad6f8a 100644 --- a/tests/unit/ci-workflow-generation.test.ts +++ b/tests/unit/ci-workflow-generation.test.ts @@ -1654,7 +1654,7 @@ describe("CI workflow generation", () => { 'if [ -n "$PROMOTION_STAGING_ROOT" ] && [ -n "$PROMOTION_CLEANUP_TOKEN" ] && [ -n "$PROMOTION_RUNNER_TEMP_DEV" ] && [ -n "$PROMOTION_RUNNER_TEMP_INO" ] && [ -n "$PROMOTION_STAGING_DEV" ] && [ -n "$PROMOTION_STAGING_INO" ]; then', ); const actionUses = [...first.matchAll(/^\s+-?\s*uses: (.+)$/gmu)].map((match) => match[1]); - expect(actionUses).toHaveLength(33); + expect(actionUses).toHaveLength(34); expect(new Set(actionUses)).toEqual( new Set([ "https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5", @@ -1743,6 +1743,105 @@ describe("CI workflow generation", () => { expect(workflowGateExecutionFailures(contract, workflow)).toEqual([]); }); + // 1105/13-01. ci:gate writes each command's output only to the gate log and + // prints one PASS/FAIL line. immutable_build uploaded only the candidate, on + // success, so why FE-GATE-015 or FE-GATE-027 failed, and the advisory record + // FE-GATE-027 writes (1103/13-03), went with the runner's workspace. + const IMMUTABLE_GATE_EVIDENCE_PATHS = [ + "artifacts/quality/gates/FE-GATE-015.txt", + "artifacts/release/release-candidate.json", + "artifacts/release/verification.json", + "artifacts/security/supply-chain-coherence.json", + "artifacts/quality/gates/FE-GATE-027.txt", + "artifacts/release/deployment-admission.json", + "artifacts/security/dependency-advisories.json", + ]; + + it("uploads immutable_build's gate logs, evidence and advisory record on every outcome (1105/13-01)", async () => { + const contract = await loadCiGateContract(process.cwd()); + const index = indexCiGateContract(contract); + const gatePaths = ["FE-GATE-015", "FE-GATE-027"].flatMap((gateId) => { + const gate = index.gates.get(gateId)!; + return [gate.logArtifactId, ...gate.evidenceArtifactIds].map((artifactId) => index.artifacts.get(artifactId)!.path); + }); + expect(IMMUTABLE_GATE_EVIDENCE_PATHS).toEqual([...gatePaths, "artifacts/security/dependency-advisories.json"]); + + const workflow = renderCiWorkflow(contract); + const immutable = workflow.slice( + workflow.indexOf(" immutable_build:\n"), + workflow.indexOf(" vulnerability_provider:\n"), + ); + const candidateUpload = immutable.indexOf(" - name: Upload release candidate\n"); + const evidenceUpload = immutable.indexOf(" - name: Upload immutable gate evidence\n"); + expect(candidateUpload).toBeGreaterThan(immutable.indexOf("ci:gate -- FE-GATE-027")); + expect(evidenceUpload).toBeGreaterThan(candidateUpload); + expect(immutable.slice(evidenceUpload)).toBe( + [ + " - name: Upload immutable gate evidence", + " if: always()", + ` uses: ${resolveCiActionUses("uploadArtifact")}`, + " with:", + ' name: "immutable-gate-evidence-${{ gitea.run_id }}-${{ gitea.run_attempt }}"', + " path: |", + ...IMMUTABLE_GATE_EVIDENCE_PATHS.map((target) => ` ${target}`), + " if-no-files-found: error", + "", + "", + ].join("\n"), + ); + // The candidate still goes up only after its archive was validated, and + // the archive's member set is not widened by the evidence. + expect(immutable.slice(candidateUpload, evidenceUpload)).not.toContain("if: always()"); + const archive = contract.jobs + .find(({ id }) => id === "immutable_build") + ?.steps.find((step) => step.kind === "archive-candidate"); + expect(archive?.kind === "archive-candidate" ? archive.members : []).not.toContain( + "artifacts/quality/gates/FE-GATE-027.txt", + ); + }); + + it.each([ + [ + "is missing", + (steps: Record[]) => steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1), + ], + [ + "runs only on success", + (steps: Record[]) => delete steps.find((step) => step.transferId === "immutable-gate-evidence")!.always, + ], + [ + "leaves out the advisory record", + (steps: Record[]) => { + const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!; + upload.paths = upload.paths.filter((target: string) => target !== "artifacts/security/dependency-advisories.json"); + }, + ], + [ + "leaves out the FE-GATE-027 log", + (steps: Record[]) => { + const upload = steps.find((step) => step.transferId === "immutable-gate-evidence")!; + upload.paths = upload.paths.filter((target: string) => target !== "artifacts/quality/gates/FE-GATE-027.txt"); + }, + ], + [ + "comes before the candidate upload", + (steps: Record[]) => { + const evidence = steps.splice(steps.findIndex((step) => step.transferId === "immutable-gate-evidence"), 1)[0]!; + steps.splice(steps.findIndex((step) => step.transferId === "release-candidate"), 0, evidence); + }, + ], + ])("rejects an immutable_build whose gate evidence upload %s (1105/13-01)", async (_name, mutate) => { + const contract = JSON.parse( + JSON.stringify(await loadCiGateContract(process.cwd())), + ) as Record; + const steps = contract.jobs.find((job: Record) => job.id === "immutable_build").steps; + expect(steps.filter((step: Record) => step.transferId === "immutable-gate-evidence")).toHaveLength(1); + mutate(steps); + expect(() => parseCiGateContract(contract)).toThrow( + /immutable_build must upload its gates' logs and evidence and the dependency advisory record/u, + ); + }); + it.each([ ["a non-matrix gate step", " run: corepack pnpm ci:gate -- FE-GATE-027\n", "FE-GATE-027"], ["a matrix entry", " - { gate: FE-GATE-020, name: removability, browser: false }\n", "FE-GATE-020"], -- 2.54.0 From a793b83e820c7fe1903e573794baa27d53912123 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:18:15 +0900 Subject: [PATCH 5/5] =?UTF-8?q?docs(changelog):=201105=20P1=20=EC=A1=B0?= =?UTF-8?q?=EC=B9=98=20=EC=85=8B=EC=9D=84=20=EC=83=88=20=EB=AF=B8=EC=B6=9C?= =?UTF-8?q?=EC=8B=9C=20=EC=A0=88=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CHANGELOG의 미출시 절은 `752a61f` → `fix/maturity-review-2026-11-03` 범위다. 그 범위는 main `409d72e`에 합쳐졌고, 2026-11-05 리뷰의 P1 조치 셋(1105/09-01, 12-01, 13-01)은 어느 절에도 없다. 다운스트림이 FE-GATE-013 러너 요구와 release job의 새 upload를 알 수 없다. `409d72e` → `fix/maturity-review-2026-11-05` 범위의 새 미출시 절을 위에 두고 세 조치를 적었다. CI 러너 요구와 workflow upload가 바뀌므로 12-01·13-01은 [계약]이다. 기존 절은 지우지 않고 main에 합쳐졌다고만 머리에 적었다. 두 절을 하나로 합칠지는 남은 조치(PR B)의 CHANGELOG 정리에서 정한다. 위험·한계: 문서만 바꿨다. 검증: desktop batch에서 changelog-review-ids, documentation-readiness 테스트. Refs: 1105/09-01, 1105/12-01, 1105/13-01 --- CHANGELOG.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5bc2e0b4..b61bf5fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,22 @@ - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). -## 미출시 — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03` +## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05` + +2026-11-05 성숙도 리뷰(`docs/reviews/2026-11-05-maturity-review/`) 조치다. 범위는 `main` `409d72e`(아래 절의 묶음을 합친 커밋)부터 이 브랜치의 끝까지다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다. + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] | FE-GATE-013(`test:system`) 러너는 비특권 user namespace와 network namespace를 허용해야 한다(provider 샌드박스의 `bwrap --unshare-net`). 사전 점검이 bwrap을 실제로 띄워 보고, 허용하지 않는 호스트에서는 provider 테스트를 돌리기 전에 이유·호스트 설정·고치는 방법을 적고 멈춘다. 요구는 러너 요구 목록, gate 정의의 `hostRequirements`, workflow 주석에 있다 (1105/12-01) | `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `config/ci/gates.json`, `docs/operations/ci-quality-gates.md` | `9655958` | +| [계약] | release job `immutable_build`가 FE-GATE-015·027의 gate 로그·evidence와 의존성 advisory 기록을 결과와 상관없이 `immutable-gate-evidence--`로 올린다. 후보 archive와 그 upload는 그대로다 (1105/13-01) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `.gitea/workflows/quality-gates.yml` | `629c713` | + +### 그 밖의 수정 + +- 테스트: 제품 확장 타입 검사 탐침이 복사본의 `product-contracts.ts`·`product-composition.ts`를 덮어쓰지 않고 덧붙인다. 기능이 제품 capability를 쓰는 다운스트림에서도 FE-GATE-005가 통과한다 (1105/09-01, `397664e`) + +## 미출시(`main` `409d72e`에 합침) — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03` 한 번의 동기화로 받는 변경의 순 요약이다. 범위는 `main` `752a61f`부터 브랜치 `fix/maturity-review-2026-11-03`의 끝까지다. 이 절을 쓸 때 끝은 `f887817`이었다(병합 커밋을 빼고 310개). 그 뒤 깨끗한 clone 검증(merge 단계 14개)에서 찾은 수정과 pin 갱신을 더했다. 버전 번호와 태그는 아직 정하지 않았다. -- 2.54.0