문제
미출시 절은 "corepack pnpm dev가 설치된 기능의 contract set으로 release
manifest를 낸다"고 적는다. 그 미들웨어는 799ab7f에서 지웠고, 지금은
create:feature와 기능 제거 드릴이 public/release-manifest.json을 다시 쓴다.
고른 방법
- 행을 지금 동작([계약]: 다시 쓰는 명령, 커밋할 것, 낡으면 실패하는 테스트)과
dev server 감시 제외로 고친다.
검증
- changelog-review-ids·documentation-readiness 테스트 20건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 16-09
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
깨끗한 clone의 FE-GATE-008에서 dev server를 쓰는 capability e2e가
"requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 1~4건씩
떨어졌다(세 번 중 세 번, 부하 9~30). 플러그인(db5728b)이 dev server 시작
때 .generated/frontend-runtime/에 manifest를 쓰는데, polling 감시
(CHOKIDAR_USEPOLLING=1)가 그 새 파일을 서버가 뜬 뒤에 보고 부팅 중인 페이지를
다시 불러오면 진행 중인 manifest 요청이 끊긴다고 본다. 플러그인을 넣기 전
같은 부하의 회차들은 66건 모두 통과했다.
고른 방법
- 자식 프로세스가 manifest를 stdout으로 내고, 플러그인은 그 문자열을
메모리에 두고 낸다. 파일을 쓰지 않으므로 감시가 볼 것이 없다.
devReleaseManifest(source)가 문자열을 돌려준다.
위험·한계
- 원인을 감시 이벤트로 직접 관측하지는 않았다(추론). 수정 뒤 재실행으로
확인한다.
검증
- tests/unit/dev-release-manifest.test.ts 2건, check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 X4
문제
test:feature-scaffold(12-02)는 기능 둘을 생성한 fixture에서 merge 단계
명령을 돈다. 15-02의 test:unit은 초기 JS 기록
(config/scale/feature-shape-ceilings.json)을 빌드와 대조한다. 두 브랜치를
합치자 드릴 안의 test:unit·test:coverage가 "initialJavascript is stale"로
실패해 FE-GATE-020이 떨어진다. 제품은 생성 명령 Next: 3번대로 기록을 다시
쓰지만 드릴은 그 단계를 하지 않았다.
고른 방법
- 생성이 성공하면 fixture를 봉인하기 전에 measure-feature-shape-growth.ts
--initial-baseline --write를 돌린다. 측정 스크립트가 없으면(샘플이 없으면)
건너뛴다. 결과는 별도 검사(initial-javascript-record)로 보고한다.
위험·한계
- 드릴이 빌드 한 번만큼 길어진다.
검증
- check:types, eslint 통과. FE-GATE-020은 깨끗한 clone에서 다시 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02, 15-performance.md 15-02
문제
c15345c의 플러그인은 apply: "serve"라 Vitest가 Vite를 띄울 때도 돌아,
test:unit마다 자식 프로세스로 manifest를 쓴다. 출력 위치
src/.generated/dev-release-manifest.json에는 자리표시자의 routeChunks(샘플
경로)가 들어 있다. test:sample-removal의 잔여 검사는 src/를 훑으므로
FE-GATE-020이 "fixture-id-residue: src/.generated/dev-release-manifest.json"으로
실패한다.
고른 방법
- 출력을 빌드의 contract set 생성물 옆 .generated/frontend-runtime/로 옮긴다
(무시 대상).
- apply가 serve이면서 VITEST가 없을 때만 돈다. 테스트는 서버에서
manifest를 받지 않는다.
검증
- browser-files capability spec(dev server) chromium 3건 통과, 생성물이 새
위치에 생긴다.
- test:unit 2,880건 통과, 실행 뒤 src/.generated에 manifest가 없다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
dev-release-manifest 테스트의 둘째 경우가 생성 결과를 커밋된 자리표시자와
통째로 비교한다. 템플릿 기능만 있으면 같지만, 기능을 더한 제품이나 생성
기능을 넣은 제거 드릴 fixture에서는 contract set이 달라 실패한다. 깨끗한
clone의 FE-GATE-020(test:sample-removal 안의 test:unit)에서 떨어졌다. 이
리뷰가 여러 번 고친 "템플릿 그대로일 때만 맞는 테스트"와 같은 결함을 새로
만들었다.
고른 방법
- 둘째 경우는 contract set을 뺀 나머지 칸이 자리표시자와 같고, contract
set이 설치된 기능의 buildContractSet()과 같은지 본다.
검증
- 테스트 2건, eslint, check:types 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)의 막힘 7건과 깨끗한 clone
검증에서 고친 것이 미출시 절에 없다.
고른 방법
- 그 밖의 수정에 한 행으로 적는다(dev release manifest 1103/16-09, 기능 제거
드릴의 초기 JS 재기록 15-02, 파일 상한 32 15-05, 업로드 client 포트
분리 01-01, 타입 검사 탐침 09-02, 시각·storybook 11-07).
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6
문제
c15345c가 vite.config.ts에서 scripts/lib/dev-release-manifest.ts를
import한다. 초기 JS를 재는 measure-feature-shape-growth.ts와
product-feature-selection-build 테스트는 빌드할 복사본에 정해진 파일만
복사하는데(BUILD_INPUTS), 그 목록에 새 파일이 없다. 그래서 복사본의 vite
build가 "Could not resolve './scripts/lib/dev-release-manifest.ts'"로 실패해
test:unit 두 파일과 세 capability 제거 드릴이 떨어졌다. c15345c 뒤에
test:unit 전체를 돌리지 않아 놓쳤다.
고른 방법
- 두 BUILD_INPUTS에 그 파일을 더한다.
- 두 목록이 같은 내용의 사본이다. 하나로 합치는 것은 이 수정의 범위 밖으로
둔다(남은 문제).
검증
- test:unit 193파일 2,880건 통과, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
src/adapters/http/fileserver-upload.ts(1103/01-01)가 입력 타입으로
application/ports/browser-file-storage의 FileByteSource를 import한다.
test:browser-file-storage-removal(FE-GATE-020)은 그 선택 런타임과 포트를
지우고 남은 코드가 import하지 않는지 본다. 그래서 "Removed browser
file/storage runtime is still imported by: src/adapters/http/
fileserver-upload.ts"로 항상 실패한다(리뷰 조치 X2 #7).
고른 방법
- client 안에 같은 모양의 FileserverByteSource(byteLength, stream이
Result<Uint8Array, { code }>를 낸다)를 두고 배럴로 낸다. client가 쓰는
것은 이 셋뿐이다. 제품은 FileContentPort.openSource가 준 FileByteSource를
그대로 넘긴다(구조 타입).
- 버린 대안: 드릴이 이 client도 함께 지우기. http 배럴이 export하므로 배럴도
고쳐야 하고, 파일 runtime을 쓰지 않는 제품도 업로드 client를 잃는다.
위험·한계
- FileByteSource 모양이 바뀌면 두 타입이 어긋날 수 있다. 통합 테스트가
FileByteSource 값을 client에 넘기므로 check:types가 그 어긋남을 잡는다.
검증
- check:types(테스트의 FileByteSource → client 호환), lint,
check:architecture, test:integration 통과. 드릴은 이 커밋 뒤 재실행한다.
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01, README.md 14.6 X2 #7
문제
매뉴얼만으로 기능을 더한 재실험(리뷰 조치 X2)에서 안내가 틀리거나 빠진
곳이 나왔다.
- 생성 명령 출력과 매뉴얼 01이 초기 JS 기록(config/scale/feature-shape-
ceilings.json)을 말하지 않는다. 출력은 "baseline does not change"만 적는다.
- 01·create-feature.md가 "드릴은 check:bundle을 돌리지 않는다"고 적는다.
12-02 뒤로 드릴은 merge 단계 명령으로 check:bundle을 돈다.
- 로컬에서 FE-GATE-013은 VITE_COMMIT_SHA가 40자리 커밋이어야 한다. 실패한
게이트의 로그 위치가 어디에도 없다.
- 01 6단계가 "생성된 판은 파라미터가 없다"고 적지만 --with-create 상세
라우트는 codec을 넘긴다. global-ids.md의 API 경로 예가 옛 생성 경로다.
고른 방법
- 생성 명령 Next에 3번(기록 다시 쓰기)과 로그 위치·FE-GATE-013 조건을
더한다. 매뉴얼 01 "merge 전에 돌릴 것"에 같은 내용과 파일 수 상한을
적는다. 나머지 문장을 지금 동작에 맞춘다.
검증
- tests/unit/create-feature.test.ts 43건, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #2#5#6
문제
initialJsFiles 상한이 템플릿 그대로의 수(26)와 같다(1b8cb12). 기능의 지연
페이지가 셸과 같은 구성요소(Button, SearchField)를 쓰면 그 구성요소가 공유
청크로 떨어져 초기 파일이 하나 는다. 매뉴얼의 검색 폼 예제를 따른 기능
하나로 FE-GATE-012가 "27 > budget 26"으로 실패했다(리뷰 조치 X2 #4).
고른 방법
- 상한을 32(지금 26 + 6)로 둔다. 템플릿은 HTTP/2 서빙을 요구하고
(1103/13-02, FE-GATE-019), 그때 파일 하나의 비용은 거의 없다(15 영역
측정). 상한은 청크가 통째로 쪼개지는 회귀를 막는 용도다.
- performance-evidence.md에 이유와, 넘었을 때 먼저 청크 그룹을 볼 것을
적는다.
- 버린 대안: 상한을 지금 수로 두고 제품마다 올리기. 템플릿 소유 파일을
기능마다 고치게 된다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다. 여유는 1,873 B다.
검증
- performance-budgets·bundle-artifact-contract 테스트 14건,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05, README.md 14.6 X2 #4
문제
config/scale/feature-shape-ceilings.json의 initialJavascript는 지금 설치된
기능으로 만든 빌드를 기록하고, test:unit이 빌드와 대조한다(1103/15-02).
제품이 기능을 더하면 기록을 다시 써야 FE-GATE-005가 통과한다. 그러면
`test:sample-removal -- --feature=<id>`가 그 기능을 지운 fixture에서 반대
이유("record 27, build 26")로 실패한다. 두 게이트를 함께 통과시킬 방법이
없다(리뷰 조치 X2 #2).
고른 방법
- 드릴이 레지스트리 기준선을 다시 찍는 것과 같은 자리에서
measure-feature-shape-growth.ts --initial-baseline --write를 fixture에서
돌린다. 제품이 기능을 지운 뒤 할 일을 드릴이 그대로 한다.
- 샘플 제거는 측정 스크립트를 함께 지우므로 그때는 건너뛴다.
위험·한계
- 측정이 빌드를 하므로 기능 제거 드릴이 1~2분 길어진다.
검증
- eslint 통과. 기능 제거 드릴은 X4 재실행(test:feature-scaffold 안의
feature-removal)에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, README.md 14.6 X2 #2
문제
tests/unit/product-extension-typecheck.test.ts(1103/09-02)는 복사본에 제품
파일과 기능 하나를 넣고 tsc 세 프로그램을 돈다. 세 가지가 제품과
제거 드릴에서 깨진다(리뷰 조치 X2 #1, #7).
- 탐침 ID가 notice-feature·notice-context다. 매뉴얼 예시가 모두 "공지"라
제품이 같은 ID를 쓰면 FE-GATE-005가 원인을 말하지 않는 TS 오류 약
20줄로 실패한다.
- product-capabilities.ts가 템플릿의 빈 선언 그대로여야 한다고 단언하고
그 선언을 바꿔 쓴다. 자기 capability를 적은 제품에서 실패한다.
- 복사 대상을 모두 복사한다. test:optional-recipe-removal의 fixture에는
recipes/가 없어 ENOENT로 떨어진다.
고른 방법
- 탐침 이름을 typecheck-probe-*(capability typecheckProbeSettings, 설정 키
TYPECHECK_PROBE_PAGE_SIZE)로 바꾸고, 그 기능 폴더가 이미 있으면 이름을
말하며 실패한다.
- capability 타입은 제품 파일 끝에 같은 이름 interface로 덧붙인다.
TypeScript가 합치므로 제품의 선언이 남는다.
- 없는 복사 대상은 건너뛴다.
위험·한계
- product-contracts.ts·product-composition.ts는 여전히 탐침 내용으로 바꿔
쓴다. 제품 기능이 이 두 파일의 이름 있는 export를 import하면 복사본에서
타입 오류가 날 수 있다.
검증
- 테스트 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02, README.md 14.6 X2
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.
고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
`/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.
위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).
검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
문제
test:sample-removal의 잔여 검사(REFERENCE_RESOURCE|reference-feature|
reference-resource)가 샘플을 지운 fixture에서 두 파일을 잡아 FE-GATE-020이
실패한다. tests/unit/hosting-probe.test.ts는 비상 스위치 예시로
FEATURE_OVERRIDES에 "reference-feature"를 쓰고(13-01), platform-examples-
context의 머리 주석은 참조 context 경로를 적는다(09-04).
고른 방법
- 테스트 값을 "platform-examples-feature"로 바꾸고, 주석은 샘플 이름 없이
적는다. 동작은 바뀌지 않는다.
검증
- tests/unit/hosting-probe.test.ts 37건, lint 통과. 제거 드릴은 X4 재실행에서
확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
홈 화면과 플랫폼 구성 화면은 build id와 release id를 글자로 그린다. CI는
workflow 전체에 VITE_BUILD_ID·VITE_COMMIT_SHA·RELEASE_ID를 준다. 그래서
test:visual(FE-GATE-008)의 build가 골든과 다른 글자를 그려, 셸 넓은 화면·
좁은 서랍·플랫폼 구성 3장이 1,109~1,545 px 달라 항상 실패한다. 깨끗한
clone에 CI env를 준 merge 단계 재실행에서 찾았다(af312de와 같은 원인,
1103/11-07).
고른 방법
- playwright.visual.config.ts webServer env로 로컬 식별값(local-build,
local, local-release)을 준다. 골든은 템플릿의 모양 계약이고 그 값으로
찍었다.
- 버린 대안: 식별값 글자를 화면마다 가리기. 가릴 곳이 화면마다 늘고,
식별값을 그리는 새 화면이 생길 때마다 다시 빠진다.
위험·한계
- 시각 테스트의 build는 CI 식별값을 쓰지 않는다. 식별값 표시 자체는
e2e(compact smoke, 11-06)가 CI 값으로 본다.
검증
- VITE_BUILD_ID=gitea-1-1·VITE_COMMIT_SHA·RELEASE_ID를 주고 test:visual 6/6,
env 없이 6/6 통과. 수정 전 CI env에서 3건 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제
fix/r1103-release(15-02)가 performance-evidence.md에 기준선 기록 파일
(config/scale/feature-shape-ceilings.json)과 측정 테스트
(tests/unit/feature-shape-growth.test.ts)를 백틱 경로로 적었다. 둘 다 참조
기능을 복사해 재므로 test:sample-removal이 함께 지운다. 그래서 제거
fixture에서 verify:documentation이 실패하고 documentation-readiness
테스트 36건이 떨어진다(깨끗한 clone FE-GATE-020). 14-04 규칙(지울 수 있는
샘플 경로는 백틱 없이)과 2f2426a와 같은 결함이다.
고른 방법
- 두 경로를 백틱 없이 적고, 샘플과 함께 지워진다고 적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture는 X4 재실행에서 확인한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 15-performance.md 15-02
문제
깨끗한 clone의 FE-GATE-008에서 test:storybook이 "Axe is already running"으로
떨어졌고, 이 worktree에서도 두 번에 한 번 떨어진다. @storybook/addon-a11y
10.6.5(13-03이 올린 판)는 story를 그린 뒤 afterEach에서 axe를 스스로 돌린다
(globals.a11y.manual이 true가 아니면). spec의 AxeBuilder.analyze()는 그 페이지의
같은 axe 인스턴스를 쓰므로, 두 실행이 겹치면 두 번째가 거절된다.
고른 방법
- spec이 story를 `globals=a11y.manual:!true`로 연다. 애드온은 자동 검사를
건너뛰고, 접근성 판정은 지금처럼 spec의 AxeBuilder가 한다.
- 버린 대안: 애드온 실행이 끝나길 axe 내부 상태로 기다리기. 공개 API가
아니고, 애드온 실행이 시작되기 전에 확인하면 여전히 겹친다.
- 버린 대안: preview 전체에서 애드온 자동 검사 끄기. workshop에서 쓰는
사람이 패널 결과를 잃는다.
위험·한계
- 이 spec만 바꿨다. 다른 storybook spec이 생기면 같은 URL을 쓴다.
검증
- test:storybook 5회 연속 통과(heavy lock). 수정 전 2회 중 1회 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5
문제
af312de(vitest와 dev server Playwright가 CI의 VITE_BUILD_ID·VITE_COMMIT_SHA를
물려받지 않는다)는 CHANGELOG 재작성(44aa44d) 뒤에 들어왔다. 미출시 절
머리의 끝 커밋 설명도 그 뒤의 변경을 말하지 않는다.
고른 방법
- 게이트·드릴 행에 1103/11-07 행을 더한다. 리뷰 README 13절에 발견으로
적는다.
- 머리에 f887817 뒤로 검증 수정과 pin 갱신이 더해졌다고 적는다.
검증
- tests/unit/changelog-review-ids.test.ts 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제
check:backend-contract-drift가 백엔드 HEAD 45d2a478에서 http-contract.md §2
두 행의 설명 변경을 알린다. IDEMPOTENT_IN_FLIGHT(PostgreSQL 저장소는 409
대신 첫 요청이 끝날 때까지 기다림)와 IDEMPOTENCY_UNAVAILABLE(processing
lease가 시작 전에 끝나 저장소가 시작을 거절함)이다. 같은 커밋이 6.1절이
인용하는 GlobalExceptionHandler와 IdempotencyExecutor도 고쳤다.
고른 방법
- 두 행의 code·status·retryable·재전송 규칙은 같다. 프론트 판정(처리 중
MAYBE_APPLIED·같은 키, UNAVAILABLE 실행 안 됨·같은 키 자동 재전송)은
바꾸지 않는다.
- 6.1절이 인용하는 블록 13개를 두 판에서 대조했다. 내용은 모두 같고
GlobalExceptionHandler 4개, IdempotencyExecutor 1개의 줄 번호만 옮겼다.
인용한 다른 백엔드 파일 15개는 바뀌지 않았다.
- pin, 답 표 JSON, 계약 문서 4.1·6·6.1절, CHANGELOG의 pin 행과 알려진
제한을 같이 고친다.
위험·한계
- PostgreSQL 저장소의 기다림이 프론트 totalDeadline보다 길면 응답 없는
끝(결과 불명, 키 유지)이 된다. 판정은 안전 쪽이다.
- Fileserver 계약(docs/fileserver/http-contract.md)은 bbe944bd 이후 바뀌지
않았다.
검증
- check:backend-contract-drift --backend <백엔드 checkout>: pinned
45d2a478.
- backend-contract-pin·changelog-review-ids 테스트 11건,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
문제
- "CI and evidence"의 로컬 merge 게이트 반복문이 13개이고 FE-GATE-012가 없다.
f41e3d5가 번들 예산 게이트를 merge 단계로 옮겨 gates.json의 merge 단계는
14개다. "Updating a copied project"가 이 반복문을 가리키므로, 동기화한
제품은 번들 예산을 건너뛴다.
- 배포 슬롯을 채우는 곳이 config/ci/product-gates.json으로 바뀌었고(12-07),
FE-GATE-019는 HTTP/2·entry 압축이 없는 호스트도 실패시킨다(13-02).
README는 둘 다 말하지 않는다.
- CHANGELOG 미출시 절이 동기화 단위 순 요약이 됐는데(14-01 D5 (b)), 업데이트
절은 그 절을 어떻게 받는지 말하지 않는다.
고른 방법
문장 셋만 고친다. 반복문에 012를 넣고 개수를 14로, 제품 merge 검사
(PRODUCT-GATE-NNN)는 workflow의 product_merge_gate job이 돈다고 적었다.
업데이트 절에는 미출시 절을 범위째 받고 "먼저 할 일"부터 하라는 한 문장을
더했다. cherry-pick 절차는 그대로 둔다(한 수정을 받을 때는 여전히 맞다).
위험·한계
- README의 다른 절(0929/14-02의 범위 동기화 절차 전체)은 다시 쓰지 않았다.
검증
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
- config/ci/gates.json merge 단계 gateIds 14개와 반복문을 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제
리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다.
- 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가
"실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다.
실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다.
- 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가
실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만
실패하고 check:types·check:architecture·verify:documentation은 통과한다.
- 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400
VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는
Envelope operation에서 결과 불명이다.
- starter-experience.md: "`NoRequest` already belongs to the sample". src에
NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다.
다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app).
고른 방법
문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지
않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로
적는다. 매뉴얼에 그 테스트를 가리켰다.
위험·한계
- 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는
돌리지 않았다.
검증
- 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0,
check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림.
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08
문제
미출시 절은 fix/ui-design-audit-2026-11-01 한 브랜치의 누적 기록이었다.
- 같은 묶음에 들어온 그 브랜치 뒤 16커밋(ece944dd0414c87d855897c8cb1917fa8d127f45238a09c90e5b7b3e 등)과 2026-11-03 조치 11개 브랜치가 없다.
- V2를 고친 행과 V2를 지운 행이 함께 있고, 알려진 제한 13줄 중 대부분이
이미 고쳐졌다.
- BREAKING 이행 안내가 "memento-web이 V2 API 행을 쓴다"고 적었다. memento-web의
apiOperations는 비어 있고, 실제 작업은 descriptor 29개의 FE-REG-API 행,
스키마 행 43개, zod가 아닌 검증기다. tech-log의 직접 조립 경로는 안내가
없었다.
- 0.2.0의 17d617a 행이 설정 스키마 분류기를 "레지스트리 호환성 분류기"라고
부르고, 그 커밋이 고치지 않은 scripts/check-registries.ts를 적는다.
고른 방법
- 결정 D5 (b): 752a61f → fix/maturity-review-2026-11-03 범위를 한 동기화
단위로 보고 최종 상태만 적는다. 머리에 범위·세 갈래·읽는 법, 이어서
"먼저 할 일 (BREAKING)"을 옮기기 전 / 옮기는 법 / 옮긴 뒤 확인 순서로,
그 뒤 영역별 [보안]·[계약] 표, 그 밖의 수정, f887817에서 사실인 알려진
제한을 둔다. 뒤 커밋이 바꾼 중간 상태 행(V2 Envelope·V2 거절·V2/V3 대조,
REST 보안 프로필 메시지, 초기 청크 16→25개 등)은 최종 행에 합치거나 지웠다.
- 14-02: 두 다운스트림(memento d3810a0, tech-log 7a4e201a)을 읽고 단계마다
실제 모양을 적었다. memento: PRODUCT_LOCAL_CONTRACT 출처, ownsShell·APP_HOME
다리, SW ACTIVE 선택, 손으로 쓴 검증기. tech-log: NOT_INSTALLED 직접 조립과
기능 모듈로 바꾸는 길(fixture-layout-product 모양).
- 리뷰 P-07-07은 경로를 scripts/lib/registry-compatibility.ts로 바꾸라고
했지만, 17d617a가 고친 것은 src/contracts/compatibility.ts(FE-GATE-014)다.
경로를 바꾸면 틀린다. 그래서 이름을 "설정 스키마 호환성 분류기"로,
둘째 경로를 scripts/check-compatibility.ts로 고쳤다.
- 머리 규칙에 미출시 절이 동기화 단위 순 요약이라는 줄을 더했다.
- 버린 대안: 브랜치별 누적 기록을 유지하고 빠진 행만 더하기(14-01 (a)).
다운스트림이 서로 뒤집는 행을 직접 걸러야 한다. 커밋 trailer 검사
(14-01 (c))는 이번에 넣지 않았다.
위험·한계
- 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento 숫자는
정적 집계다. 알려진 제한에 적었다.
- 끝 커밋은 f887817 기준이다. 이 브랜치를 합친 뒤 끝이 바뀌어도 해시 규칙
(범위 안)은 그대로다.
- 짝 백엔드가 pin c508b1ba 뒤로 바뀐 것(HEAD 45d2a478, §2 두 행 설명)을
알려진 제한에 적었다. pin은 올리지 않았다.
검증
- 미출시 절의 이 repo 해시 148개: 모두 f887817에서 닿고 752a61f에서 닿지
않는다(merge-base --is-ancestor 스크립트). 나머지는 기준점 2개와 다른
repo 커밋 4개.
- vitest changelog-review-ids, documentation-readiness 20건 통과.
- verify:documentation PASS_SCOPED, check:types, lint 통과.
- 인증 프로필 오타 변이(참조 기능): check:registries가 reason과 함께 실패,
check:types·check:architecture·verify:documentation 통과를 확인했다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-02
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-07
문제
ac52a93이 backend-api-and-server-state-contract.md를 docs/README.md 1절에서
링크해 이 문서도 경로 검사를 받는다. 이 문서는 참조 기능 파일 둘을 백틱
경로로 적는다. static-delivery.md는 config/scale/feature-shape-ceilings.json
(15-02, 샘플 제거 때 함께 지워짐)을 백틱 경로로 적는다. 그래서 참조 기능을
지운 제거 fixture에서 verify:documentation이 "names paths that do not exist"로
실패하고, 그 fixture의 documentation-readiness 테스트 36건이 떨어진다
(FE-GATE-020). 14-04가 정한 규칙(지울 수 있는 샘플 경로는 백틱 없이)을
어겼다.
고른 방법
- 세 경로를 백틱 없이 적고, static-delivery에는 샘플과 함께 지워진다고
적는다.
검증
- verify:documentation PASS_SCOPED. 제거 fixture 확인은 X4 재실행에서 한다.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04, 14-03
문제
.gitea/workflows/quality-gates.yml은 workflow 전체 env에
VITE_BUILD_ID=gitea-<run>-<attempt>와 VITE_COMMIT_SHA를 넣는다. Vite는 이
값을 import.meta.env로 번들에 넣는다. 그래서 CI와 같은 env로 돌리면:
- vitest: 앱을 local-build fixture release로 조립하는 테스트가
CONFIG_BUILD_MISMATCH로 실패한다(runtime-application,
boot-unexpected-failure, runtime-composition-service-worker-telemetry,
reference-production-vertical, 생성 기능 페이지 테스트). FE-GATE-005·006·
007과 제거 드릴(FE-GATE-020)이 떨어진다.
- capability e2e: dev server는 public/config.json(BUILD_ID local-build)을
내주는데 번들은 gitea-1-1이라, 페이지마다 rolling-release 불일치로 한 번
다시 불러오고 그다음 실패 화면이 된다. page.evaluate가 "Execution context
was destroyed"로 30건 실패한다(FE-GATE-008).
깨끗한 clone에서 merge 단계 14개를 CI env로 돌려(리뷰 조치 X4) 찾았다.
로컬에서는 이 값이 없어서 늘 통과한다. 1103/11-06과 같은 원인이다.
고른 방법
- vitest.config.ts가 npm scope 변수를 지우는 것과 같은 자리에서
VITE_BUILD_ID·VITE_COMMIT_SHA를 지운다. 테스트는 로컬 빌드 식별값으로
시작한다.
- dev server를 띄우는 Playwright 설정(capabilities, dev)은 webServer env로
VITE_BUILD_ID=local-build, VITE_COMMIT_SHA=local을 준다. 그 dev server가
내주는 config.json과 같은 값이다.
- build·preview를 쓰는 e2e·visual은 바꾸지 않았다. 빌드가 같은 값으로
config.json을 만들므로 맞는다.
- 버린 대안: 테스트마다 기대값을 env에서 읽기(11-06 방식). 같은 모양의
fixture가 여러 파일에 있고, 다음 테스트가 또 같은 실수를 한다.
위험·한계
- vitest 안에서 CI 빌드 식별값을 읽는 것을 검사하려는 테스트는 값을 직접
넣어야 한다(지금은 없다).
- CI=true와 러너 이미지 조건은 재현하지 않았다.
검증
- VITE_BUILD_ID=gitea-1-1, VITE_COMMIT_SHA=<HEAD>로: test:unit 2,878,
test:component 270, test:integration 189, test:reference-feature 97,
test:recipes 77 통과. browser-files capability spec chromium 3건 통과
(수정 전 3건 실패, env 없으면 통과).
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-06
문제
fix/r1103-release(15-02)는 초기 JS 기준선을 feature-shape-ceilings.json의
initialJavascript 한 곳에 두고, test:unit이 빌드와 대조하게 했다. 열 개
조치 브랜치를 합친 빌드는 그 브랜치 하나로 잰 기록(200,939 B, 25개)과
다르다(15-01이 떨어뜨린 파일 하나, 세션·업로드·생성기 변경). 그래서
feature-shape-growth 테스트가 "initialJavascript is stale"로 실패한다.
고른 방법
- 기록 절차(performance-evidence.md)대로
measure-feature-shape-growth.ts --initial-baseline --write로 다시 쓴다.
- 결과: 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B.
예산 204,800 B에 여유 1,873 B다.
위험·한계
- 여유가 작다. --with-create 기능 하나(+약 964 B)를 넣으면 약 900 B가
남는다.
검증
- tests/unit/feature-shape-growth.test.ts 통과(heavy lock,
CHOKIDAR_USEPOLLING=1).
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02 15-04
문제
09-06의 완료 기준은 짝 백엔드 wire의 KEYED 생성, 400 필드 오류와 함께 409
IDEMPOTENT_IN_FLIGHT를 실행하는 기능 예제다. --with-create --keyed가 만드는
gateway 테스트는 503 IDEMPOTENCY_UNAVAILABLE 재전송만 보고 409 처리 중은 보지
않는다.
고른 방법
KEYED 생성 gateway 테스트에 409 IDEMPOTENT_IN_FLIGHT 사례를 더한다. 결과는
MAYBE_APPLIED이고 code가 그대로이며, 실행기는 스스로 다시 보내지 않는다(같은
키 재전송은 폼이 한다, http-contract.md §2). NEVER 생성은 키가 없어 이 답을
받지 않으므로 더하지 않는다.
위험·한계
- Retry-After 대기는 뮤테이션 조정자 쪽이라 이 gateway 테스트는 보지 않는다.
검증
- keyx-feature --with-create --keyed를 만들어 gateway 테스트 13건 통과, eslint
통과. 생성 기능은 지웠다. tests/unit/create-feature.test.ts 43건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
문제
--with-create(NEVER)와 --with-create --keyed(KEYED)가 만드는 코드는 단위
테스트가 텍스트로만 본다. FE-GATE-020의 두 드릴(test:feature-scaffold,
test:sample-removal)은 기본 기능 하나만 만들어 게이트를 돈다. 그래서 쓰기
slice의 타입·lint·테스트·빌드가 머지 게이트에서 깨져도 모른다(16 5.3절의
"생성 결과를 매번 게이트로 돌린다"는 전제).
고른 방법
- scripts/test-feature-scaffold.ts: 기본 기능(scaffold-feature) 옆에
scaffold-write-feature를 --with-create --keyed로 하나 더 만들고, 둘 다
만들어졌을 때 같은 게이트를 한 번 돈다. 바꾼 것은 WRITE_FEATURE_ID 상수,
create-feature-write 검사 한 개, 게이트 조건(created && createdWrite), 머리
주석이다.
- scripts/test-sample-removal.ts: 참조 기능을 지운 복사본의 create:feature
인자에 --with-create 한 개를 더했다. 쓰기 slice도 샘플에 기대지 않는다는
증거다.
- 세 변형(기본, NEVER, KEYED)이 모두 드릴의 게이트를 지난다.
- reference/create-feature.md의 드릴 설명을 맞췄다.
버린 대안
- 드릴 기능 하나를 --with-create로 바꾸기: 기본 변형이 게이트에서 빠진다.
위험·한계
- test:feature-scaffold는 기능 하나만큼(create:feature 한 번과 그 기능의
테스트) 길어진다. 게이트는 한 번만 돈다.
- 다른 작업(게이트 담당)이 같은 두 파일의 명령 목록을 고칠 수 있다. 내 수정은
위 줄로 좁혔다.
검증
- flock 아래 CHOKIDAR_USEPOLLING=1 corepack pnpm test:feature-scaffold:
rc=0, "feature scaffold: PASS (17 checks)" (생성 2 + 게이트 15), 162초.
- 같은 조건 corepack pnpm test:sample-removal: rc=0, "reference-feature
removal: PASS (23 checks, no fixture IDs)". 참조 기능을 지운 복사본에서
--with-create 기능을 만든 뒤 scaffold-* 게이트 9개가 모두 통과했다. 첫
실행은 tests/unit/create-feature.test.ts에 샘플 ID 문자열이 있어
fixture-id-residue로 실패했고, 그 테스트를 앞 커밋에서 고친 뒤 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
짝 백엔드에 쓰기를 붙일 때 기능 작성자가 정하는 값 넷(호출 문맥 intent,
retryBudget, classifyStatus, operationIdentityField)을 매뉴얼이 정해 주지
않는다. 02 3절은 "retryBudget 안에서 같은 키로 재전송"과 "참조 기능은 0"을
함께 적어 부딪히고, 401·403·429를 짝 백엔드가 쓰기 전에 거절하는지는 어느
문서에도 없다. 실험에서 실행기 코드를 읽고 값을 정했다(리뷰 B1~B4). 또 백엔드
생성 create가 NOT_IDEMPOTENT라는 사실과 프론트 retrySemantics의 관계가 적혀
있지 않다(03-07).
고른 방법
- 02 3절에 "짝 백엔드의 생성 기능에 붙일 때" 표를 둔다. 백엔드 create를
그대로 두면 NEVER, IdempotencyExecutor 뒤로 옮기면 KEYED. 두 경우의
retrySemantics, retryBudget(0 / 1과 실제 상한 계산), commandRecovery와
operationIdentityField의 뜻(실행기는 읽지 않음), intent 전달,
classifyStatus(401 보안 필터, 403 @RequiresPermission 프록시, 429
rate-limit interceptor preHandle — 백엔드 코드에서 확인),
refusedBeforeWrite, acceptedStatuses, 결과 불명 화면, 생성 테스트를 적는다.
- 01 4단계에 쓰기 메서드의 호출 문맥(intent), 8단계에 NEVER는 다시 보내기
버튼이 없다는 것과 생성 예제 위치를 적는다.
- 표의 값은 create:feature --with-create(--keyed)가 만드는 값과 같다.
버린 대안
- classifyStatus를 "백엔드 확인 전에는 생략"으로 두기(리뷰 권고 (1)의 잠정안):
백엔드 코드를 확인해 생성 create에서는 셋 다 use case 전이라 NOT_APPLIED로
적었다. use case가 AuthorizationPort를 쓰기 뒤에 부르면 지우라고 조건을
붙였다.
위험·한계
- classifyStatus 판정은 백엔드 c508b1ba의 생성 템플릿과 web 어댑터 기준이다.
백엔드가 바뀌면 다시 본다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-07
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).
고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.
버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
가정 하나를 지키려고 정상 입력을 막는다.
위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
적었다. 이 경로의 드릴은 돌리지 않았다(추론).
검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
상태에서 tests/features 124건 통과, tests/component·architecture와
create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).
고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
실패 본문 행을 더한다.
버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
"빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
"...-vertical-slice"). 그대로 둔다.
위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
(REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
잡힌다.
검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
create-feature 테스트 통과. check:types, lint, verify:documentation 통과.
BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제
fix/r1103-release(15-05)는 초기 JS 파일 수 상한을 그 브랜치의 개수(25)로
두었다. fix/r1103-examples(15-01)는 플랫폼 구성 화면이 실행부 레지스트리
조립 모듈을 동적으로 받게 했다. 그 결과 그 모듈과 초기 그래프가 함께 쓰는
installed-product-manifest(198 B gzip)가 따로 떨어져 초기 파일이 하나
늘었다. 두 브랜치를 합친 빌드는 26개이고 check:bundle이
"initial JavaScript files 26 > budget 25"로 실패한다.
고른 방법
- 상한을 26으로 올린다. performance-evidence.md의 규칙대로 초기 파일을
늘린 이유를 같은 변경에 적는다. 이 파일은 15-01(lab 게이트 회복)의
결과이고, 템플릿은 HTTP/2 서빙을 전제로 한다(13-02).
- 버린 대안: manualChunks로 그 모듈을 초기 청크에 묶기. 198 B 하나 때문에
청크 그룹 규칙이 하나 늘고, 셸을 바꿀 때마다 다시 재야 한다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다.
검증
- check:bundle PASS(26/26 파일).
- performance-budgets·bundle-artifact-contract 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05 15-01
문제
직전 커밋(짝 저장소 참조 테스트 범위 축소)이 보고서의 missingPaths를
읽지만, 테스트가 JSON을 읽을 때 쓰는 타입에 그 칸이 없어 check:types가
TS2339로 실패한다. vitest는 타입을 보지 않아 테스트는 통과했다.
고른 방법
- 보고서 타입에 missingPaths?: string[]를 더한다.
검증
- check:types 통과, documentation-readiness 테스트 19건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
fix/r1103-gates(12-05)의 테스트는 옆 checkout을 흉내 낸 stub(백엔드
문서 1개)을 두고 verify:documentation 전체가 통과하기를 기대한다. 다른
브랜치를 합치자 실제 문서(매뉴얼 02·04, 백엔드 계약 문서)가 stub에 없는
백엔드 경로를 가리켜, 테스트가 status 1로 실패한다. 결함은 문서가 아니라
테스트 범위에 있다. 그 경로 14개는 실제 옆 checkout에 모두 있다.
고른 방법
- "있는 경로" 경우에서 전체 status 대신, 테스트가 고친 문서
(CI_DOC)에 빠진 경로가 없는지만 본다(stderr와 보고서 missingPaths).
- 버린 대안: stub에 실제 문서가 가리키는 백엔드 경로를 모두 만든다.
문서가 바뀔 때마다 테스트도 같이 바뀌어야 한다.
위험·한계
- 다른 문서의 짝 저장소 경로가 틀리면 이 테스트로는 잡지 않는다. 실제
옆 checkout이 있는 개발 환경의 verify:documentation이 잡는다.
검증
- tests/unit/documentation-readiness.test.ts 19건 통과.
- 실제 백엔드 checkout에서 문서가 가리키는 경로 14개 존재 확인.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다.
bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능
작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로
적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②).
고른 방법
세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는
채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다.
매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title·
navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다.
버린 대안
- 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과
다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다.
- 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의
operation ID를 싣는다. 같은 값을 두 번 싣는다.
위험·한계
- 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면
FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와
test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은
파일이라 이번에는 문서로만 적었다.
검증
- RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner·
operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과.
- tests/features/reference-feature, tests/unit/create-feature.test.ts,
scope-fence 129건 통과. check:types(app·node·test), lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
문제
BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시
적는 자유 값이다. operationId에 오타가 있어도 check:types와
check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와
다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을
처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이
같은 재기술을 적었다.
고른 방법
src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다.
descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은
이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를
넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다.
버린 대안
- BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트
약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다.
- 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌
위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지
않으므로 미뤘다.
- 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한
descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다.
위험·한계
- 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에
적었다.
- 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연
청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다).
검증
- RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패.
GREEN 뒤 통과.
- tests/features/reference-feature, tests/component/application-query.test.tsx
125건 통과.
- check:types, check:architecture, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.
고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
실패를 낸다.
- 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
빠진다.
- 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
골든을 제품 소유로 선언(동기화마다 PNG 충돌).
위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
보기" 버튼만 남는다.
검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
가림 규칙에 걸리지 않음).
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.
고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
접근성 spec 생성(파일·실행 시간 증가).
위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
"passed"로 적힌다.
검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
문제
lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이
보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에
loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된
모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이
두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms).
고른 방법 (영역 문서 최소 개선 방향 (c))
- route module은 페이지 컴포넌트를 바로 돌려준다(default export).
제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임
snapshot으로 아는 것은 바로 그린다.
- 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션
표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다.
- 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지
청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B).
- 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다.
실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다.
- 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은
이유), hover 프리페치(키보드·직접 진입에 효과 작음).
위험·한계
- 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다.
- PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를
직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다.
- 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이
페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다
약 30 ms 느리다.
- 실제 CI 러너에서는 재지 않았다.
검증
- 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가
보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과.
- test:component 통과. check:types, check:architecture, 바뀐 파일
eslint 통과.
- lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아,
test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준):
부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS.
LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두
홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시
잰 것이 위 결과다.)
- 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고,
feature-runtime·reference-schemas는 제목 뒤에 받는다.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01
문제
responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을
손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를
거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의
선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로
깨진다(리뷰 E-1).
고른 방법
계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이
없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서
그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다.
거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와
check:registries가 실패한다.
버린 대안
- responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor
약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입
변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다.
- 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다.
위험·한계
- 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트
(백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다.
- 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는
테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다.
검증
- RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과.
- tests/unit·integration·contract·component·features·runtime-schema·platform·
architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
문제: 의존성 취약점 판정은 운영 승격의 외부 provider에만 있었다. 로컬
supply chain은 스캔하지 않고 provider: UNCONFIGURED를 썼다. 그래서
lockfile이 템플릿 자신의 정책(high 이상 차단, 예외 0건)을 어겨도 merge·
release 단계에서는 아무 신호가 없었고, provider가 없는 복사본은 끝까지
몰랐다. 갱신 자동화도 없었다(짝 백엔드에는 renovate.json이 있다).
고른 방법:
- scan:dependency-advisories(scripts/scan-dependency-advisories.ts)가
pnpm audit --json에 config/security/vulnerability-policy.json과
예외 파일을 적용한다. 판정은 승격이 쓰는 validateVulnerabilityReport를
그대로 쓴다. 결과는 PASS / POLICY_VIOLATION(승격에서 막힐 항목 목록) /
UNVERIFIED(레지스트리에 닿지 못함)이고, 운영·개발 의존성별 개수와 함께
gate 로그와 artifacts/security/dependency-advisories.json에 남는다.
- FE-GATE-027(release-admission, release 단계, 후보 빌드 직후)이 이 명령을
두 번째로 돈다. 명령은 항상 exit 0이다.
- renovate.json을 둔다(보안 업데이트만, 사람이 리뷰·merge).
- 남은 운영 의존성 위반 2건과 올리지 않은 이유, 다시 볼 날짜
(2026-12-04)를 ci-quality-gates.md에 적는다.
버린 대안: merge 차단 audit(코드가 안 바뀌어도 advisory DB 변경으로
merge가 깨진다), 로컬 스캐너를 provider로 내장(서명 주체 분리라는 원래
목적이 사라진다), 새 evidence 산출물·스키마 등록(계약 변경이 커진다.
gate 로그가 이미 release 단계 산출물이다).
위험·한계: 비차단이라 신호를 읽는 사람이 있어야 한다. 네트워크가 없는
runner에서는 UNVERIFIED로 남는다. Renovate runner는 붙어 있지 않아
renovate.json은 아직 동작하지 않는다. 남은 zod·react-router high 2건은
dependency-change-evidence의 reviewer(owner와 다른 사람)와 zod의 번들
예산 결정이 있어야 고칠 수 있다. 계약 기준선(contract-baseline.json)을
명령 100개·참조 104개로 다시 기록했다.
검증: dependency-advisories.test.ts 5건(정책 위반 판정, PASS, 유효한
예외, 보고서 없음 → UNVERIFIED, FE-GATE-027 배선과 exit 0). 상태 판정을
PASS로 고정하는 변이를 넣으면 실패한다. 실제 실행: POLICY_VIOLATION
(운영 high 2, 개발 moderate 2), exit 0. 죽은 프록시로 돌리면 UNVERIFIED,
exit 0. check:ci PASS, CI workflow bytes PASS, ci-workflow-generation·
product-ci-overlay·ungated-scripts·removal-fixture·supply-chain 489건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제: pnpm audit(2026-11-04) 결과 advisory 44건(critical 1, high 16)이
있었고, 템플릿 자신의 취약점 정책(high 이상 차단, 예외 0건)을 어겼다.
대부분 개발 의존성이다: storybook 10.5.4(critical, dev 서버 코드 주입),
vite 8.1.5, vitest 4.1.10, 그리고 jsdom 경유 undici 7.28.0,
brace-expansion 5.0.8, nanoid 3.3.16, source-map-js 1.2.1.
고른 방법: 고친 버전이 있는 가장 가까운 줄로 올린다. vite 8.1.6(같은
8.1 줄), vitest·@vitest/coverage-v8 4.1.12(같은 4.1 줄), storybook
3종 10.6.5. 전이 의존성은 `pnpm update --depth Infinity`로 선언된 범위
안에서만 올렸다(undici 7.30.1, brace-expansion 5.0.12, nanoid 3.3.20,
source-map-js 1.2.2, postcss 8.5.23). 의존성 기준선을
update:dependency-baseline으로 다시 승인했다.
버린 대안: 운영 의존성 zod 4.6.7·react-router-dom 7.18.5도 함께 올리기.
직접 운영 의존성 변경은 dependency-change-evidence.json에 owner와 다른
reviewer가 필요해 기준선 생성이 거절했다(add:zod@4.6.7,
add:react-router-dom@7.18.5). 또 zod 4.6.7은 초기 JS를 약 7 KB 늘려
예산(204,800 B)을 넘긴다(측정 208,444 B). 그래서 이 커밋에 넣지 않고
다음 커밋에서 남은 위반으로 기록한다.
위험·한계: 남은 high 2건은 운영 의존성(zod GHSA-mrhx-c7xc-m3w5,
react-router GHSA-qwww-vcr4-c8h2)이다. 남은 moderate 2건(minimatch,
glob)은 고친 버전이 선언된 major 범위 밖이라 올리지 않았다. 의존성 수
561 → 562.
검증: pnpm audit → high 2(운영), moderate 2, critical 0. 이 상태에서
test:component 263, test:integration 117, build:storybook 성공,
check:bundle PASS(200,939 B, 25개), feature-shape-growth·supply-chain·
build-environment-bundle 39건 통과. 운영 의존성까지 올린 상태의
test:unit은 2,611건 통과였다(전체 test:unit은 브랜치 끝에서 다시 돌린다).
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-03
문제
starter-experience.md의 제품 소유 파일 표는 제품 런타임 설정 키의
FE-REG-ENV 행에 대해 "nothing requires the row"라고 적는다.
tests/unit/env-registry-coverage.test.ts(d0414c8)는 키마다 행을 요구하고,
fix/r1103-contracts(13-04)는 그 행의 required·defaultValue까지 스키마와
대조하게 했다. 매뉴얼 03 C절은 이 표를 정본으로 가리킨다.
고른 방법
- 그 셀을 "check:registries가 칸을 보고, env-registry-coverage 테스트
(test:unit)가 키마다 행과 required·defaultValue를 요구한다"로 바꾼다.
- 같은 표의 사라진 오류 문구(14-05 ①)는 fix/r1103-app(09-07)이 이미
고쳤다.
위험·한계
- 없음. 문서 한 셀이다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-05