Commit Graph
1053 Commits
Author SHA1 Message Date
DongHyeonka 1f4b929fbe test(service-worker): marker 읽기 상한 test가 5초보다 긴 상한을 잡는다
문제
"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
2026-11-06 05:18:25 +09:00
DongHyeonka 2a78169c58 fix(hosting): live probe가 redirect된 워커 스크립트를 거절한다
문제
워커를 싣는 빌드에서 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
2026-11-06 05:17:04 +09:00
DongHyeonka 302d3a5359 docs(review): 2026-11-06 5라운드 성숙도 리뷰 결과를 기록한다
문제: 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
2026-11-06 05:06:05 +09:00
DongHyeonka bbde570796 docs(review): 1105 조치의 결정·통합 문제·발견별 상태를 적는다
문제: 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
2026-11-06 03:00:21 +09:00
DongHyeonka 287dc6fa9b build(perf): 초기 JS 예산을 202 KiB로 올린다
문제: 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
2026-11-06 02:59:03 +09:00
DongHyeonka 0fee3fefb9 chore(scale): 합친 빌드로 초기 JS 기록을 다시 적는다
문제: 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
2026-11-06 02:59:03 +09:00
DongHyeonka c14e59f459 chore(review): 1105 문서·CHANGELOG 조치 브랜치를 합친다 2026-11-06 02:59:03 +09:00
DongHyeonka 1c884e1bd9 docs(changelog): 1105 PR B 조치와 남은 항목을 새 미출시 절에 적는다
문제
새 미출시 절(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)
2026-11-06 02:59:03 +09:00
DongHyeonka c3c595f7a3 chore(review): 1105 CI 기준선 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 57e3586292 docs(readme): 미출시 범위를 한 번에 받는 명령과 기준점 기록을 적는다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka b8d53c9aae chore(review): 1105 성능·구조 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘.
- 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
2026-11-06 02:59:02 +09:00
DongHyeonka 1ac336a72a docs: 루트 SPEC.md·tasks/를 두는 이유를 끝난 라운드에 맞춘다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka 703a33559f chore(review): 1105 가드레일·CI 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 1c4e57c0ca docs(operations): 남은 FEATURE_OVERRIDES 키가 경고를 남긴다고 적는다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka 1a29d4aa85 chore(review): 1105 실행 격리 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka b834b8d7ec docs(changelog): 리뷰 README 절과 영역 문서 ID의 꼴을 머리에 적고 테스트한다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka d5a70b4267 chore(review): 1105 테스트 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka f4be42685c docs(changelog): 두 제품이 고친 템플릿 파일을 옮길 곳과 자리 없는 것으로 나눈다
문제
"옮기기 전" 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
2026-11-06 02:59:02 +09:00
DongHyeonka 45c9c4dc48 chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 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
2026-11-06 02:59:02 +09:00
DongHyeonka 1e576ef1aa docs(changelog): 11-03 절 poll 행에 던지는 execute 규칙이 바뀌었다고 적는다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka 832774f475 docs(changelog): 11-03 절의 초기 파일 상한과 알려진 제한 기준을 끝 커밋에 맞춘다
문제
미출시 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
2026-11-06 02:59:02 +09:00
DongHyeonka e6b2a4f6bf fix(manual): 짝 백엔드 OIDC 설정 키 예시의 FE-REG-ENV 행에 defaultValue를 적는다
문제
매뉴얼 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
2026-11-06 02:59:02 +09:00
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka 332bfee9b8 fix(docs): 지운 템플릿 기능의 경로를 문서 검사가 요구하지 않는다
문제
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
2026-11-06 02:59:02 +09:00
DongHyeonka 50b631e4cd refactor(removal): 지울 수 있는 템플릿 기능 목록을 한 모듈에 둔다
문제
템플릿은 지울 수 있는 기능을 둘 둔다. 참조 기능(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
2026-11-06 02:59:02 +09:00
DongHyeonka 57c34ea626 chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 7af80859e5 chore(review): 1105 브라우저 파일·캐시·저장소 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 19d10538d6 chore(review): 1105 HTTP 판정·폼 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 510e2bbceb docs(testing): 한 checkout 두 실행의 run ID·포트 변수를 적는다
문제: 실행 격리(앞 두 커밋)의 변수(`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
2026-11-06 02:58:00 +09:00
DongHyeonka 0e72c0c116 fix(test-run): Playwright 서버가 빈 포트를 고르고 dev 서버를 재사용하지 않는다
문제: 다섯 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
2026-11-06 02:58:00 +09:00
DongHyeonka f849d781d1 fix(home): 홈 시작 링크가 런타임에 꺼진 기능을 고르지 않는다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka 90c489c31a fix(scaffold): 생성 폼이 "변경됨으로 확인" 뒤 목록을 연다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka f2b8ba75d3 fix(forms): 다른 저장이 진행 중이면 저장 버튼을 끄고 진행 문구를 보인다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka 4f3c10bc56 fix(forms): 복구 버튼으로 끝낸 저장 뒤 포커스를 feedback 자리에 둔다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka 12d97d7469 feat(forms): 기능이 백엔드 거절 code에 자기 문구를 붙인다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka 683ccfb56b fix(query): 키 없는 결과 불명 요청의 같은 입력 재제출을 훅이 막는다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka c6c37f395b fix(http): 백엔드 rate-limit 503 두 code를 쓰기 전 거절로 읽는다
문제
짝 백엔드 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
2026-11-06 02:33:16 +09:00
DongHyeonka 5c0b37e39e fix(contracts)!: 쓰기 뒤에도 나오는 플랫폼 code를 쓰기 전 거절로 적지 못하게 한다
문제
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
2026-11-06 02:33:16 +09:00
DongHyeonka 56272e86d5 fix(contracts)!: HTTP descriptor의 responseEnvelope를 필수 칸으로 둔다
문제: 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
2026-11-06 02:12:06 +09:00
DongHyeonka 6d084cf6a2 docs(manual): 기능마다 바뀌는 추적 파일 둘과 충돌 처리 명령을 적는다
문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
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
2026-11-06 02:12:06 +09:00
DongHyeonka f4d5761a2a fix(test-run): 실행마다 빌드·Playwright 출력 폴더를 따로 쓴다
문제: 빌드는 `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
2026-11-06 02:11:17 +09:00
DongHyeonka f2a4f32a91 docs(cache-storage): inspect의 verified 뜻과 비용을 port에 적고 판정 불가를 고정한다
문제: `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
2026-11-06 02:07:47 +09:00
DongHyeonka 11a0fd0f49 test(cross-context): host가 캡처한 localStorage의 pulse만 받는지 고정한다
문제: 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
2026-11-06 02:07:47 +09:00
DongHyeonka dc7c95b005 fix(recipes): OIDC PKCE 레시피가 sessionStorage 키를 registry에서 가져온다
문제: 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
2026-11-06 02:07:47 +09:00
DongHyeonka f600e6b132 fix(contracts): 짝 백엔드 pin과 drift 검사가 생성기 템플릿 사실도 대조한다
문제: 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
2026-11-06 01:23:48 +09:00
DongHyeonka b45d6a03db fix(removal): 제품 기능 제거 드릴이 템플릿 테스트의 예시 ID를 잔여로 세지 않는다
문제: 매뉴얼 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
2026-11-06 01:23:48 +09:00
DongHyeonka 81701add7e feat(perf): lab이 기능 라우트 첫 진입을 재고 500 ms 예산으로 판정한다
문제: 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
2026-11-06 01:23:48 +09:00
DongHyeonka 138c195fcd fix(examples): 릴리스 신원 칸의 자리를 미리 잡고 lab이 대상 화면 직접 진입 CLS를 잰다
문제: 플랫폼 구성 화면(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
2026-11-06 01:23:48 +09:00
DongHyeonka e02f252d57 fix(theme): 스크롤바 자리를 첫 화면부터 잡고 lab을 스크롤바와 함께 잰다
문제: 라우트 로딩 화면(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
2026-11-06 01:23:48 +09:00
DongHyeonka 46359a1c79 fix(scale): 초기 JS 기록 대조의 합계 허용 오차를 256 B로 둔다
문제: 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
2026-11-06 01:23:48 +09:00