# 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) | 백엔드 멱등 키 보관·충돌 계약 확인 | 클라이언트는 같은 키 재전송만 보장 | ## 공통 완료 기준 (모든 요구사항) 1. 동작을 바꾸는 요구사항은 재현 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이 재현할 수 없는 항목은 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구한 항목은 spec 하나를 추가한다. 2. 테스트 검출력이 문제였던 항목(변이 생존)은 리뷰에 적힌 변이를 다시 넣었을 때 새 테스트가 실패하는 것까지 확인한다. 3. 작업마다 다음 게이트가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`. 4. 레인이 끝날 때와 통합 때는 3번에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`도 통과한다. 5. adapter 파일을 추가하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 함께 고친다. 6. 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다. 7. 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다. 8. 작업 하나에 커밋 하나. 커밋 메시지에 발견 ID를 적는다. 그 작업이 바꾼 파일만 스테이징한다. 9. 문서 요구사항은 문서의 각 주장이 코드 위치를 가리키는 것으로 확인한다. ## 결정 리뷰가 대안을 제시한 항목에 대해 기본값을 정했다. 계획 승인은 이 표의 승인이다. | 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//`에 `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)는 한 작업에서 함께 닫는다.