Files
clean-architecture-frontend…/CHANGELOG.md
T
DongHyeonka ec7435c3f7 docs(review): 최종 게이트와 매뉴얼 재실험에서 찾은 것을 적는다
문제: 결정 반영 묶음을 다 합친 뒤의 게이트 결과, 매뉴얼만으로 기능을
추가한 재실험 결과, 그 과정에서 찾은 결함이 리뷰 README와 CHANGELOG에
없었다.

방법:
- 리뷰 README 14.3에 세 가지를 더했다.
  - create:feature와 참조 기능(V3 실행기)이 짝 백엔드 Envelope 응답을
    읽지 못한다(High, P1, 결정 필요라 남김).
  - 매뉴얼 재실험 결과: 막힘 5건, 예고된 실패 1건. 막힘은 매뉴얼에 메웠다.
  - webkit old-tab-chunk-recovery 간헐 실패.
- 14.5에 7c7ef32 최종 게이트 표를 둔다.
- CHANGELOG 알려진 제한에 Envelope 제한과 webkit 간헐 실패를 더했다.
버린 대안: Envelope 제한을 이번에 고치기. V3 실행기에 Envelope 읽기를
넣을지, 백엔드가 problem+json을 보낼지는 두 repo에 걸친 결정이다.
게다가 백엔드 repo는 사람만 커밋한다.

위험: Envelope 제한이 풀리기 전에는 생성한 기능을 짝 백엔드에 바로 붙일
수 없다. 매뉴얼 01-3단계가 이를 적는다.

검증: tests/unit/changelog-review-ids.test.ts 통과. webkit 반복 실행
10/10 통과(load 16).
2026-11-03 08:02:03 +09:00

51 KiB

변경 이력

이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. 가져오는 방법은 README.md의 "Updating a copied project" 절에 있다.

  • 버전은 git 태그 vX.Y.Z로 식별한다. 태그 사이의 변경을 여기 적는다.
  • [보안] 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다.
  • [계약] 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트).
  • 표시가 없으면 템플릿 안에서 끝나는 수정이다.
  • 괄호 안 ID는 리뷰 발견 ID다. MMDD/NN-MM으로 적는다. MMDD는 리뷰 폴더 docs/reviews/YYYY-MM-DD-maturity-review/의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 docs/reviews/를 지웠다면 이 폴더와 PRODUCT.md는 원본 템플릿 repo에서 찾는다. 라운드마다 NN-MM을 새로 매기므로 같은 14-02라도 라운드가 다르면 다른 결함이다. F-N은 그 라운드 FOLLOW-UP.md의 ID다. tests/unit/changelog-review-ids.test.ts가 라운드 없는 ID를 막는다.
  • 0.2.0의 커밋 해시는 브랜치 fix/maturity-review-2026-09-25에서 만들었고, main에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 기준 브랜치를 적는다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(git log --grep '03-03').

미출시 — 브랜치 fix/ui-design-audit-2026-11-01

2026-11-01 UI 디자인 감사(docs/reviews/2026-11-01-ui-design-audit.md, ID UI-NN)와 2026-11-01 성숙도 리뷰(docs/reviews/2026-11-01-maturity-review/) 수정 묶음이다. 기준은 main 752a61f이다. 버전 번호와 태그는 아직 정하지 않았다. 커밋 해시는 이 브랜치 기준이다.

먼저 할 일 — 기능 모양 변경 (BREAKING, 1101/15-01)

298201f. 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서, 참조 모양 기능 하나만 더해도 초기 JS 예산(204,800 B)을 넘었다. 그래서 기능을 두 부분으로 나눴다.

  • 선언(feature-module.ts, FeatureModule): 초기 청크에 남는다. id, contracts(route 표, route runtime 계약, invalidation, topic version, 새 contractPackages), routes, messages, loadRuntime만 가진다.
  • 실행부(feature-runtime.ts, defineFeatureRuntime): 그 기능의 route에 처음 들어갈 때 router가 application.features.load(featureId)로 적재한다. V2 API 계약(apiOperations, schemas, runtimeSchemas, mappers), adapter contribution, contract contribution을 가진다.
  • route codec은 context-routes.ts의 route handle(handle.codecs)에 실려 route와 함께 적재된다. *-runtime-descriptor.ts와 src/features/installed-feature-runtimes.tsx는 없어졌다.

기존 기능을 옮기는 순서(src/features/reference-feature/가 완성된 모양이다):

  1. 기능 계약에서 V2 API 필드 네 개(apiOperations, schemas, runtimeSchemas, mappers)를 별도 파일로 뺀다. 참조: contracts/reference-api-contract.ts의 REFERENCE_API_CONTRACT.
  2. 선언 계약에 contractPackages를 더한다. 그 기능의 EXTERNAL_PACKAGE contribution이 고정하는 계약 패키지 identity 목록이다. 없으면 Object.freeze([]). 부팅 때 release manifest를 이 목록과 맞춰 본다. 선언하지 않은 패키지를 적재하면 거절한다(src/features/installed-contract-contributions.ts).
  3. src/features/<feature>/feature-runtime.ts를 만든다. defineFeatureRuntime({ featureId, apiContract, adapters: [...], contractContributions: [...] }). 참조: src/features/reference-feature/feature-runtime.ts. featureId가 모듈 id와 다르면 적재 때 실패한다.
  4. feature-module.ts에서 adapters, contractContributions, runtimes(route codec·route runtime)를 지우고 loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME을 넣는다. feature-runtime.ts를 어디서도 정적으로 import하지 않는다. 그러면 실행부 전체가 다시 초기 청크에 들어간다.
  5. route codec을 runtime descriptor에서 context-routes.ts의 각 route handle.codecs로 옮긴다. 참조: REFERENCE_FEATURE_ROUTE_CODECS(presentation/reference-feature-runtime.ts). 플랫폼 codec과 같은 id는 쓸 수 없다.
  6. 기능 input(application.features.get(id))은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저 await application.features.load(id)를 부른다. ApplicationApi.features를 직접 구현하거나 fake로 만든 코드는 load를 더한다(공개 포트에 추가만 했다). 런타임 설정으로 꺼진 기능은 적재하지 않는다.
  7. 모든 기능의 실행부가 필요한 화면은 loadInstalledFeatureRuntimeRegistries()(async, src/features/installed-feature-runtime-registries.ts)를 부른다. Node 스크립트와 테스트는 src/features/loaded-feature-runtimes.ts를 읽는다. src/에서 이 파일을 import하면 새 아키텍처 규칙 boot-does-not-load-every-feature-runtime이 막는다.
  8. vite.config.ts의 청크 그룹 두 개(feature-declarations, feature-platform)를 가져간다. 없으면 기능마다 선언 청크가 하나씩 는다(기능당 약 +1.5 KB).
  9. check:architecture, check:types, test:sample-removal -- --feature=<feature id>, tests/unit/feature-shape-growth.test.ts(기능 하나 1 KiB 이하)를 돌린다.

