# 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 | 훅에 의존하지 않고 진입점에서 명시적으로 생성 | ## Open Questions - 없음. 방향이 여러 개인 항목은 SPEC.md의 D-1 ~ D-7로 정했다. 승인하면 그대로 진행한다.