2026-11-06 5라운드 리뷰 기록과, 그 발견을 고친 마지막 수정 라운드다. PR #7 위에 쌓았다. merge 순서는 #5 → #7 → 이 PR이다. base는 main이라, 앞의 둘이 merge되기 전에는 그 커밋도 diff에 보인다.
리뷰 기록 (302d3a5): docs/reviews/2026-11-06-maturity-review/. 기준은 bbde570(PR #7 끝)이다. 새 발견은 25건이다(High 0, P1 0, Medium 1, Low 24). 앞 라운드는 1105가 48건(P1 3), 1103이 88건(High 2, P1 12)이었다. 새 High·P1이 0건이라 반복의 멈춤 기준 중 리뷰 부분을 채웠다. 그래서 이번 라운드의 Medium·Low를 고치고 반복을 끝낸다.
수정: 새 발견 25건 중 24건을 고쳤다. 01-01은 일부만 고치고 백엔드로 넘겼다. 1103/15-02의 재발도 고쳤다. 발견별 상태·커밋·남은 것은 README 16.4절에 있다.
수정 diff 리뷰를 두 번 했다. 5라운드 발견 25건 중 18건이 앞 수정 라운드에서 생긴 것이어서다.
1차(302d3a5..f1734913): DR-01~05를 고쳤다. DR-06은 남겼다(아래).
2차(f1734913..59b2ccb5): FR-01을 고쳤다. FR-02는 계약 문서에 규칙 한 줄을 더했다. FR-03~05는 기록만 하고 고치지 않았다.
큰 묶음:
결과 불명 재전송(03-01, DR-01, FR-01):
KEYED 쓰기의 결과가 불명일 때, 같은 키 재전송이 쓰기 전에 거절되면(429·401·503 RATE_LIMIT_*, 보내기 전 실패) 다음 저장이 새 키로 나갔다. 이제 결과 불명 상태와 키를 지킨다.
결과 불명을 푸는 경우는 셋뿐이다. 성공, 짝 백엔드 표의 400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID.
나머지 경우에는 결과 불명이 남는다. 화면의 확인 버튼으로 빠져나간다.
조용히 줄던 검사:
제거 드릴 사본에서 테스트가 말없이 빠지던 것(10-01, 12-01)
RUN_OUTPUT_ROOT가 있으면 옛 빌드로 판정하던 check:bundle(12-02)
spec 본문의 기능 ID 잔여(16-01, DR-02)
a11y notChecked 분류(11-01)
SW marker 상한 test(06-02)
스키마 정책(07-02)
문서 어긋남: CHANGELOG BREAKING 1~3단계의 설명(14-01), 계약 문서 bulk·rate-limit 문장(07-01, 03-02), 저장소 문서(05-01), 초기 파일 수(1103/15-02), D7 커밋의 옛 해시(14-02).
그 밖: modal 가림막이 스크롤바 띠까지 덮는다(08-03), 다시 마운트한 폼이 결과를 보인다(08-01, DR-03), live probe가 워커 스크립트 redirect를 거절한다(06-01), 업로드 거절에 traceId를 싣는다(01-01).
고른 방법과 버린 대안
메인 세션 결정 셋은 README 16.2절에 있다. 셋 다 소유자가 뒤집을 수 있다.
D10: 결과 불명을 훅에서 지킨다.
버린 대안 1: rate-limit 503을 다시 MAYBE_APPLIED로 읽기. 1105/03-02를 되돌리게 되고, 429·401은 그대로 남는다.
버린 대안 2: 생성 페이지만 고치기. 참조 폼과 훅을 직접 부르는 코드가 남는다.
D10 보완 2: 재전송의 거절로 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다. 기능 mapProblem이 붙인 kind는 믿지 않는다.
이유: 처음에는 kind로 풀었다. 그러자 기능이 선언한 code와 422 IDEMPOTENT_REQUEST_MISMATCH까지 결과 불명이 풀렸다(FR-01).
버린 대안: 기능이 descriptor에 "매번 같은 거절"을 선언하게 하기. 계약 타입이 바뀐다.
D9: 초기 JS 예산 206,848 B를 유지한다.
근거: 드릴 실측 205,465 B에 기능 하나 상한 1 KiB를 더하고 KiB 단위로 올린 값이다.
되돌림: 드릴 실측이 204,800 B 이하가 되면 같은 규칙으로 내린다.
규칙은 문서에만 있다. 규칙 밖으로 바꾸는 것을 막는 테스트는 없다.
DR-02: spec 본문 검색은 대소문자를 구분하고, -가 든 이름만 찾는다.
이유: status·reports 같은 흔한 한 단어 ID에서 템플릿 자신의 spec이 잔여로 잡혔다.
대가: 한 단어 ID만 적은 spec은 잡지 못한다. 그래도 bbde570(spec 본문을 아예 보지 않음)보다 좁지는 않다.
이력은 고치지 않았다.
14-02: 287dc6f 본문의 옛 해시 대신 맞는 해시를 1105 README D7 행에 적었다.
DR-06: 04-02 커밋 6f06e770에 !가 없다. 대신 CHANGELOG 새 절 "먼저 할 일" 6단계에 BREAKING으로 적었다.
반복을 여기서 끝낸다. FR-01 수정 뒤에는 diff 리뷰를 다시 하지 않았다. 이 수정은 결과 불명을 푸는 경우를 줄이기만 하고, 빠져나가는 길(확인 버튼)은 테스트로 고정했다.
결과 불명 뒤 재전송이 거절되면 폼은 "나중에 같은 요청으로 다시 보내라"고 안내한다. 새 키로 저장하지 않는다.
참조 기능의 422는 결과 불명으로 남는다.
크기가 커밋 규칙 5.1절 기준을 넘는다.
bbde570 대비 104파일, +7,272 / −455줄, 커밋 54개(merge 13개 포함)다. 리뷰 기록 17파일·3,900줄을 빼면 88파일, +3,372 / −455줄이다.
나누지 않은 이유: 합칠 때 생긴 어긋남(16.3절)을 합친 커밋에서 고쳤고, merge 게이트는 합친 끝에서만 돌렸다.
시각 골든: compact 골든 한 장이 바뀌었다(08-03, x 375~390 띠). :has()를 모르는 브라우저에는 띠가 남는다. Firefox·WebKit은 보지 않았다.
초기 JS 기록: 합친 빌드로 다시 적었다(204,111 → 204,193 B, 초기 파일 27개 그대로).
남긴 것:
FR-02(시간·DB를 읽는 검증. 계약 문서 규칙으로 막음)
FR-03(다시 마운트한 폼의 재전송이 화면 값을 제출 값으로 둠. 서버 데이터는 바뀌지 않음)
FR-04·FR-05, DR-06
01-01 백엔드 요청(Fileserver 거절 이유)
이월 결정 대기 D1~D3, D8, D11
검증
1141969에서 merge 단계 게이트 14개를 corepack pnpm ci:gate FE-GATE-NNN으로 하나씩 돌렸다.
어디서: desktop. 다른 세션과 공유하는 잠금 하나 안에서 checkout부터 복원까지 한 번에 돌렸다.
env: workflow와 같다. CI=true, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE(형식만 맞춘 가짜 digest).
게이트
결과
FE-GATE-001~012, 020
모두 한 번에 통과. 020은 1,254초(생성 기능 드릴 포함), 008은 198초(e2e·capability·storybook·visual)
FE-GATE-013
사전 점검에서 실패. PR #5·#7과 같은 호스트 제약이고, "this host does not allow unprivileged user and network namespaces"를 낸다
FE-GATE-013의 사전 점검 뒤 부분은 같은 env에 SOURCE_DATE_EPOCH를 더해 따로 돌렸다.
tests/system: 115건 중 97건 통과. 실패 18건은 모두 ci-artifact-contract.test.ts의 provider 샌드박스 테스트다. 원인은 bwrap이 loopback을 만들지 못한 것(RTM_NEWADDR)이다. PR #7 끝과 같은 파일에서 같은 수가 실패했다.
나머지 명령 7개는 모두 통과했다: verify:reproducible-build, build:release-candidate, verify:local-evidence, supply-chain fixture 둘, security fixture, check:browser-security.
실행 뒤 작업 트리는 깨끗했다.
DR·FR 수정 뒤의 FE-GATE-020과 e2e(FE-GATE-008)는 수정 세션이 돌리지 않았다. 위 merge 게이트 실행이 최종 head에서 그 둘을 덮는다.
수정 세션이 돌린 것(desktop, README 16.5절):
RED 15개와 DR·FR RED: 모두 기대한 테스트에서 기대한 이유로 실패했다.
GREEN: 모두 통과했다.
변이·실험: 모두 고친 커밋에서 잡혔다. 03-R1 재현에서는 키가 모두 key-1이다.
f1734913: FE-GATE-020·012(CI env), 빠른 검사 10개, unit 3,077 · component 284 · integration 214 · contract 24 · runtime-schema 60 · visual 7.
59b2ccb5: coverage 4,143(risk 418/418).
최종 코드 트리 57ffcc96: unit 3,090 · component 296 · features 127, coverage 4,146.
해시 대조(14-02 완료 기준, 16.6절): CHANGELOG 새 절 36개와 범위 커밋 본문의 이 repo 해시 26개가 모두 브랜치 끝의 조상이다.
커밋 54개: 제목은 모두 72자 이하다. AI 꼬리말은 0건이다. merge가 아닌 커밋은 모두 Refs:가 있다.
실행하지 않은 것:
실제 Gitea runner
user namespace를 허용하는 호스트에서 provider 샌드박스 테스트 18건
두 다운스트림에 BREAKING 단계를 적용한 뒤의 게이트
실제 백엔드 연동
리뷰어가 볼 곳
합친 커밋 단위로 보면 된다(git log --first-parent 302d3a5..).
합친 커밋
영역
파일
추가 줄
c89f8b5
HTTP 판정·폼(03-01 D10, 03-02, 03-03, 14-01)
18
623
37f1f87
캐시·업로드
11
156
5e31faa
realtime
6
348
6f15ac8
Service Worker·호스팅
5
81
95a090e
테스트 기반
19
636
0c6548a
검사 범위
11
317
90e485f
release 게이트
6
87
68fc796
문서·CHANGELOG
6
37
81ff05e
화면·테마
8
239
591dd31
diff 리뷰 폼(DR-01, DR-03)
9
432
3abe28e
diff 리뷰 검사(DR-02, DR-04, DR-05)
7
158
8b8b6c5
마지막 리뷰(FR-01, FR-02)
7
109
특히 볼 곳:
src/contracts/errors.ts의 isRefusedOnEveryAttempt, src/presentation/adapters/query/application-query.ts, src/presentation/forms/use-app-form.ts: 결과 불명 재전송 규칙
## 무엇을, 왜
2026-11-06 5라운드 리뷰 기록과, 그 발견을 고친 마지막 수정 라운드다. PR #7 위에 쌓았다. merge 순서는 #5 → #7 → 이 PR이다. base는 main이라, 앞의 둘이 merge되기 전에는 그 커밋도 diff에 보인다.
- **리뷰 기록** (`302d3a5`): `docs/reviews/2026-11-06-maturity-review/`. 기준은 `bbde570`(PR #7 끝)이다. 새 발견은 25건이다(High 0, P1 0, Medium 1, Low 24). 앞 라운드는 1105가 48건(P1 3), 1103이 88건(High 2, P1 12)이었다. 새 High·P1이 0건이라 반복의 멈춤 기준 중 리뷰 부분을 채웠다. 그래서 이번 라운드의 Medium·Low를 고치고 반복을 끝낸다.
- **수정:** 새 발견 25건 중 24건을 고쳤다. 01-01은 일부만 고치고 백엔드로 넘겼다. 1103/15-02의 재발도 고쳤다. 발견별 상태·커밋·남은 것은 README 16.4절에 있다.
- **수정 diff 리뷰를 두 번 했다.** 5라운드 발견 25건 중 18건이 앞 수정 라운드에서 생긴 것이어서다.
- 1차(`302d3a5..f1734913`): DR-01~05를 고쳤다. DR-06은 남겼다(아래).
- 2차(`f1734913..59b2ccb5`): FR-01을 고쳤다. FR-02는 계약 문서에 규칙 한 줄을 더했다. FR-03~05는 기록만 하고 고치지 않았다.
큰 묶음:
- **결과 불명 재전송(03-01, DR-01, FR-01):**
- KEYED 쓰기의 결과가 불명일 때, 같은 키 재전송이 쓰기 전에 거절되면(429·401·503 `RATE_LIMIT_*`, 보내기 전 실패) 다음 저장이 새 키로 나갔다. 이제 결과 불명 상태와 키를 지킨다.
- 결과 불명을 푸는 경우는 셋뿐이다. 성공, 짝 백엔드 표의 400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID`.
- 나머지 경우에는 결과 불명이 남는다. 화면의 확인 버튼으로 빠져나간다.
- **조용히 줄던 검사:**
- 제거 드릴 사본에서 테스트가 말없이 빠지던 것(10-01, 12-01)
- `RUN_OUTPUT_ROOT`가 있으면 옛 빌드로 판정하던 `check:bundle`(12-02)
- spec 본문의 기능 ID 잔여(16-01, DR-02)
- a11y `notChecked` 분류(11-01)
- SW marker 상한 test(06-02)
- 스키마 정책(07-02)
- **문서 어긋남:** CHANGELOG BREAKING 1~3단계의 설명(14-01), 계약 문서 bulk·rate-limit 문장(07-01, 03-02), 저장소 문서(05-01), 초기 파일 수(1103/15-02), D7 커밋의 옛 해시(14-02).
- **그 밖:** modal 가림막이 스크롤바 띠까지 덮는다(08-03), 다시 마운트한 폼이 결과를 보인다(08-01, DR-03), live probe가 워커 스크립트 redirect를 거절한다(06-01), 업로드 거절에 traceId를 싣는다(01-01).
## 고른 방법과 버린 대안
메인 세션 결정 셋은 README 16.2절에 있다. 셋 다 소유자가 뒤집을 수 있다.
- **D10: 결과 불명을 훅에서 지킨다.**
- 버린 대안 1: rate-limit 503을 다시 `MAYBE_APPLIED`로 읽기. 1105/03-02를 되돌리게 되고, 429·401은 그대로 남는다.
- 버린 대안 2: 생성 페이지만 고치기. 참조 폼과 훅을 직접 부르는 코드가 남는다.
- **D10 보완 2:** 재전송의 거절로 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다. 기능 `mapProblem`이 붙인 kind는 믿지 않는다.
- 이유: 처음에는 kind로 풀었다. 그러자 기능이 선언한 code와 422 `IDEMPOTENT_REQUEST_MISMATCH`까지 결과 불명이 풀렸다(FR-01).
- 버린 대안: 기능이 descriptor에 "매번 같은 거절"을 선언하게 하기. 계약 타입이 바뀐다.
- **D9: 초기 JS 예산 206,848 B를 유지한다.**
- 근거: 드릴 실측 205,465 B에 기능 하나 상한 1 KiB를 더하고 KiB 단위로 올린 값이다.
- 되돌림: 드릴 실측이 204,800 B 이하가 되면 같은 규칙으로 내린다.
- 규칙은 문서에만 있다. 규칙 밖으로 바꾸는 것을 막는 테스트는 없다.
- **DR-02:** spec 본문 검색은 대소문자를 구분하고, `-`가 든 이름만 찾는다.
- 이유: `status`·`reports` 같은 흔한 한 단어 ID에서 템플릿 자신의 spec이 잔여로 잡혔다.
- 대가: 한 단어 ID만 적은 spec은 잡지 못한다. 그래도 `bbde570`(spec 본문을 아예 보지 않음)보다 좁지는 않다.
- **이력은 고치지 않았다.**
- 14-02: `287dc6f` 본문의 옛 해시 대신 맞는 해시를 1105 README D7 행에 적었다.
- DR-06: 04-02 커밋 `6f06e770`에 `!`가 없다. 대신 CHANGELOG 새 절 "먼저 할 일" 6단계에 BREAKING으로 적었다.
- **반복을 여기서 끝낸다.** FR-01 수정 뒤에는 diff 리뷰를 다시 하지 않았다. 이 수정은 결과 불명을 푸는 경우를 줄이기만 하고, 빠져나가는 길(확인 버튼)은 테스트로 고정했다.
## 위험과 영향
- **BREAKING(CHANGELOG 새 절 "먼저 할 일" 1~6단계):**
- 1. HTTP 스키마 행에 `direction`·`unknownFieldPolicy`가 필요하다(07-02). 빠지면 다운스트림 `test:unit`이 실패한다.
- 2. i18n 키 `form.resendLater`가 필요하다.
- 3. dialog 가림막 토큰 3개가 필요하다.
- 4. IDEMPOTENT 쓰기에 재전송 버튼이 그려진다.
- 5. CI 기준선을 다시 기록해야 한다.
- 6. `createBoundedPollCoordinator`가 descriptor 타입을 추론한다(DR-06).
- **동작 변경:**
- 결과 불명 뒤 재전송이 거절되면 폼은 "나중에 같은 요청으로 다시 보내라"고 안내한다. 새 키로 저장하지 않는다.
- 참조 기능의 422는 결과 불명으로 남는다.
- **크기가 커밋 규칙 5.1절 기준을 넘는다.**
- `bbde570` 대비 104파일, +7,272 / −455줄, 커밋 54개(merge 13개 포함)다. 리뷰 기록 17파일·3,900줄을 빼면 88파일, +3,372 / −455줄이다.
- 나누지 않은 이유: 합칠 때 생긴 어긋남(16.3절)을 합친 커밋에서 고쳤고, merge 게이트는 합친 끝에서만 돌렸다.
- **시각 골든:** compact 골든 한 장이 바뀌었다(08-03, x 375~390 띠). `:has()`를 모르는 브라우저에는 띠가 남는다. Firefox·WebKit은 보지 않았다.
- **초기 JS 기록:** 합친 빌드로 다시 적었다(204,111 → 204,193 B, 초기 파일 27개 그대로).
- **남긴 것:**
- FR-02(시간·DB를 읽는 검증. 계약 문서 규칙으로 막음)
- FR-03(다시 마운트한 폼의 재전송이 화면 값을 제출 값으로 둠. 서버 데이터는 바뀌지 않음)
- FR-04·FR-05, DR-06
- 01-01 백엔드 요청(Fileserver 거절 이유)
- 이월 결정 대기 D1~D3, D8, D11
## 검증
`1141969`에서 merge 단계 게이트 14개를 `corepack pnpm ci:gate FE-GATE-NNN`으로 하나씩 돌렸다.
- 어디서: desktop. 다른 세션과 공유하는 잠금 하나 안에서 checkout부터 복원까지 한 번에 돌렸다.
- env: workflow와 같다. `CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`(형식만 맞춘 가짜 digest).
| 게이트 | 결과 |
|---|---|
| FE-GATE-001~012, 020 | 모두 한 번에 통과. 020은 1,254초(생성 기능 드릴 포함), 008은 198초(e2e·capability·storybook·visual) |
| FE-GATE-013 | 사전 점검에서 실패. PR #5·#7과 같은 호스트 제약이고, "this host does not allow unprivileged user and network namespaces"를 낸다 |
FE-GATE-013의 사전 점검 뒤 부분은 같은 env에 `SOURCE_DATE_EPOCH`를 더해 따로 돌렸다.
- `tests/system`: 115건 중 97건 통과. 실패 18건은 모두 `ci-artifact-contract.test.ts`의 provider 샌드박스 테스트다. 원인은 bwrap이 loopback을 만들지 못한 것(`RTM_NEWADDR`)이다. PR #7 끝과 같은 파일에서 같은 수가 실패했다.
- 나머지 명령 7개는 모두 통과했다: `verify:reproducible-build`, `build:release-candidate`, `verify:local-evidence`, supply-chain fixture 둘, security fixture, `check:browser-security`.
- 실행 뒤 작업 트리는 깨끗했다.
- DR·FR 수정 뒤의 FE-GATE-020과 e2e(FE-GATE-008)는 수정 세션이 돌리지 않았다. 위 merge 게이트 실행이 최종 head에서 그 둘을 덮는다.
수정 세션이 돌린 것(desktop, README 16.5절):
- RED 15개와 DR·FR RED: 모두 기대한 테스트에서 기대한 이유로 실패했다.
- GREEN: 모두 통과했다.
- 변이·실험: 모두 고친 커밋에서 잡혔다. 03-R1 재현에서는 키가 모두 `key-1`이다.
- `f1734913`: FE-GATE-020·012(CI env), 빠른 검사 10개, unit 3,077 · component 284 · integration 214 · contract 24 · runtime-schema 60 · visual 7.
- `59b2ccb5`: coverage 4,143(risk 418/418).
- 최종 코드 트리 `57ffcc96`: unit 3,090 · component 296 · features 127, coverage 4,146.
- 해시 대조(14-02 완료 기준, 16.6절): CHANGELOG 새 절 36개와 범위 커밋 본문의 이 repo 해시 26개가 모두 브랜치 끝의 조상이다.
- 커밋 54개: 제목은 모두 72자 이하다. AI 꼬리말은 0건이다. merge가 아닌 커밋은 모두 `Refs:`가 있다.
**실행하지 않은 것:**
- 실제 Gitea runner
- user namespace를 허용하는 호스트에서 provider 샌드박스 테스트 18건
- 두 다운스트림에 BREAKING 단계를 적용한 뒤의 게이트
- 실제 백엔드 연동
## 리뷰어가 볼 곳
합친 커밋 단위로 보면 된다(`git log --first-parent 302d3a5..`).
| 합친 커밋 | 영역 | 파일 | 추가 줄 |
|---|---|---|---|
| `c89f8b5` | HTTP 판정·폼(03-01 D10, 03-02, 03-03, 14-01) | 18 | 623 |
| `37f1f87` | 캐시·업로드 | 11 | 156 |
| `5e31faa` | realtime | 6 | 348 |
| `6f15ac8` | Service Worker·호스팅 | 5 | 81 |
| `95a090e` | 테스트 기반 | 19 | 636 |
| `0c6548a` | 검사 범위 | 11 | 317 |
| `90e485f` | release 게이트 | 6 | 87 |
| `68fc796` | 문서·CHANGELOG | 6 | 37 |
| `81ff05e` | 화면·테마 | 8 | 239 |
| `591dd31` | diff 리뷰 폼(DR-01, DR-03) | 9 | 432 |
| `3abe28e` | diff 리뷰 검사(DR-02, DR-04, DR-05) | 7 | 158 |
| `8b8b6c5` | 마지막 리뷰(FR-01, FR-02) | 7 | 109 |
특히 볼 곳:
- `src/contracts/errors.ts`의 `isRefusedOnEveryAttempt`, `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`: 결과 불명 재전송 규칙
- `scripts/lib/feature-residue.ts`: 제거 드릴의 spec 본문 검색(DR-02의 `-` 필터)
- `CHANGELOG.md` 새 미출시 절의 "먼저 할 일 (BREAKING)" 1~6단계
- 리뷰 기록은 `docs/reviews/2026-11-06-maturity-review/README.md`부터 읽는다. 16절이 조치다.
## 관련
- PR #5, PR #7: 이 PR은 그 위에 쌓였다
- PR #6: 개선 작업 매뉴얼. 소유자 결정으로 재작성 중이라 merge하지 않는다
- `docs/reviews/2026-11-06-maturity-review/README.md` 16절(조치), 16.2절(결정)
2026-11-03 리뷰의 조치가 main(409d72e)에 들어간 뒤 전체를 다시 봐야
한다. 지난 README 14.4절의 상태 판정("그 밖의 81건 고침")과, 조치가
검사를 약하게 했는지는 아무도 확인하지 않았다.
가이드 기준으로 16개 영역을 다시 리뷰했다. 기준은 8a44226(= main
409d72e 트리)이다. desktop에서 merge 단계 14개(workflow env)와
CLAUDE.md 게이트 목록을 직접 돌렸다. 실험은 게이트가 끝난 뒤 78항목을
한 묶음으로 하나씩 돌렸고, 항목마다 checkout을 기준 커밋으로 되돌렸다.
처음에는 영역마다 따로 실행했으나 공유 잠금에 30여 건이 줄을 서서
취소했다(README 11.4절).
결과: 새 발견 48건(High 0, Medium 11, Low 37 / P1 3, P2 15, P3 30).
P1은 09-01, 12-01, 13-01. 지난 96건은 고쳐짐 74, 일부 22이고,
14.4절이 고침이라 한 13건을 일부로 바로잡았다. merge 게이트는 13/14
통과, FE-GATE-013은 호스트 user namespace 제한으로 실패한다.
위험·한계: 실제 Gitea 러너와 짝 백엔드 연동은 확인하지 못했다(README
8절). 리뷰라 코드는 고치지 않았다. 영역 문서의 실행 기록 일부는
리뷰 세션 scratchpad 경로를 가리킨다.
검증: desktop에서 이 커밋으로 documentation-readiness,
deletable-history-documents, changelog-review-ids 테스트와
verify:documentation(옆 백엔드 checkout 없이)을 돌렸다.
Refs: docs/reviews/2026-11-05-maturity-review/README.md
문제
실행기는 호출자·interaction·scope 세 signal에 abort listener를 달고
끝날 때 셋을 모두 지운다(src/adapters/http/http-execution-v3.ts:662-664).
listener 정리 테스트는 호출자와 scope signal만 감시해서, interaction
signal 쪽 제거 줄(:663)을 지운 변이 R2b가 107파일 995개를 모두
통과했다. 한 interaction 안에서 요청을 여러 번 보내면 요청마다
listener 하나(lifetime controller를 잡은 closure)가 interaction
마감까지 남는다.
고른 방법과 버린 대안
- 같은 테스트(tests/unit/http-execution-v3.test.ts)에
createExecutionContext로 만든 interaction을 넘기고, 그
cancellation.signal도 감시 목록에 넣는다.
- 끝나는 경우에 "interaction cancel"을 더한다. interaction 취소는
호출자 abort와 같은 forwarder를 타지만 listener를 단 signal이 달라서
따로 본다.
- 별도 테스트를 새로 만드는 안은 버렸다. 세 signal은 같은 정리 함수가
지우므로 한 테스트에서 함께 보는 편이 규칙과 맞다.
위험·한계
- 테스트만 바꿨다. 실행기 코드는 그대로다. 실제 누수량은 재지 않는다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts
- 변이 R2b(:663 제거)를 넣으면 세 경우 모두 "removes the listeners it
added to the caller, interaction and scope signals after …"가
실패해야 한다.
Refs: 1105/10-02
문제: 0929/04-01 규칙은 "환경이 online이면 transport가 낸 OFFLINE도
online 이벤트를 기다리지 않고 backoff로 재시도한다"이다
(reconnect-coordinator.ts의 RealtimeReconnectEnvironment 주석, 설계 5.3).
이 규칙을 막던 두 테스트는 SSE fetch·reader 거절이 OFFLINE이던 것을
이용했다. af00067(1103/04-04)이 SSE 거절을 PROVIDER_UNAVAILABLE로 바꾼 뒤
두 테스트는 그 kind의 재시도만 본다. 4d27b20이 지운 requireOnline() 두
줄을 되살리는 변이(MR1)에서 realtime 테스트가 모두 통과했다(리뷰 04-R4).
고른 방법: 조합 코드가 만든 transport로 그 경로를 직접 지나는 테스트
둘을 더한다. 환경은 계속 online이다.
- attempt가 OFFLINE/CONNECT/retryable로 실패한다 → 3회 시도, backoff
[50, 100], OFFLINE retryable로 끝난다. 관측 순서도 고정한다.
- 세션이 열린 뒤 OFFLINE/RECEIVE/retryable로 닫힌다 → 3회 시도,
OFFLINE retryable로 끝난다.
리뷰 대조 C1·C2와 같은 입력이고, `as never` 없이 파일의 도우미를 쓴다.
버린 대안: SSE 테스트 기대값을 OFFLINE으로 되돌리기. 템플릿 SSE는 이제
OFFLINE을 내지 않으므로 실제 동작과 다른 테스트가 된다.
위험·한계: 테스트만 더했다. 동작은 바뀌지 않는다. 그래서 RED(부모
코드)에서도 이 테스트는 통과한다. 결함을 보이는 방법은 변이 MR1이다.
검증: desktop batch에서 확인.
- GREEN: node scripts/run-vitest.ts run tests/unit/realtime/
- 변이 MR1(reconnect-coordinator.ts의 두 retry 분기 뒤 OFFLINE이면
requireOnline()): 새 두 테스트가 attempts 1, result null로 실패해야 한다
Refs: 1105/04-01
문제: bounded poll은 `execute`의 throw를 PROVIDER_UNAVAILABLE/retryable로
바꿔 lease 안에서 다시 부른다(af00067). 설계 9.2가 권하는 조합은
`execute` 안에서 V3 실행기를 부르는 것이고, 실행기는 fetch 거절을 던지지
않고 NETWORK_FAILURE 결과로 돌려준다. 그래서 그 조합에서 throw는 결과
매핑·디코딩 같은 조합 코드 결함이다. 지금은 그 결함이 maxAttempts번의
요청과 ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE, 끝으로
POLL_BUDGET_EXHAUSTED가 되어 서버 장애로 보인다. 원인 예외는 남지 않는다.
고른 방법: 리뷰 04-02의 선택지 (b). throw를 모양이 틀린 결과와 같은
계약 위반으로 본다. coordinator는 이미 `parseAttemptResult`가 거절한
결과를 재시도 없이 PROTOCOL_MISMATCH로 끝낸다. throw도 그 길로 보낸다.
lease 자신의 abort로 생긴 throw는 지금처럼 abort의 이유(ABORTED,
OFFLINE, 예산 소진 등)로 끝난다. `execute` 타입 주석, 설계 9.2와 13.1의
PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행을 같이 고쳤다.
버린 대안:
- (c) 주석과 13.1에만 "throw는 서버 장애로 재시도된다"를 적기. 완료
기준은 "결과를 보고 조합 결함과 서버 장애를 구분한다"인데, (c)는 읽는
사람만 알고 결과는 그대로라 구분할 수 없다.
- 관측에 throw 표시 칸을 더하기. 닫힌 관측 어휘를 넓히고, 결과 kind는
여전히 서버 장애다.
위험·한계:
- 배럴로 공개된 bounded poll의 결과가 바뀐다. repo 안 소비자는 테스트뿐이다.
- `fetch`를 직접 부르는 조합은 네트워크 실패를 결과로 바꾸지 않으면 첫
거절에서 lease가 끝난다. 설계가 권하지 않는 조합이고, 타입 주석과
9.2가 "실패도 결과로 돌려준다"를 적는다.
- reconnect coordinator는 던지는 `attempt`를 계속 PROVIDER_UNAVAILABLE로
재시도한다. 그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번
범위 밖이다.
- CHANGELOG.md 미출시 [계약] 행의 "poll은 던지는 execute도 lease 안에서
다시 시도한다"는 이 커밋과 맞지 않는다. CHANGELOG는 오케스트레이터가
고친다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "ends the lease with PROTOCOL_MISMATCH for an async execute that
rejects"·"... throws before returning"가 옛 코드에서 execute 3회,
POLL_BUDGET_EXHAUSTED로 실패한다. "keeps ABORTED ..."는 양쪽에서 통과한다
(보존 조건).
BREAKING CHANGE: createBoundedPollCoordinator의 `execute`가 던지면(abort로
생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가
끝난다. 전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다.
네트워크 실패를 throw로 내던 `execute`는 그것을 retryable
PROVIDER_UNAVAILABLE 결과로 바꿔 돌려준다.
Refs: 1105/04-02
문제: bounded poll은 생성 때 descriptor의 `retryBudget`이 0인지 본다
(1103/04-01). 그런데 `execute` 입력에는 descriptor가 없다. 조합 코드는
실행기에 넘길 descriptor를 스스로 골라야 하고, 같은 경로의 기본 GET
(`retryBudget: 2`)을 넘겨도 막는 것이 없다. 리뷰 04-R1 P5에서 poll 3회가
요청 9회, 실행기 대기 6번이었다. 타입 주석과 설계 9.2가 "같은 객체를
넘긴다"고 적을 뿐이다.
고른 방법: coordinator가 생성 때 검사한 그 객체를 모든 `execute` 호출에
`input.operation`으로 넘긴다. 생성 때 한 번 잡아 두므로 나중에
dependencies 객체가 바뀌어도 검사한 객체가 간다. 조합 코드는 클로저의
descriptor 대신 이것을 실행기에 넘기면 된다. 테스트의 V3 조합도 그렇게
바꿨다. 타입 주석(`bounded-polling.ts`, `bounded-poll-coordinator.ts`)과
설계 9.2를 고쳤다.
버린 대안: coordinator가 실행기를 직접 받아 부르기. 실행기 타입은
`adapters/http`에 있어 realtime 어댑터가 import할 수 없다(adapter 사이
import 금지, kernel 예외 아님). 구조 타입을 새로 두면 결과 매핑까지
coordinator가 정해야 해서 공개 모양이 크게 바뀐다.
위험·한계: 일부만 닫는다. 조합 코드가 `input.operation`을 무시하고 다른
descriptor를 실행기에 넘기면 여전히 attempt마다 요청이 최대 3번이다.
설계 9.2가 이 남은 틈을 적는다. 입력 칸을 더한 것이라 기존 `execute`는
그대로 돈다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "hands every execute call the descriptor it checked at creation"
(받은 값이 undefined), "sends one request per poll attempt with a poll
descriptor"(실행기에 undefined가 가서 요청 0개, PROTOCOL_MISMATCH)가
옛 코드에서 실패한다.
Refs: 1103/04-01
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02 탐침)는 저장소
복사본의 src/contracts/product-contracts.ts와
src/bootstrap/product-composition.ts를 탐침 내용으로 통째로 바꿔 쓴다.
탐침의 composeProduct는 typecheckProbeSettings 하나만 돌려준다. 제품이
자기 capability를 product-composition.ts에서 만들고 자기 기능의 needs에
적으면, 복사본에서는 그 값이 사라져 app 프로그램이
src/bootstrap/runtime-adapters.ts에서 TS2741로 실패한다. memento와
tech-log 모두 제품 capability를 쓰므로, 동기화 직후 FE-GATE-005가 코드와
무관하게 실패한다(리뷰 실험 09-probe-downstream).
고른 방법
- 탐침은 복사본의 product-contracts.ts·product-composition.ts를 같은
폴더의 typecheck-probe-product-contracts.ts·
typecheck-probe-product-composition.ts로 옮긴다. 새 파일은 옮긴 모듈을
export *로 다시 내보낸다. 그리고 런타임 설정 필드, env 행,
composeProduct 결과와 그 capabilities를 펼친 뒤 탐침의 키·행·capability만
더한다. 인증 프로필, credential provider, 선택 칸, session owner, 제품이
더한 다른 export는 그대로 남는다.
- capability 타입은 저장소가 아니라 복사본의 product-capabilities.ts 끝에
덧붙인다.
- 같은 함수로 "제품 capability를 기능에 주는 다운스트림"을 먼저 만들고 그
위에 탐침을 올리는 케이스를 더했다(describe 1105/09-01). 다운스트림
흉내도 덧붙이는 방식이라, 실제 다운스트림에서 이 테스트를 돌려도 그
제품의 파일을 지우지 않는다. 이름은 예약 접두사
typecheck-probe-downstream-*를 쓴다.
- 예약 이름 검사는 기능 폴더에 더해 context 폴더와 옮길 파일 이름도 본다.
버린 대안
- 제품 파일이 출하 상태가 아니면 탐침을 건너뛴다(리뷰의 (나)). 다운스트림
상태의 타입 경로 확인을 잃고, 건너뛰기로 검사를 약하게 한다.
- 다운스트림 흉내를 제품 파일 전체를 새로 쓰는 방식으로 만든다. 실제
다운스트림에서 이 테스트를 돌리면 그 제품의 capability를 지워 같은
TS2741이 다시 난다.
위험·한계
- 제품 파일의 export 이름(composeProduct, composeProductSessionOwner,
PRODUCT_*)에 기댄다. 템플릿이 그 이름을 import하므로 계약이다.
- credentialProviders와 인증 프로필은 Record라 빠져도 tsc가 모른다.
펼쳐서 남기지만 테스트로 증명하지는 않는다.
- 탐침 context는 여전히 소유 앱을 template-app으로 고정한다. 앱 id를
바꾼 제품에서는 생성기가 멈출 수 있다(리뷰 09-01의 남은 가정, 실행
안 함). 이 커밋 범위 밖이다.
- 케이스가 하나 늘어 이 파일의 tsc 실행이 3회에서 6회가 된다. 케이스별
제한 시간 120초는 그대로다.
- 결함이 테스트 파일 안의 탐침에 있어서, 표준 RED 구성(커밋의 테스트 +
부모의 비테스트 파일)은 GREEN과 같다. RED는 커밋 위에 탐침을 부모처럼
덮어쓰게 되돌리는 patch를 적용해 본다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/product-extension-typecheck.test.ts, check:types, lint.
RED patch를 적용하면 1105/09-01 케이스만 TS2741로 실패해야 한다.
- 이 노트북에서는 실행하지 않았다.
Refs: 1105/09-01
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번
나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에
reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에
"(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다.
기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을
보지 못했다.
고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지
않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는
지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError
message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류,
테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제).
위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금
reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을
실제 출력에 맞췄다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts
새 테스트는 실제 ContractContributionError를 던지는 source로
check:registries를 돌려 원인이 한 번만 나오는지 본다.
Refs: 1105/09-03
문제: VD-28은 poll 규칙을 지운 V2 실행 예산으로 적는다. "operation은
registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은
`maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`"이다.
설계 3절도 "REST `QUERY` operation"과 "REST operation registry"라고 적는다.
V2 실행 경로는 2026-11-03에 지웠고(VD-23 상태 줄), 지금 규칙은 V3
descriptor의 `frontend.retryBudget: 0`이다(설계 9.2, 1103/04-01).
a65df74가 9.2만 고쳤다.
고른 방법: VD-28 1절 끝 문장과 11절 목록, 설계 3절 두 항목을 지금
규칙으로 바꾼다. GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor, `retryBudget`
0이 아니면 생성 때 거절, 실행기가 그 칸에서 재시도 상한을 읽어 한
attempt가 요청 하나라는 것이다. 상세는 9.2를 가리킨다.
설계 3절의 "REST operation registry의 credential, conditional request, ...
재사용"은 주어를 V3 실행기로 바꾸면서 conditional request를 뺐다. V3
실행기에는 ETag 처리가 없고(`http-execution-v3.ts`에 If-None-Match 없음),
VD-23 상태 줄이 conditional execution을 `DESIGNED_NOT_IMPLEMENTED`로 적는다.
위험·한계: 문서만 바꿨다. VD-28 11절의 "ETag/`If-None-Match` 또는 server
cursor 사용" 목표 줄은 결정 내용이라 그대로 두었다.
검증: 문서 전용이라 RED 없음. desktop batch에서 확인.
- pnpm verify:documentation
- `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" --
docs/architecture/decisions/VD-28*` 0건(로컬 확인)
Refs: 1105/04-03
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.
고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
번 띄운다. 실패하면 "this host does not allow unprivileged user and
network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
두었다.
버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
없다. 주석이 지금 가능한 가장 작은 표시다.
위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
제품 overlay는 그대로 통과한다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지
Refs: 1105/12-01, 1105/11-02
문제
1103 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기댄다. 샘플을
지우면 두 테스트가 사라지거나 비어도 test:all과 제거 드릴이 통과한다.
- MAX_RETRY_ATTEMPTS가 실행기에 닿는다: 유일한 테스트가
tests/features/reference-feature/reference-runtime-composition.test.ts
에 있다. createRuntimeAdapters는 설치된 기능의 HTTP로만 실행기에 닿아,
기능이 없으면 시험할 길이 없다. REQUEST_TIMEOUT_MS도 같은 모양이다.
- 복구 중인 세션은 보호 라우트에서 기다린다:
tests/unit/navigation-policy.test.ts는 설치된 보호 라우트를 돌며
단언하는데, 보호 라우트는 모두 샘플 것이라 샘플을 지우면 반복이 0번이다.
고른 방법과 버린 대안
- src/bootstrap/runtime-adapters.ts: 설정 두 값과 auth profile 표로
실행기를 만드는 부분을 createRuntimeContractHttpExecutor로 뺀다.
조립 루트는 이 함수로만 실행기를 만든다. tests/unit/runtime-adapters
.test.ts가 테스트 계약(TEST_LIST, 재시도 예산 2)으로 MAX_RETRY_ATTEMPTS
0·1·2에 1·2·3번 나가는지, REQUEST_TIMEOUT_MS 5가 10초 계약을 5ms에
끊는지 본다. 이 파일은 이미 제거 드릴의 공통 테스트 목록에 있다.
- tests/unit/session-route-access.test.ts(새 파일): component 테스트와
같은 방법으로 생성 index를 mock해 tests/helpers/fixture-feature.tsx를
설치하고, 보호 라우트 FIXTURE_ITEMS에서 네 세션 상태의 결정을 본다.
decideRouteAccess에 라우트 정의를 받는 순수 함수를 따로 두는 안(리뷰
ⓐ)은 버렸다. fixture 기능을 설치하는 방법이 이미 있어서 운영 코드를
바꾸지 않고 실제 getRoute 경로까지 시험할 수 있다.
- scripts/test-sample-removal.ts: 새 파일을 공통 테스트 목록에 넣어,
제거 드릴이 그 파일이 남았는지 본다.
- 매뉴얼에 "샘플을 지우면 다시 고정한다"고만 적는 안(ⓒ)은 사람이
기억해야 해서 버렸다.
위험·한계
- 조립 루트가 이 함수 대신 실행기를 직접 만들도록 바뀌면 새 unit
테스트는 그걸 모른다. 템플릿 상태에서는 참조 기능 테스트가 계속
조립 루트 전체를 지킨다.
- 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts tests/unit/session-route-access.test.ts tests/unit/navigation-policy.test.ts tests/features/reference-feature/reference-runtime-composition.test.ts
- RED: 부모 커밋의 운영 코드에는 createRuntimeContractHttpExecutor가
없어 runtime-adapters.test.ts의 새 4건이 실패한다.
- 변이: 새 함수의 maxRetryAttempts를 상수 2로 바꾸면 "honours
MAX_RETRY_ATTEMPTS 0/1"이, navigation-policy.ts의 recovery-pending
분기를 show-sign-in으로 바꾸면 session-route-access.test.ts의
"answers a recovery-pending session …"이 실패해야 한다.
Refs: 1105/10-01
문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고
READY가 아닌 state를 모두 202로 답한다(FileUploadController#created).
악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다
(FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의
첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일
하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH,
APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는
안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드
문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기
검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다.
고른 방법(리뷰 01-01 최소 개선 방향 (가)):
- schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패
VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다.
413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지
않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입
FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는
성공 값으로 나오지 않는다).
- 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트)
보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는
이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다.
- 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201
REJECTED는 여전히 SCHEMA_MISMATCH다.
- MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED·
REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분).
- 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자
결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다.
버린 대안:
- REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서
거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다.
- 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는
그대로 SCHEMA_MISMATCH다.
위험·한계:
- upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서
VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로
바뀐다. CHANGELOG [계약] 한 줄이 필요하다.
- 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서
LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다.
- 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은
백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다.
- 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와
docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제
업로드 검증(미검증).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file,
not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an
undeclared size that turns out empty"(fetch를 부름)가 실패한다.
Refs: 1105/01-01, 1103/01-01
문제: 승인된 LOGOUT·ACCOUNT_DELETION purge는 객체 목록을 읽고, 하나씩
지우고, 마지막에 journal 행을 한 번 센 뒤 0이면 chunk sweep으로 끝나
`chunkSweep: "COMPLETED"`를 돌려준다. 목록과 세기는 각각 한 순간만 본다.
- 다른 탭이 새 객체를 put하는 중이면 purge의 remove가 그 put이 쥔
origin lease를 기다린다. partition에 객체가 3개 이상이면 그 put은
목록 뒤에 commit하고 세기 전에 complete까지 끝난다. 목록에도 행 수에도
없어 sweep이 그 chunk를 건너뛰고, 계정 삭제 뒤에도 파일이 읽힌다
(리뷰 실험 Y1b 메모리 20/20, Chromium 6/6). 저장소 테스트는 객체
0~1개로만 돌아서 이 틈을 놓쳤다.
- FILES_READY에서 멈춘 put의 행이 `logicalKey`를 잃으면 세지 못한다.
staging receipt가 chunk를 sweep에서 지켜 purge마다 COMPLETED인데
receipt·chunk·manifest가 남는다(Y2).
고른 방법: 마지막 객체까지 돈 purge는 sweep 대신 늘 partition 삭제로
끝낸다(리뷰 2.1절 (d')). exclusive partition lock이 그때 진행 중인
put·delete를 모두 기다린 뒤 디렉터리 전체(staging 포함)와 그 partition
행을 지우므로 두 경우를 함께 막는다. 객체 순회는 `removedObjects`·
`releasedBytes` 보고와 예산 단위 진행을 위해 남긴다. 예산이나 다른 탭의
변경(CONFLICT) 때문에 끝까지 돌지 못한 호출은 지금처럼
`moreObjectsAvailable: true`를 돌려주고, 그때만 journal 행을 세서 끝나지
않은 행이 있으면 바로 partition을 지운다(2026-11-03 05-01 그대로).
purge 성공 report는 이제 `partitionDeleted`와 `moreObjectsAvailable`
중 정확히 하나를 가진다(walk 뒤 abort도 more로 보고).
버린 대안:
- (a) sweep 뒤에 다시 세고 committed 객체를 한 번 더 본다: ①만 막고
②가 남는다. 다시 볼 때 정책상 남겨야 할 객체를 가려내려면 목록을 끝까지
다시 읽어야 한다.
- (b)+(a): 둘 다 막지만 판단 조건이 일곱 개가 된다.
- 세기를 아예 없애기: 예산에 걸린 호출의 crash 행 처리가 다음 호출로
밀린다. 지금 동작을 바꿀 이유가 없어 남겼다.
위험·한계:
- 모든 승인 purge가 다른 탭의 진행 중 put을 기다린다(지금까지는 끝나지
않은 행이 있을 때만). 기다림 상한은 `mutationLockWaitTimeoutMs`
(1103/05-02)이고 abort로 멈출 수 있다.
- 같은 partition에 LOGOUT 때 남겨야 하는 객체가 섞이면 이 방법은 맞지
않는다. 지금 정책 검사는 OPAQUE_PARTITION이면 LOGOUT·ACCOUNT_DELETION
모두 purge만 허용해 그런 객체가 생기지 않는다.
- port의 `chunkSweep`은 아무도 채우지 않는다. 읽는 코드가 깨지지 않게
타입은 남기고 `@deprecated`로 적었다.
- recipe fake의 purge도 늘 `partitionDeleted`다.
- `logicalKey`를 잃은 행 자체는 여전히 남는다(05-03 설계). 그 bytes는
이제 남지 않는다.
- Firefox·WebKit에서 Y1은 돌리지 않았다. browser spec은 객체 0·3개
두 경우로 늘렸다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
- node scripts/run-vitest.ts run tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm test:browser-capabilities tests/browser-capabilities/opfs-runtime.spec.ts --project=chromium
Refs: 1103/05-01
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면
부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는
buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의
message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다.
같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다.
고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그
`key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`,
`FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를
스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다.
오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도
싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것.
message 문구가 바뀌면 조용히 빠진다.
위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고,
그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다
(검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의
시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는
src/contracts/env.ts에 새로 더한 export다(추가만).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts
Refs: 1103/07-04
문제: 사전 캐시 수집기(`collectStaticAssets`)는 dist 전체를 돌고 파일
이름만 해시 정규식으로 본다. `public/` 파일은 이름 그대로 dist 루트에
복사되는데, `apple-touch-icon.png`, `android-chrome-192x192.png`,
`safari-pinned-tab.svg`는 정규식에 걸려 immutable 자산으로 들어간다(리뷰
06-R1). 제품이 같은 이름으로 아이콘을 바꾸고 CDN이 옛 바이트를 주면 새
릴리스 install이 INTEGRITY_MISMATCH로 통째로 거절된다. 이전 릴리스
fallback, 호스팅 정책 `/assets/*`, MIME probe, 레시피 문서는 모두
`assets/`만 가정한다.
고른 방법: 리뷰 06-01의 (a). 계약 모듈에 `BUILD_ASSET_DIRECTORY =
"assets/"` 하나를 두고, 수집기는 그 아래 파일만 받는다. 워커 fallback
(`service-worker-static-assets.ts`)과 probe(`hosting-probe.ts`)도 같은
상수를 읽는다. `build.assetsDir`를 바꿀 때(0925/06-08) 이 상수 한 곳만
고치면 된다. 수집기의 `.vite/` 제외는 새 조건이 덮으므로 지웠다. 레시피
문서에 루트 파일이 빠진다는 문장을 더했다.
버린 대안:
- 정규식을 Vite 해시 형식(8자 고정)으로 좁히기. 우연히 맞는 이름이 남는다.
- 문서만 고치기. 아이콘 문제가 그대로다.
위험·한계: 루트에 해시 이름 파일을 일부러 두는 제품은 그 파일이 사전
캐시에서 빠진다. Vite는 그런 파일을 만들지 않는다. 상수는 vite 설정에서
읽지 않는다. `build.assetsDir`를 바꾸는 제품은 상수도 같이 바꿔야 한다
(0925/06-08은 그대로 남는다).
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/service-worker-web-push-remediation.test.ts tests/unit/service-worker-runtime.test.ts tests/unit/hosting-probe.test.ts tests/unit/service-worker-build-output.test.ts
- RED: "precaches only the assets directory, not public files at the dist
root"가 옛 수집기에서 루트 아이콘 세 개를 받아 실패한다.
Refs: 1105/06-01
문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의
`unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면
check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03
수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에
필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서
FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다.
고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의
`unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로
바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향
(REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은
그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA
breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지
증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두
기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다.
리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다.
위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘
(src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도
고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를
REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿
스냅샷은 기준선과 같아 결과는 none 그대로다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts
리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를
다시 적용하면 check:registries가 `breaking change missing evidence:
FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy:
response-reader-narrowed`로 실패해야 한다.
Refs: 1105/07-02
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true,
retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시
올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다.
백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가
await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤
TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일
복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에
파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면
같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503
IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와
매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를
MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을
말하지 않는다. pin 대조도 이 표를 보지 않는다.
고른 방법:
- TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로
MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로
만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에
내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE,
STORAGE_FULL)이다.
- 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE,
MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로
판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다.
503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400
IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로
NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔
MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다.
- pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의
행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는
tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을
옮기면 두 reader가 함께 다시 대조된다.
- Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약
문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다.
- client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로
맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절).
버린 대안:
- client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과
불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일
업로드에서는 use case가 취소하므로 근거도 없다.
- TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과
pin 밖 상태가 남는다.
위험·한계:
- 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503
IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다.
- 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이
보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이
시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true,
retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에
interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지
docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을
되돌린다(재검토 조건).
- 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다
(UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성
executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다.
- 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md
추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은
같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면
충돌한다. 07-01과 함께 넣는 편이 낫다.
- Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은
것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503
IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT is an unknown result the client does not offer to
retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as
the V3 Envelope table does"가 실패한다.
Refs: 1105/01-02
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).
고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
`response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
`HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
`nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.
위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
redirect 뒤 200을 PASS), "checks every built asset type besides the
release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
빼면 "checks every built asset type ..."가 실패해야 한다.
Refs: 1105/06-02
문제: readFailureEnvelope는 실패 Envelope의 meta.traceId를 함께 돌려주고,
V3 실행기는 그 값을 AppFailure.traceId로 싣는다(1103/03-06). Fileserver
client는 envelope.value만 넘겨 traceId를 버린다. 지원 담당이 업로드 실패를
서버 로그의 요청과 잇지 못한다. 같은 백엔드의 다른 쓰기 실패는 이을 수 있다.
고른 방법: envelopeFailure가 읽은 Envelope 전체를 받아 traceId가 있으면
createFailure의 traceId로 싣는다. V3와 같은 규칙이다. 없으면 키를 두지
않는다. 매뉴얼 7절 결과 읽기에 한 줄 적었다.
위험·한계: Envelope 실패에만 싣는다. 성공 Envelope을 읽지 못한 실패
(SCHEMA_MISMATCH 등, 202 REJECTED 포함)는 readSuccessEnvelope가 meta를
돌려주지 않아 traceId가 없다. V3도 같다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표 17행이 traceId
"trace-1"이 없어 모두 실패한다.
Refs: 1105/01-03
문제: ci:gate는 명령 출력을 artifacts/quality/gates/FE-GATE-<NNN>.txt에만
쓰고 콘솔에는 PASS/FAIL 한 줄만 남긴다(scripts/run-ci-gate.ts). release
단계 job immutable_build는 후보 tar만, 그것도 성공했을 때만 올린다. 그래서
실제 run에서 FE-GATE-015·027이 왜 실패했는지와 FE-GATE-027이 쓰는
artifacts/security/dependency-advisories.json(1103/13-03의 신호)이 runner
작업 디렉터리와 함께 사라진다. 다른 gate job은 artifacts/를 if: always()로
올린다.
고른 방법:
- config/ci/gates.json의 immutable_build 마지막에 upload 단계를 더한다.
transfer ID는 immutable-gate-evidence, 이름은
immutable-gate-evidence-<run>-<attempt>, always: true. 대상은
FE-GATE-015·027의 log와 evidence 산출물(gate 순서)과 advisory 기록 7개다.
FE-GATE-015의 verification.json 등은 후보가 만들어지지 않으면 후보 안에도
없으므로 같이 올린다.
- 계약(scripts/contracts/ci-gates.ts)이 이 단계를 고정한다. immutable_build의
단계 목록에 upload 하나가 늘고, 이 upload가 always이고 마지막 단계이며
경로가 "job이 도는 gate의 log·evidence 경로 + advisory 기록"과 같아야
한다. 경로는 계약의 artifact 등록에서 계산하므로 log 경로가 바뀌면 함께
따라온다. advisory 기록은 gate evidence가 아니라(막지 않는 신호) 경로를
scripts/lib/dependency-advisories.ts의 상수로 옮기고 scan 스크립트도 그
상수를 쓴다.
- 후보 archive의 member set, 후보 upload(always 없음), 하위 job의 download는
그대로다. 생성 workflow를 generator 출력과 같게 손으로 고쳤다.
버린 대안:
- immutable_build도 artifacts/ 전체를 올림: 다른 job과 같지만 후보 증거가
두 이름으로 나가 어느 것이 승격 대상인지 흐려진다. 필요한 파일만 고정했다.
- ci:gate가 실패한 명령의 마지막 N줄을 콘솔에 씀(리뷰 대안 c, d의 콘솔
한 줄 포함): 모든 job에 걸리고 provider 출력의 비밀 노출과 로그 상한을
다시 따져야 한다. 담당 지시 범위(업로드) 밖이라 이번에 하지 않았다.
위험·한계:
- checkout·install 단계에서 실패하면 올릴 파일이 없어 이 단계도
if-no-files-found: error로 실패한다. job은 이미 실패한 뒤라 결과는 같다.
merge·release job의 upload도 같은 동작이다.
- 실제 Gitea runner에서 stage=release를 돌려 산출물이 남는지는 확인하지
못했다(runner 없음). 확인한 것은 계약·생성 workflow까지다.
- 콘솔에는 여전히 한 줄만 나온다. 사람이 산출물을 열어야 이유를 본다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
Refs: 1105/13-01, 1103/13-03
문제: 빌드, dev 서버, 타입 검사, vitest가 모두 시작할 때
`scripts/generate-product-feature-index.ts`로 `src/.generated/*.ts`를
다시 쓴다. 생성기는 `writeFile`로 파일을 제자리에서 비우고 다시 썼다.
한 checkout에서 두 실행이 겹치면, 한쪽이 파일을 비운 순간 다른 쪽의
Vite나 tsc가 빈 파일이나 반쯤 쓴 파일을 읽을 수 있다(1105/12-04의
"한 checkout 두 실행" 중 공유 소스 파일 부분).
고른 방법: 내용이 같으면 쓰지 않는다. 다르면 같은 폴더의 임시 파일에
쓰고 rename으로 바꾼다. 읽는 쪽은 옛 파일이나 새 파일 하나만 본다.
같은 선택(같은 PRODUCT_APP_ID·VITE_PRODUCT_FEATURES)으로 도는 두 실행은
아예 쓰지 않는다.
버린 대안: 실행마다 `src/.generated`를 따로 두기. 앱 소스가 이 경로를
import하므로 경로를 바꾸면 Vite·tsc·ESLint 설정이 모두 따라 바뀐다.
잠금 파일: 겹친 실행을 직렬로 만들 뿐이고, 죽은 프로세스가 잠금을
남긴다.
위험·한계: 선택이 서로 다른 두 실행(예: 한쪽만 VITE_PRODUCT_FEATURES=none)은
여전히 서로의 인덱스를 바꾼다. 그건 실행이 아니라 checkout 상태가 다른
것이라 이 커밋 범위 밖이다. 임시 파일은 `.tmp`로 끝나 tsc·Vite·ESLint
대상이 아니다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/product-feature-index-write.test.ts
Refs: 1105/12-04
문제: update spec은 옛 탭 회복을 페이지의 `fetch(removedChunk)`로만
본다. 바이트가 오는지는 알지만, B가 제어하는 A 탭에서 지워진 route를
여는 실제 경로는 아무 spec도 지나지 않는다. 워커 제어 아래 preload는
11-09 허용(`preloadunverifiable:service-worker:`) 때문에 fixture가 하나도
판정하지 못한다(리뷰 06-R9: 158줄 모두 ALLOWED). 워커가 직전 캐시로
답하지 않게 바꾼 변이(06-R10)에서 화면 단언은 통과했다. chunk 복구가
페이지를 B로 reload해 같은 not-found 화면을 그렸기 때문이다.
고른 방법: 리뷰 06-03의 (a). update spec에 test 하나를 더한다. B가
제어하는 A 탭에서 client navigation(pushState + popstate)으로 일치하지
않는 경로를 연다. `CHANGED_ROUTE_SOURCE`가 not-found 페이지라 그 경로가
지워진 chunk를 import한다. 단언:
- not-found heading이 보인다.
- 같은 문서다. navigation 전에 심은 전역 표시가 남아 있고 entry script가
그대로다(reload 없음).
- 그 문서가 chunk를 요청했다(Resource Timing 항목, 단언이 빈 경로를
보지 않게).
- navigation 뒤 서버 요청에 그 chunk가 없다(워커가 답했다).
- strict fixture가 허용 밖 실패 줄을 보지 않는다(기존 teardown 검사).
지워진 chunk를 찾는 코드는 기존 test와 같이 쓰도록 `removedRouteChunk`로
뺐다. Firefox는 같은 파일의 기존 격리(quarantine, 2027-03-31)를 그대로
따른다. Playwright Firefox는 워커가 페이지를 제어하지 못한다(06-R11 확인).
버린 대안: fixture가 워커 쪽 응답을 추적. Playwright 워커 network 이벤트는
Chromium 전용이다.
위험·한계: 테스트만 더했다. 지금 코드는 맞으므로 RED(부모 코드)에서도
통과한다. 결함은 변이로 보인다. 엔진마다 약 7초가 늘어난다(06-R9 기준).
WebKit에서는 chunk가 modulepreload link로 요청되어 워커 경로가 Chromium과
같은지 확인하지 않았다. 허용 패턴 자체는 그대로다.
검증: desktop batch에서 확인.
- corepack pnpm exec playwright test tests/e2e/service-worker-update.spec.ts --project=chromium --project=webkit
- 변이(06-R10과 같음, `service-worker-lifecycle.ts`의
PREVIOUS_RELEASE_FALLBACK 분기가 `return null`): 새 test가 chromium에서
sameDocument false(또는 fixture 실패 줄)로 실패해야 한다.
Refs: 1105/06-03
문제: Fileserver client 규칙 셋을 바꿔도 통합 테스트 48건이 모두
통과했다(리뷰 변이 FS4·FS5·FS8 생존).
- FS4: 5xx ATOMIC_PUBLISH_UNSUPPORTED를 NOT_APPLIED에서 빼도 표에 그 행이
없다.
- FS5: deadline에서 바이트 비례 몫을 없애도 시간 초과 테스트는 작은 고정값만
본다. 큰 파일이 느린 망에서 기본 30초에 끊기는 회귀를 못 잡는다.
- FS8: 선언 크기가 maxFileBytes보다 큰 파일을 읽기 전에 거절하지 않아도, 읽는
중 상한 검사가 같은 code를 내서 통과한다. 그 사이 선언 크기만큼 버퍼를 먼저
잡는다.
고른 방법(리뷰 01-04 최소 개선 방향):
- Envelope 실패 표에 503 ATOMIC_PUBLISH_UNSUPPORTED → NOT_APPLIED 행을
더한다. 504 TRANSFER_TIMEOUT 행은 01-02 커밋이 MAYBE_APPLIED로 더했다. 두
방향(빼기·되넣기)이 모두 실패를 만든다.
- 가짜 setTimeout과 주입한 fetcher·monotonicNow로, 기본 1초에 바이트당 1초를
더한 deadline 안에서 1.5초 뒤 온 답이 성공하는지, 자격 증명 owner가 받은
deadline이 1,000 + 바이트 수 × 1,000 ms인지 본다. 실제 시간에 기대지 않아
부하에 흔들리지 않는다.
- 선언 크기 초과에서 stream()이 한 번도 불리지 않음을 본다.
버린 대안: MSW에 지연을 넣고 실제 시간으로 deadline을 재는 방법. 부하가 큰
desktop에서 흔들릴 수 있고, 시간 여유를 키우면 테스트가 느려진다.
위험·한계: 테스트만 더했다. 지금 코드는 의도대로라서 부모 src에서도
통과한다. 검출력은 변이로만 확인할 수 있다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED 없음(테스트 추가). 변이 셋이 각각 실패를 만들어야 한다:
FS4' NOT_APPLIED_5XX_CODES에서 "ATOMIC_PUBLISH_UNSUPPORTED" 줄 삭제,
FS5 timeoutMs 식의 Math.ceil(...) 몫을 0으로,
FS8 readMultipartBody의 declared > maxFileBytes 거절 블록 삭제.
Refs: 1105/01-04
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.
고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
`scope_participant: <label>`. template participant 실패도 같은 길로
남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
(`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
바로 드러나야 진단에서 label이 빠지는 일이 없다.
버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
뜻이 흐려진다.
위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters-product-scope-participants.test.ts
tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
Refs: 1105/02-01
문제: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를
`files: SessionBrowserFiles`로 보강한다"고 적는다. 매뉴얼
(`docs/manual/03-outside-feature-folder.md`)은 그 타입을
`src/features/product-capabilities.ts`의
`ProductFeaturePlatformCapabilities`에 적으라고 하고, `declare module`
보강은 `check:types:node`가 키를 보지 못한다고 막는다. 주석대로 하면 앱
typecheck는 통과하고 node typecheck에서 키를 잃는다. 또 레시피 테스트는
`capabilities: {}`로 조립하고 `files.current()`를 레시피 객체에서 직접
불러서, capability가 기능 쪽으로 넘어가는 절반이 깨져도 통과한다.
고른 방법:
- 주석이 `ProductFeaturePlatformCapabilities`에 적는 예와 매뉴얼 경로를
보이고, `declare module` 보강은 쓰지 말라고 적는다.
- 레시피 테스트가 `capabilities: { files }`를 돌려주고, 템플릿이 설치된
기능의 loader에 넘기는 capability 객체(`createInstalledFeatureLoaders`의
첫 인자)를 기록한다. 테스트의 모든 파일 동작(선택, 읽기, download,
계정 전환 뒤 새 runtime)을 그 객체의 `files.current()`로 돈다. 같은
mock 방식은 `tests/recipes/session-owners-runtime.test.ts`가 이미 쓴다.
버린 대안: `files`를 `needs`에 적은 가짜 기능을 생성 index에 끼워 넣기.
`ProductFeaturePlatformCapabilities`가 비어 있는 템플릿에서는 타입을
우회해야 하고, `needs`로 고르는 부분은 1103/09-08 테스트가 이미 잡는다.
위험·한계: 검사는 loader가 받는 capability 객체까지다. 기능 factory가
`needs`로 골라 받는 마지막 단계는 기존 테스트에 맡긴다. 동작 코드는
바뀌지 않는다(주석과 테스트만).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
- 변이: 테스트 mock의 `capabilities`에서 `files`를 빼거나,
`src/bootstrap/runtime-adapters.ts`의 `...product.capabilities`를 지우면
"Features did not receive the files capability"로 실패해야 한다.
Refs: 1105/02-03
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.
고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
`notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.
위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.
Refs: 1105/07-01
CHANGELOG의 미출시 절은 `752a61f` → `fix/maturity-review-2026-11-03`
범위다. 그 범위는 main `409d72e`에 합쳐졌고, 2026-11-05 리뷰의 P1
조치 셋(1105/09-01, 12-01, 13-01)은 어느 절에도 없다. 다운스트림이
FE-GATE-013 러너 요구와 release job의 새 upload를 알 수 없다.
`409d72e` → `fix/maturity-review-2026-11-05` 범위의 새 미출시 절을
위에 두고 세 조치를 적었다. CI 러너 요구와 workflow upload가 바뀌므로
12-01·13-01은 [계약]이다. 기존 절은 지우지 않고 main에 합쳐졌다고만
머리에 적었다. 두 절을 하나로 합칠지는 남은 조치(PR B)의 CHANGELOG
정리에서 정한다.
위험·한계: 문서만 바꿨다.
검증: desktop batch에서 changelog-review-ids, documentation-readiness
테스트.
Refs: 1105/09-01, 1105/12-01, 1105/13-01
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.
고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
벌 생긴다.
위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
(`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation
Refs: 1103/09-05
문제: 2026-11-03 02-02 수정 뒤 저장된 본문을 읽지 못하면(`UNAVAILABLE`·
`NOT_READABLE`) 손상이 아니라 "모름"이다. stage 재사용 경로는 "모름"이면
실패를 돌려주고 다시 받지 않는다. 그래서 다시 쓰기 전까지 계속 읽히지 않는
entry(blob 손실 등)는 다시 stage해도 고쳐지지 않는다(리뷰 실험 E-1).
- 새 후보: activate가 `RETRY`를 안내하는데 다시 해도 같다. cleanup으로
후보를 지운 뒤에야 풀린다.
- rollback 대상: cleanup도 지우지 않아 되돌릴 길이 없다.
- 서비스 중 release: 그 asset 조회가 계속 `UNAVAILABLE`이다.
수정 전 판정에서는 같은 상태가 다시 stage 한 번으로 풀렸다.
고른 방법(리뷰 대안 (나)):
- 판정에 `UNREADABLE`(entry는 있는데 본문 읽기가 실패)을 따로 둔다.
`UNKNOWN`은 중단(`ABORTED`)과 `cache.match` 자체의 실패만 뜻한다.
- stage 재사용 경로는 `REPAIRABLE`처럼 `UNREADABLE`도 모든 asset을 다시
받아 같은 cache에 덮어쓴다. 덮어쓰는 것은 digest로 검증한 같은
바이트이고 cache를 지우지 않으므로 서비스 중인 release를 해치지 않는다
(STO-RR-04가 막는 것은 삭제다).
- activation은 지금처럼 본문 읽기 실패를 손상으로 보고하지 않고 code를
그대로 둔다. recovery만 `REHYDRATE`(같은 manifest로 다시 stage)로 바꾼다.
- 조회는 그대로 `UNAVAILABLE`/`RETRY`다.
- `cache.match`가 던지는 경우는 리뷰가 제안한 "중단 제외 UNKNOWN 전부"에서
뺐다. Cache Storage 자체가 응답하지 않을 때 모든 asset을 다시 받는 것은
고치는 것이 없고, 2026-11-01 02-03 테스트가 그 경우의 실패 보고를 고정한다.
버린 대안:
- (가) 문서에 "cleanup 뒤 다시 stage"만 적기: rollback 대상은 못 고친다.
- (다) 실패한 entry만 다시 받기: 비용은 가장 작지만 stage 경로를 entry
단위로 나눠야 한다.
위험·한계:
- 일시적인 본문 읽기 오류에도 다시 stage하면 모든 asset을 다시 받는다
(수정 전과 같은 비용).
- 실제 브라우저에서 본문 읽기 실패가 지속되는지, 어떤 오류 이름으로
오는지는 확인하지 못했다. 테스트는 메모리 fake에 오류를 주입한다.
- service-worker-pwa 번들 여유가 342 B다(FE-GATE-012). 늘어난 코드는
분기 둘이다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
tests/unit/public-response-cache.test.ts tests/unit/public-response-cache-codec.test.ts
tests/recipes/browser-file-storage-contracts.test.ts
- corepack pnpm check:optional-recipes (번들 예산)
Refs: 1105/02-02
문제: 2026-11-03 02-02가 만든 손상 code 목록(`REPAIRABLE_READ_CODES`,
`INTEGRITY_FAILED`·`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`)의
경계를 테스트가 고정하지 않는다. 리뷰 배치 02-R1에서 목록에서 하나를
빼거나 `NOT_READABLE`을 더한 변이 5개가 cache 테스트 59건을 모두
통과했다. 지금 테스트는 `TypeError` 하나로 본문 실패를 만들고, stage
재사용 경로의 repair 테스트는 entry가 없는 경우만 본다.
고른 방법: 1105/02-02 묶음에 표 테스트 하나를 둔다. 행은 목록의 code
넷(바이트 변경, 정책 밖 헤더 `cache-control: no-store`, 상한을 넘는
`content-length`, `DataError` 본문)과 목록 밖 본문 실패 둘(`TypeError`,
`NotReadableError`)이다. 행마다 activate가 돌려주는 code와 recovery
(`REHYDRATE`), 다음 stage가 모든 asset을 다시 받는지(fetch 2), 그 뒤
activate 성공을 본다. 손상 넷은 activate에서 `INTEGRITY_FAILED`이고
본문 실패는 원래 code(`UNAVAILABLE`·`NOT_READABLE`)다. 그래서 목록에서
`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 빼거나 `NOT_READABLE`을
더하면 그 행의 activate code가 바뀌어 실패한다.
위험·한계: 1105/02-02 뒤 stage는 손상과 본문 읽기 실패를 모두 다시 쓴다.
그래서 목록에서 `INTEGRITY_FAILED`를 빼는 변이(F0202-int)는 이제 동등
변이다. 그 code는 목록 밖으로 가도 activate가 같은 `INTEGRITY_FAILED`/
`REHYDRATE`를 돌려주고 stage도 똑같이 다시 쓴다. 리뷰가 걱정한 "바이트가
바뀐 후보를 다시 stage로 고치지 못한다"는 1105/02-02로 막혔고, 그 동작은
이 표의 첫 행이 지킨다. 동작 코드는 바뀌지 않는다(테스트만).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
- 변이: `public-response-cache-adapter.ts`의 `REPAIRABLE_READ_CODES`에서
`CORRUPT_DATA`·`POLICY_REJECTED`·`LIMIT_EXCEEDED`를 하나씩 빼고,
`NOT_READABLE`을 더해 각각 표의 해당 행이 실패하는지 본다.
Refs: 1105/02-04
문제: 짝 백엔드 Redis session 모드를 쿠키 recipe와 매뉴얼 04 4.3대로
이으면 서버 401이 세션에 닿지 않는다. 1103/09-01 수정 뒤 조립 루트는
제품 provider 프로필의 401을 제품의 선택 hook `onCredentialRejected`에만
알린다. 쿠키 모드의 operation은 모두 제품 프로필(SESSION_COOKIE_*)인데
매뉴얼 예시는 그 hook을 잇지 않았고, recipe와 매뉴얼은 "서버 401 →
unauthenticated"라고 적었다. 이으려 해도 ProductCompositionContext에
세션에 알릴 길이 없었다. 리뷰 09-cookie401에서 세션 만료 뒤에도 상태가
authenticated, 이전 scope가 current로 남았다.
고른 방법: 두 가지를 더했다.
- ProductCompositionContext.notifySessionUnauthenticated(): 템플릿 세션의
자기 401과 같은 판정(authSession.onUnauthenticated)을 제품이 부를 수
있게 한다(리뷰 안 C).
- recipe의 createSessionCookieRejectionHandler(context): SESSION_COOKIE_*
프로필의 401만 세션에 넘긴다. 다른 제품 프로필의 401은 넘기지 않으므로
1103/09-01의 완료 기준(세션과 무관한 provider의 401은 로그아웃시키지
않는다)은 그대로다.
매뉴얼 04 4.3 예시에 `onCredentialRejected` 한 줄을 넣고, recipe 주석,
매뉴얼 04 흐름도, 매뉴얼 02 5절과 7절 업로드 예시(BACKEND_SESSION 쿠키
세션)를 맞췄다. 버린 대안: recipe가 owner와 provider를 한 번에 만드는
함수(안 B). owner는 composeProductSessionOwner, provider는 composeProduct
에서 따로 만들어져 모듈 변수가 필요하다. provider 선언에 "세션 자격
증명" 표시를 두는 안(D)은 계약 칸이 늘고 판정이 선언과 hook 둘로 갈린다.
위험·한계: 제품이 이 한 줄을 빼면 여전히 세션 만료를 모른다. 이것을
막는 검사는 없다(매뉴얼과 recipe 주석이 적는다). 이미 recipe를 복사한
다운스트림은 handler를 복사본에 옮기고 composeProduct에 한 줄을 더해야
한다. ProductCompositionContext에 칸이 하나 늘었다. 이 context는 템플릿만
만들므로 제품 코드는 깨지지 않는다. 실제 Redis 백엔드에는 붙이지
않았다(1103/09-03 남은 부분).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts tests/recipes/cookie-session-owner.test.ts
조립 루트를 지나는 테스트가 매뉴얼 4.3 연결로 쿠키 읽기·쓰기 401 뒤
세션 unauthenticated, 이전 scope not current를 본다.
Refs: 1105/09-02
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.
고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.
위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.
검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx
BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.
Refs: 1103/16-05
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.
고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
`git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.
위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
"not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
the working tree", "reports the references as not verified when the
checkout does not have the pinned commit", "fails a link out of the
repository into a repository that is not paired".
Refs: 1105/12-02
문제
제품 overlay(config/ci/product-gates.json)의 mergeGates는 product_merge_gate
job으로 렌더링되는데, 다른 job이 이 job을 기다리지 않는다. release_gate는
merge_gate만 기다린다. 그래서 제품 검사(예: 짝 백엔드 계약 검사)가 실패해도
같은 run의 release·immutable_build·promotion·deployment는 그대로 돈다. 브랜치
필수 검사는 PR merge만 막는다. job 그래프는 계약이 고정해서(ci-gates.ts의
expectedJobGraph) 제품이 연결을 더할 방법도 없다.
고른 방법
- overlay에 게이트가 있으면 release_gate의 needs에 product_merge_gate를 더해
렌더링한다(`needs: [merge_gate, product_merge_gate]`). release_gate는 release
단계의 첫 job이고 뒤의 job은 모두 그것을 거쳐 기다린다. 템플릿 게이트가
release를 막는 방식과 같다.
- 연결은 렌더링에서만 더한다. gates.json과 계약 그래프 검사는 그대로라 템플릿
job 그래프와 check:ci의 엄격함은 바뀌지 않는다. 게이트가 없으면 workflow
바이트가 같다(.gitea/workflows/quality-gates.yml 변경 없음).
- workflowGateExecutionFailures(check:ci가 부름)가 제품 게이트가 있는데
release_gate가 product_merge_gate를 기다리지 않는 workflow를 거절한다.
"실행된다"와 "막는다"를 따로 본다.
- 문서(ci-quality-gates.md, README)에 release 단계가 제품 job을 기다린다고
적었다.
- 버린 대안: (a) 문서에만 "막지 않는다"고 적기. 제품이 막을 방법이 계속 없다.
(c) 게이트마다 blocksRelease 칸. 선택권은 주지만 칸이 늘고, 불안정한 제품
검사가 생기기 전에는 필요가 없다. 계약 그래프 검사에 overlay 예외를 넣는 것:
템플릿 계약이 제품 overlay를 알아야 한다.
위험·한계
- 불안정한 제품 게이트는 이제 release도 멈춘다. 그때는 (c)로 간다.
- Gitea가 needs와 기본 success() 조건을 GitHub Actions처럼 처리한다고 본다.
실제 runner에서는 확인하지 못했다(Actions 꺼짐).
- 제품 게이트를 이미 쓰는 다운스트림은 generate:ci-workflow를 다시 돌려야
check:ci를 통과한다(생성 YAML의 release_gate needs 한 줄이 바뀐다).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/product-ci-overlay.test.ts tests/unit/ci-workflow-generation.test.ts,
corepack pnpm check:ci.
- RED 기대: "holds the release stage until the product merge gates pass",
"runs product merge gates in a job of their own, apart from the template gates".
Refs: 1105/13-02
문제
docs/testing/frontend-platform-testing-strategy.md 11.2절이 "401 뒤 인증 복구
흐름은 tests/integration/auth-recovery.test.ts가 다룬다"고 적는다. 그 파일은
V2 클라이언트를 지울 때(048f490a) 같이 지웠고, V3 실행기에는 401 뒤 복구·재전송
흐름이 없다. 문서를 따라가면 없는 테스트와 없는 동작을 찾게 된다. 이 문서는
docs/README.md 1절 밖(목표 설계)이라 verify:documentation이 보지 않는다.
고른 방법
- 문장을 지금 동작으로 고친다: V3는 401을 UNAUTHENTICATED로 끝내고 다시 보내지
않는다(http-execution-v3.ts), 판정은 tests/unit/http-execution-v3.test.ts가
검사한다. 지운 파일 이름은 backtick 경로로 남기지 않는다.
- 1103/12-05의 남은 둘(지운 심볼 이름 검사, 1절 밖 문서 검사)은 이 커밋에서
하지 않는다. 심볼 검사는 지난 리뷰가 버린 대안이다(지운 이름 목록을 따로
관리해야 하고 오탐이 많다). 1절 밖 문서는 목표 설계라 일부러 없는 경로를
적는다. 2절 문서의 backtick repo 경로 중 없는 것이 15개쯤이고 대부분
계획 경로다(src/domain, src/generated, V2 파일 등). 검사로 넓히려면 문서별
예외 방식부터 정해야 한다(결정 대기).
위험·한계
- 같은 종류의 옛 경로는 1절 밖 다른 문서에 남아 있다(2026-07-30 결정 정본의
V2 http 파일 등). 이 커밋은 리뷰가 든 한 곳만 고친다.
검증
- 문서만 바꿨다. 이 문서를 보는 자동 검사는 없다(1절 밖). desktop batch에서
corepack pnpm verify:documentation이 그대로 통과하는지만 본다.
Refs: 1103/12-05
문제
feature-and-app-roots-do-not-reach-adapters는 기능 루트 파일
(src/features/*.ts, src/features/<id>/*.ts), src/contexts, src/apps만 본다.
그래프는 간선 하나씩 검사하므로, 기능 안에 계층이 아닌 폴더(support/ 등)를
만들어 그 파일이 http adapter 배럴을 import하고 기능 presentation이 그 파일을
import하면 presentation이 구체 adapter에 닿는다. 1105 리뷰 12-R3 변이에서
check:architecture와 ESLint가 둘 다 통과했다.
고른 방법
- 규칙의 from을 "src/features 아래 모든 파일, 기능의 adapters/ 폴더 밖"으로
바꾼다(`^src/(features/|contexts/|apps/)`, pathNot
`^src/features/([^/]+/adapters/|feature-adapter-contribution\.ts$)`). 규칙
주석이 이미 "기능 안에서는 adapters/ 폴더만 src/adapters에 닿는다"고 적고
있었고, 그 문장을 경로로 옮긴 것이다. 파일 단위 예외는 기존 하나
(feature-adapter-contribution.ts, type only) 그대로고 새로 더하지 않았다.
- domain·application·presentation은 자기 규칙이 이미 src/adapters를 막는다.
이제 그 파일들이 src/adapters를 import하면 이 규칙도 같이 걸린다(위반 두 줄).
더 엄격해질 뿐 허용이 바뀌지는 않는다.
- 지금 src/features에서 src/adapters를 import하는 곳은 reference-feature의
adapters/ 두 파일과 feature-adapter-contribution.ts뿐이라 새 위반은 없다.
create:feature가 만드는 adapter import도 adapters/ 안이다.
- 그래프 회귀 fixture에 support/ 재수출(거절), 그것을 읽는 presentation,
기능 adapters/ import(허용)를 더하고 check:architecture에 두 단언을 더했다.
규칙 경로를 check:architecture와 같은 방식으로 읽는 vitest 테스트를 더했다.
- layers.md 표와 매뉴얼 01의 설명을 고쳤다.
- 버린 대안: 계층 밖 폴더 자체를 금지(폴더 이름 목록 검사). 제품이 contracts/
같은 다른 이름을 쓰면 계속 목록을 고쳐야 한다. 규칙마다 support/ 패턴 추가:
다음 폴더 이름에서 같은 틈이 난다.
위험·한계
- 다운스트림이 기능 안 adapters/ 밖에서 src/adapters를 import하고 있었다면 이제
check:architecture가 실패한다. 그 파일을 adapters/로 옮기면 된다.
- ESLint는 여전히 간선 하나만 보므로 이 경로를 잡지 않는다. 그래프가 잡는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/architecture/feature-adapter-reach.test.ts, corepack pnpm
check:architecture(그래프 fixture 단언 2개 추가 PASS, 저장소 위반 0 기대).
- RED 기대: "rejects a concrete adapter import from a feature folder that is not
a layer", "leaves a feature's adapters folder and the type-only contribution
file to reach adapters"(support/adapters/ 경로 단언).
Refs: 0929/12-03
1105/12-01 수정이 gate 정의에 `hostRequirements`(러너가 갖춰야 할 것)를
더했지만, 기준선의 gate 모양 해시(`canonicalGateShapeSha256`)에서는
뺐다. 그래서 누가 이 요구를 지우거나 바꿔도 `contract-baseline.json`이
알아차리지 못하고 `check:ci`가 통과한다. 요구가 사라지면 workflow
주석도 사라져, user namespace가 없는 러너에서 같은 원인 불명 실패가
다시 난다.
러너 요구를 gate 모양에 넣는다. 요구를 선언한 gate만 이 키를 갖게 해
다른 gate의 해시는 그대로다. 기준선을 한 번 다시 기록했다(owner
DongHyeonka, reason에 1105/12-01). 버린 대안: 그대로 빼 두기(지우기를
리뷰가 못 본다), 모든 gate에 빈 목록을 넣기(모든 해시가 바뀌고 효과는
같다).
위험·한계: 앞으로 `hostRequirements`를 바꾸려면 기준선 재기록
(`update:ci-contract-baseline`, owner·reason 필수)이 필요하다. 의도한
비용이다.
검증: desktop batch. `tests/unit/ci-workflow-generation.test.ts`의 새
"rejects runner requirement drift through the semantic-shape digest"가
수정 전 코드·기준선에서 실패하고 수정 뒤 통과한다. `check:ci` 통과.
Refs: 1105/12-01
문제
tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴
preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict
fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서
strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는
하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다.
3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다.
고른 방법과 버린 대안
- strict fixture의 마지막 판정을 browserFailureVerdict fixture로
뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록
단언). page fixture는 기록을 그 판정에 넘긴다.
- spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를
둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page
teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히
같은지 본다.
- 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄.
- WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자,
같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로.
- 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console
error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가
따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다.
- 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다.
- 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든
실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다.
- 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에
증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다.
위험·한계
- 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다.
- 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다.
allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는
검사는 더하지 않았다.
- 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다.
그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다.
검증
- desktop batch에서 확인:
corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진)
- 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다.
- 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload
the page never runs"가 세 엔진에서 실패해야 한다.
- WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's
unused-preload guess word for word and nothing else"가 실패해야 한다.
- browserFailureVerdict 기본값의 expect 제거: "fails a test whose page
writes a console error"가 "expected to fail" 위반으로 실패해야 한다.
Refs: 1105/11-01
문제
접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를
읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는
일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데
scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고
automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은
라우트가 통과로 보고된다. annotation은 test 결과에만 남는다.
고른 방법과 버린 대안
- scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때
자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다.
실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다
마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고
rename한다.
- tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와
데이터 상태로 본 라우트는 지운다).
- a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만,
notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을
합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다).
- 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력
validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본
응답을 받는 자리를 새로 열어야 한다.
- annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y
스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업
(12-04)이 바꾸는 중이다.
- 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가
notChecked로 적히고 수동 검토가 맡는다고 적는다.
위험·한계
- a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드).
템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다.
- 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다.
지금까지 실제로 검사하지 않던 것이 드러나는 것이다.
- 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물
경로를 실행마다 나누면 이 경로도 따라가야 한다.
- 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다.
지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의
notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다.
- RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit
test 파일 전체가 실패한다.
Refs: 1103/11-01
BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.
문제
§10.8의 마지막 검사(src/adapters/http/http-execution-v3.ts:1493-1499,
검증을 통과한 성공 응답이라도 scope가 이미 현재가 아니면 SCOPE_FENCED)
를 false로 바꿔도 네 라운드째 모든 테스트가 통과한다(변이 L01). 지금
scope fence 테스트는 scope signal도 abort해서, abort 경로가 먼저
답하고 이 검사까지 오지 않는다.
고른 방법과 버린 대안
- tests/unit/http-execution-v3.test.ts에 경우 둘(조회·명령)을 더한다.
fetch 안에서 scope의 isCurrent만 false로 바꾸고 signal은 abort하지
않는다. JSON 성공 경로에서 dispatch 뒤 scope를 보는 곳은 이 검사
하나라서, 검사를 지우면 SUCCESS가 나와 테스트가 실패한다.
- 기대값: CONTRACT_VIOLATION/SCOPE_FENCED, 조회는 NOT_APPLICABLE,
명령은 MAYBE_APPLIED(보냈으니 적용됐을 수 있다).
- 기존 abort 테스트를 바꾸는 안은 버렸다. 그 테스트는 abort가 먼저
이기는 경로를 지킨다.
위험·한계
- 테스트만 더했다. 실행기 코드는 그대로다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/http-execution-v3.test.ts
- 변이 L01(:1494 조건을 false로)을 넣으면 "discards a valid read/command
success that arrives after its scope stopped being current" 2건이
실패해야 한다.
Refs: 0929/10-04
문제
taxonomy는 test:all을 일상 개발 루프라고 적는다. 그런데 test:all은
tests/features 중 참조 샘플만(test:reference-feature) 돌리고,
test:coverage(FE-GATE-005)가 도는 tests/features의 나머지(설치 표면,
feature-module, 예제 기능 2파일), tests/scripts,
tests/scale/browser-soak.contract.test.ts를 빠뜨린다. 로컬에서 초록이고
CI에서 빨강이 될 수 있다.
고른 방법과 버린 대안
- package.json test:all의 test:reference-feature 자리를 tests/features
전체 + tests/scripts + browser-soak 계약 테스트를 한 번에 도는 Vitest
실행으로 바꾼다. 참조 샘플 테스트도 tests/features 안이라 그대로
돈다. 샘플을 지우면 그 폴더만 빠진다.
- tests/unit/test-all-paths.test.ts(새 파일): package script graph로
test:all과 test:coverage의 Vitest 경로를 모아, coverage 쪽 경로가
모두 test:all 경로 안에 있는지 본다. 다시 빠지면 이 테스트가 잡는다.
- 새 package script(test:features)를 만드는 안은 버렸다. 그 이름이
tests/scripts까지 도는 것을 말하지 못하고, test:all만 쓰는 스크립트가
하나 늘 뿐이다.
- taxonomy에 "CI와 같은 집합은 test:coverage"라고만 적는 안은 버렸다.
완료 기준(test:all ⊇ test:coverage의 Vitest 파일)을 못 채운다.
- docs/testing/taxonomy.md의 test:all 설명을 바꾼다.
위험·한계
- 제거 드릴 셋(optional recipe, realtime, browser-file-storage)은
fixture 안에서 test:all만 돈다. 이제 이 파일들도 그 fixture에서
처음 돈다. import를 보면 제거 대상에 기대지 않지만 실행으로는 확인하지
못했다. 드릴 시간이 몇 초씩 는다(1101/10-06과 반대 방향).
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/test-all-paths.test.ts
corepack pnpm test:all, corepack pnpm check:ci, FE-GATE-020
- RED: 부모 커밋의 package.json에서 "runs every Vitest path
test:coverage runs"가 tests/features·tests/scripts·browser-soak
경로를 빠졌다고 실패한다.
Refs: 0929/10-05
문제
테스트 5개가 운영 코드의 시간 상수를 실제 시계로 기다린다.
- tests/unit/service-worker-runtime.test.ts "bounds a stream that never
produces a chunk": ACTIVATION_MARKER_READ_DEADLINE_MS(5초)를 그대로
기다린다. 10초 제한 중 5초를 쓴다.
- tests/unit/browser-rpc/browser-rpc-remediation.test.ts "keeps the
operation DRAINING when waitClosed …" 4개: 닫힘 확인이 없으면 stream
정리가 STREAM_CLEANUP_BOUND_MS(1초)를 기다린다. 각 1초.
고른 방법과 버린 대안
- SW 테스트: 이 테스트만 vi.useFakeTimers()로 돌리고 deadline을
advanceTimersByTimeAsync로 넘긴다. 마커를 여러 번 읽을 수 있어
끝날 때까지 5초씩 최대 4번 넘긴다. deadline이 없으면 활성화가 끝나지
않아 "settled" 단언에서 실패한다.
- RPC 테스트: 런타임은 이미 ClockPort를 주입받는다. 모든 대기를 30ms로
자르는 시스템 시계를 넘긴다. 작업 자체의 25ms deadline은 그 아래라
그대로다.
- SW lifecycle이 deadline을 의존성으로 받게 하는 안은 버렸다. 운영
코드에 테스트용 손잡이를 하나 더 열어야 한다.
- 상수 값(5,000·1,000)은 운영 코드 한 곳에 그대로 있다.
위험·한계
- 가짜 시계가 stream·마이크로태스크 순서와 얽히면 SW 테스트가
불안정해질 수 있다. 그때는 실제 시계로 되돌린다(1101/10-07 재검토
조건).
- 완료 기준(각 100ms 아래)은 junit 시간으로 desktop에서 본다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/service-worker-runtime.test.ts tests/unit/browser-rpc/browser-rpc-remediation.test.ts --reporter=junit --outputFile.junit=artifacts/tests/r1105-10-07.xml
- 실행 시간만 바꾼 커밋이라 RED는 없다. 두 파일이 통과하고 다섯
테스트가 각각 100ms 아래여야 한다.
Refs: 1101/10-07
문제: 초기 JS 측정(scripts/scale/measure-feature-shape-growth.ts)과
VITE_PRODUCT_FEATURES=none 빌드 테스트
(tests/unit/product-feature-selection-build.test.ts)가 임시 폴더에 복사할
빌드 입력 8개를 따로 적는다. vite.config.ts가 새 로컬 파일을 import하면
두 목록이 함께 낡고, 한쪽만 고치면 원인을 말하지 않는 "Could not resolve"로
실패한다(7f9a515, 799ab7f가 두 곳을 같이 고쳤다).
고른 방법: scripts/lib/vite-build-inputs.ts에 VITE_BUILD_INPUTS 하나를 두고
두 파일이 import한다. 측정 스크립트가 테스트 파일을 import하지 않는다.
새 tests/unit/vite-build-inputs.test.ts가 (1) 두 소비자에 자기 목록이
없고 이 모듈을 쓰는지, (2) vite.config.ts가 상대 경로로 닿는 모든 파일이
목록 안에 있는지 본다. (2)는 새 로컬 import를 목록에 넣지 않으면 빌드
전에 그 파일 이름으로 실패한다.
버린 대안: 목록을 vite.config.ts에서 export — 설정 파일을 빌드 도구 밖에서
import하면 플러그인 초기화가 따라온다.
위험·한계: import 그래프는 정규식으로 따라간다. 동적 import나 alias로
읽는 파일은 보지 못한다(지금은 없다). scripts/lib/removal-fixture.ts의
복사 목록은 저장소 전체 사본용이라 목적이 달라 합치지 않았다. 측정
스크립트는 참조 기능과 함께 지워지므로(test:sample-removal), (1)은 있는
소비자만 본다. 템플릿에서 그 파일이 없어지면
tests/unit/feature-shape-growth.test.ts가 import에서 실패한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts
tests/unit/product-feature-selection-build.test.ts
tests/unit/feature-shape-growth.test.ts
corepack pnpm ci:gate FE-GATE-020 (참조 기능을 지운 사본의 test:all)
Refs: 1105/15-03
문제: initialJavascriptRecordDrift가 합계를 1%까지 같다고 본다.
202,927 B에서 1%는 2,029 B로, 남은 여유 1,873 B와 기능 하나(768 B)보다
크다. 템플릿 변경이 여유를 다 써도 기록을 다시 쓰지 않은 채 test:unit을
통과하고, 기록을 인용한 문서는 없는 여유를 말한다. 단위 테스트는 1,500 B
차이를 "같음"으로 고정했다.
고른 방법: 합계만 바이트 상한 256 B(INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES)로
바꾼다. build id 차이(기록된 실행 사이 6 B, 48 B)는 넘고 기능 하나보다는
작다. 기능·context 비용(10%)과 파일 수(정확)는 그대로다. 단위 테스트는
48 B·200 B 차이는 통과, 300 B 증가와 1,500 B 차이는 실패로 고정한다.
performance-evidence.md의 "합계 1% 초과" 문장을 고쳤다.
버린 대안: 여유 자체를 기록해 대조 — 예산이 바뀔 때마다 같이 바뀌어
더 쉽게 낡는다.
위험·한계: 초기 JS를 수백 바이트 움직이는 템플릿 변경마다 기록을 다시
써야 한다(의도). CI와 로컬의 build id 차이가 256 B를 넘는 일이 생기면
test:unit이 흔들린다. 지금까지 본 차이는 50 B 안이다. 이 커밋은 기록
숫자를 바꾸지 않는다. 현재 기록과 빌드의 차이는 0 B였다(리뷰 15-lab).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
Refs: 1105/15-02
문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은
넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는
프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이
15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든
게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다.
고른 방법:
- base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가
첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay
스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다.
- lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로
--hide-scrollbars를 빼고 띄운다. lab.json context.browser에
scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다.
- 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에
scrollbar-gutter: stable이 있는지.
- 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다
(test:visual:update).
버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를
그린다.
위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다.
--hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든
5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px).
compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제
휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰
화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다
(일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산
0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다).
Firefox·Windows 스크롤바 폭은 재지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛
골든과 5건이 달라 실패, 다시 찍은 골든에서 통과)
corepack pnpm build && corepack pnpm test:performance -- --runs=5
Refs: 1105/15-05
문제: 플랫폼 구성 화면(lab 대상)은 getReleaseSummary()가 끝날 때까지
릴리스 신원 칸을 "상태" 한 칸으로 그리고, 끝나면 hint 줄이 있는 네 칸으로
바꾼다. 제목이 보인 뒤 약 30~100 ms에 grid가 hint 한 줄만큼 커져 아래
section이 21 px 내려간다(layout shift 0.00461, 리뷰 15-platform-shift
16회). lab은 `/`에서 클릭으로만 들어가고, 클릭 뒤 500 ms 안의 shift는
hadRecentInput이라 CLS에서 빠지므로 0을 낸다. `/` 밖의 라우트 CLS는 어느
게이트도 보지 않는다.
고른 방법:
- 화면: 요약 전·실패 때도 같은 네 칸(빌드·릴리스·설정 스키마·계약 집합
다이제스트)을 같은 hint 줄 구성으로 그린다. 값만 "확인하고 있습니다."
/ "확인하지 못했습니다." / "—"다. 상태 문장은 가장 좁은 칸(13rem)에서도
한 줄이 되게 짧게 했다. dl에 aria-busy를 둔다. 시각 테스트는 이미
`main [aria-busy='true']`가 0개가 될 때까지 기다리므로, dt만 보고 찍던
대기가 값이 채워진 뒤로 유지된다.
- lab: run마다 대상 라우트를 새 context에서 직접 열고 heading 뒤 network
idle까지의 CLS를 잰다(metrics.targetDeepLinkCls, 중앙값,
context.sampling.targetDeepLink에 표본). evaluateLabBudget가 lab.cls
임계값으로 판정한다. 클릭 시계(상호작용 중앙값)와 대상 라우트는 그대로다.
- 컴포넌트 테스트: 요약 전과 후의 칸 이름·hint 유무가 같다. 실패 테스트는
빌드 칸의 값으로 본다. 단위 테스트: 직접 진입 CLS가 임계값을 넘으면
lab 판정이 실패한다.
버린 대안: 릴리스 요약을 동기로 읽기 — getReleaseSummary()가 비동기
포트 계약이라 포트를 바꿔야 한다. 클릭 run에서 hadRecentInput을 무시 —
CLS 정의와 달라져 field 값과 비교할 수 없다.
위험·한계: lab 시간이 run마다 cold navigation 하나(lab 조건 약 2~3초)
늘어 5회면 +10~15초다. 직접 진입 CLS 예산은 0.1이라 0.0046 같은 작은
shift는 실패시키지 않고 lab.json에 값으로만 남는다. layout shift 0건은
lab 값(0)과 15-platform-shift 방법으로 확인해야 한다. 상태 문구가 바뀌어
"런타임 정보를 확인하고 있습니다." 문장은 이 화면에서 사라졌다(홈 화면
문구는 그대로). lab.json 스키마 문서(config/schemas/lab-performance.schema.json)에
새 칸을 필수로 더했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/component/starter-platform-overview-page.test.tsx
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(lab.json metrics.targetDeepLinkCls가 0인지)
Refs: 1105/15-01
문제: lab(FE-GATE-026)은 플랫폼 구성 화면(EXAMPLES_PLATFORM) 하나만 잰다.
이 화면은 기능 코드를 받지 않아 기능을 더해도 수치가 거의 그대로다
(146 → 154 ms). 기능 라우트는 처음 들어갈 때 context 라우트 모듈과 기능
실행부를 받고, 그다음 페이지 청크를 받는 두 번의 요청 묶음을 거친다.
lab 조건에서 EXAMPLES_UI 첫 진입은 중앙값 406 ms(403~410, 리뷰 15-R1)로
대상 화면의 2.7배인데 어느 게이트도 재지 않는다. 다운스트림의 화면은
모두 기능 라우트다.
고른 방법:
- labFeatureRoute(scripts/lib/lab-performance.ts): 설치된 기능이 가진,
세션 없이 열리는 첫 내비게이션 라우트. 템플릿에서는 EXAMPLES_UI다.
없으면 null이고 lab은 measured: false로 남기고 판정하지 않는다.
- lab은 run마다 `/`에서 그 라우트의 내비게이션 링크를 눌러 heading까지를
같은 페이지 시계로 잰다(새 cold context). metrics.featureRouteInteractionMs
(중앙값), context.sampling.featureRoute(표본, owner)에 남긴다. 기존 대상
라우트와 그 예산(200 ms)은 그대로라 회귀 비교가 이어진다.
- 예산 config/performance/budgets.json lab.featureRouteInteractionMs = 500 ms.
측정 406 ms(8a44226, i5-10400F, lab 조건)를 통과시키고, 지금 둘째 요청
묶음 크기(약 100 ms, 클릭 뒤 98~204 ms)의 왕복이 하나 더 붙으면 넘는다.
lab 자가 검사 fixture에 feature-route-over-threshold를 더해 이 예산이
실패할 수 있음을 매번 확인한다.
- 단위 테스트: 라우트 선택 규칙, 설치된 레지스트리에서의 선택, 커밋된
예산이 406 ms는 통과·516 ms는 실패·null은 판정 제외.
버린 대안:
- 두 요청 묶음을 하나로 줄이기(진입한 URL의 페이지 청크를 context 라우트
모듈과 같이 받기): 페이지 청크 이름이 context 라우트 모듈 안의 lazy()에만
있어, 첫 묶음에서 받으려면 초기 청크의 라우트 선언이 페이지 로더를 가져야
한다. 선언 모양·생성기·초기 JS를 바꾸는 일이라 이 커밋에서 하지 않았다
(결정 대기, performance-evidence.md에 적음).
- 처음에는 기록만 하기: 기록만 하면 늘어도 아무도 모른다. 측정값이 있으니
예산을 같이 둔다.
- 라우트별 예산 표: 다운스트림이 채워야 하는 표가 는다.
위험·한계: 예산 여유가 94 ms(23%)라 lab 호스트가 지금보다 20% 이상 느리면
기능 라우트 판정이 흔들릴 수 있다(0929/11-04 lab 부하 가드는 여전히 없음).
FE-GATE-026 시간이 run마다 cold navigation 하나(약 2~3초) 늘어 5회면
+10~15초다. 생성 기능의 목록 라우트는 session-required라 lab 대상이 되지
않는다. 기능 라우트의 heading은 계약 `title`과 같은 글자로 찾는다(대상
라우트와 같은 방식). CHANGELOG의 "기능 라우트 첫 진입은 어느 게이트도
재지 않는다" 제한 문장은 이 커밋에서 고치지 않았다(오케스트레이터 몫).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts
tests/unit/performance-budgets.test.ts
corepack pnpm build && corepack pnpm test:performance -- --runs=5
(featureRoute EXAMPLES_UI 중앙값이 500 ms 안인지, 표본 기록)
Refs: 1105/15-04
문제: 매뉴얼 1단계 예시 ID는 invoice-feature이고 11단계가
`test:sample-removal -- --feature=invoice-feature`로 그 기능을 지운다.
드릴은 제품 기능의 잔여를 src·tests 모든 파일에서 기능 ID의 대소문자 무시
부분 문자열로 찾았다. 템플릿 소유 tests/unit/create-feature.test.ts가 같은
예시 ID를 데이터로 51번 쓰므로, 다른 검사가 모두 통과해도
`fixture-id-residue: residue: tests/unit/create-feature.test.ts`로 rc=1이었다
(리뷰 16-R1). errors.md의 안내는 그 템플릿 파일을 고치라는 것이었다.
notice-feature, orders-feature, shop-feature 같은 이름도 같은 충돌이 난다.
고른 방법: 제품 기능의 잔여 판정을 scripts/lib/feature-residue.ts의
productFeatureResidue로 옮기고 범위를 나눈다.
- src: 지금처럼 경로나 내용에 기능 ID·폴더 이름이 있으면 잔여. 플랫폼
소스는 제품 기능을 이름으로 부르지 않으므로, 남은 이름은 타입 검사가 못
보는 참조(카탈로그 키, 런타임 오버라이드, 링크)다.
- tests: 파일 이름에 기능 ID가 있거나, 기능의 src/features/<dir>/ 또는
tests/features/<dir>/에서 import(동적 import, vi.mock 포함)하는 파일만
잔여. 테스트 본문에 ID를 글자로 적은 것은 세지 않는다. 지운 기능에 기대는
테스트는 같은 드릴의 test:all이 잡는다.
참조 샘플(reference-feature)은 템플릿이 모든 파일을 가지므로 기존 넓은
패턴을 그대로 쓴다. 빌드 산출물(dist) 잔여 검사도 그대로다.
단위 테스트: 저장소 자체(create-feature.test.ts 포함)를 invoice-feature로
훑으면 잔여 0, src/contracts에 ID를 남긴 파일·이름에 ID가 있는 e2e spec·기능
폴더 import는 잔여, 테스트 본문의 예시 데이터는 잔여 아님.
매뉴얼 01 11단계와 errors.md의 판정 문장·안내(템플릿 파일이 나오면 고치지
말고 템플릿에 알린다)를 고쳤다.
버린 대안:
- 제거 전에 한 번 훑어 이미 걸리던 파일을 제외: src/contracts에 남긴
잔여도 제거 전부터 ID를 담고 있으므로 같이 빠진다(완료 기준 둘째를 못
지킨다).
- 템플릿 테스트의 예시 ID를 예약 접두어로 바꾸기: 부분 문자열 검색이면
접두어를 붙여도 걸리고, create-feature.test.ts의 파생 이름 기대값
수십 곳을 함께 바꿔야 한다.
- 생성 명령이 템플릿 테스트에 나오는 ID를 거절: 목록이 따로 낡는다.
위험·한계: tests 안에서 기능 ID를 글자로만 담은 진짜 잔여(예: 기능을
import하지 않고 경로 문자열만 적은 테스트)는 이제 잔여로 나오지 않는다.
그런 테스트가 지운 기능에 기대면 test:all이 실패하고, 기대지 않으면 해가
없다. src 쪽 부분 문자열 검색은 그대로라 items 같은 짧은 ID는 플랫폼 소스의
글자에 여전히 걸릴 수 있다(이번 범위 밖). 실제 드릴 실행(198초)은 단위
테스트로 대신하지 못한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
16-R1과 같은 순서: create:feature invoice-feature --with-create --keyed 뒤
corepack pnpm test:sample-removal -- --feature=invoice-feature (rc=0 기대),
그리고 src/contracts/invoice-leftover.ts에 "invoice-feature"를 남긴 변이에서
rc=1(fixture-id-residue) 기대
Refs: 1105/16-04
문제: create:feature --with-create가 백엔드 생성기 템플릿의 사실 넷을
프론트 문자열로 옮겼다. 경로 복수형(scripts/new-feature.sh), 이름 상한 100
(__Feature__.java.tmpl NAME_MAX_LENGTH), 오류 code <FEATURE>_INVALID·
_NOT_FOUND(__Feature__ErrorCode·ControllerTest 템플릿), 201과 검사 순서
(Controller·Create__Feature__UseCase 템플릿)다. 그러나 pin
(config/contracts/backend-contract-pin.json)과 check:backend-contract-drift는
docs/web/http-contract.md(1105/07-01 뒤로는 그 문서의 표 사본과 답 표)만
본다. 백엔드가 템플릿을 바꾸면 생성 기능이 다른 경로·상한·code를 써도 아무
신호가 없다.
고른 방법: pin의 backend.scaffoldSources에 백엔드 템플릿 파일 여섯과 각
파일에서 옮긴 사실, 옮긴 프론트 위치(파일과 이름)를 적는다. drift 검사는
1105/07-01의 사본·답 표 대조와 종료 코드(0 일치, 1 어긋남, 2 비교 못 함)를
그대로 두고, pin 뒤 HEAD에서 이 파일들도 diff한다. 바뀐 파일마다 다시 볼
프론트 위치를 failures에 더해 exit 1한다. pin 단위 테스트는 각 항목의 프론트
이름이 실제로 그 파일에 있는지 본다. drift 단위 테스트는 07-01의 가짜 백엔드
fixture에 생성기 템플릿 파일 하나를 더하고, 그 파일이 바뀐 경우(exit 1, 프론트
위치 출력)와 pin이 이름 붙이지 않은 파일만 바뀐 경우(exit 0, "1 scaffold
sources unchanged")를 더한다. 07-01의 경우들은 그대로다. 계약 문서 4.1절과
생성기 머리 주석에 같은 내용을 적었다.
버린 대안: 백엔드가 생성기 사실을 JSON으로 내고 프론트가 읽기 — 두 repo를
바꿔야 한다(백엔드는 이번에 읽기만 한다).
위험·한계: drift 검사는 여전히 게이트 밖이고 형제 checkout이 있을 때만
돈다. 파일 단위 diff라 템플릿의 무관한 줄이 바뀌어도 알린다(사람이 다시
본다). pin의 commit(45d2a478)은 그대로다. 네 사실이 그 커밋과 같다는 대조는
리뷰(1105/16 영역)가 했고 이번에는 이름 상한만 다시 읽었다. 07-01과 같은
파일을 고쳐서 fix/r1105-contracts-core-sq 위에 다시 쌓았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-drift.test.ts
tests/unit/backend-contract-pin.test.ts
corepack pnpm check:backend-contract-drift (desktop 형제 checkout 기준, 참고)
Refs: 1105/16-02
문제: OIDC PKCE session owner 레시피가 sign-in transaction의
sessionStorage 키를 글자 그대로 적는다
(`"ca-frontend:auth:v1:oidc-pkce-transaction"`). 주석은
`buildPhysicalKey(...)`라고 하지만 함수를 부르지 않는다. 템플릿의 다른
Web Storage 키는 모두 `src/contracts/storage-keys.ts` registry가
`APP_NAMESPACE`로 만들고, 어댑터가 직접 쓰는 키도 `backend: "external"`
행으로 둔다. 그래서 제품이 `APP_NAMESPACE`를 바꾸면(memento 설계가
예정한 일) 이 키만 `ca-frontend:`로 남고, registry는 앱이 쓰는 Web
Storage 키 목록이 아니게 된다. registry로 로그아웃 때 지울 키를 정하는
제품은 버려진 sign-in의 verifier·state·nonce·돌아갈 경로를 지우지 못한다.
고른 방법:
- registry에 `AUTH_REDIRECT_TRANSACTION` 행을 둔다. `scope: "auth"`,
`name: "oidc-pkce-transaction"`, `backend: "external"`(pulse 키와 같은
모양, StoragePort는 거절), `ttl: "session"`. 물리 키는 지금 글자와 같다
(`ca-frontend:auth:v1:oidc-pkce-transaction`)라서 진행 중인 sign-in을
잃지 않는다.
- 레시피의 `OIDC_PKCE_TRANSACTION_KEY`는 그 행의 `physicalKey`다.
매뉴얼의 복사 규칙(`../../src/` → `../`)이 새 import에도 그대로 맞는다.
- 분류는 `opaque-cache`다. `sensitive-forbidden`은 "저장하지 않는다"는
뜻이고 backend가 disabled·forbidden이어야 해서 맞지 않는다. 이 값은
리다이렉트 한 번 동안 저장하는 것이 설계다.
- FE-REG-STORAGE의 `orphanExemptRows`에 이 행을 더한다
(`config/contracts/registry-governance.json`). 이 행을 쓰는 곳은 레시피
하나뿐이고, 레시피는 제품이 지울 수 있다(test:optional-recipe-removal).
행은 registry로 지울 키를 정하는 제품을 위해 남는다. `AUTH_TOKEN`처럼
사용처 없이 선언만 하는 행이다. 빼지 않으면 `src`만 복사해
check:registries를 돌리는 `tests/unit/second-api-feature-registries.test.ts`가
"has no executable consumer"로 실패한다.
버린 대안: consumer 폴더에 `recipes`를 더하기. 레시피를 지운 사본(FE-GATE-020)
에서 다시 사용처가 사라진다.
버린 대안: registry에 새 분류(예: `session-transaction`)를 더하기. 계약
타입의 union과 registry 기준선의 허용 값이 함께 바뀌는데, 분류가 코드
동작을 바꾸는 곳은 `sensitive-forbidden` 검사뿐이라 얻는 것이 없다.
위험·한계:
- `src/contracts/storage-keys.ts`에 행 하나가 더해진다(FE-REG-STORAGE
additive). CHANGELOG [계약] 행이 필요하다.
- 이미 레시피를 복사한 제품은 자기 복사본을 같은 diff로 고쳐야 키가
namespace를 따른다.
- orphan 검사가 이 행을 보지 않는다. 레시피가 키를 registry에서 가져오는지는
`tests/recipes/oidc-pkce-session-owner.test.ts`가 본다.
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/storage-registry.test.ts
tests/recipes/oidc-pkce-session-owner.test.ts
- corepack pnpm check:registries (additive 행)
- node scripts/run-vitest.ts run tests/unit/second-api-feature-registries.test.ts
- corepack pnpm test:optional-recipe-removal
Refs: 1105/05-01
문제: cross-context host는 `storage` 이벤트의 `storageArea`를 캡처한
`localStorage` 객체와 동일성으로 비교해 sessionStorage 등 다른 영역의 같은
key 이벤트를 거절한다(`browser-cross-context-host.ts` `storageEventTarget`).
transport 테스트는 core에 이미 판정된 영역 값을 넘기므로 이 비교를 지워도
(변이 N38) cross-context 테스트 46건이 모두 통과한다(1101/02-04 ②, 지난
커밋 `3bfe6a8`이 하네스가 필요해 미룸).
고른 방법: `createBrowserCrossContextInvalidationFromHost`에 탭 둘을 흉내 낸
host를 넘기는 단위 테스트를 둔다. host에는 BroadcastChannel이 없어 storage
pulse만 쓴다. 한 탭의 `localStorage.setItem`이 다른 탭 listener에 `storage`
이벤트를 보낸다. 이벤트의 `storageArea`가 받는 탭의 sessionStorage이거나
모양만 같은 다른 객체이면 구독자가 받지 않고, 받는 탭의 localStorage이면 한
번 받는다.
버린 대안: browser spec에 sessionStorage `storage` 이벤트 행을 더하기. 실제
브라우저 증거는 더 강하지만 3엔진 spec 시간이 늘고, 비교 하나를 고정하는 데는
host 단위 테스트로 충분하다.
위험·한계: 테스트만 더한다. 실제 브라우저의 `StorageEvent.storageArea`
동작은 이 테스트가 보지 않는다(기존 browser spec 몫).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/cross-tab-invalidation.test.ts
- 변이 N38: `storageArea === expectedLocalStorage` 비교를 지우면(늘
`EXPECTED_LOCAL_STORAGE`) 새 테스트가 실패해야 한다.
Refs: 1101/02-04
문제: `PublicResponseCacheAdminPort.inspect()`의 port 계약은 비용·취소·
판정 불가를 적지 않는다. `verified: false`가 "손상"인지 "읽지 못함"인지
알 수 없고, inspect가 모든 후보의 모든 entry를 다시 읽는다는 것도 port만
보고는 모른다. 판정 불가를 `verified: true`로 바꾸는 변이 M05가 cache 테스트
59건을 모두 통과한다(0929/02-02).
고른 방법:
- port 주석에 적는다. `releaseCandidates`는 entry를 모두 다시 읽어 채우므로
비용이 cache 수 × entry 수에 비례하고 cursor·deadline·signal이 없다.
`verified`는 모든 entry를 읽어 manifest와 맞을 때만 `true`이고, 없거나
다를 때와 읽지 못했을 때(본문 읽기·조회 실패) 모두 `false`다. 둘을 가르는
것은 activation이고, 같은 manifest로 다시 stage하면 둘 다 다시 쓴다
(1105/02-02).
- 테스트: 본문을 읽지 못하는 후보와 `cache.match`가 던지는 후보를 inspect가
`verified: false`로, 성한 후보를 `true`로 보이는지 고정한다. M05를 잡는다.
남긴 것(일부): inspect에 `signal`을 더하거나 판정 불가를 따로 보이는 칸을
더하지 않았다. 둘 다 port 모양을 바꾸고, VD-15 목표 runtime(cursor·deadline)과
같이 정할 일이다. service-worker-pwa 번들 여유(342 B)도 좁다. 결정은 템플릿
소유자 몫이다.
위험·한계: 동작 코드는 바뀌지 않는다(주석과 테스트만).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
- 변이 M05: `inspect`의 `verified: candidate.kind === "VERIFIED"`를
`candidate.kind !== "REPAIRABLE"`로 바꾸면 새 테스트가 실패해야 한다.
Refs: 0929/02-02
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).
고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
(`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.
위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.
고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.
위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal
Refs: 1105/16-01
문제: responseEnvelope는 descriptor의 선택 칸이고 없으면 "NONE"이다.
1103/16-01 수정은 계약 조립이 한 기여 안에서 값이 섞이면 거부하고,
refusedBeforeWrite가 있는 쓰기에 Envelope를 요구하게 했다. 그러나 읽기만
있는 기여(기본 생성 판)나 refusedBeforeWrite 없는 쓰기에서 줄을 모두 빼면
조립은 통과하고(모두 같은 NONE), 짝 백엔드의 Envelope를 DTO로 읽어
SCHEMA_MISMATCH로 깨지는 것은 손글씨 gateway 테스트만 잡는다. 지난 완료
기준("줄을 지우면 check:types가 실패한다")을 채우지 못했다.
고른 방법(1103 대안 (b)): InstalledHttpContract의 contract.responseEnvelope를
필수로 바꾼다. 생성 기능·참조 기능·예제의 descriptor는 모두
`satisfies InstalledHttpContract<...>`라 줄을 지우면 tsc가 그 자리에서
실패한다. 줄이 없던 descriptor에 "NONE" as const를 적었다: 참조 기능 셋,
tests/helpers/external-contract-fixture.ts 셋,
tests/contract/reusable-capability/feature-http-binding.test.ts,
scripts/drill-runbook.ts. 값은 전과 같아 FE-REG-API 행과 레지스트리 기준선은
바뀌지 않는다. 조립(external-contract-runtime.ts)은 그대로 빠진 값을 NONE으로
읽는다: TypeScript 밖에서 만든 descriptor를 런타임에 거부하지 않는다.
생성기 주석의 "줄을 지운다" 안내를 "NONE을 적는다"로, 매뉴얼 01(3단계,
짝 백엔드가 아닌 백엔드), errors.md, 계약 문서 4.1절을 같은 뜻으로 고쳤다.
테스트: external-contract-runtime.test.ts에 줄을 뺀 descriptor 선언 위
@ts-expect-error를 두었다. 타입이 다시 선택 칸이 되면 그 지시문이 쓰이지
않아 check:types:test가 실패한다. 같은 테스트가 런타임 조립은 NONE으로
읽는지도 본다.
버린 대안: (c) 기여 단위 기본값 — 규칙이 하나 는다. (d)만으로 두기 — 모두
빠진 경우를 못 막는다. 조립에서 빠진 키를 거부 — JS로 만든 계약 패키지가
런타임에 깨지고, 빠진 값을 일부러 다루는 테스트를 모두 바꿔야 한다.
위험·한계: descriptor를 직접 쓰는 다운스트림 코드는 줄을 더할 때까지
check:types가 실패한다. 모든 operation에 같은 틀린 값을 적는 것(짝 백엔드인데
모두 "NONE")은 여전히 타입도 조립도 통과한다(매뉴얼 "못 잡음"). 이 노트북에서
tsc를 돌리지 못해, 놓친 descriptor가 있으면 desktop check:types가 알려 준다.
검증: desktop batch에서 확인.
corepack pnpm check:types
node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts
tests/features/reference-feature tests/unit/api-operation-rows.test.ts
corepack pnpm check:registries (compatibility 변화 없음 기대)
BREAKING CHANGE: src/contracts/external-contract-runtime.ts의
InstalledHttpContract에서 contract.responseEnvelope가 필수다. 이 줄이 없는
descriptor는 check:types에서 실패한다. 감싸지 않는 백엔드는
responseEnvelope: "NONE" as const, 짝 백엔드(Envelope)는 "ENVELOPE_V1" as const를
operation마다 적는다. 런타임 동작은 같다.
Refs: 1103/16-01
문제
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
문제
짝 백엔드 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
문제
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
문제
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
문제
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
문제
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
문제
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
문제
home-page.tsx의 STARTER_ROUTES는 모듈을 불러올 때 NAVIGATION_ROUTES에서
APP_HOME을 빼고 앞 3개를 고른다. 기능이 켜져 있는지는 보지 않는다. 셸 탐색은
같은 목록을 runtime.isFeatureActive(owner)로 거르고, 라우터는 꺼진 기능의
라우트에 사용 중지 화면을 그린다. 그래서 운영자가 런타임 설정으로
platform-examples-feature를 끄면 홈의 주요 버튼 셋 중 둘(/examples/ui,
/examples/states)이 사용 중지 화면으로 간다(리뷰 08-R1 C, 1103/09-04 수정
b96d61d8이 만듦).
고른 방법
셸과 홈이 같은 함수를 쓴다. navigation-policy.ts에 activeNavigationRoutes
(isFeatureActive)를 두고(설치된 레지스트리를 읽어도 되는 기존 예외 파일이다),
셸 탐색과 홈 시작 링크가 렌더 때 그 목록을 읽는다. 홈은 그 뒤에 APP_HOME을 빼고
앞 3개를 고른다. 홈은 여전히 기능 라우트를 이름으로 부르지 않는다(1103/09-04의
보존 조건). 테스트는 platform-examples-feature 테스트 폴더에 두어 기능을 지울 때
함께 지워진다.
버린 대안
홈에서만 같은 filter를 한 번 더 쓴다: 셸과 홈의 조건이 다시 갈라질 수 있다.
위험·한계
빌드에서 뺀 기능은 처음부터 목록에 없으므로 해당 없다. 시작 링크가 셋보다 적을
수 있다(템플릿에서 예제를 끄면 둘).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/features/platform-examples-feature/example-pages.test.tsx
tests/component/product-feature-switch.test.tsx tests/component/starter-pages.test.tsx
tests/unit/navigation-policy.test.ts
Refs: 1105/08-03
문제: 다섯 Playwright 설정의 서버 포트가 고정이다(e2e 4173, visual과
capability가 둘 다 4174, storybook 6006, dev 5173). 한 checkout이든 같은
기계의 두 worktree든 두 번째 실행은 `http://127.0.0.1:4173 is already
used`로 시작하지 못한다(00-R1). dev 설정만 `reuseExistingServer: true`라
5173에 다른 checkout·브랜치의 dev 서버가 떠 있으면 말없이 그 서버를
검사한다. vite는 `--strictPort` 없이 떠서, 포트가 그 사이 잡히면 다음
포트로 옮기고 Playwright는 원래 URL의 남의 서버를 검사할 수 있다
(1105/12-04).
고른 방법: 설정마다 `reservePort(TEST_<이름>_PORT)`로 빈 포트를 고른다
(`scripts/lib/run-isolation.ts`). 커널이 port 0에 준 포트를 받고 바로
닫는다. 고른 포트를 그 변수에 써 둔다. Playwright는 worker마다 설정을
다시 평가하고 worker는 runner 환경을 물려받으므로, worker의 평가가 같은
포트를 읽어 `baseURL`이 어디서나 같다. 변수를 미리 주면 그 포트를 쓴다
(디버깅용 고정). vite 서버 넷 모두 `--strictPort`로 띄우고, dev 설정은
`reuseExistingServer: false`로 바꿨다. run ID가 없어도 빈 포트를 쓴다.
두 worktree는 출력 경로가 이미 다르고 포트만 부딪히기 때문이다. 고정
번호를 읽는 곳은 없다. spec은 `baseURL`에서 origin을 얻는다
(`resumable-upload.spec.ts`, `production-csp.spec.ts`).
버린 대안: 포트 범위를 run ID에서 계산하기. 두 checkout이 같은 run ID를
쓰거나 다른 프로그램이 그 포트를 쓰면 다시 부딪힌다. Playwright
`webServer.wait`로 서버가 고른 포트를 stdout에서 읽기: `use.baseURL`은
설정을 읽을 때 정해져서 쓸 수 없다.
위험·한계: 포트를 고른 뒤 서버가 잡기 전에 다른 프로세스가 같은 포트를
잡을 수 있다. 그때는 `--strictPort`/serve-static의 listen 실패나
Playwright의 "already used"로 시작이 실패한다. 남의 서버로 검사가 새지
않는다. 기본 실행의 포트 번호가 매번 달라진다. 고정이 필요하면
`TEST_E2E_PORT=4173`처럼 준다. `test:e2e:dev`는 이제 떠 있는 dev 서버를
쓰지 않고 자기 서버를 띄운다. capability 설정이 없는 사본
(test:browser-file-storage-removal)에서는 그 설정의 포트 테스트를 돌리지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제: 실행 격리(앞 두 커밋)의 변수(`TEST_RUN_ID`, `RUN_OUTPUT_ROOT`,
`TEST_*_PORT`)와 "게이트는 한 checkout에서 하나씩"이라는 전제가 어디에도
적혀 있지 않다. 테스트 전략 13.1은 dev E2E가 떠 있는 서버를 재사용한다고
적고 있어 바뀐 동작과 다르다(1105/12-04 "결정의 근거"는 이 선택이 어디에도
적혀 있지 않다고 지적했다).
고른 방법: 테스트 전략에 13.6절을 더한다. 핵심, 흐름도, 변수 표, 두 실행
예, 한계(게이트·증거 검사는 기본 경로만 읽음, 같은 run ID, 선택이 다른 두
실행의 `src/.generated`, Storybook 캐시, `.tmp/runs` 정리)를 적는다. 13.1의
재사용 문구를 고친다. 매뉴얼 "merge 전에 돌릴 것"과 README 게이트 반복문
아래에 짧게 적고 13.6절을 가리킨다.
버린 대안: README에 표 전체를 두기. README는 게이트를 돌리는 법만 적고
상세는 테스트 전략 문서에 두는 지금 구조를 따른다.
위험·한계: 문서만 바꾼다. 경로·스크립트 이름·링크는 verify:documentation이
검사한다.
검증: desktop batch에서 확인.
corepack pnpm verify:documentation
Refs: 1105/12-04
문제
템플릿은 지울 수 있는 기능을 둘 둔다. 참조 기능(README)과 예제 화면
기능 platform-examples-feature(starter-experience.md, CHANGELOG 6단계)다.
그 기능이 가진 경로는 제거 드릴의 SAMPLE_EXTRAS에만 있다. 그래서 문서
검사가 "이 경로는 지운 템플릿 기능의 것"을 알 길이 없다(1105/14-01,
14-03). 문서 검사가 따로 목록을 가지면 드릴과 갈라진다.
고른 방법
- scripts/lib/removable-template-features.ts에 두 기능을 적는다. 기능
ID(= src/features·tests/features 폴더 이름), 혼자 속한 context, 폴더 밖
전용 파일, 전용 package script.
- 드릴은 참조 기능의 전용 파일·script를 이 모듈에서 읽는다. 목록 내용과
주석은 그대로 옮겼다. 동작은 바뀌지 않는다.
- 예제 기능 항목은 다음 커밋(1105/14-01)의 문서 검사가 읽는다. 드릴은
예제 기능을 지금처럼 locateFeature로 찾는다.
- 버린 대안: 문서 검사 안에 목록을 따로 두기. 드릴의 SAMPLE_EXTRAS와 두
벌이 된다.
위험·한계
- 동작 변경은 없다. 드릴 출력과 지우는 경로가 같다.
검증
- desktop batch에서 확인: corepack pnpm check:types, corepack pnpm lint,
node scripts/run-vitest.ts run tests/unit/feature-removal-argument.test.ts
Refs: 1105/14-01, 1105/14-03
문제
CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능
폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세
폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과
FE-GATE-005의 documentation-readiness "passes the documents as they are"가
"starter-experience.md names paths that do not exist"로 실패한다(리뷰
14-R1). 그 문서가 안내한 드릴(test:sample-removal
--feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를
적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다.
PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿
문서를 고치면 동기화마다 그 줄이 충돌한다.
고른 방법
- 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그
기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그
경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트
폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라
feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴
채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는
폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다.
- tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용
기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다.
- 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소
사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의
verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로
지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의
잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히
실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에
더했다.
- PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙),
docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더,
generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다.
- 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또
좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가
없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c)
FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새
unit 테스트가 merge 단계에서 본다.
위험·한계
- 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit
시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다.
- 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다.
알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다.
- RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal --
--feature=platform-examples-feature
Refs: 1105/14-01
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
문제
매뉴얼 04 §3.2의 PRODUCT_ENV_REGISTRY 예시 두 행(OIDC_ISSUER,
OIDC_CLIENT_ID)에 defaultValue가 없다. 행 타입은 defaultValue를 필수 칸으로
가진다(src/contracts/env.ts). 그래서 제품이 그대로 붙이면 check:types:app이
env.ts에서 TS2322로, env-registry-coverage가 `row {"required":false}`로
실패한다(리뷰 14-R3). 매뉴얼 03 C절과 product-contracts.ts 주석은
defaultValue를 쓴다.
고른 방법
- 두 행에 `defaultValue: null`을 더하고(.optional() 키), 행 칸의 규칙을
예시 아래 한 줄로 적었다.
- 테스트 tests/unit/manual-paired-backend-settings.test.ts: 매뉴얼 §3.2의 ts
블록을 그대로 저장소 사본의 새 파일로 두고, 사본의 product-contracts.ts가
제품 자신의 파일(옆에 보존)에 그 키를 더해 내보낸다. 그 사본에서
tsconfig.app.json 타입 검사와, env-registry-coverage와 같은 행 대조(키가
없을 때 스키마가 내는 required·defaultValue)를 node로 돌린다. 제품 파일을
덮어쓰지 않으므로 다운스트림에서도 그대로 돈다(1105/09-01과 같은 방식).
- 문서를 읽는 테스트라 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. 그 목록의
항목이 문서를 읽는지 보는 removal-fixture.test.ts 정규식에 `docs/`를
더했다. 문서 대상(REMOVAL_FIXTURE_DOCUMENT_TARGETS)에 docs가 있어 README나
CHANGELOG를 읽지 않는 문서 테스트도 있을 수 있다. 목록의 뜻은 그대로다.
- 버린 대안: 예시 행을 recipe에서 export하고 recipe 테스트가 그것으로
조립하기(리뷰 ②). contracts가 recipe를 import할 수 없어 매뉴얼이 다시
복사를 시킨다. 이번 테스트가 매뉴얼 블록 자체를 지킨다.
위험·한계
- 행 대조는 env-registry-coverage의 schemaDeclaration을 이 테스트 안에 다시
적었다(사본에서 vitest를 띄우지 않으려고). 규칙이 바뀌면 둘을 함께 고친다.
- §3.3·§4.3의 코드 예시는 여전히 컴파일하지 않는다(recipe를 복사한 뒤의
모양이라 사본 구성이 더 크다).
- 테스트가 저장소 사본을 만들고 tsc app 프로그램을 돈다. test:unit이 몇 초
는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/manual-paired-backend-settings.test.ts
tests/unit/removal-fixture.test.ts, corepack pnpm verify:documentation
Refs: 1105/14-02
문제
미출시 11-03 절(752a61f → fix/maturity-review-2026-11-03)은 머리 규칙이
"최종 상태만 적는다"인데 세 곳이 중간 상태나 틀린 이름을 적는다.
- 초기 JS 파일 상한: BREAKING 7단계와 FE-GATE-012 [계약] 행이 "26개"다.
코드는 32다(config/performance/budgets.json, 2fef27d). 같은 절의 X2 줄은
32라고 적는다. [계약] 행이 인용한 1b8cb12(26으로 올림)는 범위 안에서
2fef27d가 다시 바꾼 중간 상태다.
- 알려진 제한 머리가 "이 절을 쓴 끝 커밋(f887817)"이다. 범위 끝은
8a44226이다.
- "옮긴 뒤 확인" 2단계가 "로컬 merge 게이트 14개 중" 목록에
verify:documentation(FE-GATE-017)과 제품 기능 제거 드릴을 둔다.
FE-GATE-017은 documentation 단계이고(config/ci/gates.json), 제품 기능
드릴은 어느 게이트도 돌리지 않는다(FE-GATE-020은 참조 기능만).
고른 방법
- 두 곳의 상한을 32(템플릿 26 + 기능 여유)로 고치고, [계약] 행 커밋을
1b8cb12 대신 2fef27d로 적었다. 템플릿 자체의 파일 수 26은 따로 적었다.
- 알려진 제한 머리를 범위 끝 8a44226 기준으로 바꿨다. 2026-11-05 리뷰
영역 14가 8a44226에서 그 줄들을 대조했다(낡은 줄은 지난 라운드에 빠짐).
위 절(2026-11-05 조치)이 바꾼 줄은 위 절에 적는다고 밝혔다.
- merge 단계에서 문서 검사를 하는 것은 FE-GATE-005의
documentation-readiness라 test:unit 줄에 넣고, FE-GATE-017과 제품 기능
드릴은 "merge 게이트 밖" 단계로 나눴다.
위험·한계
- 문서만 바꿨다. 1,873 B 여유는 기록 값이다(빌드마다 수십 B 다르다).
- 위 절이 바꾸는 알려진 제한 줄(기능 라우트 첫 진입, SW composeProduct 칸
등)은 위 절 행을 쓸 때 함께 고친다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1103/14-01, 1103/15-02
문제
11-03 절의 realtime BREAKING 행은 "poll은 던지는 execute도 lease 안에서
다시 시도한다"고 적는다. 그 범위 끝(8a44226)에서는 사실이지만, 같은 동기화
때 함께 받는 위 절의 05330e3(1105/04-02)이 던지는 execute를 재시도 없이
PROTOCOL_MISMATCH로 끝내게 바꿨다. 두 절을 함께 받는 제품은 아래 절의
문장대로 재시도를 기대한다. 그 커밋 본문도 이 행이 맞지 않는다고 적는다.
고른 방법
- 아래 절 행은 그 범위 끝의 사실로 두고, 위 절에서 바뀐 것과 새 결과를 한
문장으로 붙였다. 위 절의 BREAKING 행은 PR B 행을 쓸 때 05330e3 본문으로
적는다.
- 버린 대안: 아래 절 문장을 지우기. 그 절은 한 동기화 단위의 순 요약이라
위 절만 받지 않은 프로젝트가 읽을 수 있다.
위험·한계
- 문서만 바꿨다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1105/04-02
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
`RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
answers from the backend table rows at the pin"이 "is both copied and
listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
Refs: 1105/03-02, 1105/07-01
문제
"옮기기 전" 2단계는 "제품이 고친 템플릿 파일을 뽑는다"며 memento 7개,
tech-log 11개를 적는다. 실제로 af3d8e6 뒤 고친 템플릿 src 파일(기능·
context 폴더 밖)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38,
추가 2)다(리뷰 영역 14 E-4). 빠진 파일 중 일부는 이 묶음에 옮길 제품 소유
자리가 있고, 일부는 없다. 목록에 없으면 동기화 때 충돌이나 조용한 유지로
드러난다.
고른 방법
- 두 다운스트림(memento d3810a0, tech-log 7a4e201a)에서
`git diff --name-status af3d8e6 HEAD -- src`와 파일별 diff를 읽어(쓰기
없음) 2단계에 세 항목을 더했다.
- 자리가 있는 것: tech-log release-artifacts.ts의 TECH_LOG_*_SOURCE
→ PRODUCT_RUNTIME_CONFIG_FIELDS, memento offset-upload.ts와 HTTP 배럴
export → product-composition 쪽 제품 파일(그 파일은 contracts만
import한다), tech-log 라우팅 파일과 참조 기능 계약의 layoutGroup → 3단계
기능 모듈 길.
- 자리가 아직 없는 것: memento의 if-match 요청 헤더, SW 오프라인 shell과
사전 캐시 확장자, 저장소·OPFS 이름, 앱 이름 문구, 브랜드 토큰·
primitive. tech-log의 AppFailure.detail, BoundMutation.identity,
null을 빈 상태로 보기, 폼, 디자인 시스템, 문구, 전역 스타일 import.
- 템플릿 결함 후보: tech-log application-query.ts의 "마운트한 같은 턴의
저장" 수정. 템플릿은 재현하지 않았다.
- 알려진 제한에 "자리 없는 것은 이 묶음이 옮길 곳을 주지 않는다"를 더했다.
- 버린 대안: 파일마다 옮길 곳을 정하기. 템플릿에 자리를 만들지는 각각
설계 결정이다(결정 대기).
위험·한계
- 일부다. 자리 없는 항목마다 템플릿이 자리를 줄지, 제품 fork로 둘지는
정하지 않았다. 안내를 제품 코드에 적용해 게이트를 돌리지 않았다.
- 분류는 diff를 읽은 판단이다. 파일 안의 모든 변경을 확인하지는 않았다
(예: tech-log 디자인 시스템 primitive 3개는 줄 수만 봤다).
검증
- 문서만. desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1103/14-02, 0929/14-03, 0929/14-06
문제
CHANGELOG 머리는 리뷰 ID를 `MMDD/NN-MM`과 `F-N`으로만 정한다. 본문에는
`1101 README 14.3`, `1103 07 영역 P-07-06`, `백엔드 리뷰 1101/02-01`,
"리뷰 조치 X2"가 섞여 있다. 마지막은 라운드가 없어 어느 리뷰인지 찾을 수
없다. changelog-review-ids 테스트는 `NN-MM`·`F-N`만 본다(1101/14-02 잔여).
고른 방법
- 머리에 세 꼴을 적었다: `MMDD README N.N`(다시 돌린 항목은 뒤에 `X2`),
`MMDD NN 영역 P-NN-NN`, `백엔드 리뷰 MMDD/NN-MM`. 지금 본문의 참조는 이
꼴이다.
- "리뷰 조치 X2"를 `1103 README 14.6 X2`로 고쳤다(2fef27d 등의 Refs가 그
절을 가리킨다).
- 테스트 "cites README sections and other review references with their
round": 괄호 안 토큰 중 README 절·X 번호·P-ID·백엔드 리뷰를 담은 것이 이
꼴과 다르면 실패한다.
- 버린 대안: README 절도 `MMDD/README-14.3` 같은 한 꼴로 바꾸기. 본문 9곳과
커밋 Refs의 쓰임을 함께 바꿔야 해서 얻는 것보다 바꿀 것이 많다.
위험·한계
- 괄호 밖에 적은 참조는 보지 않는다(기존 테스트와 같다).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
RED: 부모 CHANGELOG에서 새 테스트가 ["리뷰 조치 X2"]로 실패한다.
Refs: 1101/14-02
문제
ci-quality-gates.md의 기준선 표는 지운 기능의 FEATURE_OVERRIDES 키가
"조용히 무시된다"고 적는다. 코드는 그 키를 무시하지만 조용하지 않다.
check:release-admission(FE-GATE-027)이 `release admission warning:
FEATURE_OVERRIDES.<id> … the override does nothing`을 내고
(scripts/check-release-admission.ts), 부팅이 진단 feature.override.unknown
(warn)을 남긴다(src/bootstrap/runtime-adapters.ts). 운영자는 경고를 오류로
오해하거나, 문서대로 아무 신호도 없다고 생각한다(0929/14-05).
고른 방법
- 표의 "검사 위치" 칸을 코드대로 고쳤다: 실패하는 검사는 없고, 두 곳이
경고를 남긴다.
위험·한계
- 문서만 바꿨다. 경고 문구가 바뀌면 이 칸도 고친다(문서 검사는 문구를
대조하지 않는다).
검증
- desktop batch에서 확인: corepack pnpm verify:documentation
Refs: 0929/14-05
문제
docs/README.md 3절은 루트의 SPEC.md·tasks/를 "2026-09-25 라운드가 쓰는
중이라 docs/ 밖에 그대로 둔다"고 적는다. 그 라운드는 0.2.0(2026-09-27)으로
끝났다. 이유가 낡아서 복사한 프로젝트가 지워도 되는지, 템플릿이 왜 루트에
작업 기록을 두는지 알 수 없다(0929/14-01 잔여).
고른 방법
- 이유를 지금 사실로 고쳤다: 라운드는 끝났고, 그때 리뷰 문서가 이 경로
(`SPEC.md:18` 등)로 가리키므로 옮기지 않는다. 지워도 되는 기록이라는
것은 README "Files you can delete after copying"이 그대로 적는다.
- 버린 대안: 두 기록을 docs/superpowers/ 아래로 옮기기. docs/reviews/의
지난 리뷰가 루트 경로로 가리키는데, 리뷰 이력은 고치지 않는다.
위험·한계
- 위치는 그대로라 복사 대상 루트에 작업 기록이 남는다. 지우는 것은
복사한 프로젝트의 몫이다(README 표). 0929/14-01은 일부로 남는다.
검증
- desktop batch에서 확인: corepack pnpm verify:documentation
Refs: 0929/14-01
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘.
- 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가
`scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해
빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다.
1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로
옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에
`scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면
`tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고,
임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로
실패한다.
- `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정
브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01
문제
README "Updating a copied project"는 미출시 절을 한 범위로 받으라고 하면서
명령은 커밋 하나의 cherry-pick과 git diff뿐이다. 두 다운스트림이 실제로
쓰는 범위 merge(memento, 이력 공유)와 3-way 이식(tech-log, 이력 없음)은
없다. 기준점 기록도 .template-origin 하나만 적고, tech-log의
template.lock.json은 CHANGELOG에만 있다(0929/14-02 잔여).
고른 방법
- 범위를 받는 두 길을 명령과 함께 적었다: 이력을 공유하면 범위 브랜치를
`git merge --no-ff`, 아니면 범위 기준점을 base로 둔 3-way 병합
`git merge-recursive <range base> -- HEAD template/<range branch>`(tech-log가
2026-09-29 동기화에 쓴 명령, 그 repo의 template-sync-2026-09-29.md).
- 기준점은 .template-origin이나 제품의 lock 파일(tech-log의
template.lock.json sourceRevision)에 두고, 범위를 받은 뒤 범위 끝으로
옮긴다고 적었다.
- 버린 대안: 동기화 스크립트를 템플릿에 두기. 두 제품의 방식이 달라
설계가 필요하다.
위험·한계
- 명령을 이 커밋에서 실행해 보지 않았다. 두 다운스트림이 지난 동기화에 쓴
명령을 옮겨 적었다(memento: git merge --no-ff, tech-log: git
merge-recursive). 충돌 처리 안내는 없다.
검증
- desktop batch에서 확인: corepack pnpm verify:documentation
Refs: 0929/14-02
문제
새 미출시 절(409d72e → fix/maturity-review-2026-11-05)에는 PR A 조치 셋만
있다. PR B(fix/maturity-review-2026-11-05-b)는 그 위에 비병합 커밋 70개를
쌓았고, 그중 `!` 커밋 다섯(1105/03-01, 1105/04-02, 1103/16-01, 1103/16-05,
1103/11-01)은 복사한 프로젝트가 코드를 바꿔야 한다. 커밋 본문이 "CHANGELOG
[계약] 행이 필요하다"고 적은 변경과 결정 대기·백엔드로 넘김·일부 항목도 이
절에 없다. 11-03 절의 알려진 제한 세 줄(기능 라우트 첫 진입, 참조 기능의
responseEnvelope, SW composeProduct 칸)은 PR B가 바꿨다.
고른 방법
- 절 머리의 범위 끝을 fix/maturity-review-2026-11-05-b로 바꾸고, 앞의 세
조치가 PR A(PR #5)에 있다고 한 줄로 적었다. PR A 행은 그대로 두었다.
- 11-03 절과 같은 모양으로 "먼저 할 일(BREAKING)"을 두었다. 옮기는 법 10단계
(responseEnvelope, MutationOperationId, refusedBeforeWrite 플랫폼 code,
poll execute, a11y.json v2, scope participant label, 레시피 복사본,
SW 칸, 제품 게이트의 workflow 재생성, 기능 안 adapters/ 밖 import)와 옮긴
뒤 확인.
- 보안·계약 표에 [계약] 행을 더했다: CI·게이트(13-02, 12-01 기준선,
12-04 TEST_RUN_ID·RUN_OUTPUT_ROOT·TEST_*_PORT, 12-02, 14-01·14-03,
0929/12-03 아키텍처 규칙, a11y.json, lab 예산, 기록 허용 오차, test:all,
제거 드릴 잔여), HTTP·계약, server-state, realtime, bootstrap·세션,
저장소·캐시(scope_participant 진단 키, chunkSweep deprecated,
UNREADABLE·REHYDRATE, AUTH_REDIRECT_TRANSACTION 행), SW·호스팅. `!` 커밋
다섯은 **BREAKING**으로 표시했다. 나머지는 "그 밖의 수정"에 영역별로 적었다.
- 이 절의 알려진 제한에 커밋 본문의 결정 대기·백엔드로 넘김·일부를 한 줄씩
적었다. 기능 라우트 첫 진입 줄은 지금 상태(lab이 EXAMPLES_UI를 500 ms로
잰다, 요청 두 묶음은 남음)로 적었다.
- 11-03 절의 세 줄은 그 범위 끝의 사실로 두고 위 절에서 바뀐 것을 붙였다.
- PR B의 비병합 커밋 70개가 모두 행이나 줄에 해시로 있다. 기준점 409d72e를
빼면 이 절의 해시는 모두 409d72e..이 브랜치 끝에 있다.
위험·한계
- 이 브랜치(fix/r1105-docs-v2) 커밋의 해시도 인용했다. 통합 때 이 브랜치를
다시 쌓으면(fixup 접기 등) 그 해시 11개를 새 값으로 바꿔야 한다.
- 안내를 두 다운스트림 코드에 적용해 보지 않았다. 1105/12-01 기준선 행의
"제품이 기준선을 다시 기록해 두었다면 다시 기록한다"는 67082cc 본문에서
추론한 것이다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1105 PR B (fix/maturity-review-2026-11-05-b)
문제: PR B 브랜치를 모두 합친 빌드의 초기 JS가 기록
(`config/scale/feature-shape-ceilings.json`의 `initialJavascript`)과
1,184 B, 파일 하나 다르다(202,927 B·26개 → 204,111 B·27개). 그래서
`tests/unit/feature-shape-growth.test.ts`가 "initialJavascript is stale"로
실패한다. 브랜치마다는 기록과 맞았고(15-02 전 브랜치는 허용 오차 1%,
15-02 뒤는 256 B), 합친 뒤에만 넘는다. 합칠 때마다 잰 증가:
- HTTP 판정·폼 브랜치 +632 B, 초기 파일 하나(`navigation-policy`). 08-03에서
홈 페이지도 `navigation-policy.ts`를 읽게 되어, boot와 홈 페이지가 나눠
갖는 청크로 떨어졌다.
- 브라우저 파일·캐시·저장소 +308 B, 계약 +148 B, realtime +72 B,
테스트 +23 B, 성능·구조 +1 B.
고른 방법: 합친 끝에서
`node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로
다시 적는다(1103 통합의 `f887817`과 같다). `perContextGzipBytes`도
233 → 218 B로 바뀐다.
버린 대안: `navigation-policy`를 기존 청크 그룹에 넣기. 청크 그룹 규칙
(15-01) 변경이라 여기서 정하지 않는다.
위험·한계: 초기 JS 예산 204,800 B(`config/performance/budgets.json`)까지
남은 여유가 689 B다. 기능 하나가 더하는 768 B보다 작다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
Refs: 1105/15-02, 1105/08-03
문제: 1105 PR B의 수정이 템플릿 초기 JS를 1,184 B 늘렸다(202,927 →
204,111 B, 초기 파일 26 → 27개, `0fee3fe`). 예산 204,800 B까지 남은 여유가
689 B로, 기능 하나가 더하는 768 B보다 작다. FE-GATE-020의 생성 기능
드릴이 기능 둘을 더하면 205,463 B가 되어 check:bundle이 "over by 663"으로
실패한다. PR A 끝(`a793b83`)에서는 통과했다.
늘어난 곳(desktop, 2026-11-06, 커밋마다 `--initial-baseline`으로 잼):
- 1105/03-01 `ab0d4a1` +327 B: 조립 때 `refusedBeforeWrite` code 검사
- 1105/08-03 `7ce9bf1` +293 B, 초기 파일 +1: `navigation-policy` 공유 청크
- 1105/02-01 `f738348` +251 B: scope closer 진단
- 계약·앱 코어 브랜치를 합칠 때 +148 B
- 나머지 +165 B: realtime +72 B, 05-01 +46 B, 테스트 +23 B, 03-02 +15 B와
합칠 때의 압축 차
고른 방법: `config/performance/budgets.json`의 `initialJsGzipBytes`를
204,800 → 206,848 B(202 KiB)로 올린다(메인 세션 결정, 2026-11-06). 늘어난
바이트는 비대가 아니라 검사와 진단 코드다. 이유와 재검토 조건을
`docs/operations/performance-evidence.md`에, 계약 행을 CHANGELOG 미출시 절에
적는다. 초기 파일 상한을 26 → 32로 올린 `2fef27d`와 같은 방식이다.
버린 대안: 줄이기. 08-03 청크를 기존 청크 그룹에 넣으면 약 240 B가 돌아올
것으로 본다(추정, 재지 않음). 663 B에는 모자라서 03-01·02-01의 런타임 검사를
빌드 시점으로 옮기는 설계 변경이 더 필요하다. 리뷰 라운드 중간의 설계
변경은 다음 라운드의 숫자를 흐린다.
위험·한계:
- 올린 뒤 여유는 템플릿 그대로 2,737 B(768 B 기능 셋), 드릴이 기능 둘을
더한 뒤 1,385 B다. 기록 대조 허용치 256 B(1105/15-02)는 두 여유보다 작다.
- 재검토 조건: 예산을 다시 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을
정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터
본다. 이 상향은 13-03을 정하지 않는다.
- 기준선 기록(`initialJavascript`)은 앞 커밋 `0fee3fe`이 측정 스크립트
`--initial-baseline --write`로 다시 썼다. 이 커밋은 기록을 바꾸지 않는다.
검증: desktop batch에서 확인.
corepack pnpm ci:gate FE-GATE-020 (CI env)
node scripts/run-vitest.ts run tests/unit/performance-budgets.test.ts tests/unit/check-bundle-output.test.ts tests/unit/feature-shape-growth.test.ts
Refs: 1105/15-02
문제: 1105 리뷰 README에는 수정 라운드의 기록이 없다. 1103 리뷰는 14절에
방법·결정·통합 문제·발견별 상태를 적었다. 초기 JS 예산 상향(D7)은 결정이라
이유·대안·재검토 조건을 남겨야 한다.
고른 방법: README 16절에 방법, 결정 표(7절 D1~D6의 결과, 새 D7과 그 근거: 커밋별 증가와 올린 뒤
여유), 합칠 때 생긴 문제와 고친 위치, 새 발견 48건·1103 이월 22건·그 밖의
이월 상태, 돌린 검사와 돌리지 않은 것을 적는다. CHANGELOG의 예산 행에 예산
커밋 `287dc6f`를 더한다.
버린 대안: 결정을 `docs/improvement/` 결정 색인에 적기. 그 폴더는 매뉴얼
PR(#6)과 겹쳐 건드리지 않는다.
위험·한계: 해시는 이 브랜치 끝에서 닿는 커밋이다. 브랜치를 다시 쓰면 함께
고쳐야 한다.
검증: desktop batch에서 확인.
옆 백엔드 checkout 없는 verify:documentation
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts
Refs: 1105/15-02, docs/reviews/2026-11-05-maturity-review/README.md
문제: PR B(`bbde570`)가 2026-11-05 리뷰의 조치를 모두 담았다. 멈춤
기준(새 High 0, 새 P1 0, merge 게이트 14개 통과)을 판정하려면 그 커밋을
다시 리뷰해야 한다.
고른 방법:
- 지난 라운드의 영역 16개를 그대로 쓰고, 영역마다 리뷰어 하나가 코드를
읽었다.
- merge stage는 같은 커밋에서 메인 세션이 돌린 실행(2026-11-06
03:24~03:56)을 게이트 증거로 썼다. merge stage 밖의 명령과 리뷰어가 읽을
산출물은 잠금 안에서 한 번 돌려 공유했다.
- 리뷰어 요청 65건과 12-04 완료 드릴은 desktop에서 한 항목씩 묶어 돌렸다.
- 지난 발견은 ID별로 다시 판정했다. 지난 README 16절의 "고침"을 그대로
쓰지 않았다. 새 High·P1 후보 둘(03-01, 08-01)은 코드에서 다시 읽었다.
버린 대안: 리뷰어마다 desktop에서 따로 실행. 지난 라운드에 잠금 줄이
30건까지 쌓였다.
위험·한계: FE-GATE-013의 tests/system 18건, release run 산출물, 실제 짝
백엔드 연동은 이 환경에서 확인하지 못했다(README 8절). 리뷰 중 배치
runner를 둘 띄워 한 항목을 다시 돌렸다(README 11.5절).
검증: 새 발견 25건(High 0, P1 0, Medium 1, Low 24). 지난 발견 140건을
다시 판정했다. 배치 67항목 모두 restore=clean이었고, desktop checkout은
원래 상태(`fix/maturity-review-2026-11-03` `8a44226`, git status 비어 있음)로
끝났다.
Refs: docs/reviews/2026-11-06-maturity-review/README.md
문제
워커를 싣는 빌드에서 live probe는 `/service-worker.js`를 기본 fetcher
`redirect: "follow"`로 받고, 최종 응답의 status와 origin만 본다
(`scripts/lib/hosting-probe.ts` `probeLiveRelease`). 같은 origin 안
redirect 뒤에 200·`no-cache`·JS MIME이 오면 FE-GATE-019가 PASS다.
브라우저는 워커 스크립트를 redirect mode "error"로 받는다(Service
Worker Update 알고리즘). 그런 호스트에서는 첫 등록, update 검사,
`REMOVE_REGISTRATION` kill switch가 모두 실패한다.
고른 방법과 버린 대안
- `serviceWorker` surface에만 `redirect` 행을 더한다.
`response.redirected`이거나 `opaqueredirect`이면 FAIL이다. 자산
probe(1105/06-02)와 같은 판정식이라 fetcher가 redirect를 따라가든
manual이든 잡는다. 3xx 응답은 지금처럼 `http-status` 행이 FAIL로 본다.
- redirect가 없으면 이 행은 PASS로 남는다. 산출물에 이 검사를 했다는
기록이 된다.
- 버린 대안: 모든 surface에서 redirect를 FAIL로 보기(리뷰 (b)).
`index`·`appRoute`의 정상 redirect(끝 슬래시 정규화 등)까지 막는다.
문서에만 적기(리뷰 (c))는 게이트가 그대로 PASS다.
- 운영 문서 두 곳에 "redirect 없이"를 적었다. release-cache-rollback.md의
live probe 설명과 browser-file-storage-recovery.md의 kill switch
전제다.
위험·한계
- 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다.
그런 호스트에서는 지금도 워커가 동작하지 않는다.
- 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 것이다. redirect하는
호스트로 실제 등록을 돌려 보지 않았고, live 모드도 실제 호스트로 돌리지
않았다(리뷰 §5 미검증 그대로).
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "live hosting probe (1105/06-02) > fails a worker script the host
answers only after a same-origin redirect"가 실패한다. 옛 probe에는
redirect 행이 없어 실패 행이 비어 있다.
- 함께: check:types, lint, verify:documentation
Refs: 1106/06-01
문제: 저장소 설계 문서와 VD-13이 Web Storage registry 행을 "현재"
목록으로 적는다. 설계 문서 50-52행은 8행 중 4행(`COLOR_SCHEME`,
`CHUNK_RELOAD_GUARD`, `AUTH_TOKEN`, `QUERY_PERSISTENCE`)만, 0절 표와
16.2절 기본 조립 표와 VD-13 2.1절 표·7.1절 문단은 `COLOR_SCHEME`,
`CHUNK_RELOAD_GUARD` 둘만("두 key") 적는다. registry에는 기본 조립이 쓰는
`LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 행
`CACHE_INVALIDATION_PULSE`·`AUTH_REDIRECT_TRANSACTION`도 있다
(`src/contracts/storage-keys.ts`, `create-application.ts`,
`boot-release-recovery.ts`). 행을 더한 커밋들이 이 문장을 따라 고치지 않았다.
고른 방법: 목록 문장을 지우고 `STORAGE_REGISTRY`를 정본으로 가리킨다.
StoragePort가 거절하는 행의 규칙(`sensitive-forbidden` 분류와
`backend: "external"`, `getStorageDefinition`)만 문장으로 남긴다. 표 두 행은
"StoragePort 행" 한 행으로 합친다. 8행을 모두 적는 대안은 버렸다. 다음에
행이 늘면 같은 식으로 낡는다.
위험·한계: 이 문장을 보는 검사는 없다. 두 문서는 docs/README.md 2절(목표
설계)이라 verify:documentation이 읽지 않는다. 다시 목록을 적으면 리뷰가
손으로 찾아야 한다.
검증: 문서만 바꿨다. 검사 없음(위). `git grep -n 'COLOR_SCHEME' --
docs/architecture`에 목록 문장이 남지 않았다(starter-experience.md의 테마
설명 한 줄만 남는다).
Refs: 1106/05-01
FE-GATE-027은 `check:release-admission`을 먼저, `scan:dependency-advisories`
를 뒤에 돈다. `ci:gate`는 처음 실패한 명령에서 멈춘다. 그래서 공개 대상
승인이 거절된 run에는 advisory 기록(`artifacts/security/
dependency-advisories.json`)이 생기지 않는다. 운영 문서는 release
산출물이 결과와 상관없이 이 기록을 싣는다고 적는다.
명령 순서를 scan → 승인으로 바꾼다. scan은 막지 않는 신호라 항상
exit 0이고, 승인 판정과 gate 결과는 그대로다. 문서 두 곳(한국어·영어)에
올라가는 것은 그 run에 생긴 파일이고, 승인이 거절돼도 기록이 있으며,
FE-GATE-015가 실패하면 FE-GATE-027이 돌지 않아 기록이 없다고 적는다.
gate 모양이 바뀌어 계약 기준선의 `gateShapeSha256`을 다시 적었다(owner
DongHyeonka, reason에 1106/13-01, 개수는 그대로). 생성 workflow는 명령
순서를 담지 않아 바뀌지 않는다.
버린 대안: (a) 문서만 고치기 — 거절된 run에서 신호가 한 run 늦는 것이
남는다. (c) scan을 always 단계로 따로 빼기 — 계약 단계와 workflow가
바뀌어 이 결함에 비해 크다.
위험·한계: 승인 전에 pnpm audit이 돌아 거절되는 run이 최대 120초(scan
timeout) 늦게 끝난다. scan이 정책 파일을 못 읽어 죽으면 이제 승인이
돌지 않는다(전에도 gate는 실패했다). FE-GATE-015가 실패한 run에는 여전히
기록이 없다. 실제 runner의 upload가 없는 파일을 건너뛰는지는 미확인이다.
제품이 `config/ci/contract-baseline.json`을 자기 값으로 다시 적어 두었다면
받은 뒤 다시 적어야 한다. 새 digest는 jq로 계산했다. 같은 계산이 바꾸기
전 기준선(7bebafe6…)을 그대로 재현했다.
검증: desktop batch에서 확인.
`node scripts/run-vitest.ts run tests/system/ci-runner/ci-evidence-freshness.test.ts tests/unit/dependency-advisories.test.ts`
— 새 "writes the advisory record when the release admission refuses the
candidate"와 바꾼 "runs before the release admission (FE-GATE-027) ..."가
수정 전 계약에서 실패하고 수정 뒤 통과한다. `check:ci`, 13-R1 C.
Refs: 1106/13-01
문제
"bounds a stream that never produces a chunk"는 가짜 시계를 5초씩 최대
4번 넘긴 뒤 활성화가 끝났는지 본다(`ce191be`, 1101/10-07). 그래서
marker 읽기 상한(`ACTIVATION_MARKER_READ_DEADLINE_MS`, 5초)을 20초까지
올려도 통과한다. 실제 시계로 기다리던 수정 전 test는 10초 test 제한에서
실패했다. 상한을 15초로 올린 리뷰 변이 06-R3에서 64건이 모두 통과했다.
고른 방법과 버린 대안
- 반복을 지우고 `advanceTimersByTimeAsync(5_000)`를 한 번만 부른다(리뷰
(가)). 이 fixture는 캐시가 현재 캐시 하나라 marker를 한 번만 읽는다
(`highestMarkedCache`는 현재 캐시를 건너뛴다). 상한이 1 ms만 길어도
활성화가 끝나지 않아 `settled` 단언이 실패한다. 수정 전 test(10초
이상만 검출)보다 강하다. 가짜 시계는 그대로라 실제 대기는 돌아오지
않는다. `cancels >= 1` 단언도 그대로다.
- 버린 대안: 상수를 `SERVICE_WORKER_BOUNDS`로 옮기고 그 값만큼 넘기기
(리뷰 (나)). test가 상수를 따라가므로 계약 모듈에서 값을 15초로 올리면
그대로 통과한다. 약점이 자리만 옮긴다. 계약 모듈 변경이라 워커·페이지
두 realm 검사도 다시 돌아야 하고, 리뷰 변이 06-R3도 이 커밋에 그대로
적용되지 않는다.
- 숫자 5_000이 test에 한 번 더 적힌다. 이 test가 지키는 값이 그것이라
일부러 둔다.
위험·한계
- fixture가 marker를 여러 번 읽게 바뀌면 이 test가 실패한다. 그때는 읽는
횟수만큼 정확히 넘긴다(리뷰 재검토 조건).
- 상한을 줄이는 변경은 잡지 않는다. 수정 전 test도 잡지 않았다.
- 한 번의 tick으로 끝나려면 deadline timer가 tick 전에 걸려 있어야 한다.
`onActivate()`부터 `setTimeout`까지는 바로 끝나는 async mock뿐이고,
`advanceTimersByTimeAsync`는 시계를 넘기기 전에 실제 macrotask 하나를
양보한다(fake-timers `tickAsync`). 코드로 본 판단이고 이 커밋으로는 아직
돌리지 않았다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/service-worker-runtime.test.ts
- 테스트만 바꾼 커밋이라 RED는 없다. 대신 변이 둘에서 이 test가 실패해야
한다: 리뷰 06-R3(상한 15_000), 완료 기준 변이(상한 5_001).
- 무변이에서는 64건이 통과한다.
Refs: 1106/06-02
문제: 짝 백엔드 Fileserver는 검증기가 거절한 업로드를 202 성공
Envelope(state REJECTED)로 답한다. client는 이 답을 FILE_REJECTED
실패로 바꾸는데, readSuccessEnvelope가 meta.traceId를 버려서 실패에
traceId가 없다. 같은 client의 Envelope 실패는 traceId를 싣는다
(1105/01-03). 서버가 정상으로 답해 trace 값이 손에 있는데도, 지원
담당이 이 거절을 서버 로그나 REJECTED 레코드와 잇지 못한다.
고른 방법: readSuccessEnvelope가 readFailureEnvelope처럼 meta.traceId가
있으면 traceId로 함께 돌려준다. Fileserver client는 202 REJECTED
실패에 그 값을 싣는다. V3 실행기는 value와 page만 읽으므로 동작이
같다. 매뉴얼 7절 결과 읽기 줄에 적었다.
버린 대안: fileserver-upload가 successEnvelopeSchema를 직접 파싱하면
Envelope 읽기가 backend-envelope.ts 밖으로 갈라진다. traceId만 읽는
함수를 따로 두면 같은 답을 두 번 파싱한다.
반환 칸이 늘어 readSuccessEnvelope 결과를 toEqual로 보는 테스트 두
곳(tests/runtime-schema/http-schema.test.ts,
tests/unit/a11y-api-answers.test.ts)의 기대값에 traceId를 더했다.
기대를 넓힌 것이 아니라 새 칸의 값까지 고정한 것이다.
위험·한계: 거절 이유는 여전히 없다. 프론트로는 고칠 수 없어
백엔드로 넘긴다.
- 사실(백엔드 45d2a478): FinalizeUploadApplicationUseCase
#applyNonAcceptVerdict는 REJECT 판정의 code(FILE_TOO_LARGE,
DIGEST_MALFORMED, 제품 검증기 code 등)를 FileRecordMutation.failure로
레코드의 lastErrorCode에만 쓴다. FileUploadController#created는
UploadedFileResponse 7칸(fileId, state, filename, mediaType, size,
sha256, etag)을 202로 답한다. 이유 칸이 없다.
- 요청: REJECT를 실패 Envelope(422, error.code = 판정 code,
retryable false)로 답하거나, 202 REJECTED 응답에 판정 code 칸을
더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 traceId를
그대로 싣고 NOT_APPLIED로 읽는다. 그때 FILE_REJECTED 분기는 지운다.
- CHANGELOG의 "백엔드로 넘김" 목록에 이 항목을 더하는 일은 CHANGELOG
담당에게 남긴다.
실제 배포 응답의 성공 meta에 traceId가 있는지는 백엔드 문서
(docs/web/http-contract.md §1 meta 키)와 EnvelopeBodyAdvice 코드로만
확인했다. backend-envelope.ts는 초기 번들에 있어 초기 JS가 수십 B
늘 수 있다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts tests/runtime-schema/http-schema.test.ts tests/unit/a11y-api-answers.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused
file, not as a broken answer"가 traceId "trace-1"이 없어 실패한다.
"reads data, and a dropped data key as null"과 "answers an Envelope
list read with an empty list inside the Envelope"는 결과에 traceId
칸이 없어 실패한다.
Refs: 1106/01-01
문제: 1103/16-05로 `BoundMutation.operationId`가 brand 타입이 됐고, 그 값은
`commandMutationIdentity`만 만든다. 이 함수는 descriptor 모양
`{ contract: { operationId, method, retrySemantics } }`만 받는다. CHANGELOG
"먼저 할 일" 2단계와 매뉴얼 01 7단계는 descriptor 상수 길만 적는다. V3
descriptor가 없는 쓰기(Fileserver 업로드 client는 `upload(request)`만 있다)와
테스트 fixture는 길이 없어, 따라 하면 `check:types`에서 막힌다. 템플릿은
자기 테스트에 `tests/helpers/mutation-operation-id.ts`를 두었지만 어느 문서도
그 helper를 말하지 않는다. 매뉴얼 01 안에서도 "손으로 적은 ID에 오타가 있으면
저장이 항상 실패한다"(BREAKING 전 동작)와 "문자열로 직접 적으면
`check:types`가 실패한다"가 서로 다르다.
고른 방법: 문서만 고친다(리뷰의 대안 A). descriptor 없는 쓰기는 descriptor
모양 객체를 넘기고, 키가 필요하면 `KEYED`, 아니면 `NEVER`를 적는다고 쓴다.
대조할 descriptor가 없어 그 ID는 intent 이름일 뿐이고 오타를 잡는 검사가
없다는 것도 적는다. 테스트는 `testMutationOperationId`를 쓰고
`requiresIdempotencyKey`는 따로 적는다. 매뉴얼 01의 "저장 때 실패" 문장은
손 객체를 넘긴 경우로 좁히고, "못 잡음" 항목을 descriptor가 있는 쓰기와 없는
쓰기로 나눈다. 버린 대안: 이름 있는 함수(B)나 Fileserver 업로드 descriptor
상수(C)를 공개하기. 공개 API가 늘고 코드 변경이라 이 문서 브랜치의 범위
밖이다. 리뷰도 A를 가장 작은 길로 적었다.
위험·한계: 손 객체가 공식 길이 된다. descriptor 없는 쓰기의 ID 오타는
여전히 아무 검사도 잡지 않는다(문서에 그렇게 적었다). 두 다운스트림의 손
ID 정책 중 몇 개가 이 길로 가야 하는지는 세지 않았다.
검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation (매뉴얼 01이 새로 적은 경로
`tests/helpers/mutation-operation-id.ts`와 script `check:types:test`가 있는지)
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts
Refs: 1106/09-01
문제: 미출시 절 "먼저 할 일"의 세 설명이 코드와 다운스트림 모양과 다르다.
(1단계) TechLog를 "감싸지 않는 백엔드"라 적는다. TechLog 백엔드는 Envelope로
감싸고 출력 검증기 `envelopeData`가 직접 벗긴다(tech-log
`tech-log-studio-contract-contribution.ts`). 같은 CHANGELOG 아래 절은
"출력은 Envelope 뼈대만 검사"로 적어 두 절이 다르다. "Envelope면
`ENVELOPE_V1`"을 따르면 실행기가 벗긴 `data`를 검증기가 다시 벗기려다 모든
응답이 실패한다. 빠뜨리면 `satisfies`에서 실패한다는 문장도 두 제품처럼
`as`로 단언한 descriptor에는 맞지 않는다.
(2단계) `commandMutationIdentity`가 `requiresIdempotencyKey`를
`retrySemantics === "KEYED"`로 다시 계산한다는 말이 없다
(`src/contracts/server-state.ts`). tech-log 관리 정책은 `true`를 적었고
descriptor는 `NEVER`라 값이 `false`로 바뀌고, 키를 요구하는 제품 가드가
저장마다 던진다. `check:types`는 통과한다.
(3단계) "계약 조립이 거절해 부팅이 멈춘다"고 적는다. 부팅은 빈 기여 목록만
조립하고(`installed-contract-contributions.ts`), 기능의 계약 기여는 그 기능
실행부를 적재할 때 `install`이 조립한다. 앱은 뜨고 그 기능 라우트에 처음
들어갈 때 실패한다.
고른 방법: 세 단계의 문장을 코드에 맞춘다. 1단계는 TechLog가 왜 `NONE`인지와
`ENVELOPE_V1`로 바꿀 때의 결과를 적고, `as` 단언에서는 타입 검사가 잡지 않는다고
덧붙인다. 2단계는 다시 계산하는 규칙, tech-log 관리 쓰기 예, 바꾸기 전에 값을
맞춰 보라는 한 줄을 붙인다. 3단계는 실패 시점과 CI에서 먼저 잡는 검사
(`test:unit`, `check:registries`)를 적고, "옮긴 뒤 확인" 1의 3단계 검사도
같이 고친다. 아래 절의 TechLog 문장은 이미 맞아 그대로 둔다.
위험·한계: `as` 단언이 빠진 `responseEnvelope`를 잡지 않는다는 것과 tech-log
관리 쓰기가 지금 실행기에서 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절된다는 것은
코드를 읽은 추론이고, 문서에도 그렇게 적었다. tech-log sync 브랜치에서
2단계 뒤 관리 저장을 해 보지 않았다.
검증: 문서만 바꿨다. CHANGELOG는 verify:documentation 밖이다. desktop
batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/14-01
문제: control cache의 active pointer entry는 있는데 저장된 본문이 다시
쓰기 전까지 계속 읽히지 않으면(blob 손실 등) Cache Storage 관리가 모두
멈춘다. readActivePointer는 이 실패를 UNAVAILABLE/RETRY(또는
NOT_READABLE/REOPEN)로 돌려주고 CORRUPT_DATA로 보지 않는다. activation은
CORRUPT_DATA 밖의 pointer 실패에서 멈추고, cleanup·inspect·조회도 같은
실패에서 멈춘다. pointer를 쓰는 곳은 activation 하나라서 RETRY를
지켜도 돌아오지 않는다. 돌아오는 길은 adapter 밖에서 control cache를
지우는 것뿐이다. 리뷰 실험 02-R1 X3이 이것을 보였다.
고른 방법: activateRelease에 선택 옵션 replaceUnreadablePointer를 둔다.
true면 이전 pointer를 읽지 못한 이유와 상관없이, 손상 pointer와 같은
0929/02-01 경로로 검증된 후보를 rollback 목록 없이 덮어쓴다. 기본값은
지금처럼 멈춤이라 "일시 오류 하나로 rollback 목록을 잃지 않는다"는
보존 조건이 지켜진다. 포트 주석, 설계 문서 8.3절, 운영 문서에 언제
쓰는지와 rollback 목록을 잃는다는 것을 적었다.
버린 대안: (가) 문서에 "control cache를 지우고 다시 activate"만 적기.
제품이 adapter 밖 코드로 소유 cache 이름을 알고 지워야 하고, 그동안
조회가 pointer 없음으로 바뀐다. (다) 연속 N회 실패를 손상으로 보기.
실패 횟수를 저장해야 하고, 긴 일시 오류에서도 rollback 목록을 잃는다.
위험·한계: 옵션을 켜면 일시 오류에서도 rollback 목록을 잃고, 다음
cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 그래서
기본값으로 두지 않았다. 일시와 지속을 가르는 판단은 운영자 몫이다.
포트에 선택 칸이 하나 늘었다. 호출부·구현부 모두 호환이라 breaking이
아니다. CHANGELOG [계약] 행은 CHANGELOG 담당에게 남긴다.
1105/02-02의 남은 부분(release marker 본문이 계속 읽히지 않으면 stage가
marker를 다시 쓰지 않는다)은 이 변경으로 풀리지 않는다. marker는 release
cache 안의 entry라 stage 경로를 바꿔야 한다. 범위 밖으로 둔다.
service-worker-pwa 레시피 번들(여유 306 B)에 수십 B가 더해진다.
실제 브라우저에서 pointer 본문 읽기 실패가 지속되는지는 확인하지
못했다(리뷰 5절 미검증과 같다).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/public-response-cache-repair.test.ts
RED(이 커밋의 테스트 + 부모 src): "replaces a pointer whose body stays
unreadable when the activation asks to (1106/02-01)"가 옵션을 준
activation에서 실패한다. 부모는 옵션을 모르므로 UNAVAILABLE/RETRY를
돌려주고 pointer를 다시 쓰지 않는다. 그 앞의 멈춤 단언(X3와 같은
결과)은 부모에서도 통과한다. 일시 오류 테스트 "still stops activation
when the pointer read fails transiently"는 바뀌지 않았고 통과해야 한다.
Refs: 1106/02-01
문제: D7 커밋 `287dc6f` 본문의 "늘어난 곳"이 1105/03-01과 1105/08-03에
적은 해시 둘은 통합에서 다시 짓기 전 해시라 `bbde570`에서 닿지 않는다
(`git merge-base --is-ancestor` rc=1). 같은 변경은 이 이력에서 `5c0b37e`,
`f849d78`이다(`git log --format='%h %s' 409d72e..bbde570`, rc=0). 원격
clone에는 두 객체가 없다. 통합 절차에 CHANGELOG·커밋 본문의 해시를 범위와
대조하는 단계가 없다.
고른 방법: 올린 이력은 고쳐 쓰지 않는다(`287dc6f`을 amend·rebase하지 않음).
1105 README 16.2절 D7 행에 본문의 두 해시가 다시 짓기 전 것이라는 것과 이
이력의 해시를 적는다(지시대로 그 행만). 닿지 않는 해시는 새로 적지 않는다.
적으면 아래 대조에 다시 걸린다. CHANGELOG 머리말의 "그 절의 해시는 모두 그
범위에 있다" 뒤에, 해시를 다시 쓴 뒤 절과 범위 커밋 본문의 해시를
`git merge-base --is-ancestor`로 대조하고 결과를 리뷰 README 조치 절에 적는
한 단계를 둔다(리뷰의 대안 b).
버린 대안: 해시를 대조하는 단위 테스트(대안 c). 싸지 않다.
- 복사한 프로젝트에는 템플릿 이력이 없거나(tech-log는 이력 없이 3-way로
옮긴다) CI checkout이 얕을 수 있어, 테스트가 그때 건너뛰어야 한다. 조건부로
도는 테스트는 이번 라운드 지시가 막는다.
- 커밋 본문은 작업 트리가 아니라 `git log` 범위를 읽어야 하고, 이미 올린
`287dc6f`이 영구히 걸리므로 예외가 필요하다. 예외 추가도 지시가 막는다.
- CHANGELOG에는 다른 repo 해시(`d3810a0` 등)가 섞여 있어 repo 표시 규칙부터
정해야 한다.
위험·한계: 대조는 사람이 하는 단계다. 빼먹으면 같은 일이 다시 난다. 완료
기준 "다음 통합 기록에 그 대조 결과가 있다"는 이번 라운드를 합칠
오케스트레이터가 채운다. 새 clone에서 `git show 287dc6f` 본문의 두 해시는
여전히 열리지 않는다.
검증: 문서만 바꿨다. desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
(새 괄호 `(1106/14-02, 1105 README 16.2)`가 참조 꼴을 지킨다)
git merge-base --is-ancestor 5c0b37ebbde570 && git merge-base --is-ancestor f849d78bbde570
Refs: 1106/14-02
문제: D7이 초기 JS 예산을 204,800 → 206,848 B로 올렸다(`287dc6f`). 드릴
(FE-GATE-020, 생성 기능 둘)이 넘은 양은 665 B(CI env)인데 2,048 B를 올렸다.
문서는 올린 뒤 여유만 적고 왜 그 폭인지, 언제 다시 내리는지를 적지 않는다.
재검토 조건 "예산을 또 넘을 때"는 이번 상향의 조건과 같아서, 내릴 조건이 없다.
다음 담당자는 예산을 넘었을 때 올릴지 줄일지 문서에서 알 수 없다.
고른 방법: 메인 세션 결정 D9를 따른다. 206,848 B를 그대로 두고
`docs/operations/performance-evidence.md`의 예산 항목에 세 가지를 적는다.
- 폭의 근거: 드릴 측정값 205,465 B(CI env, `bbde570`) + 기능 하나의 상한
1 KiB = 206,489 B를 KiB 단위로 올림해 202 KiB = 206,848 B. 드릴 위 여유
1,383 B가 기능 하나와 올림 359 B로 나뉜다. 템플릿 자신의 몫은 이 규칙에 없다.
- 되돌림 규칙: D7의 재검토 조건마다 드릴을 다시 재고, 204,800 B 이하이면 같은
규칙으로 내린다.
- 사용자가 이 결정을 뒤집을 수 있다.
버린 대안(리뷰 15-01의 대안): 예산을 드릴 + 256 B로 되돌리기(다음 템플릿
변경마다 넘는다), 테스트로 예산 값을 여유 규칙에 묶기(D9가 고르지 않았다).
위험·한계: 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는
테스트는 없다(리뷰 대안 c는 고르지 않았다). 205,465 B는 2026-11-06의 한 번
측정이고, 다음 측정은 "다시 볼 때"에 한다. 결정 기록 자체는 오케스트레이터가
2026-11-06 리뷰 README에 적는다. 이 문서는 그 파일을 가리킨다.
검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation (새로 적은 경로
`docs/reviews/2026-11-06-maturity-review/README.md`와 FE-GATE-020을 본다)
node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts
Refs: 1106/15-01
문제: `docs/operations/performance-evidence.md`의 초기 파일 상한 문장이
"상한은 템플릿 그대로의 수(26)에 6을 더한 32다"라고 적는다. 지금 기록은
27개다(`config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`,
FE-GATE-012 `27 / 32 files`). 기록을 27로 다시 쓴 `0fee3fe`이 이 문장을 고치지
않았다. 1103/15-02의 완료 기준 "문서·JSON에 서로 다른 기준선이 없다"를 다시
어긴다. 같은 문서의 바이트 쪽은 이미 숫자를 적지 않고 기록을 가리킨다.
고른 방법: 지금 수를 지우고, 상한 32가 정할 때 6칸을 더한 값이라는 것만
남긴다. 지금 템플릿 수는 그 기록이 정본이고 남은 칸은 32에서 그 값을 뺀
것이라고 적는다. 바이트 절의 "기준선 숫자는 이 문서에 적지 않는다"와 같은
방식이다. 숫자를 27로 고치는 대안은 버렸다. 다음에 파일이 하나 늘면 같은
식으로 낡는다.
위험·한계: 상한 값 32는 예산 값이라 그대로 적었다. `budgets.json`을 바꾸면
이 문장도 고쳐야 하고, 그것을 보는 검사는 없다. 기록 파일은 참조 기능과 함께
지워질 수 있고, 그때 문서 검사는 이 경로를 요구하지 않는다
(`scripts/lib/removable-template-features.ts`).
검증: 문서만 바꿨다. desktop batch에서 확인.
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/template-feature-removal-documents.test.ts
Refs: 1103/15-02
문제: FE-REG-SCHEMA 행의 direction·unknownFieldPolicy는 타입에서 선택
칸이다. tests/unit/schema-metadata-policy.test.ts는 행이 값을 적지 않으면
그 자리를 건너뛰었다(direction의 `declared === undefined`, 정책의
`if (declared === undefined) return []`). 1105/07-02는 RESPONSE 행의
정책이 REJECT_UNKNOWN으로 바뀔 때만 breaking으로 본다. 그래서 손으로 쓴
응답 행이 두 칸을 빼고 들어오면, 뒤에 응답 DTO를 .strict()로 바꿔도 행이
바뀌지 않아 check:registries는 아무것도 보지 않고 정책 테스트도 건너뛴다.
백엔드가 응답에 필드 하나를 더하면 그 API가 SCHEMA_MISMATCH로 실패한다.
고른 방법: 리뷰의 (A). descriptor의 입력·응답·실패 검증기(`slots`)로 쓰인
스키마의 행이 두 칸을 적지 않으면 두 테스트가 실패로 센다. 메시지는
`row states no direction, used as <방향>`과
`row states no unknownFieldPolicy, validator <탐침 결과>`다. 행이 아예 없으면
같은 메시지가 나오고, boundary 테스트도 `no FE-REG-SCHEMA row`로 실패한다.
템플릿 HTTP 행과 생성기가 쓰는 행(create-feature.ts, create-feature-
write-slice.ts)은 이미 두 칸을 적어 통과한다. 라우트에만 쓰이는 행
(NotFoundSplat)은 slots에 없어 그대로 두 칸이 없어도 된다.
매뉴얼 01 4단계와 errors.md에 규칙과 메시지를 적었다.
버린 대안: (B) governance가 api-* 경계 행에 두 칸을 필수로 둔다. 경계별
필수 칸 규칙이 governance에 없어 분류기 변경과 기준선 재승인이 필요하다.
타입에서 두 칸을 필수로 만들면 route 전용 행까지 바뀌고, src/contracts
export의 모양이 바뀐다.
위험·한계: 다운스트림이 두 칸 없는 HTTP 행을 가졌다면 동기화 뒤 test:unit이
실패한다. 메시지대로 두 칸을 적으면 된다. 고친 곳이 검사(테스트 파일)
자신이라 RED는 테스트 파일만으로 만들 수 없다. 참조 응답 행에서 두 칸을
지운 변이로 확인한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts
(변이 없이 통과, ReferenceResourcePayload 행의 두 칸을 지운 변이에서 두
테스트 실패)
Refs: 1106/07-02
문제: 두 테스트가 검사 대상을 "파일이 있으면"으로 정한다.
- `playwright-run-isolation.test.ts`는 capabilities 설정이 있을 때만
그 설정의 검사 8개를 정의한다(`existsSync`). browser-file-storage
드릴 사본에서 33개가 25개로 줄었는데 skip 보고가 없다. 템플릿에서
설정 이름을 바꾸고 테스트의 문자열만 놓쳐도 같이 빠진다.
- `vite-build-inputs.test.ts`는 목록 소비자 둘을 `existsSync`로 거른다.
어느 제거 목록에도 없는 `product-feature-selection-build.test.ts`의
이름이 바뀌어도 검사가 빈 반복으로 통과한다.
- 주석의 skip 차단 ID가 0929/10-04로 틀렸다. 1101/10-04다.
고른 방법(리뷰 문서 ⓐ):
- capabilities 검사 8개를 `playwright-capabilities-run-isolation.test.ts`로
옮기고 설정을 이름으로 import한다. browser-file-storage 드릴이 설정과
이 파일을 이름으로 함께 지운다. 같은 드릴이 `ci-workflow-generation`
테스트를 지우는 방식이다. `force` 없이 지워, 이름이 바뀐 파일은 드릴이
그 자리에서 멈춘다.
- 두 파일이 같은 검사를 쓰도록 불러오기·포트·결과 폴더 검사를
`tests/helpers/playwright-run-isolation.ts`로 뺐다. 단언은 그대로다.
- `vite-build-inputs`는 빌드 테스트를 늘 읽는다. 측정 스크립트는 그
파일을 가진 제거 가능 기능(`removable-template-features.ts`)이 설치돼
있을 때(feature-module.ts가 있을 때, verify:documentation과 같은 규칙)
읽는다. 그 소유 기능이 없으면 실패한다. 기능 ID를 테스트에 쓰지 않는
것은 샘플 드릴의 residue 검사가 `src`·`tests`의 샘플 이름을 잡기 때문이다.
- 틀린 ID 주석은 옮긴 검사와 함께 없어지고, 새 파일 머리말에 1101/10-04로
적었다.
버린 대안: 드릴이 표시를 넘기고 테스트가 읽는 방식(ⓑ). 드릴과 테스트
사이 계약이 늘고, capability를 지우는 제품이 테스트를 고쳐야 한다. 주석
ID만 고치기(ⓒ)는 공백이 남는다.
위험·한계:
- 테스트 수는 템플릿 33개(25 + 8)로 같다. browser-file-storage 사본에서는
25개가 돌고 8개는 파일째 지워진다(드릴 코드에 적힘).
- 측정 스크립트의 조건은 여전히 파일 존재(소유 기능의 feature-module.ts)다.
대상이 지울 수 있다고 등록된 소유자로 바뀌었다.
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/playwright-run-isolation.test.ts tests/unit/playwright-capabilities-run-isolation.test.ts tests/unit/vite-build-inputs.test.ts
이름 바꾸기 변이 둘(capabilities 설정, product-feature-selection-build
테스트), check:types, lint, ci:gate FE-GATE-020
Refs: 1106/10-01
문제: reconnect coordinator는 `attempt`·`waitClosed`가 던지면
PROVIDER_UNAVAILABLE(CONNECT·RECEIVE, retryable)로 보고 backoff로 다시
시도한다. 05330e3 뒤 poll은 같은 던짐을 PROTOCOL_MISMATCH로 끝낸다. 이
차이는 그 커밋 본문에만 있고 타입 주석과 설계 13.1에는 없다. repo의 SSE
bridge 예(`sseAttempt`)는 `attempt` 안에서 연결을 만든다. 그래서
endpoint 설정 오류가 요청 0번, attempt 3번, PROVIDER_UNAVAILABLE
(EXHAUSTED)로 끝나 서버 장애로 보인다(리뷰 실험 04-R2).
고른 방법: 리뷰 선택지 (c). 동작은 그대로 두고 규칙을 적는다.
- `attempt` 주석: 던짐은 transport 실패로 재시도된다. 설정 검사는
`attempt` 밖, 조합 코드가 transport를 만들 때 한다. poll과 다른 이유도
적었다. `waitClosed` 주석: RECEIVE로 같은 규칙.
`classifyClosed`·`confirmTransportBarrier` 주석: 던짐은
PROTOCOL_MISMATCH로 끝나고 재시도하지 않는다.
- 설계 13.1 PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행에 같은 규칙을 적었다.
- 테스트 bridge `sseAttempt`는 만들어질 때 연결 설정을 한 번 검사한다.
연결은 attempt마다 새로 만든다. session `close`가 연결을 끝내므로 한
연결을 여러 attempt에 쓸 수 없다.
- 규칙을 고정하는 테스트를 더했다. attempt·waitClosed 던짐은 3회 재시도 뒤
PROVIDER_UNAVAILABLE(EXHAUSTED), classifyClosed 던짐은 1회로
PROTOCOL_MISMATCH, bridge의 http endpoint는 만들 때 TypeError(fetch 0).
버린 대안:
- (b) reconnect도 던짐을 PROTOCOL_MISMATCH로 끝내기. 연결 실패를 던지는
라이브러리를 감싼 transport가 첫 실패에서 run을 끝내게 되는 공개 동작
변경(BREAKING)이다. 리뷰도 지금 동작이 회복에 유리하다고 봤다.
05330e3이 poll에서 (c)를 버린 이유("결과로 구분한다")는 이번 완료
기준에 없다.
- 연결 하나를 bridge에서 만들고 attempt마다 read만 하기. 위와 같이
session `close`가 연결을 닫아 다음 read가 CLOSED가 된다.
위험·한계:
- 동작이 같으므로 조합 코드가 `attempt` 안에서 연결을 만들면 설정 오류는
여전히 서버 장애로 보인다. 주석과 13.1은 모르고 쓰는 경우만 줄인다.
- 매핑 오류 같은 나머지 던짐도 그대로 재시도되고 원인 예외는 남지 않는다
(닫힌 관측 어휘).
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/realtime-reconnect-coordinator.test.ts
- RED 없음. 동작을 바꾸지 않는 커밋이라 새 테스트는 부모 커밋에서도
통과한다. 규칙을 고정하는 테스트다.
- check:types, lint, verify:documentation
Refs: 1106/04-01
문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전
거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패
(NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서
결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로
나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는
그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에
새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2).
고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)):
- 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그
intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와
같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신
markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외
(.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은
결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의
성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다.
- 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서
unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구
하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를
formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로
저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이
그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를
받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로
미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다.
버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가
남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성
기능만 덮는다).
위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시
보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은
입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를
보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금
늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에
적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1.
Refs: 1106/03-01
문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다.
기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec
말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을
null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두
통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를
적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난
실행의 기록 파일도 디렉터리에 남아 있었다.
고른 방법: 리뷰의 (다)와 기록 초기화.
- scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된
descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이
필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는
GET의 입력 스키마일 때다. GET 쪽 규칙은
tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다.
참조 기능 상세와 create:feature --with-create 상세는 GET과 같은
<Pascal>Params를 쓰므로 이 규칙에 든다.
- write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면
`a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다.
a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다.
- accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다.
기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다.
엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에
기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다.
- 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개
라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은
허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL
하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도
모른다. 참조 기능과 함께 지워진다.
- 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset).
버린 대안:
- (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만
reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도
정해야 한다.
- 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능
런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가
많다.
- spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할
뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다.
- 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정:
11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다.
위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고,
규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라
받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는
규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이
API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임
전체를 불러온다(check:registries와 같은 경로). check:types:node가 그
그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/features/reference-feature/reference-contract.test.ts
11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤
node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm
test:a11y
Refs: 1106/11-01
문제: 0929/03-03의 두 가드(재전송 버튼 canResend, 같은 입력 재제출 거절)가
intent의 키 유무로만 가른다. 뮤테이션 정책은 키 여부만 실어서 훅이 NEVER와
IDEMPOTENT를 가를 수 없다. 그래서 IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)도
결과 불명 뒤 재전송 버튼이 없고 같은 입력 저장이 UNKNOWN_EFFECT_PENDING으로
거절된다. 출구는 사실을 모르는 "변경됨으로 확인"이나 새로고침뿐이다. 매뉴얼은
IDEMPOTENT를 "여러 번 적용해도 결과가 같다"로 적고, 실행기도 보낸 뒤에
다시 보낸다.
고른 방법(리뷰 03-03 대안 (a)): commandMutationIdentity가 resendSafe
(KEYED 또는 IDEMPOTENT)를 함께 준다. BoundMutation에 선택 칸 resendSafe를
더했다(추가만). 훅은 admission마다 resendable(키가 있거나 정책이
resendSafe)을 적고, 두 가드가 키 대신 그 값을 본다. 칸이 없는 손으로 쓴
정책은 지금처럼 키 유무로 간다. NEVER의 재전송 금지와 같은 입력 거절은
그대로다. 매뉴얼 01·02와 런북 6.3-4에 IDEMPOTENT 행을 적었다.
버린 대안: 문서만 고치기(회복 경로가 그대로 불편하다), IDEMPOTENT에도 키를
붙이기(백엔드가 키를 읽지 않으면 의미가 없고 실행기가
UNEXPECTED_IDEMPOTENCY_KEY로 거절한다).
위험·한계: commandMutationIdentity의 반환 객체에 칸이 하나 늘었다. 그 값을
toEqual로 비교하던 테스트는 칸을 더해야 한다(이 repo는 1곳을 고쳤다).
IDEMPOTENT로 잘못 선언한 쓰기(백엔드가 실제로는 중복을 막지 못함)는 이제
결과 불명 뒤 사용자가 다시 보낼 수 있다. 선언의 정확성은 기능 작성자
몫이다(02 결정표 3절). 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다.
CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/unit/command-mutation-identity.test.ts
Refs: 1106/03-03
문제: 문서를 복사하지 않는 capability 드릴 셋은 `REMOVAL_FIXTURE_DOCUMENT_TESTS`
의 파일을 통째로 지운다. 문서를 읽는 테스트 하나 때문에
`backend-contract-pin.test.ts`가 목록에 들어가, config와 코드만 보는 나머지
14건(pin 커밋, 답 표 사본, 생성기 사실, Envelope 판정 대조)도 그 드릴에서
돌지 않는다. `feature-tracked-files.test.ts`의 생성기 목록 검사 1건도 같다.
목록을 지키는 검사는 파일 글자에 `README.md|CHANGELOG.md|docs/`가 있는지만
봐서, `backend-contract-pin.test.ts`는 주석 한 줄로 통과했다.
고른 방법(리뷰 문서 ⓐ+ⓑ):
- 6.1 표를 읽는 테스트를 `backend-contract-pin-document.test.ts`로 옮기고
목록에는 그 파일을 둔다. pin 파일은 목록에서 빠져 모든 드릴에서 돈다.
새 파일은 pin에서 문서 경로만 읽고, 그 경로가 `docs/` 아래인지 확인한다.
- `feature-tracked-files.test.ts`의 문서와 무관한 1건을
`feature-tracked-file-rewrites.test.ts`로 옮긴다. 남은 두 건은 모두 문서를
읽어 그 파일은 목록에 남는다(`create-feature.ts`의 참조도 그대로 맞다).
- 목록 검사는 Babel로 파일을 파싱해 코드의 문자열·템플릿 리터럴에 문서
경로가 있는지 본다. 주석은 세지 않는다. 주석만 있는 소스를 거절하는지
자체 테스트를 더했다.
- 6.1 대조를 가리키던 `external-contract-runtime.ts` 주석과 계약 문서 한
줄을 새 파일 이름으로 고쳤다.
버린 대안: capability 드릴이 계약 문서 하나만 복사하기. 문서 테스트가
늘 때마다 복사 목록이 늘고, 그 드릴이 "문서 없이"를 증명한다는 전제가
흐려진다. 목록 검사만 고치기는 빠지는 범위가 그대로다.
위험·한계:
- 목록 검사는 파일 단위다. 파일 안의 모든 테스트가 문서를 읽는지는 기계로
보지 않는다. 목록 주석에 규칙을 적었다.
- 검사는 코드에 문서 경로 문자열이 있는지 본다. 그 문자열로 실제로 읽는지는
보지 않는다.
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/removal-fixture.test.ts tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-pin-document.test.ts tests/unit/feature-tracked-files.test.ts tests/unit/feature-tracked-file-rewrites.test.ts
check:types, lint, verify:documentation, ci:gate FE-GATE-020(capability
드릴 셋의 unit 실행에 pin 14건이 나오는지)
Refs: 1106/12-01
문제: 1105/16-04 수정 뒤 제품 기능 제거 드릴의 tests 잔여는 파일
이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일뿐이다. 주석과 매뉴얼
01 11단계는 빠진 경우(본문에만 ID가 있는 테스트)를 test:all이 잡는다고
적었다. 그런데 test:all은 vitest 묶음이고 vitest는 tests의 *.test.ts(x)만
돈다. tests/e2e·visual 등의 *.spec.ts는 test:all도 드릴의 다른 단계도
돌리지 않는다. 그래서 `test.describe("invoice-feature", …)`처럼 본문에만
ID를 담은 spec은 드릴을 통과하고, 다음 CI의 브라우저 게이트에서 지운
라우트를 열다가 실패한다.
고른 방법: 리뷰의 (b). tests 중 vitest가 돌지 않는 Playwright spec
(`*.spec.[cm]?[jt]sx?`)은 본문도 찾는다. 다만 1105/16-04가 없앤 부분
문자열 검색으로 돌아가지 않고, 기능 ID·폴더 이름을 앞뒤가 영문·숫자·`-`가
아닌 한 이름으로만 찾는다. `"invoice-feature"`, `'invoices'`,
`/features/invoices/`는 잔여이고, product-feature를 지울 때
`generate-product-feature-index.ts`·`data-product-feature`·
`product-features`는 잔여가 아니다. vitest 테스트 본문은 그대로 찾지 않는다
(템플릿 테스트가 예시 ID를 데이터로 쓴다). 템플릿 자신의 spec에는
invoice-feature·product-feature·scaffold-feature가 한 이름으로 나오지 않는다
(git grep 0건). 그래서 16-R2(invoice-feature 제거)와 FE-GATE-020
(scaffold-feature)은 그대로 통과해야 한다. 주석, 매뉴얼 01 11단계, errors.md의
판정 문장을 고쳤다.
버린 대안: (a) 문서만 고친다. 빈틈이 남는다. spec 본문을 부분 문자열로
찾는다: 짧은 ID와 템플릿 이름(`generate-product-feature-index`)이 거짓
양성을 다시 낸다. tests의 모든 비-vitest 파일(helpers, mocks, fixtures)을
찾는다: tests/helpers/runtime-capabilities-stub.ts가 주석에
"product-feature"를 한 이름으로 적어 거짓 양성이 된다. spec이 import하는
helper는 spec이 지워지면 아무 데서도 돌지 않아 해가 없다.
위험·한계: route ID나 URL만 적은 spec은 여전히 못 잡는다(03 손 목록).
다운스트림 spec이 무관한 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이
난다. 1105/16-04의 남은 부분(src 경로·본문과 tests 파일 이름의 부분 문자열
검색, dist 빌드 잔여 검사)은 이 변경이 덮지 않아 그대로 두었다. 같은 이름
단위 검색으로 바꾸면 product-feature의 거짓 양성(16-R3, 20파일)은 풀리지만,
폴더 이름에 붙은 식별자(`invoices` → `InvoicesPage`)와
`<id>-helpers.test.ts` 같은 파일 이름을 놓쳐 검사가 좁아진다. 따로 정한다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
corepack pnpm create:feature invoice-feature에 본문에만 ID를 적은
tests/e2e/checkout.spec.ts를 더한 뒤 corepack pnpm test:sample-removal --
--feature=invoice-feature가 fixture-id-residue로 실패, spec 없이는 통과
Refs: 1106/16-01
문제: poll `execute`가 받는 `input.operation`은 `BoundedPollOperation`
(`InstalledHttpContract<unknown, unknown, unknown>`)이다. 권하는 대로
`executor.execute(input.operation, x, …)`를 부르면 `Input`이 `unknown`이
되어 `x`는 아무 값이나 통과하고 `outcome.value`도 `unknown`이다. 입력이
틀리면 런타임 `CONTRACT_VIOLATION`(INPUT_INVALID)으로만 드러난다. 타입을
지키려면 클로저 descriptor를 써야 해서 1103/04-01의 잔여 위험(다른 행을
실행) 쪽이 유리해진다. 또 V3 결과 9종을 poll 결과로 바꾸는 대응표가 없다.
repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable
PROVIDER_UNAVAILABLE로 바꿔, 옮기면 401·403·입력 거절도 maxAttempts번
다시 요청된다.
고른 방법: 리뷰 선택지 (b) + (c).
- `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에
`Operation extends BoundedPollOperation = BoundedPollOperation`을 더하고
`operation`·`input.operation`을 `Operation`으로 둔다. `operation`에서
추론되므로 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다.
런타임 코드는 바뀌지 않는다.
- 설계 9.2에 V3 결과 kind마다 poll 결과(kind, retryable, retryAfterMs)를
적은 표를 두고, 13.1 PROVIDER_UNAVAILABLE 행에서 그 표를 가리킨다.
9.2 "auth에서 lease 종료", 9.3 "401은 attempt를 끝낸다", 9.4, 13.1과
맞췄다. `retryAfterMs`는 값이 있을 때만 둔다(빈 칸은 모양 오류).
- 테스트 조합 예를 표대로 바꿨다(`pollAttemptResult`). 503 재시도
테스트는 같은 결과다(503 PROBLEM → retryable PROVIDER_UNAVAILABLE).
- 테스트: 틀린 입력에 `@ts-expect-error`, 출력을 기능 타입으로 받는 타입
테스트 1건. 401·403이 요청 1번으로 lease를 끝내는 테스트 2건.
버린 대안:
- (d) 대응 함수를 bootstrap이나 recipe에 두기. realtime 어댑터는
adapters/http 타입을 import할 수 없고, 레시피 번들과 제거 드릴 범위가
바뀐다.
- `BoundedPollOperation` 자체를 제네릭으로 바꾸기. application 정책의
공개 이름이 바뀐다. 제약으로만 두면 기존 이름이 그대로다.
위험·한계:
- 기존 호출은 그대로 컴파일된다. `Value`를 직접 적은 호출은 `Operation`이
기본값이라 예전처럼 `unknown`이다. 타입을 원하면 둘 다 적거나 추론에
맡긴다(타입 주석과 9.2에 적음). 그래서 `!`를 붙이지 않았다. 단, 추론에
맡긴 호출이 descriptor 타입과 다른 입력을 실행기에 넘기고 있었다면 이제
check:types가 실패한다. 이 커밋이 잡으려는 결함이다.
- 표는 조합 코드가 따를 규칙이고 강제 수단은 없다. 템플릿은 poll
`execute` 기본 구현을 주지 않는다(리뷰 재검토 조건).
- 409·410의 `CURSOR_EXPIRED` 행은 reset 계약이 있는 기능만 해당한다.
테스트 계약에는 없어 테스트 예는 그 갈래가 없다.
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.
검증: desktop batch에서 확인.
- corepack pnpm check:types:test
- node scripts/run-vitest.ts run tests/unit/realtime/bounded-poll-coordinator.test.ts
- RED: 부모 커밋의 src에서 check:types:test가 실패한다.
bounded-poll-coordinator.test.ts의 `@ts-expect-error` 줄이 TS2578(쓰이지
않은 지시문, 입력이 `unknown`이라 `{ size: 20 }`이 통과), 그 아래
`pollAttemptResult<…>(outcome)`이 TS2345(`outcome.value`가 `unknown`).
vitest 테스트는 양쪽에서 통과한다.
- lint, check:architecture, verify:documentation
Refs: 1106/04-02
문제: 저장 중에 참조 작성 폼을 떠났다가 돌아오면(1105/08-04가 지원 경로로
다루는 길) 새 폼 인스턴스에는 제출한 값도 결과도 없다. (A) 그 저장이 결과
불명으로 끝나 "변경됨으로 확인"을 누르면 settleApplied가 제출한 값이 없어
아무것도 하지 않는다. 결과 문구가 없고 눌렀던 버튼이 빠져 포커스가 body로
간다. 같은 훅의 재전송(resendUnknown)은 다시 마운트를 이미 처리한다.
(B) 그 저장이 성공하거나 적용 안 됨으로 끝나면 진행 문구만 사라지고 아무것도
보이지 않는다. 사용자가 같은 항목을 다시 입력하면 새 생성이 나간다(리뷰
probe 08-R1).
고른 방법:
- (A) 리뷰의 최소 개선 (1): settleApplied가 제출한 값이 없으면 지금 값으로
성공을 정한다. 재전송과 같다. 포커스를 잃었으면 feedback 자리로 옮긴다.
1105/08-01의 포커스 복구는 직전 결과가 effect-unknown일 때만 걸려서
다시 마운트한 폼(직전 idle)에는 닿지 않는다.
- (B) 리뷰 (2)의 작은 쪽: 참조 폼이 "자기가 시작하지 않은 저장이 돌던 것"을
기억하고, 그 저장이 끝나면 feedback에 기존 링크 "목록을 새로 불러와
확인"을 둔다. 이 폼이 직접 저장하면 지운다. 새 문구는 없다.
버린 대안: 코디네이터가 마지막 시도의 결과를 채널에 남기고 폼이 그것을
보이기(정확하지만 코디네이터 계약이 넓어진다), useAppForm이 코디네이터
상태를 받아 결과를 하나로 내기(지난 라운드 3.5 (B), 설계 변경이다).
위험·한계: (B)는 결과를 말하지 않고 목록으로 안내만 한다. 생성기 템플릿의
작성 폼은 (A)에서 목록으로 옮기므로 해당 없고, (B) 안내는 넣지 않았다
(1106/08-02는 이동만 고친다). (A)는 resetOnSuccess면 다시 마운트한 뒤 입력한
값을 비운다. 재전송과 같은 동작이다. 브라우저 3엔진 e2e는 더하지 않았다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
Refs: 1106/08-01
문제: 1105/12-04 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데,
check:bundle의 두 단계(`generate-supply-chain.ts`, `check-bundle.ts`)는 이
변수를 읽지 않고 checkout의 `dist`와 `artifacts/`를 읽는다. 셸에 이 변수를
둔 채 빌드와 check:bundle을 돌리면 예산을 3,504 B 넘는 새 빌드 대신 이전
빌드를 재서 PASS한다(리뷰 12-R2). ci:gate의 신선도 검사도 bundle.json을
check:bundle이 다시 쓰므로 막지 못한다.
고른 방법: `scripts/lib/run-isolation.ts`에 `checkoutBuildReadFailure`를
두고, 두 스크립트가 무엇을 읽기 전에 부른다. 출력 루트가 `.`이 아니면 변수
값과 이유를 적고 exit 1로 멈춘다. `.`(Playwright 설정이 run ID 없이 web
server에 넘기는 값)과 빈 값은 그대로 돈다. 그래서
`RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`도 check-bundle
단계에서 변수 이름을 적고 실패한다.
버린 대안: ci:gate가 시작 전에 거절하기(리뷰 문서 (b)). 12-R2처럼
check:bundle을 직접 돌리는 경우를 막지 못한다. 두 스크립트가 같은 루트를
읽게 하기(c)는 supply-chain 산출물 전부와 CI upload 경로를 함께 옮겨야 한다.
위험·한계:
- FE-GATE-012는 빌드 단계를 끝까지 돈 뒤 check-bundle에서 실패한다. 빌드
시간만큼 늦게 알린다.
- 같은 모양일 수 있는 `check:app-build-input:bundle`,
`check:optional-recipes --require-dist`, release candidate 조립은 보지
않았다. FE-GATE-012에서는 check-bundle이 먼저 실패해 거기까지 가지 않는다.
- 디버깅으로 변수를 둔 사람은 check:bundle 전에 지워야 한다(문서에 적음).
- 이 노트북에서는 실행하지 못했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/check-bundle-output.test.ts tests/unit/run-isolation.test.ts
리뷰 12-R2 명령(stale-bundle-rc=1, stderr에 RUN_OUTPUT_ROOT), check:types,
lint, verify:documentation, ci:gate FE-GATE-012
Refs: 1106/12-02
문제: 생성기 템플릿의 작성 폼은 저장을 기다린 뒤 openSaved에서 상세로
navigate한다. 그 사이 화면이 남아 있는지 보지 않는다. 저장 중에는 이탈 확인이
꺼져 있어 사용자는 목록이나 다른 기능으로 갈 수 있다. 저장이 끝나면 언마운트된
화면의 navigate가 앱을 그 항목의 상세로 옮긴다(데이터 라우터의 navigate는
언마운트 뒤에도 동작한다, 리뷰 probe 08-R7). 다시 돌아온 작성 폼에 입력이
있으면 이유 없는 이탈 확인 창이 뜬다. 참조 폼은 저장 뒤 이동하지 않아 생성기에만
있다.
고른 방법: 생성 페이지가 마운트 여부를 ref로 들고(useEffect에서 true, 정리에서
false), 저장 뒤 상세 이동과 "변경됨으로 확인" 뒤 목록 이동을 마운트된 동안만
한다. 생성 페이지 테스트에 한 행을 더했다: 저장을 붙잡아 둔 채 breadcrumb으로
목록에 가고, 저장을 끝내면 목록이 새 항목을 보이고(목록 무효화) 1초 안에 상세
heading이 오지 않으며 목록 heading이 남는다. 생성기 단위 테스트가 두 조건과 그
행을 NEVER·KEYED 모두에서 본다. 매뉴얼 reference/create-feature.md에 적었다.
버린 대안: 현재 위치가 작성 라우트인지 보기(다시 돌아온 새 인스턴스가 있으면
옛 인스턴스의 이동도 통과한다), 이동 대신 결과를 남겨 보이기(1106/08-01 (2)처럼;
완료 기준은 이동만 요구해 이번에는 넣지 않았다).
위험·한계: 떠난 뒤 끝난 저장은 다시 돌아온 작성 폼에 결과를 보이지 않는다(참조
폼의 목록 안내는 생성기에 없다). 생성 페이지 테스트의 새 행은 녹색일 때 1초를
기다린다(상세가 오지 않음을 보는 음성 확인). repo 안에 생성 결과 파일은 없다
(src/features/.generated 없음). 이미 생성한 기능에는 반영되지 않는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/create-feature.test.ts, corepack pnpm test:feature-scaffold
(FE-GATE-020, 생성 기능 드릴 NEVER·KEYED)
Refs: 1106/08-02
문제: 계약 문서 6.1절은 §4의 503 RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE에
"자동 재전송은 없다(KEYED도 같다)"고 적는다. 코드는 다르다. 표가 NOT_APPLIED로
정하면 retryHint는 503의 재시도 status 여부이고, 실행기는 NOT_APPLIED인
SAFE·IDEMPOTENT 요청을 retryBudget 안에서 다시 보낸다. 조립은 쓰기의
IDEMPOTENT와 retryBudget > 0을 받는다. CHANGELOG(1105/03-02 행)와 커밋 c6c37f3
본문은 코드와 같다. 그 경로를 보는 테스트가 없다.
고른 방법: 6.1절 문장을 "KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는
retryBudget 안에서 Retry-After(5초 이하) 뒤 다시 보낸다. status로 판단하므로
retryable: false인 RATE_LIMIT_INCOMPATIBLE도 다시 보낸다"로 고친다. 통합
테스트가 IDEMPOTENT PUT(retryBudget 1)의 503 두 code → 200을 fetch 2회, 키
없음, SUCCESS로 고정한다.
버린 대안: INCOMPATIBLE을 다시 보내지 않게 표에 "재시도 안 함"을 싣기(리뷰가
선택으로 둔 별도 동작 변경이다. 쓰기 전 거절이라 중복은 없다).
위험·한계: 동작은 바꾸지 않았다. INCOMPATIBLE은 같은 답을 한 번 더 받는다.
템플릿 안에는 IDEMPOTENT 쓰기가 없다. 이 테스트는 부모 커밋에서도 통과한다
(문서 결함이라 RED가 없다).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/integration/http-execution-v3-envelope.test.ts, corepack pnpm
verify:documentation
Refs: 1106/03-02
문제: 계약 문서 4.1절 끝 줄이 bulk 엔드포인트를 붙이려면 "responseEnvelope를
빼고" 기능 스키마가 본문 전체를 읽으라고 적는다. 1103/16-01(56272e8) 뒤 그
칸은 descriptor 타입의 필수 칸이라 빼면 check:types가 실패한다. 같은 기여에
"NONE"을 적으면 조립이 "a contribution is one backend's package ... split the
contribution per backend"로 거절해 부팅과 check:registries가 실패한다. 같은
절의 바로 위 줄은 "빠뜨리면 check:types가 실패한다"고 적는다. 56272e8이 위
줄만 고치고 이 줄을 남겼다.
고른 방법: 그 줄을 "그 operation을 responseEnvelope: "NONE" as const로 적고
별도 계약 기여에 둔다. 기능 스키마가 본문 전체를 읽고 classifyProblem이 적용
여부를 정한다"로 고친다. 한 기여의 operation은 같은 값을 적는다는 규칙과, 한
기능이 기여 둘을 낼 수 있다는 근거(external-contract-runtime 단위 테스트 "lets
one feature read two backends through two contributions")를 함께 적는다. 리뷰
16-02는 이 항목에 합쳐졌다.
버린 대안: bulk 기여를 조립하는 새 테스트(같은 꼴의 조립은 위 테스트가 이미
본다).
위험·한계: bulk 지원 여부는 여전히 결정 대기(1103/03-02)다. 지원으로 정해지면
이 줄을 그 방법으로 바꾼다. bulk operation을 실제로 붙여 돌려 보지는 않았다.
검증: git grep -n 'responseEnvelope.\{0,4\}를 빼' -- docs ':!docs/reviews' 0건
(노트북). desktop batch에서 확인: corepack pnpm verify:documentation
Refs: 1106/07-01
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.
고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
--dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
--dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
(390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
(gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
가림막 아래에서 한 번 더 어두워진다.
위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.
검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)
Refs: 1106/08-03
문제: 1106 조치 브랜치를 모두 합친 빌드에서 `tests/unit/feature-shape-growth.test.ts`가
"initialJavascript is stale"로 실패한다. 새 context 하나가 더하는 초기 JS가
기록 218 B, 빌드 245 B로 10% 허용치를 넘는다. 합계는 204,111 → 204,193 B로
허용치 256 B 안이다. 브랜치마다는 기록과 맞았고 합친 뒤에만 넘는다.
고른 방법: 합친 끝에서
`node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로
다시 적는다(1105의 같은 기록 커밋과 같은 방법). 기능 하나가 더하는 값은
768 → 751 B다.
위험·한계: 초기 JS 예산 206,848 B(D9)까지 템플릿 여유는 2,655 B, 생성 기능
둘을 더한 FE-GATE-020 드릴은 205,541 B로 여유 1,307 B다(CI env). 기능·context
상한(1 KiB·512 B)은 그대로다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
corepack pnpm ci:gate FE-GATE-020 (CI env)
Refs: 1106/15-01
문제: 2026-11-06 리뷰 조치 27개 커밋(`302d3a5..5cfc3a65`)이 CHANGELOG에
없다. 몇 커밋은 [계약] 행을 CHANGELOG 담당에게 남겼다(13-01 기준선,
02-01 포트 옵션, 03-01 문구 키, 03-03 `resendSafe`, 04-01·04-02, 01-01의
백엔드로 넘김).
고른 방법: 아래 1105 절 위에 새 미출시 절을 둔다. 범위는 `bbde570`(PR B
끝) → 브랜치 `fix/maturity-review-2026-11-06`이다. 이유:
- 머리말 규칙상 절마다 절 머리에 범위를 적고, 그 절의 해시는 모두 그
범위에 있다. 1105 절에 합치면 그 절의 범위(`409d72e` → 11-05-b)와 "해시는
모두 범위 안" 문장이 틀린다.
- 1105 절은 그 범위 끝 `bbde570`의 상태다. 리뷰도 지난 절의 값을 범위 끝
값으로 본다(1106 15 영역의 1103/15-02 판정). 그래서 이 범위가 1105 절의
"지금 값"을 바꾼 것(초기 JS 기록, 6.1절 대조 테스트 파일, 0929/03-03
재전송 조건, 실행 격리)은 새 절에 적고 1105 절은 고치지 않았다.
- 예외는 처음부터 틀린 문장이다. 1105 "먼저 할 일" 1~3단계는 이 라운드의
`2f0f2bb`·`06357e9`이 이미 고쳤고, 새 절 머리에 그 사실을 적었다.
- 1105 절 60행의 `tests/unit/backend-contract-pin.test.ts`는 바꾸지
않았다(지시와 다름). `bbde570`에서는 맞는 이름이다. 새 절 테스트 줄에
6.1절 대조가 `backend-contract-pin-document.test.ts`로 옮겼다고 적었다.
내용은 커밋 본문과 코드에서 옮겼다. 04-02는 [계약] BREAKING으로 적었다.
타입 인자 없이 부르는 호출은 descriptor 타입을 추론해, 입력이 맞지 않거나
`outcome.value`를 겹치지 않는 타입으로 단언한 호출이 `check:types`에서
실패할 수 있다. 두 다운스트림은 이 함수를 부르지 않는다(grep). 커밋은 `!`
없이 들어갔다. "먼저 할 일"은 여섯 단계다: 스키마 행 두 칸(07-02), 문구
키(03-01), 토큰 CSS(08-03), IDEMPOTENT 확인(03-03), CI 기준선(13-01),
poll 타입(04-02). 01-01의 백엔드 요청은 알려진 제한 "백엔드로 넘김"에 둔다.
버린 대안: 1105 절에 합쳐 순 요약으로 다시 쓰기. PR B가 아직 main에 없어
한 동기화 단위로 볼 수도 있지만, 1105 절의 해시 범위와 리뷰가 확인한 75개
해시 대조를 다시 해야 하고, 이미 1105 절을 읽은 다운스트림이 무엇이 바뀌었는지
찾기 어렵다.
위험·한계: 두 다운스트림에 적용해 게이트를 돌려 보지 않았다. 08-03 시각
spec이 제품 셸에서 도는지, 토큰 CSS가 빠졌을 때 가림막이 투명해지는지는
코드를 읽은 판단이다. 이 절의 해시는 이 범위의 커밋 27개와 기준점
`bbde570`, 리뷰 기록 `302d3a5`뿐이다. 1105 절의 해시는 이 범위 밖이라
새 절에 적지 않았다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts
노트북에서는 같은 정규식을 grep으로 흉내 내 괄호 안 라운드 없는 ID와
꼴을 벗어난 참조가 0건인 것만 봤다.
Refs: 1106/01-01, 1106/02-01, 1106/03-01, 1106/03-02, 1106/03-03, 1106/04-01, 1106/04-02, 1106/05-01, 1106/06-01, 1106/06-02, 1106/07-01, 1106/07-02, 1106/08-01, 1106/08-02, 1106/08-03, 1106/09-01, 1106/10-01, 1106/11-01, 1106/12-01, 1106/12-02, 1106/13-01, 1106/14-01, 1106/14-02, 1106/15-01, 1106/16-01, 1103/15-02
문제: 2026-11-06 리뷰 뒤 수정 라운드의 결정(D9·D10)과 발견 25건·1103/15-02의
상태가 리뷰 README에 없다. `docs/operations/performance-evidence.md`는 D9 결정
기록으로 이 README를 가리킨다. 14-02의 완료 기준은 "다음 통합 기록에 해시
대조 결과가 있다"다.
고른 방법: 1105 README 16절과 같은 모양으로 16절을 더한다. 방법(배치 70개),
결정(D9·D10은 메인 세션 결정이고 사용자가 뒤집을 수 있다고 적음, D8은 결정
대기, D1~D3·D11은 그대로), 통합에서 생긴 것(08-03 첫 수정, 초기 JS 재기록),
발견별 상태, 해시 대조 결과를 적는다. 머리 인용에 16절을 가리키는 줄 하나를
더했다. 1~15절은 리뷰 때 그대로 둔다. 16.5절(확인)은 이 커밋을 포함한
끝에서 돌린 결과라 다음 커밋에 적는다.
위험·한계: 해시 대조는 노트북에서 git으로 했다. 리뷰 문서는 history라
verify:documentation이 내용을 보지 않는다.
검증: desktop batch에서 확인.
bash /tmp/claude-gates/r6/scripts/docs-check.sh
git merge-base --is-ancestor <해시> 9b19f753 (16.6절)
Refs: 1106/14-02, 1106/15-01, 1106/03-01
문제: af3344b가 더한 Playwright spec 본문 검색은 대소문자를 무시하고
`_`를 이름 경계로 봤다(`(?<![A-Za-z0-9-])…(?![A-Za-z0-9-])`, `i`).
create:feature는 한 단어 ID(`messages`, `reports`)를 받고 폴더 이름도
ID와 같다. 그래서 `messages` 기능을 지우면 템플릿 자신의
tests/e2e/accessibility.spec.ts(`KO_MESSAGES`)와 scrollbar-gutter
visual spec이 잔여로 잡혀 드릴이 실패한다. `status`·`reports`는 템플릿
spec 여러 개가 평범한 단어로 쓴다. errors.md는 목록에 템플릿 파일이
나오면 템플릿 결함이라 적으므로 제품은 고칠 곳이 없다.
고른 방법: 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는
식별자 문자 `[A-Za-z0-9_-]`다. 폴더 이름이 ID와 다르면 같은 규칙을 쓴다.
그런데 이 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿
spec에 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"가
있다(git grep). `getByRole("status")`는 따옴표 안 한 단어라 따옴표나
문맥 규칙으로도 실제 참조와 구별되지 않는다. 그래서 `-`가 든 이름만 spec
본문에서 찾는다. 한 단어 ID·폴더 이름은 spec 본문 검색에서 빠진다.
검사를 좁히는 변경이지만 이 발견이 바로 그 거짓 양성이다. 거짓 양성은
제거를 막고 고칠 길이 없는 반면, 빠지는 쪽(한 단어 ID만 본문에 적은
spec)은 1106/16-01 전처럼 다음 CI의 브라우저 게이트가 잡는다.
테스트: 템플릿의 spec 파일 전부를 사본에 옮겨 `product-feature`,
`messages`, `status`, `reports`로 돌리면 잔여 0건이다. 적힌 그대로의
ID와 다른 폴더 이름(`invoice-docs`)은 잔여이고, `Invoice-Feature`와
`invoice-feature_v2`는 아니다. 매뉴얼 01 11단계, errors.md, CHANGELOG
1106 절의 16-01 행·확인 2·알려진 제한을 고쳤다.
버린 대안: 따옴표나 `/features/` 문맥만 센다. `getByRole("status")`가
남고, `test.describe("invoice-feature")` 같은 실제 잔여도 문맥에 따라
빠진다. 한 단어 ID를 막는 생성기 규칙은 이 수정 범위 밖이다.
위험·한계: `-`가 든 흔한 이름(예: `read-only`)을 ID로 쓰면 템플릿 spec이
그 이름을 쓸 때 다시 거짓 양성이 난다. 템플릿 spec 0건 테스트는 네
ID만 본다. src 쪽 부분 문자열 검색(1105/16-04)은 그대로다. CHANGELOG
행의 커밋 칸에는 이 커밋 해시를 아직 적지 않았다(같은 커밋에 자기 해시를
적을 수 없다).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/16-01 (diff review DR-02)
문제: e7b1b01 뒤 정책 테스트는 HTTP 자리 스키마의 행이
unknownFieldPolicy를 빼면 실패하고, 적으면 탐침 결과와 비교한다. 탐침이
객체에 닿지 못하는 검증기(두 탐침을 모두 루트에서 거절: `responseBody:
"NONE"` 출력의 z.undefined(), 문자열·null 본문)는 결과가 UNREACHED다.
행 타입은 REJECT_UNKNOWN·STRIP_UNKNOWN만 받으므로, 그런 operation은 행을
어떻게 적어도 통과하지 못한다. 칸을 빼면 `row states no
unknownFieldPolicy`, STRIP_UNKNOWN을 적으면 `row STRIP_UNKNOWN, validator
UNREACHED`다. 템플릿에는 그런 operation이 없어 다운스트림에서 난다.
고른 방법: 리뷰의 가장 작은 방향. 탐침 결과가 UNREACHED인 자리는 정책
비교에서만 빼고, direction은 그대로 요구한다. 두 검사를 슬롯·행을 받는
함수(directionProblems, policyProblems)로 꺼내, 설치된 descriptor 검사와
가짜 스키마 검사가 같은 함수를 쓴다. 새 describe가 z.undefined() 같은
NoContent 검증기로 탐침이 UNREACHED인지, 행이 direction을 빼면 실패하는지,
정책을 빼거나 적어도 통과하는지 본다. 매뉴얼 01, errors.md, CHANGELOG
1106 절의 먼저 할 일 1과 07-02 행에 적었다.
검사를 느슨하게 한 것이 아닌 이유: 탐침은 객체가 없는 스키마의 모르는
필드 정책을 판정할 수 없다. 그 자리의 비교는 맞는 답이 없는 질문이었다.
e7b1b01 전에는 칸을 빼면 이 자리 전체를 건너뛰었다. 지금은 direction을
요구하므로 그때보다 넓다. 객체에 닿는 스키마의 정책 비교는 그대로다.
버린 대안: 행 타입에 객체가 아닌 본문용 값을 더한다. src/contracts의
SchemaDefinition 모양, 분류기, 기준선이 함께 바뀐다.
위험·한계: 행이 UNREACHED 스키마에 적은 정책 값은 아무도 검사하지 않는다.
루트에서 이슈 하나로 거절하는 union(zod `invalid_union`, 예:
strict 객체 | null)도 UNREACHED가 되어 정책 비교에서 빠진다(추론, 실행하지
않음). 고친 곳이 테스트 파일 자신이라 RED는 테스트 파일만으로
만들 수 없다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts
Refs: 1106/07-02 (diff review DR-04)
문제: 9c4cddc의 report는 "로그인 라우트의 paramsSchema = 한 자원 GET의
입력 스키마"만으로 실패 화면 기록을 기대한다. 그 라우트의 페이지가 그
GET을 실제로 부르는지는 보지 않는다. 손으로 쓴 기능이 하위 항목 작성 폼
(`/things/:thingId/parts/new`)의 paramsSchema로 상세 GET과 같은
ThingParams를 쓰면, spec은 한 자원 응답을 보지 못해 기록을 남기지 않고
report가 `a11y.json not written:`으로 FE-GATE-009를 실패시킨다. 그런데
errors.md는 "spec의 기록 호출을 본다. 기능 파일은 고치지 않는다"고만
안내했다. 이 경우 고칠 곳은 기능의 라우트 스키마 ID다.
고른 방법: 리뷰의 첫 방향. report 판정은 그대로 두고 안내를 고친다.
errors.md 행이 두 원인(spec이 기록을 놓침 / 페이지가 그 GET을 부르지
않음)과 각각 고칠 곳을 적는다. 매뉴얼 01 6단계에 같은 경우와 고치는 법
(그 라우트에 자기 paramsSchema)을 더했다. CHANGELOG 1106 절 11-01 행에
같은 줄을 더했다. report의 실패 문장 끝에도 같은 안내를 붙였다. 판정
조건과 문장 앞부분은 그대로라 단위 테스트의 기대(`stringContaining`)도
그대로다.
버린 대안: spec이 "기대했지만 보지 못함"을 따로 기록하고 report가 그
경우를 다르게 다룬다. report 판정이 바뀌어 이번 범위(문서) 밖이다.
위험·한계: 같은 스키마를 쓰면서 그 GET을 부르지 않는 라우트는 여전히
실패한다. 안내로만 풀린다. 그 라우트에 스키마를 따로 두면 FE-REG-SCHEMA
행과 route codec이 하나씩 는다.
검증: desktop batch에서 확인. 테스트 없음(문서와 실패 문장 끝).
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/unit/changelog-review-ids.test.ts
Refs: 1106/11-01 (diff review DR-05)
문제: 1106/03-01(2568587)은 결과 불명 요청을 같은 키로 다시 보낸 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 이유와 상관없이 결과 불명과 키를 남긴다.
같은 요청이 매번 받는 거절(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID,
필드 목록이 있는 입력 검증)도 같다. 폼은 필드 오류를 버리고 "잠시 뒤 같은
요청으로 다시 보내 주세요"만 보인다. 저장은 꺼져 있고 다시 보내면 같은 400이
온다. 출구는 사실이 아닌 "변경됨으로 확인"이나 새로고침뿐이다. 815ea58
(1106/03-03)이 같은 길을 IDEMPOTENT 쓰기로 넓혔다(diff 리뷰 DR-01).
고른 방법(메인 세션 결정, D10 보충): 같은 키 재전송은 그 결과가 첫 요청에
무슨 일이 있었는지 보여 줄 때만 결과 불명을 푼다.
- 성공·APPLIED_CONFIRMED: 저장된 답의 재생이다. 지금처럼 푼다.
- 같은 요청이라 첫 요청도 받았을 거절: 푼다. src/contracts/errors.ts에
isRefusedOnEveryAttempt를 두었다. effect NOT_APPLIED이고, kind
VALIDATION_REJECTED(필드 목록이 있는 입력 검증)이거나 code·status가
REFUSALS_OF_EVERY_ATTEMPT(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)다.
- 그 밖(429, 401, 403, 503 RATE_LIMIT_*, 422 IDEMPOTENT_REQUEST_MISMATCH(키가
이미 서버에 닿아야 나온다), 기능이 선언한 code(바뀌는 상태의 규칙일 수
있다), IDEMPOTENT 쓰기의 404·412 같은 다른 code, NOT_STARTED): 지금처럼
결과 불명과 키를 남긴다. 어느 쪽인지 모르는 code는 남긴다.
훅(resendLeavesUnknown)과 폼(resendLeftUnknown)이 같은 함수를 부른다. 폼은 푼
경우 처음 저장과 같이 보인다(필드 오류, 다시 받는 저장, 고친 값은 새 키).
남긴 경우 결과 불명 화면(확인·다시 보내기)이 그대로라 폼이 영영 막히지
않는다. 표는 backend-envelope.ts REFUSED_BEFORE_WRITE의 부분집합이어야 하고,
표의 나머지 행은 다른 쪽으로 분류된다. backend-envelope 단위 테스트가 둘을
대조해, 표에 새 행이 생기면 이 분류를 정할 때까지 실패한다. presentation은
adapters를 import할 수 없어(.dependency-cruiser.json) 판정을 contracts에 둔다.
버린 대안: 일시 거절(NOT_STARTED, retryable, RATE_LIMITED, RATE_LIMIT_*)만
남기기(diff 리뷰 안). 401·403과 422 IDEMPOTENT_REQUEST_MISMATCH, 기능 선언
code를 풀어 버린다. AppFailure에 새 칸을 더해 실행기가 표시하기(계약 타입과
실행기·바인딩을 함께 바꾼다).
위험·한계: 기능이 선언한 결정적 거절(생성 기능의 400 <FEATURE>_INVALID)은
어느 쪽인지 알 수 없어 결과 불명으로 남는다. 출구는 결과 불명 화면의
확인이다. 필드 목록이 있는 NOT_APPLIED는 기능 선언 code여도 입력 검증으로
본다. 리뷰 실험 03-R1 X1~X3·X5(503·429·NOT_STARTED)는 그대로 키가 모두
key-1이어야 한다. 런북 6.3-4를 고쳤다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (diff review DR-01)
문제: 1106/08-01(fbaaaee)은 제출한 값이 없는(저장 중에 떠났다 다시 마운트한)
폼에서 settleApplied가 화면의 지금 값으로 성공을 정한다. 그 값은 보낸 적이
없다. 사용자가 결과 불명 동안 새 항목을 입력하고 앞의 저장을 "변경됨으로
확인"하면 "저장했습니다"와 함께 입력이 지워진다(기본 resetOnSuccess).
resetOnSuccess: false인 폼은 그 값이 기준값이 되어 dirty와 이탈 확인이 꺼진다
(diff 리뷰 DR-03).
고른 방법: 리뷰의 최소 방향대로, 제출한 값이 없으면 결과(success)와 포커스
이동만 한다. 값·기준값·touched는 건드리지 않고, 오류 표시만 비운다. 08-01의
완료 기준(확인 뒤 "저장했습니다."가 보이고 포커스가 feedback 안)은 그대로다.
버린 대안: 지금 값이 기본값과 같을 때만 정리하기(같은 결과에 분기가 하나 더
는다).
위험·한계: 다시 마운트한 폼에서 확인한 뒤 입력이 남아 있으면 dirty가 남아,
생성 기능 작성 페이지의 확인 뒤 목록 이동이 이탈 확인 창을 띄운다. 보내지
않은 입력을 지키는 쪽이다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx
Refs: 1106/08-01 (diff review DR-03)
문제: 1106 절의 03-01·03-03 행과 "먼저 할 일" 2단계, 알려진 제한은 같은 키
재전송의 쓰기 전 거절을 모두 결과 불명으로 적는다. 80e7f1d 뒤에는 같은 요청이
매번 받는 거절(입력 검증, 400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)이
결과 불명을 푼다. 08-01 행은 다시 마운트한 폼의 확인이 "지금 값으로 성공을
정한다"고 적지만 145be2d 뒤에는 값을 건드리지 않는다.
고른 방법: 그 행들만 고치고 두 커밋 해시를 커밋 칸과 괄호에 더한다. 기능이
선언한 결정적 거절이 결과 불명으로 남는 것은 알려진 제한 03-01 줄에 적는다.
버린 대안: 각 수정 커밋에 함께 넣기(그 커밋 자신의 해시를 적을 수 없다).
위험·한계: 문서만 바꾼다. 해시 대조는 머리말의 사람 단계다(1106/14-02).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1106/03-01 (diff review DR-01), 1106/08-01 (diff review DR-03)
문제: diff 리뷰 DR-02·DR-04·DR-05 조치(`eb03dab`, `efe11f1`, `95141f1`)가
CHANGELOG 1106 절의 16-01·07-02·11-01 행을 고쳤지만 커밋 칸에 자기 해시를
적지 못했다. 같은 커밋 안에서는 자기 해시를 알 수 없다.
고른 방법: 합친 뒤 세 행의 커밋 칸에 해시를 더한다. 문장은 바꾸지 않는다.
위험·한계: 없다. 세 해시는 `git merge-base --is-ancestor`로 이 브랜치 끝의
조상임을 확인했다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
Refs: 1106/16-01 (diff review DR-02), 1106/07-02 (diff review DR-04), 1106/11-01 (diff review DR-05)
문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를
보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는
선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고
(scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와
상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이
선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과
불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로
남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지
않았다(최종 리뷰 FR-01).
고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일
때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind
줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는
상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400
VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다.
테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED +
선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다.
참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과
불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이
다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과
불명과 확인 버튼이 남는 테스트를 더했다.
버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지
폼과 훅에 알리지 않는다).
위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송
뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1
X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts,
리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (final review FR-01)
문제: b41990c 뒤 같은 키 재전송이 400 VALIDATION_FAILED로 거절되면 훅과 폼이
첫 요청도 거절된 것으로 보고 결과 불명을 푼다. 백엔드가 시각이나 데이터베이스를
읽는 규칙을 VALIDATION_FAILED로 내면, 첫 요청이 적용된 뒤의 재전송도 이 답을
받을 수 있다. 계약 문서 6.1절은 이 전제를 적지 않는다(최종 리뷰 FR-02).
고른 방법: 6.1절의 재전송 규칙 옆에 한 문장을 더한다. VALIDATION_FAILED는
요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 규칙은 기능이
선언한 code로 내며 그 code는 결과 불명을 풀지 않는다.
버린 대안: 프론트에서 VALIDATION_FAILED도 결과 불명으로 남기기(메인 세션
결정 "D10 보완 2"가 이 code를 푸는 쪽으로 정했다).
위험·한계: 문서 규칙이다. 백엔드에서 이것을 막는 검사는 없다(6.1절 끝의 남은
위험과 같다).
검증: desktop batch에서 확인. corepack pnpm verify:documentation, node
scripts/run-vitest.ts run tests/unit/backend-contract-pin-document.test.ts
Refs: 1106/03-01 (final review FR-02)
문제: 1106 절의 03-01 행, "먼저 할 일" 2단계, 03-03 행, 알려진 제한 03-01
줄은 입력 검증(kind VALIDATION_REJECTED)이 재전송 뒤 결과 불명을 푼다고
적는다. b41990c 뒤에는 짝 백엔드 표의 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID만 푼다. 6142cc8은 VALIDATION_FAILED가 요청 내용 검사여야
한다는 전제를 계약 문서 6.1절에 적었다.
고른 방법: 그 행들만 고치고 두 커밋 해시를 커밋 칸에 더한다. 참조 기능처럼
problem details를 읽는 기능의 422 입력 검증이 결과 불명으로 남는 것을 알려진
제한 03-01 줄에 적는다.
버린 대안: 수정 커밋에 함께 넣기(그 커밋 자신의 해시를 적을 수 없다).
위험·한계: 문서만 바꾼다. 해시 대조는 머리말의 사람 단계다(1106/14-02).
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/unit/changelog-review-ids.test.ts
Refs: 1106/03-01 (final review FR-01), 1106/03-01 (final review FR-02)
문제: 리뷰 README 16절에 확인(16.5)이 비어 있다. 그 뒤 diff 리뷰(DR-01~06),
마지막 리뷰(FR-01~05)와 메인 세션 결정 D10 보완·보완 2도 적혀 있지 않다.
고른 방법:
- 16.2절에 D10 보완(`80e7f1d6`)과 보완 2(`b41990cd`) 행을 더한다. 둘 다 메인 세션
결정이고 사용자가 뒤집을 수 있다고 적는다.
- 16.4절의 다섯 발견 행에 DR·FR 수정 해시를 더한다.
- 16.5절: `5cfc3a65`, `f1734913`, DR 수정, `59b2ccb5`, FR-01 수정에서 돌린 검사와
돌리지 않은 것을 적는다.
- 16.6절: 해시 대조를 끝 `8b8b6c54` 기준으로 다시 돌린 결과로 바꾼다.
- 16.7절(diff 리뷰): DR-01~05는 고쳤고 DR-06은 이유와 함께 남긴다. DR-02에 메인
기준보다 하나 더한 규칙(`-`가 든 이름만)과 그 이유, 뒤집는 법을 적는다.
- 16.8절(마지막 리뷰): FR-01은 메인 세션에 먼저 알린 뒤 고쳤다. 등급은 Medium·P2이고,
리뷰어가 High로 본 이유도 같이 적는다. FR-02는 계약 문서 한 줄과 백엔드 pin grep
결과를 적는다. FR-03~05는 남긴다.
위험·한계: 이 커밋 자체의 문서 검사 결과는 이 문서에 적을 수 없다. 메인 세션 보고에
적는다. 1~15절은 리뷰 때 그대로다.
검증: desktop batch에서 확인.
bash /tmp/claude-gates/r6/scripts/docs-check.sh
git merge-base --is-ancestor <해시> 8b8b6c54 (16.6절)
Refs: 1106/03-01 (diff review DR-01, final review FR-01·FR-02), 1106/14-02
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
2026-11-06 5라운드 리뷰 기록과, 그 발견을 고친 마지막 수정 라운드다. PR #7 위에 쌓았다. merge 순서는 #5 → #7 → 이 PR이다. base는 main이라, 앞의 둘이 merge되기 전에는 그 커밋도 diff에 보인다.
302d3a5):docs/reviews/2026-11-06-maturity-review/. 기준은bbde570(PR #7 끝)이다. 새 발견은 25건이다(High 0, P1 0, Medium 1, Low 24). 앞 라운드는 1105가 48건(P1 3), 1103이 88건(High 2, P1 12)이었다. 새 High·P1이 0건이라 반복의 멈춤 기준 중 리뷰 부분을 채웠다. 그래서 이번 라운드의 Medium·Low를 고치고 반복을 끝낸다.302d3a5..f1734913): DR-01~05를 고쳤다. DR-06은 남겼다(아래).f1734913..59b2ccb5): FR-01을 고쳤다. FR-02는 계약 문서에 규칙 한 줄을 더했다. FR-03~05는 기록만 하고 고치지 않았다.큰 묶음:
RATE_LIMIT_*, 보내기 전 실패) 다음 저장이 새 키로 나갔다. 이제 결과 불명 상태와 키를 지킨다.VALIDATION_FAILED, 400IDEMPOTENCY_KEY_INVALID.RUN_OUTPUT_ROOT가 있으면 옛 빌드로 판정하던check:bundle(12-02)notChecked분류(11-01)고른 방법과 버린 대안
메인 세션 결정 셋은 README 16.2절에 있다. 셋 다 소유자가 뒤집을 수 있다.
MAYBE_APPLIED로 읽기. 1105/03-02를 되돌리게 되고, 429·401은 그대로 남는다.mapProblem이 붙인 kind는 믿지 않는다.IDEMPOTENT_REQUEST_MISMATCH까지 결과 불명이 풀렸다(FR-01).-가 든 이름만 찾는다.status·reports같은 흔한 한 단어 ID에서 템플릿 자신의 spec이 잔여로 잡혔다.bbde570(spec 본문을 아예 보지 않음)보다 좁지는 않다.287dc6f본문의 옛 해시 대신 맞는 해시를 1105 README D7 행에 적었다.6f06e770에!가 없다. 대신 CHANGELOG 새 절 "먼저 할 일" 6단계에 BREAKING으로 적었다.위험과 영향
direction·unknownFieldPolicy가 필요하다(07-02). 빠지면 다운스트림test:unit이 실패한다.form.resendLater가 필요하다.createBoundedPollCoordinator가 descriptor 타입을 추론한다(DR-06).bbde570대비 104파일, +7,272 / −455줄, 커밋 54개(merge 13개 포함)다. 리뷰 기록 17파일·3,900줄을 빼면 88파일, +3,372 / −455줄이다.:has()를 모르는 브라우저에는 띠가 남는다. Firefox·WebKit은 보지 않았다.검증
1141969에서 merge 단계 게이트 14개를corepack pnpm ci:gate FE-GATE-NNN으로 하나씩 돌렸다.CI=true,VITE_COMMIT_SHA,VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGE(형식만 맞춘 가짜 digest).FE-GATE-013의 사전 점검 뒤 부분은 같은 env에
SOURCE_DATE_EPOCH를 더해 따로 돌렸다.tests/system: 115건 중 97건 통과. 실패 18건은 모두ci-artifact-contract.test.ts의 provider 샌드박스 테스트다. 원인은 bwrap이 loopback을 만들지 못한 것(RTM_NEWADDR)이다. PR #7 끝과 같은 파일에서 같은 수가 실패했다.verify:reproducible-build,build:release-candidate,verify:local-evidence, supply-chain fixture 둘, security fixture,check:browser-security.수정 세션이 돌린 것(desktop, README 16.5절):
key-1이다.f1734913: FE-GATE-020·012(CI env), 빠른 검사 10개, unit 3,077 · component 284 · integration 214 · contract 24 · runtime-schema 60 · visual 7.59b2ccb5: coverage 4,143(risk 418/418).57ffcc96: unit 3,090 · component 296 · features 127, coverage 4,146.Refs:가 있다.실행하지 않은 것:
리뷰어가 볼 곳
합친 커밋 단위로 보면 된다(
git log --first-parent 302d3a5..).c89f8b537f1f875e31faa6f15ac895a090e0c6548a90e485f68fc79681ff05e591dd313abe28e8b8b6c5특히 볼 곳:
src/contracts/errors.ts의isRefusedOnEveryAttempt,src/presentation/adapters/query/application-query.ts,src/presentation/forms/use-app-form.ts: 결과 불명 재전송 규칙scripts/lib/feature-residue.ts: 제거 드릴의 spec 본문 검색(DR-02의-필터)CHANGELOG.md새 미출시 절의 "먼저 할 일 (BREAKING)" 1~6단계docs/reviews/2026-11-06-maturity-review/README.md부터 읽는다. 16절이 조치다.관련
docs/reviews/2026-11-06-maturity-review/README.md16절(조치), 16.2절(결정)문제: 세션 레시피 주석이 "`FeaturePlatformCapabilities`를 `files: SessionBrowserFiles`로 보강한다"고 적는다. 매뉴얼 (`docs/manual/03-outside-feature-folder.md`)은 그 타입을 `src/features/product-capabilities.ts`의 `ProductFeaturePlatformCapabilities`에 적으라고 하고, `declare module` 보강은 `check:types:node`가 키를 보지 못한다고 막는다. 주석대로 하면 앱 typecheck는 통과하고 node typecheck에서 키를 잃는다. 또 레시피 테스트는 `capabilities: {}`로 조립하고 `files.current()`를 레시피 객체에서 직접 불러서, capability가 기능 쪽으로 넘어가는 절반이 깨져도 통과한다. 고른 방법: - 주석이 `ProductFeaturePlatformCapabilities`에 적는 예와 매뉴얼 경로를 보이고, `declare module` 보강은 쓰지 말라고 적는다. - 레시피 테스트가 `capabilities: { files }`를 돌려주고, 템플릿이 설치된 기능의 loader에 넘기는 capability 객체(`createInstalledFeatureLoaders`의 첫 인자)를 기록한다. 테스트의 모든 파일 동작(선택, 읽기, download, 계정 전환 뒤 새 runtime)을 그 객체의 `files.current()`로 돈다. 같은 mock 방식은 `tests/recipes/session-owners-runtime.test.ts`가 이미 쓴다. 버린 대안: `files`를 `needs`에 적은 가짜 기능을 생성 index에 끼워 넣기. `ProductFeaturePlatformCapabilities`가 비어 있는 템플릿에서는 타입을 우회해야 하고, `needs`로 고르는 부분은 1103/09-08 테스트가 이미 잡는다. 위험·한계: 검사는 loader가 받는 capability 객체까지다. 기능 factory가 `needs`로 골라 받는 마지막 단계는 기존 테스트에 맡긴다. 동작 코드는 바뀌지 않는다(주석과 테스트만). 검증: desktop batch에서 확인 - node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts - 변이: 테스트 mock의 `capabilities`에서 `files`를 빼거나, `src/bootstrap/runtime-adapters.ts`의 `...product.capabilities`를 지우면 "Features did not receive the files capability"로 실패해야 한다. Refs: 1105/02-03문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한 백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다. backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift 스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서 답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지 않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고 (worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다. 고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의 `|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json 에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다. - test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에 같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의 `notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을 적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위). - check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를 읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤 HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가 없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라 linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을 올릴 때 사본을 pin 커밋에서 다시 옮긴다. - 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다. 버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답 표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다. 위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을 때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을 손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의 refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이 읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift 출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이 바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표 status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음, --write-excerpt를 돈다. Refs: 1105/07-01문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다 (1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절 (`blockers`)과 page controller 관측(`observe`)은 템플릿 소유 `src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03 "SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친 제품은 템플릿 동기화마다 충돌한다. 고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다. `ProductComposition.serviceWorker?: { blockers?, observe? }` (`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct` 결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립 (`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아 `createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는 blocker는 page controller가 이미 막는 쪽으로 본다. page controller는 `observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지 않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다. 버린 대안: - `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구. 이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은 기존 `composeProduct`를 그대로 둔다. - `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두 벌 생긴다. 위험·한계: 일부만 닫는다. 남은 것: - 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을 제품 소유 자리가 없다(레시피 4·5, 0925/06-05). - realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다 (`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다). `product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이 선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로 통과한다. 검증: desktop batch에서 확인. - node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts - RED: "passes the product's blockers and observer to the page controller"가 옛 조립에서 observe 기록이 비어 실패한다. - 함께: check:types, lint, check:architecture, verify:documentation Refs: 1103/09-05문제 tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴 preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서 strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는 하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다. 3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다. 고른 방법과 버린 대안 - strict fixture의 마지막 판정을 browserFailureVerdict fixture로 뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록 단언). page fixture는 기록을 그 판정에 넘긴다. - spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를 둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히 같은지 본다. - 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄. - WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자, 같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로. - 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가 따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다. - 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다. - 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든 실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다. - 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에 증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다. 위험·한계 - 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다. - 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다. allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는 검사는 더하지 않았다. - 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다. 그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다. 검증 - desktop batch에서 확인: corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진) - 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다. - 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload the page never runs"가 세 엔진에서 실패해야 한다. - WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's unused-preload guess word for word and nothing else"가 실패해야 한다. - browserFailureVerdict 기본값의 expect 제거: "fails a test whose page writes a console error"가 "expected to fail" 위반으로 실패해야 한다. Refs: 1105/11-01문제 접근성 e2e는 보호 라우트의 목록 조회에 빈 목록을 답한다. 자원 하나를 읽는 상세 라우트(참조 기능의 상세, 생성기 --with-create의 상세)는 일반 답이 없어 실패 화면에서 axe를 돌린다. 그런데 scripts/write-a11y-report.ts는 설치된 라우트 전체를 scope에 넣고 automatedStatus "passed"를 쓴다. 화면 내용은 한 번도 검사하지 않은 라우트가 통과로 보고된다. annotation은 test 결과에만 남는다. 고른 방법과 버린 대안 - scripts/lib/a11y-data-state.ts(새 파일): 라우트 test가 끝날 때 자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다. 실패 화면으로만 봤으면 이유를 쓰고, 아니면 지운다. 그래서 라우트마다 마지막 실행이 정한다. 세 엔진이 같은 파일을 쓰므로 임시 파일에 쓰고 rename한다. - tests/e2e/accessibility.spec.ts: 위 기록을 남긴다(공개 라우트와 데이터 상태로 본 라우트는 지운다). - a11y.json schemaVersion 2: scope에는 자기 상태로 검사한 라우트만, notChecked에는 실패 화면으로만 본 라우트와 이유를 넣는다. 둘을 합치면 설치된 라우트 레지스트리와 같아야 한다(schema가 본다). - 상세 라우트를 실제 데이터 상태로 검사하는 안은 버렸다. 출력 validator에서 유효한 값을 일반적으로 만들 수 없고, 기능마다 견본 응답을 받는 자리를 새로 열어야 한다. - annotation을 Playwright JSON reporter로 읽는 안은 버렸다. test:a11y 스크립트의 reporter와 산출물 경로를 바꿔야 하고, 경로는 다른 작업 (12-04)이 바꾸는 중이다. - 매뉴얼(docs/manual/reference/create-feature.md)에 상세 라우트가 notChecked로 적히고 수동 검토가 맡는다고 적는다. 위험·한계 - a11y.json 모양이 바뀐다(schemaVersion 1 → 2, scope 의미, 새 필드). 템플릿 안의 소비자는 ci-artifact-validator 하나이고 같이 바꿨다. - 템플릿 상태에서도 참조 기능의 상세 라우트가 notChecked로 나온다. 지금까지 실제로 검사하지 않던 것이 드러나는 것이다. - 기록 디렉터리는 artifacts/tests 아래 고정 경로다. 12-04가 산출물 경로를 실행마다 나누면 이 경로도 따라가야 한다. - 라우트 test가 돌지 않은 실행에서는 그 라우트의 지난 기록이 남는다. 지난 기록이 "검사 안 함"이면 덜 주장하는 쪽이라 위험하지 않다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts corepack pnpm test:a11y (세 엔진) 뒤 artifacts/tests/a11y.json의 notChecked에 REFERENCE_RESOURCE_DETAIL이 있고 scope에 없어야 한다. - RED: 부모 커밋에는 scripts/lib/a11y-data-state.ts가 없어 새 unit test 파일 전체가 실패한다. Refs: 1103/11-01 BREAKING CHANGE: artifacts/tests/a11y.json이 schemaVersion 2가 된다. scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 notChecked 배열에 { routeId, reason }으로 들어간다. scope를 설치된 라우트 전체로 읽던 도구는 scope와 notChecked를 합쳐 읽는다.문제: 라우트 로딩 화면(280 px)은 720 px 창에 들고 홈 화면(732 px 문서)은 넘친다. 일반(overlay가 아닌) 스크롤바를 쓰는 브라우저에서 홈이 그려지는 프레임에 세로 스크롤바가 생겨 너비가 15 px 줄고 header 오른쪽(세션 영역)이 15 px 밀린다(1280x720·1366x657에서 CLS 0.0002, 리뷰 15-R2 12회). lab과 모든 게이트의 Playwright Chromium은 --hide-scrollbars로 떠서 이 shift를 못 본다. 고른 방법: - base.css의 :root에 scrollbar-gutter: stable을 둔다. 스크롤바 자리가 첫 프레임부터 있어 내용이 길어져도 너비가 바뀌지 않는다. overlay 스크롤바(macOS 기본)는 어느 쪽이든 자리를 쓰지 않는다. - lab(scripts/test-performance.ts)은 labBrowserLaunchOptions()로 --hide-scrollbars를 빼고 띄운다. lab.json context.browser에 scrollbars: "visible"을 남긴다. 이제 lab의 `/` CLS가 같은 회귀를 본다. - 단위 테스트: 실행 옵션이 --hide-scrollbars를 빼는지, :root에 scrollbar-gutter: stable이 있는지. - 시각 골든 5장을 새 gutter에 맞춰 desktop에서 다시 찍는다 (test:visual:update). 버린 대안: html { overflow-y: scroll } — 짧은 화면에도 빈 스크롤바를 그린다. 위험·한계: 스크롤바 폭만큼 오른쪽 여백이 짧은 화면에서도 늘 생긴다. --hide-scrollbars로 뜬 Chromium도 gutter 자리를 잡는다. 그래서 시각 골든 5장이 모두 바뀌었다. 바뀐 것은 내용 폭 15 px다(main 1040 → 1025 px). compact(390 px) 골든은 줄바꿈이 늘어 1297 → 1377 px로 길어졌다. 실제 휴대폰은 overlay 스크롤바라 자리를 쓰지 않으므로, compact 골든은 휴대폰 화면보다 15 px 좁게 그린다. 열린 drawer의 가림막은 gutter를 덮지 않는다 (일반 스크롤바 브라우저에서는 그 자리에 스크롤바가 그려진다). lab의 CLS 예산 0.1은 그대로라 0.0002 shift가 다시 생겨도 lab은 통과한다(값만 남는다). Firefox·Windows 스크롤바 폭은 재지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/lab-performance.test.ts corepack pnpm test:visual (부모 d5b6aeba에서 6건 통과, 이 변경은 옛 골든과 5건이 달라 실패, 다시 찍은 골든에서 통과) corepack pnpm build && corepack pnpm test:performance -- --runs=5 Refs: 1105/15-05문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다. create:feature가 public/release-manifest.json(dev server manifest)의 setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록 (config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시 써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언, a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도 두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔 충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다. 고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는 명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다. - scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를 두고 생성 출력이 충돌 처리 줄에 쓴다. - 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에 두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다. - 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다. 초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서 백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의 verify:documentation). 버린 대안(이번에 하지 않음, 결정 대기): - (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에 만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을 바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다. - (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을 빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다. 위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시 돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리 명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다. 테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지 않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts corepack pnpm verify:documentation corepack pnpm test:realtime-removal Refs: 1105/16-01문제: responseEnvelope는 descriptor의 선택 칸이고 없으면 "NONE"이다. 1103/16-01 수정은 계약 조립이 한 기여 안에서 값이 섞이면 거부하고, refusedBeforeWrite가 있는 쓰기에 Envelope를 요구하게 했다. 그러나 읽기만 있는 기여(기본 생성 판)나 refusedBeforeWrite 없는 쓰기에서 줄을 모두 빼면 조립은 통과하고(모두 같은 NONE), 짝 백엔드의 Envelope를 DTO로 읽어 SCHEMA_MISMATCH로 깨지는 것은 손글씨 gateway 테스트만 잡는다. 지난 완료 기준("줄을 지우면 check:types가 실패한다")을 채우지 못했다. 고른 방법(1103 대안 (b)): InstalledHttpContract의 contract.responseEnvelope를 필수로 바꾼다. 생성 기능·참조 기능·예제의 descriptor는 모두 `satisfies InstalledHttpContract<...>`라 줄을 지우면 tsc가 그 자리에서 실패한다. 줄이 없던 descriptor에 "NONE" as const를 적었다: 참조 기능 셋, tests/helpers/external-contract-fixture.ts 셋, tests/contract/reusable-capability/feature-http-binding.test.ts, scripts/drill-runbook.ts. 값은 전과 같아 FE-REG-API 행과 레지스트리 기준선은 바뀌지 않는다. 조립(external-contract-runtime.ts)은 그대로 빠진 값을 NONE으로 읽는다: TypeScript 밖에서 만든 descriptor를 런타임에 거부하지 않는다. 생성기 주석의 "줄을 지운다" 안내를 "NONE을 적는다"로, 매뉴얼 01(3단계, 짝 백엔드가 아닌 백엔드), errors.md, 계약 문서 4.1절을 같은 뜻으로 고쳤다. 테스트: external-contract-runtime.test.ts에 줄을 뺀 descriptor 선언 위 @ts-expect-error를 두었다. 타입이 다시 선택 칸이 되면 그 지시문이 쓰이지 않아 check:types:test가 실패한다. 같은 테스트가 런타임 조립은 NONE으로 읽는지도 본다. 버린 대안: (c) 기여 단위 기본값 — 규칙이 하나 는다. (d)만으로 두기 — 모두 빠진 경우를 못 막는다. 조립에서 빠진 키를 거부 — JS로 만든 계약 패키지가 런타임에 깨지고, 빠진 값을 일부러 다루는 테스트를 모두 바꿔야 한다. 위험·한계: descriptor를 직접 쓰는 다운스트림 코드는 줄을 더할 때까지 check:types가 실패한다. 모든 operation에 같은 틀린 값을 적는 것(짝 백엔드인데 모두 "NONE")은 여전히 타입도 조립도 통과한다(매뉴얼 "못 잡음"). 이 노트북에서 tsc를 돌리지 못해, 놓친 descriptor가 있으면 desktop check:types가 알려 준다. 검증: desktop batch에서 확인. corepack pnpm check:types node scripts/run-vitest.ts run tests/unit/external-contract-runtime.test.ts tests/features/reference-feature tests/unit/api-operation-rows.test.ts corepack pnpm check:registries (compatibility 변화 없음 기대) BREAKING CHANGE: src/contracts/external-contract-runtime.ts의 InstalledHttpContract에서 contract.responseEnvelope가 필수다. 이 줄이 없는 descriptor는 check:types에서 실패한다. 감싸지 않는 백엔드는 responseEnvelope: "NONE" as const, 짝 백엔드(Envelope)는 "ENVELOPE_V1" as const를 operation마다 적는다. 런타임 동작은 같다. Refs: 1103/16-01문제 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문제 1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조 기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다. 검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation- readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조 기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도 실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가 예제 경로에서 거짓이다. 고른 방법 - 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로, README, starter-experience, static-delivery, compatibility, backend-api-and-server-state-contract, manual-checklist, adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의 참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로 적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다. 1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을 지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과 measure 명령 세 줄도 같은 규칙으로 고쳤다. - patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS 안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈 위치로 고쳤다. - 테스트: template-feature-removal-documents.test.ts에 "names their paths and scripts only where verify:documentation checks them"을 더했다. 검사기가 읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿 기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다. 같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞 커밋의 "passes in a copy without reference-feature"가 본다. - 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책). 검사기와 같은 규칙을 두 곳에 두게 된다. 위험·한계 - 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다. 백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다. - 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이 아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts tests/unit/documentation-readiness.test.ts, corepack pnpm verify:documentation, corepack pnpm test:sample-removal Refs: 1105/14-03문제 매뉴얼 04 §3.2의 PRODUCT_ENV_REGISTRY 예시 두 행(OIDC_ISSUER, OIDC_CLIENT_ID)에 defaultValue가 없다. 행 타입은 defaultValue를 필수 칸으로 가진다(src/contracts/env.ts). 그래서 제품이 그대로 붙이면 check:types:app이 env.ts에서 TS2322로, env-registry-coverage가 `row {"required":false}`로 실패한다(리뷰 14-R3). 매뉴얼 03 C절과 product-contracts.ts 주석은 defaultValue를 쓴다. 고른 방법 - 두 행에 `defaultValue: null`을 더하고(.optional() 키), 행 칸의 규칙을 예시 아래 한 줄로 적었다. - 테스트 tests/unit/manual-paired-backend-settings.test.ts: 매뉴얼 §3.2의 ts 블록을 그대로 저장소 사본의 새 파일로 두고, 사본의 product-contracts.ts가 제품 자신의 파일(옆에 보존)에 그 키를 더해 내보낸다. 그 사본에서 tsconfig.app.json 타입 검사와, env-registry-coverage와 같은 행 대조(키가 없을 때 스키마가 내는 required·defaultValue)를 node로 돌린다. 제품 파일을 덮어쓰지 않으므로 다운스트림에서도 그대로 돈다(1105/09-01과 같은 방식). - 문서를 읽는 테스트라 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. 그 목록의 항목이 문서를 읽는지 보는 removal-fixture.test.ts 정규식에 `docs/`를 더했다. 문서 대상(REMOVAL_FIXTURE_DOCUMENT_TARGETS)에 docs가 있어 README나 CHANGELOG를 읽지 않는 문서 테스트도 있을 수 있다. 목록의 뜻은 그대로다. - 버린 대안: 예시 행을 recipe에서 export하고 recipe 테스트가 그것으로 조립하기(리뷰 ②). contracts가 recipe를 import할 수 없어 매뉴얼이 다시 복사를 시킨다. 이번 테스트가 매뉴얼 블록 자체를 지킨다. 위험·한계 - 행 대조는 env-registry-coverage의 schemaDeclaration을 이 테스트 안에 다시 적었다(사본에서 vitest를 띄우지 않으려고). 규칙이 바뀌면 둘을 함께 고친다. - §3.3·§4.3의 코드 예시는 여전히 컴파일하지 않는다(recipe를 복사한 뒤의 모양이라 사본 구성이 더 크다). - 테스트가 저장소 사본을 만들고 tsc app 프로그램을 돈다. test:unit이 몇 초 는다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/manual-paired-backend-settings.test.ts tests/unit/removal-fixture.test.ts, corepack pnpm verify:documentation Refs: 1105/14-02문제: 저장소 설계 문서와 VD-13이 Web Storage registry 행을 "현재" 목록으로 적는다. 설계 문서 50-52행은 8행 중 4행(`COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`, `AUTH_TOKEN`, `QUERY_PERSISTENCE`)만, 0절 표와 16.2절 기본 조립 표와 VD-13 2.1절 표·7.1절 문단은 `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD` 둘만("두 key") 적는다. registry에는 기본 조립이 쓰는 `LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 행 `CACHE_INVALIDATION_PULSE`·`AUTH_REDIRECT_TRANSACTION`도 있다 (`src/contracts/storage-keys.ts`, `create-application.ts`, `boot-release-recovery.ts`). 행을 더한 커밋들이 이 문장을 따라 고치지 않았다. 고른 방법: 목록 문장을 지우고 `STORAGE_REGISTRY`를 정본으로 가리킨다. StoragePort가 거절하는 행의 규칙(`sensitive-forbidden` 분류와 `backend: "external"`, `getStorageDefinition`)만 문장으로 남긴다. 표 두 행은 "StoragePort 행" 한 행으로 합친다. 8행을 모두 적는 대안은 버렸다. 다음에 행이 늘면 같은 식으로 낡는다. 위험·한계: 이 문장을 보는 검사는 없다. 두 문서는 docs/README.md 2절(목표 설계)이라 verify:documentation이 읽지 않는다. 다시 목록을 적으면 리뷰가 손으로 찾아야 한다. 검증: 문서만 바꿨다. 검사 없음(위). `git grep -n 'COLOR_SCHEME' -- docs/architecture`에 목록 문장이 남지 않았다(starter-experience.md의 테마 설명 한 줄만 남는다). Refs: 1106/05-01문제: 1103/16-05로 `BoundMutation.operationId`가 brand 타입이 됐고, 그 값은 `commandMutationIdentity`만 만든다. 이 함수는 descriptor 모양 `{ contract: { operationId, method, retrySemantics } }`만 받는다. CHANGELOG "먼저 할 일" 2단계와 매뉴얼 01 7단계는 descriptor 상수 길만 적는다. V3 descriptor가 없는 쓰기(Fileserver 업로드 client는 `upload(request)`만 있다)와 테스트 fixture는 길이 없어, 따라 하면 `check:types`에서 막힌다. 템플릿은 자기 테스트에 `tests/helpers/mutation-operation-id.ts`를 두었지만 어느 문서도 그 helper를 말하지 않는다. 매뉴얼 01 안에서도 "손으로 적은 ID에 오타가 있으면 저장이 항상 실패한다"(BREAKING 전 동작)와 "문자열로 직접 적으면 `check:types`가 실패한다"가 서로 다르다. 고른 방법: 문서만 고친다(리뷰의 대안 A). descriptor 없는 쓰기는 descriptor 모양 객체를 넘기고, 키가 필요하면 `KEYED`, 아니면 `NEVER`를 적는다고 쓴다. 대조할 descriptor가 없어 그 ID는 intent 이름일 뿐이고 오타를 잡는 검사가 없다는 것도 적는다. 테스트는 `testMutationOperationId`를 쓰고 `requiresIdempotencyKey`는 따로 적는다. 매뉴얼 01의 "저장 때 실패" 문장은 손 객체를 넘긴 경우로 좁히고, "못 잡음" 항목을 descriptor가 있는 쓰기와 없는 쓰기로 나눈다. 버린 대안: 이름 있는 함수(B)나 Fileserver 업로드 descriptor 상수(C)를 공개하기. 공개 API가 늘고 코드 변경이라 이 문서 브랜치의 범위 밖이다. 리뷰도 A를 가장 작은 길로 적었다. 위험·한계: 손 객체가 공식 길이 된다. descriptor 없는 쓰기의 ID 오타는 여전히 아무 검사도 잡지 않는다(문서에 그렇게 적었다). 두 다운스트림의 손 ID 정책 중 몇 개가 이 길로 가야 하는지는 세지 않았다. 검증: 문서만 바꿨다. desktop batch에서 확인. corepack pnpm verify:documentation (매뉴얼 01이 새로 적은 경로 `tests/helpers/mutation-operation-id.ts`와 script `check:types:test`가 있는지) node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts Refs: 1106/09-01문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전 거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패 (NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서 결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로 나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는 그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에 새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2). 고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)): - 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가 NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그 intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와 같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신 markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외 (.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은 결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의 성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다. - 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서 unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구 하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를 formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로 저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이 그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를 받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로 미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다. 버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가 남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성 기능만 덮는다). 위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시 보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은 입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를 보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금 늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에 적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1. Refs: 1106/03-01문제: 1105/16-04 수정 뒤 제품 기능 제거 드릴의 tests 잔여는 파일 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일뿐이다. 주석과 매뉴얼 01 11단계는 빠진 경우(본문에만 ID가 있는 테스트)를 test:all이 잡는다고 적었다. 그런데 test:all은 vitest 묶음이고 vitest는 tests의 *.test.ts(x)만 돈다. tests/e2e·visual 등의 *.spec.ts는 test:all도 드릴의 다른 단계도 돌리지 않는다. 그래서 `test.describe("invoice-feature", …)`처럼 본문에만 ID를 담은 spec은 드릴을 통과하고, 다음 CI의 브라우저 게이트에서 지운 라우트를 열다가 실패한다. 고른 방법: 리뷰의 (b). tests 중 vitest가 돌지 않는 Playwright spec (`*.spec.[cm]?[jt]sx?`)은 본문도 찾는다. 다만 1105/16-04가 없앤 부분 문자열 검색으로 돌아가지 않고, 기능 ID·폴더 이름을 앞뒤가 영문·숫자·`-`가 아닌 한 이름으로만 찾는다. `"invoice-feature"`, `'invoices'`, `/features/invoices/`는 잔여이고, product-feature를 지울 때 `generate-product-feature-index.ts`·`data-product-feature`· `product-features`는 잔여가 아니다. vitest 테스트 본문은 그대로 찾지 않는다 (템플릿 테스트가 예시 ID를 데이터로 쓴다). 템플릿 자신의 spec에는 invoice-feature·product-feature·scaffold-feature가 한 이름으로 나오지 않는다 (git grep 0건). 그래서 16-R2(invoice-feature 제거)와 FE-GATE-020 (scaffold-feature)은 그대로 통과해야 한다. 주석, 매뉴얼 01 11단계, errors.md의 판정 문장을 고쳤다. 버린 대안: (a) 문서만 고친다. 빈틈이 남는다. spec 본문을 부분 문자열로 찾는다: 짧은 ID와 템플릿 이름(`generate-product-feature-index`)이 거짓 양성을 다시 낸다. tests의 모든 비-vitest 파일(helpers, mocks, fixtures)을 찾는다: tests/helpers/runtime-capabilities-stub.ts가 주석에 "product-feature"를 한 이름으로 적어 거짓 양성이 된다. spec이 import하는 helper는 spec이 지워지면 아무 데서도 돌지 않아 해가 없다. 위험·한계: route ID나 URL만 적은 spec은 여전히 못 잡는다(03 손 목록). 다운스트림 spec이 무관한 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 1105/16-04의 남은 부분(src 경로·본문과 tests 파일 이름의 부분 문자열 검색, dist 빌드 잔여 검사)은 이 변경이 덮지 않아 그대로 두었다. 같은 이름 단위 검색으로 바꾸면 product-feature의 거짓 양성(16-R3, 20파일)은 풀리지만, 폴더 이름에 붙은 식별자(`invoices` → `InvoicesPage`)와 `<id>-helpers.test.ts` 같은 파일 이름을 놓쳐 검사가 좁아진다. 따로 정한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts corepack pnpm create:feature invoice-feature에 본문에만 ID를 적은 tests/e2e/checkout.spec.ts를 더한 뒤 corepack pnpm test:sample-removal -- --feature=invoice-feature가 fixture-id-residue로 실패, spec 없이는 통과 Refs: 1106/16-01문제: poll `execute`가 받는 `input.operation`은 `BoundedPollOperation` (`InstalledHttpContract<unknown, unknown, unknown>`)이다. 권하는 대로 `executor.execute(input.operation, x, …)`를 부르면 `Input`이 `unknown`이 되어 `x`는 아무 값이나 통과하고 `outcome.value`도 `unknown`이다. 입력이 틀리면 런타임 `CONTRACT_VIOLATION`(INPUT_INVALID)으로만 드러난다. 타입을 지키려면 클로저 descriptor를 써야 해서 1103/04-01의 잔여 위험(다른 행을 실행) 쪽이 유리해진다. 또 V3 결과 9종을 poll 결과로 바꾸는 대응표가 없다. repo의 유일한 V3 조합 예(테스트)는 SUCCESS 외 전부를 retryable PROVIDER_UNAVAILABLE로 바꿔, 옮기면 401·403·입력 거절도 maxAttempts번 다시 요청된다. 고른 방법: 리뷰 선택지 (b) + (c). - `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에 `Operation extends BoundedPollOperation = BoundedPollOperation`을 더하고 `operation`·`input.operation`을 `Operation`으로 둔다. `operation`에서 추론되므로 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다. 런타임 코드는 바뀌지 않는다. - 설계 9.2에 V3 결과 kind마다 poll 결과(kind, retryable, retryAfterMs)를 적은 표를 두고, 13.1 PROVIDER_UNAVAILABLE 행에서 그 표를 가리킨다. 9.2 "auth에서 lease 종료", 9.3 "401은 attempt를 끝낸다", 9.4, 13.1과 맞췄다. `retryAfterMs`는 값이 있을 때만 둔다(빈 칸은 모양 오류). - 테스트 조합 예를 표대로 바꿨다(`pollAttemptResult`). 503 재시도 테스트는 같은 결과다(503 PROBLEM → retryable PROVIDER_UNAVAILABLE). - 테스트: 틀린 입력에 `@ts-expect-error`, 출력을 기능 타입으로 받는 타입 테스트 1건. 401·403이 요청 1번으로 lease를 끝내는 테스트 2건. 버린 대안: - (d) 대응 함수를 bootstrap이나 recipe에 두기. realtime 어댑터는 adapters/http 타입을 import할 수 없고, 레시피 번들과 제거 드릴 범위가 바뀐다. - `BoundedPollOperation` 자체를 제네릭으로 바꾸기. application 정책의 공개 이름이 바뀐다. 제약으로만 두면 기존 이름이 그대로다. 위험·한계: - 기존 호출은 그대로 컴파일된다. `Value`를 직접 적은 호출은 `Operation`이 기본값이라 예전처럼 `unknown`이다. 타입을 원하면 둘 다 적거나 추론에 맡긴다(타입 주석과 9.2에 적음). 그래서 `!`를 붙이지 않았다. 단, 추론에 맡긴 호출이 descriptor 타입과 다른 입력을 실행기에 넘기고 있었다면 이제 check:types가 실패한다. 이 커밋이 잡으려는 결함이다. - 표는 조합 코드가 따를 규칙이고 강제 수단은 없다. 템플릿은 poll `execute` 기본 구현을 주지 않는다(리뷰 재검토 조건). - 409·410의 `CURSOR_EXPIRED` 행은 reset 계약이 있는 기능만 해당한다. 테스트 계약에는 없어 테스트 예는 그 갈래가 없다. - CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다. 검증: desktop batch에서 확인. - corepack pnpm check:types:test - node scripts/run-vitest.ts run tests/unit/realtime/bounded-poll-coordinator.test.ts - RED: 부모 커밋의 src에서 check:types:test가 실패한다. bounded-poll-coordinator.test.ts의 `@ts-expect-error` 줄이 TS2578(쓰이지 않은 지시문, 입력이 `unknown`이라 `{ size: 20 }`이 통과), 그 아래 `pollAttemptResult<…>(outcome)`이 TS2345(`outcome.value`가 `unknown`). vitest 테스트는 양쪽에서 통과한다. - lint, check:architecture, verify:documentation Refs: 1106/04-02-가 든 이름만 찾는다 eb03dabdfd문제: af3344b가 더한 Playwright spec 본문 검색은 대소문자를 무시하고 `_`를 이름 경계로 봤다(`(?<![A-Za-z0-9-])…(?![A-Za-z0-9-])`, `i`). create:feature는 한 단어 ID(`messages`, `reports`)를 받고 폴더 이름도 ID와 같다. 그래서 `messages` 기능을 지우면 템플릿 자신의 tests/e2e/accessibility.spec.ts(`KO_MESSAGES`)와 scrollbar-gutter visual spec이 잔여로 잡혀 드릴이 실패한다. `status`·`reports`는 템플릿 spec 여러 개가 평범한 단어로 쓴다. errors.md는 목록에 템플릿 파일이 나오면 템플릿 결함이라 적으므로 제품은 고칠 곳이 없다. 고른 방법: 메인 세션 기준대로 적힌 그대로(대소문자 구분) 찾고, 경계는 식별자 문자 `[A-Za-z0-9_-]`다. 폴더 이름이 ID와 다르면 같은 규칙을 쓴다. 그런데 이 둘만으로는 `status`·`reports`가 0건이 되지 않는다. 템플릿 spec에 `status: 200`, `getByRole("status")`, 테스트 제목의 "reports"가 있다(git grep). `getByRole("status")`는 따옴표 안 한 단어라 따옴표나 문맥 규칙으로도 실제 참조와 구별되지 않는다. 그래서 `-`가 든 이름만 spec 본문에서 찾는다. 한 단어 ID·폴더 이름은 spec 본문 검색에서 빠진다. 검사를 좁히는 변경이지만 이 발견이 바로 그 거짓 양성이다. 거짓 양성은 제거를 막고 고칠 길이 없는 반면, 빠지는 쪽(한 단어 ID만 본문에 적은 spec)은 1106/16-01 전처럼 다음 CI의 브라우저 게이트가 잡는다. 테스트: 템플릿의 spec 파일 전부를 사본에 옮겨 `product-feature`, `messages`, `status`, `reports`로 돌리면 잔여 0건이다. 적힌 그대로의 ID와 다른 폴더 이름(`invoice-docs`)은 잔여이고, `Invoice-Feature`와 `invoice-feature_v2`는 아니다. 매뉴얼 01 11단계, errors.md, CHANGELOG 1106 절의 16-01 행·확인 2·알려진 제한을 고쳤다. 버린 대안: 따옴표나 `/features/` 문맥만 센다. `getByRole("status")`가 남고, `test.describe("invoice-feature")` 같은 실제 잔여도 문맥에 따라 빠진다. 한 단어 ID를 막는 생성기 규칙은 이 수정 범위 밖이다. 위험·한계: `-`가 든 흔한 이름(예: `read-only`)을 ID로 쓰면 템플릿 spec이 그 이름을 쓸 때 다시 거짓 양성이 난다. 템플릿 spec 0건 테스트는 네 ID만 본다. src 쪽 부분 문자열 검색(1105/16-04)은 그대로다. CHANGELOG 행의 커밋 칸에는 이 커밋 해시를 아직 적지 않았다(같은 커밋에 자기 해시를 적을 수 없다). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts Refs: 1106/16-01 (diff review DR-02)