PR #16은 PR #14(chore/layout-3-merge) 위에 쌓았다. #14가 하네스 PR #13이
들어간 main을 합친 커밋(568f3328)을 받는다. 충돌은 없었다.
630 lines
171 KiB
Markdown
630 lines
171 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/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 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'`).
|
||
|
||
## 미출시 — `8327e221` → 하네스와 작업 매뉴얼
|
||
|
||
2026-11-07 소유자가 정한 Claude Code 작업 환경(하네스)을 백엔드 템플릿과 같은 방식으로 둔다(design-docs `harness/01-harness-design.md` 13절). 루트 지침 `AGENTS.md`(정본)와 `CLAUDE.md`(가져오기), `.claude/`(규칙·스킬·서브에이전트·권한·훅), 작업 매뉴얼 `docs/work/`, 검증 진입점 `scripts/verify.sh`, 장부 `docs/ledger/`다. 제품 코드와 게이트 동작은 바뀌지 않는다.
|
||
|
||
### 먼저 할 일
|
||
|
||
- 루트 `CLAUDE.md`를 더 이상 걸러 내지 않는다. `AGENTS.md`·`CLAUDE.md`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `docs/work/`, `scripts/hooks/`, `scripts/verify.sh`, `scripts/check-work-docs.py`, `scripts/tests/`는 템플릿 계약이라 받는다. 자기 환경에 맞게 바꿀 곳은 `docs/work/operate.md` 4.1절, `docs/work/delegate.md` 4.3절, `scripts/verify.sh`의 환경 변수(호스트, 원격 checkout, 잠금, 로그 폴더)다.
|
||
- `.gitignore`가 `.claude/`를 넷만 남기고 무시한다. 자기 `.claude/` 파일을 추적하고 있었으면 그 줄에 `!` 예외를 더한다.
|
||
- `docs/ledger/estimates.jsonl`은 줄을 비우고 받는다. `.gitattributes`의 `merge=union` 한 줄도 받는다.
|
||
|
||
### 보안·계약 변경
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
| --- | --- | --- | --- |
|
||
| [계약] | 제거 드릴의 문서 사본(`REMOVAL_FIXTURE_DOCUMENT_TARGETS`)에 `AGENTS.md`가 들어간다. `docs/README.md` 1절이 `../AGENTS.md`, `work/`, `work/reference/`를 링크해 `verify:documentation`(FE-GATE-017, FE-GATE-005·020 안의 같은 검사) 범위에 든다. 이 문서들의 경로·script·게이트 ID가 틀리면 merge가 막힌다 | `scripts/lib/removal-fixture.ts`, `docs/README.md`, `tests/unit/template-contract-documents.test.ts` | `98f5c6e7`, `4a21bc79` |
|
||
| [계약] | README 지워도 되는 파일 표에서 `CLAUDE.md` 행이 빠지고 `docs/ledger/estimates.jsonl`(줄을 비운다)이 들어간다. `tests/unit/deletable-history-documents.test.ts`는 `CLAUDE.md`를 더 보지 않는다 | `README.md`, `tests/unit/deletable-history-documents.test.ts` | `98f5c6e7` |
|
||
|
||
### 그 밖의 수정
|
||
|
||
- 작업 매뉴얼 `docs/work/`: README, playbook 여섯, reference 일곱, 근거 `evidence.md`. 개선 매뉴얼 초안(PR #6, main에 없음)과 옛 `CLAUDE.md`의 리뷰 기준을 흡수했다. `SPEC.md`의 공통 완료 기준은 `docs/work/improve.md` 5절로 옮겼다. 처음 읽는 세션으로 시험해 막힌 곳을 고쳤다(`3524d6b0`, `8721be47`, `18ea5e93`).
|
||
- 루트 `AGENTS.md`(꼭 지킬 것 5·지도·검증·라우터)와 `@AGENTS.md`를 가져오는 `CLAUDE.md`, 검사기 `scripts/check-work-docs.py`(`6e8cc963`).
|
||
- `src/`의 계층 폴더마다 지역 규칙 `AGENTS.md`(그 폴더의 할 일·import 금지·게이트)와 그것을 가져오는 `CLAUDE.md`. `docs/reviews/adapters/INVENTORY.md`에 두 행이 생겼다. 소유자가 채우는 빈 양식 `docs/vision.md`·`docs/problem-statement.md`(`93e3c7b1`, `f117a5af`).
|
||
- `.claude/rules/` 다섯, 스킬 `desktop-gates`·`new-feature`, 읽기 전용 서브에이전트 `arch-reviewer`·`verify-app`·`code-simplifier`, 하네스 플러그인 켜기와 실제 `.env` 읽기 차단(`9f859628`).
|
||
- repo 훅 `scripts/hooks/hooks.py`: 편집 직후 경계(`.dependency-cruiser.json` 규칙)·게이트 기준·문서 알림과 턴 끝 desktop 검증 알림. 막지 않는다(`9961ecb1`).
|
||
- `scripts/verify.sh <단계>`: stage·게이트·명령을 `config/ci/gates.json`에서 읽어 desktop에서 CI env로 돈다. `script <이름> -- <인자>`, `exec -- <명령>`, 원격에서 바뀐 파일을 받는 `--apply-back`, 리뷰용 사본 `VERIFY_SNAPSHOT=1`(`c6e42528`, `c50da347`). 장부 `docs/ledger/`(`9d65a41d`).
|
||
|
||
### 알려진 제한
|
||
|
||
- 훅·검사기·`verify.sh` 시험(`python3 -m unittest discover -s scripts/tests`)은 아직 CI workflow가 부르지 않는다. 노트북 `scripts/verify.sh hooks`로 돈다.
|
||
|
||
## 미출시 — `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`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지)을 담는다. 기준점 `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`로 바꾸지 않았으면 계약 조립이 `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to <fixture owner> 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/<dir> has no feature-module.ts; add one, or keep code that is no feature outside src/features`로 실패한다. 템플릿의 local-draft 샘플은 `tests/fixtures/indexeddb-consumer/`로 옮겼다 (`b72cd7d4`)
|
||
7. **음성 타입 fixture를 더한 프로젝트는 첫 줄에 기대를 쓰고 fixture별 tsconfig·script를 지운다.** 템플릿은 `tests/fixtures/typecheck/tsconfig.<이름>.json` 23개와 `check:types:fixture*` script 23개를 `check:types:fixtures` 하나(`scripts/check-type-fixtures.ts`)로 합쳤다. `invalid-*.ts(x)` fixture마다 첫 줄에 `// expect: TS2322`(실패와 그 진단) 또는 `// expect: pass`를 쓴다. 없으면 `check:types:fixtures`가 `` missing `// expect:` first line ``으로 실패한다. 자기 `config/ci/product-gates.json`이 옛 명령 id(`check-types-fixture-*`)를 참조했으면 `check-types-fixtures`로 바꾼다 (`bf485f44`)
|
||
8. **`tsconfig.recipes.json`·`tsconfig.web-worker.json`과 그 script(`check:types:recipes`, `check:types:web-worker`)가 없어졌다.** recipe는 `check:types:test`가 검사한다. 자기 recipe tsconfig를 고쳤으면 그 옵션을 `tsconfig.test.json`에 옮긴다. Web Worker 코드를 들인 프로젝트는 매뉴얼 03 C절 「Web Worker를 들일 때 tsconfig 더하기」대로 tsconfig와 script를 되살린다. `check:types` 끝의 `check-typecheck-inputs.ts`는 tsc에 넘기는 tsconfig의 입력이 0개면 `Typecheck inputs: FAIL (no input files: <tsconfig>)`로 실패한다 (`bf485f44`)
|
||
9. **수동 a11y 기록을 옮긴다.** `artifacts/tests/a11y-manual/<ROUTE_ID>.md` → `docs/accessibility/route-reviews/<ROUTE_ID>.md`(자기 라우트 기록도 `git mv`). `.gitignore`가 더는 `artifacts/` 아래 `.md`를 들이지 않는다. 남기면 `tests/unit/tracked-artifacts.test.ts`가 그 파일을 이름으로 실패시키고, 옮기지 않으면 `verify:documentation`이 `docs/accessibility/route-reviews/ has no record for route IDs: <ids>`로 실패한다 (`79dc945a`)
|
||
10. **루트 `schemas/`를 `config/schemas/`로 옮긴다.** 산출물 스키마는 `config/schemas/artifacts/`, recipe 카탈로그 스키마는 `config/schemas/recipes/`다. 자기 스키마를 `schemas/`에 두었으면 같은 곳으로 옮기고 `$schema` 상대 경로를 고친다. hosting 응답 fixture는 `config/hosting/response-headers.fixture.json` → `tests/fixtures/hosting/response-headers.json` (`79dc945a`)
|
||
11. **자기 루트 항목을 등록부에 더한다.** 루트 항목마다 `config/repository-layout.json`에 종류·역할·읽는 곳을 적는다. 제품이 더한 루트 항목(예: `Dockerfile`, `compose.yaml`, `deploy/`)이 없으면 `tests/unit/repository-layout.test.ts`가 `add an entry with its role to config/repository-layout.json`으로 실패한다. 비밀값 검사 범위에 넣을 항목은 `sets`에 `secret-scan`을 적고 `config/security/secret-scan-policy.json`의 `trackedRoots`에도 같은 이름을 더한다. 둘이 다르면 같은 시험이 실패한다. 루트 경로 목록을 코드에 새로 적지 말고 `selectRepositoryPaths(<집합>)`으로 고른다(매뉴얼 03 E절 R2) (`79dc945a`)
|
||
12. **CI 계약 기준선을 자기 값으로 다시 기록한 프로젝트는 다시 기록한다.** FE-GATE-003 명령이 25개에서 2개로, FE-GATE-009·028의 수동 a11y 기록 산출물 경로와 id가 바뀌었다. 4단계와 같은 명령이다 (`bf485f44`, `79dc945a`)
|
||
13. **CI 계약 기준선 파일이 없어졌다.** `config/ci/contract-baseline.json`, `scripts/update-ci-contract-baseline.ts`, `update:ci-contract-baseline` script를 지웠다(소유자 결정). 위 12단계와 이 절 4단계, 아래 절들의 "기준선을 다시 기록한다"는 이 절까지 받으면 할 일이 없다. 병합에서 자기 기준선 파일이 수정/삭제 충돌이 되면 삭제 쪽을 고른다. 자기 script나 문서가 `update:ci-contract-baseline`을 부르면 지운다 (`f6b2b96c`)
|
||
14. **merge 단계 job 이름이 바뀌었다.** 게이트마다 하나이던 행렬 job(`FE-GATE-NNN / <이름>`)이 `merge / static checks`(`merge_static`), `merge / tests`(`merge_test`), `merge / browser tests`(`merge_browser`) 셋이 됐다. 게이트는 job 안의 단계 이름(`FE-GATE-NNN / <이름>`)으로 남는다. Gitea 브랜치 보호의 필수 검사를 옛 job 이름으로 걸었으면 새 job 셋으로 바꾼다. 증거 업로드 이름도 `FE-GATE-NNN-<run>`에서 `merge-static-<run>`·`merge-test-<run>`·`merge-browser-<run>`으로 바뀌었다 (`0739f26b`)
|
||
|
||
#### 옮긴 뒤 확인
|
||
|
||
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`(5·9·11단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다).
|
||
- 검사기의 음성 fixture 명령 15개와 ungated 검사(`check:ci:gating`)는 PR이 아니라 브랜치 push의 FE-GATE-029(`main_gate`)에서 돈다. 새 시험 파일이나 검증 script를 게이트에 걸지 않으면 PR은 통과하고 main push가 실패한다. 로컬에서는 `corepack pnpm ci:gate FE-GATE-029`로 미리 본다 (`f6b2b96c`).
|
||
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=<id>`의 보고서는 늘 `artifacts/tests/feature-removal-<id>.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` |
|
||
| [계약] **BREAKING** | 음성 타입 fixture 23개를 실행기 하나로 돈다. fixture 첫 줄의 `// expect:`가 기대이고, 판정은 전과 같다(tsc exit 1과 `error TS<code>:`). fixture별 결과와 맞은 진단 줄을 출력한다. `TelemetryPort.emit` 인자를 넓히는 변이(0925/07-05)에서 실패하는 것을 확인했다. recipes tsconfig는 test에 합쳤고 web-worker tsconfig(0파일 검사)는 지웠다(결정 D4). 위 "먼저 할 일" 7·8 | `scripts/check-type-fixtures.ts`, `scripts/check-typecheck-inputs.ts`, `tests/fixtures/typecheck/`, `package.json`, `config/ci/gates.json` | `bf485f44` |
|
||
| [계약] **BREAKING** | 루트 등록부 `config/repository-layout.json`이 생겼다. 루트 경로 목록을 쓰던 7곳(복사 대상, 비밀값 검사 범위, 공급망 시험, 이력 문서 검사, 규모 입력, vite 입력, TS 전용 규칙)이 등록부의 집합을 고른다. `schemas/`·수동 a11y 기록·hosting 응답 fixture를 옮겼다. 위 "먼저 할 일" 9~11 | `config/repository-layout.json`, `scripts/lib/repository-layout.ts`, `config/schemas/`, `docs/accessibility/route-reviews/`, `tests/fixtures/hosting/` | `79dc945a` |
|
||
| [계약] | 저장소 배치 규칙 R1~R10을 매뉴얼 03 E절에 적고, 기계로 볼 수 있는 것을 게이트에 넣었다: R1·R2·R7(파일)·R9 `tests/unit/repository-layout.test.ts`, R3 `tests/unit/tracked-artifacts.test.ts`, R4·R5 `tests/unit/example-feature-rules.test.ts`(이상 FE-GATE-005), R6·R7(문서) `verify:documentation`(FE-GATE-017, 산출물에 `layoutRuleViolations`), R8 FE-GATE-003 | `docs/manual/03-outside-feature-folder.md`, `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts` | `e902e657` |
|
||
| [계약] **BREAKING** | merge 단계 job 14개(게이트마다 행렬 하나)를 셋으로 합쳤다. job마다 설치를 한 번 하고 게이트를 차례로 돈다. 앞 게이트가 실패해도 다음 게이트가 돈다(`if: ${{ !cancelled() }}`). release 단계는 세 job을 모두 기다린다. 위 "먼저 할 일" 14 | `config/ci/gates.json` `jobs`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `0739f26b` |
|
||
| [계약] **BREAKING** | 새 단계 `main`(`MAIN_READY`, 승격을 막지 않음)과 게이트 FE-GATE-029 `checker-self-tests`. FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거, `check:ci`의 ungated 검사(`check:ci:gating`으로 뗌)를 옮겼다. merge 단계 명령 참조 64 → 49. 음성 타입 fixture(`check:types:fixtures`)는 src 타입 계약 시험이라 merge에 남겼다. CI 계약 기준선 파일은 지웠다. 위 "먼저 할 일" 13 | `config/ci/gates.json`, `scripts/check-ci-gating.ts`, `scripts/lib/promotion-readiness.ts` | `f6b2b96c` |
|
||
|
||
### 그 밖의 수정
|
||
|
||
- `scripts/check-*.ts` 30개를 ESLint 규칙·의존 규칙·시험으로 옮길 수 있는지 판정한 표를 `docs/operations/ci-script-assessment.md`에 남겼다. 코드는 바꾸지 않았다 (`3ce77d9e`).
|
||
- 정리 3단계에서 문서가 가리키던 옛 명령·경로(`check:types:fixture:*`, `check:types:recipes`, a11y 기록과 스키마 경로)를 새 이름으로 바꿨다 (`bf485f44`, `79dc945a`).
|
||
- 정리 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`).
|
||
- 라우트 런타임 음성 fixture(`tests/fixtures/typecheck/invalid-route-runtime.ts`)는 라우트 하나만 뺀다. 빠진 라우트 수에 따라 TS2739와 TS2740으로 갈리던 진단이 TS2741 하나가 됐고 FE-GATE-003의 기대 진단도 바꿨다. 라우트가 3개로 줄자 옛 기대(TS2740)가 어긋났다 (`e47a0ab2`).
|
||
|
||
### 알려진 제한
|
||
|
||
- 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4).
|
||
- R2 검사는 등록부를 쓰는 7곳만 본다. 그 밖에 루트 이름 둘 이상을 담은 문자열 배열이 약 20곳 남았다(예: `tests/e2e/support/fixture-builds.ts`의 복사 제외 목록, `scripts/check-test-evidence.ts`의 playwright 설정 목록). 뜻이 다른 목록이라 이번에 옮기지 않았다.
|
||
- R5는 문자열 검색이라 샘플 ID나 라우트 경로를 조립해 쓰는 시험은 놓친다.
|
||
- CI 재편(merge job 셋, main 단계)은 desktop에서 게이트 명령으로 확인했다. Gitea runner에서 새 workflow가 도는지는 Actions를 켠 뒤 확인한다.
|
||
- 성능 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`에 없다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다.
|
||
|
||
아래 절은 그 범위 끝(`bbde570`)의 상태다. 아래 절이 지금 값으로 적은 것을 이 범위가 바꾼 경우, 아래 절은 그대로 두고 이 절에 적었다. 예외는 처음부터 틀리게 적은 문장이다. 아래 절 "먼저 할 일" 1~3단계의 대상·바뀌는 값·증상(1106/14-01)과 2단계의 descriptor 없는 쓰기·테스트 fixture 길(1106/09-01)은 아래 절에서 바로 고쳤다. 아래 절을 이미 읽었으면 그 세 단계를 다시 읽는다.
|
||
|
||
### 먼저 할 일 (BREAKING)
|
||
|
||
아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
|
||
|
||
#### 옮기는 법
|
||
|
||
1. **HTTP 스키마 행에 `direction`·`unknownFieldPolicy`를 적는다.** descriptor의 입력·응답·실패 검증기로 쓰이는 스키마의 FE-REG-SCHEMA 행이 둘 중 하나를 빼면 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 `row states no direction, used as <방향>`이나 `row states no unknownFieldPolicy, validator <탐침 결과>`로 실패한다. 행이 아예 없으면 같은 메시지와 `no FE-REG-SCHEMA row`가 나온다. 라우트에만 쓰는 행은 그대로 둬도 된다. 객체가 아닌 본문의 검증기(`responseBody: "NONE"` 출력의 `z.undefined()` 등)는 탐침이 정책을 판정할 수 없어 `direction`만 요구한다. memento-web이 2026-11-03 조치 절 "옮기는 법" 5단계로 더하는 43행도 두 칸을 적는다 (1106/07-02)
|
||
2. **`src/presentation/i18n/catalog.ts`를 고친 제품은 `form.resendLater`를 한국어·영어 두 catalog에 더한다.** 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전에 거절되면(짝 백엔드 표의 400 `VALIDATION_FAILED`·`IDEMPOTENCY_KEY_INVALID`는 빼고) 폼이 이 문구를 보인다. 키가 없으면 그 자리에 `common.unavailable` 문구가 나오고, 한 언어에만 있으면 `check:i18n`이 실패한다 (1106/03-01)
|
||
3. **디자인 토큰 CSS를 고친 제품은 `src/presentation/design-system/tokens/component.css`의 `--dialog-backdrop-weight`·`--dialog-backdrop`·`--dialog-backdrop-on-surface`를 가져온다.** `primitives.css`의 `.ui-dialog::backdrop`과 `:root:has(.ui-dialog[open])`이 이 토큰을 읽는다. 빠지면 modal 가림막이 투명해지고, 그것을 잡는 검사는 없다. memento는 이 파일을 고쳤다 (1106/08-03)
|
||
4. **IDEMPOTENT로 선언한 쓰기가 두 번 적용해도 결과가 같은지 확인한다.** `...commandMutationIdentity(<descriptor>)`로 받은 정책은 이제 `resendSafe`를 싣는다. 그래서 IDEMPOTENT 쓰기는 결과 불명 뒤 재전송 버튼이 그려지고, 같은 입력 저장이 `UNKNOWN_EFFECT_PENDING`으로 거절되지 않는다. 백엔드가 중복을 막지 못하는 쓰기를 IDEMPOTENT로 적었다면 사용자가 다시 보내 같은 항목이 둘 생길 수 있다(매뉴얼 02 결정표 3절). memento-web의 IDEMPOTENT 쓰기는 아래 절 2단계로 옮기면 여기에 든다. `commandMutationIdentity` 결과를 `toEqual`로 비교하던 테스트는 `resendSafe`를 더한다 (1106/03-03)
|
||
5. **CI 계약 기준선을 자기 값으로 다시 기록한 제품은 받은 뒤 다시 기록한다.** FE-GATE-027의 명령 순서가 바뀌어 `gateShapeSha256`이 바뀌었다. `CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline`. 다시 기록하지 않으면 `check:ci`가 기준선 차이로 실패한다 (1106/13-01)
|
||
6. **bounded poll 조합 코드가 있는 제품만: `createBoundedPollCoordinator`가 descriptor 타입을 따라간다.** 타입 인자 없이 부르면 `operation`에서 `Operation`을 추론하고, `execute`의 `input.operation`이 그 descriptor 타입이 된다. 실행기 호출의 입력이 descriptor 입력 타입과 맞지 않으면 `check:types`가 실패한다. `outcome.value`를 겹치지 않는 타입으로 단언하던 코드도 실패할 수 있다. 입력을 맞춘다. 옛 타입으로 두려면 `createBoundedPollCoordinator<Value, BoundedPollOperation>`으로 적는다. `Value`만 적은 호출은 전과 같다. 두 다운스트림의 지금 코드(2026-11-06에 읽음)는 이 함수를 부르지 않는다 (1106/04-02)
|
||
|
||
#### 옮긴 뒤 확인
|
||
|
||
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `test:unit`(1단계), `check:i18n`(2단계), `check:ci`(5단계), `check:types`(6단계), `test:a11y`(FE-GATE-009. 한 자원을 읽는 상세 라우트에 실패 화면 기록이 없으면 `a11y.json not written:`으로 실패한다), `check:bundle`(셸에 `RUN_OUTPUT_ROOT`가 있으면 멈춘다. 지우고 돈다).
|
||
2. 제품 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)은 본문에 그 기능 ID를 적힌 그대로 한 이름으로 적은 Playwright spec을 잔여로 센다. `-`가 없는 한 단어 ID는 spec 본문에서 찾지 않는다.
|
||
3. 시각 골든: `base.css`·`primitives.css`를 받은 제품은 열린 modal을 찍은 자기 골든을 다시 찍는다(`corepack pnpm test:visual:update`). 새 시각 검사 `tests/visual/scrollbar-gutter.visual.spec.ts`는 템플릿 셸의 메뉴 버튼과 `/not-found`를 쓴다. 셸을 바꾼 제품은 그 spec을 자기 셸에 맞춘다. 제품 셸에서는 돌려 보지 않았다.
|
||
4. 배포가 있는 제품: `/service-worker.js`를 redirect 뒤에 주는 호스트는 FE-GATE-019가 FAIL이다. 그런 호스트에서는 지금도 워커 등록·업데이트·kill switch가 실패한다.
|
||
5. 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)이 충돌하면 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`를 다시 돌려 푼다.
|
||
|
||
### 보안·계약 변경
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | FE-GATE-027이 `scan:dependency-advisories`를 `check:release-admission`보다 먼저 돈다. 공개 대상 승인이 거절된 run에도 advisory 기록(`artifacts/security/dependency-advisories.json`)이 생긴다. FE-GATE-015가 실패하면 FE-GATE-027이 돌지 않아 기록이 없다. 승인 판정과 gate 결과는 그대로이고, 거절되는 run은 scan 시간(상한 120초)만큼 늦게 끝난다. 생성 workflow는 그대로다. gate 모양 기준선 `gateShapeSha256`을 다시 기록했다. 위 "먼저 할 일" 5단계 (1106/13-01) | `config/ci/gates.json`, `config/ci/contract-baseline.json`, `scripts/scan-dependency-advisories.ts`, `docs/operations/ci-quality-gates.md` | `c5ab7a3` |
|
||
| [계약] | FE-GATE-019 live probe가 `/service-worker.js`를 같은 origin 안 redirect 뒤에 준 호스트를 FAIL로 본다(`serviceWorker` surface의 `redirect` 행, `response.redirected`나 `opaqueredirect`). 브라우저는 워커 스크립트를 redirect mode "error"로 받는다. `index`·`appRoute`의 redirect는 전처럼 받는다. 위 "옮긴 뒤 확인" 4 (1106/06-01) | `scripts/lib/hosting-probe.ts`, `docs/operations/release-cache-rollback.md`, `docs/operations/browser-file-storage-recovery.md` | `2a78169` |
|
||
| [계약] | `check:bundle`의 `generate-supply-chain.ts`·`check-bundle.ts`가 `RUN_OUTPUT_ROOT`가 비어 있지 않고 `.`도 아니면 변수 값과 이유를 적고 exit 1로 멈춘다. 빌드는 그 경로 아래에 쓰는데 두 스크립트는 checkout의 `dist`·`artifacts/`를 읽어서, 예산을 넘는 새 빌드 대신 이전 빌드로 PASS했다. `ci:gate -- FE-GATE-012`도 check-bundle 단계에서 멈춘다 (1106/12-02) | `scripts/lib/run-isolation.ts`, `scripts/check-bundle.ts`, `scripts/generate-supply-chain.ts`, `docs/testing/frontend-platform-testing-strategy.md` | `68fde02` |
|
||
| [계약] | `test:a11y`(FE-GATE-009)의 report(`scripts/write-a11y-report.ts`)가 설치된 descriptor로 한 자원을 읽는 라우트를 찾는다. 로그인이 필요한 라우트의 `paramsSchema`가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마인 경우다. 그 라우트에 실패 화면 기록(`artifacts/tests/a11y-data-state/`)이 없으면 `a11y.json not written:`으로 실패하고 `a11y.json`을 쓰지 않는다. 접근성 spec의 라우트 test는 시작할 때 자기 기록을 지운다. `paramsSchema`가 GET 입력과 다른 상세 라우트는 전처럼 기록만으로 정해진다. 그 GET을 부르지 않는 페이지의 라우트(하위 항목 작성 폼 등)가 GET 입력 스키마를 `paramsSchema`로 쓰면 이 검사가 실패한다. 그 라우트에 자기 `paramsSchema`를 따로 둔다 (1106/11-01) | `scripts/lib/a11y-data-state.ts`, `scripts/write-a11y-report.ts`, `tests/e2e/accessibility.spec.ts` | `9c4cddc`, `95141f1` |
|
||
| [계약] | `tests/unit/schema-metadata-policy.test.ts`가 descriptor의 입력·응답·실패 검증기로 쓰인 스키마 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 실패한다. 전에는 건너뛰어서, 응답 DTO를 strict로 바꿔도 `check:registries`와 `test:unit` 어느 쪽도 보지 않았다. 템플릿 HTTP 행과 생성기가 쓰는 행은 이미 두 칸을 적는다. 탐침이 객체에 닿지 못하는 검증기(객체가 아닌 본문)는 `direction`만 요구한다. 위 "먼저 할 일" 1단계 (1106/07-02) | `tests/unit/schema-metadata-policy.test.ts`, `docs/manual/01-add-a-feature.md`, `docs/manual/reference/errors.md` | `e7b1b01`, `efe11f1` |
|
||
| [계약] | 제품 기능 제거 드릴의 `tests` 잔여에, 본문이 기능 ID나 폴더 이름을 적힌 그대로(대소문자 구분) 한 이름(앞뒤가 `[A-Za-z0-9_-]`가 아님)으로 적은 Playwright spec(`*.spec.[cm]?[jt]sx?`)이 든다. `-`가 든 이름만 찾는다. `messages`·`status` 같은 한 단어 ID는 템플릿 spec이 평범한 단어로 쓰므로 찾지 않는다. vitest는 spec을 돌지 않아 `test:all`도 잡지 못했다. vitest 테스트 본문은 전처럼 보지 않는다. 매뉴얼 01 11단계와 `errors.md`의 판정 문장을 고쳤다 (1106/16-01) | `scripts/lib/feature-residue.ts`, `docs/manual/` | `af3344b`, `eb03dab` |
|
||
| [계약] | KEYED 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전 거절(429, 401, 403, 503 `RATE_LIMIT_*`, 422 `IDEMPOTENT_REQUEST_MISMATCH`, 기능이 선언한 code)이나 보내기 전 실패(`NOT_STARTED`)로 끝나면, 훅이 결과 불명과 intent·키를 남긴다. 전에는 그 판정을 논리 요청 전체의 판정으로 써서 다음 저장이 새 키로 나갔다. 실패는 그대로 돌려주고, `Retry-After`는 다음 재전송의 대기 시각이 되고, 낙관적 층은 되돌리지 않고 불확실로 둔다. 폼은 결과 불명 화면(확인·다시 보내기)을 그대로 두고 `form.resendLater` 문구로 feedback에 포커스를 옮긴다. 같은 요청이 매번 받는 거절은 첫 요청도 거절됐다는 뜻이라 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 받는다. 짝 백엔드 표의 code만 그렇게 읽는다. 지금은 400 `VALIDATION_FAILED`(필드 목록이 있든 없든)와 400 `IDEMPOTENCY_KEY_INVALID`다(`isRefusedOnEveryAttempt`). 기능의 `mapProblem`이 정한 kind(`VALIDATION_REJECTED`)는 보지 않는다. 기능 code는 상태 규칙일 수 있다. 그래서 백엔드의 `VALIDATION_FAILED`는 요청 내용만 보는 검사여야 한다(계약 문서 6.1절). 처음 보낸 요청의 `NOT_APPLIED`와 재전송의 성공은 전처럼 정리한다. 메인 세션 결정 D10과 그 보충 둘이다. 위 "먼저 할 일" 2단계 (1106/03-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/contracts/errors.ts`, `src/presentation/i18n/catalog.ts`, `docs/operations/api-contract-and-server-state-recovery.md`, `docs/architecture/backend-api-and-server-state-contract.md` | `2568587`, `80e7f1d`, `b41990c`, `6142cc8` |
|
||
| [계약] | `commandMutationIdentity`가 `resendSafe`(`retrySemantics`가 `KEYED`나 `IDEMPOTENT`)도 돌려주고, `BoundMutation`에 선택 칸 `resendSafe?`가 생겼다(추가만). 결과 불명 뒤 재전송 버튼과 같은 입력 재제출 거절(아래 절 0929/03-03 행)이 키 유무 대신 "키가 있거나 `resendSafe`"를 본다. 그래서 IDEMPOTENT 쓰기도 다시 보낼 수 있다. 그 재전송도 위 1106/03-01 행의 규칙을 따른다. 기능 분류기가 적용 안 됨으로 읽는 404·412 같은 code는 첫 요청이 이미 적용됐을 때 흔한 답이라 결과 불명을 남기고, 짝 백엔드 표의 두 400만 푼다. 칸이 없는 손 정책과 NEVER는 전과 같다. 위 "먼저 할 일" 4단계 (1106/03-03) | `src/contracts/server-state.ts`, `src/presentation/adapters/query/application-query.ts`, `src/application/view-models/async-state.ts`, `docs/manual/` | `815ea58`, `80e7f1d`, `b41990c` |
|
||
| [계약] **BREAKING** | `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에 타입 인자 `Operation extends BoundedPollOperation = BoundedPollOperation`이 생겼다. `operation`과 `execute`의 `input.operation`이 그 타입이라, 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다. 런타임 동작은 같다. realtime 설계 9.2절에 V3 실행기 결과 kind마다 poll 결과(kind, retryable, `retryAfterMs`)를 적은 표가 생겼다. 표대로 조합하면 401·403은 요청 한 번으로 lease를 끝낸다. 표는 조합 코드가 따를 규칙이고 강제하지 않는다. 위 "먼저 할 일" 6단계 (1106/04-02) | `src/adapters/realtime/polling/bounded-poll-coordinator.ts`, `src/application/policies/bounded-polling.ts`, `docs/architecture/realtime-events-web-push-and-bounded-polling.md` | `6f06e77` |
|
||
| [계약] | `PublicResponseCacheAdminPort.activateRelease`의 옵션에 `replaceUnreadablePointer?: boolean`이 생겼다(추가만). `true`면 active pointer 본문을 읽지 못한 이유와 상관없이, 손상 pointer처럼 검증된 후보로 rollback 목록 없이 덮어쓴다. 기본값은 전처럼 멈춤이다. 켜면 일시 오류에서도 rollback 목록을 잃고, 다음 cleanup이 새 활성 release 밖의 owned release cache를 모두 지운다. 언제 쓰는지는 운영 문서에 있다 (1106/02-01) | `src/application/ports/browser-file-storage/cache-storage-ports.ts`, `src/adapters/cache-storage/public-response-cache-adapter.ts`, `docs/operations/client-cache-and-storage-recovery.md`, `docs/architecture/browser-file-and-origin-storage.md` | `4cef2a2` |
|
||
| [계약] | 열린 modal의 가림막이 스크롤바 자리(`scrollbar-gutter: stable`, 1105/15-05)까지 덮는다. modal이 열린 동안 `:root:has(.ui-dialog[open])`이 root 배경을 가림막을 페이지 바탕에 겹친 불투명 색(`--dialog-backdrop-on-surface`)으로 바꾸고, `body`가 페이지 바탕(`--color-surface`)을 직접 칠한다. `component.css`에 토큰 셋(`--dialog-backdrop-weight` 55%, `--dialog-backdrop`, `--dialog-backdrop-on-surface`)이 생겼다. 새 시각 검사 `tests/visual/scrollbar-gutter.visual.spec.ts`가 스크롤바를 숨기지 않은 Chromium에서 그 자리 색을 본다. compact 골든 1장(`app-shell-compact-pseudo-drawer`)을 다시 찍었다. header 띠는 남는다(디자인 시스템 문서 8.2절). 위 "먼저 할 일" 3단계 (1106/08-03) | `src/presentation/design-system/tokens/component.css`, `src/presentation/styles/theme/base.css`, `src/presentation/styles/theme/primitives.css`, `tests/visual/` | `7625dc4` |
|
||
| [계약] | 초기 JS 기록(`initialJavascript`)을 이 범위를 합친 빌드로 다시 적었다. 204,111 → 204,193 B, 초기 파일 27개 그대로, 기능 하나 768 → 751 B, 새 context 218 → 245 B다. 예산 `initialJsGzipBytes`는 206,848 B 그대로다(결정 D9). 폭의 근거(드릴 측정값에 기능 하나의 상한 1 KiB를 더해 KiB로 올림)와 되돌림 규칙(재검토 조건마다 드릴을 다시 재고 204,800 B 이하이면 같은 규칙으로 내린다)을 운영 문서에 적었다. 사용자가 이 결정을 뒤집을 수 있다. 합친 뒤 여유는 템플릿 2,655 B, 생성 기능 둘을 더한 FE-GATE-020 드릴(205,541 B, CI env) 1,307 B다 (1106/15-01) | `config/scale/feature-shape-ceilings.json`, `docs/operations/performance-evidence.md` | `1eaa644`, `5cfc3a6` |
|
||
|
||
### 그 밖의 수정
|
||
|
||
- 폼·화면: `useAppForm`의 `settleApplied`는 제출한 값이 없으면(저장 중에 떠났다 다시 마운트한 폼) 결과를 성공으로 보이고, 포커스를 잃었으면 feedback 자리로 옮긴다. 화면의 값과 기준값은 그대로 둔다. 그 값은 보낸 적이 없어서, 입력이 남아 있으면 이탈 확인도 남는다. 참조 작성 폼은 자기가 시작하지 않은 저장이 끝나면 "목록을 새로 불러와 확인" 링크를 둔다 (1106/08-01, `fbaaaee`, `145be2d`). 생성 기능 작성 페이지(`create:feature --with-create`)는 마운트된 동안만 저장 뒤 상세로, "변경됨으로 확인" 뒤 목록으로 옮긴다. 이미 생성한 기능은 바뀌지 않는다. 그 `<base>-create-page.tsx`에는 `scripts/create-feature-write-slice.ts`의 `mounted` ref를 손으로 옮긴다 (1106/08-02, `116cbf3`)
|
||
- HTTP: Fileserver 업로드의 202 `REJECTED` 실패(`FILE_REJECTED`)가 성공 Envelope의 `meta.traceId`를 `traceId`로 싣는다. 거절 이유는 여전히 없다(알려진 제한) (1106/01-01, `7395c78`)
|
||
- realtime: reconnect coordinator는 던지는 `attempt`·`waitClosed`를 전처럼 `PROVIDER_UNAVAILABLE`(retryable)로 재시도하고, 던지는 `classifyClosed`·`confirmTransportBarrier`는 `PROTOCOL_MISMATCH`로 끝낸다. 이 규칙을 타입 주석과 realtime 설계 13.1절에 적고 테스트로 고정했다. endpoint 같은 설정 검사는 `attempt` 밖, 조합 코드가 transport를 만들 때 한다. 동작은 같다 (1106/04-01, `0438c3f`)
|
||
- 계약 문서: 6.1절의 rate-limit 503 뒤 IDEMPOTENT 쓰기는 `retryBudget` 안에서 `Retry-After`(5초 이하) 뒤 다시 보낸다고 적었다. 아래 절 1105/03-02 행과 코드는 이미 그렇다. 통합 테스트가 그 경로를 고정한다 (1106/03-02, `8156d85`). 4.1절의 bulk 엔드포인트는 `responseEnvelope: "NONE" as const`로 별도 계약 기여에 둔다. 전에는 "`responseEnvelope`를 빼고"라 적어, 따르면 `check:types`나 조립이 실패했다 (1106/07-01, 1106/16-02, `c6c86dc`)
|
||
- 문서: 저장소 설계 문서와 VD-13이 registry 키 목록 대신 `STORAGE_REGISTRY`를 가리킨다 (1106/05-01, `02a761f`). 매뉴얼 01 7단계의 descriptor 없는 쓰기와 테스트 fixture의 operation ID 길(아래 절 "먼저 할 일" 2단계도) (1106/09-01, `06357e9`). 아래 절 "먼저 할 일" 1~3단계의 대상·바뀌는 값·증상 (1106/14-01, `2f0f2bb`). 성능 문서의 초기 파일 상한 문장이 템플릿 파일 수를 기록에서 읽는다 (1103/15-02, `43ed03d`)
|
||
- CHANGELOG·리뷰 기록: 머리말에 해시를 다시 쓴 뒤의 해시 대조 단계. D7 커밋 본문의 다시 짓기 전 해시 둘은 2026-11-05 리뷰 README의 D7 행에 맞는 해시로 적었다 (1106/14-02, 1105 README 16.2, `ddc6353`)
|
||
- 테스트: Service Worker marker 읽기 상한 test가 상한 5초를 1 ms라도 넘기면 실패한다. 전에는 20초까지 통과했다 (1106/06-02, `1f4b929`). run 격리의 capabilities 설정 검사 8개를 `tests/unit/playwright-capabilities-run-isolation.test.ts`로 옮겼고, browser-file-storage 제거 드릴이 그 설정과 이 파일을 이름으로 함께 지운다. 그 런타임을 손으로 지운 제품은 이 파일도 지운다. 빌드 입력 목록 검사는 측정 스크립트를 그 소유 기능이 설치돼 있을 때 읽는다 (1106/10-01, `a135fa8`). 제거 드릴의 문서 테스트 목록에는 문서를 읽는 테스트만 둔다. 아래 절 1105/03-01 행이 적은 `tests/unit/backend-contract-pin.test.ts`의 6.1절 대조는 `tests/unit/backend-contract-pin-document.test.ts`로 옮겼고, pin 테스트의 나머지 14건은 모든 드릴에서 돈다. `feature-tracked-files.test.ts`의 문서 무관 1건은 `feature-tracked-file-rewrites.test.ts`로 옮겼다. 목록 검사는 주석이 아닌 코드의 문자열을 본다 (1106/12-01, 1106/10-02, `b8535f8`)
|
||
|
||
### 알려진 제한
|
||
|
||
이 절의 범위 끝에서 사실인 것만 적었다. 아래 절의 알려진 제한 중 이 범위가 바꾼 것과 새로 생긴 것만 적고, 나머지는 아래 절 그대로다.
|
||
|
||
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다.
|
||
- 백엔드로 넘김: Fileserver는 검증기가 거절한 업로드(REJECT)를 202 `REJECTED` 성공 답으로 주고, 판정 code(`FILE_TOO_LARGE`, 제품 검증기 code 등)는 파일 레코드의 `lastErrorCode`에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다. 요청은 둘 중 하나다. REJECT를 422 실패 Envelope(`error.code` = 판정 code, `retryable: false`)로 답하거나, 202 답에 판정 code 칸을 더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 `traceId`를 싣고 `NOT_APPLIED`로 읽으며, 그때 `FILE_REJECTED` 분기를 지운다 (1106/01-01).
|
||
- 일부: 실행 격리. `check:bundle`은 이제 `RUN_OUTPUT_ROOT`가 있으면 멈춘다. 같은 모양일 수 있는 `check:app-build-input:bundle`, `check:optional-recipes --require-dist`, release candidate 조립은 보지 않았다 (1105/12-04, 1106/12-02).
|
||
- 일부: poll 조합 코드가 `input.operation`을 무시하고 다른 descriptor를 넘기는 것은 여전히 막지 않는다. 이제 `input.operation`이 descriptor 타입을 가져 그 길을 쓰기가 더 쉽다. 9.2절 표는 규칙이고, 템플릿은 poll `execute` 기본 구현을 주지 않는다 (1103/04-01, 1106/04-02).
|
||
- 일부: reconnect `attempt` 안에서 연결을 만드는 조합 코드는 설정 오류가 여전히 서버 장애로 보인다. 규칙만 적었다 (1106/04-01).
|
||
- 일부: 결과 불명 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남고, 다시 보내기는 `Retry-After`(상한 5초)를 기다린다. 폼 밖에서 부른 같은 입력 재저장이 `NOT_APPLIED`로 끝나면 훅은 키를 지키지만 폼은 retry-later를 보인다. 기능이 선언한 결정적 거절(생성 기능의 400 `<FEATURE>_INVALID`)과 problem details를 읽는 기능의 422 입력 검증(참조 기능은 모든 422를 필드 오류로 읽는다)은 어느 쪽인지 알 수 없어 재전송 뒤에도 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다 (1106/03-01).
|
||
- 일부: 기능 제거 드릴은 route ID나 URL만 적은 spec과 한 단어 기능 ID만 적은 spec을 잡지 못하고, 다운스트림 spec이 다른 이유로 `-`가 든 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 부분 문자열 검색의 거짓 양성과 dist 빌드 잔여 검사는 그대로다 (1106/16-01, 1105/16-04).
|
||
- 일부: `:has()`를 모르는 브라우저(Firefox 121 미만 등)는 전처럼 가림막 옆에 띠가 남는다. 오른쪽 drawer, RTL, Firefox, WebKit은 보지 않았다 (1106/08-03).
|
||
- 일부: Cache Storage release marker 본문이 계속 읽히지 않으면 stage가 marker를 다시 쓰지 않는다. `replaceUnreadablePointer`는 active pointer만 푼다 (1105/02-02, 1106/02-01).
|
||
- 일부: 초기 JS 예산의 폭과 되돌림 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는 테스트는 없다 (1106/15-01).
|
||
- 일부: CHANGELOG·커밋 본문의 해시 대조는 사람이 하는 단계다(머리말) (1106/14-02).
|
||
|
||
## 미출시 — `409d72e` → 브랜치 `fix/maturity-review-2026-11-05-b`
|
||
|
||
2026-11-05 성숙도 리뷰(`docs/reviews/2026-11-05-maturity-review/`) 조치다. 범위는 `main` `409d72e`(아래 절의 묶음을 합친 커밋)부터 브랜치 `fix/maturity-review-2026-11-05-b`(PR B)의 끝까지다. 앞의 세 조치(`9655958`, `629c713`, `397664e`)는 PR A(PR #5, 브랜치 `fix/maturity-review-2026-11-05`)에 있고, PR B는 그 위에 쌓였다. 기준점 `409d72e`를 빼면 이 절의 해시는 모두 이 범위에 있다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다.
|
||
|
||
### 먼저 할 일 (BREAKING)
|
||
|
||
아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
|
||
|
||
#### 옮기는 법
|
||
|
||
1. **HTTP descriptor마다 `responseEnvelope`를 적는다.** `InstalledHttpContract`의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web)는 `"NONE" as const`, 짝 백엔드 Envelope는 `"ENVELOPE_V1" as const`다. TechLog 백엔드는 Envelope로 감싸지만 출력 검증기(`envelopeData`)가 Envelope를 직접 벗기므로 `"NONE"`이다. `"ENVELOPE_V1"`로 바꾸면 실행기가 한 번 벗긴 `data`를 검증기가 다시 벗기려다 모든 응답이 실패한다. 빠뜨리면 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 `check:types`가 실패한다. 두 제품의 descriptor helper처럼 `as`로 단언한 descriptor는 빠뜨려도 `check:types`가 잡지 않는다(타입 규칙으로 읽은 추론, 돌려 보지 않았다). 그런 descriptor는 직접 찾아 적는다. 빠진 값은 조립이 `NONE`으로 읽어 런타임 동작은 같다 (1103/16-01)
|
||
2. **뮤테이션 정책의 operation ID를 손으로 적지 않는다.** `BoundMutation.operationId`는 brand 타입 `MutationOperationId`다. `operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<descriptor>)`로 바꾼다. 문자열로 적으면 `check:types`가 실패한다. 이 함수는 `requiresIdempotencyKey`를 descriptor의 `retrySemantics`가 `KEYED`일 때만 `true`로 다시 계산한다. 손으로 적은 값이 descriptor와 다른 정책은 동작이 바뀌고, `check:types`는 이것을 잡지 않는다. 예: tech-log 관리 쓰기는 정책이 `true`, descriptor가 `NEVER`라 `false`가 되고, 키가 없으면 던지는 자기 가드 때문에 저장마다 `TypeError`다(지금도 실행기가 키를 실은 `NEVER` 요청을 `UNEXPECTED_IDEMPOTENCY_KEY`로 거절하는 모양이다. 코드로 읽은 추론이다). 바꾸기 전에 정책마다 손으로 적은 값과 descriptor의 `retrySemantics`를 맞춰 본다. V3 descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "<ID>", method: "POST", retrySemantics: "KEYED" } })`. 멱등 키가 필요 없으면 `"NEVER"`다. 대조할 descriptor가 없으니 이 ID의 오타는 어느 검사도 잡지 않는다. 테스트 fixture는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("<ID>")`를 쓴다. 문자열 ID는 `check:types:test`에서 실패한다. 매뉴얼 01 7단계 (1103/16-05)
|
||
3. **`refusedBeforeWrite`에서 플랫폼 code를 뺀다.** 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(`PLATFORM_CODES_POSSIBLY_AFTER_WRITE`: `BAD_PARAMETER`, `MAPPING_FAILED`, `DB_*` 8개, `LOCK_ACQUISITION_TIMEOUT`, Fileserver code)를 적으면 그 기능 실행부를 적재할 때 계약 조립이 거절한다. 부팅은 기능의 계약 기여를 조립하지 않으므로 앱은 뜨고, 그 기능 라우트에 처음 들어갈 때와 플랫폼 구성 화면에서 실패한다. CI에서는 모든 기능 실행부를 조립하는 `test:unit`과 `check:registries`가 먼저 잡는다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01)
|
||
4. **bounded poll의 `execute`는 실패를 던지지 않고 결과로 돌려준다.** 던지면(lease 자신의 abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. 네트워크 실패를 throw로 내던 `execute`는 retryable `PROVIDER_UNAVAILABLE` 결과로 바꾼다. 실행기에는 클로저의 descriptor 대신 `input.operation`(생성 때 검사한 descriptor)을 넘긴다 (1105/04-02, 1103/04-01)
|
||
5. **`artifacts/tests/a11y.json`을 읽는 도구는 schemaVersion 2를 읽는다.** `scope`는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새 `notChecked` 배열에 `{ routeId, reason }`으로 들어간다. 설치된 라우트 전체는 둘을 합친 것이다 (1103/11-01)
|
||
6. **제품 scope participant의 `label`은 소문자 kebab-case 48자 이하로 쓴다.** 아니면 조립이 `TypeError`로 멈춘다 (1105/02-01)
|
||
7. **레시피를 복사한 제품은 복사본을 고친다.** 쿠키 세션 모드는 `createSessionCookieRejectionHandler(context)`를 `composeProduct`의 `onCredentialRejected`에 잇는다. 잇지 않으면 서버 401이 템플릿 세션에 닿지 않는다(매뉴얼 04 4.3) (1105/09-02). OIDC PKCE owner는 sign-in transaction 키를 registry 행 `AUTH_REDIRECT_TRANSACTION`의 `physicalKey`에서 가져온다. 키 글자는 같다 (1105/05-01)
|
||
8. **Service Worker를 켠 제품은 `blockers`·`observe`를 `composeProduct`의 선택 칸 `serviceWorker`로 옮긴다.** 템플릿 파일 `src/bootstrap/create-runtime-composition.ts`는 템플릿 것으로 되돌린다 (1103/09-05)
|
||
9. **제품 merge 게이트(`config/ci/product-gates.json`의 `mergeGates`)가 있는 제품은 `corepack pnpm generate:ci-workflow`를 다시 돈다.** `release_gate`가 `product_merge_gate`도 기다리는 줄이 생긴다. 다시 돌리지 않으면 `check:ci`가 실패한다 (1105/13-02)
|
||
10. **기능 안 `adapters/` 밖에서 `src/adapters`를 import하는 파일은 `adapters/`로 옮긴다.** 아니면 `check:architecture`가 `feature-and-app-roots-do-not-reach-adapters`로 실패한다 (0929/12-03)
|
||
|
||
#### 옮긴 뒤 확인
|
||
|
||
1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:types`(1·2단계), 모든 기능 실행부를 조립하는 `test:unit`·`check:registries`(3단계), 앱을 조립하는 `test:unit`·`test:component`(6단계), `check:ci`(9단계), `check:architecture`(10단계), `check:registries`(응답 스키마 행을 `REJECT_UNKNOWN`으로 좁힌 변경은 이제 breaking).
|
||
2. 한 checkout에서 브라우저 테스트 실행 두 개를 함께 돌리려면 실행마다 `TEST_RUN_ID`를 다르게 준다. 게이트(`ci:gate`)와 증거 검사는 기본 경로만 읽으므로 한 checkout에서 하나씩 돈다.
|
||
3. 배포가 있는 제품: 자산을 redirect로 주는 호스트는 FE-GATE-019가 FAIL이다.
|
||
|
||
### 보안·계약 변경
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | FE-GATE-013(`test:system`) 러너는 비특권 user namespace와 network namespace를 허용해야 한다(provider 샌드박스의 `bwrap --unshare-net`). 사전 점검이 bwrap을 실제로 띄워 보고, 허용하지 않는 호스트에서는 provider 테스트를 돌리기 전에 이유·호스트 설정·고치는 방법을 적고 멈춘다. 요구는 러너 요구 목록, gate 정의의 `hostRequirements`, workflow 주석에 있다 (1105/12-01) | `scripts/check-system-test-prerequisites.ts`, `scripts/lib/provider-sandbox-namespaces.ts`, `config/ci/gates.json`, `docs/operations/ci-quality-gates.md` | `9655958` |
|
||
| [계약] | release job `immutable_build`가 FE-GATE-015·027의 gate 로그·evidence와 의존성 advisory 기록을 결과와 상관없이 `immutable-gate-evidence-<run>-<attempt>`로 올린다. 후보 archive와 그 upload는 그대로다 (1105/13-01) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts`, `.gitea/workflows/quality-gates.yml` | `629c713` |
|
||
| [계약] | gate 모양 기준선(`canonicalGateShapeSha256`)이 FE-GATE-013의 `hostRequirements`도 본다. 요구를 지우거나 바꾸면 `check:ci`가 기준선 차이로 실패하고, 바꿀 때는 `update:ci-contract-baseline`(owner·reason 필수)으로 다시 기록한다. 제품이 `config/ci/contract-baseline.json`을 자기 값으로 다시 기록해 두었다면 받은 뒤 다시 기록한다 (1105/12-01) | `scripts/contracts/ci-gates.ts`, `config/ci/contract-baseline.json` | `67082cc` |
|
||
| [계약] | 제품 overlay에 merge 게이트가 있으면 `release_gate`가 `product_merge_gate`를 기다린다. 제품 검사가 실패하면 같은 run의 release·immutable_build·promotion·deployment가 멈춘다. 게이트가 없으면 workflow는 그대로다. `check:ci`가 그 연결이 없는 workflow를 거절한다. 위 "먼저 할 일" 9단계 (1105/13-02) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts` | `92d5019` |
|
||
| [계약] | 한 checkout에서 실행 두 개가 서로를 지우지 않는다. `TEST_RUN_ID`를 주면 Playwright 결과·report·JUnit과 서빙할 빌드가 `.tmp/runs/<id>/` 아래로 간다. 빌드 단계는 `RUN_OUTPUT_ROOT`(설정이 web server에 넘긴다) 아래에 쓴다. 다섯 Playwright 설정은 빈 포트를 골라 `TEST_E2E_PORT`·`TEST_VISUAL_PORT`·`TEST_CAPABILITIES_PORT`·`TEST_STORYBOOK_PORT`·`TEST_DEV_PORT`에 적고(미리 주면 그 포트), vite는 `--strictPort`로 뜨고, dev 설정은 떠 있는 서버를 쓰지 않는다. 변수가 없으면 출력 경로는 전과 같다. 기능 인덱스 생성기는 내용이 같으면 쓰지 않고 다르면 rename으로 바꾼다. 상세는 `docs/testing/frontend-platform-testing-strategy.md` 13.6절 (1105/12-04) | `scripts/lib/run-isolation.ts`, `playwright*.config.ts`, `vite.config.ts`, `scripts/build-frontend.ts`, `scripts/generate-product-feature-index.ts` | `ddbda4d`, `f4d5761`, `0e72c0c`, `510e2bb` |
|
||
| [계약] | `verify:documentation`이 짝 백엔드 경로·링크를 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리(옆 checkout의 git 기록)에서 찾는다. 작업 트리와 HEAD는 보지 않는다. checkout이나 그 커밋이 없으면 확인하지 못한 것으로 남긴다. repo 밖으로 나가는 링크가 pin한 저장소가 아니면(이름 오타 포함) 실패한다 (1105/12-02) | `scripts/verify-documentation-readiness.ts` | `fc95672` |
|
||
| [계약] | `verify:documentation`은 지울 수 있는 템플릿 기능(참조 기능, 예제 화면 기능. `scripts/lib/removable-template-features.ts`)의 경로와 script를 그 기능이 설치돼 있으면 검사하고, `src/features/<id>/feature-module.ts`가 없으면 요구하지 않는다. 그래서 아래 절 6단계대로 예제 기능을 지운 제품도 문서 검사와 FE-GATE-005가 통과한다. 참조 기능 경로는 다시 백틱으로 적어 검사를 받는다. 1절 문서가 그 경로를 백틱 밖에 적으면 `test:unit`이 실패한다 (1105/14-01, 1105/14-03) | `scripts/verify-documentation-readiness.ts`, `scripts/lib/removable-template-features.ts`, `scripts/test-sample-removal.ts`, `docs/` | `50b631e`, `332bfee`, `1dda18d` |
|
||
| [계약] | 아키텍처 규칙 `feature-and-app-roots-do-not-reach-adapters`가 기능의 `adapters/` 폴더와 `feature-adapter-contribution.ts`를 뺀 `src/features` 전체를 본다. 기능 안 `support/` 같은 계층 밖 폴더가 `src/adapters`에 닿으면 실패한다. 위 "먼저 할 일" 10단계 (0929/12-03) | `.dependency-cruiser.json`, `scripts/check-architecture.ts` | `a37ebba` |
|
||
| [계약] **BREAKING** | `artifacts/tests/a11y.json`이 schemaVersion 2다. 실패 화면으로만 axe를 돌린 라우트(일반 답이 없는 상세 라우트)는 `scope`에서 빠져 `notChecked`(`{ routeId, reason }`)에 들어간다. 라우트 test가 자기 상태를 `artifacts/tests/a11y-data-state/<ROUTE_ID>.json`에 남긴다. 위 "먼저 할 일" 5단계 (1103/11-01) | `scripts/write-a11y-report.ts`, `scripts/lib/a11y-data-state.ts`, `scripts/contracts/release-artifacts.ts`, `tests/e2e/accessibility.spec.ts` | `757d1c7` |
|
||
| [계약] | lab(FE-GATE-026)이 기능 라우트 첫 진입을 잰다. 대상은 설치된 기능의 첫 공개 내비게이션 라우트(`labFeatureRoute`, 템플릿에서는 `EXAMPLES_UI`)이고 예산은 `budgets.json`의 `lab.featureRouteInteractionMs` 500 ms다. 그런 라우트가 없으면 `measured: false`로 남기고 판정하지 않는다. run마다 대상 라우트를 직접 열어 CLS도 잰다(`metrics.targetDeepLinkCls`, 예산 `lab.cls`). lab은 스크롤바를 보이게 띄운다. `lab.json` schema에 새 칸이 필수다 (1105/15-04, 1105/15-01, 1105/15-05) | `config/performance/budgets.json`, `config/schemas/lab-performance.schema.json`, `scripts/test-performance.ts`, `scripts/lib/lab-performance.ts` | `81701ad`, `138c195`, `e02f252` |
|
||
| [계약] | 초기 JS 기록 대조(`tests/unit/feature-shape-growth.test.ts`)의 합계 허용 오차가 1%(약 2 KB)가 아니라 256 B다. 초기 JS를 수백 바이트 움직이는 변경은 기록을 다시 쓴다 (1105/15-02) | `scripts/scale/measure-feature-shape-growth.ts` | `46359a1` |
|
||
| [계약] | 초기 JS 예산(`initialJsGzipBytes`)이 204,800 B가 아니라 206,848 B(202 KiB)다. 이 묶음의 검사·진단 코드가 초기 JS를 1,184 B 늘려 생성 기능 둘을 더한 드릴(FE-GATE-020)이 예산을 넘었다. 템플릿 기록은 204,111 B·초기 파일 27개로 다시 적었다. 예산을 복사한 제품은 자기 값을 그대로 두거나 같은 이유로 올린다. 재검토 조건은 `docs/operations/performance-evidence.md` (1105/15-02) | `config/performance/budgets.json`, `config/scale/feature-shape-ceilings.json` | `0fee3fe`, `287dc6f` |
|
||
| [계약] | `test:all`이 `test:coverage`(FE-GATE-005)가 도는 Vitest 경로를 모두 돈다(`tests/features` 전체, `tests/scripts`, browser-soak 계약 테스트). `tests/unit/test-all-paths.test.ts`가 대조한다 (0929/10-05) | `package.json` | `7ead8d3` |
|
||
| [계약] | 제품 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)의 잔여 판정: `src`는 기능 ID·폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 그 기능 폴더에서 import하는 파일만이다. 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여가 아니다. 참조 기능은 전처럼 넓게 찾는다 (1105/16-04) | `scripts/lib/feature-residue.ts`, `scripts/test-sample-removal.ts` | `b45d6a0` |
|
||
| [계약] **BREAKING** | `InstalledHttpContract`의 `contract.responseEnvelope`가 필수다. 참조 기능과 테스트 fixture는 `"NONE"`을 적는다. 조립은 빠진 값을 전처럼 `NONE`으로 읽는다. 위 "먼저 할 일" 1단계 (1103/16-01) | `src/contracts/external-contract-runtime.ts`, `scripts/create-feature.ts`, `src/features/reference-feature/contracts/` | `56272e8` |
|
||
| [계약] **BREAKING** | `refusedBeforeWrite`에 `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`(계약 문서 6.1절의 "쓰기 뒤 가능" 플랫폼 code)를 적으면 `composeContractContributions`가 거절한다. 실행기의 fail-close도 그 목록을 무시한다. `tests/unit/backend-contract-pin.test.ts`가 6.1절 표와 목록을 양방향으로 대조한다. 위 "먼저 할 일" 3단계 (1105/03-01) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/backend-envelope.ts` | `5c0b37e` |
|
||
| [계약] | Envelope operation의 503 `RATE_LIMIT_UNAVAILABLE`·`RATE_LIMIT_INCOMPATIBLE`은 쓰기 전 거절(`NOT_APPLIED`)이다. kind는 `SERVER_FAILURE`(action retry)이고 IDEMPOTENT 쓰기는 `retryBudget` 안에서 다시 보낸다. KEYED·NEVER는 자동 재전송이 없다 (1105/03-02) | `src/adapters/http/backend-envelope.ts`, `config/contracts/backend-idempotency-answers.json` | `c6c37f3` |
|
||
| [계약] | 짝 백엔드 `http-contract.md` §2·§4 표를 pin 커밋 그대로 `config/contracts/backend-http-contract-excerpt.json`에 옮겼다. `test:unit`이 답 표와 사본을 행마다 대조한다(옮기지 않은 행은 pin의 `notCopied`). `check:backend-contract-drift`(게이트 밖)는 사본을 pin 커밋의 문서와 비교하고, pin의 `backend.scaffoldSources`(백엔드 생성기 템플릿 파일과 옮긴 프론트 위치)가 pin 뒤 바뀌었는지도 본다. 비교하지 못하면 rc=2다. pin을 올릴 때는 `--write-excerpt` (1105/07-01, 1105/16-02) | `config/contracts/backend-contract-pin.json`, `config/contracts/backend-http-contract-excerpt.json`, `scripts/check-backend-contract-drift.ts`, `scripts/lib/backend-contract-excerpt.ts` | `daf3474`, `f600e6b` |
|
||
| [계약] | Fileserver 업로드 client: 202 `REJECTED`는 실패 `VALIDATION_REJECTED`, code `FILE_REJECTED`, `NOT_APPLIED`다(전에는 `SCHEMA_MISMATCH`). 빈 파일은 보내지 않고 `FILE_EMPTY`, `NOT_STARTED`로 끝난다. 504 `TRANSFER_TIMEOUT`은 결과 불명(`MAYBE_APPLIED`, retryable 아님, 자동 재전송 없음)이다. 멱등성 code와 V3 판정 표에 있는 답은 V3 표대로 판정해 503 `IDEMPOTENCY_UNAVAILABLE`도 결과 불명이다. 실패 Envelope의 `meta.traceId`를 `AppFailure.traceId`로 싣는다 (1105/01-01, 1103/01-01, 1105/01-02, 1105/01-03) | `src/adapters/http/fileserver-upload.ts`, `docs/manual/` | `6608fef`, `471b001`, `8b92f45` |
|
||
| [계약] | FE-REG-SCHEMA `direction: "RESPONSE"` 행의 `unknownFieldPolicy`를 `REJECT_UNKNOWN`으로 좁히면 `check:registries`가 breaking(`response-reader-narrowed`)으로 본다. 넓히는 쪽과 REQUEST 행은 그대로 behavior-change다 (1105/07-02) | `scripts/lib/registry-compatibility.ts` | `3b62ccd` |
|
||
| [계약] **BREAKING** | `BoundMutation.operationId`와 `commandMutationIdentity`가 돌려주는 operationId가 brand 타입 `MutationOperationId`다. 위 "먼저 할 일" 2단계 (1103/16-05) | `src/contracts/server-state.ts` | `48c1ab7` |
|
||
| [계약] | 키 없는(`NEVER`) 결과 불명 요청과 같은 입력으로 `submit`하면 보내지 않고 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)를 돌려준다. `AsyncSurface`는 `unknownEffectResendable === true`일 때만 재전송 버튼을 그린다. 손으로 만든 결과 불명 상태를 넘기던 화면은 버튼이 사라진다 (0929/03-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/components/async-surface.tsx` | `683ccfb` |
|
||
| [계약] **BREAKING** | `createBoundedPollCoordinator`의 `execute`가 던지면(abort 제외) 재시도 없이 `PROTOCOL_MISMATCH`(retryable 아님)로 lease가 끝난다. `execute` 입력에 생성 때 검사한 descriptor `input.operation`이 실린다(추가만). 위 "먼저 할 일" 4단계 (1105/04-02, 1103/04-01) | `src/adapters/realtime/` | `05330e3`, `27e3dec` |
|
||
| [계약] | scope reset이 실패하면 단계마다 진단 `cache.operation.failed`(`operation: "SCOPE_RESET"`, `reason` `PARTICIPANT_FAILED`·`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`·`PARTICIPANTS_UNREADABLE`, participant면 `scope_participant: <label>`)를 남긴다. 진단 계약에 키 `scope_participant`(값 정책 `isScopeParticipantLabel`)가 생겼다. 제품 closer는 각자 participant가 되고, 형식에 맞지 않는 label은 조립이 `TypeError`로 거절한다. 위 "먼저 할 일" 6단계 (1105/02-01) | `src/contracts/diagnostics.ts`, `src/adapters/query-cache/server-state-scope-runtime.ts`, `src/bootstrap/runtime-adapters.ts` | `f738348` |
|
||
| [계약] | `ProductCompositionContext.notifySessionUnauthenticated()`가 생겼다. 쿠키 세션 recipe의 `createSessionCookieRejectionHandler(context)`는 `SESSION_COOKIE_*` 프로필의 401만 세션에 넘긴다. 위 "먼저 할 일" 7단계 (1105/09-02) | `src/bootstrap/product-composition-contract.ts`, `recipes/session-owners/cookie-session-owner.ts` | `0007699` |
|
||
| [계약] | `ProductComposition.serviceWorker`(선택): `{ blockers?, observe? }`. 템플릿 조립이 `createOptionalRuntimeHost`에 넘긴다. `observe`가 던져도 worker 흐름은 바뀌지 않는다. 위 "먼저 할 일" 8단계 (1103/09-05) | `src/bootstrap/product-composition-contract.ts`, `src/bootstrap/create-runtime-composition.ts` | `fdc1db9` |
|
||
| [계약] | 금지된 설정 키로 멈춘 부팅 오류의 `invalidKeys`에 그 키의 점 경로가 실린다. `src/contracts/env.ts`가 `UnsafeConfigNameError`(`key`)를 새로 내보낸다(추가만) (1103/07-04) | `src/contracts/env.ts`, `src/bootstrap/load-runtime-config.ts` | `2e1acb1` |
|
||
| [계약] | 저장소 registry 행 `AUTH_REDIRECT_TRANSACTION`(`backend: "external"`, FE-REG-STORAGE additive). OIDC PKCE recipe의 sessionStorage 키가 이 행의 `physicalKey`다. 사용처가 지울 수 있는 레시피뿐이라 FE-REG-STORAGE orphan 검사에서 뺀다. 위 "먼저 할 일" 7단계 (1105/05-01) | `src/contracts/storage-keys.ts`, `recipes/session-owners/oidc-pkce-session-owner.ts`, `config/contracts/registry-governance.json` | `dc7c95b` |
|
||
| [계약] | 승인된 LOGOUT·ACCOUNT_DELETION purge가 마지막 객체까지 돌면 늘 partition을 지운다. 성공 report는 `partitionDeleted`와 `moreObjectsAvailable` 중 정확히 하나를 가진다. port의 `chunkSweep`은 아무도 채우지 않아 `@deprecated`다 (1103/05-01) | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/opfs-ports.ts`, `recipes/frontend-capabilities/` | `23662fb` |
|
||
| [계약] | Cache Storage: 본문을 읽지 못한 entry는 판정 `UNREADABLE`이고, 다시 stage하면 모든 asset을 다시 받아 덮어쓴다. activation은 그 경우 code는 그대로 두고 recovery를 `REHYDRATE`로 준다 (1105/02-02) | `src/adapters/cache-storage/public-response-cache-adapter.ts` | `8e9fb1f` |
|
||
| [계약] | Service Worker 사전 캐시는 `assets/`(`BUILD_ASSET_DIRECTORY`) 아래 해시 파일만 담는다. `public/`의 루트 파일(아이콘 등)은 빠진다. `build.assetsDir`를 바꾸는 제품은 이 상수도 바꾼다 (1105/06-01) | `src/contracts/service-worker.ts`, `scripts/generate-service-worker-assets.ts`, `src/adapters/service-worker/service-worker-static-assets.ts`, `scripts/lib/hosting-probe.ts` | `1c7c614` |
|
||
| [계약] | 자산 MIME probe(FE-GATE-019 live)가 redirect를 FAIL로 본다(install fetch는 `redirect: "error"`). live 분기는 `probeLiveHosting` 하나다 (1105/06-02) | `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts` | `4d6f254` |
|
||
|
||
### 그 밖의 수정
|
||
|
||
- 테스트: 제품 확장 타입 검사 탐침이 복사본의 `product-contracts.ts`·`product-composition.ts`를 덮어쓰지 않고 덧붙인다. 기능이 제품 capability를 쓰는 다운스트림에서도 FE-GATE-005가 통과한다 (1105/09-01, `397664e`)
|
||
- 폼·화면: 기능이 `useAppForm`의 `refusalMessages`로 쓰기 전 거절 code에 자기 문구와 필드를 붙인다 (1103/03-01, `12d97d7`). 복구 버튼으로 끝낸 저장 뒤 포커스가 feedback 자리로 간다 (1105/08-01, `4f3c10b`). 다른 저장이 진행 중이면 저장 버튼을 끄고 진행 문구를 보인다 (1105/08-04, `f2b8ba7`). 생성 폼이 "변경됨으로 확인" 뒤 목록으로 간다 (1105/08-02, `90c489c`). 홈 시작 링크가 런타임에 꺼진 기능을 고르지 않는다 (1105/08-03, `f849d78`). `:root`에 `scrollbar-gutter: stable`. 스크롤바 자리만큼 내용 폭이 15 px 줄어 시각 골든 5장을 다시 찍었다. base.css를 받은 제품은 자기 골든도 다시 찍는다 (1105/15-05, `e02f252`). 플랫폼 구성 화면이 릴리스 신원 칸 자리를 처음부터 잡는다 (1105/15-01)
|
||
- 레지스트리 도구: `check:registries`가 계약 조립 실패 원인을 한 번만 적는다 (1105/09-03, `bfd9d50`)
|
||
- 문서: VD-28과 realtime 설계 3절의 poll 규칙을 V3 descriptor로 (1105/04-03, `05880d1`). 테스트 전략 11.2절의 지운 auth-recovery 테스트 (1103/12-05, `e72fb6e`). 기능마다 바뀌는 추적 파일 둘과 충돌 처리 (1105/16-01, `6d084cf`). 매뉴얼 04 §3.2 설정 키 예시의 `defaultValue`와 그 블록을 그대로 타입 검사하는 테스트 (1105/14-02, `e6b2a4f`). Cache Storage inspect의 `verified` 뜻과 비용 (0929/02-02, `f2a4f32`). 세션 파일 recipe 주석의 capability 타입 위치 (1105/02-03, `d31c7d6`). 남은 `FEATURE_OVERRIDES` 키의 경고 (0929/14-05, `1c4e57c`). 루트 `SPEC.md`·`tasks/`의 이유 (0929/14-01, `1ac336a`). README에 미출시 범위를 받는 두 명령과 기준점 기록 (0929/14-02, `57e3586`)
|
||
- CHANGELOG: 아래 절의 초기 파일 상한 32·알려진 제한 기준·FE-GATE-017 단계 (1103/14-01, 1103/15-02, `832774f`), poll 행 (1105/04-02, `1e576ef`), "옮기기 전" 2단계 목록 (1103/14-02, `f4be426`), 리뷰 참조 꼴과 그 테스트 (1101/14-02, `b834b8d`)
|
||
- 테스트 고정: interaction signal listener 정리 (1105/10-02, `dae44f5`), 조합 transport의 OFFLINE 재시도 (1105/04-01, `bde7fa4`), MAX_RETRY_ATTEMPTS·REQUEST_TIMEOUT_MS와 복구 중 세션의 보호 라우트를 샘플 밖에서 (1105/10-01, `00b12b3`), 옛 탭이 지워진 route를 reload 없이 연다 (1105/06-03, `aaa782b`), Fileserver 5xx·deadline·읽기 전 크기 거절 (1105/01-04, `f2f7dc4`), strict fixture가 preload 기록으로 test를 실패시킨다(`browserFailureVerdict`) (1105/11-01, `e025529`), 오래된 scope의 성공 응답 (0929/10-04, `c842bac`), 손상 code 목록의 경계 (1105/02-04, `56c0bd0`), 실제 시계를 기다리던 테스트 5개 (1101/10-07, `ce191be`), cross-context host의 localStorage 영역 (1101/02-04, `11a0fd0`), vite 빌드 입력 목록 한 모듈 (1105/15-03, `c9aa73f`)
|
||
|
||
### 알려진 제한
|
||
|
||
이 절의 범위 끝에서 사실인 것만 적었다. 하나씩 결정 대기·백엔드로 넘김·일부를 적는다.
|
||
|
||
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다.
|
||
- 기능 라우트 첫 진입: lab이 `EXAMPLES_UI`를 500 ms 예산으로 잰다(1105/15-04). 진입은 여전히 요청 두 묶음(context 라우트 모듈·실행부, 그다음 페이지 청크)이다. 하나로 줄이려면 초기 청크의 라우트 선언이 페이지 로더를 가져야 한다. 결정 대기(선언 모양·초기 JS). 예산 여유는 94 ms이고 lab 부하 가드는 없다(0929/11-04).
|
||
- 예제 기능 제거 드릴(`test:sample-removal -- --feature=platform-examples-feature`)은 어느 게이트도 돌리지 않는다. 문서 쪽은 `test:unit`의 사본 테스트가 본다. 일부(1105/14-01).
|
||
- 결정 대기: KEYED 결과 불명의 같은 키 재전송이 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받아도 재전송 버튼이 남는다. 고르는 사람은 프론트 템플릿 담당이다(재전송을 거두기 / 백엔드가 롤백을 효과 없음으로 기록 / 지금대로) (1103/03-01).
|
||
- 결정 대기: 워커 없는 빌드에서 자산 MIME probe를 script·style만 보게 좁힐지. 지금은 글꼴·이미지 MIME도 FAIL이다 (1105/06-02).
|
||
- 결정 대기: Cache Storage inspect에 `signal`과 판정 불가 칸을 더할지(VD-15 목표 runtime과 함께) (0929/02-02).
|
||
- 결정 대기: dev manifest를 생성 파일로 둘지, 초기 JS 기록에서 제품 기능을 뺄지. 지금은 기능 브랜치 둘이 같은 줄에서 충돌하고 명령을 다시 돌려 푼다 (1105/16-01).
|
||
- 결정 대기: 1절 밖 문서(목표 설계)의 경로 검사. 문서별 예외 방식부터 정해야 한다 (1103/12-05).
|
||
- 결정 대기: 두 제품이 고친 템플릿 파일 중 제품 소유 자리가 없는 것을 템플릿에 들일지(아래 절 "옮기기 전" 2단계) (1103/14-02, 0929/14-03). 다운스트림이 찾은 템플릿 결함을 어디에 기록할지 (0929/14-06). 현재 계약 절과 목표 설계 절이 섞인 문서를 나눌지 (1101/14-07).
|
||
- 백엔드로 넘김: Fileserver 504 `TRANSFER_TIMEOUT`은 작업이 시작된 뒤에도 retryable로 온다. 백엔드가 `ambiguous` 표시를 주거나 504가 "READY 없음"을 보장하면 프론트 판정을 다시 본다. `POST /v1/files`는 `Idempotency-Key`를 읽지 않는다 (1105/01-02).
|
||
- 백엔드로 넘김: 백엔드 매뉴얼의 짝 경로 안내와 `docs/fileserver/http-contract.md`의 202 state 목록. 실제 백엔드 업로드는 돌리지 않았다 (1103/01-01).
|
||
- 백엔드로 넘김: `RateLimitInterceptor`가 비동기 재디스패치에서도 평가되면 503 rate-limit이 쓰기 뒤에도 나올 수 있다. 요청은 `DispatcherType.REQUEST`에서만 평가하기다. 지금 백엔드에는 그런 쓰기 컨트롤러가 없다 (1105/03-02).
|
||
- 일부: poll 조합 코드가 `input.operation`을 무시하고 다른 descriptor를 넘기면 attempt마다 요청이 최대 3번이다 (1103/04-01).
|
||
- 일부: Service Worker 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을 제품 소유 자리가 없다. realtime·Web Worker·오프라인 명령 선택은 조립이 거절한다 (1103/09-05).
|
||
- 일부: 짝 백엔드 표 사본과 백엔드 문서의 일치, 생성기 템플릿 변경은 `check:backend-contract-drift`(게이트 밖, 옆 checkout 필요)만 본다. Fileserver 자신의 code 표는 pin 대조 밖이다 (1105/07-01, 1105/16-02, 1105/01-02).
|
||
- 일부: 실행 격리는 브라우저 테스트 실행까지다. 게이트와 증거 검사는 기본 경로만 읽고, 선택이 다른 두 실행은 `src/.generated`를 서로 바꾸고, Storybook 캐시는 공유한다 (1105/12-04).
|
||
- 일부: 쿠키 세션 handler를 잇지 않은 제품은 여전히 세션 만료를 모르고, 막는 검사는 없다. 세션 owner recipe는 실제 Keycloak·Redis에 붙여 보지 않았다 (1105/09-02).
|
||
- 일부: 아래 절 "옮기기 전" 목록(0929/14-03 포함), 루트 작업 기록 위치, README 범위 동기화 명령은 문서만 고쳤고 명령은 실행하지 않았다 (1103/14-02, 0929/14-01, 0929/14-02).
|
||
|
||
## 미출시(`main` `409d72e`에 합침) — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03`
|
||
|
||
한 번의 동기화로 받는 변경의 순 요약이다. 범위는 `main` `752a61f`부터 브랜치 `fix/maturity-review-2026-11-03`의 끝까지다. 이 절을 쓸 때 끝은 `f887817`이었다(병합 커밋을 빼고 310개). 그 뒤 깨끗한 clone 검증(merge 단계 14개)에서 찾은 수정과 pin 갱신을 더했다. 버전 번호와 태그는 아직 정하지 않았다.
|
||
|
||
이 묶음은 세 갈래를 합쳤다.
|
||
|
||
- `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/`) 조치.
|
||
- `claude/happy-easley-233d07`: 짝 백엔드 Envelope 읽기, V2 HTTP 경로 삭제, 거절 판정 표, 쿠키 쓰기 CSRF, KEYED 재전송. 앞 갈래와 `e40684b`에서 합쳤다.
|
||
- 2026-11-03 성숙도 리뷰(`docs/reviews/2026-11-03-maturity-review/`) 조치 브랜치 11개. `fix/maturity-review-2026-11-03`에서 합쳤다.
|
||
|
||
읽는 법:
|
||
|
||
- 최종 상태만 적는다. 같은 범위 안에서 뒤 커밋이 다시 바꾼 중간 상태는 적지 않는다. 예를 들어 V2 클라이언트를 고친 커밋들은 V2를 지운 행 하나로 남겼다. 중간 기록은 커밋 이력에 있다.
|
||
- 이 repo의 커밋 해시는 기준점 `752a61f`·`af3d8e6`을 빼면 모두 이 범위에 있다. 브랜치 끝에서 닿고 `752a61f`에서는 닿지 않는다. 다른 repo의 커밋(다운스트림, 짝 백엔드)은 repo 이름과 함께 적었다.
|
||
- 두 다운스트림(tech-log-frontend, memento-frontend)의 기준점은 `af3d8e6`이다. `af3d8e6`과 `752a61f` 사이에는 리뷰 문서만 있다. 그래서 두 제품이 받을 변경은 이 절과 같다.
|
||
|
||
### 먼저 할 일 (BREAKING)
|
||
|
||
복사한 프로젝트가 이 묶음을 받을 때 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림에서 읽은 모양(memento-frontend `d3810a0`, tech-log-frontend `7a4e201a`, 2026-11-05)을 단계마다 적었다. 템플릿은 이 안내를 두 제품 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
|
||
|
||
#### 옮기기 전
|
||
|
||
1. 기준점을 확인한다. memento는 `.template-origin`, tech-log는 `template.lock.json`의 `sourceRevision`에 있다. 둘 다 `af3d8e6`이다.
|
||
2. 제품이 고친 템플릿 파일을 뽑는다. 이 묶음은 그 일을 받을 제품 소유 파일을 새로 둔다(옮기는 법 2단계). 템플릿 파일을 고친 채로 두면 동기화마다 충돌한다.
|
||
- memento: `src/bootstrap/runtime-adapters.ts`, `src/features/feature-adapter-contribution.ts`(capability `offsetUpload`·`runtime`), `src/contracts/rest-profiles.ts`(`MEMENTO_BFF_READ`·`MEMENTO_BFF_WRITE`), `src/contracts/external-contract-runtime.ts`(출처 종류 `PRODUCT_LOCAL_CONTRACT`), `src/features/installed-feature-contracts.ts`(`APP_HOME` 다리), `src/features/installed-runtime-capabilities.ts`(Service Worker `ACTIVE`), `src/presentation/routes/app-router.tsx`(`ownsShell` 다리).
|
||
- tech-log: `src/contracts/env.ts`(`TECH_LOG_STUDIO_SOURCE`·`TECH_LOG_PUBLIC_SOURCE` 행), `src/bootstrap/create-runtime-composition.ts`(부트 전 BFF 세션 owner), `src/contracts/rest-profiles.ts`(`TECH_LOG_STUDIO_SESSION`·`TECH_LOG_STUDIO_BOOTSTRAP`), `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/features/installed-*` 다섯 개(TechLog 직접 조립. 그중 `installed-feature-runtimes.tsx`는 템플릿이 지웠다), `src/presentation/routes/app-router.tsx`(PUBLIC/STUDIO 라우터).
|
||
- 위 목록은 일부다. `af3d8e6` 뒤 두 제품이 고친 템플릿 `src` 파일(기능·context 폴더 밖, `git diff --name-status af3d8e6 HEAD -- src`)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2, 그 밖에 삭제. 추가 중 `reference-feature/NOT_INSTALLED`는 옮기는 법 1단계)다. 2026-11-05에 두 repo의 diff를 읽어 나눴다(1103/14-02).
|
||
- 제품 소유 자리가 있는 것. tech-log `src/contracts/release-artifacts.ts`의 `TECH_LOG_STUDIO_SOURCE`·`TECH_LOG_PUBLIC_SOURCE` 필드는 `PRODUCT_RUNTIME_CONFIG_FIELDS`로 간다(옮기는 법 2단계). memento `src/adapters/http/offset-upload.ts`(추가)와 `src/adapters/http/index.ts`의 그 export는 capability `offsetUpload`를 만드는 제품 코드라 `src/bootstrap/product-composition.ts` 쪽 제품 파일로 옮기고 HTTP 배럴은 템플릿 것으로 되돌린다. tech-log의 라우팅 파일(`src/contracts/routes.ts`·`route-runtime-contract.ts`의 `layoutGroup`과 플랫폼 라우트 삭제, 참조 기능 계약 `reference-feature-contract.ts`의 `layoutGroup`, `src/presentation/routes/` 6개와 추가 `route-url-builder.ts`)은 직접 조립의 일부라 3단계 끝의 기능 모듈 길로 바꾸면 템플릿 것으로 돌아간다.
|
||
- 제품 소유 자리가 아직 없는 것. 템플릿이 자리를 정하지 않았다. 동기화 때 충돌하거나 제품이 고친 채로 남는다(알려진 제한). memento: 요청 헤더 `if-match`(`http-contract-bridge.ts`, `http-execution-v3.ts`. V3 descriptor에는 요청 헤더 칸이 없다), Service Worker 오프라인 navigation shell(`service-worker-lifecycle.ts`)과 사전 캐시 확장자 `.html`·`.jpg`(`service-worker-static-manifest.ts`), 저장소 이름 `APP_NAMESPACE`(`storage-keys.ts`)와 OPFS 이름(`opfs-policy.ts`, `indexeddb-opfs-journal.ts`), 앱 이름 문구(`catalog.ts`의 `common.appName`·`route.APP_HOME.title`), 브랜드 토큰·글꼴·primitive(`design-system/tokens/` CSS 3개와 `token-contract.ts`, `primitives/core.tsx`, `design-system/index.ts`, `styles/theme.css`, 추가 폴더 `design-system/memento/`). tech-log: `AppFailure.detail`(`errors.ts`, `feature-http-binding.ts`), `BoundMutation.identity`(`server-state.ts`)와 그것을 쓰는 `application-query.ts`, `deriveAsyncState`와 조회 훅이 `null`을 데이터 없음이 아닌 빈 상태로 보는 것(`async-state.ts`, `application-query.ts`), 폼(`use-app-form.ts`의 select, `use-dirty-navigation-guard.tsx`), 디자인 시스템(`primitives/core.tsx`·`forms.tsx`·`navigation.tsx`, `patterns/common-patterns.tsx`, `design-system/index.ts`, `page-templates.tsx`, `app-shell.tsx`), 문구(`catalog.ts`, `message-contract.ts`), 전역 글꼴·스타일 import(`src/bootstrap/main.tsx`).
|
||
- 템플릿 결함 후보. tech-log `application-query.ts`는 마운트한 같은 이벤트 턴에 저장하면 결과 불명 채널이 아직 없어 거절되던 것을 고쳤다(채널을 제출 때도 얻는다). 템플릿은 이것을 재현하지 않았다.
|
||
3. 기능마다 HTTP descriptor를 센다. method, `retrySemantics`, `responseEnvelope`, 입력·응답·실패 검증기의 schemaId, 그 검증기가 zod인지. 옮기는 법 4·5단계의 작업량이 이 숫자로 정해진다.
|
||
- memento-web: descriptor 29개. 입력·응답 schemaId 42개와 실패 본문 `MementoProblem` 1개. 검증기는 zod가 아니라 손으로 쓴 `isRecord` 검사다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`·`IDEMPOTENT`·`NEVER`다.
|
||
- TechLog: 검증기는 `zodValidator`다. 출력은 Envelope 뼈대만 검사하고 본문은 통과시킨다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`나 `NEVER`(둘 다 `retryBudget` 0)다.
|
||
4. 지금 게이트 결과를 남긴다. 동기화 뒤의 실패가 원래 있던 것인지 가르는 데 쓴다. 두 제품의 지난 동기화 기록(`docs/operations/template-sync-2026-09-29.md`)과 같은 목록이면 된다.
|
||
|
||
#### 옮기는 법
|
||
|
||
1. **기능이 아닌 폴더의 표시.** `src/features/<dir>/NOT_INSTALLED`를 같은 자리의 `NOT_A_FEATURE`로 바꾼다. 생성기는 `NOT_INSTALLED`를 더는 읽지 않는다. 표시와 `feature-module.ts`가 한 폴더에 있으면 생성기가 실패한다.
|
||
- memento: `local-draft-feature`. 템플릿 폴더라 병합으로 바뀐다.
|
||
- tech-log: `tech-log`, `reference-feature`, `local-draft-feature`. `reference-feature`는 템플릿이 그 폴더에 둔 `feature-module.ts`·`feature-runtime.ts`·`context-routes.ts`를 받지 않는다.
|
||
(1103/09-09)
|
||
2. **제품 코드를 제품 소유 파일로 옮긴다.** 템플릿은 아래 파일을 비워서 내보내고, 복사한 뒤에는 고치지 않는다. 제품 코드를 여기로 옮기고 "옮기기 전" 2단계의 템플릿 파일은 템플릿 것으로 되돌린다.
|
||
- `src/contracts/product-contracts.ts`
|
||
- `PRODUCT_REST_AUTH_PROFILES`: 제품 인증 프로필. memento의 `MEMENTO_BFF_READ`·`MEMENTO_BFF_WRITE`, tech-log의 `TECH_LOG_STUDIO_SESSION`·`TECH_LOG_STUDIO_BOOTSTRAP`이 여기 온다. 템플릿 프로필과 id가 겹치면 모듈 로드가 실패한다.
|
||
- `PRODUCT_RUNTIME_CONFIG_FIELDS`와 `PRODUCT_ENV_REGISTRY`: 제품 런타임 설정 키(zod, `.default()`나 `.optional()`)와 그 FE-REG-ENV 행(`as const`). 키마다 행이 있어야 하고 행의 `required`·`defaultValue`가 스키마와 같아야 한다(`tests/unit/env-registry-coverage.test.ts`, `test:unit`). tech-log의 `TECH_LOG_*_SOURCE` 두 키가 여기 온다.
|
||
- `src/bootstrap/product-composition.ts`
|
||
- `composeProductSessionOwner(context)`: 부트 전 세션 owner. `AUTH_MODE=external`일 때만 불린다. tech-log가 `create-runtime-composition.ts`에서 host 전역에 넣던 BFF owner가 여기 온다. context의 `fetch`는 필수 칸이다(마감 `REQUEST_TIMEOUT_MS`, 본문 64 KiB, redirect 거부). 이 context를 직접 만드는 제품 테스트는 `fetch`를 더한다. 짝 백엔드 두 인증 모드의 owner 예시는 `recipes/session-owners/`에 있다.
|
||
- `composeProduct(context)`: `capabilities`(memento `offsetUpload`·`runtime`, tech-log Studio 소스·HTTP), `credentialProviders`(인증 프로필별 자격증명. memento는 `x-xsrf-token`, tech-log는 `x-csrf-token`), 선택 칸 `onCredentialRejected`와 `scopeParticipants`.
|
||
- 401 처리가 바뀌었다. 제품 provider가 자격증명을 낸 요청의 401은 템플릿 세션을 로그아웃시키지 않고 `onCredentialRejected`로만 온다. 두 제품처럼 provider와 세션 owner가 한 쿠키 세션을 쓰면 여기서 owner에 알린다(예: owner의 `notifyUnauthenticated`). 알리지 않으면 템플릿 세션은 그 401을 모른다.
|
||
- `scopeParticipants`: 로그아웃·계정 전환 때 FENCED와 READY 사이에서 닫을 제품 자원. 닫기가 실패하면 READY로 가지 않는다.
|
||
- `src/features/product-capabilities.ts`
|
||
- `ProductFeaturePlatformCapabilities`: 제품 capability의 타입. `feature-adapter-contribution.ts`의 `FeaturePlatformCapabilities`에 `declare module`로 붙이던 보강을 여기로 옮긴다. 템플릿이 만드는 키(`http`, `telemetry`, `indexedDb`)는 다시 선언할 수 없다.
|
||
- `PRODUCT_RUNTIME_CAPABILITY_SELECTION`: Service Worker·realtime·web worker·offline command 선택. memento가 `installed-runtime-capabilities.ts`에 적은 Service Worker `ACTIVE` 선택이 여기 온다.
|
||
- `config/ci/product-gates.json`: 배포(`deployment`)와 제품 merge 검사(`mergeGates`, ID `PRODUCT-GATE-NNN`). 배포 슬롯을 `config/ci/gates.json`에서 채웠다면 여기로 옮긴다. `deployment`에는 package script 이름과 `vars.*`·`secrets.*` 바인딩만 적는다. 승격 후보를 받아 digest를 확인하고 푸는 단계는 템플릿이 만들고, `secrets.*`는 deploy 단계에만 간다.
|
||
- 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 코드는 `undefined`를 받는다.
|
||
(1101/09-02, 1103/09-01, 1103/09-02, 1103/09-03, 1103/09-05, 1103/09-08, 1103/02-01, 1103/12-07, 1103/13-05)
|
||
3. **기능을 선언과 실행부로 나눈다.** 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서 나눴다. 완성된 모양은 `src/features/reference-feature/`다.
|
||
- 선언(`feature-module.ts`, `FeatureModule`): 초기 청크에 남는다. `id`, `contracts`(route 표, route runtime 계약, invalidation, topic version, `contractPackages`), `routes`, `messages`, `loadRuntime`만 가진다.
|
||
- 실행부(`feature-runtime.ts`, `defineFeatureRuntime({ featureId, schemas, adapters, contractContributions })`): 그 기능의 route에 처음 들어갈 때 router가 `application.features.load(featureId)`로 적재한다.
|
||
|
||
순서:
|
||
|
||
1. 기능 계약에서 V2 칸 `apiOperations`·`runtimeSchemas`·`mappers`를 지운다. 스키마 메타데이터 `schemas`는 별도 파일로 빼서 `defineFeatureRuntime`에 넘긴다(참조: `contracts/reference-schema-metadata.ts`). memento-web에는 `*-api-contract.ts`가 없다. 이 칸들은 `contracts/memento-feature-contract.ts`에 있다. `apiOperations`와 `mappers`는 비어 있어 지우기만 한다. `runtimeSchemas`(`MEMENTO_RUNTIME_SCHEMA_CODECS`, 라우트 codec 7개)는 3번으로, `schemas`(라우트 행 7개)는 새 메타데이터 파일로 간다.
|
||
2. 선언 계약에 `contractPackages`를 더한다. 기능의 `EXTERNAL_PACKAGE` 계약 기여가 고정하는 패키지 신원 목록이다. 없으면 `Object.freeze([])`. 부팅 때 release manifest를 이 목록과 맞춰 본다. 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능 전용이다. memento가 템플릿 파일에 더한 `PRODUCT_LOCAL_CONTRACT`는 조립이 `unknown contribution source kind`로 거절한다. `EXTERNAL_PACKAGE`로 바꾸고 신원(패키지 이름·정확한 버전·`sha256:` digest·revision)을 준다. 자리표시자 신원은 로컬·개발 빌드에서는 되지만 staging·production 승인(FE-GATE-027)이 거절한다. 선택 기준은 `docs/manual/02-decision-tables.md` 2절이다.
|
||
3. route codec을 `context-routes.ts`의 각 route `handle.codecs`로 옮긴다(참조: `presentation/reference-route-codecs.ts`의 `REFERENCE_FEATURE_ROUTE_CODECS`). 플랫폼 codec과 같은 id는 쓸 수 없다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없어졌다.
|
||
4. `feature-runtime.ts`를 만들고, `feature-module.ts`에서 `adapters`·`contractContributions`·`runtimes`를 지운 뒤 `loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME`을 넣는다. `feature-runtime.ts`를 어디서도 정적으로 import하지 않는다. 그러면 실행부가 다시 초기 청크에 들어간다. `featureId`가 모듈 id와 다르면 적재 때 실패한다.
|
||
5. runtime descriptor에 붙인 제품 칸은 context로 옮긴다. memento-web의 `ownsShell: true`와 `app-router.tsx` 다리는 `src/contexts/memento-context/context-layout.tsx`의 `CONTEXT_LAYOUT`이 대신한다. 레이아웃은 skip link와 `<main id="main-content" tabIndex={-1}>` 하나를 그린다. `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 검사한다. memento-web은 이미 route id `APP_HOME`을 선언하므로 그것만으로 플랫폼 홈을 대신한다. `installed-feature-contracts.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` 다리는 지운다.
|
||
6. 기능 input(`application.features.get(id)`)은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저 `await application.features.load(id)`를 부른다. `ApplicationApi.features`를 직접 구현하거나 fake로 만든 코드는 `load`를 더한다. 모든 기능의 실행부가 필요한 화면은 `loadInstalledFeatureRuntimeRegistries()`를, Node 스크립트와 테스트는 `src/features/loaded-feature-runtimes.ts`를 쓴다. `src/`에서 이 파일을 import하면 아키텍처 규칙 `boot-does-not-load-every-feature-runtime`이 막는다.
|
||
7. `vite.config.ts`의 청크 그룹(`feature-declarations`, `feature-platform`, `react-dom`)을 가져간다. 없으면 기능마다 선언 청크가 하나씩 는다.
|
||
|
||
**직접 조립 제품(tech-log).** TechLog는 `feature-module.ts` 없이 `installed-*` 파일에 직접 조립된다. 이 묶음에는 그 자리가 없다. `installed-feature-runtimes.tsx`가 없어졌고, route codec은 context route handle에 실리고, 계약 기여는 기능 실행부를 적재할 때 설치되고, FE-REG-API·FE-REG-SCHEMA는 생성기가 설치한 기능만 본다. 템플릿이 준비한 길은 TechLog를 기능 모듈로 바꾸는 것이다. PUBLIC 묶음은 루트 `*`에 자기 레이아웃과 `APP_HOME`을 가진 context가 되고, 필요하면 같은 레이아웃을 쓰는 두 번째 루트 context(예: `topics/*`)를 둔다. STUDIO 묶음은 자기 레이아웃을 가진 `studio` context가 된다. 이 모양은 `tests/helpers/fixture-layout-product.tsx`가 선언하고 `tests/component/context-layouts.test.tsx`와 `layout-landmarks.test.tsx`가 실행한다. 바꾸면 TechLog descriptor에도 4·5단계가 적용된다. 직접 조립을 유지하면 `installed-*`와 라우터를 제품이 계속 고쳐야 하고, 템플릿은 그 경로를 검사하지 않는다(알려진 제한).
|
||
(1101/15-01, 1101/07-04, 1101/09-03, 1101/16-04)
|
||
4. **HTTP descriptor 조립 규칙.** 계약 조립(`composeContractContributions`)이 아래를 어기는 기여를 거절한다. 메시지는 `Installed contract contribution is not composable: <reason>`이다.
|
||
- GET·HEAD의 `retrySemantics`는 `SAFE`나 `IDEMPOTENT`다. 재시도를 막으려면 `retryBudget: 0`.
|
||
- POST·PUT·PATCH·DELETE에는 `SAFE`를 쓸 수 없다. `IDEMPOTENT`, `KEYED`(`commandRecovery` 필요), `NEVER`(`retryBudget` 0) 중 하나다.
|
||
- 계약 기여 하나 안의 operation은 모두 같은 `responseEnvelope`를 읽는다. 값이 없는 것과 `"NONE"`은 같다. 두 백엔드를 쓰면 기여를 나눈다.
|
||
- 쿠키 인증 프로필로 쓰기를 하면 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다.
|
||
- `commandEffect.refusedBeforeWrite`(쓰기 전에 나는 업무 거절 code 목록)는 `responseEnvelope: "ENVELOPE_V1"` operation에만 쓴다. `IDEMPOTENT_*`·`IDEMPOTENCY_*` code는 적을 수 없다.
|
||
|
||
두 다운스트림의 지금 descriptor는 앞의 넷을 지킨다. memento의 쓰기 프로필 `MEMENTO_BFF_WRITE`는 `x-xsrf-token`을, TechLog의 `TECH_LOG_STUDIO_SESSION`은 `x-csrf-token`을 요구한다. `responseEnvelope`가 없는 operation의 적용 여부는 지금처럼 `classifyProblem`이 정한다.
|
||
|
||
뮤테이션: `useApplicationMutation`은 `useServerStateScope()`의 scope를 담은 `BoundMutation`만 받는다. memento-web의 뮤테이션 8곳과 TechLog는 이미 그 모양이다. `operationId`·`requiresIdempotencyKey`는 `commandMutationIdentity(<descriptor>)`로 받을 수 있고, 그러면 오타를 타입 검사가 잡는다. `BoundMutation.owner`와 `QueryDefinition.owner`·`operationId`는 `@deprecated` 선택 칸이 됐고 다음 릴리스에서 지운다.
|
||
(1103/07-01, 1103/03-03, 1103/16-01, 1103/07-02, 1103/03-01, 1101/08-03, 1103/16-05, 1103/16-06)
|
||
5. **레지스트리 행과 기준선.**
|
||
- FE-REG-API 행은 설치된 기능의 모든 V3 descriptor에서 뽑는다(22칸). V2 API 행이 없던 기능도 descriptor마다 행이 새로 생긴다. memento-web은 29행이다.
|
||
- 각 행의 `requestSchema`·`responseSchema`·`problemSchema`는 FE-REG-SCHEMA 행을 가리켜야 한다. 그 기능의 `schemas`에 schemaId마다 행을 더한다. memento-web은 지금 라우트 행 7개뿐이라 43행(입력·응답 42, `MementoProblem` 1)을 더한다. 없으면 `check:registries`가 operation마다 `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>`로 실패한다.
|
||
- 행의 칸: `boundary`는 쓰인 자리대로 적는다(`api-request` 입력, `api-response` 응답, `api-problem` 실패 본문, `route-params`, `route-search`, `route-search-api-request`). `direction`은 입력이 `REQUEST`, 응답·실패 본문이 `RESPONSE`다. `unknownFieldPolicy`는 적으면 검증기 동작과 같아야 한다. `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 설치된 기능 전부를 대조한다.
|
||
- `runtime`은 `"zod"`만 받는다. 손으로 쓴 검증기를 그대로 두고 `"zod"`라고 적으면 행이 사실과 다르다. memento-web의 검증기는 `zodValidator(schemaId, schema)`(`src/contracts/zod-validator.ts`)로 옮긴다. 지금 검사하는 만큼(객체인지, `items`가 배열인지)만 옮겨도 된다. 일부러 검증하지 않을 칸은 `unvalidatedPayload(schemaId, reason)`로 바꾼다. 그 칸은 FE-REG-API 행의 `unvalidated`와 플랫폼 구성 화면에 드러난다. governance의 `runtime` 허용값을 제품 쪽에서 넓히지 않는다.
|
||
- 다 맞춘 뒤 기준선을 한 번 다시 승인한다. FE-REG-API governance가 바뀌어 동기화 직후 `check:registries`가 `contract-field-changed`로 실패하기 때문이다. `REGISTRY_BASELINE_OWNER=<owner> REGISTRY_BASELINE_REASON="<이유>" corepack pnpm update:registry-baseline`. 지금 diff와 맞지 않는 옛 breaking 증거 행도 이 명령이 지운다.
|
||
(1103/07-01, 1103/16-04, 1103/07-03, 1101/07-03, 0929/07-01)
|
||
6. **쓰는 곳이 있을 때만.**
|
||
- V2 HTTP 클라이언트와 V2 API 행에서 지운 이름(아래 `048f490`·`12f3bb7` 행). 두 다운스트림은 앱 코드에서 V2 클라이언트를 부르지 않는다. 부르는 곳은 템플릿의 `tests/unit/runtime-adapters.test.ts`뿐이고 그 파일은 템플릿 것으로 바뀐다.
|
||
- realtime: `BoundedPollOperationContract`를 지웠다. SSE·poll이 서버에 닿지 못한 실패는 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`이다.
|
||
- 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더, `tests/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`를 지우고 `corepack pnpm generate:feature-index`를 돈다. 지우기 전에 `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`가 사본에서 같은 삭제로 게이트를 돈다. 템플릿 문서가 지운 폴더를 계속 적어도 `verify:documentation`과 FE-GATE-005가 통과하는 것은 위 절의 수정부터다(1105/14-01). 그래서 두 절을 함께 받는다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다.
|
||
- 포트를 직접 구현한 코드: `OpfsJournalPort.countPartitionTransactions`·`removePartition`, worker gateway의 `removePartition`, `PublicCacheInspection.activePointer`가 필수 칸이다.
|
||
- offline-indexeddb recipe 타입: `src`와 이름이 같은 34개가 `src` 타입을 다시 내보낸다.
|
||
(1103/04-01, 1103/04-04, 1103/09-04, 1103/05-01, 0929/05-01, 1103/02-05, 0929/05-03)
|
||
7. **초기 JS 예산.** 예산은 gzip 204,800 B와 초기 파일 32개다(`config/performance/budgets.json`, merge 게이트 FE-GATE-012의 `check:bundle`). 템플릿 자체가 202,927 B와 파일 26개를 쓴다. 여유는 1,873 B다. 측정용 기능 복사본 하나를 같은 context에 더하면 +768 B, 새 context 하나는 +233 B다(`config/scale/feature-shape-ceilings.json`. `tests/unit/feature-shape-growth.test.ts`가 기능 1 KiB·context 512 B로 막는다). 제품 기능의 선언(라우트 표, 문구)은 초기 청크에 들어간다. memento-web(라우트 14개)과 기능 모듈로 바꾼 TechLog의 크기는 템플릿이 재지 않았다. `build` 뒤 `check:bundle`이 넘은 한도와 초과량을 적는다. 예산을 올릴 때는 `docs/operations/performance-evidence.md`대로 기준선·새 측정값·이유를 같은 변경에 적는다. 초기 파일 수는 HTTP/2 서빙이 전제다.
|
||
(1101/15-01, 1103/15-02, 1103/15-03, 1103/15-04, 1103/15-05)
|
||
|
||
#### 옮긴 뒤 확인
|
||
|
||
1. 로컬 merge 게이트 14개를 돈다(README "CI and evidence"의 반복문). `config/ci/product-gates.json`에 적은 `PRODUCT-GATE-NNN`은 workflow의 `product_merge_gate` job이 돈다.
|
||
2. 그중 이 묶음 때문에 먼저 볼 것:
|
||
- `check:registries`: `11 registries PASS`. 기준선을 다시 승인한 뒤에는 `compatibility=none`.
|
||
- `test:unit`: `schema-metadata-policy`, `env-registry-coverage`, `feature-shape-growth`, `documentation-readiness`(문서 검사. 참조 기능을 지운 제품도 통과한다).
|
||
- `test:component`: `layout-landmarks`, `context-layouts`.
|
||
- `build` 뒤 `check:bundle`: 예산 안.
|
||
3. merge 게이트 밖에서 한 번 돈다.
|
||
- `verify:documentation`(FE-GATE-017, documentation 단계). merge 단계에서는 FE-GATE-005의 `documentation-readiness`가 같은 스크립트를 돈다.
|
||
- `test:sample-removal -- --feature=<제품 기능 id>`: 그 기능을 지운 사본이 게이트를 통과한다. FE-GATE-020은 참조 기능만 지워 본다.
|
||
4. 배포가 있는 제품: FE-GATE-019는 TLS ALPN `h2`와 entry 응답의 `Content-Encoding`(br·gzip·zstd)을 요구한다. HTTP/1.1이나 압축하지 않는 호스트는 FAIL이다.
|
||
|
||
### 보안·계약 변경
|
||
|
||
#### 기능 구조와 조립
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] **BREAKING** | 기능을 선언(`feature-module.ts`)과 실행부(`feature-runtime.ts`)로 나눴다. 위 "먼저 할 일" 3단계. `ApplicationApi.features`에 `load(featureId)`가 생겼다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없다 (1101/15-01) | `src/features/`, `src/application/ports/in/application-api.ts`, `src/presentation/routes/`, `vite.config.ts`, `.dependency-cruiser.json` | `298201f` |
|
||
| [계약] **BREAKING** | 기능이 아닌 폴더의 표시는 `NOT_A_FEATURE`다. `NOT_INSTALLED`는 읽지 않는다. 표시와 `feature-module.ts`가 함께 있으면 생성기가 실패한다 (1103/09-09) | `scripts/generate-product-feature-index.ts`, `src/features/*/NOT_A_FEATURE` | `9edc830` |
|
||
| [계약] | 제품 코드는 템플릿 파일이 아니라 제품 소유 파일에 둔다. `src/bootstrap/product-composition.ts`(capability, 인증 프로필별 자격증명 provider, `composeProductSessionOwner`, 선택 `onCredentialRejected`·`scopeParticipants`), `src/contracts/product-contracts.ts`(제품 인증 프로필, 런타임 설정 키, 그 FE-REG-ENV 행), `src/features/product-capabilities.ts`(capability 타입 `ProductFeaturePlatformCapabilities`, 선택 런타임 `PRODUCT_RUNTIME_CAPABILITY_SELECTION`). 자격증명 순서는 scope fence → ANONYMOUS → 제품 provider → 세션 → fence 재확인이다. 제품 설정 키는 `.default()`나 `.optional()`이어야 템플릿 테스트가 통과한다 (1101/09-02, 1103/09-02, 1103/09-05) | `src/bootstrap/product-composition.ts`, `src/bootstrap/product-composition-contract.ts`, `src/contracts/product-contracts.ts`, `src/features/product-capabilities.ts`, `src/features/installed-runtime-capabilities.ts` | `da1e128`, `ece944d`, `245f428`, `2f6df14`, `2963c6f` |
|
||
| [계약] | 런타임 설정 키마다 FE-REG-ENV 행이 있어야 하고, 행의 `required`·`defaultValue`가 스키마와 같아야 한다(`tests/unit/env-registry-coverage.test.ts`). 템플릿 행 `RELEASE_ID`·`BUILD_ID`를 더했고 `TELEMETRY_ENABLED`·`AUTH_MODE`·`RELEASE_MANIFEST_URL`·`CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` 행을 스키마에 맞췄다. `defaultValue`는 객체일 수 있다 (1101/09-02, 1103/13-04) | `src/contracts/env.ts`, `config/contracts/registry-governance.json`, `tests/unit/env-registry-coverage.test.ts` | `d0414c8`, `a144b57` |
|
||
| [계약] | 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 기능은 `undefined`를 받는다 (1103/09-08) | `src/features/feature-adapter-contribution.ts` | `e7d6358` |
|
||
| [계약] | 기능 계약이 route id `APP_HOME`을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. `src/contexts/<context>/context-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `<main id="main-content" tabIndex={-1}>` 하나를 그려야 하고, `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 실행해 본다 (1101/09-03) | `src/contracts/routes.ts`, `src/contexts/bounded-context-module.ts`, `scripts/generate-product-feature-index.ts`, `tests/component/layout-landmarks.test.tsx` | `ca16187`, `27f4523` |
|
||
| [계약] | 앱 조립이 닿지 않는 기능 라우트를 앱 모듈을 평가할 때 throw로 거절한다. 소유 context 루트 밖의 라우트, 계약에 없는 route handle, 플랫폼 라우트가 먼저 받는 경로, 다른 기능과 같은 경로(파라미터 이름만 다른 것과 대소문자·끝 슬래시만 다른 것 포함)다. 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands)도 거절한다 (1101/09-06, 1101/09-07, 1103/08-04, 1101 README 14.4) | `src/apps/deployable-app-module.ts`, `src/contexts/bounded-context-module.ts`, `src/bootstrap/` | `7139c7c`, `d6e4e51`, `7d85589`, `8469554`, `851fded`, `48a4074` |
|
||
| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더, 그 테스트 폴더, context를 지운다(위 "먼저 할 일" 6단계). `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` |
|
||
| [계약] | 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능만 하나 쓸 수 있다. 다른 출처 종류는 `unknown contribution source kind`로 거절한다 (1101/07-04) | `src/contracts/external-contract-runtime.ts` | `c063389` |
|
||
| [계약] **BREAKING** | `useApplicationMutation`은 raw `{ execute, definitionId }`를 받지 않는다. `useServerStateScope()`의 scope로 만든 `BoundMutation`을 넘기고 `execute(input, { signal, intent })`로 부른다. `commandMutationIdentity(<descriptor>)`가 `operationId`·`requiresIdempotencyKey`를 descriptor에서 준다. `QueryDefinition.owner`·`operationId`와 `BoundMutation.owner`는 아무도 읽지 않아 `@deprecated` 선택 칸으로 바꿨고 다음 릴리스에서 지운다. raw query는 남았다. 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기) (1101/08-03, 1103/16-05, 1101/03-03, 1103/16-06) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/adapters/query/` | `1fa5f3e`, `f59a806`, `68f94f5` |
|
||
|
||
#### HTTP와 계약
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] **BREAKING** | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(`src/adapters/http/index.ts`)에서 `createHttpClient`, `HttpClient`, `HttpClientDependencies`, `HttpFailure`, `HttpResult`, `LegacyHttpInput`, `Scheduler`, `OperationRequestInput`가, `src/bootstrap/runtime-adapters.ts`에서 `createRuntimeHttpClient`, `RuntimeHttpContract`가 없어졌다. 지운 파일: `client.ts`, `bounded-json.ts`, `request-builder.ts`, `resource-mapper.ts`, `retry-policy.ts`, `schema-registry.ts`(`src/adapters/http/`). Envelope 스키마는 `backend-envelope.ts`에 있다. V2 클라이언트를 부르는 코드는 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다 | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `048f490` |
|
||
| [계약] **BREAKING** | 기능마다 적던 V2 API 행을 지웠다. FE-REG-API 행은 contract contribution의 V3 descriptor에서 뽑는다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`, 22칸: operation·경로·인증·재시도 의미·본문 모양·Envelope·스키마 세 개·`acceptedStatuses`·`emptyBodyStatuses`·`unvalidated`·바이트 상한 둘·`totalDeadlineMs`·`retryBudget`·`traffic`·`commandEffect`·`commandRecovery`). `problemSchema`도 FE-REG-SCHEMA를 참조하고, 그 행의 `boundary`는 새 값 `api-problem`이다. `problemSchema`·`unvalidated` 변경과 status 값 제거는 breaking이다. `FeatureRuntime`은 `apiContract` 대신 `schemas`(FE-REG-SCHEMA 행)를 받는다. 지운 이름: `defineRestOperation`, `ApiOperation`, `RestOperationV2`, `composeApiOperations`, `validateApiRuntimeBindings`, `getApiOperation`, contracts의 `API_OPERATIONS`; `rest-profiles.ts`의 `createRestProviderProfile`, `RestProviderProfile`, `resolveRestSecurityProfiles`, `validateRestProfileBindings`, `REST_CSRF_PROFILES`, `RestCsrfProfile`; `loaded-feature-runtimes.ts`의 `RUNTIME_SCHEMA_CODECS`, `MAPPER_REGISTRY`, `REST_PROFILE_BINDINGS_VALID`, `API_RUNTIME_BINDINGS_VALID`. realtime `apiOperations` 바인딩은 `ApiOperationRow`를 받고, snapshot operation을 `method: "GET"`과 `SAFE`·`IDEMPOTENT`로 본다. 옮기는 법은 위 "먼저 할 일" 3·5단계 (1103/07-01, 1103/16-04) | `src/contracts/api-operations.ts`, `src/contracts/schema-registry.ts`, `src/features/feature-module.ts`, `src/features/installed-feature-runtime-registries.ts`, `config/contracts/`, `scripts/create-feature.ts` | `12f3bb7`, `08ed0a0`, `3b40f73` |
|
||
| [계약] **BREAKING** | 재시도 의미를 조립 때 검사한다. GET·HEAD는 `SAFE`·`IDEMPOTENT`만, POST·PUT·PATCH·DELETE는 `SAFE`를 쓸 수 없다 (1103/07-01, 1103/03-03) | `src/contracts/external-contract-runtime.ts` | `e4caafd`, `61f70cb` |
|
||
| [계약] | 계약 기여 하나 안의 operation이 서로 다른 `responseEnvelope`를 읽으면 조립이 거절한다. 두 백엔드는 기여를 나눈다 (1103/16-01) | `src/contracts/external-contract-runtime.ts` | `3f7e10c` |
|
||
| [보안] [계약] | 쿠키 인증 프로필(`SAME_ORIGIN_COOKIE`)로 쓰기(GET·HEAD 밖)를 하는 operation은 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다. 아니면 조립이 거절한다. POST·PUT·PATCH·DELETE × 두 헤더 표로 테스트한다 (1103/07-02) | `src/contracts/external-contract-runtime.ts` | `365d8c3`, `a94006b` |
|
||
| [계약] | V3 descriptor의 선택 칸 `responseEnvelope: "ENVELOPE_V1"`이면 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. `meta.requestId`·`traceId`는 선택이다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가). `create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능과 값이 없는 descriptor는 DTO와 problem details를 읽는다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` |
|
||
| [계약] | Envelope operation의 400·409·422와 백엔드가 정한 5xx 넷은 `classifyProblem` 대신 백엔드 기준 표(`backend-envelope.ts`, 근거는 계약 문서 6.1절)가 정한다. 적용 안 됨(`NOT_APPLIED`)은 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH`와 그 operation의 `refusedBeforeWrite` code다. 그 밖의 400·409·422는 결과 불명이다. 503 `IDEMPOTENCY_UNAVAILABLE`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, 500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 503 `REQUEST_TIMEOUT`은 분류기와 상관없이 결과 불명이고 키를 지킨다. KEYED operation은 503 `IDEMPOTENCY_UNAVAILABLE`을 `retryBudget` 안에서 같은 키로 다시 보낸다. 필드 목록이 있는 거절은 `VALIDATION_REJECTED`와 필드 오류, 필드 목록 없는 422는 `UNKNOWN_CLIENT_FAILURE`다. 진단은 두 멱등성 거절에 `reason`을 싣는다 (1101 README 14.4, 1103/03-04, 1103/08-05) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/http-execution-v3.ts`, `docs/architecture/backend-api-and-server-state-contract.md` | `3261208`, `c05f41a`, `3761507`, `613c1cf` |
|
||
| [계약] | `CommandEffectDescriptor.refusedBeforeWrite`(선택, Envelope operation 전용): 그 엔드포인트가 쓰기 전에만 내는 업무 거절 code. 적은 code의 400·409·422는 `NOT_APPLIED`라 폼에서 값을 고쳐 다시 저장할 수 있다. 멱등성 code를 적거나 Envelope가 아닌 operation에 적으면 조립이 거절한다 (1103/03-01) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/backend-envelope.ts`, `src/contracts/api-operations.ts` | `1e8b3d0`, `3fba68b` |
|
||
| [계약] | 짝 백엔드 계약 기준점을 기계가 읽는다. `config/contracts/backend-contract-pin.json`(백엔드 `45d2a478`)과 백엔드 `docs/web/http-contract.md` §2 답 표(`config/contracts/backend-idempotency-answers.json`)를 `tests/unit/backend-contract-pin.test.ts`가 프론트 판정 표와 대조한다. `check:backend-contract-drift --backend <백엔드 checkout>`(로컬, 게이트 밖)이 pin 뒤의 백엔드 변경을 알린다 (1103/12-06) | `config/contracts/`, `scripts/check-backend-contract-drift.ts`, `src/adapters/http/backend-envelope.ts` | `ba2b4f4`, `5379c80` |
|
||
| [계약] | 성공 결과에 Envelope `meta.page`가 `page`로 실리고, `mapSuccess` 두 번째 인자 `FeatureHttpSuccessContext { page }`로 받는다(배럴 `EnvelopePage`). bulk `results`는 지원하지 않는다. 실패 Envelope의 `meta.traceId`는 `AppFailure.traceId`가 된다. 실행 결과의 선택 칸 `sentRequestId`: 서버가 `x-correlation-id`를 돌려주지 않으면 `AppFailure.requestId`는 보낸 값이고, 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (1103/03-02, 1103/03-06, 0929/03-04) | `src/adapters/http/` | `49a0986`, `631ce33`, `849d000` |
|
||
| [계약] | 결과 불명 쓰기의 진단·텔레메트리에 `effect_certainty`가, 진단 `reason`에 `UnknownEffectReason`이 실린다 (1103/03-05) | `src/adapters/http/`, `config/contracts/` | `39c1de2` |
|
||
| [계약] | 키 없는(`NEVER`) 결과 불명 요청에는 "같은 요청으로 다시 보내기"가 없다. mutation 컨트롤러 `canResendUnknownEffect`, `AsyncState.unknownEffectResendable`. 처리 중 409의 `Retry-After`는 `retryAfterMs`로 실리고, 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다 (0929/03-03, 백엔드 리뷰 1101/02-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/components/async-surface.tsx` | `2017ef7`, `47fec5c` |
|
||
| [계약] | 전송 전 거절의 원인이 진단에 남는다. 연결 실수·멱등 키 위반은 `UNKNOWN_CLIENT_FAILURE`이고 화면 문구는 "요청을 처리할 수 없습니다."다 (1101/03-02) | `src/adapters/http/` | `4da0466` |
|
||
| [계약] | 참조 기능의 생성 분류기가 409를 problem code로 나눈다. 선언한 충돌 code(`CONFLICT`)만 적용 안 됨이고, `IDEMPOTENT_IN_FLIGHT`·code 없는 409·모르는 409는 결과 불명이라 다음 전송이 같은 멱등 키를 쓴다 (0929/03-01) | `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` | `112c870` |
|
||
| [계약] | 인증 프로필 `REFERENCE_EXTERNAL_BEARER`의 새 이름은 `EXTERNAL_BEARER`다. 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남는다. `CREDENTIAL_HEADER_NAMES`에 짝 백엔드 CSRF 헤더 `x-xsrf-token`을 더했다 (1101/16-03, 1101/09-02) | `src/contracts/rest-profiles.ts` | `6c5818f`, `183a4a3` |
|
||
| [계약] | `zodValidator`(`src/contracts/zod-validator.ts`)가 zod 스키마를 `RuntimeValidator`로 바꾼다. 검증을 일부러 생략할 때는 `unvalidatedPayload(schemaId, reason)`를 쓴다. `listUnvalidatedPayloads(composed)`가 생략 목록을 만들어 플랫폼 구성 화면이 보여 준다 (1101/07-03) | `src/contracts/zod-validator.ts`, `src/contracts/unvalidated-payload.ts` | `d3ddc89`, `8b7c6eb` |
|
||
| [계약] | 폐기 별칭 `MappingResult`(`boundary-mapper.ts`)와 `ApiFailure`(`errors.ts`)는 export로 남지만 lint가 `src`·`tests`의 import를 막는다. `BoundaryMappingResult`, `AppFailure`로 바꾼다 (1101/07-01) | `eslint.config.ts`, `src/contracts/boundary-mapper.ts`, `src/contracts/errors.ts` | `fc303d8` |
|
||
|
||
#### 레지스트리
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | breaking 증거(`config/contracts/registry-change-evidence.json`)에 `after`가 필요하고 diff의 after 값과 같아야 한다. 지금 diff와 맞지 않는 증거 행은 `check:registries`가 적고 실패하며, `update:registry-baseline`이 그런 행을 지운다 (0929/07-01) | `scripts/lib/registry-compatibility.ts`, `scripts/update-registry-baseline.ts`, `docs/operations/ci-quality-gates.md` | `5e6be9a`, `4ada84e` |
|
||
| [계약] | 분류기가 덜 깐깐해졌다. 선언 타입 안의 null ↔ 값 전환은 `breakingFields`로 등급을 정하고(보통 behavior-change), `allowedValues`에 값을 더하기만 하면 additive다. 무효화 그래프에 원소를 더하기만 한 변경도 additive다. 빼거나 바꾸면 그대로 breaking이다 (0929/07-02) | `scripts/lib/registry-compatibility.ts`, `scripts/check-registries.ts` | `82c9e59`, `605fd17` |
|
||
| [계약] | FE-REG-ROUTE가 `paramsSchema`·`searchSchema`를 허용 목록으로 보지 않고, `loadingSurface`는 kebab-case 형식만 본다. 기능 라우트를 더해도 governance를 고치지 않는다. 다운스트림은 목록에 더해 둔 값을 지운다 (0929/07-03) | `config/contracts/registry-governance.json`, `scripts/check-registries.ts` | `e8d7fb4` |
|
||
| [계약] | `StorageBackend`에 `"external"`이 생겼다. cross-context pulse 키는 외부 소유라 StoragePort로 읽고 쓰면 `*_UNAVAILABLE`로 거절된다. exhaustive switch는 분기를 더한다 (1101/05-01) | `src/contracts/storage-keys.ts`, `config/contracts/` | `e98a980`, `65ea208` |
|
||
| [계약] | 진단 `ui.render.failed`의 `route_id`: 등록 라우트가 없는 URL의 적재 실패는 `NOT_FOUND` 대신 `UNREGISTERED_ROUTE`, 복구하지 못한 context 라우트 청크 실패는 context id 대신 그 라우트 id다. 이 값으로 거르는 대시보드·알림은 고친다 (1101 README 14.3) | `src/presentation/routes/`, `src/contracts/routes.ts` | `7c8cb19` |
|
||
|
||
#### 세션·인증
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | 401은 그 요청의 자격증명을 낸 쪽에만 알린다. 템플릿 세션이 낸 자격증명의 401만 세션을 로그아웃시키고 캐시를 비운다. ANONYMOUS 요청과 제품 provider 요청의 401은 `ProductComposition.onCredentialRejected`(선택)로 간다 (1103/09-01) | `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/product-composition-contract.ts` | `0aada28` |
|
||
| [계약] | 인증 프로필이 ANONYMOUS인 요청은 세션 상태와 상관없이 자격증명 없이 나간다. 전에는 어느 세션 상태에서도 보내지 않았다 (1101/09-01) | `src/bootstrap/runtime-adapters.ts` | `ddf411e` |
|
||
| [계약] | `ProductSessionOwnerContext`에 `fetch`(필수. 마감 `REQUEST_TIMEOUT_MS`, 본문 64 KiB, redirect 거부), `page`(`href`, `replaceUrl`, `assign`), `redirectStorage`, `readCookie`가 생겼다. 짝 백엔드 두 인증 모드의 owner recipe는 `recipes/session-owners/`(`oidc-pkce-session-owner.ts`, `cookie-session-owner.ts`)이고 매뉴얼은 `docs/manual/04-paired-backend-session.md`다. `src`가 이 recipe를 import하면 `check:optional-recipes`가 `PRODUCTION_IMPORTS_RECIPE`로 거절한다 (1103/09-03) | `src/bootstrap/product-composition-contract.ts`, `recipes/session-owners/`, `scripts/check-optional-recipes.ts` | `d02efe7`, `05958bb`, `f3fd10f` |
|
||
| [계약] | 세션 상태 전이: 복구 성공은 authenticated, no-session은 unauthenticated(또는 integration-failed), 거절은 상태 유지다. "세션 복구" 화면은 no-session이면 로그인 버튼을 보인다 (1103/09-11) | `src/adapters/auth/external-session-adapter.ts`, `src/presentation/providers/session-provider.tsx` | `d7c6cb4` |
|
||
| [계약] | `ProductComposition.scopeParticipants`(선택): 로그아웃·계정 전환 때 FENCED와 READY 사이에서 닫을 제품 자원. 닫기가 실패하면 READY로 가지 않는다. 예시는 `recipes/frontend-capabilities/browser-file-session-capability.ts` (1103/02-01) | `src/bootstrap/product-composition-contract.ts`, `src/bootstrap/runtime-adapters.ts`, `recipes/frontend-capabilities/` | `f485e51` |
|
||
|
||
#### 저장소·파일·전송
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | OPFS journal 목록이 손상 행을 건너뛰고 `corruptRows`로 센다. reconcile은 `corruptTransactions`, 소속 partition이 없는 손상 행은 선택 칸 `unattributedRows`·`unattributedCorruptTransactions`로 따로 세고 DEGRADED 관측에서 뺀다. 승인된 LOGOUT·ACCOUNT_DELETION purge는 끝나지 않은 행을 보면 진행 중인 put을 기다린 뒤 partition을 지우고 `partitionDeleted`를 보고한다. partition 삭제는 partition Web Lock으로 다른 탭의 put과 겹치지 않는다. `OpfsJournalPort`의 `countPartitionTransactions(scope)`·`removePartition`과 worker gateway `removePartition`은 필수 메서드다 (0929/05-01, 1103/05-01, 1103/05-03) | `src/adapters/storage/opfs/`, `src/application/ports/browser-file-storage/` | `72edb55`, `e5b7b3e`, `d13a393`, `fd6b631` |
|
||
| [계약] | OPFS partition lock을 기다리는 put·remove는 자기 abort로 `ABORTED`, `mutationLockWaitTimeoutMs`를 넘으면 `BLOCKED`(retryable)다. 정책의 `putIdleTimeoutMs`가 `mutationLockWaitTimeoutMs` 이상이면 조립이 거절한다 (1103/05-02, 0929/05-09) | `src/adapters/storage/opfs/` | `7b55f0f`, `f6b74ed` |
|
||
| [계약] **BREAKING** | recipe의 browser-file·OPFS·storage durability·cache 타입 중 `src`와 이름이 같은 34개는 `src` 타입을 다시 내보낸다. fake는 `src` port를 구현하고 `BrowserDataResult`를 돌려준다. `MemoryDurableObjectStore` 생성자가 바뀌었고 `DurableObjectDataClass`·`DurableObjectIntegrity`·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 지웠다. 이 fake의 reconcile은 `FILES_READY` put을 runtime처럼 commit하고 LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지운다. offline-indexeddb recipe를 쓰는 프로젝트만 해당 (0929/05-03, 1103/05-04) | `recipes/frontend-capabilities/` | `e1a4580`, `36ff633` |
|
||
| [계약] | `PublicCacheInspection.activePointer`가 필수 칸이다. 손상 pointer에서도 inspect가 상태와 후보를 보여 준다. 포트를 직접 구현한 쪽은 채운다 (1103/02-05) | `src/adapters/cache-storage/public-response-cache-adapter.ts`, `src/application/ports/browser-file-storage/cache-storage-ports.ts` | `7e7614f` |
|
||
| [보안] | download 정책의 `safeExtension`이 위험 확장자이거나 그것으로 끝나면 조립이 거절한다 (1101/02-02) | `src/adapters/browser-files/` | `4f78890` |
|
||
| [계약] | 업로드 part 발급·PUT이 서버의 `Retry-After`를 기다린다. `maxRetryAfterMs`를 넘으면 다시 보내지 않고 `upload()`·`abort()`가 `RESUME`·`retryable: false`를 준다. 실패 결과에 대기 시간이 붙도록 포트 반환 타입이 넓어졌다(추가만). upload 실패 번역은 HTTP 상태와 code로 recovery를 고르고, part 발급(BFF)의 401/403은 `NONE`(`retryable: false`)이다. file-transfer recipe를 쓰는 프로젝트만 해당 (1101/01-01, 1103/01-02, 0929/01-01) | `src/adapters/browser-transfer/` | `95e4445`, `c695898`, `9142390`, `c5f87aa` |
|
||
|
||
#### realtime·Service Worker·Web Push
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] **BREAKING** | `BoundedPollOperationContract`(V2 어휘)를 지웠다. `createBoundedPollCoordinator`의 operation과 `assertBoundedPollOperation`의 둘째 인자는 V3 descriptor(`BoundedPollOperation`)다. 조립된 행을 넘기고, `frontend.retryBudget` 0인 poll 전용 operation을 등록한다. 0이 아니면 생성 때 거절한다 (1103/04-01) | `src/adapters/realtime/` | `a65df74` |
|
||
| [계약] **BREAKING** | SSE의 fetch·reader 거절과 bounded poll의 execute 거절은 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`(retryable)로 끝난다. 브라우저가 online이면 online 이벤트를 기다리지 않고 backoff로 다시 시도하고 상한에서 끝난다. poll은 이 범위 끝에서 던지는 execute를 lease 안에서 다시 시도했다. 위 절에서 다시 바뀌어, 던지는 execute는 재시도 없이 `PROTOCOL_MISMATCH`로 끝난다(1105/04-02). `OFFLINE`은 환경 신호에서만 나온다 (1103/04-04, 0929/04-01) | `src/adapters/realtime/` | `af00067`, `4d27b20` |
|
||
| [계약] | stream coordinator와 live-poll handoff coordinator의 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`·`PROVIDER_UNAVAILABLE`로 나온다. stream coordinator의 `RealtimeObservation.reason`도 같다. `IDLE_TIMEOUT`은 전송 idle에만 쓴다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts`, `src/adapters/realtime/` | `1196b86`, `17fa8d1` |
|
||
| [계약] | realtime 배럴이 결과 생성 함수 `realtimeSuccess`·`realtimeFailure`를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) | `src/adapters/realtime/index.ts` | `3fe28de` |
|
||
| [계약] | Service Worker 빌드가 `public/`을 다시 복사하지 않는다(`publicDir: false`). 전에는 SW를 켠 빌드의 `dist/config.json`이 local 문서로 덮어써졌다 (0929/06-01) | `vite.service-worker.config.ts`, `scripts/build-frontend.ts` | `c7b9cb8` |
|
||
| [계약] | 라우터 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` |
|
||
| [보안] | Web Push registry가 URL로 해석하면 바뀌는 path(`..`, `%2e%2e`, `.`)를 생성 때 거절한다 (1103/06-02) | `src/adapters/web-push/` | `a145f30` |
|
||
|
||
#### 화면·문구·디자인 시스템
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | `check:design-system` 규칙 4개: 두 테마에서 `--color-focus`가 표면 토큰 8종 모두와 3:1 이상, `color-mix()`는 `in oklab`만, 계약의 컴포넌트 토큰은 스타일 하나 이상이 `var(--name)`으로 읽음, `--font-sans` 첫 글꼴은 기본 키워드이거나 `@font-face`로 싣는 글꼴이거나 `PRODUCT_LOADED_FONT_FAMILIES`(`token-contract.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`, `src/presentation/design-system/tokens/token-contract.ts` | `35b183b`, `bfa7dd9`, `165ed19`, `8576ce1`, `49d8675`, `e714c0d`, `b4ccada` |
|
||
| [계약] | 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` |
|
||
| [계약] | `MessageArguments<Key>`가 catalog 문자열의 `{이름}`에서 파라미터를 만든다(값은 string 또는 number). `check:i18n`은 catalog parity와 raw backend 메시지만 보고, 화면 문구 literal은 ESLint `screenTextSelectors`가 잡는다(template literal·삼항식·객체 prop 문구는 못 본다) (0929/08-03, 0929/08-02) | `src/presentation/i18n/message-contract.ts`, `eslint.config.ts`, `scripts/check-i18n.ts` | `ff33d58`, `855d22a` |
|
||
|
||
#### 빌드·배포·CI
|
||
|
||
| 표시 | 변경 | 영향 경로 | 커밋 |
|
||
|---|---|---|---|
|
||
| [계약] | 번들 예산 게이트 FE-GATE-012가 merge 단계에서 돈다. 예산은 gzip 204,800 B와 초기 파일 32개(`initialJsFiles`, 템플릿 26개 + 기능 여유)다. `check:bundle`은 넘은 한도와 초과량을 적고, `bundle.json`에 `initialJsFiles`·`initialFilesPassed`가 있다. 초기 JS 기준선은 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`(지금 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B)이고 `test:unit`이 빌드와 대조한다 (1101/15-01, 1103/15-05, 1103/15-03, 1103/15-02, 1103/15-04) | `config/ci/gates.json`, `config/performance/budgets.json`, `scripts/check-bundle.ts`, `config/scale/` | `f41e3d5`, `46dfe23`, `2fef27d`, `c9e7bab`, `f887817` |
|
||
| [계약] | 호스팅 계약: 파일이 없는 모든 경로에 그 release의 `index.html`을 HTML 헤더로 준다(SPA fallback, `appRoute`). 워커를 싣는 빌드의 `service-worker.js`는 `no-cache`다. live probe는 사전 캐시 확장자마다 `Content-Type`을 확인한다. nginx 예시는 `docs/operations/release-cache-rollback.md` (1101/13-04, 1103/06-03) | `config/hosting/cache-policy.json`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts` | `629c8f0`, `0f58abb` |
|
||
| [계약] | FE-GATE-019(production 단계)는 workflow의 `deployment` 슬롯이 배포한 승격 release를 본다. 슬롯이 비어 있으면 `UNVERIFIED`다. 배포된 `release-manifest.json`의 buildId·releaseId, `config.json`(비상 스위치 제외), `index.html` entry가 후보와 다르면 FAIL이다. TLS ALPN `h2`와 entry `Content-Encoding`(br·gzip·zstd)을 요구한다(`config/hosting/cache-policy.json`). HTTP/1.1이나 비압축 호스트는 FAIL이다. nginx 예시가 http2·gzip을 켠다 (1101/13-01, 1103/13-01, 1103/13-02) | `.gitea/workflows/quality-gates.yml`, `config/ci/gates.json`, `config/hosting/cache-policy.json`, `scripts/verify-hosting-headers.ts` | `de379ea`, `4bce8bf`, `2e12d2f` |
|
||
| [계약] | 제품 소유 `config/ci/product-gates.json`: 배포(`deployment`, package script와 `vars.*`·`secrets.*` 바인딩)와 제품 merge 검사(`PRODUCT-GATE-NNN`, job `product_merge_gate`). 템플릿은 승격 후보를 받아 `CANDIDATE_ARCHIVE_SHA256`으로 확인하고 푸는 단계를 만든다. 배포 슬롯은 `gates.json`이 아니라 여기서 채운다 (1103/12-07, 1103/13-01) | `config/ci/product-gates.json`, `scripts/contracts/product-ci-overlay.ts`, `scripts/generate-ci-workflow.ts` | `4c4248a`, `2e12d2f` |
|
||
| [보안] | 배포 슬롯의 `secrets.*`는 deploy 단계 env에만 간다 (1103/13-05) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts` | `2e12d2f` |
|
||
| [계약] | staging·production 승인(FE-GATE-027)이 `example.com`·`example.net`·`example.org`와 그 하위 도메인, `.example`·`.invalid`·`.test` endpoint와 자리표시자 계약 신원(digest `PLACEHOLDER_CONTRACT_PACKAGE_DIGEST`)을 거절한다. `findAdmissionViolations`가 세 번째 인자로 계약 패키지를 받는다. CI에서 endpoint는 `config/runtime/<profile>.json`에 커밋한다 (1101/13-02, 1101/16-01) | `src/contracts/deployment-admission.ts`, `scripts/check-release-admission.ts` | `7b34756`, `1269992` |
|
||
| [보안] | release 단계 FE-GATE-027이 `scan:dependency-advisories`로 의존성 advisory를 템플릿 정책에 따라 판정해 남긴다(막지 않음). `renovate.json`을 더했다. 개발 의존성의 high·critical advisory를 범위 안에서 고쳤다(storybook 10.6.5, vite 8.1.6, vitest 4.1.12) (1103/13-03) | `scripts/scan-dependency-advisories.ts`, `renovate.json`, `package.json`, `pnpm-lock.yaml` | `eeb6f92`, `26ca2fd` |
|
||
| [보안] | provider 샌드박스가 `.git` 파일(worktree·서브모듈)을 `/dev/null` 읽기 전용 bind로 가린다. worktree에서도 `test:system`이 돈다 (1103/11-04) | `scripts/run-and-validate-provider.ts` | `0edc3fc` |
|
||
| [계약] | `create:feature <id> [--context <ctx>] [--with-create [--keyed]] [--package <name@version> --digest <sha256> --revision <hex>]`가 기능 뼈대를 만든다. 목록 경로는 짝 백엔드 `new-feature.sh`와 같은 `/<plural>`이고 결과 수는 `meta.page.total`이다. `--with-create`는 짝 백엔드 생성기와 같은 상세 GET·작성 POST(기본 `NEVER`, `--keyed`면 `KEYED`)·폼·결과 불명 화면·백엔드 본문 테스트를 더한다. FE-GATE-020의 `test:feature-scaffold`는 생성한 기능으로 `gates.json`의 merge 단계 명령을 돌고(브라우저 게이트·`test:system`·`verify:lockfile`·제거 드릴은 이유와 함께 뺀다) 그 기능의 제거 드릴도 돈다 (1101/16-01, 1103/03-07, 1103/09-06, 1103/12-02, 1103/16-02) | `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `scripts/test-feature-scaffold.ts`, `config/ci/gates.json` | `d166aa3`, `2ec9d56`, `e1b4e28`, `7411d4a` |
|
||
| [계약] | `verify:documentation`(FE-GATE-017)이 입구 문서 4개의 src 최상위 폴더 설명과 `layers.md`의 아키텍처 규칙 이름을 검사한다(`sourceStructure`). `docs/README.md` 1절 현재 계약 문서의 repo 경로·명령 안 경로·링크·package script·FE-GATE ID와 짝 백엔드 참조를 검사한다(`documentReferences`, 짝 저장소가 옆에 없으면 `unverifiedLinks`). 수동 접근성 범위는 라우트별 기록 파일로 검사한다. 참조 기능 경로와 그 전용 script는 문서에 백틱 없이 적어, 참조 기능을 지워도 통과한다 (1101/14-03, 1101/14-05, 1103/12-05, 1103/14-04) | `scripts/verify-documentation-readiness.ts`, `docs/README.md`, `docs/manual/` | `61baf96`, `16202fd`, `b4e4f98`, `c4d5870`, `fd11d08` |
|
||
| [계약] | 규모 설계서는 `docs/architecture/scale-architecture.md`(현재 계약, 절 번호 유지)다. 코드 주석 `Spec §N`은 `scale-architecture.md §N`이고, 문서 이름 없는 `spec §` 참조는 `tests/unit/deletable-history-documents.test.ts`가 막는다. `docs/reviews/adapters/`는 지울 수 있는 기록이 아니다 (1101/14-01) | `docs/architecture/scale-architecture.md`, `README.md`, `docs/README.md` | `0a7fbed`, `b26517e` |
|
||
| [계약] | 쓰지 않는 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` | `98b9682` |
|
||
| [계약] | Vitest가 CI에서 skip·todo·only가 남은 실행을 실패시킨다(`-t`나 `file:line`으로 좁힌 실행은 제외). quarantine 주석이 붙은 skip도 실패한다 (1101/10-04) | `vitest.config.ts`, `tests/support/` | `95e7d11` |
|
||
| [계약] | 시각 테스트: `tests/visual/fonts.conf`로 글꼴을 고정하고 스크린샷 전에 실제 글꼴을 검사한다(Linux 전용). CI 브라우저 설치 단계가 글꼴 4종(`fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`)을 설치한다. 허용치는 절대 50 px다. 골든은 설치된 기능의 링크·목록·계약 다이제스트를 가리고 찍어, 기능을 더해도 다시 찍지 않는다 (1101/11-02, 1103/11-02, 1101/11-03, 1103/12-01) | `tests/visual/`, `playwright.visual.config.ts`, `.gitea/workflows/quality-gates.yml` | `08b5ccc`, `b0195e3`, `5ce3db9`, `0a6ff6e` |
|
||
| [계약] | 레시피 번들 예산: file-transfer 57,800, offline-indexeddb 38,500, realtime 42,200, service-worker-pwa 10,100 B. 측정값 + 3%를 100 B 단위로 올린 값이고, 3%를 넘는 증가는 커밋 본문에 이유를 적는다. 규칙은 `docs/architecture/optional-adapter-recipes.md` (0929/05-04) | `config/recipes/frontend-capability-recipes.json` | `313f9ba` |
|
||
|
||
### 그 밖의 수정
|
||
|
||
- 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음, `--font-sans`가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가 `--field-border`를 읽음 (UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, UI-08, 1101/12-01)
|
||
- 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서 `getByText`로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-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)
|
||
- 폼: 짝 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등 20개)마다 문구가 있다. 모르는 code는 기본 문구다 (`8a09c90`, 1101 README 14.4). `constructor` 같은 필드 code는 기본 문구다 (1103/08-03). 키보드 저장이 결과 불명·429 등 필드 오류가 아닌 실패로 끝나면 포커스가 실패 상태로 간다(`FormPage` `feedbackId`, 저장 버튼 pending) (1103/08-02)
|
||
- 진단: context·feature 오류 경계와 라우트 모듈 실패가 진단에 남고 지원 참조가 `build:incident` 형식이다 (1101/09-09). 계약 조립 오류 메시지가 `reason`을 싣는다 (1103/09-07). 문제 응답 분류기 실패는 `CLASSIFIER_FAILED` (1101/03-05). 어느 무효화 topic도 닿지 않는 조회 namespace를 진단으로 한 번 알린다 (1101/03-01)
|
||
- 저장소: 진단 `storage.operation.failed`에 `reason`이 붙는다 (1101/05-02). lifecycle 리스너 주인 규칙과 테스트 (1101/05-03). OPFS purge가 객체를 못 지우면 완료와 chunk sweep을 보고하지 않는다 (0929/05-02). 여러 페이지를 다 지운 purge는 한 번에 끝났다고 보고한다 (`c4052f0`, 1101 README 13.6)
|
||
- 브라우저 파일·캐시: preview·download의 dispose가 자기 lease만 푼다 (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). Cache Storage 활성화의 본문 읽기 일시 오류는 손상이 아니라 `UNAVAILABLE`·`RETRY`다 (1103/02-02). browser-files vault에서 inspect 중에 놓은 ref는 `NOT_FOUND`·`RESELECT`다 (1103/02-04)
|
||
- 전송: 재조정에서 checkpoint 삭제가 실패해도 `upload()`가 `resourceId`를 준다 (0929/01-02). `FILE_BYTE_SOURCE` 이어 올리기는 수락된 part를 다시 해시하지 않는다 (1101/01-02). 짝 백엔드 Fileserver `POST /v1/files` 한 번 업로드 client `createFileserverUploadClient`(`src/adapters/http` 배럴, 201·202, 실패 Envelope, `Idempotency-Key`, `Retry-After`)를 더했다. 413·415·422 파일 거절은 `VALIDATION_REJECTED`, 같은 키 불일치 422는 공통 판정이다. presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 문서에 적었다 (1103/01-01)
|
||
- 운영: 배포된 `config.json`의 비상 스위치(`CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`)를 바꾸기 전에 `check:release-admission --config <고친 사본> --original <배포된 원본>`으로 검사한다. 두 스위치 밖의 필드가 바뀌면 거절한다. 절차는 `docs/runbooks/FE-RB-001.md` (1101/13-05). 워커 스크립트 헤더 검사 범위 (1103/06-01), waiting 기간의 소유 캐시 누적 (1103/06-04), 워커 제거 1단계 유지 기간 (0929/06-06)을 운영 문서에 적었다
|
||
- realtime 문서: 짝 백엔드 실시간 출구와 프론트 transport 대응표 (1103/04-02), 레지스트리 세 바인딩의 출처 (1103/04-06), heartbeat를 멈춘 WebSocket (0929/04-04), Service Worker 레시피가 오프라인 셸을 약속하지 않음 (0929/06-03). WebSocket 구독별 초당 event 상한 (1101/04-03)과 워커 보호 장치 4개 (1101/06-04)를 테스트로 고정했다
|
||
- 빌드: react-dom과 scheduler를 자기 청크로 빼 build id만 바뀐 release의 캐시 손실을 줄였다 (1103/15-06). 운영 빌드가 react-router의 운영 빌드를 싣는다 (1103/15-07). 폐기 예정 `build.rollupOptions`를 `rolldownOptions`로 바꿨다 (0929/13-07). pnpm 설치 정책 키가 빠지거나 약해지면 테스트가 실패한다 (0929/13-08). README 변수 표에 `VITE_BUILD_ID`가 staging·production에서 필수임을 적었다 (0929/13-09). 갤러리 전용 primitive를 초기 청크에서 뺐다 (1101/08-08)
|
||
- 성능: 플랫폼 구성 화면이 제목과 선언 정보를 먼저 그리고 실행부 표만 나중에 채운다. lab 게이트 FE-GATE-026이 다시 통과한다. `PlatformOverviewPage`의 `contracts` prop은 Promise다 (1103/15-01). 성능 문서의 번들 기준선과 분류 규칙을 지금 빌드에 맞췄다 (1101/15-02, 1103/15-02)
|
||
- 레지스트리 도구: `check:registries`가 조립 실패의 `reason`을 적고, 읽지 못한 레지스트리를 지운 것으로 세지 않는다 (1103/14-06). FE-REG-SCHEMA 행의 `direction`·`unknownFieldPolicy`·`boundary`를 검증기·쓰임과 대조한다 (1103/07-03, 1103/16-04). 금지 조각이 든 런타임 설정 키를 `test:unit`이 이름과 함께 막는다 (1103/07-04). `check:feature-index` 예외 이유를 실제 사용처로 고쳤다 (1101/12-05)
|
||
- 아키텍처 검사: zod 하위 경로(`zod/v4` 등) import도 `src/contracts/zod.ts`를 거쳐야 한다 (`64f19ac`, 1103 07 영역 P-07-06). 금지 fixture를 그 계층의 운영 ESLint 설정으로 검사하고 fixture 전용 블록을 지웠다 (1103/12-04). adapter kernel 설명을 실제 `platform` 폴더 내용에 맞췄다 (`3f72ae7`). 두 오류 어휘(`AppFailure`·`AppError`)와 `commandRecovery`를 누가 읽는지 타입 옆에 적었다 (1101/07-05, 1101/07-07)
|
||
- 게이트·드릴: coverage 증거 검사(FE-GATE-005)가 istanbul summary의 `branchesTrue`를 받는다 (1103/12-09). compact smoke e2e가 빌드에 준 `VITE_BUILD_ID`를 기대해 CI 값에서 FE-GATE-008이 항상 실패하지 않는다 (1103/11-06). vitest와 dev server를 띄우는 Playwright 설정(capabilities, dev)이 CI의 `VITE_BUILD_ID`·`VITE_COMMIT_SHA`를 물려받지 않는다. 전에는 CI env에서 앱을 local-build fixture로 조립하는 테스트와 capability e2e가 `CONFIG_BUILD_MISMATCH`로 떨어져 FE-GATE-005·006·007·008·020이 항상 실패했다 (1103/11-07). 테스트가 만드는 로컬 빌드(fixture 빌드, 시각 골든 build, 브라우저 테스트의 dev server)는 `CI=true`에서도 release 빌드로 검사되지 않는다(`localBuildEnvironment`, `LOCAL_BUILD_IDENTITY`). 전에는 workflow env에서 FE-GATE-005·008·020이 실패했다 (1103/11-08). 브라우저 테스트의 strict fixture가 WebKit의 "preload했지만 몇 초 안에 쓰지 않았다" 경고 문구만 무시하고, 대신 preload된 build script가 실제로 실행됐는지를 세 엔진에서 검사한다(`preloadunused:`, `tests/support/browser/preload-use.ts`). WebKit은 load 3초 뒤 한 번 추정해서, 곧 쓰일 청크를 preload한 화면에서 FE-GATE-008이 가끔 떨어졌고 정말 안 쓴 preload는 놓쳤다. build script를 직접 fulfill하는 test는 `fulfillBuildScript`를 쓴다 (1103/11-09). browser capability의 파일 선택·다운로드 test가 붙이는 버튼을 앱 위 고정 층에 둔다. 앱이 그리는 도중 내용이 자라 클릭 사이에 버튼이 움직였고, 클릭이 버튼에 닿지 않아 firefox에서 FE-GATE-008이 가끔 30초 시간 초과로 떨어졌다 (1103/11-10). capability 제거 드릴 3개가 문서 테스트 `ENOENT`로 항상 실패하던 것을 고쳤다. 문서를 읽는 테스트 목록은 `scripts/lib/removal-fixture.ts` 한 곳이다 (1103/02-06). `test:sample-removal`이 문서를 복사해 `lint`·`verify:documentation`·`check:i18n`·`check:design-system`을 돈다 (1103/14-04). 제품 기능 제거 드릴이 CI 기준선 사유 공백으로 멈추지 않는다 (1103/16-02). `test:system` provider 묶음 30초 예산 (1103/11-03), scope wrapper EOF 테스트 (1103/10-01)와 IndexedDB 차단 업그레이드 테스트 (1103/11-05)의 부하 원인을 없앴다. `artifacts/**/*.log`를 추적하지 않는다 (1103/12-08)
|
||
- 기능 추가 뒤 검증(1103 README 14.6 X2): [계약] `create:feature`와 기능 제거 드릴이 dev server의 manifest(`public/release-manifest.json`)의 contract set을 설치된 기능으로 다시 쓴다(`node scripts/write-dev-release-manifest.ts`). 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 실패한다. 전에는 `create:feature` 직후 dev server와 dev server를 쓰는 capability e2e가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못했다 (1103/16-09). dev server가 `artifacts/`·`dist/`·`.tmp/`를 감시하지 않는다. 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)이 지운 뒤 초기 JS 기록을 다시 쓴다 (1103/15-02). 초기 JS 파일 상한이 32다(템플릿 26 + 여유) (1103/15-05). Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않아 그 런타임을 지워도 남는다(`FileserverByteSource`) (1103/01-01). 제품 확장 타입 검사 탐침이 예약 이름(`typecheck-probe-*`)을 쓰고 제품의 capability 선언을 덮어쓰지 않는다 (1103/09-02). 시각 골든 build와 storybook workshop spec이 CI 식별값·a11y 애드온 자동 검사와 겹치지 않는다 (1103/11-07)
|
||
- 테스트: Testing Library 대기 기한을 `tests/setup.ts` 한 곳에서 5초로 정했다 (0929/10-01). `npx vitest`나 npm을 거친 IDE 실행기로 돌려도 실패하지 않는다 (1101/15-05). cgroup 시스템 테스트가 실행 단계가 남긴 PID·argv 기록을 읽는다 (1101/11-01). exact-five CLI 테스트가 실제 출력 문구를 기대한다 (0929/11-01). guardian이 실패하면 stdin을 기다리지 않고 끝난다 (`3c175a5`). 계약 조립기의 쓰기 API 규칙 5개 (1101/07-06), 이벤트 계약 검증 (1101/10-01), Envelope 판정 경계와 처리 중 409 무재전송 (1103/10-02), `MAX_RETRY_ATTEMPTS` 전달과 signal listener 정리 (1103/10-04)를 테스트로 고정했다. 규모 측정 기준선을 다시 쟀고 측정용 기능 복사본은 외부 패키지를 고정한다 (`9333595`, 1101/07-04). 설치 기능이 0개여도 타입 검사와 커버리지가 통과한다 (`e4ace51`, 1101/15-01)
|
||
- 테스트: 플랫폼 component 테스트가 스타터 화면 대신 테스트 전용 페이지(`tests/helpers/fixture-feature.tsx`)를 쓴다. 스타터 화면을 바꾸는 제품은 `tests/component/starter-*.test.tsx`를 함께 지운다. HTTP 시나리오 증거(FE-GATE-007)와 기능 API 타입 음성 fixture(FE-GATE-003)는 샘플을 지워도 남는다 (0929/10-02). 기능 테스트는 `createHttpScenarioHandler(<설치 계약>, { scenario, payload })`로 공유 MSW 시나리오를 쓰고, `tests/mocks/**`는 플랫폼 소유다 (1101/16-02, 1101/16-01). SW e2e가 제품이 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 접근성 e2e가 설치된 descriptor의 경로와 `responseEnvelope`로 빈 목록을 답하고 목록 화면에 경고 상자가 없음을 단언한다. 기능을 더해도 spec을 고치지 않는다 (1103/11-01, 1103/16-03)
|
||
- 참조 기능: 샘플 페이지가 `referenceRouteUrl(routeId, input)`으로 링크를 만들고 route 입력 cast를 없앴다. `REFERENCE_FEATURE_ROUTE_CODECS`는 `presentation/reference-route-codecs.ts`에 있다. 목록 링크 href는 `?limit=20`이 붙은 정식 URL이다 (1101/16-04). `create:feature --context reference-context`로 만들어도 참조 라우팅 테스트가 깨지지 않는다 (`e8c4197`)
|
||
- 문서: 새 기능 추가 매뉴얼 `docs/manual/`(한국어)을 더했다. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것을 적고, 결정표·기능 폴더 밖 파일·`create:feature` 인자·전역 ID·패턴·오류 메시지 참조를 둔다. 두 템플릿 공통 원칙은 design-docs repo `conventions/feature-design-principles.md`에 있다 (1101/16-01). 짝 백엔드 생성 기능의 쓰기 값 넷 결정표 (1103/16-07), 업무 거절 code를 `refusedBeforeWrite`에 적는 안내 (1103/03-01), 짝 백엔드 세션에 처음 붙이기 `docs/manual/04-paired-backend-session.md` (1103/09-03), 기능 실행부 설명 네 곳 (1103/09-10, 1103/07-05)
|
||
- 문서: 목표 설계 문서 VD-23·VD-24와 `api-contract-schema-mapper-and-server-state.md`의 V2 상태를 `REMOVED`로 바꾸고, VD-23의 401 문장을 정본 8.4("401 뒤 숨은 refresh-and-replay 없음")에 맞췄다. 쓰기 전 거절 표(계약 문서 6.1절)는 `docs/README.md` 1절이 링크해 경로 검사를 받는다 (1103/14-03). 정본 표가 제품 설정 키의 FE-REG-ENV 행을 요구하는 테스트를 적는다 (1103/14-05). `PRODUCT.md`를 더하고 예제 제거 주장을 드릴 범위에 맞췄다 (1101/14-04). 리뷰 ID에 라운드를 붙인다 (1101/14-02). `verify:documentation`이 실패하면 실패한 검사 이름과 고칠 문서·빠진 route ID를 적는다 (1101/14-06)
|
||
|
||
### 알려진 제한
|
||
|
||
이 절의 범위 끝(브랜치 `fix/maturity-review-2026-11-03`의 `8a44226`)에서 사실인 것만 적었다. 위 절이 바꾼 것은 위 절에 적는다.
|
||
|
||
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento-web의 숫자(descriptor 29개, schemaId 42개 + `MementoProblem`)는 memento `d3810a0`을 정적으로 센 값이다.
|
||
- 두 제품이 고친 템플릿 파일 중 제품 소유 자리가 없는 것("옮기기 전" 2단계의 셋째 항목: memento의 `if-match`·오프라인 shell·저장소 이름·브랜드 토큰, tech-log의 `AppFailure.detail`·`BoundMutation.identity`·`null` 빈 상태·디자인 시스템 등)은 이 묶음이 옮길 곳을 주지 않는다. 동기화 때 충돌하거나 제품이 고친 채로 남는다. 어느 것을 템플릿에 들일지는 정하지 않았다.
|
||
- 직접 조립 제품(tech-log의 TechLog): 템플릿에 그 자리가 없다. 기능 모듈로 바꾸는 길은 fixture(`tests/helpers/fixture-layout-product.tsx`)로만 검사했고 TechLog 화면으로는 해 보지 않았다. 직접 조립을 유지하면 FE-REG-API·FE-REG-SCHEMA와 스키마 메타 대조 테스트가 TechLog descriptor를 보지 않는다.
|
||
- 제품 안에 적은 계약(memento `PRODUCT_LOCAL_CONTRACT`)에 줄 출처 종류가 없다. `EXTERNAL_PACKAGE` 신원을 어떻게 정할지(패키지 없이 digest를 붙이는 법)는 템플릿이 정하지 않았다.
|
||
- 참조 기능은 DTO와 problem details만 읽는다(이 범위 끝에서는 `responseEnvelope`를 선언하지 않았고, 위 절에서 필수 칸이 되어 `"NONE"`을 적는다). 짝 백엔드에 붙는 완성 예시는 `create:feature --with-create`가 만드는 기능이다.
|
||
- 짝 백엔드 생성기(`new-feature.sh`)에 목록 GET이 없다. `create:feature` 목록 화면은 백엔드가 `GET /<plural>`을 더한 뒤에야 닿는다 (1103/03-07).
|
||
- 짝 백엔드 계약 pin은 `45d2a478`(2026-11-05)이다. 그 뒤 백엔드가 바뀌면 `check:backend-contract-drift --backend <백엔드 checkout>`가 알린다. 이 검사는 게이트 밖이라 CI는 알리지 않는다.
|
||
- 업로드: 백엔드 `POST /v1/files`는 `Idempotency-Key`를 읽지 않는다. 결과 불명 뒤 같은 키로 다시 보내도 파일이 둘 생길 수 있다. client의 code 목록은 백엔드 기준점에 묶여 있다. `EXTERNAL_BEARER`로 올리려면 제품 provider가 필요하다. 실제 백엔드 업로드와 firefox·webkit은 돌리지 않았다.
|
||
- 세션 owner recipe는 실제 Keycloak·Redis와 붙여 보지 않았다. jwt 모드: 백엔드 realm에 브라우저용 public client가 없어 제품이 더한다(매뉴얼 04에 JSON). redis-session 모드: 백엔드 운영 코드에 로그인·로그아웃·세션 조회·CSRF 발급 엔드포인트가 없어 owner가 URL을 기본값 없이 받는다. OIDC owner는 토큰을 메모리에 두어 새로고침하면 로그아웃되고, ID token 서명을 검사하지 않는다.
|
||
- 플랫폼 구성 화면(`EXAMPLES_PLATFORM`, `/examples/platform`)은 플랫폼 라우트라 끌 수 없고 FE-GATE-028 서명 대상이다. 예제 기능을 뺀 제품에서 예제 화면을 여는 e2e·visual spec은 실패한다 (1103/09-04).
|
||
- 기능 라우트 첫 진입(실행부 청크, 약 430 ms)은 이 범위 끝에서 어느 게이트도 재지 않았다. 위 절에서 lab이 `EXAMPLES_UI` 첫 진입을 500 ms 예산으로 잰다. 요청 두 묶음은 그대로다(1105/15-04).
|
||
- 초기 JS 여유가 1,873 B다. `--with-create` 기능 하나(약 +964 B)를 넣으면 약 900 B가 남는다.
|
||
- 운영 의존성 high advisory 2건이 남았다: `zod` 4.4.3 GHSA-mrhx-c7xc-m3w5(고치는 버전은 초기 JS 약 +7 KB로 예산을 넘는다), `react-router` 7.18.1 GHSA-qwww-vcr4-c8h2(약 +470 B). 둘 다 owner와 다른 reviewer의 `config/security/dependency-change-evidence.json` 항목이 필요하다. moderate 2건(`minimatch`, `glob`)은 major 범위 밖이다.
|
||
- 실제 Gitea runner, 실제 HTTPS 호스트, nginx 예시에서는 돌리지 않았다. FE-GATE-019 배포 슬롯은 주입한 fetcher로만 시험했다.
|
||
- `test:feature-scaffold` 한 번이 513~866초 걸린다(부하에 따라). FE-GATE-020 job 상한은 45분이다. 브라우저 게이트는 scaffold 드릴 밖이다. 짝 저장소 참조(1103/12-05)는 CI와 중첩 worktree에서 `not verified`다.
|
||
- Service Worker를 켠 제품의 `composeProduct` 쪽 칸(SW blocker·observe)은 이 범위 끝에서 없었다. 위 절에서 `ProductComposition.serviceWorker`가 생겼다 (1103/09-05). SW e2e와 실제 live probe는 이 묶음에서 돌리지 않았다.
|
||
- OPFS: `logicalKey`까지 깨진 행은 staging에 남을 틈이 있고, 같은 lock 대기 상한이 partition 삭제에도 걸린다. `dispose()`는 `scopeParticipants`를 부르지 않는다. 실제 로그아웃 E2E는 없다.
|
||
- 라우트 계약의 `title`·`navigationLabel`은 화면이 읽지 않는다(catalog가 읽는다) (1103/16-06). 키보드 저장 실패 포커스는 스크린리더로 확인하지 않았다 (1103/08-02).
|
||
|
||
## 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` |
|
||
| [계약] | 설정 스키마 호환성 분류기(`classifyObjectSchemaChange`)가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014, `verify:compatibility`). 레지스트리 분류기(`scripts/lib/registry-compatibility.ts`)와는 다른 것이다 (0925/07-02, 0925/13-10) | `src/contracts/compatibility.ts`, `scripts/check-compatibility.ts`, `config/compatibility/` | `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` |
|