Mark T51-T115 done and record the fresh-checkout gate, bundle budget and Playwright results plus the behaviour changes to know about. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Implementation Plan: src 리뷰 긴급·필수 항목 수정
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에 있다.
- 브랜치:
fix/src-review-2026-09-24 - 기준 커밋:
b04d570
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.
실행 방식
- Phase 0 (순차): T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다.
- Phase 1 (병렬 레인 9개): 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은
fix/src-review-2026-09-24HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다. - 통합 (순차): 레인 브랜치를 하나씩
fix/src-review-2026-09-24에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트). - 최종 체크포인트: 전체 게이트,
build, 깨끗한 체크아웃 재현(src/.generated삭제 후 게이트)을 확인한다.
| 레인 | 영역 | 작업 |
|---|---|---|
| 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 |
레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 docs/reviews/adapters/INVENTORY.md(adapter 파일 추가 시)와 src/bootstrap/(H의 T45와 I)이다. 통합 단계에서 해결한다.
Task List (요약 — 상세는 tasks/todo.md)
Phase 0: 기반
- T01 R-0 깨끗한 체크아웃에서 게이트 동작
Checkpoint 0
src/.generated삭제 후 arch/types/lint/unit/component/verify:documentation 통과
Phase 1: 레인 A–I (병렬)
- 레인 A: T02–T05
- 레인 B: T06–T10
- 레인 C: T11–T16 (고위험 T12, T13, T15 포함)
- 레인 D: T17–T20
- 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함)
- 레인 F: T26–T33 (고위험 T33 포함)
- 레인 G: T34–T38 (고위험 T37 포함)
- 레인 H: T39–T47
- 레인 I: T48–T50 (고위험 T50 포함)
Checkpoint 레인별 (통합할 때마다)
- check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과
- adapter 파일을 바꿨으면 check:adapter-inventory 통과
Checkpoint 최종
- 위 게이트 +
corepack pnpm build통과 - 깨끗한 체크아웃 재현 통과
- 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크)
고위험 작업 (계획 승인 = 이 작업들의 사전 승인)
| 작업 | 이유 | 안전장치 |
|---|---|---|
| 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)이 가려지지 않음을 테스트로 고정 |
모두 코드 변경이라 git revert로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다.
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 | 훅에 의존하지 않고 진입점에서 명시적으로 생성 |
결과 (2026-09-24)
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 (사용자 결정 필요)
- 번들 예산:
check:optional-recipes가 기준 커밋부터 실패하고 있었다. 기준 커밋 대비 file-transfer는 99바이트 줄었고, realtime은 초과폭이 9바이트에서 139바이트로 늘었다. offline-indexeddb는 이번 수정으로 예산을 56바이트 새로 넘었다. 예산을 올릴지, 코드를 줄일지 결정이 필요하다. - T29(R-6.3b) vs T32(R-6.6): fetch를 manifest URL로만 가로채도록 좁혔기 때문에, 이전 캐시 fallback은 현재 manifest에 있는 URL에만 적용된다. 리뷰의 원래 시나리오(옛 빌드 lazy chunk)는 여전히 네트워크로만 간다. 가로채는 범위를 "same-origin GET + 해시 파일명"으로 넓힐지 결정이 필요하다.
- T12(R-3.2a): 기존 owner는 subject를 제공하지 않는다. 그래서 인증 상태에서 인증 상태로 오는 알림(토큰 갱신 등)은 owner가
readSubject를 구현하기 전까지 여전히 캐시를 비운다. fail-closed 기본값이다. - T41(R-8.8): disabled 쿼리는 이제
empty("데이터가 없습니다")로 보인다. 의존 쿼리에 이 화면이 맞지 않다면idle상태를 따로 만들어야 한다. - T20(R-4.4): 250KB 벤치에서 ASCII는 36~80배 빨라졌지만 멀티바이트 위주 입력은 약 5배에 그쳤다. 10배 목표는 ASCII만 달성했다.
- 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(main9bef702에서 분기) - 범위:
SPEC.md2차 라운드 절, 작업 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)은 커널로 옮기지 않았다