문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로
있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single
server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이
아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도
호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다.
고른 방법:
- nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를
문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live
모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은
절 이름·같은 언어(한국어)다.
- 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7;
listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types →
10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17;
index.html → 3·6; try_files fallback → 4·6; config.json·
release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18;
없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15;
.map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / →
1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19.
- static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다.
- ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권
user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는
방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은
scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로
바꾼다. 그 스크립트가 같은 세 방법을 출력한다.
버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기.
아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다).
위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일,
10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의
전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니
재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서
없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다.
검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그
~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의
경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함),
test:unit 3091 tests 통과.
Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
문제
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
문제: (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
문제: (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
문제: 3f9c087은 초기 청크를 묶지 않는 근거로 "템플릿은 HTTP/2 이상으로
서빙한다"를 정했다. 그런데 이 전제는 작업 기록인 performance-evidence.md
에만 있다. 호스팅을 정하는 사람이 읽는 현재 계약 문서(static-delivery.md)
에는 서빙 프로토콜 이야기가 없다.
고른 방법: static-delivery.md 끝에 한 단락을 더한다. HTTP/2 이상으로
서빙한다는 것, HTTP/1.1에서 늦어지는 정도(Fast 3G 약 1초), HTTP/2에서의
차이(100 ms 미만), HTTP/1.1만 되는 제품이 할 일을 적고 측정 기록으로
링크한다.
버린 대안: README의 배포 절에 적기. README는 배포 변수와 명령을 다루고,
호스트 동작은 static-delivery.md가 다룬다.
위험·한계: 수치는 2026-11-03 한 번의 측정이다. 셸이 바뀌면 달라진다.
검증: node scripts/verify-documentation-readiness.ts PASS_SCOPED
문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
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>