수치(298201f 측정): 템플릿 초기 JS 203,572 → 202,361 B. 참조 모양 기능 하나 +3,922 → +741 B. 예산 안에 참조 모양 기능이 약 3개 더 들어간다. 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 기능 계약끼리의 중복 검사는 부팅이 아니라 그 기능의 적재 시점과 Node 검사로 옮겨 갔다.

보안·계약 변경

표시 변경 영향 경로 커밋
[계약] 기능 모양 변경. 위 "먼저 할 일" 절을 본다. ApplicationApi.features에 load(featureId)가 생겼다 (1101/15-01) src/features/, src/application/ports/in/application-api.ts, src/presentation/routes/, vite.config.ts, .dependency-cruiser.json 298201f
[계약] 번들 예산 게이트 FE-GATE-012가 release 단계에서 merge 단계로 옮겼다. 초기 JS를 예산보다 키우는 PR이 merge 게이트에서 실패한다 (1101/15-01) config/ci/gates.json, .gitea/workflows/quality-gates.yml, scripts/lib/promotion-readiness.ts f41e3d5
[계약] 참조 기능의 생성 분류기가 409를 problem code로 나눈다. 선언한 충돌 code(CONFLICT)만 적용 안 됨이고, IDEMPOTENT_IN_FLIGHT·code 없는 409·모르는 409는 결과 불명이라 다음 전송이 같은 멱등 키를 쓴다. 백엔드는 같은 키의 처리 중 재전송에 409 IDEMPOTENT_IN_FLIGHT를 주고, 진짜 충돌 409 code를 계약에 적어야 한다 (0929/03-01) src/features/reference-feature/contracts/reference-feature-contract-contribution.ts 112c870
[계약] 인증 프로필이 ANONYMOUS(auth: "none")인 요청을 세션 상태와 상관없이 자격증명 없이 보낸다. 전에는 어느 세션 상태에서도 fetch가 0회였다. 제품 쪽 우회가 있으면 지운다 (1101/09-01) src/bootstrap/runtime-adapters.ts ddf411e
[계약] realtime: 서버만 끊긴 OFFLINE 실패(브라우저는 online)를 online 이벤트를 기다리지 않고 backoff로 재시도하고, 상한에 닿으면 끝낸다. realtime recipe를 쓰는 프로젝트만 해당 (0929/04-01) src/adapters/realtime/ 4d27b20
[계약] Service Worker 빌드가 public/을 다시 복사하지 않는다(publicDir: false). 전에는 SW를 켠 빌드의 dist/config.json이 local 문서로 덮어써져 운영 승인이 거절됐다. SW를 켠 프로젝트만 해당 (0929/06-01) vite.service-worker.config.ts, scripts/build-frontend.ts c7b9cb8
[계약] check:design-system 규칙 4개가 생겼다. 두 테마에서 --color-focus가 표면 토큰 8종 모두와 3:1 이상, color-mix()는 in oklab만(oklch·lch·hsl·hwb 혼합은 실패), 계약의 컴포넌트 토큰은 스타일 하나 이상이 var(--name)으로 읽음, --font-sans 첫 글꼴은 기본 키워드이거나 @font-face로 싣는 글꼴. 규칙은 scripts/lib/design-system-rules.ts의 순수 함수다. deg 색상각과 시스템 글꼴 이름은 받는다 (UI-01, UI-02, UI-03, UI-05, 1101/12-01, 1101/12-02, 1101/12-04) scripts/check-design-system.ts, scripts/lib/design-system-rules.ts, scripts/lib/oklch-contrast.ts 35b183b, bfa7dd9, 165ed19, 8576ce1, 49d8675, e714c0d
[계약] 시각 테스트가 tests/visual/fonts.conf로 글꼴을 고정하고, 스크린샷 전에 실제로 그려진 글꼴을 검사한다(visual-fonts setup 프로젝트). CI runner에 fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation이 있어야 한다. Linux 전용이다 (1101/11-02) tests/visual/fonts.conf, tests/visual/fonts.setup.ts, playwright.visual.config.ts, docs/testing/frontend-platform-testing-strategy.md 08b5ccc
[계약] 레지스트리 breaking 증거(config/contracts/registry-change-evidence.json)에 after가 필요하고, diff의 after 값과 같아야 한다. 한 번 쓴 증거로 같은 row·field의 다음 변경이 통과하던 문제다. diff에 남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다 (0929/07-01) scripts/lib/registry-compatibility.ts, config/contracts/registry-change-evidence.json, docs/operations/ci-quality-gates.md 5e6be9a
[계약] 레지스트리 호환성 분류: 선언 타입(string|null 등) 안의 null ↔ 값 전환은 타입 변경(breaking)이 아니라 breakingFields로 등급을 정하고(보통 behavior-change), contract allowedValues에 값을 더하기만 하면 additive다. 값을 빼거나 제한을 없애면 그대로 breaking이다 (0929/07-02) scripts/lib/registry-compatibility.ts, scripts/check-registries.ts 82c9e59
[계약] 참조 기능 밖의 기능이 TEMPLATE_FIXTURE 출처 contract contribution을 쓰면 조립 때 ContractContributionError로 실패한다. 제품 기능은 EXTERNAL_PACKAGE를 쓴다. fixture 기여가 둘 이상이어도 실패한다 (1101/07-04) src/contracts/external-contract-runtime.ts, docs/architecture/starter-experience.md c063389
[계약] 폐기 별칭 MappingResult(boundary-mapper.ts)와 ApiFailure(errors.ts)는 export로 남지만 lint(no-restricted-imports)가 src·tests의 import를 막는다. BoundaryMappingResult, AppFailure로 바꾼다. 타입이 같아 런타임은 그대로다 (1101/07-01) eslint.config.ts, src/contracts/boundary-mapper.ts, src/contracts/errors.ts, src/adapters/http/ fc303d8
[계약] StorageBackend에 "external"이 생겼다. cross-context pulse 키는 외부 소유로 바뀌어 StoragePort로 읽고 쓰면 *_UNAVAILABLE로 거절된다. exhaustive switch를 쓰는 코드는 분기를 더한다 (1101/05-01) src/contracts/storage-keys.ts, config/contracts/registry-governance.json, config/contracts/registry-change-evidence.json e98a980
[계약] 쓰지 않는 npm script 4개(scan:security:fixture, build:profile, generate:contract-set, build:app-only)를 지웠다. 게이트가 닿지 않는 scan:* script는 config/ci/ungated-scripts.json 항목이 있어야 한다 (1101/12-05) package.json, scripts/lib/ungated-scripts.ts, docs/operations/ci-quality-gates.md 98b9682
[계약] 호스팅 계약에 앱 경로(appRoute, /__probe/deep-link)와 워커 스크립트(serviceWorker, 워커를 싣는 빌드만) 표면이 생겼다. 호스트는 파일이 없는 모든 경로에 그 release의 index.html을 HTML 헤더로 주고(SPA fallback), service-worker.js는 no-cache로 준다. fallback이 없으면 FE-GATE-019 live probe가 실패한다. nginx 예시는 docs/operations/release-cache-rollback.md에 있다 (1101/13-04) config/hosting/cache-policy.json, config/hosting/response-headers.fixture.json, scripts/lib/hosting-probe.ts, scripts/verify-hosting-headers.ts 629c8f0
[계약] 업로드 part 발급·PUT이 서버의 Retry-After를 기다리고, maxRetryAfterMs를 넘으면 다시 보내지 않는다. 실패 결과에 대기 시간이 붙도록 포트 반환 타입이 넓어졌다(추가만) (1101/01-01) src/adapters/browser-transfer/ 95e4445
[계약] upload 실패 번역이 HTTP 상태와 함께 code를 보고 복구 행동(recovery)을 고른다. 6개 경로 중 5개의 recovery 값이 표대로 바뀌었다. BFF 발급 401/403은 아직 object store 403과 구분되지 않는다 (0929/01-01) src/adapters/browser-transfer/ 9142390
[계약] realtime 배럴이 결과 생성 함수 realtimeSuccess·realtimeFailure를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) src/adapters/realtime/index.ts 3fe28de
[계약] 라우터 base path(VITE_ROUTER_BASE_PATH)를 쓰면 Web Push 정상 클릭, SW 사전 캐시 URL, SW의 설정 URL이 모두 그 경로 아래로 간다 (1101/06-01, 0929/06-02) src/adapters/web-push/, scripts/generate-service-worker-assets.ts c67edd2, 85d55e0
[계약] 앱 조립이 소유 context 루트가 닿지 않는 기능 라우트(1101/09-06)와 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands, 1101/09-07)를 throw로 거절한다. 전에는 조용히 NOT_FOUND가 되거나 아무것도 시작하지 않았다 src/apps/deployable-app-module.ts, src/bootstrap/ 7139c7c, 48a4074
[계약] 전송 전 거절의 원인이 진단에 남고, 연결 실수·멱등 키 위반은 VALIDATION_REJECTED 대신 UNKNOWN_CLIENT_FAILURE로 나온다. 그 실패의 화면 문구가 "요청을 처리할 수 없습니다."로 바뀐다 (1101/03-02) src/adapters/http/ 4da0466
[계약] Vitest가 CI에서 skip·todo·only가 남은 실행을 실패시킨다(-t나 file:line으로 좁힌 실행은 제외). quarantine 주석이 붙은 skip도 실패한다(docs/testing/frontend-platform-testing-strategy.md 16.5절) (1101/10-04) vitest.config.ts, tests/support/ 95e7d11
[계약] 시각 회귀 허용치가 비율 0.2%에서 절대 50 px로 바뀌었다. 전에는 잘린 선택 상자(UI-04, 1,145 px)도 통과했다 (1101/11-03) playwright.visual.config.ts 5ce3db9
[계약] BREAKING useApplicationMutation이 raw { execute, definitionId } 입력을 받지 않는다. useServerStateScope()의 scope로 만든 BoundMutation(definitionVersion·operationId·requiresIdempotencyKey·owner·duplicatePolicy·invalidate)을 넘기고 execute(input, { signal, intent })로 부른다. raw query는 남았다. raw query는 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기). LEGACY 실행 분기는 legacy 전용 테스트 때문에 남겼다 (1101/08-03) src/presentation/adapters/query/application-query.ts, tests/helpers/legacy-application-query-harness.ts 1fa5f3e
[계약] BREAKING recipe의 browser-file·OPFS·storage durability·cache 타입 중 src와 이름이 같은 34개는 src 타입을 다시 내보낸다. fake는 src port를 구현하고 BrowserDataResult를 돌려준다. MemoryDurableObjectStore 생성자가 바뀌었고 DurableObjectDataClass·DurableObjectIntegrity·DurableObjectRead·ObjectStoreRecoverySummary는 지웠다. offline-indexeddb recipe를 쓰는 프로젝트만 해당 (0929/05-03) recipes/frontend-capabilities/ e1a4580
[계약] 제품은 runtime-adapters.ts를 고치지 않는다. 추가 capability(FeaturePlatformCapabilities 확장, indexedDb 포함)와 인증 프로필별 자격증명 제공자는 src/bootstrap/product-composition.ts에서, 제품 인증 프로필과 런타임 설정 키(zod)는 src/contracts/product-contracts.ts에서 돌려준다. 자격증명 순서는 scope fence → ANONYMOUS → 제품 제공자 → 세션 → fence 재확인이다. 그동안 runtime-adapters.ts·feature-adapter-contribution.ts·rest-profiles.ts·release-artifacts.ts·runtime-config-schema.ts에 넣은 제품 코드를 이 두 파일로 옮긴다 (1101/09-02) src/bootstrap/product-composition.ts, src/contracts/product-contracts.ts, src/bootstrap/runtime-adapters.ts da1e128
[계약] 기능 계약에 route id APP_HOME을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. src/contexts/<context>/context-layout.tsx가 CONTEXT_LAYOUT을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 <main id="main-content" tabIndex={-1}> 하나를 가져야 한다 (1101/09-03) src/contracts/routes.ts, src/contexts/bounded-context-module.ts, scripts/generate-product-feature-index.ts ca16187
[계약] context 라우트 적재 때 기능 계약에 없는 handle routeId가 있으면 route id·context id·기능 id를 담은 오류로 실패한다 (1101/09-06) src/contexts/bounded-context-module.ts, src/apps/deployable-app-module.ts d6e4e51
[계약] 인증 프로필 REFERENCE_EXTERNAL_BEARER의 새 이름은 EXTERNAL_BEARER다. 옛 이름은 한 릴리스 동안 @deprecated 별칭으로 남는다 (1101/16-03) src/contracts/rest-profiles.ts 6c5818f
[계약] CREDENTIAL_HEADER_NAMES에 x-xsrf-token을 더했다. 짝 백엔드(Spring CookieCsrfTokenRepository)의 기본 CSRF 헤더다 (1101/09-02) src/contracts/rest-profiles.ts 183a4a3
[계약] V2 Envelope에 data 키가 없으면 null로 읽는다. meta.requestId·traceId는 선택이다. 짝 백엔드는 null 필드를 생략한다 (백엔드 리뷰 1101/02-02) src/adapters/http/schema-registry.ts 969979d
[계약] V2: 422 IDEMPOTENT_REQUEST_MISMATCH·400 IDEMPOTENCY_KEY_INVALID가 effect: "NOT_APPLIED"와 진단 reason을 싣는다. 409의 Retry-After는 retryAfterMs로 실린다(V3 PROBLEM 실패도 같다). 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다. 응답 code의 정본은 백엔드 템플릿 docs/web/http-contract.md §2다 (백엔드 리뷰 1101/02-01) src/adapters/http/client.ts, src/adapters/http/feature-http-binding.ts, src/presentation/adapters/query/application-query.ts 93782b0, 47fec5c
[계약] V2 클라이언트가 짝 백엔드의 400 VALIDATION_FAILED(필드 목록 details: [{field, code, message}])를 422와 같은 VALIDATION_REJECTED·validationIssues로 읽는다. 필드 검증 거절(422와 이 400)은 effect: "NOT_APPLIED"다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다 (백엔드 리뷰 1101/02-01) src/adapters/http/client.ts, src/contracts/errors.ts 02e35d2, 64e98ee
[계약] V3 실행 결과에 선택 필드 sentRequestId가 생겼다. 서버가 x-correlation-id를 돌려주지 않으면 AppFailure.requestId는 보낸 값이다. 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (0929/03-04) src/adapters/http/http-execution-v3.ts, src/adapters/http/feature-http-binding.ts 849d000
[계약] ResumableUploadPort.upload(): part 발급(BFF)이 401/403으로 거절하면 recovery가 RESUME 대신 NONE(retryable: false)이다. 세션 만료·권한 회수라 재인증 전에는 다시 불러도 같다. object store PUT 403은 그대로 RESUME이다 (0929/01-01) src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts c5f87aa
[계약] realtime stream coordinator의 effect·recovery·close 마감 실패가 IDLE_TIMEOUT 대신 APPLY_FAILED/APPLY, PROVIDER_UNAVAILABLE/RECOVER, PROVIDER_UNAVAILABLE/CLOSE로 나온다. RealtimeObservation.reason도 같다 (1101/04-02) src/adapters/realtime/stream-coordinator.ts 1196b86
[계약] OPFS journal 목록이 손상 행을 건너뛰고 corruptRows로 센다. reconcile은 corruptTransactions를 보고한다. 손상 때문에 끝나지 못한 승인된 LOGOUT·ACCOUNT_DELETION은 partition을 지우고 partitionDeleted를 보고한다. OpfsJournalPort.removePartition과 worker gateway removePartition이 필수 메서드로 추가됐다 (0929/05-01) src/adapters/storage/opfs/ 72edb55
[계약] MessageArguments<Key>가 catalog 문자열의 {이름}에서 파라미터를 만든다(값은 string 또는 number). MessageParameters는 값 타입을 좁히는 덮어쓰기이고, ParameterlessMessageKey는 자리표시자 없는 키만이다 (0929/08-03) src/presentation/i18n/message-contract.ts ff33d58
[계약] check:i18n은 catalog parity와 raw backend 메시지만 검사한다. 화면 문구 literal은 ESLint screenTextSelectors가 잡는다. 한글 주석은 통과하고, 영어 JSX 문구·접근성 이름은 실패한다. template literal·삼항식·객체 prop 문구는 못 본다 (0929/08-02) eslint.config.ts, scripts/check-i18n.ts 855d22a
[계약] design-system primitive를 src/presentation/design-system/primitives/<컴포넌트>.tsx로 나눴다. design-system/index.ts의 export 목록은 같다. 파일을 직접 import하던 코드는 경로를 바꾼다 (1101/08-08) src/presentation/design-system/primitives/, vite.config.ts 6dd4bc1, 51941a5
[계약] token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES가 생겼다. 첫 글꼴 규칙이 이 목록의 글꼴을 허용한다 (1101/12-04) src/presentation/design-system/tokens/token-contract.ts, scripts/lib/design-system-rules.ts b4ccada
[계약] 지금 diff와 맞지 않는 breaking 증거 행이 있으면 check:registries가 그 행을 적고 실패한다. update:registry-baseline이 그런 행을 지운다. 다운스트림은 오래된 행을 지우거나 한 번 재승인한다 (0929/07-01) scripts/lib/registry-compatibility.ts, scripts/update-registry-baseline.ts 4ada84e
[계약] FE-REG-ROUTE가 paramsSchema·searchSchema를 허용 목록으로 보지 않고, loadingSurface는 kebab-case 형식만 본다. 기능 라우트를 더해도 governance를 고치지 않는다. 다운스트림은 목록에 더해 둔 값을 지운다 (0929/07-03) config/contracts/registry-governance.json, scripts/check-registries.ts e8d7fb4
[계약] 레지스트리 분류기가 무효화 그래프(topics·namespaces·edges)에 원소를 더하기만 한 변경을 additive로 본다. 빼거나 바꾸면 그대로 breaking이다. 이런 추가에 적어 둔 breaking 증거 행은 stale로 실패하니 update:registry-baseline으로 지운다 (0929/07-02) scripts/lib/registry-compatibility.ts 605fd17
[계약] 레지스트리 기준선을 한 번 재승인했다. FE-REG-API·FE-REG-SCHEMA source를 1101/15-01 뒤 위치로 고쳤고, 그 전 승인 뒤 쌓인 변경도 함께 승인했다. 다운스트림은 동기화 뒤 한 번 재승인한다 (1101/15-01) config/contracts/registry-baseline.json 70d0ac1
[계약] staging·production 승인(FE-GATE-027)이 example.com·example.net·example.org와 그 하위 도메인, .example·.invalid·.test endpoint를 거절한다. 프로필을 고치지 않은 운영 빌드는 두 위반으로 거절된다. CI에서 endpoint는 config/runtime/<profile>.json에 커밋한다 (1101/13-02) src/contracts/deployment-admission.ts 7b34756
[계약] staging·production 승인이 자리표시자 계약 신원(digest PLACEHOLDER_CONTRACT_PACKAGE_DIGEST)을 거절한다. findAdmissionViolations가 세 번째 인자로 계약 패키지를 받는다. --config 수정본 검사는 패키지를 보지 않는다 (1101/16-01) src/contracts/deployment-admission.ts, scripts/check-release-admission.ts 1269992
[계약] workflow의 promotion과 production_gate 사이에 deployment 배포 슬롯 job이 생겼다(job 10개). 슬롯이 비어 있으면 FE-GATE-019가 UNVERIFIED다. FE-GATE-019는 다시 빌드하지 않고 --release-root .release/promoted-release를 보며, 배포된 release-manifest.json의 buildId·releaseId가 후보와 다르면 FAIL이다. 예전에 PASS하던 FE-GATE-019가 이제 UNVERIFIED 또는 FAIL이다 (1101/13-01) .gitea/workflows/quality-gates.yml, config/ci/gates.json de379ea
[계약] src/contracts/zod-validator.ts의 zodValidator로 zod 스키마를 RuntimeValidator로 바꾼다. 검증을 일부러 생략할 때는 unvalidatedPayload(schemaId, reason)(src/contracts/unvalidated-payload.ts)를 쓴다. 이 검증기에는 validation: "NONE" 표시가 붙고, listUnvalidatedPayloads(composed)가 조립 결과에서 생략 목록을 만들어 플랫폼 개요 화면이 보여 준다 (1101/07-03) src/contracts/zod-validator.ts, src/contracts/unvalidated-payload.ts d3ddc89, 8b7c6eb
[계약] pnpm create:feature <id> [--context <ctx>] [--package <name@version> --digest <sha256> --revision <hex>]로 기능 뼈대를 만든다. FE-GATE-020이 test:feature-scaffold(생성한 기능으로 merge 게이트 15개)를 돈다. test:sample-removal은 샘플을 지운 뒤 기능을 생성해 게이트를 다시 돈다 (1101/16-01) scripts/create-feature.ts, scripts/test-feature-scaffold.ts, config/ci/gates.json d166aa3
[계약] verify:documentation(FE-GATE-017)이 입구 문서 4개의 src 최상위 폴더 설명과 layers.md의 아키텍처 규칙 이름을 검사한다(sourceStructure). docs/README.md 1절 현재 계약 문서에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지도 검사한다(documentReferences). 수동 접근성 범위는 route ID 목록 대신 라우트별 기록 파일로 검사하므로 라우트를 더해도 README·체크리스트를 고치지 않는다. 참조 기능을 지운 복사본은 그 파일을 가리키는 문서를 고쳐야 통과한다 (1101/14-03, 1101/14-05) scripts/verify-documentation-readiness.ts, docs/README.md 61baf96, 16202fd
[계약] 규모 설계서를 docs/architecture/scale-architecture.md(현재 계약, 절 번호 유지)로 옮겼다. 절마다 현재 계약·기록만 상태와 코드와 다른 점을 적었다. 코드 주석 Spec §N 87곳은 scale-architecture.md §N으로 바꿨고, 문서 이름 없는 spec § 참조는 tests/unit/deletable-history-documents.test.ts가 막는다. 지울 수 있는 기록 목록에서 docs/reviews/adapters/를 뺐다(INVENTORY와 remediation ledger가 그 안의 리뷰로 링크한다). 복사한 프로젝트는 이 폴더를 지우지 않는다 (1101/14-01) docs/architecture/scale-architecture.md, README.md, docs/README.md, tests/unit/deletable-history-documents.test.ts 0a7fbed, b26517e
[계약] 레시피 번들 예산을 측정값 + 3%를 100 B 단위로 올린 값으로 다시 정했다: file-transfer 57,800, offline-indexeddb 38,500, realtime 42,200, service-worker-pwa 10,100. 3%를 넘는 증가는 커밋 본문에 이유를 적고 같은 규칙으로 올린다. 규칙은 docs/architecture/optional-adapter-recipes.md에 있다. 그 전에 file-transfer가 이 브랜치에서 55,700 → 56,100으로 한 번 올랐다 (0929/05-04) config/recipes/frontend-capability-recipes.json 95e4445 외, 313f9ba

