Files
clean-architecture-frontend…/CHANGELOG.md
T
DongHyeonka eaa5b63571 docs(changelog): 미출시 절에 이번 브랜치의 변경과 기능 이행 순서를 적는다
문제
fix/ui-design-audit-2026-11-01 브랜치에는 다운스트림(tech-log, memento)이
따라 고쳐야 하는 변경이 쌓였는데 CHANGELOG에 한 줄도 없다. 특히
298201f(15-01)는 FeatureModule 모양을 바꾸는 BREAKING 변경이라, 커밋
본문의 BREAKING CHANGE 꼬리말만으로는 기존 기능을 어떤 순서로 옮겨야
하는지 알 수 없다. 영역 14는 check:design-system 규칙 추가가 CHANGELOG에
없다고 지적했고, 영역 07 수정(증거 형식, 분류 판정, TEMPLATE_FIXTURE
거부, 폐기 별칭 lint)도 [계약] 행이 필요하다고 각 커밋이 적었다.

고른 방법
- 기존 형식(버전 절 → 보안·계약 표 → 그 밖의 수정 → 알려진 제한)을 따라
  "미출시 — 브랜치 fix/ui-design-audit-2026-11-01" 절을 0.2.0 위에 둔다.
  버전 번호는 정하지 않았다. 리뷰 ID는 1101/14-02 규칙대로 라운드를
  붙였다.
- 15-01은 "먼저 할 일" 절로 따로 뺐다. 298201f 본문과
  src/features/reference-feature/의 실제 모양(feature-module.ts,
  feature-runtime.ts, context-routes.ts, contracts/reference-api-contract.ts,
  installed-contract-contributions.ts, feature-module.ts 타입)을 근거로 아홉
  단계를 적었다.
- [계약] 표에 15-01, FE-GATE-012 merge 이동, 0929/03-01·09-01·0929/04-01·
  0929/06-01(High), check:design-system 규칙 4개, 시각 테스트 fonts.conf와
  runner 글꼴 패키지, 0929/07-01·0929/07-02·07-04·07-01, 05-01, 12-05,
  13-04를 넣었다. 경로는 각 커밋의 변경 파일과 대조했다.
- 커밋 해시는 브랜치에 있는 해시다. 영역 07 등 합쳐진 수정은 브랜치의
  cherry-pick 해시(5e6be9a 등)를 쓴다.

버린 대안
- 0.3.0 같은 버전 절을 미리 만들기: 버전 번호는 이번 작업에서 정하지
  않는다.
- 15-01 이행 순서를 starter-experience.md만 가리키기: 그 문서는 새 기능
  추가 순서라, 이미 있는 기능을 옮기는 단계(runtimes 삭제, features.load
  호출, fake의 load)가 없다.

위험·한계
- 이 worktree에 없는 커밋(5e6be9a까지 브랜치에 합쳐진 것)은 커밋 본문과
  변경 파일 목록으로만 확인했다. 이후 합쳐지는 수정은 이 절에 없다.
- 13-04·13-05·15-02·14-02·14-06·15-05 행의 해시는 이 worktree의 해시라
  브랜치에 옮길 때 바뀔 수 있다.
- registry-baseline의 source 경로, feature-shape-growth 기준선, 08-01 서랍
  시각 골든은 알려진 제한에 적기만 했다.

검증
- node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
  tests/unit/deletable-history-documents.test.ts: 2 passed
- grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md → 0, 새 절 본문의 라운드
  없는 ID 0
- verify-documentation-readiness PASS_SCOPED
2026-11-01 22:49:13 +09:00

154 lines
30 KiB
Markdown

# 변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다.
- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다.
- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다.
- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트).
- 표시가 없으면 템플릿 안에서 끝나는 수정이다.
- 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 라운드마다 `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`에서는 해시가 다를 수 있으니 ID로 찾는다. 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` | `cee9198` |
### 그 밖의 수정
- 화면: 라이트 포커스 링 대비, 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/`. 시각 골든은 `c0c5d9c`에서 다시 찍었다
- 화면: 좁은 화면(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)
### 알려진 제한
- `config/contracts/registry-baseline.json`의 FE-REG-API·FE-REG-SCHEMA `source`가 1101/15-01 뒤에도 `src/features/installed-feature-contracts.ts`를 가리킨다. 승인 digest가 걸려 있어 소유자가 재승인할 때 고친다. `check:registries`는 통과한다.
- 규모 기준선 `config/scale/feature-shape-growth.json`은 1101/15-01 전 측정이다. 그 뒤 수치는 `config/scale/feature-shape-ceilings.json`의 Initial JavaScript 항목에 있다.
- 0929/03-01의 백엔드 계약(처리 중 재전송의 status·code, 충돌 409 code 목록)은 이 repo에서 끝나지 않았다.
- 좁은 화면 서랍(1101/08-01)의 시각 골든 `app-shell-compact-pseudo-drawer.png`는 이 절을 쓸 때 다시 찍지 않았다.
- 실제 Gitea runner에서는 돌리지 않았다(SPEC U-1). 시각 테스트의 글꼴 패키지 설치 단계는 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-04~10-07, 0925/11-04~11-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` |