Commit Graph
98 Commits
Author SHA1 Message Date
DongHyeonka 8a9bc978a9 Merge branch 'fix/r9-primitive-a11y' into fix/r9-form-and-primitives
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 15m8s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 7m8s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
2026-11-13 10:28:11 +09:00
DongHyeonka fccfa27ec2 Merge remote-tracking branch 'origin/main' into fix/r9-form-and-primitives 2026-11-13 08:45:29 +09:00
DongHyeonka d4aa365bd9 fix(query): stale 실패를 렌더 중에 계산하고 실패 진단이 원인을 남긴다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m26s
frontend-quality-gates / merge / tests (pull_request) Failing after 15m50s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 11m10s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
useApplicationQuery가 "데이터가 있고 마지막 조회가 실패했다"는 파생 값을
effect로 state에 복사한다. 다시 시도가 그 값을 지운 뒤 refetch해도, 조회
중에 effect가 다시 돌아 true로 되돌린다. 그래서 낡은 데이터의 다시 시도가
진행 중에도 지난 실패(stale-degraded)를 보인다(1112/01-05).

query·mutation 실패 진단은 원인을 버린다. cache의 onError가 모든 실패를
cache.operation.failed로 남기는데, ApplicationQueryError에 kind가 없어
safeErrorKind가 이름(APPLICATION_QUERY_ERROR)을 쓴다. 404, 필드 거절,
abort가 한 가지로 남는다. 예상 밖 throw는 정의 이름 대신 고정 문자열
(APPLICATION_QUERY, APPLICATION_MUTATION)을 쓴다(1112/01-04).

고른 방법: staleFailure를 query.isError && hasData && !isFetching으로 렌더
중에 계산하고 state와 effect를 지운다. 다시 시도 중은 refreshing이다.
ApplicationQueryError가 failure.kind를 kind로 싣는다. 예상 밖 throw는 query
정의 ID와 mutation 정의 ID를 쓰고, 정의가 없는 legacy mutation만 옛 이름을
둔다. 버린 대안: cache onError가 ApplicationQueryError를 아예 세지 않기
(서버 실패를 cache 진단에서 잃는다).

위험·한계: 낡은 데이터의 배경 재조회 중에도 stale 대신 refreshing을
보인다. 진단 error_kind 값이 바뀌어 그 값을 읽는 대시보드가 있으면
바꿔야 한다(템플릿 안에는 없다).

검증: tests/component/application-query-bridge.test.tsx의 새 시험 셋이
고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문).

Refs: 1112/01-04, 1112/01-05
2026-11-13 01:50:35 +09:00
DongHyeonka 42b183f72c fix(design-system): Dialog 밖 Popover·Tooltip이 Dialog의 Escape를 막지 않는다
앞 커밋은 Popover와 보이는 Tooltip이 Escape를 document capture 단계에서
받아 기본 동작을 막게 했다(1112/05-11). 그런데 대상이 어디인지 보지 않는다.
열린 popover를 Tab으로 벗어나 키보드로 Dialog를 열거나, tooltip이 보이는
채로 Dialog가 열리면, Dialog 안의 첫 Escape를 뒤쪽 층이 먹고 Dialog는 닫히지
않는다. 고치기 전에는 둘 다 닫혔다(확인 리뷰).

고른 방법: escape-layer.ts의 escapeIsForLayer가 Escape를 누른 곳이 그 층을
품지 않은 dialog 안이면 그 Escape를 dialog 것으로 본다. 층 안, 층을 품은
dialog 안, 요소 밖(포커스가 body)에서 누른 Escape는 층의 것이다. Popover와
Tooltip이 이것을 묻는다. 버린 대안: 대상이 층 안일 때만 받기(WebKit은 클릭한
버튼에 포커스를 주지 않아 열린 popover가 Escape로 닫히지 않는다).

위험·한계: native <dialog>가 아닌 modal(role="dialog"만 단 것)은 이 판정이
모른다. 템플릿의 Dialog·Drawer는 <dialog>다.

검증: design-system-a11y.test.tsx의 새 시험 셋(Dialog 밖 Popover, Dialog 밖
Tooltip, body에서 누른 Escape)이 고치기 전 코드에서 앞 둘이 실패하고 셋째는
통과(대조)하며, 고친 뒤 모두 통과한다(desktop, PR 본문).

Refs: 1112/05-11
2026-11-13 00:05:26 +09:00
DongHyeonka 63ba523519 fix(form): 저장 뒤 이동과 마운트 판정을 폼이 맡고 다시 로그인 안내를 먼저 그린다
앞 커밋(1112/01-01) 뒤 확인 리뷰가 완료 기준의 남은 셋과 결함 둘을 찾았다.

- 생성 작성 페이지에 마운트 표시(useRef)와 저장 뒤 이동이 남았다. 저장이
  끝나면 페이지가 폼보다 먼저, 폼이 pending인 동안 상세로 옮겼다. 다시
  마운트한 폼에서 재전송이 성공하면 사용자가 돌아와 입력한, 보낸 적 없는
  값을 이탈 확인 없이 버렸다(1112/01-02 영향).
- 폼이 재전송 결과로 결과 불명을 다시 판정했다(resendLeftUnknown).
  코디네이터와 401에서 갈린다. 코디네이터는 결과 불명을 쥐고 폼은 다시
  로그인으로 가는데, FormSaveFeedback이 결과 불명을 먼저 그려 다시 로그인
  안내를 가렸다(D-2 위반).
- 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 생성 페이지 시험에만
  있었다.

고른 방법: useAppForm에 onSaved를 더한다(추가만). 폼이 결과를 보이고
pending을 끈 뒤, 마운트된 동안만 부른다. confirmUnknownEffect(then)도
마운트된 동안만 then을 부른다. resendUnknownEffect의 then 인자와
FormSaveFeedback의 onResent는 지운다(앞 커밋에서 생겨 아직 내보낸 적이
없다). 재전송 뒤 결과 불명인지는 코디네이터의 새 holdsUnknownEffect로
묻는다. mutation 없이 쓰는 폼(이미 생성한 페이지)은 물을 곳이 없어 같은
거절 표(isRefusedOnEveryAttempt)로 본다. FormSaveFeedback은 다시 로그인
실패를 결과 불명보다 먼저 그린다. 생성 페이지는 mutation.submit을 그대로
넘기고 onSaved와 onConfirmed에서 옮기기만 한다. VD-04 머리 칸에 넣었던
문장은 보완 절로 옮긴다(머리 칸의 백틱 낱말을 문서 검사가 경로로 본다).
페이지가 FormSaveFeedback을 늘 넘기므로, 할 말이 없는 피드백 칸은 자리를
차지하지 않는다(templates.css, 빈 칸이 그리드 간격을 한 줄 더했다).

