Files
clean-architecture-frontend…/CHANGELOG.md
T
DongHyeonka c8b70f5a2b
frontend-quality-gates / merge / tests (pull_request) Failing after 13m9s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 8m30s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m18s
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
docs(changelog): FE-GATE-013 판정·스킬 절 대조·ungated reason을 적는다
문제: desktop FE-GATE-013 판정 규칙, 스킬 절 인용 시험, ungated-tests
reason 번역이 변경 이력에 없다. 절 인용 시험은 자기 문서의 절 이름을 바꾼
다운스트림이 스킬도 같이 고쳐야 통과한다.

고른 방법: 「정리 단계」 절 머리에 이 브랜치 범위를 더하고 「그 밖의
수정」에 세 줄을 더한다.

위험: 커밋 해시는 이 브랜치의 것이다. main이 다시 바뀌어 rebase하면 함께
고친다.

검증: 문서 검사는 desktop에서 돌린다.
2026-11-12 10:49:49 +09:00

182 KiB
Raw Blame History

변경 이력

이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. 가져오는 방법은 README.md의 「원본 업데이트 반영」 절에 있다.

  • 버전은 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, 85f941c4121e1125, main f33e4778에 합침), 2단계(브랜치 chore/layout-2-sample-removal, c7e80f2fad3a071f), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 chore/layout-3-merge, bf485f44~c54c3813), CI 재편(브랜치 chore/ci-merge-jobs, 0739f26b부터 브랜치 끝까지), 문서 체계 단계(브랜치 claude/fe-b-docs-korean-645f55, 99e76e87부터 브랜치 끝까지. design-docs conventions/docs-system.md), 4단계에 남은 R2·R5 검사(브랜치 chore/layout-rules-r2-r5, 3f64c689부터 브랜치 끝까지), 문서 체계 후속(브랜치 claude/fe-b-docs-followup, 8acf07c2부터 브랜치 끝까지. 브랜치 claude/fe-b-docs-followup-2, 1b3eee41부터 브랜치 끝까지)을 담는다. 기준점 48c7695b를 빼면 이 절의 해시는 모두 이 범위에 있다.

먼저 할 일 (BREAKING)

아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 커밋이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).