그 밖의 수정

  • 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음(서비스가 토큰으로 브랜드를 바꿀 수 있다), --font-sans가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가 --field-border를 읽음(대비 3:1 이상) (UI-01~UI-06, UI-08, 1101/12-01). src/presentation/design-system/, src/presentation/styles/theme/, src/presentation/examples/. 시각 골든은 373b27b에서 고정 글꼴로 다시 찍었다
  • 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서 getByText로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-01). src/presentation/layouts/app-shell.tsx, src/presentation/styles/theme/
  • 저장소: 진단 이벤트 storage.operation.failed에 실패 원인(reason)이 붙는다 (1101/05-02). lifecycle 리스너 주인 주석을 실제에 맞추고 테스트를 뒀다 (1101/05-03). OPFS purge가 객체를 못 지우면 완료와 chunk sweep을 보고하지 않는다 (0929/05-02). src/adapters/storage/, src/adapters/platform/
  • 운영: 배포된 config.json의 비상 스위치(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES)를 바꿀 때 check:release-admission --config <고친 사본> --original <배포된 원본>으로 먼저 검사한다. 두 스위치 밖의 필드가 바뀌면 거절한다. 절차는 docs/runbooks/FE-RB-001.md (1101/13-05). scripts/check-release-admission.ts, .env.example
  • 문서: 성능 문서의 번들 기준선(202,509~202,522 B, 여유 약 2,280 B)과 출처별 크기, 분류 규칙을 1101/15-01 뒤 빌드에 맞췄다 (1101/15-02). PRODUCT.md를 더하고 예제 제거 주장을 드릴 범위에 맞췄다 (1101/14-04). 이 문서와 리뷰 가이드가 리뷰 ID에 라운드를 붙인다 (1101/14-02)
  • verify:documentation이 실패하면 실패한 검사 이름과 고칠 문서·빠진 route ID를 적는다 (1101/14-06)
  • 테스트: Testing Library 대기 기한을 tests/setup.ts 한 곳에서 5초로 정하고, 부하에 흔들리던 극한 규모·guardian 테스트를 고쳤다 (0929/10-01). npx vitest나 npm을 거친 IDE 실행기로 돌려도 npm scope 환경변수 때문에 실패하지 않는다(vitest.config.ts) (1101/15-05). cgroup 시스템 테스트가 /proc 표본 대신 실행 단계가 남긴 PID·argv 기록을 읽는다 (1101/11-01). exact-five CLI 테스트가 실제 출력 문구를 기대한다 (0929/11-01). guardian이 실패하면 stdin을 기다리지 않고 끝난다(3c175a5). 계약 조립기와 V2/V3 대조 테스트 보강 (1101/07-02, 1101/07-06)
  • 브라우저 파일·캐시: preview와 download의 dispose가 자기 lease만 풀어 grace 중인 download URL을 끊지 않는다 (1101/02-01). 같은 이미지 동시 resolve는 probe를 한 번만 돈다 (1101/01-04). 캐시 stage 재검증 실패가 CACHE_STAGE로 기록되고 (1101/02-03), 정책 변경·손상 뒤에도 다음 배포가 pointer를 덮어쓴다 (0929/02-01). cross-context publish 실패 원인이 관측 reason에 실린다 (1101/02-05)
  • HTTP·조회: 문제 응답 분류기 실패가 진단 reason CLASSIFIER_FAILED로 남는다 (1101/03-05). 어느 무효화 topic도 닿지 않는 조회 namespace를 진단으로 한 번 알린다 (1101/03-01)
  • 화면: 검색값만 바뀌면 포커스·스크롤·route.changed를 건드리지 않는다 (1101/08-02). h2·h3·h4 제목 크기·굵기 (1101/08-04), 한국어 단어 단위 줄바꿈 (1101/08-06), 상태 화면·오류 요약의 제목 수준 지정 (1101/08-05), 예제 화면의 lang="ko-KR" (1101/08-07), 폼 저장 실패와 결과 불명 화면의 지원 참조 (0929/08-04)
  • 진단: context·feature 오류 경계와 라우트 모듈 실패가 진단에 남고, 지원 참조가 build:incident 형식이다 (1101/09-09). REST 보안 프로필 오류가 operation과 깨진 조건을 말한다 (1101/16-03)
  • 테스트·운영 도구: guardian이 실패하면 stdin을 기다리지 않고 바로 끝난다 (G-1). SW e2e가 제품이 이미 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 이벤트 계약 검증이 실제 이벤트 행으로 고정됐다 (1101/10-01). 규모 측정 기준선을 1101/15-01 뒤 코드로 다시 쟀다. 측정용 기능 복사본은 외부 패키지를 고정하고 선언한다 (9333595, 1101/07-04). reference feature를 지워 설치 기능이 0개여도 타입 검사와 create-application.ts 커버리지가 통과한다 (e4ace51, 1101/15-01)
  • 문서: 새 기능 추가 매뉴얼 docs/manual/(한국어)을 더했다. 0~11단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것을 적고, 결정표·기능 폴더 밖 파일·create:feature 인자·전역 ID·패턴·오류 메시지 참조를 둔다. 두 템플릿 공통 원칙은 design-docs repo conventions/feature-design-principles.md에 있다. verify:documentation이 매뉴얼의 경로·명령·게이트 ID를 검사한다 (1101/16-01)
  • 성능: 갤러리 전용 primitive를 초기 청크에서 빼 초기 JS를 2,718 B 줄였다. 초기 청크는 16 → 25개가 됐다. HTTP/1.1로 호스팅하면 청크 수를 다시 본다 (1101/08-08)
  • 테스트: 플랫폼 component 테스트가 스타터 화면 대신 테스트 전용 페이지(tests/helpers/fixture-feature.tsx)를 쓴다. 스타터 화면을 바꾸는 제품은 tests/component/starter-*.test.tsx를 함께 지운다. HTTP 시나리오 증거(FE-GATE-007)와 기능 API 타입 음성 fixture(FE-GATE-003)는 샘플을 지워도 남는다. tests/mocks/handlers/reference-resources.ts는 tests/features/reference-feature/reference-resource-handlers.ts로 옮겼다 (0929/10-02)
  • 테스트: 기능 테스트가 createHttpScenarioHandler(<설치 계약>, { scenario, payload })로 공유 MSW 시나리오를 쓴다. 기능을 더해도 카탈로그와 기능 밖 테스트를 고치지 않는다. tests/mocks/**는 플랫폼 소유다 (1101/16-02, 1101/16-01)
  • 참조 기능: 샘플 페이지가 경로 문자열 대신 referenceRouteUrl(routeId, input)으로 링크를 만들고 route 입력 cast를 없앴다. REFERENCE_FEATURE_ROUTE_CODECS는 presentation/reference-route-codecs.ts로 옮겼다. 목록 링크 href가 ?limit=20이 붙은 정식 URL이 된다 (1101/16-04)
  • 저장소: OPFS purge가 여러 페이지를 다 지우면 끝났다고 보고하고 chunk sweep을 한다. 전에는 한 번 더 불러야 끝났다 (README 13.6)
  • 운영 도구: 적재에 실패한 레지스트리 source는 "missing" 대신 그 오류 메시지를 적는다. check:feature-index 예외 이유를 실제 사용처로 고쳤다 (1101/12-05). 워커를 싣는 빌드의 SW 스크립트 헤더 검사를 테스트로 고정했다 (0929/06-05)

알려진 제한

  • 백엔드 응답 code 정본(clean-architecture-backend-template/docs/web/http-contract.md)은 아직 백엔드 repo에 커밋되지 않았다. 그래서 프론트 계약 문서는 커밋 SHA 대신 결정일로 기준을 적었다. 백엔드 application 층이 쓰기 뒤에 VALIDATION_FAILED를 던지면 "적용 안 됨" 판정이 틀린다. 지금 백엔드는 이 code를 요청 바인딩 단계에서만 낸다.
  • 백엔드 필드 검증 code(NOT_BLANK, SIZE 등)가 폼 문구 표에 없어 "입력값을 확인해 주세요." 기본 문구가 나온다. V3 실행기 진단에는 problem code가 없다.
  • create:feature로 만든 기능과 참조 기능(V3 실행기)은 짝 백엔드의 Envelope 응답({success, data|error, meta})을 그대로 읽지 못한다. V3는 DTO 본문과 problem details를 읽는다. 백엔드 맞추기는 V2 클라이언트에만 들어갔다. 해결 방법은 아직 정하지 않았다 (1101 README 14.3).
  • webkit에서 old-tab-chunk-recovery.spec.ts가 가끔 "preload했지만 쓰지 않음" 경고로 실패할 수 있다(한 번 관찰, 10회 반복은 통과).
  • context 레이아웃의 skip link와 <main>은 타입 주석·문서·테스트로만 지킨다. 실행 검사는 없다 (1101/09-03).
  • OPFS: lease 밖(FINISH~commit)에서 다른 탭이 같은 partition에 쓰는 경합은 검증하지 않았다 (0929/05-01).
  • realtime: live-poll handoff coordinator의 마감 4곳은 아직 IDLE_TIMEOUT이다 (1101/04-02 범위 밖).
  • 등록 라우트가 없는 URL에서 적재가 실패하면 진단 route_id가 NOT_FOUND다 (1101/09-09).
  • ui-gallery-page.tsx는 component 테스트 커버리지가 0%다. e2e와 시각 테스트만 본다.
  • create:feature --context reference-context로 만들면 참조 기능 라우팅 테스트가 깨진다. 생성 명령은 기본으로 새 context를 만든다.
  • 실제 Gitea runner와 실제 HTTPS 호스트에서는 돌리지 않았다(SPEC U-1). FE-GATE-019 배포 슬롯은 주입한 fetcher로만 시험했다 (1101/13-01). 시각 테스트의 글꼴 패키지 설치 단계는 workflow에 넣지 않았다. nginx 예시는 실행해 보지 않았다.

0.2.0 — 태그 v0.2.0 (2026-09-27)

2026-09-25 성숙도 리뷰(docs/reviews/2026-09-25-maturity-review/) 수정 묶음이다. 기준은 main 4626b73이다. package.json의 version은 0.2.0이다.

보안·계약 변경

먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다.

표시 변경 영향 경로 커밋
[계약] 모든 V3 HTTP 요청이 논리 실행마다 x-correlation-id 헤더를 하나 보낸다. 다른 origin API는 preflight Access-Control-Allow-Headers에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 Access-Control-Expose-Headers에도 넣는다 (0925/03-03) src/adapters/http/http-execution-v3.ts, src/adapters/http/feature-http-binding.ts, src/bootstrap/runtime-adapters.ts, docs/operations/api-contract-and-server-state-recovery.md c5da3cf, f0a6495
[계약] 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (0925/03-01, 0925/08-03) src/presentation/adapters/query/application-query.ts, src/presentation/forms/use-app-form.ts, src/presentation/components/async-surface.tsx dfb1b9e
[계약] 명령의 401/403/429를 기능 패키지가 분류할 수 있다(classifyStatus, 선택 필드). 재로그인이 먼저다 (0925/03-02) src/adapters/http/http-effect-certainty.ts, src/adapters/http/http-execution-v3.ts, src/contracts/errors.ts, src/contracts/external-contract-runtime.ts 2afee67
[계약] 422 problem body의 필드 오류(path, code)를 폼까지 전달한다 (0925/03-04) src/adapters/http/feature-http-binding.ts, src/features/reference-feature/contracts/reference-schemas.ts 479acd5
[계약] 텔레메트리 수집기 이벤트마다 build_id, release_id가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (0925/13-11, 0925/03-05) src/adapters/telemetry/telemetry-collector.ts, src/bootstrap/runtime-adapters.ts 43e47f4, e14c613
[보안] 번들이 읽지 않는 VITE_* 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, ENV_REGISTRY에 없는 VITE_* 이름은 빌드를 멈춘다 (0925/13-06) src/contracts/env.ts, vite.config.ts, eslint.config.ts 2ec59ad
[보안] 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (0925/05-03, 0925/05-04) src/adapters/platform/indexeddb-connection.ts, src/adapters/storage/indexeddb/indexeddb-runtime.ts, src/adapters/storage/opfs/opfs-byte-store-adapter.ts, src/application/ports/browser-file-storage/ 3e37fbf, 6ab564f
[계약] RELEASE_TARGET이 APP_PROFILE과 다르면 배포 승인이 거절된다 (0925/12-02, 0925/13-01) scripts/check-release-admission.ts, .gitea/workflows/quality-gates.yml 239b22a
[계약] 설정·매니페스트 URL이 VITE_ROUTER_BASE_PATH를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (0925/13-07) scripts/generate-runtime-config.ts, src/contracts/env.ts, vite.config.ts e215c84
[계약] VITE_PRODUCT_FEATURES는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (0925/09-02) scripts/generate-product-feature-index.ts, src/contracts/product-features.ts a8111f7
[계약] src/features/<id>/에 feature-module.ts도 NOT_INSTALLED 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 --feature=<id>를 받는다 (0925/09-07, 0925/14-03) scripts/generate-product-feature-index.ts, scripts/test-sample-removal.ts, config/contracts/registry-governance.json, docs/architecture/starter-experience.md ad0e83c
[계약] 기능 루트·context·app 파일은 src/adapters를 import할 수 없다. presentation은 app·context를 import할 수 없다(app-router.tsx 예외) (0925/12-03) scripts/check-architecture.ts, .dependency-cruiser.json, docs/architecture/layers.md f8b6a36
[계약] CI 계약의 게이트 수·해시가 config/ci/contract-baseline.json으로 옮겨졌다. 게이트를 바꾸면 update:ci-contract-baseline로 갱신한다 (0925/14-02) config/ci/contract-baseline.json, scripts/check-ci-contract.ts 0114b1e
[계약] 모든 테스트 파일은 어떤 게이트가 돌리거나 config/ci/ungated-tests.json에 이유가 있어야 한다 (0925/12-04, 0925/09-11, 0925/11-03) config/ci/gates.json, config/ci/ungated-tests.json, scripts/lib/ungated-tests.ts 840de45, 45ee231
[계약] 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 UNVERIFIED(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (0925/08-06, 0925/11-01, 0925/13-03, 0925/13-05) config/ci/gates.json, .gitea/workflows/quality-gates.yml, scripts/drill-runbook.ts, docs/operations/ci-quality-gates.md 7298275, 7f889a6, a263d8c
[계약] engineStrict, saveExact를 pnpm-workspace.yaml로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (0925/13-09) pnpm-workspace.yaml, .npmrc a5dc851
[계약] 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (0925/08-01) src/presentation/forms/form-contracts.ts, src/presentation/forms/use-app-form.ts, src/presentation/forms/form-components.tsx 9894a70
[계약] browser-transfer 포트: upload() 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 resourceId를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (0925/01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 src/application/ports/browser-transfer/, src/adapters/browser-transfer/ 648fe4e, 7b2cefb, 5a6665a, 426b6b8 외
[계약] IndexedDB·OPFS 포트: 미래 스키마는 INCOMPATIBLE, 빈 receipt는 없음으로 본다 (0925/05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 src/application/ports/browser-file-storage/, src/adapters/storage/ 7f45afa, 47cf040, 8fc816e 외
[계약] 외부 세션 owner의 readSubject()와 SessionGateway.getSubject()가 필수가 됐다. readSubject가 없는 owner는 integration-failed로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 src/adapters/auth/external-session-adapter.ts, src/application/ports/, docs/architecture/starter-experience.md c6300e9
[보안] 운영 CSP(unsafe-eval 없음) 아래에서 zod가 eval을 시험하지 않는다. src/의 코드는 zod를 src/contracts/zod.ts로만 가져온다(dependency-cruiser 규칙) (0925/13-08, 0925/F-7) src/contracts/zod.ts, .dependency-cruiser.json, tests/e2e/production-csp.spec.ts 9dc95ca
[계약] 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (0925/07-02, 0925/13-10) src/contracts/compatibility.ts, scripts/check-registries.ts, config/contracts/ 17d617a
[계약] 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 @deprecated와 제거 조건을 붙였다 (0925/07-04, 0925/07-07) src/contracts/errors.ts, src/contracts/ aff5f43, 9e616d3
[계약] staging·production 빌드는 VITE_BUILD_ID가 없으면 실패한다 (0925/13-15, 0925/F-6) scripts/generate-runtime-config.ts, src/contracts/env.ts 063375e
[계약] Service Worker 빌드가 public/config.json 대신 프로필에서 만든 dist/config.json을 읽고, APP_ENV가 APP_PROFILE과 다르면 빌드를 멈춘다 (0925/06-10, 0925/F-8) vite.service-worker.config.ts, scripts/lib/service-worker-build-input.ts cefb0b2
[계약] Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. REMOVE_REGISTRATION은 스스로 등록을 해지하는 worker를 배포한다 (0925/06-02, 0925/06-06, 0925/06-03) src/adapters/web-push/, scripts/lib/self-unregistering-service-worker.ts, docs/runbooks/ e6c683e, 996a959, 9f2305a
[계약] realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE Retry-After를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (0925/04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 src/adapters/realtime/, config/recipes/frontend-capability-recipes.json bcad7b0, 02d3fdf, 7e37660, 2c5e268 외
[계약] browser-files 포트: 같은 턴의 abort는 ABORTED, 닫은 선택 창은 DISMISSED, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (0925/02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 src/adapters/browser-file-storage/, src/adapters/cache-storage/ c9be8d6, d76653b, 0b41cb3, 55c0bf5 외
[계약] 샘플 상세 경로가 /examples/reference-resources/items/:resourceId로 옮겨졌다. ID가 new·status인 항목도 상세가 열린다 (0925/08-13) src/features/reference-feature/contracts/reference-feature-contract.ts, config/contracts/registry-change-evidence.json d7b81c6
[계약] tsconfig.base.json에 noUnusedLocals를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 check:types에서 실패한다 (0925/12-12) tsconfig.base.json 49413af

그 밖의 수정

  • 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (0925/09-03, 0925/09-04, 0925/09-10). src/bootstrap/, src/presentation/boundaries/boot-error-shell.tsx

  • 부트: FEATURE_OVERRIDES의 모르는 키를 진단으로 남긴다 (0925/09-09). src/bootstrap/runtime-adapters.ts, scripts/check-release-admission.ts

  • 빌드: dist 파일을 다른 사용자도 읽을 수 있게 한다 (0925/13-02). scripts/lib/dist-permissions.ts

  • 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (0925/13-12, 0925/13-04). scripts/lib/vite-module-inventory.ts, scripts/verify-exact-promotion-bundle.ts

  • 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (0925/12-05~12-11). scripts/check-architecture.ts

  • 기능 조립: needs 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (0925/09-01, 0925/09-05, 0925/09-06, 0925/09-08, 0925/09-12, 0925/00-02). src/features/, src/bootstrap/runtime-adapters.ts

  • 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (0925/13-08, 0925/01-04, 0925/05-08, 0925/10-03)

  • 샘플 제거: test:sample-removal이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (0925/14-01, 0925/14-08, 0925/00-01, 0925/10-01). scripts/test-sample-removal.ts, scripts/lib/removal-fixture.ts

  • 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 verify:documentation이 변수 목록을 검사한다 (0925/13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (0925/13-13, 0925/13-14, 0925/03-06, 0925/03-08).

  • 화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (0925/07-01, 0925/08-02, 0925/08-04, 0925/08-07~08-12, 0925/F-10). src/presentation/, src/presentation/i18n/

  • 접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (0925/08-05, 0925/11-02). tests/e2e/accessibility.spec.ts

  • 계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (0925/07-03, 0925/07-05, 0925/07-06, 0925/09-07, 0925/F-3). tests/unit/, src/contracts/

  • Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (0925/06-01, 0925/06-04, 0925/06-05, 0925/06-07~06-09). src/adapters/web-push/, src/adapters/service-worker/, src/bootstrap/

  • 테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (0925/10-02, 0925/10-0410-07, 0925/11-0411-08, 0925/F-2). tests/, scripts/scale/, scripts/lib/lab-performance.ts

  • 테스트 fixture가 공유 node_modules를 다시 쓰지 않고, 임시 폴더를 지운다 (0925/F-4, 0925/F-12, 0925/00-03). scripts/lib/removal-fixture.ts, tests/unit/

  • 문서: 손으로 적은 게이트 수와 LOC를 지우고 verify:documentation의 검사 범위를 적었다 (0925/14-07)

알려진 제한

  • Playwright spec은 chromium·firefox·webkit에서 확인했다. WebKit에서만 난 실패 1건(구 탭 청크 복구 spec의 콘솔 문구 허용 목록)은 b1a36ab로 고쳤다.
  • 사용자 몫(SPEC "범위 밖" U-1~U-5, 0925/F-11)은 이 버전에 들어 있지 않다.

0.1.0 — main 4626b73 (2026-09-24)

태그가 없는 main이고 package.json 버전은 0.1.0이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다.

표시 변경 영향 경로 커밋
[보안] 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) src/adapters/http/http-contract-bridge.ts, src/adapters/auth/external-session-adapter.ts 5e62b7e
[보안] REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) src/contracts/api-operations.ts f26fd18
[보안] 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) src/platform/telemetry/redact-telemetry.ts 4e0745c