문제
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
문제
/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
문제: 의존성 취약점 판정은 운영 승격의 외부 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
문제
fb20699의 새 테스트는 보호 라우트 하나를 찾아 단언하고, 없으면 실패한다.
참조 기능을 지운 제거 fixture에는 보호 라우트가 없어서, test:sample-removal
(snapshot fd11d08)의 test:all과 test:coverage가 이 테스트 하나로 실패했다.
고른 방법
- 같은 파일의 "every non-public route" 반복 안에서 recovery-pending과
authenticated를 함께 단언한다. 라우트가 있는 템플릿에서는 같은 변이를 잡고,
보호 라우트가 없는 구성에서는 다른 단언처럼 대상이 없다.
검증
- 파일 4건 통과. 변이 L02(wait-for-session → show-sign-in)를 넣으면 그 반복
테스트가 실패한다(되돌림). eslint 통과.
- snapshot fd11d08의 test:sample-removal: 이 테스트 말고 실패한 검사가
없었다(documentation·lint·i18n·design-system 포함).
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 1101/10-03
문제
fix/r1103-contracts는 fix/r1103-http가 아직 없을 때
CommandEffectDescriptor에 없는 refusedBeforeWrite를 구조 캐스트로
읽었다. 두 브랜치를 합치자 그 칸이 타입에 생겼다. 또 행 투영 테스트가
Envelope가 아닌 operation에 refusedBeforeWrite를 적는데, http 쪽 조립
검사(1103/03-01)는 그것을 거절해 테스트가 ContractContributionError로
실패한다.
고른 방법
- api-operations.ts는 effect.refusedBeforeWrite를 타입으로 읽는다.
- 테스트의 create descriptor에 responseEnvelope ENVELOPE_V1을 주고,
code를 업무 거절 모양(TEST_ENTITY_INVALID 등)으로 바꾼다.
위험·한계
- 행 모양은 그대로다. 기준선 영향 없음.
검증
- tests/unit/api-operation-rows.test.ts 12건, test:unit 2,790건,
check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
문제: pnpm 11은 설치 정책을 pnpm-workspace.yaml에서 읽는다(13-09가
.npmrc에서 옮겼다). engineStrict·saveExact가 빠지거나 minimumReleaseAge를
기본값(1440분)보다 짧게 줄여도 실패하는 검사가 없었다(0929/13-08, 세
라운드 남음). 지원하지 않는 Node로 설치되거나, 새 의존성이 ^ 범위로
저장되거나, 방금 나온 버전이 설치될 수 있다.
고른 방법: unit 테스트가 pnpm-workspace.yaml의 engineStrict: true,
saveExact: true를 확인하고, minimumReleaseAge를 적었다면 1440 이상인지
본다. minimumReleaseAgeExclude 항목은 정확한 버전만 허용한다.
버린 대안: `pnpm config get`을 부르는 테스트. 자식 프로세스 비용이 들고
같은 파일을 읽는다.
위험·한계: 파일 텍스트를 정규식으로 읽는다. 키를 다른 YAML 형식(인라인
맵 등)으로 바꾸면 테스트가 실패하므로 놓치는 쪽으로는 틀리지 않는다.
검증: 2건 통과. saveExact: false와 minimumReleaseAge: 60으로 바꾸면
실패하고 되돌리면 통과한다.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 0929/13-08
문제
fix/r1103-storage가 더한 browser-file-session-capability·
runtime-adapters-product-scope-participants 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)의 제품 확장 타입 검사
테스트가 이 두 파일에서 TS2322로 실패한다(9b9d62a와 같은 원인).
고른 방법
- 두 테스트도 testRuntimeConfig로 설정을 만든다.
위험·한계
- 동작 변경은 없다.
검증
- tests/unit/product-extension-typecheck.test.ts, 두 테스트, test:recipes,
lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제
c4d5870 뒤 test:sample-removal이 문서를 복사하고 verify:documentation과 문서
테스트를 돌린다. 실제 드릴 실행(snapshot 0edc3fc)에서 두 가지로 실패했다.
- 드릴은 fixture에서만 tests/unit/ci-workflow-generation.test.ts와
tests/unit/removal-fixture.test.ts를 지운다(전체 저장소를 고정하는 테스트라).
docs/operations/adapter-remediation-ledger.md가 그 두 파일을 백틱 경로로 적어,
fixture의 문서 검사와 문서 테스트 7건이 실패했다. 샘플을 지운 실제 프로젝트는
그 테스트를 지우지 않으므로 이 실패는 fixture에만 있다.
- 잔여 검사가 tests/unit/documentation-readiness.test.ts의 정규식
REFERENCE_RESOURCE_[A-Z]+를 샘플 흔적으로 잡았다. 그 파일은 예전에는 fixture
에서 지워져 검사되지 않았다.
고른 방법
- 원장(기록 문서)의 그 세 곳을 백틱 없는 경로로 바꾼다. 드릴의 fixture 전용
삭제 목록 옆에 "현재 계약 문서는 이 파일들을 백틱 경로로 적지 않는다"를
적었다.
- 정규식을 [A-Z]+_RESOURCE_[A-Z]+로 쓴다. 라우트 ID를 지우는 용도는 같다.
- 버린 대안: 문서 검사에 fixture 전용 예외 경로를 넘기는 환경 변수. 운영
스크립트에 테스트용 입력이 생긴다. fixture 전용 삭제를 그만두기.
ci-workflow-generation 스냅샷은 줄어든 CI 계약과 맞지 않는다.
위험·한계
- 앞으로 현재 계약 문서가 그 두 테스트를 백틱으로 적으면 sample 드릴이 다시
문서 검사에서 실패한다. 실패 메시지가 파일과 경로를 적는다.
검증
- 수정 전 snapshot 0edc3fc의 test:sample-removal exit 1: documentation,
unit-integration, coverage, fixture-id-residue와 scaffold- 세 검사가 이 두
원인으로 실패. lint·check:i18n·check:design-system 등 나머지는 통과.
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지운 복사본(sim-sample-docs.sh)에서
verify:documentation PASS_SCOPED. 저장소에서 documentation-readiness 19건
통과, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
capability 제거 드릴의 fixture도 test:unit을 돈다. 앞 커밋들이 더한 가드
테스트 두 개가 그 안에서 실패했다.
- removal-fixture.test.ts: 문서 테스트 파일과 드릴 스크립트를 이름으로 읽는데,
fixture는 문서 테스트를 지우고(02-06) 드릴은 자기 스크립트를 지운다.
browser-file-storage·realtime 드릴이 이 두 건으로 `test` 검사에서 실패했다.
- feature-scaffold-drill: 제거 드릴이 자기 capability 명령을 계약에서 빼면,
scaffold 드릴 제외 목록의 그 스크립트가 "merge 단계에 없음"으로 실패한다.
고른 방법
- 문서 테스트는 "문서가 있는 곳에만 있다"를 단언한다(저장소: 둘 다 있음,
capability fixture: 둘 다 없음).
- 드릴 목록은 scripts/test-*.ts 중 removal-fixture.ts를 import하는 파일로 찾고,
sample·scaffold 드릴이 그 안에 있는지 확인한다.
- 제외 목록이 낡았다는 판정은 계약에 있으나 merge 단계 밖인 명령에만 한다.
계약에서 아예 빠진 명령(제거 드릴이 정리한 capability)은 낡은 것이 아니다.
위험·한계
- 계약에서 지운 스크립트의 제외 항목이 저장소에 남아도 이 검사는 알리지
않는다. 남아도 아무 명령을 숨기지 않는다.
검증
- 수정 전 snapshot(0edc3fc)에서 test:browser-file-storage-removal,
test:realtime-removal 모두 이 두 테스트로 exit 1(ENOENT).
- 수정 뒤 removal-fixture·feature-scaffold-drill 18건 통과, eslint·tsc 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
문제
tests/unit/runbook-drill.test.ts의 "상수 판정 금지" 검사는 옛 모양
(assertion(..., true), Asserted: true)만 찾는다. drill은 이제
verdict()로 "PASS"/"FAIL" 문자열을 쓴다. 지난 리뷰 변이(:238의
verdict(await builtAssetsPresent(...))를 상수 "PASS"로)가 이 검사를
통과했다.
고른 방법
- assertion(..., "PASS"), *Asserted / *AsExpected: "PASS", verdict(true)
모양을 더 찾는다. 옛 정규식 셋은 그대로 둔다.
위험·한계
- 문자열을 변수에 담아 넘기는 우회는 이 정적 검사가 못 본다. 그 경우는
동작 테스트(FE-RB-002 등)가 본다.
검증
- 검사 통과. 리뷰의 변이를 다시 넣으면 이 검사가 실패한다(되돌림).
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 0929/11-08
문제
decideRouteAccess의 recovery-pending 분기(wait-for-session)를 어떤 테스트도
보지 않았다. 지난 리뷰 변이 L02(wait-for-session을 show-sign-in으로)가 18파일
105개 테스트를 통과했다. 그러면 세션을 복구하는 중인 사용자가 들어갈 수 있는
페이지에서 로그인 화면으로 튕긴다.
고른 방법
- tests/unit/navigation-policy.test.ts에 보호 라우트 하나로 recovery-pending은
wait-for-session, authenticated는 허용임을 단언한다.
위험·한계
- 화면(route-status-surfaces) 수준의 대기 표시는 따로 고정하지 않았다.
검증
- 새 테스트 통과. 변이 L02를 넣으면 새 테스트만 실패한다(되돌림).
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 1101/10-03
문제
create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고
적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다.
그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가
88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서
생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이
실제로 그렇게 생겼다). 또 제품 기능 제거 드릴
(test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유
결함(16-02)이 드러나지 않았다.
고른 방법
- 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json
merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은
run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다.
- 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다:
브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix
browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한
provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다),
제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는
스크립트를 제외 목록에 두면 실패한다.
- 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로
다시 지운다(16-02 둘째 절반).
- 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다.
- 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본
에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십
분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을
고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다.
그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다.
위험·한계
- 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번).
FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다.
tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다.
- 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기).
검증
- RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what
test:feature-scaffold runs"가 수정 전 실패.
- 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성
fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부,
드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과.
verify:documentation PASS_SCOPED, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).
고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.
위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.
검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
문제
verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서
`corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의
명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장
docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께
지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도
알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger
사유는 "It passes at this commit"이라는 시점 문장을 담았다.
고른 방법
- 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서
명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash,
sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고,
--flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로
경로로 보지 않는다.
- 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick
경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이
있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not
verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다.
보고서 schema에 그 칸을 더했다.
- 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고,
ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을
고쳤다.
- 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고
오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛
경로를 적어 예외가 늘어난다.
위험·한계
- 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다.
- 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이
있는 개발 환경에서만 된다.
- 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다.
검증
- RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소
없음 보고) 실패.
- 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가
"names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation
PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified).
check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제
tests/fixtures/architecture/forbidden/**에는 fixture 전용 ESLint 블록이
붙어 있었다. 모든 계층의 금지 import와 fetch·localStorage·sessionStorage
금지를 합친 것이다. check-architecture.ts는 fixture마다 ESLint 종료 코드가
0이 아니면 거부됐다고 셌다. 그래서 운영 src/presentation/** 블록에서 계층
import 금지와 fetch 금지를 지워도(변이 M2) check:architecture는 "9 forbidden
rejected"로 통과했다. 전역 fetch·localStorage 금지는 이 ESLint 블록 말고 지키는
검사가 없다.
고른 방법
- 새 scripts/lib/architecture-lint-fixtures.ts가 fixture마다 그것이 대표하는
운영 경로(lintAs, 예: src/presentation/__architecture_fixture__/…)와 거부해야
하는 규칙(rejectedBy)을 적는다. ESLint API lintText(code, { filePath })로
그 경로의 운영 설정을 그대로 적용한다. 금지 fixture는 그 규칙이 보고해야
통과하고, 허용 fixture는 계층 규칙(no-restricted-imports·globals)이 아무것도
보고하지 않아야 통과한다. 목록에 없는 fixture 파일도 실패로 센다.
- domain fixture는 domain 코드가 실제로 사는 src/features/*/domain 블록으로
검사한다(최상위 src/domain 폴더는 없다).
- fixture 전용 ESLint 블록을 지운다. check-architecture.ts에서 쓰이지 않게 된
pnpm 하위 프로세스 실행과 npm_execpath 요구를 지운다.
- 버린 대안: 금지 fixture 삭제. import 방향은 그래프가 지키지만 전역 금지의
검출이 0이 된다. 종료 코드만 보고 운영 경로로 옮기기. 다른 규칙(화면 문구
등)이 걸려도 거부로 센다.
위험·한계
- 계층 규칙 이름이 바뀌면 fixture 표의 rejectedBy도 같이 고쳐야 한다(고치지
않으면 실패로 드러난다).
- 출력 문구가 "3 allowed PASS, 9 forbidden rejected by the production rule for
their layer"로 바뀐다. 이 문구를 읽는 스크립트는 없다.
검증
- RED: 수정 전 변이 M2(운영 presentation 블록의 계층 import 금지와 fetch 금지
삭제)에서 check:architecture exit 0, "9 forbidden rejected".
- 수정 뒤 같은 변이에서 check:architecture exit 1, presentation fixture 5개가
"was accepted"로 실패. 되돌린 뒤 exit 0.
- 새 tests/unit/architecture-lint-fixtures.test.ts 3건(운영 설정 통과,
overrideConfig로 규칙을 끄면 실패, 목록 밖 fixture 실패) 통과.
architecture-report 3건 통과. check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-04
문제
짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이
SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와
5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에
bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의
어떤 검사도 알리지 않았다(README 10.6).
고른 방법 (결정 D6 (1)+(2))
- config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한
문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당.
- config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과
§4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다.
백엔드가 문서에 적은 사실만 담는다.
- tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를
확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서
같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은
둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절
읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이
늘거나 status가 바뀐 JSON을 넣으면 실패한다.
- scripts/check-backend-contract-drift.ts(check:backend-contract-drift):
형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를
바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다.
ungated-scripts.json에 이유를 적었다.
- 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는
5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고
줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler →
HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator).
버린 대안
- 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만
알리고 무엇을 고칠지 말하지 않는다.
- 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는
pin과 표가 작다.
위험·한계
- 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와
리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은
백엔드 저장소 몫이다.
- 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500
IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다.
프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그
문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다.
검증
- 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트
표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER
추가, 답 표의 RECOVERY_REQUIRED status 변경.
- check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드
checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력.
- test:unit 178파일 2,645건, check:ci, check:types, eslint,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06
Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
문제: 조회는 cache 이름 목록을 pointer보다 먼저 읽는다. 그 사이 다른
탭의 activation이 pointer를 새 캐시로 옮기면 목록에 그 캐시가 없다.
코드는 목록을 한 번 더 읽고서야 STORAGE_EVICTED를 낸다
(1101/02-04 ⑤, N39). 이 재확인을 지워도 테스트가 모두 통과했다. 빠지면
방금 배포한 release의 첫 조회가 "지워졌다"로 끝나고 REHYDRATE로 간다.
고른 방법: 첫 keys()만 배포 전 목록을 돌려주는 저장소로 r2 활성화 뒤
조회한다. adapter는 만들 때 keys를 잡아 두므로 저장소 하위 클래스로
한 번만 낡은 답을 준다.
위험·한계: 테스트만 바꾼다. 1101/02-04의 N38(host storageArea 비교)은
pulse wire 값을 만드는 하네스가 필요해 이번에 하지 않았다.
검증: N39 변이를 넣으면 이 테스트가 STORAGE_EVICTED로 실패하고(cache
단위 3파일 + tests/recipes 71건 중 1건), 되돌리면 같은 파일 14건 통과.
check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
문제
FE-GATE-020의 제거 드릴은 정해진 목록만 fixture에 복사하고, 그 목록에
README.md·CHANGELOG.md·docs/가 없다. 그런데 fixture에서 도는 test:all에는
그 문서를 읽는 테스트 두 개(documentation-readiness,
changelog-review-ids)가 들어 있다. sample-removal 드릴만 두 테스트를
지웠고, browser-file-storage·realtime·optional-recipe 드릴은 제거 대상과
무관하게 `test` 검사에서 ENOENT로 항상 실패했다. 세 드릴의 실패는 merge
게이트를 빨갛게 하고 release 단계도 막는다.
고른 방법
- scripts/lib/removal-fixture.ts에 문서 목록
(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과 그 문서를 읽는 테스트 목록
(REMOVAL_FIXTURE_DOCUMENT_TESTS)을 한 번만 둔다. prepareRemovalFixture는
문서를 복사하지 않은 fixture에서 그 테스트를 지운다. 문서를 복사하는
드릴(test:feature-scaffold)에서는 그대로 돈다.
- sample-removal 드릴의 자체 제외 두 줄을 지운다.
- 버린 대안: 모든 드릴이 문서까지 복사. capability 드릴은 문서가
설명하는 runtime을 지우므로, 문서 테스트가 지운 경로를 실패로 본다.
드릴마다 문서 예외가 필요해진다. 드릴마다 제외를 복사. 지금 고장의
원인(갈라진 목록)을 되풀이한다.
- 단위 테스트가 목록을 고정한다: 문서 없이 복사하면 제외, 문서를
복사하면 제외 없음, 제외 대상이 실제로 문서를 읽음, 다섯 드릴이 모두
prepareRemovalFixture를 쓰고 자체 제외 목록을 두지 않음.
위험·한계
- 저장소 루트 문서를 읽는 테스트가 더 생기면 이 목록에 더해야 한다.
더하지 않으면 capability 드릴이 다시 ENOENT로 실패한다(조용히 통과하지는
않는다).
- 세 드릴의 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- RED: 새 테스트 "is the only exclusion list"가 수정 전 sample 드릴의 자체
목록 때문에 실패.
- tests/unit/removal-fixture.test.ts 12건 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-06
문제: 1101/02-04의 두 변이가 이번에도 cache 단위 테스트를 모두
통과했다. N26b는 Cache-Control: no-cache 거절, N26은 Set-Cookie 응답
거절을 지운다. 둘 다 빠지면 사용자별이거나 재검증이 필요한 응답이 익명
공용 캐시에 들어간다. 기존 표는 no-store·pragma·www-authenticate만 따로
보았다.
고른 방법: 응답 검증 표("keeps response validation failure codes")에 두
행을 더한다. 각 행은 규칙 하나만 어긴다.
위험·한계: 테스트만 바꾼다.
검증: 두 변이를 하나씩 넣고 cache 단위 3파일 + tests/recipes를 돌렸다.
둘 다 이 테스트가 실패했고 되돌린 뒤 통과. eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
문제: complete 응답을 잃은 뒤 다음 upload()가 재조정해 서버 status
QUARANTINED를 찾았을 때, 로컬 checkpoint 삭제가 한 번 실패하면 runtime이
그 실패를 그대로 돌려준다({UNAVAILABLE, UPLOAD_RECONCILE, retryable:true,
RESUME}). 서버에는 자원이 이미 있는데 이 호출은 resourceId를 잃는다. 같은
상황의 complete 경로는 삭제 실패를 무시하고 성공을 준다.
고친 방법: 재조정의 QUARANTINED 분기도 complete 경로와 같이 삭제 결과와
상관없이 {QUARANTINED, resourceId, replayed:true}를 준다. 남은 행은 다음
upload()나 abort()가 같은 자원으로 정리한다. 설계 문서 4.3절의 같은 규칙
줄에 재조정 경우를 더했다.
위험·한계: 삭제가 계속 실패하는 저장소에서는 행이 남는다. 다음 호출마다
status를 한 번 읽고 같은 resourceId를 replayed로 준다. complete 경로와 같은
한계다.
검증:
- 새 테스트: 고치기 전 {ok:false, UNAVAILABLE, UPLOAD_RECONCILE} (리뷰 X4와
같다), 고친 뒤 {ok:true, QUARANTINED, resource_01, replayed:true}, 행 남음,
다음 호출이 정리
- 영역 단위 테스트 15파일 276건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 0929/01-02
문제: 이번 리뷰에서도 아래 browser-files 변이가 관련 unit 파일을 모두
통과했다.
- M10(0929/02-05): bounded download의 catch에서 lease?.release()를 지운다.
handoff가 던지면 만든 blob URL이 runtime dispose까지 남는다.
- N27(1101/02-04 ③): 같은 파일을 다시 inspect할 때 이전 receipt를
무효화하지 않는다. 다른 정책으로 검사한 옛 receipt로 preview가 열린다.
- N29(1101/02-04 ①): object URL lease의 합계 바이트 상한을 지운다. 기존
테스트는 개수 상한이 먼저 막아 바이트 상한을 보지 못했다.
- N30(1101/02-04 ⑥): browser-managed handoff의 fragment 거절을 지운다.
고른 방법: 규칙마다 실패하는 테스트 하나. N29는 개수 여유가 있을 때도
바이트가 막는 경우를 기존 상한 테스트 끝에 더했고, N30은 target 규칙
표에 fragment href 한 줄을 더했다.
위험·한계: 테스트만 바꾼다. 1101/02-04의 나머지(N26·N26b는 다음 커밋,
N38 host storageArea, N39 조회 keys() 재확인)는 이 커밋에 없다.
검증: 네 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes를
돌렸다. 모두 새 테스트(또는 늘린 행)가 실패했고 되돌린 뒤 통과. 원래
코드에서 두 파일 47건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-05, 1101/02-04
문제: FILE_BYTE_SOURCE로 이어 올리면 runtime이 서버가 이미 받은 part까지
SHA-256으로 다시 검증한다. 검증(verifyUploadPartBytes)이 수락 확인보다
앞에 있기 때문이다. 8 part 중 6개가 수락된 뒤 이어 올리면 part 해시가
16번 돈다. RANGE_READER 경로는 같은 상황에서 10번이다(manifest 8 + 보낼
part 2).
고친 방법: 스트림 경로에서 수락된 part는 검증 전에 건너뛴다. 보내지 않는
part의 바이트는 검증할 필요가 없다. 파일이 checkpoint와 같은지는 그 앞의
manifest 계산이 이미 확인한다(다른 파일이면 STALE_RESULT). part의
offset·길이 확인은 그대로 모든 part에 한다.
위험·한계: 스트림은 여전히 처음부터 끝까지 읽는다. 읽기를 건너뛰는 것은
스트림 모양상 할 수 없다.
검증:
- 새 테스트(8 part 중 6개 수락 뒤 FILE 재개, part 크기 digest 수): 고치기
전 16, 고친 뒤 10
- 영역 단위 테스트 15파일 275건 통과
- check:types(test), eslint(바꾼 파일) 통과
Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 1101/01-02
문제: 2026-11-01 05-06에서 남은 두 분기를 테스트가 잡지 못한다. 이번
리뷰에서도 두 변이가 Web Storage 관련 테스트 3파일 49건을 통과했다.
- W4: quota 판정 목록에서 Firefox의 NS_ERROR_DOM_QUOTA_REACHED를 빼도
테스트가 통과한다. 빠지면 Firefox의 quota 실패가 memory fallback 없이
STORAGE_UNAVAILABLE이 된다.
- W8: 만료 비교 `<=`를 `<`로 바꿔도 통과한다. 만료 시각과 같은 순간에
값을 돌려준다.
고른 방법: 각 분기에 실패하는 테스트 하나씩. 저장소 test double에
Firefox 이름으로 던지는 모드를 더했고, 만료 경계는 expiresAt 100·101을
now 100에서 읽는다.
위험·한계: 테스트만 바꾼다. codec을 직접 부르는 테스트는 여전히 없다.
검증: W4·W8 변이를 하나씩 넣고 storage-registry·runtime-adapters·
browser-storage-policy 테스트를 돌렸다. 둘 다 새 테스트가 실패했고,
원래 코드에서 storage-registry 26건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 1101/05-06
문제
V2를 지울 때(048f490) 같이 지운 테스트 둘이 V3 동작도 지키고 있었다.
- 운영 설정 MAX_RETRY_ATTEMPTS가 실행기에 닿는지. V3는
runtime-adapters.ts에서 넘긴다. 값을 상수 2로 바꾼 변이 H53이 15파일
143건을 통과했다. 장애 때 재시도를 끄는 손잡이가 조용히 사라질 수 있다
(REQUEST_TIMEOUT_MS는 실제로 한 번 그렇게 버려졌다).
- 호출자·scope signal에 단 abort listener를 지우는지. 호출자 쪽 제거를 지운
H56은 머지 게이트 테스트를 모두 통과했고, scope 쪽(H57)은 nightly
tier의 long-session 테스트 하나만 잡았다.
고른 방법
- tests/features/reference-feature/reference-runtime-composition.test.ts:
실제 createRuntimeAdapters에 MAX_RETRY_ATTEMPTS 0·1을 주고, 재시도
예산 2인 참조 목록 조회가 503에 1회·2회 나가는지 센다(Math.random 0으로
backoff 대기 없음). 설치된 기능의 HTTP가 있어야 조립 루트 경로를 탈 수
있어 참조 기능 테스트에 두었다. test:reference-feature는 머지 게이트다.
- tests/unit/http-execution-v3.test.ts: 응답으로 끝날 때와 호출자 abort로
끝날 때, 호출자·scope signal에 더한 abort listener가 같은 함수로 모두
지워지는지 센다.
위험·한계
- ①은 참조 기능에 기댄다. 샘플을 지운 제품에서는 이 테스트도 같이
빠진다. 조립 루트를 기능 없이 부를 수단이 없어서다.
- 10-04 ③(realtime snapshot의 GET 조건)은 다른 작업 몫이다.
검증
- 변이 H53·H56·H57을 하나씩 넣으면 새 테스트가 실패하고, 되돌리면 통과한다.
- 두 파일 76건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-04
문제
test:sample-removal은 참조 기능을 지운 복사본에서 test:unit을 돈다. 그때
product-extension-typecheck 픽스처 기능이 유일한 기능이 되는데, 메시지
catalog가 비어 있어(messages: {}) 메시지 키 타입이 무너져 tsc app이 presentation
파일 수십 곳에서 실패했다. 템플릿 결함이 아니라 픽스처 기능의 모양 문제다.
고른 방법
픽스처 기능에 두 locale의 메시지를 준다. two-feature-install-typecheck 픽스처와
같은 모양이다.
위험·한계
없다고 보는 이유: 테스트 픽스처 문자열만 바뀐다.
검증
- product-extension-typecheck.test.ts 통과(전체 repo).
- test:sample-removal 재실행 결과는 브랜치 보고에 적는다.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제: putIdleTimeoutMs < mutationLockWaitTimeoutMs는 05-07이 기대는
관계다(멈춘 put이 idle 상한에서 origin lock을 놓아야 줄 선 writer가
대기 상한 전에 돈다). 이 관계가 opfs-policy.ts 주석에만 있고, 정책
검사는 각 값의 범위만 본다. 두 값을 뒤집은 정책은 조용히 통과하고,
멈춘 put 하나가 다른 탭의 모든 쓰기를 BLOCKED로 끝낸다.
고른 방법: assertOpfsRuntimePolicy가 putIdleTimeoutMs >=
mutationLockWaitTimeoutMs를 TypeError로 거절한다. 다른 정책 오류와
같은 자리·같은 방식이다. 기본값(2분 < 10분)과 repo 안의 모든 정책은
이미 관계를 지킨다.
위험·한계: 이 관계를 어긴 정책을 쓰던 다운스트림은 조립 때 실패한다.
의도한 동작이다.
검증:
- RED: opfs-worker-runtime.test.ts 새 2건(같음, 김)이 throw 없음으로 실패.
- GREEN: OPFS 단위 3파일 + tests/recipes + tests/contract 174건 통과.
check:types, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-09
문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.
고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
"effect_certainty는 필요해지면 더한다" 문장은 지웠다.
버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
섞인다. 비율은 effect_certainty로 센다.
위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
맞춰야 한다.
검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
tests/unit·integration·component·features·contract·runtime-schema·platform
282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
문제: browser-files runtime은 세션을 모르고, 닫는 수단은
runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state
scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일
runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지
않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번
불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서
연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중
download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이
메모리와 다운로드 폴더에 남을 수 있다).
고른 방법(리뷰 5.3절 (다) + 레시피 예제):
- ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant:
label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline
lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가
돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가
있으면 template participant와 같이 READY로 가지 않는다(FAILED).
composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이
자리를 미리 만들고 나중에 채운다.
- recipes/frontend-capabilities/browser-file-session-capability.ts:
기능에는 runtime 대신 current() getter를 주고, participant가 dispose한
뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다.
- 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새
레시피 파일도 같이 지운다.
버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수
없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독
위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를
제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 —
adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다.
위험·한계:
- 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로
컴파일된다, [계약]).
- 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을
들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음
세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는
없다).
- app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다.
- 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다).
- scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도
고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다.
검증:
- RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환
뒤에도 이전 runtime의 readRange가 ok로 실패.
- GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange
UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대
runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope-
participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행).
- 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락)
모두 새 테스트가 잡았다.
- runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과.
check:types, 바꾼 파일 eslint, check:architecture, verify:documentation
통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유
config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도
"deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이
바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고,
다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다.
고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈
파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다.
- deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지
슬롯(promoted-release download, digest로 확인하는 extract, deploy)은
템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을
그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay
양쪽에서 슬롯을 채우면 거절한다.
- mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의
product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE
id·명령·산출물·readiness 공식은 건드리지 못한다.
loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약
기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는
거절하고, 제품 gate script는 ungated 검사에서 gated로 센다.
버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할
명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이
산출물 전달이 검증되지 않았다).
위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식
밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성
workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면
재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다.
검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯
채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job
렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를
채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성
YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿
변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다.
ci-workflow-generation 425건, check:ci PASS.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제: composeProductSessionOwner는 config와 raw fetcher만 받는다. owner는
http보다 먼저 만들어져 세션 조회·토큰 호출을 직접 해야 하는데, 응답하지
않는 호출 하나가 세션을 recovery-pending에 영원히 둔다. 픽스처의 쿠키
owner 스케치가 바로 그렇게 쓴다. 로그인 리다이렉트에 필요한 페이지
(location·history)와 sessionStorage도 bootstrap lint가 전역 접근을 막아
제품 파일에서 얻을 길이 없다.
고른 방법: ProductSessionOwnerContext에 넷을 더한다.
- fetch: 헤더와 본문 전체에 마감 하나(REQUEST_TIMEOUT_MS가 상한, 호출이
줄일 수만 있다). 본문은 64 KiB까지 메모리로 읽어 새 Response로 준다.
redirect는 항상 error. fetcher가 signal을 무시해도 경합으로 끝난다.
- readCookie: composeProduct와 같은 host cookie 읽기.
- page: href·replaceUrl·assign. host에 없으면 throw로 닫힌다.
replaceUrl은 라우터의 history state를 그대로 둔다.
- redirectStorage: host sessionStorage. 토큰이 아니라 리다이렉트 한 번
동안의 상태만 둔다고 계약에 적었다.
조립은 새 파일 product-session-owner-context.ts에 두고
runtime-adapters.ts는 호출 한 곳만 바꿨다. fetch 구현
(session-owner-fetch.ts)은 처음 쓸 때 동적 import로 읽는다. 초기 번들
여유가 3 KB 남짓이라 demo 모드나 owner 없는 제품이 이 코드를 내려받지
않게 했다.
버린 대안:
- platform 커널 createAbortableOperation 사용. 커널이 boot가 이미 읽는
배럴과 같은 청크로 묶여 지연 청크로 빼도 초기 번들에 남았다(빌드로
확인). 그래서 read-bounded-boot-json.ts와 같은 마감 방식을 쓴다.
- 마감만 주고 본문은 owner가 읽게 두기. 본문이 멈추면 다시 무한 대기다.
위험·한계: fetch는 필수 필드라 ProductSessionOwnerContext를 직접 만드는
제품 테스트는 컴파일이 깨진다. 기존 fetcher는 그대로 둔다. 지연 청크
적재 시간은 마감에 들어가지 않는다(라우트 청크와 같다).
검증: tests/unit/product-session-owner-context.test.ts 12건(구현 전 모듈
없음으로 실패 확인), product-composition-fixture·runtime-adapters 테스트
통과, check:types, eslint 통과. build + check:bundle: initial JS
202,242 / 204,800 B gzip(09-11 포함, 기준 201,848), 지연 청크
session-owner-fetch 0.81 kB gzip.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
문제: (1) 배포 슬롯 계약은 단계 종류만 제한하고 "마지막이 deploy 하나"만
강제했다. checkout → setup-node → frozen-install → deploy(script)처럼
후보 archive를 받지 않고 다시 빌드하는 슬롯도 check:ci를 통과했고,
생성된 job 이름은 그대로 deploy-promoted-release였다(리뷰 실험 E-3).
(2) 생성기는 슬롯의 환경 바인딩을 job 수준 env:로 썼다. 그래서
secrets.* 배포 자격 증명이 checkout, setup-node, frozen-install과
제3자 download action에도 보였다.
고른 방법: (1) deploy 단계에 script가 있으면 promoted-release 전송 하나만
download하고, 그 경로의 release-candidate.tar.gz를 extract하고,
CANDIDATE_ARCHIVE_SHA256을 immutable_build의 digest로 바인딩해야 한다.
extract는 verify-ci-candidate-archive.ts가 digest로 확인한다. 빈 슬롯은
그대로 허용한다. (2) 배포 슬롯의 secrets.* 바인딩은 deploy 단계의 env:로만
렌더링한다. vars.*와 후보 digest는 job 수준에 남는다(extract가 digest를
쓴다).
버린 대안: 슬롯 단계를 템플릿이 통째로 고정하기. 다음 커밋의 제품
overlay가 채우는 모양을 고정하고, gates.json으로 채우는 길은 이 규칙으로
막는다.
위험·한계: 슬롯이 받은 파일을 deploy 스크립트가 실제로 올리는지는 계약이
볼 수 없다. 그것은 FE-GATE-019의 config.json·entry 대조(앞 커밋)가 결과로
본다. 템플릿 슬롯은 비어 있어 생성 workflow 바이트는 바뀌지 않는다.
검증: ci-workflow-generation.test.ts에 후보 없이 deploy하는 슬롯과
digest 없이 extract하는 슬롯의 거절, secret이 deploy 단계 env에만 한 번
나오는 것을 더했다(고치기 전 3건 실패). 425건 통과. check:ci PASS,
CI workflow bytes PASS.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-05
문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만
후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬
프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback
API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인
(FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는
config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만
비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip
바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지
않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다.
고른 방법:
- 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치
두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나
읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수
(scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다.
- 받은 index.html의 entry script를 후보 index.html의 것과 비교한다.
- cache-policy.json에 transport.alpnProtocols(["h2"])와
hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS
handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의
Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로
붙어서 프로토콜은 따로 확인해야 한다.
- nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와
release-cache-rollback.md에 두 전제와 실패 조건을 적었다.
두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다.
버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이
생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기
(아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면
제품이 끌 수 있다).
위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그
제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와
Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약
규칙은 다음 커밋(제품 overlay)에 있다.
검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상
스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry →
FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을
더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험:
http2.createSecureServer → "h2", https.createServer → "http/1.1",
인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID.
verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과.
Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02
문제: OPFS worker runtime을 메모리에서 돌리는 MemoryDirectory·MemoryFile이
tests/unit/opfs-worker-runtime.test.ts 안에만 있다. 05-04를 고치려면
recipe fake와 runtime에 같은 시나리오를 돌리는 parity 테스트가
tests/recipes에 필요한데, 그 테스트는 이 파일 시스템을 쓸 수 없다.
unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로
parity 테스트를 unit 쪽에 둘 수도 없다.
고른 방법: 그 블록(MemoryNode·MemoryFile·MemoryDirectory·fileHandle·
notFound)을 그대로 tests/helpers/memory-opfs.ts로 옮기고 export한다.
memory-indexeddb.ts와 같은 자리다. 코드는 바꾸지 않았다. helper는 src를
import하지 않아 browser-file-storage 제거 드릴에서도 남아도 된다.
위험·한계: 동작 변경 없음.
검증: opfs-worker-runtime.test.ts 82건 통과. check:types:test, 바꾼 파일
eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04
문제
워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번
리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect:
"error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의
CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8).
고른 방법
- service-worker-runtime.test.ts에 테스트 3건을 더한다.
- install이 자산마다 cache no-store, credentials omit, redirect error로
요청한다(M1).
- 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은
client의 drain 응답은 세지 않는다(M3, M9).
- active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8).
- 동작은 바꾸지 않는다.
위험·한계
- N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를
흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다.
검증
- service-worker-runtime 64건 통과.
- 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고
되돌렸다.
- 바꾼 파일 eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는
logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된
ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은
남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE
DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도
지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고
수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고,
그 경보가 진짜 손상을 가린다.
고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지
않는다. 대신
- journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키
범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음).
- reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸
없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다.
- runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면
없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다.
버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 —
그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번).
위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage
.unattributedRows, OpfsReconciliationReport
.unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면
지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이
SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의
partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다.
offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B.
검증:
- RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음,
opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions
없음으로 실패.
- GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다.
키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면
DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host +
tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일
eslint, check:optional-recipes:source PASS, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03
문제
기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은
"missing registry source src/features/loaded-feature-runtimes.ts: Installed
contract contribution is not composable" 두 줄, "FE-REG-API is not an
object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA",
"breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은
ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다.
끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을
제안한다(실험 E-9).
고른 방법
- source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께
적는다.
- 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사
("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교
(removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지
않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다.
- errors.md 레지스트리 표에 이 메시지 행을 더했다.
버린 대안
- 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와
CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다.
위험·한계
- source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도
"missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서
지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다.
- FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다.
검증
- RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가
다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를
던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고
cascade 3줄이 더 나와 실패했다.
- GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록
operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason:
reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId
NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다.
- check:registries:fixture·check:routes:fixture·baseline-fixture가 기대
진단으로 실패한다. eslint, check:types:node, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06
문제
참조 기능의 FE-REG-SCHEMA 행은 응답 스키마를 STRIP_UNKNOWN, 요청 스키마를
REJECT_UNKNOWN이라 적는다. 실제 정책은 zod .strip()·.strict()가 정하고,
unknownFieldPolicy·direction을 읽는 실행 코드는 없다. 응답 DTO를 .strict()로
바꿔도 check:registries와 관련 테스트가 모두 통과한다(실험 X8). 그러면
백엔드가 응답에 필드 하나를 더할 때마다 그 API가 SCHEMA_MISMATCH로
실패하는데, 스냅샷과 docs/contracts/compatibility.md는 여전히 additive라
말한다.
고른 방법
설치된 기능의 HTTP descriptor마다 입력·출력 검증기를 FE-REG-SCHEMA 행과
대조하는 테스트를 더한다.
- direction: 입력 검증기 행은 REQUEST, 출력 검증기 행은 RESPONSE.
- unknownFieldPolicy: 아무 스키마도 선언하지 않는 키 하나를 가진 객체와,
그 객체 하나를 담은 배열을 검증기에 넣는다. 그 객체 위치의
unrecognized_keys면 REJECT_UNKNOWN, 객체 안을 봤는데 그 issue가 없으면
STRIP_UNKNOWN이다. 정책을 적은 행만 본다.
loaded-feature-runtimes를 읽으므로 다운스트림이 더한 기능도 같은 검사를
받는다. create:feature 뼈대(NoRequest strict, 목록 응답 strip)도 맞는다.
버린 대안
- 메타데이터에서 두 칸을 지우기: 읽는 곳이 없어 가장 단순하지만 호환
문서의 근거가 사라지고 기준선 재승인이 필요하다. 메타데이터 생성은
다른 작업(16-04~06) 범위다.
- 스키마마다 유효한 예시 값을 두고 모르는 키를 더하기: 기능마다 예시를
손으로 써야 해 다운스트림 기능을 자동으로 덮지 못한다.
위험·한계
- 탐침은 payload의 첫 객체 단계(객체, 또는 배열의 항목)만 본다. 그 아래
중첩 객체의 정책은 보지 않는다.
- problem 검증기는 FE-REG-SCHEMA 행이 없어 대상이 아니다.
검증
- 변이: 응답 DTO .strip()→.strict()(X8), 생성 명령 .strict()→.strip(),
응답 행 direction을 REQUEST로 바꾸면 각각 실패한다. 되돌리면 2건 통과. 설치된 기능이 없으면(샘플 제거 뒤) 두 건 모두 빈 채로 통과한다.
- eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-03
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.
고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
(409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
<FEATURE>_INVALID 예와 거부 문구를 적었다.
버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).
위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.
검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
계속 검출.
- check:types, lint, check:registries, check:architecture,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).
고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
소유 src/features/product-capabilities.ts의
PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
(validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
(선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.
위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.
검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
runtime-composition-service-worker-telemetry, product-features,
product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫
복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이
섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가
비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md,
static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고
현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발).
(3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서
픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드
(약 201 KB)가 아니라 약 264 KB였다.
고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가
기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의
비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰
값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript
한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계
1%, 파일 수 정확히, 기능·context 비용 10%). 기록은
`measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다.
문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고
돈다.
버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서
숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가
필요하다).
위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는
변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다.
`298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은
측정 기록으로 남겼다.
검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2%
바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개,
기능 +765 B, context +214 B. feature-shape-growth 7건 통과,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04