옮기기 전

  • 템플릿은 참조 기능(src/features/reference-feature/, context src/contexts/reference-context/)과 예제 화면(src/features/platform-examples-feature/, context src/contexts/platform-examples-context/)을 지웠다. 받으면 템플릿 쪽 파일의 삭제가 함께 온다.
  • 자기 문서가 템플릿 문서의 옛 경로(docs/superpowers/, docs/architecture/decisions/, docs/architecture/의 목표 설계, 루트 SPEC.md)를 가리키는지 본다: git grep -n -E 'docs/superpowers|architecture/decisions|SPEC\.md' -- '*.md' src tests scripts. 새 위치는 아래 표의 문서 이동 행에 있다.
  • 자기 프로젝트가 그 폴더를 고쳐 남겨 두었는지 본다: 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)

  15. 코드에 적은 루트 경로 목록을 등록부 집합으로 바꾼다. R2 검사가 등록부를 쓰는 7곳이 아니라 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안 경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 tests/unit/repository-layout.test.ts가 choose a set from config/repository-layout.json with selectRepositoryPaths로 실패한다. 템플릿의 19개 목록은 집합 12개로 옮겼다. 자기 목록은 맞는 집합을 고르거나, 없으면 scripts/lib/repository-layout.ts의 REPOSITORY_LAYOUT_SETS와 등록부 sets 설명에 집합을 더해 고른다. 시험이 메모리 안에 만드는 가상 저장소의 경로 목록(실제 루트 항목을 옮겨도 바뀌지 않는 것)은 tests/unit/repository-layout.test.ts의 MADE_UP_REPOSITORY_LISTS에 파일·목록·이유를 적는다. 사본이 건너뛰는 node_modules·dist 같은 추적 안 하는 항목은 종류 untracked, optional: true로 적는다(매뉴얼 03 E절 R1·R2) (3f64c689)

  16. 샘플을 목록에 둔 프로젝트는 게이트 대상이 샘플 소유가 아닌지 본다. R5 검사가 문자열 검색 대신 대상의 소유자를 따라간다: goto 경로 → 라우트 표의 기능, workshop story id → stories 파일, spec의 import → 불러오는 파일, 게이트 명령 → package script와 경로 인자, sourceFeature → 기능. config/ci/gates.json의 수동 a11y 기록이 라우트 표에 없는 라우트를 가리켜도 실패한다(지운 기능의 기록을 남긴 경우) (1f57c38e)

  17. 자기 문서를 새 문서 검사에 맞춘다. verify:documentation(FE-GATE-017)이 살아 있는 문서 전부(루트 README.md, docs/ 아래 기록 밖 문서, 모듈 README)를 본다: 본문이 한국어인지, 「~한다」 체인지, 버전·개수를 복사하지 않았는지, 적은 경로·script·게이트 ID가 있는지. 루트 README는 ## 프로젝트 구조부터 ## 규칙과 기여까지 정해진 절을 순서대로 가져야 하고, docs/README.md는 docs/ 아래 모든 폴더를 표 첫 칸 폴더/로 덮어야 한다. 자기 기록(docs/design/, docs/history/, docs/adr/)은 맨 위에 머리 블록을 단다(형식은 템플릿 docs/README.md 3절). 한 번에 다 고칠 수 없으면 걸린 줄을 scripts/docs-system-exceptions.txt에 기준선으로 적고 그 지문을 scripts/lib/docs-system.ts의 FROZEN에 넣는다. 그 목록은 줄기만 한다 (7a9aefdf)

  18. README의 바뀐 절 이름을 따른다. 「Files you can delete after copying」은 「복사한 뒤 지워도 되는 것」이다. verify:documentation이 이 제목 아래 표의 첫 칸으로 지워도 되는 경로를 읽는다. 자기 README를 템플릿 README로 받았으면 이 제목을 지킨다 (7a9aefdf)

옮긴 뒤 확인

  1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: check:registries(3단계), check:ci(4·12단계), test:unit(5·9·11·15·16단계), 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 R2 검사를 추적되는 코드 파일 전체로 넓히고 남은 루트 경로 목록 19개를 등록부 집합 12개로 옮겼다. 등록부에 종류 untracked가 생겼다. R5 검사는 게이트 대상을 라우트 표·stories 파일·import·package script 그래프·규모 기록 필드로 따라가 소유자를 본다. 위 "먼저 할 일" 15·16 config/repository-layout.json, scripts/lib/repository-layout.ts, tests/unit/repository-layout.test.ts, tests/unit/example-feature-rules.test.ts 3f64c689, 1f57c38e
