docs: plan the 2026-09-25 maturity review fixes

SPEC maps all 138 findings to requirements and fixes the defaults for
the review's open choices (D-1..D-19). The plan runs gate/CI groundwork
first, then parallel area lanes, then integration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 21:05:08 +09:00
co-authored by Claude Opus 5.5
parent 412b3d1f1e
commit c5f379b82c
3 changed files with 286 additions and 734 deletions
+52 -213
View File
@@ -1,228 +1,67 @@
# SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정
# SPEC: 성숙도 리뷰(2026-09-25) 전 항목 반영
## 목적
`docs/reviews/2026-09-24-src-full-review.md`의 **긴급 1건 + 필수 46건**을 고친다. 권장·사소 항목은 이번 범위가 아니다.
`docs/reviews/2026-09-25-maturity-review/`의 발견 사항 **138건 전부**를 해결한다. 대상은 High 8 · Medium 57 · Low 73이다. 영역 문서 142건에서 같은 결함 4쌍과 포함 관계 1건을 합치고, 오케스트레이터 발견 00-01을 더한 수다.
각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 **무엇이 되면 완료인지**와 **방향이 여러 개인 항목의 결정**만 적는다.
요구사항 ID는 리뷰의 발견 ID와 같다(예: `03-01`). 이 문서에는 세 가지만 적는다. 문제 설명·근거·발생 조건은 리뷰 문서를 기준으로 한다.
## 범위 밖
- 모든 요구사항에 공통인 완료 기준
- 리뷰에서 방향이 여러 개였던 항목의 결정
- repo 밖이라 이 작업이 끝낼 수 없는 항목
- 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다.
- `src/` 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다.
- 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다.
**완료 기준의 기준은 해당 발견 항목의 "완료 기준" 칸이다.** 아래 결정 표가 그 칸과 다르게 정한 경우에만 결정 표를 따른다.
## 범위 밖 (repo 밖 · 사람이 해야 함)
이 항목들은 코드로 끝낼 수 없다. repo 쪽 준비만 하고, 나머지는 `tasks/todo.md` "사용자 몫"에 남긴다.
| ID | 사용자 몫 | repo 쪽에서 하는 것 |
|---|---|---|
| U-1 (12-01, 14-01) | Gitea 저장소 Actions 활성화, runner 연결, branch protection에 merge 게이트를 required check로 지정 | push 트리거에 `main` 추가, README에 CI 상태와 머지 전 로컬 명령 명시 |
| U-2 (08-06) | 릴리스 후보 하나로 10개 라우트 수동 접근성 검토 수행·서명 | 결정 D-8 |
| U-3 (14-04) | 태그 push | CHANGELOG, README 업데이트 절, 로컬 태그 |
| U-4 (14-03, 13-13) | 작성자 외 사람의 기능 추가 수행 기록, staging에서 공급망 end-to-end smoke | 문서 정비, "provider 없는 구성" 문서화 |
| U-5 (03-01) | 백엔드 멱등 키 보관·충돌 계약 확인 | 클라이언트는 같은 키 재전송만 보장 |
## 공통 완료 기준 (모든 요구사항)
1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다.
2. `corepack pnpm check:architecture`, `check:types:app`, `check:types:test`, `lint`, `test:unit`, `test:component`이 통과한다.
3. adapter 파일을 추가하거나 이동하면 `docs/reviews/adapters/INVENTORY.md`를 함께 고치고 `check:adapter-inventory`가 통과한다.
4. adapter 간 공용 로직은 `src/adapters/platform/`(kernel)으로, 공유 어휘는 `src/contracts/`로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다.
1. 동작을 바꾸는 요구사항은 재현 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이 재현할 수 없는 항목은 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구한 항목은 spec 하나를 추가한다.
2. 테스트 검출력이 문제였던 항목(변이 생존)은 리뷰에 적힌 변이를 다시 넣었을 때 새 테스트가 실패하는 것까지 확인한다.
3. 작업마다 다음 게이트가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
4. 레인이 끝날 때와 통합 때는 3번에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`도 통과한다.
5. adapter 파일을 추가하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 함께 고친다.
6. 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다.
7. 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다.
8. 작업 하나에 커밋 하나. 커밋 메시지에 발견 ID를 적는다. 그 작업이 바꾼 파일만 스테이징한다.
9. 문서 요구사항은 문서의 각 주장이 코드 위치를 가리키는 것으로 확인한다.
## 요구사항
## 결정
### R-0 빌드 기반 (긴급)
- 깨끗한 체크아웃(`src/.generated/` 없음)에서 `dev`, `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 사전 수동 명령 없이 동작한다.
- CI 게이트도 같은 조건에서 통과한다.
리뷰가 대안을 제시한 항목에 대해 기본값을 정했다. 계획 승인은 이 표의 승인이다.
### R-1 browser-transfer
- R-1.1 `dispose()`가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 `CLOSED`가 된다.
- R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다.
- R-1.3 동시성 정책 검증은 `partSize × maxConcurrency × copyFactor`를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 **실제 worker 수**를 요청한다.
- R-1.4 크기나 part 수 한도 초과는 `LIMIT_EXCEEDED`로 보고된다.
### R-2 browser-files / cache-storage / cross-context
- R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 `deliver()`는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다.
- R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 `NEXT`다.
- R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 `DEGRADED`로 보고된다.
- R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. `window` 함수를 그대로 주입해도 동작한다.
- R-2.5 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 받아들인다. `content-type`이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다.
### R-3 http / query-cache / auth
- R-3.1 경로 값 `.`과 `..`는 V3와 V2 모두에서 `PATH_VALUE_INVALID`(V2는 `PATH_PARAMETER_INVALID`)로 거부된다.
- R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 `onUnauthenticated()`를 부르지 않는다. 서버 401만 부른다. **[고위험: 인증·캐시]**
- R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(`ENVELOPE_MISMATCH`)로 매핑되지 않는다.
- R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. **[고위험: 인증]**
- R-3.5 feature 바인딩에서 `mapSuccess`/`mapProblem`이 던지면 `MAPPING_CONTRACT_VIOLATION` Result로 반환되고 effect가 보존된다.
### R-4 realtime
- R-4.1 `await quiescence` 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다.
- R-4.2 `retryable:true`인 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두).
- R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다.
- R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록).
### R-5 storage
- R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. **[고위험: 삭제]**
- R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). **[고위험: 삭제]**
- R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다.
- R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. **[고위험: 삭제]**
- R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. **[고위험: 데이터 판독]**
### R-6 service-worker / web-push
- R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 `registration.waiting`이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다.
- R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다.
- R-6.3 앱이 `reloadRequired`/`updateWaiting`을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다.
- R-6.4 첫 방문에서 설치 중인 워커는 `ACTIVE`로 보고되지 않는다.
- R-6.5 JavaScript MIME 동의어를 허용한다. `content-encoding`이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다.
- R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 `respondWith`를 부른다.
- R-6.7 reconcile에서 서버가 `ABSENT`이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. **[고위험: 동의]**
### R-7 contracts
- R-7.1 멱등 키는 `^[\x21-\x7E]{1,256}$`만 허용한다. 이 버그를 고정한 기존 테스트도 고친다.
- R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다.
- R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다.
- R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. `semantics`/`replayPolicy`는 enum으로 검증된다. **[고위험: CSRF]**
- R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다.
### R-8 presentation
- R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다.
- R-8.2 WebKit(`Importing a module script failed`)과 Vite CSS preload 실패가 청크 실패로 인식된다.
- R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다.
- R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다.
- R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다.
- R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다.
- R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 `recoverChunk`를 거친다.
- R-8.8 `enabled:false` 쿼리는 로딩으로 표시되지 않는다.
### R-9 bootstrap / platform
- R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다.
- R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다.
- R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin` 계열을 추가한다. **[고위험: 보안]**
## 결정 (방향이 여러 개였던 항목의 기본값)
| ID | 결정 | 이유 |
| ID | 대상 | 결정 |
|---|---|---|
| D-1 (R-0) | 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. | 6f6c48e가 앱별 생성(`PRODUCT_APP_ID`)을 의도했으므로 gitignore를 유지한다. |
| D-2 (R-1.3) | 기본 `maxConcurrency`를 실제 동작값에 맞춘다. 메모리 한도(`maxInFlightBytes`)는 올리지 않는다. | 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다. |
| D-3 (R-5.3) | lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. | 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다. |
| D-4 (R-2.3) | 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. | 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다. |
| D-5 (R-8.3) | 로케일 저장은 테마와 같은 `preferences` 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. | 이미 있는 테마 패턴을 재사용한다. |
| D-6 (R-9.2) | 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 `occurrences`로 보낸다. | 기존 이벤트 스키마(`occurrences`)를 그대로 쓴다. |
| D-7 (R-6.3) | previous 캐시 fallback은 hashed URL에만 적용한다. | hashed URL은 같은 URL이면 같은 내용이라 안전하다. |
| D-1 | 03-01, 08-03 | 결과 불명(`UNKNOWN`) admission의 intent를 보관한다. 같은 canonical input으로 다시 저장하면 그 intent(같은 `Idempotency-Key`)로 보내고, 입력이 바뀌면 새 키를 쓴다. 결과 불명 화면의 "변경되지 않음으로 확인"은 "같은 요청으로 다시 보내기"로 바꾸고, 목록 새로고침 링크를 둔다. "변경됨으로 확인"은 유지한다. |
| D-2 | 03-02, 08-01 | `CommandEffectDescriptor`에 선택 필드 `classifyStatus(status)`를 추가한다. 없으면 지금처럼 `MAYBE_APPLIED`다. `AUTH_REQUIRED`는 effect와 무관하게 재로그인을 먼저 안내한다. reference 생성 계약은 401·403·429를 `NOT_APPLIED`로 선언한다. 폼은 `reauth-required`·`forbidden`·`retry-later` 상태를 가진다. |
| D-3 | 05-01 | 트랜잭션별 Web Lock을 begin부터 complete까지 잡는다. reconcile은 `ifAvailable`로 잠기지 않은 행만 처리한다. |
| D-4 | 06-02 | Web Locks(`web-push-control`)로 enable·reconcile·revoke를 origin 단위로 직렬화한다. native `unsubscribe`는 그 호출이 새로 만든 구독에만 한다. |
| D-5 | 06-03 | 운영 문서를 코드에 맞춘다. 부팅을 막는 워커용 비상 경로로 "자기 해제 워커" 빌드 모드를 만들고, `REMOVE_REGISTRATION`이 이 워커를 내보내게 한다. |
| D-6 | 07-02, 13-10 | 경계별 호환 규칙 표를 문서에 넣는다. 분류기는 모르는 변경(타입·enum·nullable)을 `breaking`으로 답한다(fail-closed). FE-GATE-014는 커밋한 기준 스키마와 현재 빌드 스키마를 비교한다. |
| D-7 | 07-03 | V2 행과 V3 descriptor의 일치 테스트를 추가한다. V2를 V3에서 생성하는 작업은 하지 않는다. |
| D-8 | 08-06 | `review:a11y-manual`을 release 단계 게이트로 옮긴다. merge 단계에는 기록 형식 검사만 남긴다. 실제 수동 검토는 U-2다. |
| D-9 | 09-02 | 생성기(`generate-product-feature-index.ts`)가 `VITE_PRODUCT_FEATURES`를 읽어 선택된 기능만 인덱스에 넣는다. 잘못된 값은 생성 단계에서 실패한다. |
| D-10 | 09-07, 14-03 | 생성기는 `src/features/<f>/`에 `feature-module.ts`가 없고 `NOT_INSTALLED` 표식 파일도 없으면 실패한다. 제거 스크립트는 기능 ID를 인자로 받는다. |
| D-11 | 12-05 | dependency-cruiser 실행을 뺀다. `.dependency-cruiser.json`은 이름을 그대로 두고 규칙 파일로 쓴다(스크립트·문서·메모리 참조가 많다). 문서 3곳을 고친다. |
| D-12 | 12-10, 12-08 | 새 시스템을 만들지 않고 줄인다. import 관련 정규식 규칙(icon vendor, realtime import, design-system deep import)은 그래프 규칙으로 옮기고 정규식을 지운다. workflow 계약에는 "모든 gate id가 run step에 있다" 불변식을 둔다. `package-script-graph.ts`는 막는 위험이 `--ignore-scripts`·`allowBuilds`로 이미 막히는지 확인한다. 막히면 줄이고, 아니면 이유를 기록한다. |
| D-13 | 14-02 | CI 계약의 개수·해시를 코드 상수에서 `config/ci/contract-baseline.json`(owner·reason 포함)으로 옮긴다. 갱신 스크립트 `update:ci-contract-baseline`을 제공한다. 제거 스크립트는 완화 모드 대신 갱신 절차를 거쳐 canonical `check:ci`를 통과한다. |
| D-14 | 11-01, 13-03, 13-05 | 로컬에서 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 코드에 상수 `true` 판정을 두지 않는다. 운영 승격은 live·provider 증거를 요구한다. FE-GATE-016과 025의 중복을 정리한다. |
| D-15 | 14-04 | CHANGELOG, README "원본 업데이트 반영" 절, 로컬 태그 `v0.2.0`. 태그 push는 U-3이다. |
| D-16 | 14-05 | `docs/README.md` 색인을 만든다(현재 계약 / 목표 설계 / 작업 이력). `SPEC.md`와 `tasks/`는 이 작업에서 쓰므로 옮기지 않고, 색인에서 이력으로 표시한다. |
| D-17 | 12-01 | repo 쪽만 한다(U-1 참조). |
| D-18 | 11-04 | reference feature를 복제한 실제 모양 기능 25개·100개로 측정한다. 400개는 시간이 허용하면 측정한다. 호스트 부하 조건을 함께 기록한다. |
| D-19 | 12-12 | `noUnusedLocals`를 켠다. 여러 영역 파일을 건드리므로 모든 레인을 통합한 뒤 마지막 작업으로 한다. |
---
## 요구사항 목록
# 2차 라운드: 권장·사소 항목과 1차 후속 결정
1차 라운드(R-0 ~ R-9.3)는 `9bef702`로 main에 병합했다. 2차 라운드에서는 리뷰의 **권장·사소 항목 전부**와 1차에서 남긴 결정 두 건을 처리한다. 요구사항 ID는 `Q-<리뷰 섹션>` 형식이다(예: Q-6.1-5 = 리뷰 6.1-5).
## 공통 완료 기준 (2차)
1차 공통 기준과 같다. 여기에 두 가지를 더한다.
- **동작을 바꾸지 않는 정리(파일 분리, 중복 합치기)**: 새 RED 테스트 대신 기존 테스트가 안전망이다. 해당 경로에 테스트가 없으면 현재 동작을 고정하는 테스트(characterization)를 먼저 추가한다.
- **번들**: 정리가 끝난 뒤 `check:optional-recipes`가 통과해야 한다. 예산은 올리지 않는다(D-11).
## 요구사항
### browser-transfer
- Q-6.1-5 worker 하나가 실패하면 transfer 단위 abort로 나머지 worker를 즉시 멈춘다.
- Q-6.1-6 해석할 수 없는 checkpoint 행이 있어도 abort는 그 행을 지우고 ORPHANED로 보고한다.
- Q-6.1-7 PRIMARY_REQUIRED probe를 쓰는 preset은 fit이 cover/contain/fill일 때만 정책을 통과한다(D-12).
- Q-6.1-8 probe의 decode는 EXIF/irot 회전을 적용하지 않는다(`imageOrientation: "none"`).
- Q-6.1-9 presigned HTTP helper를 한 모듈로 합친다. statusFailure recovery를 통일하고, 쓰지 않는 `compensateLateResponse`는 삭제한다. download Content-Length를 엄격하게 파싱하고, runtime attempt는 kernel `createAbortableOperation`을 쓴다.
- Q-6.1-3b part마다 일어나는 방어적 복사 중 겹치는 것(`Uint8Array.from`과 `slice()`)을 하나로 줄인다.
- Q-6.1-10 `resumable-upload-runtime.ts`에서 서버 응답 검증과 의존성 snapshot 래퍼를 별도 모듈로 분리한다. 동작은 바꾸지 않는다.
- Q-6.1-11 vault `register`는 snapshot 값만 읽는다.
### browser-files / cache-storage / cross-context
- Q-6.2-6 cache 조회 비용: JSON은 chunk를 모아 읽고, 검증된 marker는 메모리에 캐시하고, asset 탐색은 Map으로 한다.
- Q-6.2-7 browser-files의 abort race를 kernel `race`와 compensate로 교체한다. 늦게 도착한 lease와 writable은 닫는다.
- Q-6.2-8 native `cancel`을 한 번이라도 관찰했으면 focus fallback을 끈다.
- Q-6.2-9 host factory가 비활성으로 끝날 때 observe로 보고한다. epoch는 releaseId를 인코딩해서 만든다.
- Q-6.2-10 파일명 자르기를 O(n)으로 바꾸고, 중복 호출을 하나로 줄인다.
- Q-6.2-11 `public-response-cache-adapter.ts`와 `download-delivery-adapter.ts`에서 코덱·검증 모듈을 분리한다. 동작은 바꾸지 않는다.
- Q-6.2-12 `MEDIA_TYPE`/opaque 정규식과 `positiveSafeInteger` 중복을 합치고, `object-url-lease.ts`의 죽은 분기를 지운다.
### http / browser-rpc / query-cache / auth
- Q-6.3-6 요청 종료 사유 판정을 `terminalOutcomeFor` 하나로 모은다. 백오프 중 scope fence는 scope 종료로 분류된다.
- Q-6.3-7 명령의 최종 effect는 누적 certainty와 합친다. `MAYBE_APPLIED`면 재시도하지 않는다.
- Q-6.3-8 namespace 무효화를 병렬로 실행한다.
- Q-6.3-9 RPC 명령이 전송 뒤 실패하면 `MAYBE_APPLIED`로 보고한다. 재시도 전에 scope를 확인하고, 소비자가 abort한 stream은 정리한다.
- Q-6.3-11 V2 401 복구를 재시도 예산과 분리한다. "롤백 가능 seam" 문서의 잘못된 주장을 고친다(V2와 V3는 wire 형식이 다르다).
- Q-6.3-12 cursor pagination의 누적 직렬화와 `push(...)` 한도 문제를 고친다. 쓰지 않는 `validTransportFailure`를 삭제하고, 따옴표가 닫히지 않은 `W/"` ETag를 거부한다.
- Q-6.3-3b V2도 5xx/408/425의 HTML/빈 바디를 status를 담은 서버 장애로 분류하고 재시도 대상으로 둔다.
### realtime
- Q-6.4-5 chunk당 item 상한을 넘으면 실패하지 않고 다음 처리로 넘긴다. COMMENT는 상수 객체를 쓴다.
- Q-6.4-6 dedupe는 FIFO로 제거하고, fingerprint는 해시로 저장하고, prune은 `break`한다. 가득 차도 전체 recovery를 하지 않는다.
- Q-6.4-7 재시도 예산은 유효 신호가 있고 `stableOpenMs`가 지났을 때만 초기화한다.
- Q-6.4-8 realtime 내부의 DataSnapshot과 abort/timeout race 헬퍼를 한 벌로 합친다. Retry-After 파싱과 JSON 중복 키 스캐너는 kernel(`src/adapters/platform/`)로 올리고, http retry-policy와 web-push codec도 이를 쓴다.
- Q-6.4-9 반복되는 attempt 정리를 `endAttempt()`로 뽑고, 무시되던 `_recovery` 파라미터를 없앤다.
- Q-6.4-10 probe 버퍼 상한을 현재 버퍼 기준으로 계산한다.
- Q-6.4-11 사소 항목: poll execute가 throw하면 retryable OFFLINE으로 둔다. BOM은 한 번만 제거하고, 이중 encode와 이벤트마다 만드는 TextEncoder를 없애고, 잘못 붙은 JSDoc을 옮긴다.
### storage
- Q-6.5-6 openObject는 사전 검증에서 manifest만 대조하고, root digest는 스트림 끝에서 확인한다.
- Q-6.5-7 IndexedDB 저장 행 타입·검증기·측정 공식을 `indexeddb-records.ts` 하나로 모은다. 동작은 바꾸지 않는다.
- Q-6.5-8 삭제 후 재생성하면 revision/generation이 다시 시작한다는 점을 port 주석과 문서에 명시한다(D-13).
- Q-6.5-9 보상이 실패해도 put의 원래 실패 코드를 유지하고, recovery만 RECONCILE로 바꾼다.
- Q-6.5-10 kernel: `succeed` 뒤에 온 `fail`이 이기도록 하고, settle된 뒤의 upgrade는 abort한다.
### service-worker / web-push
- Q-6.6-6b fetch 가로채기를 "same-origin GET, navigate 아님, 해시 파일명 또는 manifest URL"로 넓힌다. previous 캐시 fallback이 옛 빌드 chunk에 실제로 동작해야 한다(1차 T29/T32 후속, 사용자 결정).
- Q-6.6-8 후보 캐시 이름이 active 캐시와 같으면 설치 실패 시 지우지 않는다.
- Q-6.6-9 activate는 오래된 캐시부터 지우고, marker 쓰기 실패가 삭제를 막지 않는다.
- Q-6.6-10b 페이지 쪽 활성화 deadline에 워커 drain 시간과 여유분을 더한다.
- Q-6.6-11 알림 클릭이 거절되면 handoff 데이터 없이 앱 루트를 연다. 조용한 push drop은 트레이드오프를 문서에 명시한다(D-14).
- Q-6.6-12 web-push codec primitive(base64url, OPAQUE_ID, validAuthority, exactRecord)를 한 모듈로 합친다. page controller가 주입받은 document를 쓴다.
### contracts
- Q-6.7-6 exact-key/스냅샷 구현을 `exact-snapshot.ts` 하나로 모으고 배열 스냅샷을 추가한다. iterator·getter 우회를 막는다.
- Q-6.7-7 검증된 인덱스·레지스트리는 `createReadOnlyRegistry`를 쓰고 row마다 스냅샷해서 얼린다.
- Q-6.7-8 검증기 프로토콜과 `MappingResult`의 기준 모양을 하나로 정하고, 나머지는 호환 alias나 어댑터로 둔다(D-15).
- Q-6.7-9 REST 인증 프로필은 설치된 레지스트리 하나를 기준으로 한다. V2 resolve도 검증된 레지스트리를 쓴다.
- Q-6.7-10 배포 승인은 IPv6 loopback·ULA·link-local, IPv4-mapped, CGNAT, `0.0.0.0/8`, `.internal`/`.local`을 사설 주소로 본다. 로컬 호스트 목록은 한 곳에 둔다.
- Q-6.7-11 레지스트리 조회는 `Object.hasOwn`으로 한다. 목록에 없는 offline 전이는 false를 반환한다.
- Q-6.7-12 release-tokens는 비교하지 않은 값을 통과로 보고하지 않는다. contract-set 중복은 실패 코드로 반환한다. query-keys 정렬은 필요할 때만 한다. dependency-cruiser에 contracts → presentation/bootstrap 금지 규칙을 추가한다.
### presentation
- Q-6.8-9 디자인시스템 링크(`PageActionBar`, `Breadcrumbs`, `LinkButton`)는 router `Link`로 렌더한다. Pagination은 다른 검색 파라미터를 보존한다.
- Q-6.8-10 로딩·인증필요·404 화면을 하나씩으로 합치고, 세션 액션은 hook 하나로 묶는다. reject 시 멈추던 임시 로딩도 고친다.
- Q-6.8-11 Tooltip: `aria-describedby`를 포커스되는 자식에 붙이고, Escape로 닫는다.
- Q-6.8-12 Pagination은 현재 페이지 주변과 처음·끝만 보여주고(windowing), landmark 중첩을 없앤다.
- Q-6.8-13a 플랫폼 라우트의 `none` 코덱은 모르는 쿼리 파라미터를 거부하지 않고 무시한다(D-16).
- Q-6.8-13b 폼 제출은 비동기 검증 중에도 두 번 일어나지 않는다. 저장 직후 이동할 때 dirty guard가 뜨지 않는다.
- Q-6.8-13c 기본 fallback 문구는 현재 로케일을 따른다. SearchField를 지우면 입력으로 포커스를 돌려준다.
- Q-6.8-13d `theme.css`를 여러 파일로 나눈다. 빌드 결과 CSS 바이트가 달라지지 않아야 한다.
### application / features / bootstrap / platform (+ telemetry adapter)
- Q-6.9-4 텔레메트리 전송 계층을 하나로 합친다(rate limit, credentials `omit`, `pagehide` flush, dispose abort). best-effort fetch에 타임아웃을 둔다(6.3-10 포함).
- Q-6.9-5 킬스위치로 끈 feature는 `features.get()`이 API를 돌려주지 않는다.
- Q-6.9-6 adapter contribution의 featureId가 중복되거나 소속 module과 다르면 throw한다.
- Q-6.9-7 execution context interaction에 완료/정리 API를 두어 부모 signal listener가 남지 않게 한다.
- Q-6.9-8 부트 중에 정적 boot shell(로딩 표시, `aria-busy`)을 보여준다.
- Q-6.9-9 chunk와 boot의 "한 번만 reload" 가드를 공용 guard 하나로 합친다.
- Q-6.9-10 검증을 통과한 config 값만 safe 에러에 싣는다.
- Q-6.9-11 텔레메트리 버퍼는 필요한 공간이 확보될 때만 낮은 severity를 지운다. 주석을 코드와 맞춘다.
- Q-6.9-12 re-export만 하는 `reference-feature-runtime.tsx`를 삭제한다. CI 전용 정책(`promotion-readiness`, `performance-budgets`)은 src 소비자가 없으면 `scripts/`로 옮긴다. 메시지 로케일은 하드코딩하지 않고 카탈로그에서 도출한다.
### 통합
- Q-B 번들 예산: 모든 레인을 병합한 뒤 `check:optional-recipes`를 통과시킨다. 필요하면 해당 번들 코드를 줄인다(D-11).
## 결정 (2차)
| ID | 결정 |
|---|---|
| D-11 | 번들 예산은 올리지 않는다. 코드를 줄여 맞춘다(사용자 결정). |
| D-12 | PRIMARY_REQUIRED는 fit cover/contain/fill만 허용한다. 비율을 유지하는 fit은 probe를 쓰지 않는 preset에서만 허용한다. |
| D-13 | 삭제 뒤 revision 재시작(ABA)은 스키마를 바꾸지 않고 문서로 계약을 명시한다. tombstone 도입은 저장 스키마 변경이라 범위 밖이다. |
| D-14 | 클릭 실패 시 앱 루트를 연다. push drop은 설계 의도로 두고 문서에 명시한다. |
| D-15 | `external-contract-runtime`의 모양을 기준으로 삼는다. 다른 쪽은 호환 alias나 어댑터로 유지한다(공개 타입을 삭제하지 않음). |
| D-16 | 플랫폼 라우트의 모르는 쿼리 파라미터는 무시한다(strip). URL은 건드리지 않는다. |
---
# 3차 라운드: 남은 문제 8건
2차 뒤에 남은 문제 8건을 처리한다(사용자 결정 2026-09-24). ID는 `R3-n`이다.
- R3-1 HTTP V2: 408/425 응답을 안전하거나 멱등인 요청에 한해 재시도한다. `client.ts`의 Retry-After 파싱은 kernel `platform/retry-after.ts`를 쓴다.
- R3-2 업로드 fetch transport의 Retry-After 파싱도 kernel을 쓴다. file-transfer 번들은 동작을 바꾸지 않는 축소로 예산 대비 여유를 546B(1%) 이상 확보한다. 예산은 바꾸지 않는다.
- R3-3 세션 subject: demo 어댑터가 subject를 제공해서, 같은 사용자의 인증 상태 알림(토큰 갱신 등)은 캐시를 비우지 않는다. subject를 주지 않는 외부 owner는 fail-closed로 동작하고, 그 사실과 `readSubject` 구현 방법을 문서에 적는다.
- R3-4 꺼 둔(`enabled:false`) 쿼리는 `idle` 상태로 표시한다. loading이나 empty가 아니다. `AsyncSurface`는 idle에서 로딩이나 빈 상태 문구를 보여주지 않는다.
- R3-5 SSE 파서는 디코딩 전 바이트 단위로 줄 경계를 찾는다. 멀티바이트 입력에서도 원래 파서 대비 10배 이상 빨라진다(수동 벤치로 측정).
- R3-6 실제 브라우저 검증: 모바일 드로어 이동 후 포커스, bind하지 않은 picker 호출, 서비스 워커 두 빌드 간 업데이트와 옛 chunk의 이전 캐시 fallback, `application/javascript`와 gzip 응답의 static 설치, 실제 Cache API의 `Vary: Accept-Encoding`을 Playwright 스펙으로 확인한다. 여러 탭 OPFS 경합은 결정적으로 재현할 수 있으면 넣고, 없으면 그 이유를 기록한다.
- R3-7 WebKit: 시스템 라이브러리를 설치한 뒤 Playwright 스위트 전체를 WebKit으로 돌린다(Safari 청크 오류 메시지 포함).
- R3-8 원격 반영: 3차가 끝나면 브랜치를 push하고 Gitea PR을 만든다(사용자 결정).
138건과 작업의 대응은 `tasks/todo.md`에 있다. 모든 발견 ID가 정확히 한 작업에 속한다. 같은 결함 쌍(03-01=08-03, 12-02=13-01, 11-01=13-03, 07-01=08-02)과 포함 관계(09-11⊂12-04)는 한 작업에서 함께 닫는다.
+64 -123
View File
@@ -1,158 +1,99 @@
# Implementation Plan: src 리뷰 긴급·필수 항목 수정
# Implementation Plan: 성숙도 리뷰(2026-09-25) 전 항목 반영
## Overview
`SPEC.md`의 요구사항 47개(R-0 + R-1.1 ~ R-9.3)를 작업 50개로 나눠 고친다. R-3.2, R-6.3, R-8.3은 각각 두 작업으로 쪼갰다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 전체 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록과 완료 조건은 `tasks/todo.md`에 있다.
`SPEC.md`의 요구사항(리뷰 발견 138건, ID 기준 143개)을 작업 단위로 나눠 고친다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록은 `tasks/todo.md`에 있다.
- 브랜치: `fix/src-review-2026-09-24`
- 기준 커밋: `b04d570`
- 브랜치: `fix/maturity-review-2026-09-25`
- 기준 커밋: `4626b73`
## Architecture Decisions
- 결정 D-1 ~ D-7은 `SPEC.md` "결정" 표를 따른다.
- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
- 공개 포트는 추가만 한다. 기존 시그니처는 깨지 않는다.
- 버그를 정상 동작으로 고정한 기존 테스트는 같은 커밋에서 고친다. 해당 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`, `tests/unit/release-mismatch-recovery.test.ts:64` 부근, `tests/platform/telemetry/telemetry-pipeline.test.ts:93`.
- 결정 D-1 ~ D-19는 `SPEC.md` "결정" 표를 따른다.
- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다.
- 공개 포트는 추가만 한다.
- 버그를 정상 동작으로 고정한 기존 테스트(예: 12-02의 workflow 스냅샷 테스트)는 같은 커밋에서 고친다.
- `config/ci/gates.json`과 `.gitea/workflows/quality-gates.yml`은 Phase 0과 레인 K만 바꾼다. 다른 레인이 게이트 변경이 필요하면 레인 보고에 적고, 통합 때 반영한다.
## 실행 방식
1. **Phase 0 (순차):** T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다.
2. **Phase 1 (병렬 레인 9개):** 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 `fix/src-review-2026-09-24` HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다.
3. **통합 (순차):** 레인 브랜치를 하나씩 `fix/src-review-2026-09-24`에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트).
4. **최종 체크포인트:** 전체 게이트, `build`, 깨끗한 체크아웃 재현(`src/.generated` 삭제 후 게이트)을 확인한다.
직전 라운드(`fix/src-review-2026-09-24`)와 같은 구조다.
| 레인 | 영역 | 작업 |
|---|---|---|
| A | browser-transfer | T02–T05 |
| B | browser-files / cache / cross-context | T06–T10 |
| C | http / query-cache / auth | T11–T16 |
| D | realtime | T17–T20 |
| E | storage | T21–T25 |
| F | service-worker / web-push | T26–T33 |
| G | contracts | T34–T38 |
| H | presentation | T39–T47 |
| I | bootstrap / platform | T48–T50 |
1. **Phase 0 (순차):** 게이트·CI 기반 7개 작업. 이게 끝나야 새 clone, 샘플 제거, CI 계약이 이후 작업의 검증 수단으로 동작한다. Phase 0 뒤 Checkpoint 0.
2. **Phase 1 (병렬 레인):** 레인마다 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 Phase 0이 반영된 브랜치 HEAD에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 진행한다(RED → GREEN → 게이트 → 커밋). 호스트 부하를 줄이려고 두 묶음으로 나눈다.
- 1차: A, C, E, I, K (작업이 많거나 위험이 큰 레인)
- 2차: B, D, F, G, H, J, M
3. **통합 (순차):** 레인 브랜치를 하나씩 rebase해 병합하고, 병합할 때마다 공통 게이트를 돌린다.
4. **통합 후 작업:** 12-12, 14-07, 리뷰 색인 상태 갱신.
5. **최종 체크포인트:** 전체 게이트, `build`, `test:sample-removal`, 깨끗한 worktree 재현.
레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 `docs/reviews/adapters/INVENTORY.md`(adapter 파일 추가 시)와 `src/bootstrap/`(H의 T45와 I)이다. 통합 단계에서 해결한다.
worktree 준비 규칙: `node_modules`는 최상위 항목마다 심볼릭 링크를 건다. pnpm 상태 파일(`.pnpm-workspace-state-v1.json`, `.modules.yaml`, `.package-map.json`)은 복사하고, 상태 파일의 프로젝트 경로를 worktree로 바꾼다. 이 방식이면 worktree에서 `corepack pnpm <script>`를 돌려도 설치 단계가 돌지 않는다. 공유 `node_modules`도 바뀌지 않는다(2026-09-25 시험 확인).
| 레인 | 영역 | 작업 수 | 겹칠 수 있는 파일 |
|---|---|---|---|
| Z | Phase 0 · 통합 후 | 7 + 2 | — |
| A | browser-transfer | 11 | INVENTORY |
| B | browser-files / cache | 9 | INVENTORY |
| C | HTTP·서버 상태·인증·텔레메트리 | 11 | `application-query.ts`, `async-surface.tsx`, `use-app-form.ts`(C가 소유) |
| D | realtime | 8 | INVENTORY |
| E | 저장소·kernel | 14 | `tests/helpers/memory-indexeddb.ts`, INVENTORY |
| F | Service Worker / Web Push | 10 | `create-runtime-composition.ts`(I와) |
| G | contracts | 6 | `src/contracts/compatibility.ts` |
| H | presentation | 10 | `catalog.ts`, e2e spec |
| I | 앱 코어·조립·빌드 입력 | 14 | `src/contracts/env.ts`, 제거 스크립트, 생성기 |
| J | 테스트 체계 | 10 | `tests/setup.ts`, `vitest.config.ts`, Playwright 설정 |
| K | CI·가드레일·릴리스 | 19 | `gates.json`, workflow, `check-architecture.ts`, `eslint.config.ts` |
| M | 템플릿 제품성·문서 | 3 | README |
겹치는 파일은 소유 레인을 위 표로 정했다. 소유하지 않은 레인이 그 파일을 바꿔야 하면 레인 보고에 적고, 통합 때 반영한다.
## Task List (요약 — 상세는 tasks/todo.md)
### Phase 0: 기반
- [x] T01 R-0 깨끗한 체크아웃에서 게이트 동작
- [ ] 10-01, 00-01, 14-01, 14-02, 12-02·13-01, 12-01, 12-04·09-11
### Checkpoint 0
- [x] `src/.generated` 삭제 후 arch/types/lint/unit/component/verify:documentation 통과
- [ ] 공통 게이트 + `check:ci` + `test:sample-removal` + `build`
### Phase 1: 레인 A–I (병렬)
- [x] 레인 A: T02–T05
- [x] 레인 B: T06–T10
- [x] 레인 C: T11–T16 (고위험 T12, T13, T15 포함)
- [x] 레인 D: T17–T20
- [x] 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함)
- [x] 레인 F: T26–T33 (고위험 T33 포함)
- [x] 레인 G: T34–T38 (고위험 T37 포함)
- [x] 레인 H: T39–T47
- [x] 레인 I: T48–T50 (고위험 T50 포함)
### Phase 1: 레인 A–M
- [ ] 1차: A, C, E, I, K
- [ ] 2차: B, D, F, G, H, J, M
### Checkpoint 레인별 (통합할 때마다)
- [x] check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과
- [x] adapter 파일을 바꿨으면 check:adapter-inventory 통과
- [ ] 공통 게이트 + `check:ci` + `check:adapter-inventory`
### 통합 후
- [ ] 12-12, 14-07, 리뷰 색인 갱신
### Checkpoint 최종
- [x] 위 게이트 + `corepack pnpm build` 통과
- [x] 깨끗한 체크아웃 재현 통과
- [x] 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크)
- [ ] 공통 게이트 + `check:ci` + `check:adapter-inventory` + `verify:documentation` + `test:sample-removal` + `build`
- [ ] 깨끗한 worktree 재현
- [ ] 발견 143개 ID 모두 체크
## 고위험 작업 (계획 승인 = 이 작업들의 사전 승인)
| 작업 | 이유 | 안전장치 |
|---|---|---|
| T12, T13 (R-3.2) | 세션·캐시 fence 동작이 바뀜 | 상태가 실제로 바뀌면 여전히 fence됨을 테스트로 고정 |
| T15 (R-3.4) | 자격증명 헤더 검증 | 기존 정상 토큰 통과 테스트 유지 |
| T21, T22, T24 (R-5.1, R-5.2, R-5.4) | 삭제 경로 | 참조 중 청크와 다른 파티션 행은 절대 지우지 않음을 테스트로 고정 |
| T25 (R-5.5) | 저장 데이터 판독 규칙 | 기존 manifest 객체가 정책 변경 뒤에도 읽힘을 테스트로 고정 |
| T33 (R-6.7) | 푸시 동의 | 크래시 복구(local ACTIVE) 재등록은 유지됨을 테스트로 고정 |
| T37 (R-7.4) | CSRF 규칙 강화 | 설치된 기존 operation이 모두 통과함을 확인 |
| T50 (R-9.3) | 리댁션 | 정상 텔레메트리 값(enum, id)이 가려지지 않음을 테스트로 고정 |
| 03-01, 03-02, 08-01 | 결과 불명 쓰기·인증 실패 처리가 바뀜 | 입력이 바뀌면 새 키. 결과 불명 뒤 자동 재전송은 여전히 없음(사용자 행동으로만). 기존 fence 테스트 유지 |
| 05-03, 05-04, 05-05 | 삭제 경로 | LOGOUT/ACCOUNT_DELETION과 authority 승인 proof가 있을 때만 DB 삭제. 다른 partition·정상 행은 지우지 않음을 테스트로 고정 |
| 05-01, 05-02 | 저장 데이터 판독·정리 | 기존 journal·receipt가 읽히는지 테스트로 고정 |
| 06-02, 06-06 | 푸시 구독 해지 | 다른 탭·다른 계정의 정상 구독을 지우지 않음을 테스트로 고정 |
| 13-06 | 번들에 들어가는 설정 | 필요한 `VITE_*` 값이 모두 번들에 남음을 테스트로 고정 |
| 09-02, 09-07 | 기능 선택·설치 규칙 | 기본값(전체 설치)의 산출물이 바뀌지 않음을 확인 |
| 11-01, 13-03, 13-05 | 승격 판정 의미 변경(PASS → UNVERIFIED) | 로컬 증거 생성 경로는 그대로 두고 판정 이름만 정직하게 |
| 12-12 | 여러 영역 파일 수정 | 통합 뒤 단독 작업, 동작 변경 없음 |
모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다.
모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다. 태그는 로컬만 만들고 push하지 않는다.
## Risks and Mitigations
| Risk | Impact | Mitigation |
| 위험 | 영향 | 대응 |
|---|---|---|
| worktree마다 `node_modules`가 없음 | Med | 레인 시작 시 `corepack pnpm install --frozen-lockfile --prefer-offline` |
| 레인 9개가 동시에 테스트를 돌려 느려짐 | Low | 레인 안에서는 관련 테스트만, 커밋 전에만 전체 unit/component |
| INVENTORY.md 병합 충돌 | Low | 통합 단계에서 수동 병합 후 `check:adapter-inventory` |
| 브라우저에서만 재현되는 항목(T06, T09, T26, T29, T31, T32, T44) | Med | fake로 조건을 재현. 실제 브라우저 확인은 "미검증"으로 최종 보고 |
| T20 성능 요구(10배)는 CI에서 측정하기 불안정 | Low | 정확성 테스트는 자동, 성능은 벤치 스크립트 수동 측정값을 커밋 메시지에 기록 |
| R-0 방식이 pnpm pre/post 훅에 의존하면 환경마다 다름 | Med | 훅에 의존하지 않고 진입점에서 명시적으로 생성 |
| 레인 병렬 실행 부하로 시간 의존 테스트가 흔들림(10-02) | 가짜 실패 | 무관한 실패는 단독 재실행으로 확인하고 레인 보고에 적는다. 10-02는 레인 J에서 고친다 |
| 레인 간 파일 충돌 | 통합 지연 | 소유 레인 표. 통합은 레인 하나씩, 병합마다 게이트 |
| `gates.json` 변경마다 CI 계약 해시가 바뀜 | 게이트 실패 | 14-02를 Phase 0에서 먼저 끝낸다. 이후 변경은 `update:ci-contract-baseline`으로 기준을 갱신한다 |
| 리뷰가 제안한 방향이 실제 코드에서 더 큰 변경을 요구 | 범위 증가 | 결정 표 밖의 설계가 필요하면 멈추고 사용자에게 묻는다 |
## 결과 (2026-09-24)
## Open Questions
50개 작업을 모두 커밋했다. 레인 9개를 병합할 때마다 전체 게이트를 돌렸다.
깨끗한 체크아웃(`src/.generated` 삭제) 기준 최종 게이트 결과:
- 통과: check:architecture, check:types, lint, test:runtime-schema(53), test:unit(1890), test:contract(12), test:component(149), test:integration(104), test:recipes(17), test:reference-feature(56), test:platform(245), check:release-coherence(46), check:adapter-inventory, check:registries, check:ci, verify:documentation, build
- Playwright: test:e2e는 Chromium·Firefox 전부 통과, test:browser-capabilities도 Chromium·Firefox 전부 통과. WebKit은 이 머신에 시스템 의존성이 없어 실행 자체가 안 됨(`playwright install-deps` 필요)
계획 밖에서 추가로 한 일:
- R-0 1차 수정이 진입점 36개를 놓쳤다. 여기에는 CI 게이트 실행기 `ci:gate`와 `check:ci`가 포함된다. 가드 테스트가 import를 따라가 검사하도록 바꾸고 누락분을 채웠다(`7dfb89f`).
- `check:adapter-inventory`가 기준 브랜치에서도 실패하고 있었다(6f6c48e에서 추가한 파일 2개가 인벤토리에 없음). 행을 추가했다(`2fb07c8`).
## Open Questions (사용자 결정 필요)
1. **번들 예산**: `check:optional-recipes`가 기준 커밋부터 실패하고 있었다. 기준 커밋 대비 file-transfer는 99바이트 줄었고, realtime은 초과폭이 9바이트에서 139바이트로 늘었다. offline-indexeddb는 이번 수정으로 예산을 56바이트 새로 넘었다. 예산을 올릴지, 코드를 줄일지 결정이 필요하다.
2. **T29(R-6.3b) vs T32(R-6.6)**: fetch를 manifest URL로만 가로채도록 좁혔기 때문에, 이전 캐시 fallback은 현재 manifest에 있는 URL에만 적용된다. 리뷰의 원래 시나리오(옛 빌드 lazy chunk)는 여전히 네트워크로만 간다. 가로채는 범위를 "same-origin GET + 해시 파일명"으로 넓힐지 결정이 필요하다.
3. **T12(R-3.2a)**: 기존 owner는 subject를 제공하지 않는다. 그래서 인증 상태에서 인증 상태로 오는 알림(토큰 갱신 등)은 owner가 `readSubject`를 구현하기 전까지 여전히 캐시를 비운다. fail-closed 기본값이다.
4. **T41(R-8.8)**: disabled 쿼리는 이제 `empty`("데이터가 없습니다")로 보인다. 의존 쿼리에 이 화면이 맞지 않다면 `idle` 상태를 따로 만들어야 한다.
5. **T20(R-4.4)**: 250KB 벤치에서 ASCII는 36~80배 빨라졌지만 멀티바이트 위주 입력은 약 5배에 그쳤다. 10배 목표는 ASCII만 달성했다.
6. **T14(R-3.3)**: V2 client(`client.ts`)는 바꾸지 않았다. V2에서 HTML 바디 502는 여전히 CONTENT_TYPE_MISMATCH이고 재시도하지 않는다.
실제 브라우저에서 따로 확인해야 하는 항목: SW 두 빌드 간 업데이트 순서(T26~T30), 실제 서버의 MIME·gzip 응답(T31), 네이티브 file picker 호출(T09), `Cache.match`와 Vary(T10), 멀티 탭 OPFS 경합(T22), 모바일 드로어 포커스(T44), Safari 청크 오류 메시지(T40). WebKit 계열은 전부 미검증이다.
---
# 2차 라운드 계획
- 브랜치: `fix/src-review-round2` (main `9bef702`에서 분기)
- 범위: `SPEC.md` 2차 라운드 절, 작업 T51–T115 (`tasks/todo.md`)
- 실행 방식: 1차와 같다. 레인 A–I를 병렬 worktree에서 진행하고, 레인마다 cherry-pick한 뒤 전체 게이트를 돌린다. 마지막 T115(번들 예산)는 통합 단계에서 한다.
- 레인 사이 공유 파일: `http/retry-policy.ts`(C는 retryKinds, D는 Retry-After 파서), `http/client.ts`(C, 그리고 G의 한 줄), `web-push/push-codec.ts`(D는 중복 키 스캔, F는 나머지), `INVENTORY.md`. 충돌이 나면 통합 단계에서 해결한다.
- 최종 확인: 1차와 같은 게이트 목록 + `check:optional-recipes` + Playwright(Chromium/Firefox).
## 2차 결과 (2026-09-24)
T51–T115를 모두 커밋했다. 레인 9개와 T115를 병합할 때마다 전체 게이트를 돌렸다.
깨끗한 체크아웃 기준 최종 결과:
- 통과: check:architecture, check:types, lint, runtime-schema(55), unit(2057), contract(14), component(177), integration(110), recipes(17), reference-feature(59), platform(248), release-coherence(46), adapter-inventory(래칫 17/17), registries, ci, diagnostics, i18n, design-system, realtime-boundaries, verify:documentation, build, **check:optional-recipes**
- 번들 예산: file-transfer 54562/54600, offline-indexeddb 35854/36000, realtime 39685/40000, service-worker-pwa 9500/10000
- Playwright(Chromium·Firefox): e2e 66, browser-capabilities 30 전부 통과. WebKit은 이 머신에서 실행 불가
사용자가 알아야 할 동작 변경은 커밋 메시지와 각 Q-ID에 적었다. 주요 항목:
- presigned provider의 401/403/429/5xx recovery가 REISSUE_CAPABILITY로 통일됐다(T55)
- contracts 레지스트리가 accessor, 비열거 키, 커스텀 prototype을 거부한다(T91)
- 킬스위치로 끈 feature는 API를 받지 않는다(T107)
- 텔레메트리 전송 한도는 두 포트 합쳐 분당 20회다(T106)
- 플랫폼 라우트는 모르는 쿼리를 무시한다(T102)
남은 것:
- file-transfer 번들 여유가 38바이트뿐이다
- V2에서 408/425는 SERVER_FAILURE로 분류되지만 재시도하지 않는다(T72)
- Retry-After 복사본 2곳(http client, resumable fetch transport)은 커널로 옮기지 않았다
## 3차 결과 (2026-09-24)
- R3-1 V2 408/425/503: 안전하거나 멱등인 요청만 재시도하고, Retry-After는 kernel 파서로 읽는다. 408/425는 본문 형식과 관계없이 SERVER_FAILURE로 분류한다.
- R3-2 업로드 fetch transport의 Retry-After를 kernel로 옮겼다. file-transfer 54468/54600(여유 132B). **목표였던 546B에는 414B가 모자란다.** 같은 코드 여러 벌을 하나로 합쳐도 gzip이 이미 반복을 압축해서 크기가 거의 줄지 않는다. 더 줄이려면 presigned나 resumable 흐름을 크게 다시 쓰거나, 예산을 새로 정해야 한다.
- R3-3 demo 세션에 subject를 붙였다. `readSubject`가 무엇을 반환해야 하는지와 fail-closed 기본 동작을 문서에 적었다.
- R3-4 꺼 둔 쿼리는 `idle` 상태가 된다. `AsyncSurface`에 선택형 `idle` slot을 추가했다.
- R3-5 SSE 파서가 바이트 단위로 줄 경계를 찾는다. 멀티바이트 입력은 원래 파서보다 약 53배, ASCII는 약 348배 빠르다.
- R3-6 실제 브라우저 스펙 5종을 추가했다(드로어 포커스, picker receiver, SW 두 빌드 업데이트와 옛 chunk fallback, install 헤더, Cache API Vary).
- 이 스펙들이 제품 버그 2건을 찾았고 둘 다 고쳤다. 하나는 ACTIVE 워커 빌드 실패, 다른 하나는 호스팅 헤더 게이트가 ACTIVE 빌드를 거부하던 문제다.
- 여러 탭 OPFS 경합은 결정적으로 재현할 방법이 없어 스펙을 넣지 않았다. 60초 이상 grace period를 기다려야 하고, 페이지 쪽 참조 확인 사이에 끼워 넣을 수단이 없다.
- Firefox에서는 Playwright의 SW 제어 제약 때문에 SW 업데이트 스펙이 skip된다.
- 최종 확인(깨끗한 체크아웃): 모든 게이트 통과(unit 2077, component 182, integration 151, check:optional-recipes 포함). Playwright Chromium·Firefox는 e2e 76건 통과(skip 2), browser-capabilities 34건 통과.
- T122 WebKit: 시스템 라이브러리를 설치한 뒤 e2e 39건과 browser-capabilities 17건이 모두 통과했다. 청크 오류 문구 스펙(`tests/browser-capabilities/chunk-load-error.spec.ts`)은 Chromium·Firefox·WebKit에서 앱 판별 함수가 실제 엔진 문구를 인식하는지 확인하고, 세 엔진 모두 통과했다.
- 남은 것: T123 push와 PR. SW 파일에 `Cache-Control: no-cache` 헤더가 붙는지는 호스팅 검사가 확인하지 않는다(범위 밖).
- 없음. 결정 표 기본값으로 진행한다. 결정을 바꾸려면 승인 전에 알려 주면 된다.
+170 -398
View File
@@ -1,440 +1,212 @@
# Tasks: src 리뷰 긴급·필수 항목 수정
# Tasks: 성숙도 리뷰(2026-09-25) 전 항목 반영
각 작업의 문제 설명은 `docs/reviews/2026-09-24-src-full-review.md` 해당 섹션을 본다. 요구사항은 `SPEC.md`, 실행 방식은 `tasks/plan.md`에 있다.
작업 ID는 리뷰의 발견 ID다. 문제 설명·근거·검증 방법은 `docs/reviews/2026-09-25-maturity-review/<영역 문서>`의 같은 ID 항목을 본다. 결정은 `SPEC.md` "결정" 표(D-x), 실행 방식은 `tasks/plan.md`를 따른다.
## 모든 작업에 공통인 검증
- [x] RED: 재현 테스트가 수정 전에 실패한다
- [x] GREEN: 해당 테스트 파일 통과 — `node scripts/run-vitest.ts run <test file>`
- [x] 게이트 통과 — `corepack pnpm check:architecture && corepack pnpm check:types:app && corepack pnpm check:types:test && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component`
- [x] adapter 파일을 추가하거나 이동했으면 `docs/reviews/adapters/INVENTORY.md`를 갱신하고 `corepack pnpm check:adapter-inventory` 통과
- [x] 커밋 1개, 메시지에 R-ID 포함, 해당 작업 파일만 스테이징
- RED: 재현 테스트가 수정 전에 실패한다(문서만 바꾸는 작업은 제외)
- GREEN: 해당 테스트 파일 통과 — `node scripts/run-vitest.ts run <test file>`
- 게이트 통과 — `corepack pnpm check:architecture && corepack pnpm check:types && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:contract && corepack pnpm test:runtime-schema`
- adapter 파일을 추가·이동했으면 `docs/reviews/adapters/INVENTORY.md` 갱신 + `corepack pnpm check:adapter-inventory`
- 커밋 1개. 메시지에 발견 ID. 그 작업의 파일만 스테이징
---
## Phase 0
## Phase 0 — 게이트·CI 기반 (순차, 레인 Z)
### T01 — R-0 깨끗한 체크아웃에서 게이트 동작 (리뷰 6.0)
- 완료 조건:
- [x] `rm -rf src/.generated` 뒤 `dev`(기동까지), `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 통과한다
- [x] CI(`config/ci/gates.json` → 생성 workflow)도 생성 단계를 거친다. `check:ci-contract` 등 관련 검사가 통과한다
- 테스트: 스크립트 레벨 검증(위 명령). 필요하면 `tests/scripts/generate-product-feature-index.test.ts`에 보강
- 파일: `package.json`, `scripts/*`(진입점), `config/ci/gates.json`, 생성 workflow
- 의존: 없음 · 크기: M
- [ ] 10-01 새 clone에서 `test:unit` 통과 — 완료: `removal-fixture.test.ts`가 임시 폴더의 가짜 증거로 검사. 새 worktree에서 `test:unit` 통과
- [ ] 00-01 fixture가 공유 `node_modules`의 pnpm 상태 파일을 덮어쓰지 않음 — 완료: 통합 테스트 전후 원본 상태 파일 해시 동일
- [ ] 14-01 샘플 제거 게이트 복구 — 완료: 플랫폼 테스트 6개가 샘플 대신 테스트 전용 기능·platform route 사용. `test:sample-removal` PASS(13 testcase 성공)
- [ ] 14-02 CI 계약 기준값 외부화 (D-13) — 완료: `config/ci/contract-baseline.json` + `update:ci-contract-baseline`. 샘플 제거 fixture가 `CI_CONTRACT_MODE` 없이 canonical `check:ci`·`check:registries` 통과
- [ ] 12-02 · 13-01 workflow가 job의 모든 gate 실행 — 완료: workflow에 `ci:gate -- FE-GATE-027`. 계약 검사가 run step 누락 변형을 거부. `APP_PROFILE`≠`RELEASE_TARGET`이면 실패. 변수 문서화
- [ ] 12-01 (repo 쪽, D-17) — 완료: push 트리거에 `main`. README에 CI 상태와 머지 전 로컬 명령
- [ ] 12-04 · 09-11 CI 밖 테스트·검사 연결 — 완료: `tests/architecture`·`release`·`scripts`·`features` 최상위·`scale/browser-soak.contract`·`scripts/verify-extreme-scale`과 `check:adapter-inventory`, image fixture가 게이트에 연결. 고아 테스트를 잡는 계약 검사와 음성 fixture
### Checkpoint 0
- [ ] 공통 게이트 + `check:ci` + `test:sample-removal` + `build` 통과
---
## 레인 A — browser-transfer
## 레인 A — browser-transfer (`01-adapters-browser-transfer.md`)
### T02 — R-1.1 dispose 재시도 가능 (6.1-1)
- 완료 조건: [x] deadline 초과 뒤 작업이 끝나면 두 번째 `dispose()`가 성공하고 `lifecycle()==="CLOSED"`, checkpoint store가 닫힌다
- 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts`
- 파일: `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts`
- 의존: T01 · 크기: S
- [ ] 01-01 PUT 401/403·만료 → capability 재발급 재시도
- [ ] 01-04 같은 idempotency key 재사용 테스트 3개 — 완료: 변이 M1·M6·M7 검출
- [ ] 01-02 완료·결과 불명 업로드 보고 — 완료: complete 성공 뒤 정리 실패도 성공 반환, `abort()` ALREADY_COMPLETED에 resourceId
- [ ] 01-03 크기·진행 기반 전송 제한 — 완료: 1Mbit/s 모의에서 5MiB part 성공, 멈춘 연결은 idle 제한 안에 끊김
- [ ] 01-05 recovery → 행동 1:1 — 완료: ABORT_PENDING과 CAS 충돌 실패값 구분, port 주석 표
- [ ] 01-06 `maxClockSkewMs`
- [ ] 01-07 vault 항목 `finally` 정리
- [ ] 01-08 재개 시 정책 재검사 제거
- [ ] 01-09 part 수 상한 × 전송 상한 교차 검사
- [ ] 01-10 `UPLOAD_PART` 관측 1건 + 시도 수 bucket
- [ ] 01-11 image probe 동시 상한·재사용
### T03 — R-1.4 크기 초과는 LIMIT_EXCEEDED (6.1-4)
- 완료 조건: [x] `maxFileBytes`/`maxPartCount` 초과 upload가 `LIMIT_EXCEEDED`를 반환한다
- 테스트: `tests/unit/resumable-upload-runtime.test.ts`
- 파일: `resumable-upload-runtime.ts`
- 의존: T01 · 크기: S
## 레인 B — browser-files / cache (`02-adapters-browser-files-cache.md`)
### T04 — R-1.2 opaque ID 문법 단일화 (6.1-2)
- 완료 조건: [x] `-`/`_`로 시작하는 43자 base64url ID가 session, part 발급, download 발급까지 통과한다 [x] 정규식 정의는 한 곳
- 테스트: `tests/unit/presigned-transfer*.test.ts` 또는 `resumable-upload-*` 중 해당 파일
- 파일: `resumable-upload/checkpoint-schema.ts`, `presigned/presigned-capability-http-provider.ts`, `presigned/presigned-transfer-executor.ts`
- 의존: T01 · 크기: S
- [ ] 02-01 preview 직후 abort → ABORTED, lease 증가 없음
- [ ] 02-02 Cache Storage 익명 요청 규칙 테스트
- [ ] 02-03 로그아웃 시 runtime dispose 문서·recipe
- [ ] 02-04 lease 한도 초과 retryable
- [ ] 02-05 `inspect()` 실제 보장
- [ ] 02-06 취소와 handoff 성공 관측 구분
- [ ] 02-07 조회당 `keys()` 1번·복사 2번 이하
- [ ] 02-08 가려진 규칙 5개 단독 테스트 — 완료: 변이 5개 검출
- [ ] 02-09 cross-tab 설계 문서 현행화
### T05 — R-1.3 동시성 정책 정합 (6.1-3, D-2)
- 완료 조건: [x] 정책 검증이 `partSize×maxConcurrency×copyFactor > maxInFlightBytes`를 거절한다 [x] 기본 정책이 검증을 통과한다 [x] createSession이 실제 worker 수를 요청한다
- 테스트: `tests/unit/resumable-upload-runtime.test.ts`(기본 정책 사용 케이스)
- 파일: `resumable-upload/runtime-policy.ts`, `resumable-upload-runtime.ts`, 필요 시 `docs/architecture/presigned-transfer-and-image-cdn.md`
- 의존: T01 · 크기: S
## 레인 C — HTTP·서버 상태·인증·텔레메트리 (`03-adapters-http-state.md`)
## 레인 B — browser-files / cache-storage / cross-context
- [ ] 03-01 · 08-03 결과 불명 쓰기의 같은 키 재전송 (D-1) — 완료: 504 뒤 재전송의 `Idempotency-Key` 동일, 근거 없는 "변경되지 않음" 확정 경로 없음
- [ ] 03-02 401/403/429 분류 (D-2)
- [ ] 08-01 폼 저장 실패 상태 분리 (D-2) — 완료: 401·403·429가 서로 다른 문구·행동, "입력 내용을 확인해 주세요" 제목 없음
- [ ] 03-03 correlation id → `requestId`, 요청 식별자 헤더
- [ ] 03-04 V3 422 필드 오류가 폼까지
- [ ] 03-05 텔레메트리 keepalive 64KiB 분할
- [ ] 10-03 KEYED·retryBudget 2 실행기 테스트 — 완료: 변이 M1b 검출
- [ ] 13-11 텔레메트리 envelope에 `build_id`·`release_id`
- [ ] 03-06 전송별 재시도·타임아웃 규칙 표
- [ ] 03-07 전송 0회 미인증은 telemetry 0건
- [ ] 03-08 HTTP 복구 runbook 현행화
### T06 — R-2.1 BOUNDED_OBJECT_URL open 실패 시 Result 반환 (6.2-1)
- 완료 조건: [x] presigned source + BOUNDED_OBJECT_URL에서 open 중 abort하면 `deliver()`가 `{ok:false, ABORTED}`로 resolve된다 [x] 늦게 온 lease가 닫힌다
- 테스트: `tests/unit/browser-file-download.test.ts`
- 파일: `src/adapters/browser-files/download-delivery-adapter.ts`
- 의존: T01 · 크기: S
## 레인 D — realtime (`04-adapters-realtime.md`)
### T07 — R-2.2 watermark를 TTL과 분리 (6.2-2)
- 완료 조건: [x] 같은 source의 seq 1 → 61초 뒤 seq 2가 `NEXT`로 전달된다 [x] watermark 메모리는 `sourceCapacity`로만 제한된다
- 테스트: `tests/unit/cross-tab-invalidation.test.ts`
- 파일: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts`
- 의존: T01 · 크기: S
- [ ] 04-01 모든 세션 종료 경로에서 예산 초기화, offline 동안 예산 정지
- [ ] 04-02 SSE Retry-After bridge
- [ ] 04-03 미등록 이벤트 타입 → freshness UNKNOWN, 별도 사유
- [ ] 04-04 닫기 책임 주석(또는 구독)
- [ ] 04-05 큰 chunk 분할
- [ ] 04-06 SSE idle timeout 테스트 — 완료: 변이 M7 검출
- [ ] 04-07 reconnect·poll 관측 hook
- [ ] 04-08 VD-28·설계 5.3 현행화
### T08 — R-2.3 발행 실패 뒤에도 수신 유지, 수신 불가면 DEGRADED (6.2-3, D-4)
- 완료 조건: [x] postMessage가 한 번 실패한 탭이 다른 탭의 broadcast를 계속 받는다 [x] BroadcastChannel을 만들 수 없는 탭의 status가 DEGRADED다
- 테스트: `tests/unit/cross-tab-invalidation.test.ts`(발행 탭은 정상, 수신 탭이 실패하는 구성)
- 파일: `browser-cross-context-invalidation.ts`, 필요 시 status 타입(`src/application/ports/…`)
- 의존: T07 · 크기: S
## 레인 E — 저장소·kernel (`05-adapters-storage-kernel.md`)
### T09 — R-2.4 picker 함수 bind 제거 (6.2-4)
- 완료 조건: [x] `this`가 options이면 throw하는 fake picker를 주입해도 picker와 save가 동작한다
- 테스트: `tests/unit/browser-file-picker.test.ts`, `tests/unit/browser-file-download.test.ts`
- 파일: `src/adapters/browser-files/browser-file-picker.ts`, `download-delivery-adapter.ts`
- 의존: T06 · 크기: S
- [ ] 05-01 OPFS reconcile vs 진행 중 put (D-3) — 완료: 공유 root 2런타임에서 put 성공이면 open 성공, reconcile은 행 건너뜀
- [ ] 05-02 빈 receipt = 없음, reconcile 루프 계속 → GC 도달
- [ ] 05-08 메모리 IndexedDB 대역 fidelity(DB 이름 분리·트랜잭션 직렬화·비활성 요청 예외 또는 헤더 명시)
- [ ] 05-03 손상 governance에서도 LOGOUT/ACCOUNT_DELETION 삭제
- [ ] 05-04 OPFS purge 뒤 partition 파일 0개
- [ ] 05-05 sweep·prune이 손상 행 건너뜀
- [ ] 05-06 future schema → INCOMPATIBLE/ONLINE_ONLY
- [ ] 05-07 멈춘 put idle timeout으로 lock 해제
- [ ] 05-09 OPFS runbook 현행화, 죽은 `EFFECT_UNKNOWN` 분기 정리
- [ ] 05-10 objectId 문법 policy 연동, `stableJson` 한 벌
- [ ] 05-11 IndexedDB 예외 매핑 한 벌, OPFS→indexeddb import 0
- [ ] 05-12 binding 검증을 kernel 트랜잭션으로
- [ ] 05-13 admission 중 versionchange 처리
- [ ] 05-14 GC 유예 기준(또는 계약 주석)
### T10 — R-2.5 cache 정책의 Vary/content-type (6.2-5)
- 완료 조건: [x] 기본 정책으로 `Vary: Accept-Encoding` 응답을 stage하고 activate할 수 있다 [x] `content-type`이 없는 정책은 `assertPublicCachePolicy`가 거부한다
- 테스트: `tests/unit/public-response-cache.test.ts`
- 파일: `src/adapters/cache-storage/public-response-cache-adapter.ts`, `public-cache-policy.ts`
- 의존: T01 · 크기: S
## 레인 F — Service Worker / Web Push (`06-adapters-service-worker-push.md`)
## 레인 C — http / query-cache / auth
- [ ] 06-01 알림 클릭 `"data" in` — 완료: prototype accessor fake로 클릭 테스트 통과
- [ ] 06-02 두 탭 push 경쟁 (D-4)
- [ ] 06-04 kill switch 분기 테스트 — 완료: 변이 검출
- [ ] 06-03 SW 비상 경로·운영 문서 (D-5)
- [ ] 06-05 SW 관측 조립
- [ ] 06-06 계정 전환 시 push fence 넘기기
- [ ] 06-07 drain 시간 초과를 `CLIENT_DRAIN_TIMEOUT`으로
- [ ] 06-08 fallback을 빌드 자산 경로로 한정
- [ ] 06-09 거절 클릭 fallback이 base path 사용
- [ ] 06-10 SW 빌드가 프로필 설정 사용(또는 불일치 실패)
### T11 — R-3.1 경로 값 `.`/`..` 거부 (6.3-1)
- 완료 조건: [x] V3 bridge가 `PATH_VALUE_INVALID`, V2 request-builder가 `PATH_PARAMETER_INVALID`를 반환한다(`"."`, `".."` 각각)
- 테스트: `tests/unit/http-contract-bridge*.test.ts`(없으면 신규), V2 request-builder 테스트
- 파일: `src/adapters/http/http-contract-bridge.ts`, `src/adapters/http/request-builder.ts`
- 의존: T01 · 크기: S
## 레인 G — contracts (`07-contracts.md`)
### T12 — R-3.2a scope fence는 상태가 바뀔 때만 (6.3-2) [고위험]
- 완료 조건: [x] 같은 (상태, 주체) 알림은 fence·abort·cache clear를 일으키지 않는다 [x] 상태나 주체가 바뀌면 여전히 fence된다
- 테스트: server-state-scope 런타임 테스트(`tests/unit/…server-state-scope…`)
- 파일: `src/adapters/query-cache/server-state-scope-runtime.ts`
- 의존: T01 · 크기: S
- [ ] 07-02 · 13-10 호환성 규칙·분류기·FE-GATE-014 (D-6)
- [ ] 07-03 V2/V3 일치 테스트 (D-7)
- [ ] 07-04 읽지 않는 registry 필드 연결 또는 삭제 — 완료: 변이 M1 검출
- [ ] 07-05 diagnostics fixture를 `@ts-expect-error` 3개로
- [ ] 07-06 `invokeValidator` 입력 검사
- [ ] 07-07 `@deprecated`와 제거 조건
### T13 — R-3.2b 요청 전 미인증과 서버 401 구분, demo 동일 값 무알림 (6.3-2) [고위험]
- 완료 조건: [x] V3 요청 전 자격증명 없음은 `onUnauthenticated`를 호출하지 않는다 [x] 서버 401은 호출한다 [x] demo `setState`는 같은 값이면 listener를 부르지 않는다
- 테스트: `tests/unit/http-execution-v3*.test.ts`, `tests/unit/runtime-adapters.test.ts` 또는 auth 어댑터 테스트
- 파일: `src/adapters/http/http-execution-v3.ts`, `src/adapters/auth/external-session-adapter.ts`, `src/bootstrap/runtime-adapters.ts`
- 의존: T12 · 크기: M
## 레인 H — presentation (`08-presentation.md`)
### T14 — R-3.3 5xx 비정상 바디와 요청 쪽 위반 분류 (6.3-3)
- 완료 조건: [x] HTML/빈 바디 502/503/504가 status를 담은 서버 장애(재시도 가능)로 끝난다 [x] 바인딩 결과가 `contact-support`가 아니다 [x] `FINAL_REQUEST_INVARIANT_FAILED`/`MISSING_IDEMPOTENCY_KEY`가 `ENVELOPE_MISMATCH`로 매핑되지 않는다
- 테스트: `tests/unit/http-execution-v3.test.ts`, feature-http-binding 테스트
- 파일: `http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`
- 의존: T13 · 크기: M
- [ ] 07-01 · 08-02 오류 종류 38개 문구 + 누락 검출 테스트
- [ ] 08-04 샘플 문구 catalog화 + `check:i18n` 범위 확대
- [ ] 08-05 · 11-02 a11y·visual이 실제 화면을 검사(heading 대기, 보호 라우트는 로그인 후, 상태별)
- [ ] 08-07 실패 화면 지원 참조·다음 행동
- [ ] 08-08 스크롤 복원·해시 이동
- [ ] 08-09 실패 시 결과 수 status 숨김
- [ ] 08-10 언어 전환 시 폼 오류 재번역
- [ ] 08-11 상태 화면 한 벌로
- [ ] 08-12 Pagination 수정키 클릭 허용
- [ ] 08-13 상세 경로와 정적 경로 충돌 제거
### T15 — R-3.4 자격증명 헤더 ByteString 검증 (6.3-4) [고위험]
- 완료 조건: [x] NUL, 비 Latin-1, 제어문자가 든 값이 전송 전에 `CREDENTIAL_HEADER_VALUE_INVALID`가 된다(NETWORK_FAILURE 아님) [x] 대소문자만 다른 중복 헤더가 거부된다 [x] 정상 Bearer 토큰은 통과한다
- 테스트: bridge/V3 테스트, auth 어댑터 테스트
- 파일: `http-contract-bridge.ts`, `http-execution-v3.ts`, `external-session-adapter.ts`
- 의존: T14 · 크기: M
## 레인 I — 애플리케이션 코어·조립·빌드 입력 (`09-app-core.md`)
### T16 — R-3.5 매퍼 예외를 Result로 (6.3-5)
- 완료 조건: [x] `mapSuccess`/`mapProblem`이 throw하면 `MAPPING_CONTRACT_VIOLATION` Result가 반환되고 effect가 보존된다
- 테스트: feature-http-binding 테스트
- 파일: `feature-http-binding.ts`
- 의존: T14 · 크기: S
- [ ] 09-01 기능 2개 이상 설치 타입 — 완료: 모양이 다른 두 기능 설치 typecheck fixture가 게이트에서 통과
- [ ] 09-05 `needs` 검사 + IndexedDB capability 조립 예시
- [ ] 09-02 `VITE_PRODUCT_FEATURES`를 생성기에서 (D-9)
- [ ] 13-06 `VITE_*` 개별 참조 + 전체 객체 참조 lint 금지 + 허용 목록 밖 변수 build 실패
- [ ] 13-07 하위 경로 배포 URL
- [ ] 09-03 모듈 평가 실패도 부트 오류 화면
- [ ] 09-04 `BOOT_UNEXPECTED_FAILURE`, 원인 보존
- [ ] 09-06 local-draft 도메인 규칙 적용
- [ ] 09-07 · 14-03 기능 추가·제거 경로 (D-10), 문서 현행화
- [ ] 14-08 제거 스크립트 실패 보고·임시 폴더
- [ ] 09-08 local-draft ABA 방지
- [ ] 09-09 모르는 override 키 진단
- [ ] 09-10 부트 실패 다시 시도 버튼
- [ ] 09-12 local-draft fixture 복사본 제거
## 레인 D — realtime
## 레인 J — 테스트 체계 (`10-tests-fast-layers.md`, `11-tests-browser-release-scale.md`)
### T17 — R-4.2 hint 없는 retryable 실패도 재연결 (6.4-2)
- 완료 조건: [x] WS `NETWORK_LOST`/`RESTART`, SSE 502/504(hint 없음)가 재연결된다 [x] polling도 같다 [x] `retryable:false`는 여전히 종료된다
- 테스트: `tests/unit/realtime/realtime-reconnect-coordinator.test.ts` + WS↔reconnect 연결 테스트 신규
- 파일: `src/adapters/realtime/reconnect-coordinator.ts`, `polling/bounded-poll-coordinator.ts`
- 의존: T01 · 크기: S
- [ ] 10-02 reference-page 첫 대기 안정화 — 완료: 부하 조건 20회 실패 0
- [ ] 10-04 커버리지 정책·문서 일치, live 재시도 모듈 포함
- [ ] 10-05 파일 하나 실행 문서, vitest `include`
- [ ] 10-06 전역 `afterEach` 실제 타이머 복원
- [ ] 10-07 테스트 문서 현행화
- [ ] 11-04 실제 모양 기능 규모 측정 (D-18)
- [ ] 11-05 SW 없는 구 탭 청크 복구 e2e
- [ ] 11-06 reference E2E 데이터 단언 + 저장 성공·재시도
- [ ] 11-07 성능 측정 반복·중앙값·strictPort
- [ ] 11-08 모든 Playwright 설정 `forbidOnly`, quarantine 만료 검사
### T18 — R-4.1 DRAINING 중 recovery 차단 (6.4-1)
- 완료 조건: [x] quiescence를 기다리는 동안 effect가 DRAINING이 되면 recovery가 authority를 호출하지 않고 실패한다
- 테스트: `tests/unit/realtime/stream-coordinator.test.ts`
- 파일: `src/adapters/realtime/stream-coordinator.ts`
- 의존: T01 · 크기: S
## 레인 K — CI·가드레일·릴리스 (`12-guardrails-ci.md`, `13-build-release-supply-chain.md`)
### T19 — R-4.3 barrier NONE recovery는 계속 진행 (6.4-3)
- 완료 조건: [x] SNAPSHOT_ONLY + barrier NONE 스트림에서 gap → recovery 뒤 연결이 유지되고 PROTOCOL_MISMATCH가 나지 않는다
- 테스트: consumer + coordinator 실제 조합 테스트(mock 없이)
- 파일: `src/adapters/realtime/event-consumer.ts`, 필요 시 `stream-coordinator.ts`
- 의존: T18 · 크기: M
`config/ci/gates.json`과 생성 workflow는 이 레인과 Phase 0만 바꾼다.
### T20 — R-4.4 SSE 파서 성능 (6.4-4)
- 완료 조건: [x] 기존 파서 테스트가 모두 통과한다(CRLF, 분할 chunk, BOM 등) [x] 250KB chunk 벤치에서 10배 이상 빨라진다(수동 측정값을 커밋 메시지에 기록)
- 테스트: `tests/unit/realtime/sse-parser*.test.ts` + 대형 chunk 정확성 케이스
- 파일: `src/adapters/realtime/sse/sse-parser.ts`
- 의존: T01 · 크기: S
- [ ] 08-06 수동 a11y 게이트를 release 단계로 (D-8)
- [ ] 11-01 · 13-03 drill 판정 정직화 (D-14) — 완료: JS 자산 없는 dist에서 FE-RB-002·005 실패, provider 없으면 UNVERIFIED, 016/025 중복 정리
- [ ] 11-03 CPU 무관 scale tier를 PR 게이트에
- [ ] 12-03 재수출 경유 경계 우회 차단
- [ ] 12-10 · 12-08 정규식 import 규칙 → 그래프 규칙 (D-12)
- [ ] 12-05 dependency-cruiser 실행 제거·문서 정정 (D-11)
- [ ] 12-06 `import.meta.glob` 거부
- [ ] 12-07 예외 범위 축소·이유·담당
- [ ] 12-09 레이어 규칙 기준 파일 하나
- [ ] 12-11 위반 메시지에 이유·해결 방향
- [ ] 13-02 dist 공개 파일 권한
- [ ] 13-04 `verify:promotion` 보관 모드
- [ ] 13-05 hosting 헤더 fixture 모드는 UNVERIFIED, live는 배포 후 (D-14)
- [ ] 13-08 운영 CSP 아래 e2e smoke
- [ ] 13-09 `engineStrict`·`saveExact`를 `pnpm-workspace.yaml`로
- [ ] 13-12 SBOM·provenance 증명 범위 표, 배포물 패키지 목록
- [ ] 13-13 provider 없는 구성 문서화, 키 교체 절차
- [ ] 13-14 번들 예산 기준선·여유·조건 문서
- [ ] 13-15 README 설정 절, `public/config.json` 동기화
## 레인 E — storage
## 레인 M — 템플릿 제품성·문서 (`14-template-product-docs.md`)
### T21 — R-5.1 orphan 후보 커서 (6.5-1) [고위험]
- 완료 조건: [x] 참조 중 청크 150개 뒤에 있는 orphan이 reconcile로 지워진다 [x] 참조 중 청크는 지워지지 않는다
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/opfs-byte-store.test.ts`
- 파일: `src/adapters/storage/opfs/opfs-worker-runtime.ts`, `opfs-worker-protocol.ts`, `opfs-worker-client.ts`, `opfs-byte-store-adapter.ts`
- 의존: T01 · 크기: M
### T22 — R-5.2 dedup 재사용 청크의 grace 보호 (6.5-2) [고위험]
- 완료 조건: [x] 같은 digest를 다시 쓰면 청크의 mtime이 갱신되어 `listOrphanCandidates`에 나오지 않는다
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`
- 파일: `opfs-worker-runtime.ts`
- 의존: T21 · 크기: S
### T23 — R-5.3 lock 대기를 RPC 타임아웃에서 분리 (6.5-3, D-3)
- 완료 조건: [x] 긴 put이 lock을 잡고 있어도 뒤에 온 put/remove가 60초에 실패하지 않고 lock을 얻은 뒤 진행된다 [x] lock 대기는 정책값 상한으로 끝난다
- 테스트: 배타 lease를 쓰는 worker/client 테스트 신규
- 파일: `opfs-worker-client.ts`, `opfs-worker-runtime.ts`, `opfs-policy.ts`
- 의존: T22 · 크기: M
### T24 — R-5.4 파티션 purge가 손상 행을 넘어 끝까지 (6.5-4) [고위험]
- 완료 조건: [x] 손상 record/sidecar/budget이 섞인 파티션에서 LOGOUT/ACCOUNT_DELETION purge가 COMPLETE된다 [x] 다른 파티션의 행은 남는다 [x] 손상은 observe로 보고된다
- 테스트: `tests/unit/indexeddb-runtime.test.ts`
- 파일: `src/adapters/storage/indexeddb/indexeddb-runtime.ts`
- 의존: T01 · 크기: M
### T25 — R-5.5 prepared-object 검증 단일화 (6.5-5) [고위험]
- 완료 조건: [x] 4MiB 청크로 저장한 객체를 정책 `chunkSizeBytes=8MiB`인 런타임에서 open, reconcile할 수 있다 [x] 검증 함수 정의는 한 곳
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/indexeddb-opfs-journal.test.ts`
- 파일: 신규 공용 모듈(`src/adapters/storage/opfs/…`), `opfs-worker-runtime.ts`, `indexeddb-opfs-journal.ts`, `opfs-worker-client.ts`, INVENTORY
- 의존: T23 · 크기: M
## 레인 F — service-worker / web-push
### T26 — R-6.1 확정 이후 메시지 처리 (6.6-1)
- 완료 조건: [x] ACCEPTED 도착 시 `registration.waiting===null`, `active===worker`여도 활성화가 성공한다 [x] 관련 없는 메시지(SYNC_WAKE_OBSERVED 등)가 활성화를 실패시키지 않는다
- 테스트: page-controller 테스트
- 파일: `src/adapters/service-worker/service-worker-page-controller.ts`
- 의존: T01 · 크기: S
### T27 — R-6.2 drain 짝 맞추기 수정 (6.6-2)
- 완료 조건: [x] 빌드 N 탭과 N+1 탭이 함께 있어도 활성화가 drain을 끝내고 완료된다
- 테스트: lifecycle 테스트 + page-controller 테스트
- 파일: `service-worker-lifecycle.ts`, `service-worker-page-controller.ts`
- 의존: T26 · 크기: S
### T28 — R-6.3a reloadRequired/updateWaiting 구독 (6.6-3)
- 완료 조건: [x] host 계약에 구독 API가 추가되고, 다른 탭의 `ACTIVATED_RELOAD_REQUIRED`와 주기 update의 waiting이 구독자에게 전달된다
- 테스트: page-controller 테스트
- 파일: `service-worker-page-controller.ts`, `src/contracts/service-worker.ts`, 관련 host 타입
- 의존: T27 · 크기: M
### T29 — R-6.3b previous 캐시 fallback (6.6-3, D-7)
- 완료 조건: [x] current 캐시에 없는 hashed asset을 previous 캐시에서 제공한다 [x] hashed가 아닌 URL에는 적용되지 않는다
- 테스트: lifecycle/runtime 테스트
- 파일: `service-worker-lifecycle.ts`, 필요 시 `service-worker-static-assets.ts`
- 의존: T28 · 크기: S
### T30 — R-6.4 설치 중 워커를 ACTIVE로 보고하지 않음 (6.6-4)
- 완료 조건: [x] `installing`만 있는 등록에서 `start()`가 ACTIVE가 아닌 상태를 반환한다 [x] 설치가 끝나면 올바른 상태로 수렴한다
- 테스트: page-controller 테스트(`installing` fixture 추가)
- 파일: `service-worker-page-controller.ts`
- 의존: T27 · 크기: S
### T31 — R-6.5 MIME 동의어와 content-encoding (6.6-5)
- 완료 조건: [x] `application/javascript` 응답과 `content-encoding: gzip` + 압축 크기 Content-Length 응답이 설치된다 [x] 바이트와 sha256 검증은 유지된다
- 테스트: static-assets 테스트
- 파일: `service-worker-static-assets.ts`
- 의존: T01 · 크기: S
### T32 — R-6.6 fetch 가로채기 범위 (6.6-6)
- 완료 조건: [x] navigate, 비 GET, manifest 밖 URL에서는 `respondWith`가 호출되지 않는다 [x] manifest asset은 캐시에서 제공된다
- 테스트: service-worker entry/runtime 테스트
- 파일: `service-worker-entry.ts`, 필요 시 runtime의 `manifestUrls` 노출
- 의존: T29 · 크기: S
### T33 — R-6.7 ABSENT 재등록 조건 (6.6-7) [고위험]
- 완료 조건: [x] fence REVOKED/UNASSOCIATED + native 구독 잔존 + 서버 ABSENT → 재등록하지 않고 native를 해제한다 [x] local ACTIVE(크래시 복구)면 재등록한다
- 테스트: `tests/unit/web-push-subscription-adapter.test.ts`
- 파일: `src/adapters/web-push/push-subscription-adapter.ts`
- 의존: T01 · 크기: S
## 레인 G — contracts
### T34 — R-7.1 멱등 키 문법 (6.7-1)
- 완료 조건: [x] 앞뒤 공백, 비 ASCII, 257자 키가 거부된다 [x] UUID 등 정상 키는 통과한다 [x] 기존 고정 테스트(`legacy-and-optional-network-remediation.test.ts:136`)를 고친다
- 테스트: 위 테스트 + mutation-intent 테스트
- 파일: `src/contracts/mutation-intent.ts`
- 의존: T01 · 크기: S
### T35 — R-7.2 FEATURE_OVERRIDES 키는 금지어 검사 제외 (6.7-2)
- 완료 조건: [x] `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`로 부팅 설정 로드가 성공한다 [x] 최상위나 다른 중첩의 금지 이름은 여전히 거부된다
- 테스트: runtime-config 테스트
- 파일: `src/contracts/env.ts`
- 의존: T01 · 크기: S
### T36 — R-7.3 매니페스트 URL 검증 (6.7-3)
- 완료 조건: [x] `"/\t/evil.example/m.json"`, 개행 포함, `/a/%2e%2e/b`가 거부된다 [x] 정상 경로는 통과한다
- 테스트: `tests/runtime-schema/runtime-config.test.ts`
- 파일: `src/contracts/release-artifacts.ts`
- 의존: T01 · 크기: S
### T37 — R-7.4 REST V2 COMMAND 메서드 규칙 (6.7-4) [고위험]
- 완료 조건: [x] `{semantics:"COMMAND", method:"GET"}`와 모르는 `semantics`/`replayPolicy` 값이 거부된다 [x] 설치된 기존 operation은 모두 통과한다
- 테스트: api-operations 테스트
- 파일: `src/contracts/api-operations.ts`
- 의존: T01 · 크기: S
### T38 — R-7.5 operationId 문법 단일화 (6.7-5)
- 완료 조건: [x] `getUser` 같은 V3 operationId의 `api.request.failed` 이벤트가 검증을 통과해 드롭되지 않는다 [x] 정의는 contracts 한 곳 [x] diagnostics도 같은 규칙
- 테스트: telemetry/diagnostics 계약 테스트
- 파일: `src/contracts/telemetry.ts`, `diagnostics.ts`, `external-contract-runtime.ts`, 공용 정의 위치
- 의존: T01 · 크기: M
## 레인 H — presentation
### T39 — R-8.1 청크 복구 상태 라우트별 초기화 (6.8-1)
- 완료 조건: [x] 라우트 A에서 청크 실패 → 라우트 B로 이동하면 B가 정상 렌더된다 [x] 실패 화면에 한 번 새로고침 버튼이 있다
- 테스트: `tests/component/chunk-recovery-boundary.test.tsx` 또는 라우터 컴포넌트 테스트
- 파일: `src/presentation/routes/app-router.tsx`, `src/presentation/boundaries/chunk-recovery-boundary.tsx`
- 의존: T01 · 크기: S
### T40 — R-8.2 WebKit/Vite 청크 실패 인식 (6.8-2)
- 완료 조건: [x] 두 메시지가 `isChunkLoadFailure`에서 true다 [x] `vite:preloadError`가 복구 경로로 이어진다
- 테스트: chunk-recovery 테스트
- 파일: `chunk-recovery-boundary.tsx`, 필요 시 `src/bootstrap/main.tsx`
- 의존: T39 · 크기: S
### T41 — R-8.8 enabled:false는 로딩 아님 (6.8-8)
- 완료 조건: [x] disabled 쿼리의 `isInitialLoading`이 false다 [x] 실제 첫 로딩은 여전히 true다
- 테스트: `tests/component/application-query*.test.tsx`
- 파일: `src/presentation/adapters/query/application-query.ts`
- 의존: T01 · 크기: XS
### T42 — R-8.4 로케일 변경 시 포커스·스크롤·재보고 없음 (6.8-4)
- 완료 조건: [x] 언어를 바꾸면 제목만 갱신되고 focus, scrollTo, reportRouteChanged가 호출되지 않는다
- 테스트: 라우터 컴포넌트 테스트
- 파일: `app-router.tsx`
- 의존: T39 · 크기: S
### T43 — R-8.5 모든 분기에서 RouteLifecycle (6.8-5)
- 완료 조건: [x] 인증필요, 잘못된 주소, 비활성 기능 화면에서 title, main focus, route 텔레메트리가 동작한다
- 테스트: 라우터 컴포넌트 테스트
- 파일: `app-router.tsx`
- 의존: T42 · 크기: S
### T44 — R-8.6 드로어 이동 시 포커스 (6.8-6)
- 완료 조건: [x] 드로어 링크로 이동하면 activeElement가 새 페이지 h1 또는 main이다 [x] Escape로 닫으면 여전히 메뉴 버튼으로 돌아간다
- 테스트: app-shell 컴포넌트 테스트
- 파일: `src/presentation/layouts/app-shell.tsx`, 필요 시 `design-system/primitives/core.tsx`
- 의존: T43 · 크기: S
### T45 — R-8.3a 로케일 저장 (6.8-3, D-5)
- 완료 조건: [x] 로케일 선택이 preferences에 저장되고 새 mount 때 저장값으로 시작한다
- 테스트: `tests/component/locale-platform.test.tsx`
- 파일: `src/presentation/i18n/locale-provider.tsx`, `src/application/ports/in/application-api.ts`, `src/application/create-application.ts`, preferences 저장 경로
- 의존: T42 · 크기: M
### T46 — R-8.3b provider를 scope fence 밖으로, router dispose (6.8-3)
- 완료 조건: [x] scope가 FENCED → READY가 되어도 LocaleProvider/ThemeProvider 상태가 유지된다 [x] AppRouter unmount 시 `router.dispose()`가 호출된다
- 테스트: 컴포넌트 테스트(세션 전환)
- 파일: `app-router.tsx`, `src/presentation/adapters/query/server-state-scope-provider.tsx`, provider 조립 위치(bootstrap/runtime-application 등)
- 의존: T45 · 크기: M
### T47 — R-8.7 context 게이트웨이 key와 청크 복구 (6.8-7)
- 완료 조건: [x] context가 바뀌면 이전 routes로 매칭하지 않는다(NOT_FOUND 텔레메트리 없음) [x] routes 모듈 로드의 청크 실패가 `recoverChunk`를 거친다
- 테스트: 라우터 컴포넌트 테스트(가짜 context 2개)
- 파일: `app-router.tsx`
- 의존: T46 · 크기: S
## 레인 I — bootstrap / platform
### T48 — R-9.1 부트 reload 세션당 1회 (6.9-1)
- 완료 조건: [x] 키가 A→B→A로 바뀌어도 TTL 안에서는 두 번째부터 `show-failure`다 [x] 기존 연속 reload 기대 테스트를 고친다
- 테스트: `tests/unit/release-mismatch-recovery.test.ts`, `tests/release/mixed-replica.test.ts`
- 파일: `src/platform/release/release-mismatch-recovery.ts`
- 의존: T01 · 크기: S
### T49 — R-9.2 중복 발생 횟수 전달 (6.9-2, D-6)
- 완료 조건: [x] 기본 스케줄(queueMicrotask)에서 같은 이벤트 1000회 → 수집기가 받는 occurrences 합계가 1000이다
- 테스트: `tests/platform/telemetry/telemetry-pipeline.test.ts`(자동 flush 켠 케이스 추가, 기존 기대값 정리)
- 파일: `src/platform/telemetry/telemetry-pipeline.ts`
- 의존: T01 · 크기: M
### T50 — R-9.3 리댁션 보강 (6.9-3) [고위험]
- 완료 조건: [x] 중간의 `Authorization: Bearer …`, URL `?access_token=…`, 이메일, `pwd`/`pass`/`auth`/`otp`/`pin` 키가 가려진다 [x] 정상 enum/id 값은 가려지지 않는다
- 테스트: redact-telemetry 테스트
- 파일: `src/platform/telemetry/redact-telemetry.ts`
- 의존: T01 · 크기: S
- [ ] 14-04 CHANGELOG, README 업데이트 절, 로컬 태그 (D-15)
- [ ] 14-05 `docs/README.md` 색인 (D-16)
- [ ] 14-06 README 지원 범위 표·상태 어휘 대응표
---
# 2차 라운드 (권장·사소 + 1차 후속)
## 통합 후 (순차, 레인 Z)
요구사항은 `SPEC.md` "2차 라운드" 절에 있다(Q-ID = 리뷰 섹션). 공통 검증은 위와 같다. 동작을 바꾸지 않는 정리 작업은 기존 테스트가 안전망이고, 테스트가 없으면 characterization 테스트를 먼저 추가한다.
- [ ] 12-12 `noUnusedLocals` (D-19)
- [ ] 14-07 문서 수치·목록 현행화(게이트 수는 레인 K 결과 기준)
- [ ] 리뷰 README 발견 색인의 상태를 "해결 · <커밋>"으로 갱신
## 레인 A — browser-transfer
- [x] T51 Q-6.1-5 worker 실패 시 나머지 worker 즉시 abort — `resumable-upload-runtime.ts`, test: `resumable-upload-runtime.test.ts`
- [x] T52 Q-6.1-6 해석 불가 checkpoint를 abort로 정리 — `indexeddb-checkpoint-store.ts`, runtime
- [x] T53 Q-6.1-7 PRIMARY_REQUIRED + fit 정책 검증 (D-12) — `image-cdn/image-cdn-policy.ts`
- [x] T54 Q-6.1-8 probe decode `imageOrientation: "none"` — `image-cdn/browser-image-probe.ts`
- [x] T55 Q-6.1-9 presigned helper 통합, statusFailure 통일, 죽은 함수 삭제, Content-Length 엄격 파싱, runtime attempt kernel화 — `presigned/*`, runtime
- [x] T56 Q-6.1-3b part 방어적 복사 중복 제거 — `presigned/presigned-upload-part-executor.ts`, executor
- [x] T57 Q-6.1-10 runtime 파일 분리(검증·snapshot 래퍼), 동작 불변 — `resumable-upload/*`, INVENTORY
- [x] T58 Q-6.1-11 vault register는 snapshot만 읽음 — `presigned/presigned-capability-vault.ts`
### Checkpoint 최종
- [ ] 공통 게이트 + `check:ci` + `check:adapter-inventory` + `verify:documentation` + `test:sample-removal` + `build`
- [ ] 새 worktree(깨끗한 체크아웃)에서 공통 게이트 통과
- [ ] 발견 138건 모두 체크
## 레인 B — browser-files / cache-storage / cross-context
- [x] T59 Q-6.2-6 cache 조회 비용 절감 — `cache-storage/public-response-cache-adapter.ts`
- [x] T60 Q-6.2-7 abort race를 kernel로 — `browser-files/download-delivery-adapter.ts`, `browser-file-vault.ts`
- [x] T61 Q-6.2-8 native cancel 관찰 시 focus fallback 끔 — `browser-files/browser-file-picker.ts`
- [x] T62 Q-6.2-9 host factory 실패 보고와 epoch 인코딩 — `cross-context-invalidation/browser-cross-context-host.ts`
- [x] T63 Q-6.2-10 파일명 자르기 O(n), 중복 호출 제거 — `browser-files/file-policy.ts`, download adapter
- [x] T64 Q-6.2-11 큰 파일 두 개에서 코덱·검증 모듈 분리, 동작 불변 — cache adapter, download adapter, INVENTORY
- [x] T65 Q-6.2-12 정규식·정수 검사 중복 통합, 죽은 분기 삭제 — `object-url-lease.ts` 등
## 사용자 몫 (SPEC "범위 밖")
## 레인 C — http / browser-rpc / query-cache / auth
- [x] T66 Q-6.3-6 `terminalOutcomeFor` 통합, 백오프 중 scope fence 분류 — `http/http-execution-v3.ts`
- [x] T67 Q-6.3-7 명령 effect 누적 합치기, MAYBE_APPLIED 재시도 금지 — `http-execution-v3.ts`
- [x] T68 Q-6.3-8 namespace 무효화 병렬화 — `query-cache/tanstack-cache-coordinator.ts`
- [x] T69 Q-6.3-9 RPC 명령 effect, 재시도 전 scope 확인, stream 정리 — `browser-rpc/browser-rpc-runtime.ts`
- [x] T70 Q-6.3-11 V2 401 복구를 재시도 예산에서 분리, 롤백 seam 문서 정정 — `http/client.ts`, 관련 docs
- [x] T71 Q-6.3-12 cursor pagination 직렬화·push, `validTransportFailure` 삭제, `W/"` ETag 거부 — query-cache, browser-rpc
- [x] T72 Q-6.3-3b V2 5xx 비정상 바디 분류·재시도 — `http/client.ts`, `http/retry-policy.ts`(retryKinds만)
## 레인 D — realtime (+ kernel 헬퍼)
- [x] T73 Q-6.4-5 chunk item 상한 초과 시 이어서 처리 — `sse/sse-parser.ts`
- [x] T74 Q-6.4-6 dedupe FIFO, 해시 fingerprint, prune break — `stream-coordinator.ts`, `event-codec.ts`
- [x] T75 Q-6.4-7 재시도 예산 초기화 조건 — `reconnect-coordinator.ts`, `reconnect-policy.ts`
- [x] T76 Q-6.4-8 헬퍼 통합, Retry-After 파서·JSON 중복 키 스캐너를 kernel로(http `retry-policy.ts` 파싱부와 web-push `push-codec.ts` 중복 키 검사도 전환) — INVENTORY
- [x] T77 Q-6.4-9 `endAttempt()` 추출, `_recovery` 파라미터 제거 — reconnect, websocket-connection
- [x] T78 Q-6.4-10 probe 버퍼 상한을 현재 버퍼 기준으로 — `live-poll-handoff-coordinator.ts`
- [x] T79 Q-6.4-11 사소 5건 — poll, sse-parser, event-codec, fetch-sse-connection, websocket-protocol
## 레인 E — storage
- [x] T80 Q-6.5-6 openObject 사전 검증 축소, root digest는 스트림 끝에서 — `opfs/opfs-worker-client.ts`, worker runtime
- [x] T81 Q-6.5-7 `indexeddb-records.ts`로 행 타입·검증·측정 통합, 동작 불변 — indexeddb runtime/maintenance/governance, INVENTORY
- [x] T82 Q-6.5-8 삭제 후 revision 재시작을 port 주석과 문서로 명시 (D-13)
- [x] T83 Q-6.5-9 보상 실패 시 원래 실패 코드 유지 — `opfs/opfs-byte-store-adapter.ts`
- [x] T84 Q-6.5-10 kernel transaction/connection 구멍 2개 — `platform/indexeddb-transaction.ts`, `platform/indexeddb-connection.ts`
## 레인 F — service-worker / web-push
- [x] T85 Q-6.6-6b fetch 가로채기를 same-origin GET + 해시 파일명까지 넓힘, 옛 chunk fallback 동작 — `service-worker-entry.ts`, lifecycle
- [x] T86 Q-6.6-8 active와 같은 캐시 이름이면 실패해도 지우지 않음 — `service-worker-static-assets.ts`
- [x] T87 Q-6.6-9 activate: 삭제 먼저, marker 실패 격리 — `service-worker-lifecycle.ts`
- [x] T88 Q-6.6-10b 페이지 활성화 deadline 여유분 — `service-worker-page-controller.ts`
- [x] T89 Q-6.6-11 클릭 실패 시 앱 루트, push drop 문서화 (D-14) — `web-push/inbound/*`, docs
- [x] T90 Q-6.6-12 web-push codec primitive 통합(중복 키 스캔은 T76 담당), page controller의 document 주입 — `web-push/*`, `register-service-worker.ts`, INVENTORY
## 레인 G — contracts
- [x] T91 Q-6.7-6 exact-key/스냅샷 단일화 + 배열 스냅샷, 우회 차단 — `exact-snapshot.ts` 외 5곳
- [x] T92 Q-6.7-7 인덱스·레지스트리 불변화 — query-invalidation, web-worker, offline-command, runtime-capabilities
- [x] T93 Q-6.7-8 검증기 프로토콜과 MappingResult 기준 통일 (D-15)
- [x] T94 Q-6.7-9 REST 인증 프로필 기준 원본 단일화(V2 resolve 포함) — rest-profiles, external-contract-runtime, `http/client.ts` 호출부 한 줄
- [x] T95 Q-6.7-10 배포 승인 사설 주소 판정 보강, 로컬 호스트 목록 단일화 — deployment-admission, browser-rpc, rest-profiles
- [x] T96 Q-6.7-11 레지스트리 조회 `Object.hasOwn`, offline 전이 false — api-operations, storage-keys, offline-command
- [x] T97 Q-6.7-12 release-tokens, contract-set, query-keys, dependency-cruiser 규칙
## 레인 H — presentation
- [x] T98 Q-6.8-9 디자인시스템 링크를 router Link로, Pagination 파라미터 보존
- [x] T99 Q-6.8-10 상태 화면 통합, 세션 액션 hook, 임시 로딩 reject 처리
- [x] T100 Q-6.8-11 Tooltip 접근성
- [x] T101 Q-6.8-12 Pagination windowing, landmark 중첩 제거
- [x] T102 Q-6.8-13a `none` 코덱이 모르는 쿼리 무시 (D-16)
- [x] T103 Q-6.8-13b 폼 이중 제출 방지, 저장 직후 dirty guard 오탐 제거
- [x] T104 Q-6.8-13c fallback 문구 로케일, SearchField 포커스
- [x] T105 Q-6.8-13d theme.css 분리(빌드 CSS 바이트 동일)
## 레인 I — application / features / bootstrap / platform / telemetry adapter
- [x] T106 Q-6.9-4 텔레메트리 전송 단일화 + fetch 타임아웃(6.3-10 포함) — `src/adapters/telemetry/*`, `platform/telemetry/*`, `bootstrap/runtime-adapters.ts`
- [x] T107 Q-6.9-5 킬스위치를 feature input에 적용 — `features/installed-feature-adapters.ts`, runtime-adapters
- [x] T108 Q-6.9-6 featureId 중복·불일치 throw — `features/feature-adapter-contribution.ts`
- [x] T109 Q-6.9-7 execution context 정리 API — `platform/execution/execution-context.ts`
- [x] T110 Q-6.9-8 정적 boot shell — `index.html`, `bootstrap/main.tsx`
- [x] T111 Q-6.9-9 reload guard 통합 — `application/use-cases/decide-chunk-recovery.ts`, `platform/release/*`
- [x] T112 Q-6.9-10 검증 통과 값만 safe 에러에 — `bootstrap/load-runtime-config.ts`
- [x] T113 Q-6.9-11 텔레메트리 버퍼 eviction 정정 — `platform/telemetry/telemetry-buffer.ts`
- [x] T114 Q-6.9-12 re-export 파일 삭제, CI 정책 scripts로 이동, 메시지 로케일 도출
## 통합
- [x] T115 Q-B 번들 예산 통과(코드 축소, D-11)
---
# 3차 라운드 (남은 문제 8건)
- [x] T116 R3-1 V2 408/425 재시도 + client Retry-After를 kernel로 — `http/client.ts`, `http/retry-policy.ts`
- [x] T117 R3-2 fetch transport Retry-After를 kernel로 + file-transfer 번들 여유 546B 이상 — browser-transfer
- [x] T118 R3-3 demo subject 제공, 외부 owner 문서 — `auth/external-session-adapter.ts`, docs
- [x] T119 R3-4 `idle` 비동기 상태 — `application/view-models/async-state.ts`, presentation
- [x] T120 R3-5 SSE 바이트 단위 파싱 — `realtime/sse/*`
- [x] T121 R3-6 실제 브라우저 Playwright 스펙 — `tests/e2e`, `tests/browser-capabilities`
- [x] T122 R3-7 WebKit 전체 실행
- [x] T123 R3-8 push + Gitea PR
- [ ] U-1 Gitea Actions 활성화·runner·required check
- [ ] U-2 수동 접근성 검토 10건
- [ ] U-3 태그 push
- [ ] U-4 작성자 외 기능 추가 기록, staging 공급망 smoke
- [ ] U-5 백엔드 멱등 키 계약 확인