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

6.5 KiB
Raw Permalink Blame History

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

  • 없음. 결정 표 기본값으로 진행한다. 결정을 바꾸려면 승인 전에 알려 주면 된다.