[계약] 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
[계약] BREAKING 문서 체계 검사가 생겼다. verify:documentation이 백엔드 check-docs.py와 같은 규칙 여섯(language, head, number, map, readme, style)을 scripts/lib/docs-system.ts로 돌리고, 참조 검사의 대상이 docs/README.md 1절이 링크한 문서에서 살아 있는 문서 전부로 넓어졌다. pull request에서는 FE-GATE-005의 tests/unit/documentation-readiness.test.ts가 이 repo로 verify:documentation을 돌리므로 문서가 걸리면 merge 단계가 실패한다. 예외 목록(scripts/docs-system-exceptions.txt)은 비어 있고 줄기만 한다. 위 "먼저 할 일" 7 scripts/lib/docs-system.ts, scripts/verify-documentation-readiness.ts, scripts/docs-system-exceptions.txt, docs/README.md 7a9aefdf
[계약] 문서를 수명으로 나눠 옮겼다. 설계서는 docs/design/(옛 docs/superpowers/specs/와 docs/architecture/의 목표 설계 16개는 <작성일>-<이름>-design.md로), 계획서는 docs/history/plans/(옛 docs/superpowers/plans/, 루트 SPEC.md는 docs/history/plans/2026-09-25-review-fix-round/), 결정 기록 VD는 docs/adr/(번호 그대로)다. 기록 67개에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 코드 주석의 문서 경로도 고쳤다. 위 "먼저 할 일" 옮기기 전 docs/design/, docs/history/, docs/adr/, .dependency-cruiser.json, tests/component/router.test.tsx 99e76e87, e632b230, 9540bf81, 75fad73a, 2b8a348c
[계약] 루트 README를 한국어로 다시 썼다. 절은 프로젝트 구조 → 시작하기 → (런타임 설정과 배포 변수) → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여다. 옛 「Support scope」는 「기능 켜고 끄기」의 「지원 범위」, 「Updating a copied project」는 「새 서비스로 시작하기」의 「원본 업데이트 반영」, 「CI and evidence」는 「검증」의 「게이트와 CI」다. 위 "먼저 할 일" 8 README.md, tests/unit/documentation-readiness.test.ts 7a9aefdf

그 밖의 수정

  • 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).

  • provider 업로드 시험(tests/system/ci-runner/ci-artifact-contract.test.ts, FE-GATE-013)의 기준 fixture가 .claude/를 통째로 건너뛰었다. 그래서 하네스가 .claude/에 추적 파일을 둔 뒤로 finalizer 시험 18개가 공급망 생성의 ENOENT … .claude/agents/arch-reviewer.md로 실패했다. 이제 다른 worktree가 있는 .claude/worktrees만 건너뛴다(등록부 provider-fixture-skip) (ceaf21ea).

  • 살아 있는 문서를 모두 한국어로 옮겼다(현재 계약, 운영, runbook, 보안, 스타일, 접근성, 테스트, 모듈 README). 뜻은 바꾸지 않았고 백틱 안, 링크 대상, 절 번호, 표 구조는 그대로다. 문서를 읽는 테스트의 기대 문자열(tests/unit/feature-tracked-files.test.ts)과 절 이름을 인용한 주석을 같이 고쳤다 (af10cae9, 45e8cb77, 11530b1a).

  • check:remediation-ledger는 옮긴 원장의 절 제목 ## 세 번째 재검토 (2026-08-14)을 찾고, 「모두 닫혔다」를 한국어로도 잡는다 (45e8cb77).

  • 하네스 범위가 더한 작업 매뉴얼·규칙(docs/work/, .claude/rules/docs.md, docs/problem-statement.md)의 문서 체계 설명을 새 위치와 검사 범위(살아 있는 문서 전부)에 맞췄다. docs/work/evidence.md는 근거 기록이라 참조·숫자 검사에서 뺐다 (5757742e).

  • verify:documentation의 경로 검사가 줄임표 「…」를 ...처럼 자리표시자로 본다(node scripts/…). 문서가 제거 드릴 사본에 없는 루트 파일을 링크하지 않게 docs/README.md를 고쳤다. 문서 검사를 띄우는 시험에 60초 한도를 줬다 (743f6fcc, 5f10f928, 7b09c215).

  • 문서 검사는 라우트별 수동 접근성 기록(docs/accessibility/route-reviews/)을 문서로 보지 않는다. 정해진 영어 키 형식의 게이트 입력이다 (e9e98b8a).

  • SPEC.md의 공통 완료 기준은 하네스 범위가 docs/work/improve.md 5절로 옮겼다. 이 범위가 먼저 만든 사본 docs/manual/reference/done-criteria.md는 지웠다(ee5e19f4에서 만들고 뒤 커밋에서 지움).

  • 설정 파일의 설명 칸(recipe 카탈로그, runbook 등록, 규모 상한, 짝 백엔드 pin의 fact, secret scan 허용 이유)을 한국어로 옮겼다. 키와 값의 모양은 그대로다 (309631e4).

  • 결정 뒤 본문을 제자리에서 고친 VD-09·11·13의 상태를 「채택(보완)」으로 올리고, 맨 아래 「보완」 절에 고친 날짜와 커밋을 적었다. 본문은 그대로다 (8acf07c2).

  • 번역할 때 남겨 둔 낡은 서술 일곱 곳을 코드·설정에 맞췄다: 계약 파일 수는 src/contracts/를 가리키고, Local Draft는 테스트 fixture라고 쓰고, 초기 JS 파일 수의 기준은 feature가 없는 빌드다. .dependency-cruiser.json 주석은 절 이름을 쓰고, runbook 문서 제목은 runbooks.json title과 같다. zod advisory 행의 잰 버전을 밝히고, runbook record 고정 경로 문단의 두 문장을 제자리로 옮겼다 (374af986).

  • drill:runbook의 복구 확인 항목 이름이 runbooks.json의 recoveryEvidence와 같다. record.json의 assertion 값이 한국어가 되고, tests/unit/runbook-drill.test.ts가 이름과 순서를 대조한다. 자기 recoveryEvidence를 고쳤으면 drill 이름도 같이 고친다 (6571d8cb).

  • config/ci/ungated-scripts.json의 reason을 한국어로 옮겼다 (b824195c).

  • desktop의 FE-GATE-013은 실패가 user namespace 제한 하나뿐이고 scripts/verify.sh parts FE-GATE-013의 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다. 게이트 충족은 조건을 갖춘 runner에서 통과한 것으로만 센다(docs/work/reference/gates.md 3절, 결정 색인 2.2절). 열린 결정에서 뺐다 (bdda84f8).

  • 스킬이 인용하는 절 이름·번호가 그 문서에 있는지 scripts/tests/test_claude_setup.py가 대조한다. 번역으로 사라진 절을 가리키던 9곳을 지금 제목으로 고쳤다. 자기 문서의 절 이름을 바꾸면 그 절을 인용하는 스킬도 같이 고친다 (1b3eee41).

  • config/ci/ungated-tests.json의 reason을 한국어로 옮겼다 (ac19de85).

