diff --git a/CHANGELOG.md b/CHANGELOG.md index 4691937d..f0230cf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,60 @@ - 괄호 안 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다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +## 미출시 — `48c7695b` → 정리 단계 + +2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침)와 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`부터 브랜치 끝까지)를 담는다. 3단계(합치기)는 아직 없다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. + +### 먼저 할 일 (BREAKING) + +아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 커밋이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한). + +#### 옮기기 전 + +- 템플릿은 참조 기능(`src/features/reference-feature/`, context `src/contexts/reference-context/`)과 예제 화면(`src/features/platform-examples-feature/`, context `src/contexts/platform-examples-context/`)을 지웠다. 받으면 템플릿 쪽 파일의 삭제가 함께 온다. +- 자기 프로젝트가 그 폴더를 고쳐 남겨 두었는지 본다: `git log --oneline <마지막 동기화 기준>..HEAD -- src/features/reference-feature tests/features/reference-feature src/features/platform-examples-feature`. 고친 파일은 병합에서 수정/삭제 충돌이 된다. + +#### 옮기는 법 + +1. **샘플 사본을 쓰지 않으면 지운다.** 충돌한 파일은 삭제 쪽을 고른다(`git rm`). 함께 지울 것: `tests/features/reference-feature/`, `tests/features/platform-examples-feature/`, `tests/e2e/reference-form.spec.ts`·`reference-route.spec.ts`·`reference-save.spec.ts`, 수동 접근성 기록 7개(`artifacts/tests/a11y-manual/REFERENCE_RESOURCE_{LIST,DETAIL,FORM,STATUS}.md`, `EXAMPLES_{UI,STATES,AUTH}.md`), 런타임 프로필 4개와 `public/config.json`의 `FEATURE_OVERRIDES."reference-feature"`, `package.json`의 `test:reference-feature`. 그다음 `corepack pnpm generate:feature-index`, `node scripts/write-dev-release-manifest.ts`를 돈다 (`e3c8db48`) +2. **샘플 사본을 남겨 쓰는 프로젝트(tech-log의 참조 기능 12파일 등)는 자기 기능으로 옮긴다.** 남길 파일이 기대던 템플릿 쪽 파일(위 1단계 목록, 지운 테스트, `TEMPLATE_FIXTURE` 출처)은 다시 생기지 않는다. 계약 기여의 출처를 `EXTERNAL_PACKAGE`로 바꾸지 않았으면 계약 조립이 `: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to only`로 거부한다. 지울 예정이면 `scripts/lib/removable-template-features.ts`에 적는다. 그러면 `test:sample-removal`(FE-GATE-020)이 그 기능을 지운 사본에서 게이트를 돌고, 문서는 그 경로를 지운 뒤에도 통과한다 (`e3c8db48`) +3. **레지스트리 기준선을 다시 승인한다.** 템플릿 기준선은 샘플의 라우트·operation·스키마·무효화 행을 뺀 것이다. 자기 기준선을 쓰는 프로젝트는 병합 뒤 자기 행으로 다시 받는다: `REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON="<이유>" corepack pnpm update:registry-baseline`. 행을 빼는 것은 breaking이라 승인 없이 `check:registries`가 `breaking change missing evidence:`로 실패한다 (`e3c8db48`) +4. **CI 계약 기준선과 workflow를 자기 값으로 다시 기록한 프로젝트는 다시 기록한다.** FE-GATE-007에서 `test:reference-feature` 명령과 그 산출물이, FE-GATE-009·028에서 지운 라우트의 수동 접근성 기록 산출물 4개가 빠졌다. `CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline`, 그다음 `corepack pnpm generate:ci-workflow` (`e3c8db48`) +5. **초기 JS 기록을 다시 쓴다.** `config/scale/feature-shape-ceilings.json`의 `initialJavascript`에 `firstFeatureGzipBytes`가 더해졌고, 측정은 참조 기능 대신 생성 기능을 복사해 잰다. `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 다시 쓰지 않으면 `test:unit`이 기록과 빌드가 다르다며 실패한다 (`b2042de9`) +6. **`src/features/` 아래에 기능이 아닌 폴더를 두었으면 밖으로 옮긴다.** 생성기는 `NOT_A_FEATURE` 표식을 더 읽지 않는다. 선언 없는 폴더는 `src/features/ has no feature-module.ts; add one, or keep code that is no feature outside src/features`로 실패한다. 템플릿의 local-draft 샘플은 `tests/fixtures/indexeddb-consumer/`로 옮겼다 (`b72cd7d4`) + +#### 옮긴 뒤 확인 + +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4단계), `test:unit`(5단계), `generate:feature-index`(6단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다). +2. 시각 골든: 갤러리 두 장(`design-system-gallery-dark`, `state-surfaces-light`)은 이제 Storybook 정적 빌드의 story를 찍는다. 자기 골든을 다시 찍은 프로젝트는 `corepack pnpm test:visual:update`로 그 둘을 다시 찍는다. +3. `/examples/ui`·`/examples/states`·`/examples/auth`를 열던 자기 e2e는 플랫폼 라우트나 자기 화면으로 옮긴다. 템플릿의 그런 spec은 옮겼다(아래 표). + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] **BREAKING** | 참조 기능과 예제 화면(`/examples/ui`, `/examples/states`, `/examples/auth`)을 지웠다. 소유자 결정(2026-11-07): 샘플은 매뉴얼과 `create:feature`가 생겼으니 지운다. 샘플이 맡던 시험 대상은 먼저 옮겼다(아래 행들). 레지스트리 기준선과 CI 계약 기준선을 다시 승인했다. 위 "먼저 할 일" 1~4 | `src/features/`, `src/contexts/`, `tests/features/`, `config/contracts/registry-baseline.json`, `config/ci/`, `config/runtime/`, `public/` | `e3c8db48` | +| [계약] | `scripts/lib/removable-template-features.ts` 목록이 비었다. 장치는 남는다: 프로젝트가 자기 샘플을 적으면 `test:sample-removal`(인자 없음, FE-GATE-020)이 하나씩 지워 게이트를 돈다. 목록이 비면 `sample removal: SKIP`을 출력하고 보고서에 건너뛴 사례 하나를 남긴다. `--feature=`의 보고서는 늘 `artifacts/tests/feature-removal-.xml`이다 | `scripts/test-sample-removal.ts`, `scripts/lib/removable-template-features.ts` | `e3c8db48` | +| [계약] | 갤러리를 Storybook story로 옮겼다(`src/presentation/design-system/galleries.stories.tsx`). visual 골든 두 장이 Storybook 정적 빌드를 찍는다. visual 설정이 두 번째 web server(정적 workshop, 포트 변수 `TEST_VISUAL_WORKSHOP_PORT`)를 띄운다. 디자인 토큰 색 하나(`--color-action`)를 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px 차이로 실패하는 것을 확인했다. 옛 골든도 같은 변이를 같은 크기로 잡았다. 갤러리의 브라우저 상호작용 검사는 `tests/storybook/galleries.spec.ts`로 옮겼다. 위 "옮긴 뒤 확인" 2 | `.storybook/preview.tsx`, `playwright.visual.config.ts`, `tests/visual/`, `tests/storybook/`, `scripts/lib/storybook-static.ts` | `c7e80f2f` | +| [계약] | 기능 하나가 실제 브라우저에서 라우트·폼·저장까지 되는지는 `create:feature --with-create --keyed` 기능을 넣은 저장소 사본의 빌드가 맡는다(`tests/e2e/generated-feature.spec.ts`, `scripts/lib/generated-feature.ts`). 오래된 탭의 청크 복구 시험도 그 기능의 목록 라우트를 쓴다. 생성기 출력이 바뀌면 FE-GATE-008이 잡는다 | `tests/e2e/`, `scripts/lib/generated-feature.ts` | `794a51a3` | +| [계약] | 규모 측정이 참조 기능 대신 생성 기능을 복사해 잰다(`planShapeFeatures`). `initialJavascript`에 `firstFeatureGzipBytes`(기능이 없는 템플릿에 첫 기능을 더할 때의 비용)가 생겼고, context 비용은 둘째 기능을 새 context에 둘 때와 같은 context에 둘 때의 차이다. 기록: 템플릿 194,354 B·17파일, 첫 기능 6,327 B, 기능 하나 539 B, context 하나 4 B. 성장 기준선(0·25·100개)도 다시 쟀다. 위 "먼저 할 일" 5 | `scripts/scale/measure-feature-shape-growth.ts`, `config/scale/` | `b2042de9`, `9c87cc4d` | +| [계약] | 생성기가 `NOT_A_FEATURE` 표식을 읽지 않는다. local-draft 샘플은 IndexedDB 소비자 시험 fixture(`tests/fixtures/indexeddb-consumer/`)가 됐다. 위 "먼저 할 일" 6 | `scripts/generate-product-feature-index.ts`, `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `b72cd7d4` | +| [계약] | 브라우저 soak(`scripts/scale/browser-soak.ts`, nightly 밖)이 기본으로 생성 기능을 넣은 빌드를 만들어 그 목록 라우트에서 실패하는 백엔드를 관찰한다. `--dist`를 주면 `--feature-route`도 준다. 결과 칸 이름이 `featureVisits`·`settledFeatureVisits`·`apiRequestsPerFeatureVisit`으로 바뀌었다 | `scripts/scale/browser-soak.ts` | `e3c8db48` | + +### 그 밖의 수정 + +- 정리 1단계: 읽는 곳 없는 산출물 13개를 지우고 `artifacts/`를 폴더째 무시한다(`85f941c4`). 아무도 읽지 않는 `config/schemas/` JSON Schema 4개를 지웠다(`0805910c`). 루트 `tasks/`와 `.superpowers/` 기록을 `docs/history/`로 옮겼다(`429b8d88`). nginx 설정 예시를 지우고 호스트가 지킬 조건만 남겼다(`121e1125`). +- `/examples/ui`·`/examples/states`를 열던 e2e(반응형, 스크롤 복원, 타이포그래피, 건너뛰기 링크)는 홈과 `/examples/platform`으로 옮겼다 (`e7210c71`). +- 매뉴얼(`docs/manual/`)의 예제 칸은 생성기 출력 경로와 매뉴얼 안 코드 조각을 가리킨다. 코드 조각 일곱 개(problem details 백엔드의 분류와 매핑, 도메인 모델, 검색값 읽기, 실패 행동, 403 페이지 시험)는 `tests/unit/manual-code-blocks.test.ts`가 생성 기능 위에서 타입 검사·lint·아키텍처 검사·동작 시험을 돌린다. problem details 예는 소유자 결정대로 02 결정표 4절에 있다 (`01cac930`). +- 기능 스위치 시험(`tests/component/product-feature-switch.test.tsx`)과 홈 시작 링크의 스위치 시험은 시험 전용 fixture 기능으로 옮겼다 (`e3c8db48`). + +### 알려진 제한 + +- 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4). +- 성능 lab(FE-GATE-026)의 기능 라우트 측정(`featureRouteInteractionMs`)은 템플릿에 공개 기능 라우트가 없어 `measured: false`다. 제품 기능이 생기면 잰다. +- `TEMPLATE_FIXTURE` 출처와 `REFERENCE_EXTERNAL_BEARER` 별칭이 플랫폼 코드에 남았다. 쓰는 기능이 없다. +- visual 골든의 픽셀 비교는 색 허용치(`threshold` 0.2)를 넘지 않는 미세한 토큰 변경(예: 어두운 테마 `--color-danger` red-500 → red-600)을 잡지 못한다. 옛 골든도 같았다. + ## 미출시 — `bbde570` → 브랜치 `fix/maturity-review-2026-11-06` 2026-11-06 성숙도 리뷰(`docs/reviews/2026-11-06-maturity-review/`) 조치다. 범위는 아래 절의 끝 `bbde570`(PR B, PR #7)부터 브랜치 `fix/maturity-review-2026-11-06`의 끝까지다. 리뷰 기록 커밋 `302d3a5` 위에 조치 브랜치 9개를 합치고, 합친 빌드로 초기 JS 기록을 다시 적었다(`5cfc3a6`). 기준점 `bbde570`을 빼면 이 절의 해시는 모두 이 범위에 있다. PR B는 아직 `main`에 없다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다.