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>
7.8 KiB
7.8 KiB
SPEC: 성숙도 리뷰(2026-09-25) 전 항목 반영
목적
docs/reviews/2026-09-25-maturity-review/의 발견 사항 138건 전부를 해결한다. 대상은 High 8 · Medium 57 · Low 73이다. 영역 문서 142건에서 같은 결함 4쌍과 포함 관계 1건을 합치고, 오케스트레이터 발견 00-01을 더한 수다.
요구사항 ID는 리뷰의 발견 ID와 같다(예: 03-01). 이 문서에는 세 가지만 적는다. 문제 설명·근거·발생 조건은 리뷰 문서를 기준으로 한다.
- 모든 요구사항에 공통인 완료 기준
- 리뷰에서 방향이 여러 개였던 항목의 결정
- repo 밖이라 이 작업이 끝낼 수 없는 항목
완료 기준의 기준은 해당 발견 항목의 "완료 기준" 칸이다. 아래 결정 표가 그 칸과 다르게 정한 경우에만 결정 표를 따른다.
범위 밖 (repo 밖 · 사람이 해야 함)
이 항목들은 코드로 끝낼 수 없다. repo 쪽 준비만 하고, 나머지는 tasks/todo.md "사용자 몫"에 남긴다.
| ID | 사용자 몫 | repo 쪽에서 하는 것 |
|---|---|---|
| U-1 (12-01, 14-01) | Gitea 저장소 Actions 활성화, runner 연결, branch protection에 merge 게이트를 required check로 지정 | push 트리거에 main 추가, README에 CI 상태와 머지 전 로컬 명령 명시 |
| U-2 (08-06) | 릴리스 후보 하나로 10개 라우트 수동 접근성 검토 수행·서명 | 결정 D-8 |
| U-3 (14-04) | 태그 push | CHANGELOG, README 업데이트 절, 로컬 태그 |
| U-4 (14-03, 13-13) | 작성자 외 사람의 기능 추가 수행 기록, staging에서 공급망 end-to-end smoke | 문서 정비, "provider 없는 구성" 문서화 |
| U-5 (03-01) | 백엔드 멱등 키 보관·충돌 계약 확인 | 클라이언트는 같은 키 재전송만 보장 |
공통 완료 기준 (모든 요구사항)
- 동작을 바꾸는 요구사항은 재현 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이 재현할 수 없는 항목은 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구한 항목은 spec 하나를 추가한다.
- 테스트 검출력이 문제였던 항목(변이 생존)은 리뷰에 적힌 변이를 다시 넣었을 때 새 테스트가 실패하는 것까지 확인한다.
- 작업마다 다음 게이트가 통과한다:
check:architecture,check:types,lint,test:unit,test:component,test:integration,test:contract,test:runtime-schema. - 레인이 끝날 때와 통합 때는 3번에 더해
check:ci,check:adapter-inventory,verify:documentation,test:sample-removal,build도 통과한다. - adapter 파일을 추가하거나 옮기면
docs/reviews/adapters/INVENTORY.md를 함께 고친다. - 공용 로직은
src/adapters/platform/(kernel) 또는src/contracts/에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다. - 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다.
- 작업 하나에 커밋 하나. 커밋 메시지에 발견 ID를 적는다. 그 작업이 바꾼 파일만 스테이징한다.
- 문서 요구사항은 문서의 각 주장이 코드 위치를 가리키는 것으로 확인한다.
결정
리뷰가 대안을 제시한 항목에 대해 기본값을 정했다. 계획 승인은 이 표의 승인이다.
| ID | 대상 | 결정 |
|---|---|---|
| D-1 | 03-01, 08-03 | 결과 불명(UNKNOWN) admission의 intent를 보관한다. 같은 canonical input으로 다시 저장하면 그 intent(같은 Idempotency-Key)로 보내고, 입력이 바뀌면 새 키를 쓴다. 결과 불명 화면의 "변경되지 않음으로 확인"은 "같은 요청으로 다시 보내기"로 바꾸고, 목록 새로고침 링크를 둔다. "변경됨으로 확인"은 유지한다. |
| D-2 | 03-02, 08-01 | CommandEffectDescriptor에 선택 필드 classifyStatus(status)를 추가한다. 없으면 지금처럼 MAYBE_APPLIED다. AUTH_REQUIRED는 effect와 무관하게 재로그인을 먼저 안내한다. reference 생성 계약은 401·403·429를 NOT_APPLIED로 선언한다. 폼은 reauth-required·forbidden·retry-later 상태를 가진다. |
| D-3 | 05-01 | 트랜잭션별 Web Lock을 begin부터 complete까지 잡는다. reconcile은 ifAvailable로 잠기지 않은 행만 처리한다. |
| D-4 | 06-02 | Web Locks(web-push-control)로 enable·reconcile·revoke를 origin 단위로 직렬화한다. native unsubscribe는 그 호출이 새로 만든 구독에만 한다. |
| D-5 | 06-03 | 운영 문서를 코드에 맞춘다. 부팅을 막는 워커용 비상 경로로 "자기 해제 워커" 빌드 모드를 만들고, REMOVE_REGISTRATION이 이 워커를 내보내게 한다. |
| D-6 | 07-02, 13-10 | 경계별 호환 규칙 표를 문서에 넣는다. 분류기는 모르는 변경(타입·enum·nullable)을 breaking으로 답한다(fail-closed). FE-GATE-014는 커밋한 기준 스키마와 현재 빌드 스키마를 비교한다. |
| D-7 | 07-03 | V2 행과 V3 descriptor의 일치 테스트를 추가한다. V2를 V3에서 생성하는 작업은 하지 않는다. |
| D-8 | 08-06 | review:a11y-manual을 release 단계 게이트로 옮긴다. merge 단계에는 기록 형식 검사만 남긴다. 실제 수동 검토는 U-2다. |
| D-9 | 09-02 | 생성기(generate-product-feature-index.ts)가 VITE_PRODUCT_FEATURES를 읽어 선택된 기능만 인덱스에 넣는다. 잘못된 값은 생성 단계에서 실패한다. |
| D-10 | 09-07, 14-03 | 생성기는 src/features/<f>/에 feature-module.ts가 없고 NOT_INSTALLED 표식 파일도 없으면 실패한다. 제거 스크립트는 기능 ID를 인자로 받는다. |
| D-11 | 12-05 | dependency-cruiser 실행을 뺀다. .dependency-cruiser.json은 이름을 그대로 두고 규칙 파일로 쓴다(스크립트·문서·메모리 참조가 많다). 문서 3곳을 고친다. |
| D-12 | 12-10, 12-08 | 새 시스템을 만들지 않고 줄인다. import 관련 정규식 규칙(icon vendor, realtime import, design-system deep import)은 그래프 규칙으로 옮기고 정규식을 지운다. workflow 계약에는 "모든 gate id가 run step에 있다" 불변식을 둔다. package-script-graph.ts는 막는 위험이 --ignore-scripts·allowBuilds로 이미 막히는지 확인한다. 막히면 줄이고, 아니면 이유를 기록한다. |
| D-13 | 14-02 | CI 계약의 개수·해시를 코드 상수에서 config/ci/contract-baseline.json(owner·reason 포함)으로 옮긴다. 갱신 스크립트 update:ci-contract-baseline을 제공한다. 제거 스크립트는 완화 모드 대신 갱신 절차를 거쳐 canonical check:ci를 통과한다. |
| D-14 | 11-01, 13-03, 13-05 | 로컬에서 확인하지 못한 판정은 PASS가 아니라 UNVERIFIED다. 코드에 상수 true 판정을 두지 않는다. 운영 승격은 live·provider 증거를 요구한다. FE-GATE-016과 025의 중복을 정리한다. |
| D-15 | 14-04 | CHANGELOG, README "원본 업데이트 반영" 절, 로컬 태그 v0.2.0. 태그 push는 U-3이다. |
| D-16 | 14-05 | docs/README.md 색인을 만든다(현재 계약 / 목표 설계 / 작업 이력). SPEC.md와 tasks/는 이 작업에서 쓰므로 옮기지 않고, 색인에서 이력으로 표시한다. |
| D-17 | 12-01 | repo 쪽만 한다(U-1 참조). |
| D-18 | 11-04 | reference feature를 복제한 실제 모양 기능 25개·100개로 측정한다. 400개는 시간이 허용하면 측정한다. 호스트 부하 조건을 함께 기록한다. |
| D-19 | 12-12 | noUnusedLocals를 켠다. 여러 영역 파일을 건드리므로 모든 레인을 통합한 뒤 마지막 작업으로 한다. |
요구사항 목록
138건과 작업의 대응은 tasks/todo.md에 있다. 모든 발견 ID가 정확히 한 작업에 속한다. 같은 결함 쌍(03-01=08-03, 12-02=13-01, 11-01=13-03, 07-01=08-02)과 포함 관계(09-11⊂12-04)는 한 작업에서 함께 닫는다.