SPEC maps all 138 findings to requirements and fixes the defaults for the review's open choices (D-1..D-19). The plan runs gate/CI groundwork first, then parallel area lanes, then integration. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
100 lines
6.5 KiB
Markdown
100 lines
6.5 KiB
Markdown
# Implementation Plan: 성숙도 리뷰(2026-09-25) 전 항목 반영
|
||
|
||
## Overview
|
||
|
||
`SPEC.md`의 요구사항(리뷰 발견 138건, ID 기준 143개)을 작업 단위로 나눠 고친다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록은 `tasks/todo.md`에 있다.
|
||
|
||
- 브랜치: `fix/maturity-review-2026-09-25`
|
||
- 기준 커밋: `4626b73`
|
||
|
||
## Architecture Decisions
|
||
|
||
- 결정 D-1 ~ D-19는 `SPEC.md` "결정" 표를 따른다.
|
||
- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다.
|
||
- 공개 포트는 추가만 한다.
|
||
- 버그를 정상 동작으로 고정한 기존 테스트(예: 12-02의 workflow 스냅샷 테스트)는 같은 커밋에서 고친다.
|
||
- `config/ci/gates.json`과 `.gitea/workflows/quality-gates.yml`은 Phase 0과 레인 K만 바꾼다. 다른 레인이 게이트 변경이 필요하면 레인 보고에 적고, 통합 때 반영한다.
|
||
|
||
## 실행 방식
|
||
|
||
직전 라운드(`fix/src-review-2026-09-24`)와 같은 구조다.
|
||
|
||
1. **Phase 0 (순차):** 게이트·CI 기반 7개 작업. 이게 끝나야 새 clone, 샘플 제거, CI 계약이 이후 작업의 검증 수단으로 동작한다. Phase 0 뒤 Checkpoint 0.
|
||
2. **Phase 1 (병렬 레인):** 레인마다 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 Phase 0이 반영된 브랜치 HEAD에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 진행한다(RED → GREEN → 게이트 → 커밋). 호스트 부하를 줄이려고 두 묶음으로 나눈다.
|
||
- 1차: A, C, E, I, K (작업이 많거나 위험이 큰 레인)
|
||
- 2차: B, D, F, G, H, J, M
|
||
3. **통합 (순차):** 레인 브랜치를 하나씩 rebase해 병합하고, 병합할 때마다 공통 게이트를 돌린다.
|
||
4. **통합 후 작업:** 12-12, 14-07, 리뷰 색인 상태 갱신.
|
||
5. **최종 체크포인트:** 전체 게이트, `build`, `test:sample-removal`, 깨끗한 worktree 재현.
|
||
|
||
worktree 준비 규칙: `node_modules`는 최상위 항목마다 심볼릭 링크를 건다. pnpm 상태 파일(`.pnpm-workspace-state-v1.json`, `.modules.yaml`, `.package-map.json`)은 복사하고, 상태 파일의 프로젝트 경로를 worktree로 바꾼다. 이 방식이면 worktree에서 `corepack pnpm <script>`를 돌려도 설치 단계가 돌지 않는다. 공유 `node_modules`도 바뀌지 않는다(2026-09-25 시험 확인).
|
||
|
||
| 레인 | 영역 | 작업 수 | 겹칠 수 있는 파일 |
|
||
|---|---|---|---|
|
||
| Z | Phase 0 · 통합 후 | 7 + 2 | — |
|
||
| A | browser-transfer | 11 | INVENTORY |
|
||
| B | browser-files / cache | 9 | INVENTORY |
|
||
| C | HTTP·서버 상태·인증·텔레메트리 | 11 | `application-query.ts`, `async-surface.tsx`, `use-app-form.ts`(C가 소유) |
|
||
| D | realtime | 8 | INVENTORY |
|
||
| E | 저장소·kernel | 14 | `tests/helpers/memory-indexeddb.ts`, INVENTORY |
|
||
| F | Service Worker / Web Push | 10 | `create-runtime-composition.ts`(I와) |
|
||
| G | contracts | 6 | `src/contracts/compatibility.ts` |
|
||
| H | presentation | 10 | `catalog.ts`, e2e spec |
|
||
| I | 앱 코어·조립·빌드 입력 | 14 | `src/contracts/env.ts`, 제거 스크립트, 생성기 |
|
||
| J | 테스트 체계 | 10 | `tests/setup.ts`, `vitest.config.ts`, Playwright 설정 |
|
||
| K | CI·가드레일·릴리스 | 19 | `gates.json`, workflow, `check-architecture.ts`, `eslint.config.ts` |
|
||
| M | 템플릿 제품성·문서 | 3 | README |
|
||
|
||
겹치는 파일은 소유 레인을 위 표로 정했다. 소유하지 않은 레인이 그 파일을 바꿔야 하면 레인 보고에 적고, 통합 때 반영한다.
|
||
|
||
## Task List (요약 — 상세는 tasks/todo.md)
|
||
|
||
### Phase 0: 기반
|
||
- [ ] 10-01, 00-01, 14-01, 14-02, 12-02·13-01, 12-01, 12-04·09-11
|
||
|
||
### Checkpoint 0
|
||
- [ ] 공통 게이트 + `check:ci` + `test:sample-removal` + `build`
|
||
|
||
### Phase 1: 레인 A–M
|
||
- [ ] 1차: A, C, E, I, K
|
||
- [ ] 2차: B, D, F, G, H, J, M
|
||
|
||
### Checkpoint 레인별 (통합할 때마다)
|
||
- [ ] 공통 게이트 + `check:ci` + `check:adapter-inventory`
|
||
|
||
### 통합 후
|
||
- [ ] 12-12, 14-07, 리뷰 색인 갱신
|
||
|
||
### Checkpoint 최종
|
||
- [ ] 공통 게이트 + `check:ci` + `check:adapter-inventory` + `verify:documentation` + `test:sample-removal` + `build`
|
||
- [ ] 깨끗한 worktree 재현
|
||
- [ ] 발견 143개 ID 모두 체크
|
||
|
||
## 고위험 작업 (계획 승인 = 이 작업들의 사전 승인)
|
||
|
||
| 작업 | 이유 | 안전장치 |
|
||
|---|---|---|
|
||
| 03-01, 03-02, 08-01 | 결과 불명 쓰기·인증 실패 처리가 바뀜 | 입력이 바뀌면 새 키. 결과 불명 뒤 자동 재전송은 여전히 없음(사용자 행동으로만). 기존 fence 테스트 유지 |
|
||
| 05-03, 05-04, 05-05 | 삭제 경로 | LOGOUT/ACCOUNT_DELETION과 authority 승인 proof가 있을 때만 DB 삭제. 다른 partition·정상 행은 지우지 않음을 테스트로 고정 |
|
||
| 05-01, 05-02 | 저장 데이터 판독·정리 | 기존 journal·receipt가 읽히는지 테스트로 고정 |
|
||
| 06-02, 06-06 | 푸시 구독 해지 | 다른 탭·다른 계정의 정상 구독을 지우지 않음을 테스트로 고정 |
|
||
| 13-06 | 번들에 들어가는 설정 | 필요한 `VITE_*` 값이 모두 번들에 남음을 테스트로 고정 |
|
||
| 09-02, 09-07 | 기능 선택·설치 규칙 | 기본값(전체 설치)의 산출물이 바뀌지 않음을 확인 |
|
||
| 11-01, 13-03, 13-05 | 승격 판정 의미 변경(PASS → UNVERIFIED) | 로컬 증거 생성 경로는 그대로 두고 판정 이름만 정직하게 |
|
||
| 12-12 | 여러 영역 파일 수정 | 통합 뒤 단독 작업, 동작 변경 없음 |
|
||
|
||
모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다. 태그는 로컬만 만들고 push하지 않는다.
|
||
|
||
## Risks and Mitigations
|
||
|
||
| 위험 | 영향 | 대응 |
|
||
|---|---|---|
|
||
| 레인 병렬 실행 부하로 시간 의존 테스트가 흔들림(10-02) | 가짜 실패 | 무관한 실패는 단독 재실행으로 확인하고 레인 보고에 적는다. 10-02는 레인 J에서 고친다 |
|
||
| 레인 간 파일 충돌 | 통합 지연 | 소유 레인 표. 통합은 레인 하나씩, 병합마다 게이트 |
|
||
| `gates.json` 변경마다 CI 계약 해시가 바뀜 | 게이트 실패 | 14-02를 Phase 0에서 먼저 끝낸다. 이후 변경은 `update:ci-contract-baseline`으로 기준을 갱신한다 |
|
||
| 리뷰가 제안한 방향이 실제 코드에서 더 큰 변경을 요구 | 범위 증가 | 결정 표 밖의 설계가 필요하면 멈추고 사용자에게 묻는다 |
|
||
|
||
## Open Questions
|
||
|
||
- 없음. 결정 표 기본값으로 진행한다. 결정을 바꾸려면 승인 전에 알려 주면 된다.
|