문제
create:feature --with-create가 만드는 작성 폼의 feedback은 form.failure와 결과
불명 두 가지뿐이다. 저장 성공은 상세로 이동해서 알리는데, "변경됨으로 확인"은
reconcileUnknownEffect(...).then(form.settleApplied)이고 이동하지 않는다.
settleApplied가 결과를 success로 바꾸고 기본값 resetOnSuccess로 입력을 비우므로,
결과 불명 화면이 사라진 뒤 빈 폼만 남는다. 짝 백엔드 기본(NEVER)에서는 이것이
화면 안의 유일한 행동이다. 사용자는 확인이 받아들여졌는지 모르고, 다시 입력해
저장하면 키 없는 생성이 한 번 더 나간다(실제로 저장됐던 경우 중복). 참조 폼은
같은 경우 "저장했습니다."를 보인다.
고른 방법
확인 뒤 폼을 정리하고(settleApplied, flushSync라 이동 전에 dirty 가드가 풀린다)
목록으로 이동한다. 목록은 항목이 실제로 저장됐는지를 보여 주는 화면이고,
reconcileUnknownEffect가 이미 목록 topic을 무효화한다. 라우터가 목록 제목으로
포커스를 옮기므로 08-01의 포커스 문제도 이 폼에서는 생기지 않는다. 생성 기능
테스트에 "응답을 잃은 생성 → 변경됨으로 확인 → 목록 제목과 항목"을 한 행 더했다
(NEVER·KEYED 공통). 매뉴얼 02의 생성 테스트 행에 적었다.
버린 대안
참조 폼처럼 success 가지에 확인 문구를 둔다: 생성 catalog에 키가 하나 늘고,
항목이 실제로 있는지는 여전히 보이지 않는다.
위험·한계
- 짝 백엔드 생성기에는 목록 GET이 아직 없다(1103/03-07 결정 대기). 실제 짝
백엔드에서는 이동한 목록이 405를 받는다(생성 목록 페이지가 지금 그렇다).
생성 테스트는 MSW로 목록을 답한다.
- 생성 결과 파일은 단위 테스트가 문자열로만 보고, 동작은 test:feature-scaffold
(KEYED, FE-GATE-020)와 test:sample-removal(NEVER)에서 생성한 테스트가 본다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/create-feature.test.ts
corepack pnpm test:feature-scaffold
corepack pnpm test:sample-removal
Refs: 1105/08-02
문제
1103/08-02 수정(2d5d41f8)이 저장 버튼을 disabled 대신 pending으로 바꾸면서
버튼은 결과 불명일 때만 꺼진다. 코디네이터가 mutation-pending이어도 이 폼이
저장 중이 아닐 수 있다. 저장 중에 화면을 떠났다가 같은 세션에서 돌아온 경우
(진행 중 시도가 있는 동안 채널이 남는다)와 "변경됨으로 확인"을 처리하는
동안이다. 그때 onSubmit은 아무것도 하지 않고 돌아가고 feedback에도 아무것도
없다. 저장을 눌러도 반응이 없고, 첫 저장이 끝난 뒤에도 그 클릭은 실행되지
않는다(리뷰 08-R1 D). 참조 폼과 생성기 템플릿이 같다.
고른 방법
"코디네이터가 mutation-pending인데 이 폼은 저장 중이 아님"을 otherSaveRunning으로
두고 두 가지를 함께 한다.
- 저장 버튼을 그동안 끈다. 이 폼 자신의 저장 중에는 지금처럼 끄지 않고 busy로
둔다(포커스 유지, 1103/08-02). 그때 포커스는 저장 버튼에 있지 않다(다시
마운트한 폼이거나, 누른 버튼은 "변경됨으로 확인"이다).
- feedback에 코디네이터 상태를 AsyncSurface로 그려 "변경 사항을 저장하고
있습니다."를 보인다. 이 폼의 결과 불명을 확인하는 동안(결과가 effect-unknown)은
그리지 않는다. 확인이 끝나면 곧 결과가 바뀌고, 그 사이에 상태 문구가 하나 더
생기지 않게 한다.
참조 폼 페이지와 create:feature 쓰기 슬라이스 템플릿을 같이 고쳤다.
버린 대안
문구만 보이고 버튼은 켜 둔다(리뷰 문서가 포커스 때문에 권한 쪽): 확인 중에는
문구를 그릴 수 없어(위) 그때 버튼이 다시 무반응이 된다. 끄는 버튼에 포커스가
없으므로 포커스를 잃지 않는다.
위험·한계
- 생성기 쪽은 생성 결과 문자열만 단위 테스트가 본다. 다시 마운트하는 동작은
참조 폼 테스트로만 확인한다. 생성 기능의 기존 테스트는 test:feature-scaffold
(FE-GATE-020)와 test:sample-removal에서 돈다.
- 다른 탭이나 새로고침은 해당 없다(코디네이터는 앱 메모리 안이다).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx
tests/unit/create-feature.test.ts
Refs: 1105/08-04
문제
1103/08-02 수정으로 저장이 실패 상태나 결과 불명으로 끝나면 포커스가 feedback
자리로 가고, Tab 한 번에 복구 버튼("변경됨으로 확인", "같은 요청으로 다시
보내기", "다시 시도")에 닿는다. 그런데 그 버튼을 키보드로 눌러 일이 끝나면
버튼을 그리던 상태가 "저장했습니다."로 바뀌며 버튼이 문서에서 빠지고, 브라우저가
포커스를 body로 돌린다. 폼은 실패 결과일 때만 포커스를 옮기고 성공 쪽
settleSuccessfulValues는 옮기지 않는다(리뷰 08-R2: chromium·firefox·webkit × 세
경우 9건 모두 body, jsdom 08-R1 B1~B3도 BODY).
고른 방법
useAppForm의 포커스 effect가 직전에 그린 결과를 기억한다. 결과가 상태
결과(reauth-required·forbidden·retry-later·unavailable)나 effect-unknown에서
success로 바뀌었고 그때 포커스가 body(잃음)이면 feedback 자리로 옮긴다. 페이지마다
복사하지 않고 폼 하나에서 고친다. 포커스를 잃었을 때만 옮기므로 버튼이나 필드에
남아 있는 포커스는 빼앗지 않고, 처음 저장이 그냥 성공할 때는 옮기지 않는다
(1103/08-02의 보존 조건). success를 그릴 feedback이 없는 화면(생성 폼은 저장 뒤
상세로 이동)에서는 아무것도 하지 않는다.
버린 대안
settleSuccessfulValues에서 늘 feedback으로 옮긴다: 마우스로 누른 첫 저장에서도
포커스가 움직인다. 리뷰 문서의 (2)(확인 중에도 feedback 자리를 비우지 않는다)는
08-04에서 다룬다. 자리를 유지해도 눌렀던 버튼은 빠지므로 끝난 뒤 포커스는 이
커밋이 정한다.
위험·한계
- 확인·재전송이 진행되는 동안(끝나기 전)에는 포커스가 잠깐 body에 있다. 끝난
뒤만 고친다(완료 기준).
- 포커스를 받는 feedback 자리에 역할·이름이 없어 스크린 리더가 어떻게 읽는지는
확인하지 않았다(리뷰 3.5절 관찰 그대로).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
corepack pnpm exec playwright test tests/e2e/reference-save.spec.ts
--project=chromium --project=firefox --project=webkit
Refs: 1105/08-01
문제
refusedBeforeWrite로 선언한 업무 거절은 이제 결과 불명이 아니고 다시
저장된다. 그런데 거절 이유가 사용자 말로 보이지 않는다. 선언한 400은 kind
UNKNOWN_CLIENT_FAILURE라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이고,
409는 kind CONFLICT라 "다른 변경과 충돌했습니다."다. 고칠 수 있는 입력인데
지원 문의로 보낸다. mapProblem으로 필드 오류를 만들어도 문구는 플랫폼 표에서
issue code로만 고르므로(표에 없는 DUPLICATE는 "입력값을 확인해 주세요.")
기능이 *_ALREADY_EXISTS 같은 거절에 자기 문구를 붙일 자리가 없다(리뷰 08-R1
A1~A3). conflict 결과에서는 form.failure가 null이라 페이지가 code를 읽어 따로
그릴 수도 없다.
고른 방법
useAppForm에 refusalMessages 옵션을 더한다. 실패 code별로 기능 catalog의
메시지 키와(선택) 필드를 적는다. 적용 안 됨(effect NOT_APPLIED)으로 끝난 실패의
code가 있으면 그 문구를 필드 오류로(필드가 없거나 allowedServerFields 밖이면 오류
요약으로) 보이고 결과를 validation-error로 둔다. 필드면 그 필드로 포커스를
옮긴다. 키는 렌더 때 번역한다(다른 폼 오류와 같다). Object.hasOwn으로 자기 키만
읽는다(1103/08-03). 재로그인(action reauth)이 먼저다. 결과 불명은 code와 상관없이
결과 불명이다. 매뉴얼 02 4절에 적었다.
버린 대안
- 플랫폼 문구 표(form-contracts.ts)에 code를 더한다: 기능 code를 템플릿 파일에
적게 된다.
- mapProblem이 문구까지 돌려주게 한다: 어댑터가 presentation 메시지 키를 알게
된다.
- 지난 리뷰 5.3절 (B)(useAppForm이 코디네이터 상태를 받아 결과를 하나로 낸다):
더 넓은 구조 변경이라 이 커밋에서 하지 않았다.
위험·한계
- 1103/03-01 남은 부분 중 이 커밋은 "이유 문구와 기능 문구 자리"만 고친다.
KEYED 결과 불명의 같은 키 재전송이 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받아도
재전송 버튼이 남는 것(08-R1 A5)은 결정 대기로 남긴다. 백엔드 §2는 이 답에
"같은 키 재전송은 안전하다, 첫 시도가 늦게 끝났으면 그 결과를 재생한다"고 적고
답 표 사본도 sameKeyResend: true다. 버튼을 거두면 그 회복 길도 닫힌다. 고르는
사람: 프론트 템플릿 담당(frontend-platform). 선택지: (a) RECOVERY_REQUIRED 뒤
재전송을 거두고 "목록에서 확인" 안내를 둔다(AppFailure에 답의 원인을 싣는 계약
추가 필요), (b) 백엔드가 KEYED 작업 안의 업무 예외(트랜잭션 롤백)를 "효과 없음"
으로 기록해 같은 키 재전송이 다시 실행되게 한다(백엔드 변경), (c) 지금대로 둔다
(재전송은 안전하고, 참조 폼은 목록 새로 보기 링크가 있다).
- 선언하지 않은 code는 지금처럼 결과 불명이고 "변경됨으로 확인"이 남는다(완료
기준의 설계). 참조 기능과 생성기는 이 옵션을 쓰지 않는다. 생성기는 이미
<FEATURE>_INVALID를 필드 오류로 보인다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx
Refs: 1103/03-01
문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
그린다(실험 X3).
고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.
버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.
위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
(런북 6.3-7의 한계 그대로).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx
Refs: 0929/03-03
문제
짝 백엔드 http-contract.md §4는 web 전용 code 넷을 적는다. 그중 503
RATE_LIMIT_UNAVAILABLE(저장소 응답 없음, retryable, Retry-After 있음)과 503
RATE_LIMIT_INCOMPATIBLE(제공자 불일치)이 답 표 사본에도 프론트 판정 표에도
없다. 그래서 이 503은 기능 분류기가 정하고, create:feature가 만든 쓰기의
분류기는 늘 MAYBE_APPLIED다. 아무 일도 일어나지 않은 저장이 결과 불명이 되고,
NEVER 쓰기는 사실과 다른 "변경됨으로 확인"을 눌러야 폼이 풀린다(리뷰 실험 X4:
429는 NOT_APPLIED, 503 둘은 SERVER_FAILURE/MAYBE_APPLIED). pin은 §4를
대조했다고 적었지만 사본에는 REQUEST_TIMEOUT 한 행만 있었다.
고른 방법
백엔드 45d2a478을 읽기만 해서 code마다 판정했다. 두 code는
RateLimitInterceptor.preHandle이 false를 돌려주며 쓰고(Unavailable·
Indeterminate → RATE_LIMIT_UNAVAILABLE, Incompatible →
RATE_LIMIT_INCOMPATIBLE), main 소스에서 두 code를 내는 곳은 그 두 줄뿐이다.
preHandle이 false면 handler를 부르지 않으므로 둘 다 쓰기 전이다. 백엔드는 같은
키 재전송을 요구하지 않는다(멱등성 executor 전). 그래서 답 표 사본에
refusedBeforeWrite: true, sameKeyResend: false로 두 행을 더하고, 프론트 거절 표
REFUSED_BEFORE_WRITE에 status 503과 함께 더했다. pin 테스트의 "답 표대로 읽는다"
규칙이 그대로 NOT_APPLIED를 요구하고 양방향 대조가 두 표를 함께 지킨다. kind는
지금처럼 SERVER_FAILURE(action retry)이고, KEYED도 자동 재전송은 없다(같은 키를
요구하는 답은 503 IDEMPOTENCY_UNAVAILABLE 하나다). pin의 comparedOn을 §4를 다시
대조한 날짜로 올렸다. 계약 문서 4.1·6.1절과 매뉴얼 01·02의 5xx 행 수를 고쳤다.
버린 대안
생성기 분류기가 503을 code별로 보게 한다: 생성 기능에만 고쳐지고 손으로 쓴
Envelope operation은 그대로 남는다. 판정은 백엔드 답 표 한 곳이 정한다는 지금
규칙을 따랐다.
위험·한계
- 추론(실행 확인 안 함): Spring MVC는 비동기 처리(Callable·DeferredResult) 뒤
ASYNC 재디스패치에서도 interceptor의 preHandle을 다시 부르고, 이 interceptor는
dispatcher 종류를 보지 않는다. 비동기 쓰기 컨트롤러라면 이 503(그리고 429)이
쓰기 뒤에도 나올 수 있다. 45d2a478에는 Envelope을 돌려주는 비동기 쓰기
컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). 계약 6.1절에 적었다.
백엔드에 넘길 요청: RateLimitInterceptor가 DispatcherType.REQUEST에서만
평가하게 한다.
- fileserver-upload.ts는 같은 백엔드 답을 자기 표로 따로 판정한다(01 영역).
여기서는 바꾸지 않았다.
- NOT_APPLIED가 되면서 IDEMPOTENT 쓰기는 이 503에 retryBudget 안에서 자동으로
다시 보낼 수 있게 됐다(503은 재시도 status다). 쓰기 전 거절이라 중복은 없다.
RATE_LIMIT_INCOMPATIBLE은 백엔드가 retryable false로 보내지만 실행기는 status로
판단하므로 같은 답을 한 번 더 받을 수 있다. KEYED·NEVER는 자동 재전송이 없다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/backend-envelope.test.ts
tests/unit/backend-contract-pin.test.ts
tests/integration/http-execution-v3-envelope.test.ts
Refs: 1105/03-02
문제
commandEffect.refusedBeforeWrite의 조립 검사는 code 문법, 멱등성 접두사,
중복, Envelope 여부만 본다. 계약 문서 6.1절은 BAD_PARAMETER(어느 층이든
IllegalArgumentException), MAPPING_FAILED(멱등성 응답 직렬화는 action 뒤),
DB_* 8개, LOCK_ACQUISITION_TIMEOUT, fileserver code를 "쓰기 뒤 가능"으로
적는다. 이 code를 목록에 적어도 조립이 통과하고, 그 code로 온 400·409·422가
NOT_APPLIED가 된다. 쓰기 뒤에 난 실패를 사용자가 다시 저장하면 새 키나 키
없는 새 요청이 나가 같은 항목이 둘 생길 수 있다(리뷰 실험 X2: 네 code가
조립을 통과하고 모두 NOT_APPLIED).
고른 방법
6.1절의 "쓰기 뒤 가능" 플랫폼 code를 src/contracts/external-contract-runtime.ts에
PLATFORM_CODES_POSSIBLY_AFTER_WRITE로 두고, assertRefusedBeforeWrite가 그
code의 선언을 6.1절을 이유로 거절한다. 실행기의 fail-close(조립 없이 부른
경우)도 같은 목록을 무시한다. 목록을 adapters가 아니라 contracts에 둔 것은
조립 검사가 adapters를 import할 수 없기 때문이다(리뷰 문서의 최소 개선은
backend-envelope.ts에 두라고 했다). backend-contract-pin.test.ts가 계약 문서
6.1절 표의 "쓰기 뒤 가능" 행을 읽어 목록과 양방향으로 대조한다. 참조 도메인
code와 web-advanced patch code는 엔드포인트가 단계를 정하므로 테스트의 예외
목록에 적고 선언할 수 있게 둔다.
버린 대안
- 매뉴얼 문장만 둔다(현상 유지): 폼을 막는 code를 넣고 싶어지는 바로 그
자리에 통제가 없다.
- 업무 code 접두사 규칙(<FEATURE>_로 시작하는 code만 허용): 다운스트림 code
이름을 강제해 과하다.
위험·한계
- 이미 이 code를 적은 다운스트림 계약은 부팅에서 조립이 실패한다. 의도한
실패다.
- 6.1절 표에 플랫폼 code가 더해지면 목록도 같이 고쳐야 한다. 대조 테스트가
알린다. 백엔드가 code를 더한 것은 pin을 올릴 때 6.1절을 다시 읽어야 안다.
- 업무 code를 잘못 선언하는 것은 여전히 막지 못한다(기능 작성자의 판단).
- 대조 테스트는 계약 문서를 읽으므로, 문서를 복사하지 않는 기능 제거
드릴(FE-GATE-020의 optional-recipe·browser-file-storage·realtime)에서는
돌지 않는다. `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에
`tests/unit/backend-contract-pin.test.ts`를 더했다. 저장소 자신의 test:unit은
그대로 돌린다.
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/unit/backend-envelope.test.ts tests/unit/backend-contract-pin.test.ts
corepack pnpm test:optional-recipe-removal
BREAKING CHANGE: refusedBeforeWrite에 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔
플랫폼 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE)를 적으면
composeContractContributions가 거절한다. 그 code를 목록에서 지운다. 그 code의
실패는 결과 불명으로 남는다.
Refs: 1105/03-01
문제: FE-GATE-008의 test:browser-capabilities가 firefox에서 가끔 30초 시간
초과로 떨어졌다. browser-files.spec.ts의 두 test가 번갈아 걸렸다. 하나는
"filechooser"를, 다른 하나는 "download"를 기다리다 끝났다. desktop에서
firefox capability suite를 30회씩 돌리면 두 test 60건 중 3건이 떨어졌다(두
번 모두). 부하와는 상관없었다(1.05에서도 남). 리뷰 14.7절은 이것을 "알려진
flake"로 두었다(1103/11-10).
원인: 두 test는 `goto("/")` 직후 label·input·button을 `<body>` 끝, 앱 root
뒤에 붙이고 그 button을 누른다. 그때 앱은 아직 그리는 중이다. 실패한 6건의
event 기록(진단 branch, 커밋 안 함)은 모두 같았다.
- pointerdown·mousedown은 button("Choose test file"/"Download generated").
- 30~45 ms 뒤 pointerup·mouseup은 홈 화면 내용("프로젝트 시작점…").
- click은 둘의 공통 조상(앱 root)이라 button의 handler가 돌지 않았다
(`__browserFileResult` 없음). 그래서 picker도 download도 없었다.
- 위치까지 적은 3건에서 그 사이 scrollY는 24로 같았다. body 높이는 744에서 756으로, button top은
696에서 708로 둘 다 12 px 늘었다. 앱 내용이 클릭 도중 12 px 자랐고,
viewport 아래 끝의 button 중앙 좌표가 button 밖이 됐다. 통과한 run은
pointerdown 때 이미 756이었다.
고른 방법: 두 test가 붙이는 control을 `position: fixed` 층(왼쪽 위, 가장
높은 z-index)에 둔다. 앱의 흐름 밖이라 앱이 늦게 그려도 button이 움직이지
않는다. 제품 코드는 바꾸지 않는다.
버린 대안:
- 앱이 다 그려질 때까지 기다린다. "다 그려짐"을 정할 신호가 없다. 늦게 오는
글꼴이나 내용이 생기면 다시 깨진다.
- `dispatchEvent("click")`이나 `force` click. 신뢰된 사용자 입력이 아니어서
firefox가 file picker를 열지 않는다. test가 증명하려는 것을 지운다.
- 재시도·timeout 늘리기·worker 줄이기. 금지된 우회이고 원인이 남는다.
위험·한계: 고정 층이 앱 header 왼쪽 위를 덮는다. 두 test는 앱 UI를 누르지
않는다. 다른 capability spec은 body에 control을 붙이지 않는다(grep).
검증 (desktop):
- RED(커밋 안 한 재현): mousedown 때 앱 root에 400 px를 더하고 layout을
다시 계산한다(앱이 늦게 그리는 것과 같은 일). 수정 전 spec은 세 엔진 두
test 6/6 실패(filechooser·download 대기 시간 초과).
- GREEN: 같은 재현에서 수정 뒤 6/6 통과.
- 실제 조건 firefox capability suite ×30: 수정 전 두 번 다 3 failed /
657 passed, 수정 뒤 660 passed.
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).
고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
"preload한 script가 실제로 실행됐는가"를 본다.
- 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
MutationObserver로 적고, 끝에 남은 link도 더한다.
- page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
문장 하나를 앞에 붙인다.
- test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
"참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
- script가 아닌 preload는 `preloadunverifiable:<as>:`.
- Service Worker가 문서를 제어할 때 만든 preload는
`preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
release manifest의 sha256 대조가 깨진다.
- route.fetch가 세 번 실패해 표시 없이 넘어간 script는
`preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
- boot-module-failure: 깨진 build의 boot 정적 closure.
- old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
허용이 WebKit 경고 문구로만 있었다.
- service-worker-update: worker 제어 중 preload만.
- production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
fulfillBuildScript를 쓴다.
버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.
위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
service-worker-update만 허용).
검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
- 변이 test는 세 엔진 모두 Expected
["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
- 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
…/reference-schemas-DICBcHlO.js was preloaded using link preload but not
used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
- 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
- 새 fixture: 3/3 실패,
"preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
- 이전 fixture: webkit 실패.
- 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
(probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
문제
workflow는 모든 job에 CI=true와 CI 빌드 식별값을 준다. 메인 세션이 깨끗한
clone에서 그 env 그대로(CI=true 포함) merge 단계 14개를 돌리자 FE-GATE-005·
008·020이 실패했다.
- vitest 안의 fixture 빌드(tests/e2e/support/fixture-builds.ts →
build-frontend.ts)가 CI=true를 물려받아 release 빌드처럼 검사된다.
af312de가 vitest에서 VITE_COMMIT_SHA를 지워 "missing required CI build
environment: VITE_COMMIT_SHA"로 멈춘다(service-worker-build-output 7건이
돌지 않음, 제거 드릴 안에서도 같다).
- 시각 골든 build(9bddfa5)가 VITE_COMMIT_SHA="local"을 받는데 CI=true가
40·64자리 hex를 요구해 webServer가 뜨지 않는다.
내 X4가 CI=true 없이 돌아 놓쳤다. 1103/11-07과 같은 원인이다.
고른 방법
- scripts/lib/build-environment.ts에 둘을 둔다.
- localBuildEnvironment(env): spawn하는 로컬 빌드용. CI와 CI 빌드 식별값을
뺀 사본. fixture-builds.ts, service-worker-builds.ts가 쓴다.
- LOCAL_BUILD_IDENTITY: Playwright web server용. Playwright가 env를
process.env 위에 합치므로 CI를 지우지 않고 ""로 덮는다(검사는
CI === "true"일 때만). visual·capabilities·dev 설정이 쓴다.
- assertCiBuildEnvironment의 CI=true 검사는 그대로다. job 자신의 release
빌드(build:release-candidate 등)는 계속 검사된다.
- 버린 대안: 로컬 빌드에 유효한 가짜 커밋 id(0×40)를 주기. CI=true 검사의
다른 칸(CI_RUNNER_IMAGE, SOURCE_DATE_EPOCH)도 함께 맞춰야 하고, 로컬
빌드가 release 빌드인 척한다.
위험·한계
- 로컬 빌드 안에서 CI를 읽어 동작을 바꾸는 코드가 있으면 그 빌드는 이제
CI가 아닌 쪽으로 돈다(지금은 build-environment 검사뿐이다).
검증
- tests/unit/local-build-environment.test.ts 3건: 구현 전 2건 실패(RED),
CI job 자체 검사는 유지.
- CI=true·VITE_COMMIT_SHA·VITE_BUILD_ID=gitea-41-1·RELEASE_ID·
CI_RUNNER_IMAGE·SOURCE_DATE_EPOCH로: service-worker-build-output 7건,
test:visual 6/6, test:unit 2,883, test:component 270, test:integration 189
통과. 수정 전 service-worker-build-output은 7건 미실행.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
깨끗한 clone의 FE-GATE-008에서 dev server를 쓰는 capability e2e가
"requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 1~4건씩
떨어졌다(세 번 중 세 번, 부하 9~30). 플러그인(db5728b)이 dev server 시작
때 .generated/frontend-runtime/에 manifest를 쓰는데, polling 감시
(CHOKIDAR_USEPOLLING=1)가 그 새 파일을 서버가 뜬 뒤에 보고 부팅 중인 페이지를
다시 불러오면 진행 중인 manifest 요청이 끊긴다고 본다. 플러그인을 넣기 전
같은 부하의 회차들은 66건 모두 통과했다.
고른 방법
- 자식 프로세스가 manifest를 stdout으로 내고, 플러그인은 그 문자열을
메모리에 두고 낸다. 파일을 쓰지 않으므로 감시가 볼 것이 없다.
devReleaseManifest(source)가 문자열을 돌려준다.
위험·한계
- 원인을 감시 이벤트로 직접 관측하지는 않았다(추론). 수정 뒤 재실행으로
확인한다.
검증
- tests/unit/dev-release-manifest.test.ts 2건, check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 X4
문제
dev-release-manifest 테스트의 둘째 경우가 생성 결과를 커밋된 자리표시자와
통째로 비교한다. 템플릿 기능만 있으면 같지만, 기능을 더한 제품이나 생성
기능을 넣은 제거 드릴 fixture에서는 contract set이 달라 실패한다. 깨끗한
clone의 FE-GATE-020(test:sample-removal 안의 test:unit)에서 떨어졌다. 이
리뷰가 여러 번 고친 "템플릿 그대로일 때만 맞는 테스트"와 같은 결함을 새로
만들었다.
고른 방법
- 둘째 경우는 contract set을 뺀 나머지 칸이 자리표시자와 같고, contract
set이 설치된 기능의 buildContractSet()과 같은지 본다.
검증
- 테스트 2건, eslint, check:types 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
c15345c가 vite.config.ts에서 scripts/lib/dev-release-manifest.ts를
import한다. 초기 JS를 재는 measure-feature-shape-growth.ts와
product-feature-selection-build 테스트는 빌드할 복사본에 정해진 파일만
복사하는데(BUILD_INPUTS), 그 목록에 새 파일이 없다. 그래서 복사본의 vite
build가 "Could not resolve './scripts/lib/dev-release-manifest.ts'"로 실패해
test:unit 두 파일과 세 capability 제거 드릴이 떨어졌다. c15345c 뒤에
test:unit 전체를 돌리지 않아 놓쳤다.
고른 방법
- 두 BUILD_INPUTS에 그 파일을 더한다.
- 두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 이 수정의 범위 밖으로
둔다(남은 문제).
검증
- test:unit 193파일 2,880건 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02)는 복사본에 제품
파일과 기능 하나를 넣고 tsc 세 프로그램을 돈다. 세 가지가 제품과
제거 드릴에서 깨진다(리뷰 조치 X2 #1, #7).
- 탐침 ID가 notice-feature·notice-context다. 매뉴얼 예시가 모두 "공지"라
제품이 같은 ID를 쓰면 FE-GATE-005가 원인을 말하지 않는 TS 오류 약
20줄로 실패한다.
- product-capabilities.ts가 템플릿의 빈 선언 그대로여야 한다고 단언하고
그 선언을 바꿔 쓴다. 자기 capability를 적은 제품에서 실패한다.
- 복사 대상을 모두 복사한다. test:optional-recipe-removal의 fixture에는
recipes/가 없어 ENOENT로 떨어진다.
고른 방법
- 탐침 이름을 typecheck-probe-*(capability typecheckProbeSettings, 설정 키
TYPECHECK_PROBE_PAGE_SIZE)로 바꾸고, 그 기능 폴더가 이미 있으면 이름을
말하며 실패한다.
- capability 타입은 제품 파일 끝에 같은 이름 interface로 덧붙인다.
TypeScript가 합치므로 제품의 선언이 남는다.
- 없는 복사 대상은 건너뛴다.
위험·한계
- product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔
쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 복사본에서
타입 오류가 날 수 있다.
검증
- 테스트 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02, README.md 14.6 X2
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.
고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
`/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.
위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).
검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
test:sample-removal의 잔여 검사(REFERENCE_RESOURCE|reference-feature|
reference-resource)가 샘플을 지운 fixture에서 두 파일을 잡아 FE-GATE-020이
실패한다. tests/unit/hosting-probe.test.ts는 비상 스위치 예시로
FEATURE_OVERRIDES에 "reference-feature"를 쓰고(13-01), platform-examples-
context의 머리 주석은 참조 context 경로를 적는다(09-04).
고른 방법
- 테스트 값을 "platform-examples-feature"로 바꾸고, 주석은 샘플 이름 없이
적는다. 동작은 바뀌지 않는다.
검증
- tests/unit/hosting-probe.test.ts 37건, lint 통과. 제거 드릴은 X4 재실행에서
확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
깨끗한 clone의 FE-GATE-008에서 test:storybook이 "Axe is already running"으로
떨어졌고, 이 worktree에서도 두 번에 한 번 떨어진다. @storybook/addon-a11y
10.6.5(13-03이 올린 판)는 story를 그린 뒤 afterEach에서 axe를 스스로 돌린다
(globals.a11y.manual이 true가 아니면). spec의 AxeBuilder.analyze()는 그 페이지의
같은 axe 인스턴스를 쓰므로, 두 실행이 겹치면 두 번째가 거절된다.
고른 방법
- spec이 story를 `globals=a11y.manual:!true`로 연다. 애드온은 자동 검사를
건너뛰고, 접근성 판정은 지금처럼 spec의 AxeBuilder가 한다.
- 버린 대안: 애드온 실행이 끝나길 axe 내부 상태로 기다리기. 공개 API가
아니고, 애드온 실행이 시작되기 전에 확인하면 여전히 겹친다.
- 버린 대안: preview 전체에서 애드온 자동 검사 끄기. workshop에서 쓰는
사람이 패널 결과를 잃는다.
위험·한계
- 이 spec만 바꿨다. 다른 storybook spec이 생기면 같은 URL을 쓴다.
검증
- test:storybook 5회 연속 통과(heavy lock). 수정 전 2회 중 1회 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).
고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.
버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
가정 하나를 지키려고 정상 입력을 막는다.
위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
적었다. 이 경로의 드릴은 돌리지 않았다(추론).
검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
상태에서 tests/features 124건 통과, tests/component·architecture와
create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).
고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
실패 본문 행을 더한다.
버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
"빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
"...-vertical-slice"). 그대로 둔다.
위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
(REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
잡힌다.
검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
create-feature 테스트 통과. check:types, lint, verify:documentation 통과.
BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
직전 커밋(짝 저장소 참조 테스트 범위 축소)이 보고서의 missingPaths를
읽지만, 테스트가 JSON을 읽을 때 쓰는 타입에 그 칸이 없어 check:types가
TS2339로 실패한다. vitest는 타입을 보지 않아 테스트는 통과했다.
고른 방법
- 보고서 타입에 missingPaths?: string[]를 더한다.
검증
- check:types 통과, documentation-readiness 테스트 19건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
fix/r1103-gates(12-05)의 테스트는 옆 checkout을 흉내 낸 stub(백엔드
문서 1개)을 두고 verify:documentation 전체가 통과하기를 기대한다. 다른
브랜치를 합치자 실제 문서(매뉴얼 02·04, 백엔드 계약 문서)가 stub에 없는
백엔드 경로를 가리켜, 테스트가 status 1로 실패한다. 결함은 문서가 아니라
테스트 범위에 있다. 그 경로 14개는 실제 옆 checkout에 모두 있다.
고른 방법
- "있는 경로" 경우에서 전체 status 대신, 테스트가 고친 문서
(CI_DOC)에 빠진 경로가 없는지만 본다(stderr와 보고서 missingPaths).
- 버린 대안: stub에 실제 문서가 가리키는 백엔드 경로를 모두 만든다.
문서가 바뀔 때마다 테스트도 같이 바뀌어야 한다.
위험·한계
- 다른 문서의 짝 저장소 경로가 틀리면 이 테스트로는 잡지 않는다. 실제
옆 checkout이 있는 개발 환경의 verify:documentation이 잡는다.
검증
- tests/unit/documentation-readiness.test.ts 19건 통과.
- 실제 백엔드 checkout에서 문서가 가리키는 경로 14개 존재 확인.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다.
bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능
작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로
적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②).
고른 방법
세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는
채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다.
매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title·
navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다.
버린 대안
- 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과
다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다.
- 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의
operation ID를 싣는다. 같은 값을 두 번 싣는다.
위험·한계
- 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면
FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와
test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은
파일이라 이번에는 문서로만 적었다.
검증
- RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner·
operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과.
- tests/features/reference-feature, tests/unit/create-feature.test.ts,
scope-fence 129건 통과. check:types(app·node·test), lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
문제
BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시
적는 자유 값이다. operationId에 오타가 있어도 check:types와
check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와
다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을
처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이
같은 재기술을 적었다.
고른 방법
src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다.
descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은
이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를
넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다.
버린 대안
- BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트
약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다.
- 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌
위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지
않으므로 미뤘다.
- 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한
descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다.
위험·한계
- 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에
적었다.
- 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연
청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다).
검증
- RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패.
GREEN 뒤 통과.
- tests/features/reference-feature, tests/component/application-query.test.tsx
125건 통과.
- check:types, check:architecture, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.
고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
실패를 낸다.
- 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
빠진다.
- 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
골든을 제품 소유로 선언(동기화마다 PNG 충돌).
위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
보기" 버튼만 남는다.
검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
가림 규칙에 걸리지 않음).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.
고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
접근성 spec 생성(파일·실행 시간 증가).
위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
"passed"로 적힌다.
검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).
고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
이유), hover 프리페치(키보드·직접 진입에 효과 작음).
위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.
검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
feature-runtime·reference-schemas는 제목 뒤에 받는다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
문제
responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을
손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를
거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의
선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로
깨진다(리뷰 E-1).
고른 방법
계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이
없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서
그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다.
거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와
check:registries가 실패한다.
버린 대안
- responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor
약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입
변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다.
- 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다.
위험·한계
- 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트
(백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다.
- 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는
테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다.
검증
- RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과.
- tests/unit·integration·contract·component·features·runtime-schema·platform·
architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제: 의존성 취약점 판정은 운영 승격의 외부 provider에만 있었다. 로컬
supply chain은 스캔하지 않고 provider: UNCONFIGURED를 썼다. 그래서
lockfile이 템플릿 자신의 정책(high 이상 차단, 예외 0건)을 어겨도 merge·
release 단계에서는 아무 신호가 없었고, provider가 없는 복사본은 끝까지
몰랐다. 갱신 자동화도 없었다(짝 백엔드에는 renovate.json이 있다).
고른 방법:
- scan:dependency-advisories(scripts/scan-dependency-advisories.ts)가
pnpm audit --json에 config/security/vulnerability-policy.json과
예외 파일을 적용한다. 판정은 승격이 쓰는 validateVulnerabilityReport를
그대로 쓴다. 결과는 PASS / POLICY_VIOLATION(승격에서 막힐 항목 목록) /
UNVERIFIED(레지스트리에 닿지 못함)이고, 운영·개발 의존성별 개수와 함께
gate 로그와 artifacts/security/dependency-advisories.json에 남는다.
- FE-GATE-027(release-admission, release 단계, 후보 빌드 직후)이 이 명령을
두 번째로 돈다. 명령은 항상 exit 0이다.
- renovate.json을 둔다(보안 업데이트만, 사람이 리뷰·merge).
- 남은 운영 의존성 위반 2건과 올리지 않은 이유, 다시 볼 날짜
(2026-12-04)를 ci-quality-gates.md에 적는다.
버린 대안: merge 차단 audit(코드가 안 바뀌어도 advisory DB 변경으로
merge가 깨진다), 로컬 스캐너를 provider로 내장(서명 주체 분리라는 원래
목적이 사라진다), 새 evidence 산출물·스키마 등록(계약 변경이 커진다.
gate 로그가 이미 release 단계 산출물이다).
위험·한계: 비차단이라 신호를 읽는 사람이 있어야 한다. 네트워크가 없는
runner에서는 UNVERIFIED로 남는다. Renovate runner는 붙어 있지 않아
renovate.json은 아직 동작하지 않는다. 남은 zod·react-router high 2건은
dependency-change-evidence의 reviewer(owner와 다른 사람)와 zod의 번들
예산 결정이 있어야 고칠 수 있다. 계약 기준선(contract-baseline.json)을
명령 100개·참조 104개로 다시 기록했다.
검증: dependency-advisories.test.ts 5건(정책 위반 판정, PASS, 유효한
예외, 보고서 없음 → UNVERIFIED, FE-GATE-027 배선과 exit 0). 상태 판정을
PASS로 고정하는 변이를 넣으면 실패한다. 실제 실행: POLICY_VIOLATION
(운영 high 2, 개발 moderate 2), exit 0. 죽은 프록시로 돌리면 UNVERIFIED,
exit 0. check:ci PASS, CI workflow bytes PASS, ci-workflow-generation·
product-ci-overlay·ungated-scripts·removal-fixture·supply-chain 489건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제
fb20699의 새 테스트는 보호 라우트 하나를 찾아 단언하고, 없으면 실패한다.
참조 기능을 지운 제거 fixture에는 보호 라우트가 없어서, test:sample-removal
(snapshot fd11d08)의 test:all과 test:coverage가 이 테스트 하나로 실패했다.
고른 방법
- 같은 파일의 "every non-public route" 반복 안에서 recovery-pending과
authenticated를 함께 단언한다. 라우트가 있는 템플릿에서는 같은 변이를 잡고,
보호 라우트가 없는 구성에서는 다른 단언처럼 대상이 없다.
검증
- 파일 4건 통과. 변이 L02(wait-for-session → show-sign-in)를 넣으면 그 반복
테스트가 실패한다(되돌림). eslint 통과.
- snapshot fd11d08의 test:sample-removal: 이 테스트 말고 실패한 검사가
없었다(documentation·lint·i18n·design-system 포함).
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 1101/10-03
문제
fix/r1103-transfer의 Fileserver 업로드 client는 실패 kind를 공유 Envelope
판정(envelopeFailureReading)에서 받고 413·415만 VALIDATION_REJECTED로
바꾼다. fix/r1103-http(1103/08-05)는 필드 목록 없는 422를
UNKNOWN_CLIENT_FAILURE로 읽게 했다. 두 브랜치를 합치자 Fileserver의
422(digest·서명·검사기 거절, 예: MALWARE_DETECTED)가 입력 거절이 아니게
되어 통합 테스트 2건이 실패한다.
고른 방법
- Fileserver 계약에서 422는 파일 자체의 거절이다(백엔드
docs/fileserver/http-contract.md 상태 표). 사용자가 파일을 바꿔야 하는
413·415와 같이 VALIDATION_REJECTED로 둔다.
- 422 IDEMPOTENT_REQUEST_MISMATCH(같은 키, 다른 본문)는 파일 문제가
아니므로 08-05의 공통 판정(UNKNOWN_CLIENT_FAILURE)을 따른다. 테스트
기대값도 그렇게 바꿨다.
- 버린 대안: 공통 판정을 422 전체 입력 거절로 되돌리기. 08-05가 고친
결함(같은 키 불일치를 입력 오류로 보임)이 다시 생긴다.
위험·한계
- 422 code 목록을 파일 거절로 고정하지 않고 "불일치가 아니면 파일 거절"로
본다. 백엔드가 파일 업로드에 다른 뜻의 422를 더하면 다시 본다.
검증
- test:integration 189건(fileserver-upload 48건 포함), check:types,
lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, 08-presentation.md 08-05
문제
fix/r1103-contracts는 fix/r1103-http가 아직 없을 때
CommandEffectDescriptor에 없는 refusedBeforeWrite를 구조 캐스트로
읽었다. 두 브랜치를 합치자 그 칸이 타입에 생겼다. 또 행 투영 테스트가
Envelope가 아닌 operation에 refusedBeforeWrite를 적는데, http 쪽 조립
검사(1103/03-01)는 그것을 거절해 테스트가 ContractContributionError로
실패한다.
고른 방법
- api-operations.ts는 effect.refusedBeforeWrite를 타입으로 읽는다.
- 테스트의 create descriptor에 responseEnvelope ENVELOPE_V1을 주고,
code를 업무 거절 모양(TEST_ENTITY_INVALID 등)으로 바꾼다.
위험·한계
- 행 모양은 그대로다. 기준선 영향 없음.
검증
- tests/unit/api-operation-rows.test.ts 12건, test:unit 2,790건,
check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제: pnpm 11은 설치 정책을 pnpm-workspace.yaml에서 읽는다(13-09가
.npmrc에서 옮겼다). engineStrict·saveExact가 빠지거나 minimumReleaseAge를
기본값(1440분)보다 짧게 줄여도 실패하는 검사가 없었다(0929/13-08, 세
라운드 남음). 지원하지 않는 Node로 설치되거나, 새 의존성이 ^ 범위로
저장되거나, 방금 나온 버전이 설치될 수 있다.
고른 방법: unit 테스트가 pnpm-workspace.yaml의 engineStrict: true,
saveExact: true를 확인하고, minimumReleaseAge를 적었다면 1440 이상인지
본다. minimumReleaseAgeExclude 항목은 정확한 버전만 허용한다.
버린 대안: `pnpm config get`을 부르는 테스트. 자식 프로세스 비용이 들고
같은 파일을 읽는다.
위험·한계: 파일 텍스트를 정규식으로 읽는다. 키를 다른 YAML 형식(인라인
맵 등)으로 바꾸면 테스트가 실패하므로 놓치는 쪽으로는 틀리지 않는다.
검증: 2건 통과. saveExact: false와 minimumReleaseAge: 60으로 바꾸면
실패하고 되돌리면 통과한다.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-08
문제
fix/r1103-storage가 더한 browser-file-session-capability·
runtime-adapters-product-scope-participants 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)의 제품 확장 타입 검사
테스트가 이 두 파일에서 TS2322로 실패한다(9b9d62a와 같은 원인).
고른 방법
- 두 테스트도 testRuntimeConfig로 설정을 만든다.
위험·한계
- 동작 변경은 없다.
검증
- tests/unit/product-extension-typecheck.test.ts, 두 테스트, test:recipes,
lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제
fix/r1103-session의 session-owners-runtime 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)은 템플릿 테스트가 제품 설정
키의 기본값을 받도록 testRuntimeConfig로 설정을 만들게 했고, 복사본에
제품 키를 넣은 뒤 tsc test 프로그램을 도는 테스트를 더했다. 두 브랜치를
합치자 그 테스트가 session-owners-runtime.test.ts:161에서 TS2322로
실패한다.
고른 방법
- 이 테스트도 tests/helpers/runtime-config.ts의 testRuntimeConfig로
설정을 만든다. 다른 템플릿 테스트와 같은 방식이다.
위험·한계
- 동작 변경은 없다. 테스트 입력 모양만 바뀐다.
검증
- tests/unit/product-extension-typecheck.test.ts 통과.
- tests/recipes/session-owners-runtime.test.ts 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02 09-03
문제
c4d5870 뒤 test:sample-removal이 문서를 복사하고 verify:documentation과 문서
테스트를 돌린다. 실제 드릴 실행(snapshot 0edc3fc)에서 두 가지로 실패했다.
- 드릴은 fixture에서만 tests/unit/ci-workflow-generation.test.ts와
tests/unit/removal-fixture.test.ts를 지운다(전체 저장소를 고정하는 테스트라).
docs/operations/adapter-remediation-ledger.md가 그 두 파일을 백틱 경로로 적어,
fixture의 문서 검사와 문서 테스트 7건이 실패했다. 샘플을 지운 실제 프로젝트는
그 테스트를 지우지 않으므로 이 실패는 fixture에만 있다.
- 잔여 검사가 tests/unit/documentation-readiness.test.ts의 정규식
REFERENCE_RESOURCE_[A-Z]+를 샘플 흔적으로 잡았다. 그 파일은 예전에는 fixture
에서 지워져 검사되지 않았다.
고른 방법
- 원장(기록 문서)의 그 세 곳을 백틱 없는 경로로 바꾼다. 드릴의 fixture 전용
삭제 목록 옆에 "현재 계약 문서는 이 파일들을 백틱 경로로 적지 않는다"를
적었다.
- 정규식을 [A-Z]+_RESOURCE_[A-Z]+로 쓴다. 라우트 ID를 지우는 용도는 같다.
- 버린 대안: 문서 검사에 fixture 전용 예외 경로를 넘기는 환경 변수. 운영
스크립트에 테스트용 입력이 생긴다. fixture 전용 삭제를 그만두기.
ci-workflow-generation 스냅샷은 줄어든 CI 계약과 맞지 않는다.
위험·한계
- 앞으로 현재 계약 문서가 그 두 테스트를 백틱으로 적으면 sample 드릴이 다시
문서 검사에서 실패한다. 실패 메시지가 파일과 경로를 적는다.
검증
- 수정 전 snapshot 0edc3fc의 test:sample-removal exit 1: documentation,
unit-integration, coverage, fixture-id-residue와 scaffold- 세 검사가 이 두
원인으로 실패. lint·check:i18n·check:design-system 등 나머지는 통과.
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지운 복사본(sim-sample-docs.sh)에서
verify:documentation PASS_SCOPED. 저장소에서 documentation-readiness 19건
통과, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
capability 제거 드릴의 fixture도 test:unit을 돈다. 앞 커밋들이 더한 가드
테스트 두 개가 그 안에서 실패했다.
- removal-fixture.test.ts: 문서 테스트 파일과 드릴 스크립트를 이름으로 읽는데,
fixture는 문서 테스트를 지우고(02-06) 드릴은 자기 스크립트를 지운다.
browser-file-storage·realtime 드릴이 이 두 건으로 `test` 검사에서 실패했다.
- feature-scaffold-drill: 제거 드릴이 자기 capability 명령을 계약에서 빼면,
scaffold 드릴 제외 목록의 그 스크립트가 "merge 단계에 없음"으로 실패한다.
고른 방법
- 문서 테스트는 "문서가 있는 곳에만 있다"를 단언한다(저장소: 둘 다 있음,
capability fixture: 둘 다 없음).
- 드릴 목록은 scripts/test-*.ts 중 removal-fixture.ts를 import하는 파일로 찾고,
sample·scaffold 드릴이 그 안에 있는지 확인한다.
- 제외 목록이 낡았다는 판정은 계약에 있으나 merge 단계 밖인 명령에만 한다.
계약에서 아예 빠진 명령(제거 드릴이 정리한 capability)은 낡은 것이 아니다.
위험·한계
- 계약에서 지운 스크립트의 제외 항목이 저장소에 남아도 이 검사는 알리지
않는다. 남아도 아무 명령을 숨기지 않는다.
검증
- 수정 전 snapshot(0edc3fc)에서 test:browser-file-storage-removal,
test:realtime-removal 모두 이 두 테스트로 exit 1(ENOENT).
- 수정 뒤 removal-fixture·feature-scaffold-drill 18건 통과, eslint·tsc 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
문제
tests/browser-capabilities/resumable-upload.spec.ts가 CORS 응답의 origin을
"http://127.0.0.1:4174"로 따로 적는다. playwright.capabilities.config.ts의
baseURL과 지금은 같아서 동작하지만, 설정의 포트를 바꾸면 이 spec만 CORS로
조용히 깨진다.
고른 방법
- 설정 파일을 import해 use.baseURL의 origin을 쓴다. test.info()는 route
처리기 안에서 부를 수 있는지가 Playwright 내부 맥락에 달려 고르지 않았다.
검증
- check:types(tsconfig.test.json) 통과, eslint 통과. 브라우저 실행 결과는
이 커밋 메시지에 적지 않았다(공유 잠금 대기).
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md (2절 FOLLOW-UP resumable-upload 포트)
문제
tests/unit/runbook-drill.test.ts의 "상수 판정 금지" 검사는 옛 모양
(assertion(..., true), Asserted: true)만 찾는다. drill은 이제
verdict()로 "PASS"/"FAIL" 문자열을 쓴다. 지난 리뷰 변이(:238의
verdict(await builtAssetsPresent(...))를 상수 "PASS"로)가 이 검사를
통과했다.
고른 방법
- assertion(..., "PASS"), *Asserted / *AsExpected: "PASS", verdict(true)
모양을 더 찾는다. 옛 정규식 셋은 그대로 둔다.
위험·한계
- 문자열을 변수에 담아 넘기는 우회는 이 정적 검사가 못 본다. 그 경우는
동작 테스트(FE-RB-002 등)가 본다.
검증
- 검사 통과. 리뷰의 변이를 다시 넣으면 이 검사가 실패한다(되돌림).
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 0929/11-08