문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.
고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
폴더 이름을 적지만 지운 사본에서도 통과하므로
deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
테스트와 검사기 시험에 적었다).
위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).
검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
문제
.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
The gate count and the reference-feature LOC table were hand-typed and
drifted from the code, so they are removed; the LOC table now names the
files and the command that measures them. .env.example pointed to
layers.md for runtime profiles, which never described them; it now points
to the README section that does. ci-quality-gates.md lists the three
things DOCUMENTATION_READY checks, so the gate name is not read as a
general documentation-accuracy guarantee. The route list (③) and the
README config location (④) were already fixed by 14-03 and 13-15.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The provider sandbox never ran. bubblewrap 0.9.0 stops parsing an `--args`
file at the first non-option and never hands the remainder back, so the
command written into that file was silently dropped: bwrap printed its usage
text, exited 1, and the provider produced no evidence at all. The options
still travel in the args file — that is what keeps host paths and credentials
out of `/proc/<pid>/cmdline` — but the command now rides on real argv, and
`encodeProviderBwrapInput` refuses a `--` so the drop cannot come back.
The scope wrapper then could not exit. It read the supervisor's liveness pipe
through `fs`, which runs a blocking `read(2)` on a threadpool thread; the
supervisor holds that pipe open for the scope's whole life, so the read never
returned and closing the descriptor did not interrupt it. Once bubblewrap
finished the wrapper deadlocked in `process.exit`, the scope outlived the
provider, and a completed run was reported as a timeout kill. The channel is
now read through the event loop, so teardown is observable and terminal.
Creation modes were left to the ambient umask. `mkdir(mode)` and `open(mode)`
are requests the kernel subtracts the umask from, so a runner exporting a
restrictive umask produced directories it could not enter and handed `tar` a
file it could not re-open. Private modes are pinned instead of inherited.
Promotion cleanup deleted before it checked. Removals run through a pinned
descriptor, so a leaf substituted after validation had this promotion's exact
five destroyed first and the substitution reported afterwards, leaving a
half-emptied directory a retry could not tell from a completed one. The name
is re-bound to the inode before anything is removed, so the failure is total.
Separately, release coherence proved the artifacts agreed with each other but
never that they belonged where they were going: a build whose runtime document
said `APP_ENV: local`, `AUTH_MODE: demo` and a loopback API is coherent with
itself and passed every gate. `public/` is copied verbatim into `dist/`, so
that local document shipped with every build regardless of what the build was
for. Runtime configuration now comes from a declared profile, and FE-GATE-027
refuses to admit an artifact to an environment it does not match — including
refusing an undeclared destination, so nothing is admitted by omission.
`REQUEST_TIMEOUT_MS` and `VITE_ROUTER_BASE_PATH` were validated and then
dropped: the V3 executor ran every operation on its contract's own deadline,
and Vite emitted root-absolute assets for a sub-path deployment. The timeout is
now a ceiling that may tighten a contract but never loosen one, and one base
path feeds the router, the Service Worker scope and the asset base together.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>