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