위험·한계: 저장 뒤 이동이 폼이 결과를 그린 뒤로 한 번 늦어진다. 다시
마운트한 폼에 보내지 않은 값이 있으면 이동이 이탈 확인을 띄운다(의도).

검증: form-foundation 새 시험 일곱과 create-feature 생성 페이지 시험
(RED·GREEN, 막기·다른 저장·충돌 안내 변이 셋), 생성 기능 e2e의 피드백 칸 간격 시험은 desktop에서 돌려 PR
본문에 적는다.

Refs: 1112/01-01, 1112/01-02, 1105/08-02, 1105/08-04, 1106/08-02, 1112/04-02
2026-11-13 00:03:42 +09:00
DongHyeonka 6b79e7b39f fix(form): 폼이 mutation을 받아 저장 규칙을 맡고 FormSaveFeedback이 피드백을 그린다
결과 불명 상태를 코디네이터(useApplicationMutation)와 폼(useAppForm)이
따로 갖고, 둘을 맞추는 규칙은 생성 작성 페이지의 사본에 있다: 결과 불명·
다른 저장 중 새 저장 막기, 「변경됨으로 확인」 뒤 settleApplied, 같은 키
재전송, 다른 저장이 도는 동안의 표시. 그래서 플랫폼에서 고친 것(1105/08-02,
1105/08-04, 1106/08-02)이 이미 생성한 기능에 들어가지 않는다(1112/01-01).
같은 구조에서 셋이 더 나온다.

- 재전송이 쓰기 전에 거절되거나(429·503) 선언한 409가 나면 "입력 내용을
  확인해 주세요." 요약 아래 나온다(1112/04-02).
- 폼 밖에서 부른 같은 입력이 NOT_APPLIED로 끝나면 훅은 결과 불명인데 폼은
  다시 시도를 보인다(1106/03-01 ②).
- 필드 이름이 붙은 결과 불명(VALIDATION_REJECTED + MAYBE_APPLIED)이 필드
  오류와 결과 불명 화면을 함께 띄운다(1101/03-04).

고른 방법(R9-D1, 권하는 안으로 정함(2026-11-12, 총괄)): useAppForm에 선택
옵션 mutation을 더한다(추가만). 주면 폼이 saveBlocked로 새 저장을 막고
confirmUnknownEffect·resendUnknownEffect를 내주며, 입력 오류가 아닌 저장
안내를 notice로 둔다. 새 FormSaveFeedback이 결과 불명 → 저장 실패 → 충돌 →
다른 저장 순으로 피드백을 그리고, AsyncSurface의 새 notice 칸에 재전송 거절
안내를 보인다. 결과 불명을 코디네이터 상태로 먼저 보므로 ②도 같은 화면이
된다. 폼은 MAYBE_APPLIED를 입력 오류보다 먼저 본다. 생성 작성 페이지는 이
둘을 쓰고 자기 사본을 지운다. mutation을 주지 않은 폼은 전과 같다. 버린
대안: 판정 hook을 따로 두고 폼은 그대로(사본이 하나 더 생긴다).

위험·한계: 이미 생성한 기능은 바뀌지 않는다. CHANGELOG에 생성 페이지를
옮기는 방법을 적는다. 다시 마운트한 폼이 mutation 없이 쓰이면 ②는 그대로다.
VD-04 결정 5의 범위(선언하지 않은 409만)는 머리 블록에 적었다(1103/03-01 (3)).

검증: tests/component/form-foundation.test.tsx의 새 시험 넷(막기, 확인,
재전송 거절 표면, 결과 불명 우선)과 create-feature.test.ts의 생성 페이지
시험이 고치기 전 코드에서 실패하고 고친 뒤 통과한다. 생성 페이지는
FE-GATE-020 scaffold 드릴과 FE-GATE-008 e2e가 돈다(PR 본문).

Refs: 1112/01-01, 1112/04-02, 1106/03-01, 1101/03-04, 1103/03-01
2026-11-12 23:21:21 +09:00
DongHyeonka 353bed7ac2 fix(design-system): 공통 primitive의 키보드·보조기술 동작을 약속대로 맞춘다
공통 primitive가 디자인 시스템 설계 8.1·8.2절과 WCAG 2.2 AA 약속을
어긴다.

- Popover가 이름 없는 role="dialog"를 그린다(1112/05-10).
- Dialog 안의 Menu·Popover·Tooltip에서 Escape를 누르면 Dialog까지
  닫힌다. Dialog가 안쪽이 처리한 Escape를 보지 않는다(05-11).
- SearchField는 required 기호만, Checkbox는 상태만 있다(05-13).
- Toast를 닫기 버튼으로 닫으면 포커스가 body로 떨어진다(05-14).
- TextArea 글자 수가 <output>(암묵 status)이라 글자마다 발표되고 입력과
  이어지지 않는다(05-17).
- 라우트 h1의 :focus outline 제거가 layer 순서로 키보드 :focus-visible
  표시까지 지운다(05-02). Tooltip이 pointer-events: none과 틈 때문에
  포인터를 설명 위로 옮기면 사라진다(1.4.13, 05-06).
- 홈 readiness 목록이 role 없는 div에 aria-label을 단다(05-15).
- fe-a11y·fe-ux 스킬이 제출 실패 때 오류 요약으로 포커스가 간다고 적는다.
  코드는 첫 오류 필드로 보낸다(05-09).

고른 방법: Popover는 trigger id로 이름을 받는다. Popover·Tooltip은
Escape를 capture 단계에서 받아 preventDefault하고, Dialog는 기본 동작이
막힌 Escape(과 그 뒤 cancel)를 넘긴다. Tooltip은 보일 때(hover·focus)만
Escape를 가진다. 숨은 tooltip이 다른 Dialog의 Escape를 막지 않게 하려는
것이다. Toast 닫기는 다음 toast의 닫기 버튼, 없으면 toast로 들어오기 전
요소로 포커스를 돌린다. TextArea 글자 수는 aria-describedby로 잇고 0에
닿을 때만 따로 발표한다. h1은 :focus:not(:focus-visible)만 outline을
지운다. Tooltip은 보일 때만 포인터를 받고 ::before 다리로 틈을 메운다.
버린 대안: Dialog가 안쪽 layer 목록을 들고 Escape를 나누기(primitive끼리
묶인다).