알려진 제한

  • 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4).
  • (해결, 3f64c689) R2 검사는 등록부를 쓰는 7곳만 본다. 그 밖에 루트 이름 둘 이상을 담은 문자열 배열이 약 20곳 남았다(예: tests/e2e/support/fixture-builds.ts의 복사 제외 목록, scripts/check-test-evidence.ts의 playwright 설정 목록). 뜻이 다른 목록이라 이번에 옮기지 않았다.
  • (해결, 1f57c38e) R5는 문자열 검색이라 샘플 ID나 라우트 경로를 조립해 쓰는 시험은 놓친다.
  • R2 검사는 코드의 문자열 배열만 본다. 정규식의 대안 목록, 객체 키, package.json script 인자, tsconfig include의 루트 목록은 보지 않는다.
  • R5 검사는 실행 때 정해지는 goto 대상(라우트 표 전체를 도는 a11y spec, 생성 기능의 경로)을 따라가지 않는다. 그런 spec이 샘플 모듈을 import하면 import 경로로 잡힌다.
  • CI 재편(merge job 셋, main 단계)은 Gitea runner에서 돈다(2026-11-11 PR #16 실행 #5: job 셋이 시작하고 게이트별 단계와 !cancelled()가 동작). runner에서는 FE-GATE-005·020(tests/unit/fixture-node-modules.test.ts F-4 시험)과 FE-GATE-013(이미지에 bwrap 없음)이 실패한다. main의 옛 workflow도 같다.
  • 성능 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-0410-07, 0925/11-0411-08, 0925/F-2). tests/, scripts/scale/, scripts/lib/lab-performance.ts

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

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

알려진 제한

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

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

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

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