Files
DongHyeonkaandClaude Opus 5.5 c5f379b82c docs: plan the 2026-09-25 maturity review fixes
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>
2026-09-25 21:05:08 +09:00

100 lines
6.5 KiB
Markdown
Raw Permalink 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: 성숙도 리뷰(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
- 없음. 결정 표 기본값으로 진행한다. 결정을 바꾸려면 승인 전에 알려 주면 된다.