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>
6.5 KiB
6.5 KiB
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)와 같은 구조다.
- Phase 0 (순차): 게이트·CI 기반 7개 작업. 이게 끝나야 새 clone, 샘플 제거, CI 계약이 이후 작업의 검증 수단으로 동작한다. Phase 0 뒤 Checkpoint 0.
- Phase 1 (병렬 레인): 레인마다 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 Phase 0이 반영된 브랜치 HEAD에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 진행한다(RED → GREEN → 게이트 → 커밋). 호스트 부하를 줄이려고 두 묶음으로 나눈다.
- 1차: A, C, E, I, K (작업이 많거나 위험이 큰 레인)
- 2차: B, D, F, G, H, J, M
- 통합 (순차): 레인 브랜치를 하나씩 rebase해 병합하고, 병합할 때마다 공통 게이트를 돌린다.
- 통합 후 작업: 12-12, 14-07, 리뷰 색인 상태 갱신.
- 최종 체크포인트: 전체 게이트,
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
- 없음. 결정 표 기본값으로 진행한다. 결정을 바꾸려면 승인 전에 알려 주면 된다.