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>
94 lines
5.6 KiB
Markdown
94 lines
5.6 KiB
Markdown
# 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로 정했다. 승인하면 그대로 진행한다.
|