Files
clean-architecture-frontend…/tasks/plan.md
T
DongHyeonkaandClaude Opus 5.5 60900fe232 docs: record round 2 results
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>
2026-09-24 14:53:23 +09:00

11 KiB
Raw Blame History

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.

실행 방식

  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 삭제 후 게이트)을 확인한다.
레인 영역 작업
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 (사용자 결정 필요)

  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)은 커널로 옮기지 않았다