위험·한계: native <dialog>가 막힌 keydown 뒤에도 cancel을 쏘는지는
브라우저마다 다를 수 있어, Dialog는 같은 task의 cancel 하나를 넘긴다.
Toast가 돌려줄 요소가 지워졌으면 포커스를 옮기지 않는다. 시각 골든이
바뀌는지는 desktop test:visual로 본다.

검증: 새 component 시험(tests/component/design-system-a11y.test.tsx,
starter-pages), e2e(app-shell focus ring, 세 엔진), storybook(tooltip
hover)의 RED·GREEN은 desktop에서 돌려 PR 본문에 적는다.

Refs: 1112/05-02, 1112/05-06, 1112/05-09, 1112/05-10, 1112/05-11,
 1112/05-13, 1112/05-14, 1112/05-15, 1112/05-17
2026-11-12 22:53:40 +09:00
DongHyeonka 7420bafe49 fix(form): 다시 마운트한 폼의 재전송이 보내지 않은 화면 값을 저장 값으로 쓰지 않는다
저장 결과가 불명인 채 페이지를 떠났다 돌아오면 폼은 새로 마운트되어
보낸 값을 모른다. 그때 resendUnknown은 화면 값을 제출 값으로 썼다
(unknownSubmissionRef ?? values). 재전송이 성공하면 기본 resetOnSuccess가
사용자가 돌아와 입력한, 보낸 적 없는 값을 지우거나 깨끗한 값으로
표시했다. 재전송이 쓰기 전에 거절되어 결과 불명에 남으면 그 화면 값을
보낸 값으로 기억해, 다음 「변경됨으로 확인」이 같은 일을 했다. 같은
상황의 settleApplied는 이미 화면 값과 dirty를 그대로 둔다(1106/08-01).
그 settleApplied 분기를 지키던 시험은 참조 기능 시험과 함께 지워졌다.

고른 방법: 결과 불명 기록을 { values: Values | null }로 바꿔 "보낸 값
모름"을 따로 둔다. 재전송은 그 값만 쓰고, 값을 모르면 성공·적용 확인을
settleApplied의 재마운트 분기와 같은 처리(settleUnsentValues)로 끝낸다.
기록이 남아 있는 동안 새 저장은 그대로 막는다. 버린 대안: 화면 값을
쓰되 성공 뒤 값을 되돌리기(사용자가 친 값을 잃는다).

위험·한계: 다시 마운트한 폼에서 결과 불명이 확인되기 전까지는 폼도 새
저장을 막는다(전에도 재전송이 불명으로 남으면 막았다). 결과 불명 상태를
코디네이터와 폼이 따로 갖는 구조(1112/01-01)는 결정 대기다.

검증: tests/component/form-foundation.test.tsx의 새 describe 셋 중 둘이
고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문).

Refs: 1106/03-01, 1112/01-02, 1112/10-01
2026-11-12 22:53:23 +09:00
DongHyeonka f117a5af41 docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
2026-11-08 22:57:03 +09:00
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00
DongHyeonka c7e80f2f8a test(visual): 갤러리를 Storybook story로 옮기고 골든 대상을 바꾼다
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).

두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.

위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.

