Files
clean-architecture-frontend…/tasks/plan.md
T
DongHyeonkaandClaude Opus 5.5 ea0f01ff05 docs: plan fixes for src review critical and required findings
SPEC.md lists the 47 requirements (R-0, R-1.1..R-9.3) and decisions D-1..D-7.
tasks/plan.md and tasks/todo.md break them into 50 tasks across 9 lanes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 11:48:19 +09:00

94 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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로 정했다. 승인하면 그대로 진행한다.