문제
.env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고
적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를
검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고,
build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를
스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID
변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세
줄이고 고치는 방법이 없다.
고른 방법
- check-release-admission.ts가 `--config <고친 사본> --original <배포된
원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고,
원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도
바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다.
`--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지
않는다).
- 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다.
그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다.
- FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서
rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고,
release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치
설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드
없이 바꾼다"로 좁혔다.
- pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다.
버린 대안
- `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼
빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로
더 좁다.
- release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더
늘고, 여전히 BUILD_ID만 본다.
- 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어
스위치의 목적이 사라진다(리뷰 대안 비교).
위험·한계
- 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도
"바뀜"으로 거절한다(닫힌 쪽으로 실패).
- 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release
기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
새 6건 실패. 모두 "release admission refused: dist/config.json is
unreadable"(--config를 무시하고 dist를 읽음)
- GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음,
SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경·
--original 누락은 exit 1
- runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed
- 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성),
`-- --config dist/config.json --original public/config.json` ADMITTED
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05
문제
라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지
않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약
(config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는
`/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로
PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과
검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다.
고른 방법
- cache-policy.json에 표면 두 개를 더한다.
- appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은
Cache-Control, content-type, 보안 헤더를 요구한다.
- serviceWorker: `/service-worker.js`, no-cache, JS MIME.
`requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드
(ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은
checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다.
- live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨
fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다.
appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를
가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를
모두 FAIL로 잡는다.
- release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를
적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라
404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을
적었다.
버린 대안
- createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약·
테스트가 모두 바뀐다(리뷰 대안 비교에서 기각).
- 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만
읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다.
- 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지
않았다.
위험·한계
- nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다.
호스트가 실제로 무엇을 주는지는 live probe가 확인한다.
- 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로
실패한다(의도).
- 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
5 failed. "expected undefined to match object { cacheControl:
'no-cache', …}"(정책에 appRoute·serviceWorker 없음),
"probeLiveRelease is not a function"
- GREEN: 같은 파일 22 passed. fallback 없는 호스트에서
["appRoute http-status", "appRoute entry-script"]가 실패로 나온다
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts:
483 passed
- build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3,
결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED, check-ci-contract PASS
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04
A worker that stops the page from booting had no exit: every off switch was
page code. A REMOVE_REGISTRATION release now writes a service-worker.js that
skips waiting and unregisters itself (D-5), checked end to end in the browser.
The runbook and rollback doc now name only paths that exist in code.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FE-GATE-019 ran before the release existed and passed by comparing the declared
headers with a copy of themselves. The fixture result is now UNVERIFIED, the
gate runs in the production stage after deployment, and the live probe
requests the entry script the served index.html names (D-14).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Provider evidence expires two hours after issue, so no repo tool could
re-verify a release before deploying it later or rolling back to it.
verify:promotion --archived keeps every signature, digest and member check and
judges freshness at the recorded promotion time; the FE-RB-005 drill takes the
extracted release with --release-root.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
verify-hosting-headers.ts passed the serviceWorker probe only when
cache-policy.json said `enabled: false` AND dist had no worker script, so no
configuration let a supported ACTIVE build through the hosting gate. The
probe now follows the static selection: ACTIVE requires exactly the selected
`service-worker.js` at the dist root; null / REMOVE_REGISTRATION /
PURGE_OWNED_RESOURCES still reject any worker script. The now-unused
`serviceWorker.enabled` policy flag is removed; the artifact keeps the same
`serviceWorker`/`enabled` probe key.
RED (ACTIVE build from the previous commit, `node scripts/verify-hosting-headers.ts`):
Hosting cache/content-type/security header verification failed. exit=1
{ surface: serviceWorker, header: enabled, expected: false, observed: true, passed: false }
GREEN: same ACTIVE build -> PASS exit=0 (expected: true, observed: true);
default build -> PASS; default build + stray dist/service-worker.js -> exit=1
(reason "dist worker scripts: service-worker.js");
tests/unit/hosting-probe.test.ts 13 passed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>