From c5f379b82c34b1ecf7ee38f85da4e6d71fa4b642 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 21:05:08 +0900 Subject: [PATCH] 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 --- SPEC.md | 265 +++++------------------ tasks/plan.md | 187 ++++++----------- tasks/todo.md | 568 +++++++++++++++----------------------------------- 3 files changed, 286 insertions(+), 734 deletions(-) diff --git a/SPEC.md b/SPEC.md index ad261b3a..1ad37aaf 100644 --- a/SPEC.md +++ b/SPEC.md @@ -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//`에 `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)는 한 작업에서 함께 닫는다. diff --git a/tasks/plan.md b/tasks/plan.md index 90a8dc9d..ac9fe234 100644 --- a/tasks/plan.md +++ b/tasks/plan.md @@ -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