검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
2026-11-08 13:51:54 +09:00
DongHyeonka b41990cdd5 fix(query): 재전송 거절의 결과 불명 해제를 짝 백엔드 표 code로만 정한다
문제: 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)
2026-11-06 08:25:28 +09:00
DongHyeonka 145be2df13 fix(forms): 다시 마운트한 폼의 확인은 보내지 않은 입력을 저장됨으로 두지 않는다
문제: 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)
2026-11-06 08:01:53 +09:00
DongHyeonka 80e7f1d63a fix(query): 같은 요청이 매번 받는 거절로 끝난 재전송은 결과 불명을 푼다
문제: 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)
2026-11-06 08:00:56 +09:00
DongHyeonka 81ff05efc1 chore(review): 1106 화면·테마 조치 브랜치를 합친다 2026-11-06 07:24:11 +09:00
DongHyeonka 7625dc4548 fix(theme): 열린 modal의 가림막이 스크롤바 자리까지 덮게 한다
문제: :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
2026-11-06 07:24:02 +09:00
DongHyeonka fbaaaee43d fix(forms): 다시 마운트한 폼이 자기가 시작하지 않은 저장의 끝을 보인다
문제: 저장 중에 참조 작성 폼을 떠났다가 돌아오면(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
2026-11-06 05:33:23 +09:00
DongHyeonka 815ea58e80 fix(query): IDEMPOTENT 쓰기는 결과 불명 뒤에도 다시 보낼 수 있게 한다
문제: 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
2026-11-06 05:31:30 +09:00
DongHyeonka 25685871f1 fix(query): 쓰기 전에 거절된 같은 키 재전송 뒤에도 결과 불명과 키를 지킨다
문제: 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
2026-11-06 05:28:30 +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 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 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 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 83f4dd5f8e chore(review): 1103 예제 화면·시각·접근성 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-04 15-01 12-01 11-01 16-03 11-02

# Conflicts:
#	docs/architecture/frontend-application-foundation.md
#	docs/architecture/starter-experience.md
#	docs/manual/03-outside-feature-folder.md
#	tests/unit/runtime-adapters.test.ts
2026-11-04 23:04:17 +09:00
DongHyeonka b96d61d8f7 feat(examples)!: 예제 화면 3개를 끌 수 있는 기능으로 옮긴다
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.

고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
  자기 context platform-examples-context(루트 examples/*)에 산다.
  reference-context의 examples/reference-resources/*와 플랫폼 라우트
  /examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
  기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
  쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
  routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
  같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
  lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
  PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
  청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
  routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
  (페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
  지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
  "{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
  구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
  화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
  하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
  (product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
  옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
  기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
  "플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
  찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
  잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
  예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
  제품이 지우게 둠(동기화 충돌 자리가 남음).

위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
  state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
  PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
  home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
  예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
  (starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
  않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
  때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
  임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
  재지 않는다.

검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
  홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
  뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
  16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
  registries, test:all, coverage, test-evidence, ci, home-smoke, build,
  route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
  측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
  측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
  architecture 383 통과. check:types, lint, check:architecture,
  check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
  old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
  d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
2026-11-04 22:59:03 +09:00
DongHyeonka d549ceb330 perf(examples): 플랫폼 구성 화면이 제목을 먼저 그리고 실행부 표만 기다린다
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).

고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
  제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
  snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
  표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
  청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
  실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
  이유), hover 프리페치(키보드·직접 진입에 효과 작음).

위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
  직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
  페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
  약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.

검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
  보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
  eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
  test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
  부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
  LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
  홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
  잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
  feature-runtime·reference-schemas는 제목 뒤에 받는다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
2026-11-04 22:59:03 +09:00
DongHyeonka 6088f6e533 chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 22:28:57 +09:00
DongHyeonka c17b3a05d6 chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 21:40:51 +09:00
DongHyeonka 2017ef76ff fix(query): 키 없는 결과 불명 요청에는 재전송을 주지 않는다
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.

고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
  idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
  거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
  훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
  onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
  페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.

버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
  배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.

위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
  "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
  결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.

검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
  execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
2026-11-04 20:43:06 +09:00
DongHyeonka 2d5d41f85d fix(forms): 필드 오류가 아닌 저장 실패 뒤 키보드 포커스를 실패 상태로 옮긴다 (1103/08-02)
문제
참조 폼 페이지는 저장 중과 결과 불명 동안 저장 버튼에 disabled를 준다.
포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 body로 내려놓는다. 폼은 필드
오류일 때만 포커스를 옮겼으므로, 키보드로 저장했다가 결과 불명(500)이나 429를
받으면 세 엔진 모두 포커스가 body로 떨어졌다. 복구 버튼은 폼 위 feedback
자리에 있어 셸 머리말부터 다시 지나야 닿았다.

고른 방법
- useAppForm이 feedbackId를 내고, 필드 오류·성공이 아닌 결과(결과 불명,
  재인증, 권한 없음, 다시 시도, 사용 불가, 충돌)로 끝나면 렌더 뒤 그 요소에
  포커스를 준다. FormPage(StandardPage)는 feedbackId를 받으면 feedback 자리를
  id + tabIndex=-1인 포커스 대상으로 만든다. 페이지마다 포커스 코드를 복사하지
  않게 하려고 hook과 템플릿에 두었다.
- 참조 폼의 저장 버튼은 저장 중에 disabled 대신 Button의 pending(aria-busy)을
  쓴다. 중복 제출은 지금처럼 폼(submitForm)과 onSubmit 가드가 막는다. 결과
  불명 동안에는 여전히 꺼진다(08-01 범위). 그때는 위의 포커스 이동이 받는다.
- 첫 행동 버튼 대신 feedback 자리 전체를 포커스한 이유: 실패 종류마다 버튼
  구성이 다르고, Tab 한 번에 첫 복구 버튼에 닿는다.
매뉴얼 02 6절 FormPage에 feedbackId와 pending을 적었다.

위험·한계
- 스크린 리더가 포커스된 feedback 자리를 어떻게 읽는지는 확인하지 않았다.
- 파생 폼 페이지는 feedbackId를 넘겨야 이 동작을 얻는다.
- "deduplicates create" 테스트의 저장 중 단언을 disabled에서 aria-busy와
  포커스 유지로 바꿨다. 한 번만 호출되는 단언은 그대로다.

검증
- RED: reference-page.test.tsx 새 2행(결과 불명, 429)이 수정 전 실패. e2e
  reference-save.spec.ts 새 2건이 수정 전 소스에서 chromium·firefox·webkit
  6건 모두 실패(feedback 자리 focused 아님).
- 수정 후 reference-save·reference-form e2e 3엔진 45건 통과(heavy lock,
  CHOKIDAR_USEPOLLING=1). tests/component·tests/features 60 files / 368
  tests 통과. check:types, eslint, check:design-system, check:i18n,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-02
2026-11-04 20:42:32 +09:00
DongHyeonka d7c6cb4fd2 fix(auth): 세션 복구가 no-session이면 로그인 버튼을 보인다
문제: useSessionAction이 recover()의 결과를 버린다. owner가
"no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와
셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가
지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면
코드를 읽고 추론해야 했다.

고른 방법: 두 가지를 함께 한다.
- SessionState·SessionGateway.recover·ExternalSessionOwner에 전이
  계약을 적는다. restored면 authenticated, no-session이면
  unauthenticated(또는 integration-failed), reject면 상태 유지.
- SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데
  owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에
  unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을
  보인다.
버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만
보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독
알림을 새로 만들어야 해서 scope fence와 얽힌다.

위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다.
application·scope fence는 owner의 상태를 그대로 본다.

검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패
확인), router·app-shell·route-status-surfaces·auth-session-adapter
테스트 통과, check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11
2026-11-04 20:23:22 +09:00
DongHyeonka 4282a541d0 fix(forms): 필드 code 문구를 표의 자기 키로만 찾는다 (1103/08-03)
문제
validationMessage가 VALIDATION_COPY[code]로 찾았다. Object.freeze({...})는
Object.prototype을 물려받으므로 constructor·toString·hasOwnProperty·
__proto__는 undefined가 아니라 함수·객체가 되고 ?? 대체가 걸리지 않았다.
그 값이 문구 키로 넘어가 "요청한 문구를 표시할 수 없습니다."가 나왔다.

고른 방법
같은 영역의 다른 표(route-codecs.ts, backend-envelope.ts)처럼
Object.hasOwn으로 자기 키만 본다. 표를 Object.create(null)로 바꾸는 대안은
타입 선언과 다른 표의 관용이 갈려 버렸다.

위험·한계
짝 백엔드는 대문자 code만 보내므로 짝 구성의 화면 결과는 바뀌지 않는다.

검증
- RED: 내장 이름 4개 행이 수정 전 실패, SOME_FUTURE_CODE 행은 통과.
- form-foundation.test.tsx 28건 통과. eslint, tsc(app) 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-03
2026-11-04 20:16:19 +09:00
DongHyeonka 7c8cb19e94 fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
  레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
  `NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
  화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
  라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
  `route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
  `invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
  붙어서 지금은 닿지 않는 값이다.

이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.

고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.

버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
  가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
  kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
  `route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
  id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
  바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.

위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
  결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
  복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
  `route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
  않았다.

검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
  `"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
  `"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
  (`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
  files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
  check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
2026-11-03 20:30:35 +09:00
DongHyeonka 8a09c90379 fix(forms): 짝 백엔드 필드 검증 code마다 문구를 보인다 (1101/14.4)
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.

고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
  키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
  invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
  invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
  positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
  future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
  넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.

버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
  문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
  (check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
  목록은 테스트에 SHA와 함께 적었다.

위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
  방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
  제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
  배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
  청크에 있다.

검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
  백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
  "Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
  tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
  237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
  compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
  check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
  쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
2026-11-03 20:18:12 +09:00
DongHyeonka 47fec5c27c fix(query): 처리 중 409의 Retry-After 전 재전송은 그 시각까지 기다린다 (백엔드 1101/02-01)
문제
짝 백엔드는 같은 키의 첫 요청이 아직 실행 중이면 409
IDEMPOTENT_IN_FLIGHT, retryable=true, Retry-After: 2를 준다(백엔드
docs/web/http-contract.md §2). 클라이언트 행동은 "같은 키로 Retry-After 뒤
재전송"이다.
- 같은 키: 0929/03-01이 이 409를 MAYBE_APPLIED로 두어 코디네이터가 intent를
  붙든다. 재전송은 같은 키를 쓴다(기존 vertical 테스트가 [K, K, K]를
  고정). 이 부분은 이미 맞다.
- Retry-After: 지키지 않는다. V3는 응답 metadata에 retryAfterMs를 읽지만
  feature binding이 PROBLEM을 AppFailure로 옮길 때 버린다. V2는 409의
  Retry-After를 읽지 않는다. 그래서 결과 불명 화면의 "같은 요청으로 다시
  보내기"(또는 같은 입력 다시 저장)를 바로 누르면 즉시 나가서 같은 409를
  한 번 더 받는다.

고른 방법
재전송이 그 시각 전이면 기다렸다 보낸다.
- feature binding이 PROBLEM의 metadata.retryAfterMs를 AppFailure에 싣는다.
  V2는 409의 Retry-After도 읽는다(409는 여전히 자동 재시도하지 않는다).
- mutation 코디네이터(application-query.ts)가 MAYBE_APPLIED로 남기는
  admission에 resendNotBefore = 지금 + min(retryAfterMs, 5초)를 적는다.
  같은 intent를 다시 쓰는 submit(재전송 버튼, 같은 입력 저장)이 그 시각까지
  기다린 뒤 보낸다. 기다리는 동안 admission이 ACTIVE라 화면은 pending이다.
  scope가 바뀌면 기존 mutationFn 검사가 NOT_STARTED로 막는다.
- 상한 5초는 V3 실행기의 Retry-After 상한(RETRY_AFTER_CEILING_MS)과 같다.
  더 일찍 보내도 같은 키라 서버가 다시 409를 줄 뿐 두 번 적용하지 않으므로,
  긴 Retry-After를 다 기다리게 하지 않는다.

버린 대안
- Retry-After 전에는 버튼을 막기: 화면과 시각 회귀 골든이 바뀌고, 다시
  열어 줄 타이머와 문구가 더 든다. 기다렸다 보내는 쪽이 변경이 작다.
- V3 실행기가 키별 "이 시각 전 금지" 표를 들기: 실행기에 키를 기억하는
  상태와 정리 규칙이 생긴다. 재전송을 만드는 곳은 코디네이터 하나다.
- 그대로 두기(이른 재전송은 409를 한 번 더 받을 뿐): 서버 문서가 허용하는
  동작이지만 사용자는 같은 결과 불명 화면을 한 번 더 본다. 요구는
  Retry-After를 지키는 것이다.

위험·한계
- AppFailure.retryAfterMs가 V3 PROBLEM에도 실린다(추가 필드). 이 값을 읽는
  곳은 코디네이터뿐이다.
- 기다림은 MAYBE_APPLIED로 남은 admission을 다시 보낼 때만 생긴다. 다른
  상태(NOT_APPLIED 등)는 그대로다.
- 시계는 performance.now(), 대기는 setTimeout이다. 탭이 백그라운드면
  브라우저가 타이머를 늦출 수 있다(더 늦게 보낼 뿐이다).

검증
- RED: 4행 실패.
  - tests/features/reference-feature/reference-production-vertical.test.tsx
    처리 중 409(Retry-After: 1) 뒤 재전송 간격 39.7ms(기대 990ms 이상)
  - tests/component/application-mutation-admission.test.tsx 재전송이
    retryAfterMs 300을 기다리지 않음
  - tests/features/reference-feature/reference-http-problem-mapping.test.ts
    retryAfterMs 없음
  - tests/integration/http-client.test.ts V2 409 retryAfterMs 없음
  상한 행은 수정 전에도 통과하고, 상한을 뺀 변이에서 시간 초과로 실패하는
  것을 확인했다.
- GREEN: 위 행 모두 통과. tests/component·features·contract/reusable-
  capability, tests/integration/http-client·http-diagnostics, tests/unit/
  http-execution-v3 62 files 491 tests 통과. tsc app·test 통과, 바꾼 파일
  eslint 통과.

Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
2026-11-03 02:00:45 +09:00
DongHyeonka 8b7c6ebf6c perf(contracts): 검증 생략 목록을 부팅 경로 밖에서 만든다 (1101/07-03)
문제
- 93180f6(합친 커밋 d3ddc89)이 초기 JS를 늘렸다. 기능 모양 측정
  (scripts/scale/measure-feature-shape-growth.ts) 기준으로 기능 0개가
  202,376 → 202,526 B(+150)로, 기능 1개 추가분이 960 → 1,029 B로 늘었다.
  tests/unit/feature-shape-growth.test.ts의 1 KiB 상한을 넘는다.
- 원인은 두 가지다.
  - 부팅 때 도는 composeContractContributions가 검증기마다 생략 표시를
    읽고 목록을 만들었다(feature-platform 청크 +164 B). 이 목록을 쓰는
    곳은 플랫폼 개요 화면(lazy 라우트)뿐이다.
  - 공유 zod-validator.ts가 기능이 두 개가 되면 lazy 청크 하나로 따로
    나왔다. 모든 context-routes·feature-runtime import의 preload 목록에
    파일 이름이 하나 늘어 boot·feature-declarations 청크가 각각 약 25 B
    커졌다.

고른 방법
- 목록 계산을 src/contracts/unvalidated-payload.ts의
  listUnvalidatedPayloads(composed)로 옮긴다. 플랫폼 개요 화면만 이것을
  import한다. 결정의 뜻(생략한 operation이 조립 결과에서 목록으로
  나온다)은 그대로다. 계산 시점만 화면이 열릴 때로 미룬다.
  ComposedContractContributions.unvalidatedPayloads 필드는 뺀다.
- unvalidatedPayload 팩토리도 같은 모듈로 옮긴다.
- 조립기의 표시 검사도 뺀다. 이유가 빈 생략은 unvalidatedPayload가 만들
  때 거부한다(TypeError). 손으로 붙인 표시는 값이 "NONE"이 아니거나 이유가
  없어도 목록에 나온다(화면에는 "이유 없음"). 그래서 생략이 숨지 않는다.
  external-contract-runtime.ts에는 RuntimeValidator의 선택 타입 필드
  2개만 남는다.
- vite.config.ts에서 zod-validator.ts를 schema-registry.ts와 같은 lazy
  청크로 묶는다. 어댑터를 import하는 곳은 이미 schema-registry 청크를
  preload한다. includeDependenciesRecursively: false라서 다른 모듈은
  끌려오지 않고, 두 모듈 모두 부팅 그래프 밖이다.

버린 대안
- 조립기에 "NONE + 이유" 검사만 남기기: feature-platform 청크 +57 B gzip.
  검사를 팩토리와 목록으로 옮기면 0 B다. 손으로 붙인 잘못된 표시를
  부팅 때 거부하지 못하지만, 목록에는 나온다.
- zodValidator를 schema-registry.ts 안에 정의: 빌드 설정 없이 같은 결과가
  나오지만 결정한 위치(src/contracts/zod-validator.ts)와 다르고, 다음 단계의
  기능 생성 명령이 그 경로를 쓴다.
- 어댑터를 zod.ts에 두기: zod 입구는 초기 청크라 기능 0개 초기 JS가 는다.

위험·한계
- 조립 결과 타입에서 unvalidatedPayloads 필드가 빠진다. 93180f6 뒤 이
  필드를 쓴 코드는 listUnvalidatedPayloads로 바꿔야 한다. repo 안에서는
  화면과 테스트만 썼다.
- 손으로 만든 잘못된 표시(예: validation: "PARTIAL")는 더 이상 조립에서
  거부되지 않는다. 목록에만 나온다. 테스트 2건을 이 동작으로 바꿨다.
- 청크 묶음은 빌드 설정에 두 파일 경로를 적는다. 파일 이름을 바꾸면
  정규식도 함께 바꿔야 한다. 놓치면 바이트만 늘고 동작은 같다.
- 플랫폼 개요 화면을 열면 schema-registry 청크에 어댑터(351 B raw)가 같이
  온다.

검증
- 기능 모양 측정(0개 / 1개 추가분, gzip B):
  - ee81c44(07-03 전): 202,376 / 960
  - d3ddc89(07-03 합친 뒤): 202,526 / 1,029
  - 목록만 부팅 밖으로: 202,407 / 1,035
  - 청크 묶음 추가: 202,424 / 983
  - 조립기 검사 제거(이 커밋): 202,371 / 958
- feature-shape-growth.test.ts 6건 통과.
- 07-03 테스트 3파일 33건 통과(zod-validator, external-contract-runtime,
  starter-platform-overview-page).
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  270파일 3,203건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
- tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. 아키텍처 그래프 검사(pnpm 대신 exec stub) 413 모듈 PASS.
  check-registries PASS(compatibility=none).
- 본 빌드 초기 JS gzip 202,371 B(26파일). raw 644,782 B로 ee81c44 측정과
  같다.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03
2026-11-03 01:58:38 +09:00
DongHyeonka ca161878f2 feat(routes): 기능이 홈을 대신하고 context가 자기 레이아웃을 선언한다 (1101/09-03)
문제: 라우터는 모든 context gateway를 `AppShell` 하나 아래에 붙이고 플랫폼
`/`를 index로 둔다. 기능이 `APP_HOME`을 선언하면 `composeUniqueRecord`가
throw한다. 그래서 제품 홈이 기능 화면이거나 화면이 `AppShell`이 아닌 자기
셸을 쓰면 제품이 템플릿 라우터와 조립 카탈로그를 고쳐야 한다. memento는
카탈로그 브리지(`APP_HOME` 허용 목록)와 라우터 브리지(`ownsShell`)를 넣고
동기화마다 병합한다. tech-log는 라우터를 PUBLIC/STUDIO 그룹 라우터로 통째로
바꿔 생성기 설치 경로(context gateway)를 쓰지 못한다.

고른 방법: 리뷰 4.3의 (B). 선언 두 개를 연다.
- 홈 대체: 플랫폼이 기능이 대신할 수 있는 라우트 id를 선언한다
  (`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS = ["APP_HOME"]`,
  src/contracts/routes.ts). 그 id를 선언한 기능의 정의가 플랫폼 정의를
  대신한다. 둘이 선언하면 카탈로그를 읽을 때 두 기능 id를 담아 throw한다
  (`withoutTakenOverPlatformRoutes`). 다른 플랫폼 id는 지금처럼 중복 오류다.
  라우터는 대체된 라우트를 소유 context와 함께 그 경로에 붙인다.
- context 레이아웃: `BoundedContextRouteModule.loadLayout`(선택). 생성기는
  `src/contexts/<context>/context-layout.tsx`가 있으면 그 `CONTEXT_LAYOUT`을
  지연 import로 싣는다. 라우터는 그 context를 `AppShell` 형제인 `/` 레이아웃
  라우트 아래, 기능의 등록 경로마다 붙인다. 그래서 모르는 URL은 여전히
  `AppShell`의 NOT_FOUND로 간다. 선언이 없으면 지금처럼 `AppShell` 아래 루트에
  붙는다. 레이아웃 청크 실패는 라우트 청크와 같은 reload-once 복구를 받는다.
- 09-06 불변식을 레이아웃으로 넓힌다. 레이아웃 라우트는 모두 `/`의
  형제라서 루트는 레이아웃과 상관없이 그 아래 URL을 가진다. 그래서 기존
  루트 검사가 모든 레이아웃에 걸친다. 한 레이아웃 아래 루트 여럿(같은
  컴포넌트를 싣는 context들)은 허용한다. 대체된 플랫폼 라우트는 라우터가
  경로에 직접 붙이므로 루트 검사에서 뺀다(09-06 재검토 조건).
- tests/unit/product-features.test.ts의 "플랫폼 라우트는 소유자가 없다"
  검사가 대체 가능한 id는 건너뛴다. memento가 고쳤던 템플릿 테스트다.
- `ContextRouteModule`에 `featureIds`가 생겨서, `TEMPLATE_APP_MODULE`을
  손으로 mock하며 필수 필드 `features`를 빼먹은 두 테스트
  (context-route-gateway, context-boundary-diagnostics)에 `features: []`를
  넣었다.

버린 대안:
- (A) 현 상태: 제품마다 브리지를 넣고 동기화마다 병합한다.
- (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 tech-log를 담지 못한다.
- 같은 레이아웃을 쓰는 context를 로더 함수로 묶어 레이아웃 라우트 하나에
  모으기: 만들었다가 지웠다. React 19는 같은 컴포넌트로 풀린 lazy 타입을 같은
  타입으로 맞춰 레이아웃 인스턴스를 그대로 둔다. 묶지 않은 변이로 테스트가
  그대로 통과해서 쓸모없는 코드였다.
- `CONTEXT_LAYOUT_ID` 리터럴로 다른 context의 레이아웃을 가리키기: 같은
  컴포넌트를 내보내는 파일 두 개로 같은 결과가 나와 선언을 하나 덜 둔다.
- 레이아웃 라우트를 `AppShell`보다 앞에 두기(memento 브리지 순서): 경로가
  같으면 기능이 플랫폼 라우트를 조용히 가린다. `AppShell`을 앞에 두어
  지금처럼 플랫폼이 이긴다.

위험·한계:
- 레이아웃이 skip link와 `<main id="main-content">` 하나를 그리는 것은
  계약(타입 주석, starter-experience.md)과 테스트 fixture로만 지킨다. 실행 중
  검사는 없다. 레이아웃 로딩·실패 화면에는 `<main>`이 없다(`AppShell`의
  errorElement와 같다).
- 레이아웃 렌더 결함(청크 실패가 아닌 것)은 라우트 errorElement로 가고
  진단을 남기지 않는다. `AppShell` 렌더 결함과 같다.
- 홈을 대신한 기능을 실행 중에 끄면 `/`는 비활성 기능 화면이 된다. 빌드에서
  빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
- tech-log의 PUBLIC 셸 안 NOT_FOUND는 표현하지 않는다. 모르는 URL은
  `AppShell`의 NOT_FOUND다. STUDIO의 `/studio/*` 라우트는 STUDIO 레이아웃
  아래에서 동작한다. tech-log는 기능 하나를 레이아웃 그룹별 기능 둘(context
  둘)로 나눠야 한다.
- 플랫폼 라우트와 기능 라우트의 같은 경로는 여전히 검사하지 않는다(7139c7c
  한계). 루트 `*` context에서 `APP_HOME`이 아닌 id로 `/`를 선언하면 플랫폼
  홈에 가려진다.
- 초기 JS gzip +349 B(204,586 -> 204,935 B). 예산 204,800 B를 135 B
  넘는다(이전 여유 214 B). boot 청크 +228(라우터·앱 모듈),
  installed-feature-contracts 청크 +121. 같은 worktree에서 HEAD 파일로
  `vite build`를 한 번 더 해서 청크별로 비교했다. 예산은 고치지 않았다.

검증:
- RED: tests/component/context-layouts.test.tsx는 파일 적재에서
  "Duplicate route registry key: APP_HOME"으로 실패.
  tests/architecture/context-route-roots.test.ts 15건 중 3건 실패(APP_HOME
  루트 예외 "not under the route root", 대체 함수가 없어 2건).
  tests/scripts/generate-product-feature-index.test.ts 새 1건이 HEAD 생성기로
  "expected ... to contain 'loadLayout: async () => (await import…'"로 실패.
- GREEN: 세 파일 37건 통과(생성기 15, 루트 16, context-layouts 6).
- 변이: 라우터가 `loadLayout`을 무시하면 context-layouts 6건 중 5건 실패.
  topics 레이아웃을 다른 컴포넌트로 바꾸면 "keeps one layout instance" 실패.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
  300 files, 3,451건 통과. check-registries, check-adapter-inventory,
  verify-documentation-readiness(PASS_SCOPED) 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과. 생성기 --check 통과.
- check:architecture는 pnpm이 필요해 돌리지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-03, 4.3
2026-11-03 01:52:18 +09:00
DongHyeonka d3ddc8957f feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제
- zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의
  reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은
  복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을
  structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다.
- RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도
  검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이
  타입·이름·조립 결과 어디에도 남지 않는다.

고른 방법 (C: 공유 어댑터 + 생략 표시)
- zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과
  tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은
  참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code
  문자열). tests/helpers도 이제 성공 값을 복사한다.
- unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에
  둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다.
  zod가 필요 없어서 검증기 프로토콜 옆에 뒀다.
- composeContractContributions가 이 표시가 붙은 검증기를
  unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로
  내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두
  본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다.
- 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약"
  표를 둔다. 목록이 비면 그리지 않는다.

버린 대안
- (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다.
- (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의
  자체 검증기까지 막아 §4 설계와 충돌한다.

위험·한계
- 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을
  통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을
  만들어 그 길로 생략한 것만 드러낸다.
- 공개 계약 추가: RuntimeValidator에 선택 필드 2개,
  ComposedContractContributions에 필드 1개, 새 export zodValidator·
  unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다.
  ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야
  한다(repo 안에는 없다).
- 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다.
  플랫폼 개요 청크 4,625 → 4,750 B.
- 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는
  돌리지 않았다.
- tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는
  그대로 둔다(16-01이 그 파일을 넓힌다).

검증
- RED(수정 전): zod-validator.test.ts "Cannot find module
  '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와
  starter-platform-overview-page.test.tsx "unvalidatedPayload is not a
  function". 3파일 모두 실패.
- GREEN: 같은 3파일 33건 통과.
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
  tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. check-registries PASS(compatibility=none), verify-documentation
  PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신
  exec stub) 383 모듈 PASS.
- 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능
  폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용.
  src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립·
  플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3
2026-11-03 01:34:32 +09:00
DongHyeonka b4ccadab77 feat(design-system): 제품이 싣는 글꼴을 토큰 계약에 선언하게 한다 (1101/12-04)
문제
첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반
키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴
패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수
없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니
제품은 템플릿 소유 스크립트를 고치게 된다.

고른 방법
- token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를
  둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다.
- firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로
  실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다.
- 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다.
- docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다.
- 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을
  적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이
  커밋은 (4)만 한다.
버린 대안
- 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러
  설정까지 봐야 해서 규칙이 커진다.
- 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다.

위험·한계
- 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과
  문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다.
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은
  tests/unit/design-system-rules.test.ts뿐이다.
- 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다.

검증
- RED: 새 테스트 "passes a family the product declares it loads, and only
  that one"이 실패(expected [ Array(1) ] to deeply equal []).
- GREEN: design-system-rules·oklch-contrast·design-system-contract
  22/22 통과.
- 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로
  시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새
  메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS.
- tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness
  PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
2026-11-03 01:24:31 +09:00
DongHyeonka 6dd4bc1c24 refactor(design-system): primitive를 컴포넌트마다 한 파일로 나눈다 (1101/08-08)
문제
primitive가 종류별 파일 5개(core·forms·overlays·navigation·feedback)에
모여 있다. 번들러는 export가 아니라 모듈 단위로 청크를
나눈다. 그래서 셸이 쓰는 Button·Drawer·Select와 같은 파일에 있는
Tooltip·Menu·Card 같은 갤러리 전용 primitive도 셸과 같은 청크로 간다.
다음 커밋(side effect 없음 선언)이 효과를 내려면 먼저 파일이 나뉘어야
한다.

고른 방법
- primitives/ 아래를 컴포넌트마다 파일 하나로 나눈다(32개). 본문은 원래
  줄을 그대로 옮기고 import만 새로 쓴다. ToastProvider·useToast는 한
  파일, 내부 타입 FieldCopy는 field.tsx에서 내보낸다.
- PaginationLandmarkContext는 pagination-landmark.ts로 따로 둔다.
  page-templates.tsx(StatusPage, 초기 청크)가 이것만 읽는데, Pagination과
  같은 파일이면 Pagination 코드가 초기 청크로 간다.
- design-system/index.ts의 export 이름은 그대로다(값 71개, 타입 36개를
  전후 비교). components/ui/*.ts 재수출, page-templates.tsx,
  common-patterns.tsx는 새 경로를 가리킨다. .dependency-cruiser.json의
  page-templates 예외는 출발 파일 기준이라 그대로 맞다.
버린 대안
- 셸이 쓰는 것과 나머지 두 파일로 나누기: 제품 셸이 Tooltip 하나를
  쓰면 나머지가 다시 초기 청크로 간다.

위험·한계
- 이 커밋만으로는 번들이 바뀌지 않는다. 배럴이 다시 내보내는 모듈은
  side effect가 있다고 보고 모두 초기 청크에 남는다(초기 JS 16개 청크,
  203,818 → 203,824 B). 다음 커밋이 같이 있어야 효과가 난다.
- primitives/ 안의 파일 경로를 직접 import하던 다운스트림 코드는 경로를
  바꿔야 한다. 공개 경계(index.ts)는 그대로다.

검증
- 원래 5개 파일의 import 아래 본문 줄이 새 파일에 빠짐없이 한 번씩
  있다(줄 다중집합 비교).
- tsc(app·node·test) 통과, 바꾼 파일 eslint 통과.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- 빌드(flock): 초기 JS 16개 청크 203,824 B, ui-tooltip 등 갤러리 클래스는
  여전히 초기 청크에 있다(예상대로).

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
2026-11-03 01:24:31 +09:00
DongHyeonka ff33d58e95 feat(i18n): 문구 보간 파라미터를 catalog의 {이름}에서 만든다 (0929/08-03)
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.

고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.

버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.

위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
  덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
  `tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
  않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
  Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
  (+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
  흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
  샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
  샘플 키에 기대지 않는다.

검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
  feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
  feature-module.test.ts(26,60): error TS2345: Argument of type
  '{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
  계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
  locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
2026-11-03 00:54:18 +09:00
DongHyeonka 1fa5f3e237 fix(query)!: 제품 mutation 훅이 raw 입력을 받지 않게 한다 (1101/08-03)
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.

고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
  시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
  query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
  명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
  입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
  tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
  세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
  ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
  QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
  온 이전 응답은 버려진 client에 쓰인다. 이 동작을
  server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
  client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
  시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
  밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.

위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.

검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
  "error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
  통과(옮긴 테스트 포함). tests/unit·component·features·contract·
  runtime-schema·architecture·scripts·integration(security-followup-
  archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
  avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
  (바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
  제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
  raw 호출이 있어 harness와 함께 동기화해야 한다.

BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03
2026-11-03 00:53:16 +09:00
DongHyeonka e54fbf2014 feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.

고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
  보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
  여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
  그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
  보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
  넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.

위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).

검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
  reference-page 3. 예: "Unable to find an element with the text: 지원
  참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
  corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
  59 files 336 tests 통과. e2e reference-save·reference-form·
  reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
  check-i18n, check-design-system 통과.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:32 +09:00
DongHyeonka ad73e56476 fix(presentation): 예제 화면이 자기 언어를 ko-KR로 밝힌다 (08-07)
문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제
화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다.
en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US"
아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2).

고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을
준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다.
버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다.
예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다.

위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는
문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서
영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어
본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다.
예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다.

검증:
- RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (Platform composition: lang Expected "ko-KR", Received "").
- GREEN: i18n·accessibility·ui-gallery·platform-overview e2e
  chromium·firefox·webkit 69/69 통과. tests/component 220/220,
  check-i18n PASS, tsc app 통과, eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07
2026-11-01 23:20:31 +09:00
DongHyeonka dda153b25e feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.

고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.

위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).

검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
  [ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
  통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
  eslint 통과. e2e accessibility·typography·reference-form·reference-save
  chromium 27/27.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
2026-11-01 23:20:31 +09:00
DongHyeonka 8ed5beb8fd fix(design-system): 한국어 문구가 단어 사이에서만 줄바꿈되게 한다 (08-06)
문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로
한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트
200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어
기본 원칙과 맞지 않고 모든 파생 서비스가 받는다.

고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap:
break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도
적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content
계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며
라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드
토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다.

위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은
오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의
줄바꿈은 눈으로 확인하지 않았다.

검증:
- RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (wordBreak "normal", overflowWrap "normal").
- GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과.
  accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell·
  responsive·theme·compact-smoke·platform-overview chromium/compact
  34/34 통과. check-design-system PASS. 시각 회귀는 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06
2026-11-01 23:20:31 +09:00
DongHyeonka 6fc77bb71f fix(design-system): h2·h3·h4에 제목 단계 크기와 굵기를 준다 (08-04)
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로
되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두
h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다
제목 크기를 따로 만들게 된다.

고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem)
·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰
(--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤
base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면
h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰
값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로
골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에
흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이
바로 실패하고, 결과는 아래 e2e가 지킨다.

위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은
오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게
보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다.

검증:
- RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패
  (h2 16px, h3 16px: "Expected: > 16, Received: 16").
- GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n·
  ui-gallery·app-shell·responsive·theme·design-system-interactions·
  compact-smoke + typography chromium/chromium-compact 32/32 통과(별도
  playwright 설정, vite preview, pnpm 없이 빌드).
- check-design-system PASS(48 tokens). 시각 회귀는 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:31 +09:00