문제
test:sample-removal은 참조 기능을 지울 때 그 전용 script
test:reference-feature도 package.json에서 지운다. 샘플을 지운 프로젝트도
같다. 그런데 docs/testing/taxonomy.md와 원장 두 행이 그 script를 백틱·명령
형태로 적어, 문서 검사가 "names package scripts that do not exist:
test:reference-feature"로 실패했다(b6bfc9b snapshot의 드릴 실행).
고른 방법
- 참조 기능 경로와 같은 규칙(patterns.md 첫머리): 참조 기능이 가진 script는
백틱이나 `corepack pnpm` 없이 적고 "참조 기능과 함께 지워진다"를 붙인다.
위험·한계
- 템플릿에서도 문서 검사가 이 script 이름의 존재를 보지 않는다.
검증
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지우고 test:reference-feature를
package.json에서 뺀 복사본(sim-sample-docs.sh)에서 verify:documentation
PASS_SCOPED. 저장소에서도 PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
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
문제
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
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.
고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
verify:documentation, check:i18n, check:design-system을 돈다
(FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
(c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.
위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
documentation-readiness 14건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.
고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.
버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.
위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
"적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.
검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
문제: 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
문제
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
문제: withTransactionLock은 partition lock을 signal 없이 요청한다
(withPartitionLock("shared", operation, undefined, run)). put·remove의
request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면
시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만
걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은
partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면,
삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기).
05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다.
고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고,
withPartitionLock은 kernel createAbortableOperation으로 caller signal과
mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller
abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의
acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를
지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다).
lock 전 abort는 journal begin 전이라 보상할 것이 없다.
버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이
남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다.
위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다.
다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고
호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort
경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb
번들 37,521 → 37,555 / 38,500 gzip B.
검증:
- RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에
끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지
않아 10초 timeout.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건
통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source
PASS, verify:documentation 통과.
- browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진
27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러
5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02
문제
자기 해제 service-worker.js는 REMOVE_REGISTRATION release만 낸다
(build-frontend.ts). 다음 단계 release에는 워커 파일이 없어 update
검사가 404로 실패한다. PURGE_OWNED_RESOURCES는 부팅한 페이지만 다시
unregister하고, null은 아무것도 하지 않는다. 1단계 기간에 오지 않은
사용자에게 부팅을 막는 워커나 옛 워커가 남는다(리뷰 1103 실험 L3).
운영 문서는 세 단계 순서만 적고 각 단계 유지 기간이 없다.
고른 방법
- 0929/06-06의 최소 방향 중 문서 한 줄을 고른다. SW runbook 8절과
release-cache-rollback.md 4단계에 "1단계를 최대 미방문 기간 이상 유지,
그 뒤 남은 사용자가 보이면 1단계를 다시 배포"를 적는다.
- 버린 대안: 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을
맞추기. 빌드·hosting 검사·e2e를 함께 바꿔야 해서 이월 항목의 작은
수정 범위를 넘는다.
위험·한계
- 동작은 그대로다. 유지 기간을 지키는지는 운영자 몫이다.
검증
- 문서와 코드(build-frontend.ts, service-worker-page-controller.ts
PURGE_OWNED_RESOURCES 분기, service-worker-removal.ts)를 대조했다.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-06
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.
고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.
위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.
검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
문제
캐시를 지우는 곳은 activate 하나다(현재 + 마커가 가장 높은 직전 1개).
템플릿은 requestActivation()을 부르지 않으므로 활성화는 그 scope의
탭이 모두 닫혀야 일어난다. 그 사이 release마다 새 후보가 waiting
워커를 밀어내지만 밀려난 캐시는 남는다(리뷰 실험 L2: A 활성 + 탭
유지에서 B, C를 받으면 소유 캐시 3개, 활성화 뒤 2개). 운영 문서는
"현재 + 직전 1개"만 말해 waiting 기간의 캐시 수가 보이지 않는다.
고른 방법
- 리뷰 5.1 판단대로 (a) 문서만 고친다. SW runbook 8절에 쌓이는 규칙,
예, 크기 상한, 쿼터에 닿았을 때의 결과, 줄이는 방법
(requestActivation 화면)과 install이 지우지 않는 이유를 적는다.
release-cache-rollback.md SW 1단계에 한 문장과 링크를 둔다.
- 버린 대안: (b) install 성공 뒤 "무마커 + 이번 후보 아님 + 활성 캐시
아님"을 지우기. install하는 워커는 활성 캐시 이름을 모르고, 마커
쓰기에 실패한 활성 캐시는 후보와 구별되지 않는다. (c) 이번 후보를 뺀
무마커 캐시를 모두 지우기. 그 활성 캐시를 지워 직전 캐시 보존 성질을
깬다.
위험·한계
- 쌓이는 동작 자체는 그대로다. 사전 캐시가 1 MiB를 넘고 release가 잦아
지면 (b)를 다시 본다(리뷰 재검토 조건).
- 브라우저 종료로 활성화되는지는 확인하지 않았다.
검증
- 문서와 코드(service-worker-lifecycle.ts onActivate,
service-worker-static-assets.ts QUOTA_EXCEEDED, service-worker.ts
assetSetBytes)를 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-04
문제
SW runbook(browser-file-storage-recovery.md 8절)은
"verify:hosting-headers는 파일이 있는지만 보고 이 헤더는 보지 않는다"고
적는다. 지금은 워커를 싣는 빌드에서 serviceWorker surface가 필수이고
Cache-Control이 no-cache가 아니면 FAIL이다(cache-policy.json
serviceWorker, verify-hosting-headers.ts). release-cache-rollback.md는
맞게 적어 두 운영 문서가 반대로 말한다.
고른 방법
- 그 문장을 live 모드가 /service-worker.js의 no-cache를 확인한다로
고친다. fixture 모드가 UNVERIFIED라는 것과, 하위 경로 base는 probe가
아직 받지 않아 손으로 확인해야 한다는 것을 함께 적는다.
위험·한계
- 하위 경로 문장은 0929/13-06이 고쳐지면 지워야 한다.
검증
- 문서와 코드(cache-policy.json, verify-hosting-headers.ts,
hosting-probe.ts classifyLiveHostingBaseUrl)를 대조했다.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-01
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.
고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
결과는 surface hashedAsset.<ext>, header content-type이다.
verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
(c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
— 검출이 없다(리뷰 5.2).
위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.
검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
문제
2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에
나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED
재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두
브랜치를 합친 상태를 리뷰 기준으로 골랐다.
고른 방법
새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는
건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다.
- 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가
없어진 이쪽을 택했다.
- 6절: 거절 판정 위치는 backend-envelope.ts 표다.
- 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다.
위험·한계
- 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는
사용자가 정한다.
검증
- check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다.
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.
고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
조립된 contribution의 descriptor마다 operationId, featureId, method, path,
authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
(digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.
버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.
위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
필드를 갖지만 자체 계약이라 바꾸지 않았다.
검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.
BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
문제
08-08은 초기 JS 바이트를 줄이는 대신 초기 파일을 16개에서 25개(entry
포함 26개)로 늘렸고, "HTTP/1.1 호스팅이면 다시 본다"를 남겼다. vite
preview도 HTTP/1.1이다. 비용을 잰 적이 없어 위험이 열려 있었다.
고른 방법
- 지금 빌드와 묶은 빌드 두 가지를 쟀다. (가) 08-08이 나눈 초기 primitive
청크 4개(field·button·select·page-templates)를 하나로. (나) 묶을 수 있는
초기 청크 14개를 하나로(entry·preload-helper·boot, 부트 실패 화면 closure,
15-01 그룹은 뺐다). 같은 커밋을 임시 복사본에서 그룹 하나만 더해 빌드했다.
- 측정: vite preview(HTTP/1.1, gzip), Chromium CDP 네트워크 에뮬레이션
(DevTools Fast 3G·Fast 4G 값), 새 context·캐시 없음, 첫 화면 =
boot 셸이 사라지고 route h1이 들어온 시각. 세 빌드를 번갈아 7번씩, 중앙값.
HTTP/2(node:http2, 자체 서명 인증서, gzip)도 같은 방법으로 쟀다.
- 결과(Fast 3G / Fast 4G 중앙값)
- 지금 26개 202,782 B: 5,887 / 1,874 ms
- (가) 23개 201,818 B: 5,426 / 1,764 ms
- (나) 13개 198,673 B: 4,930 / 1,535 ms
- HTTP/2: 지금 4,793 / 1,444, (가) 4,769 / 1,440, (나) 4,708 / 1,422 ms
- 판단: 묶지 않는다. 측정값과 판단을 performance-evidence.md에 적고,
vite.config.ts의 "재검토" 주석이 그 절을 가리키게 한다.
- (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로
고를 방법이 없었다. boot 정적 closure는 design-system 배럴을 지나 갤러리
전용 primitive까지 잡는다. rolldown `$initial` 태그는 entry가 앱을 dynamic
import로 읽어서(09-03) 아무것도 잡지 않는다. boot.tsx를 entry로 더하면
manifest 분류가 lazy 화면까지 초기로 센다(28개, 216,820 B, 예산 초과).
- 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 맞춰야 하고, 낡아도
실패하는 검사가 없다. 08-08이 같은 이유로 manualChunks 이름 고정을 버렸다.
- 템플릿은 HTTP/2 이상 서빙을 전제로 본다. HTTP/1.1로만 서빙하는 제품은
(나) 같은 그룹을 넣고 셸을 바꿀 때마다 다시 잰다고 문서에 적었다.
버린 대안
- (나)를 고정 목록으로 넣기: HTTP/1.1에서 Fast 3G 0.96초 빠르지만 숨은
결합이다(위).
- (가)만 넣기: 0.46초. 같은 이유.
위험·한계
- HTTP/1.1로 서빙하는 다운스트림은 첫 화면이 Fast 3G에서 약 1초 늦다.
이 커밋은 그 비용을 없애지 않고 숫자와 전제를 적는다. 호스팅 HTTP 버전을
검사하는 게이트는 없다(FE-GATE-019 probe 밖).
- 측정은 이 머신의 loopback과 CDP 에뮬레이션이다. 연결 수립(TCP·TLS) 비용은
CDP 지연에 들어가지 않는다. loadavg는 HTTP/1.1 측정 6~20, HTTP/2 측정
3~6이라 두 표끼리는 비교하지 않는다. 각 표 안은 번갈아 재서 비교할 수 있다.
검증
- 빌드 바이트: classify-vite-bundle + gzipSync(check:bundle과 같은 계산).
지금 빌드는 기준 202,770 B(local-build)와 맞다.
- 측정 스크립트와 로그는 커밋하지 않았다(worktree의 .tmp/ra/, 일회성).
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED.
- npx eslint vite.config.ts, npx tsc --project tsconfig.node.json --noEmit 통과.
문제: 손상 때문에 끝나지 못한 LOGOUT·ACCOUNT_DELETION purge의 partition
삭제는 두 단계다. 디렉터리를 origin lease 안에서 지우고, 이어서 journal
row를 lease 밖에서 지운다. origin lease는 put의 BEGIN~FINISH만 막는다.
그래서 다른 탭에서 journal `begin`을 끝낸 put이 두 단계 사이에 BEGIN을
하면 새 디렉터리에 파일을 쓰고, 두 번째 단계가 그 put의 row를 지운다.
put은 다음 journal 단계에서 `CONFLICT`로 실패하지만 파일을 치울 주체가
없다.
- markFilesReady 전에 row가 지워지면: 보상이 manifest·staging을 지우고
chunk가 남는다.
- commitPut 전에 지워지면: 보상이 없어 manifest·FILES_READY staging
receipt·chunk가 남는다. staging receipt가 chunk를 GC·sweep에서 지키고
row가 없어 reconcile도 보지 않으므로 영원히 남는다. 다음 LOGOUT purge는
`chunkSweep: COMPLETED`를 보고하면서 이 bytes를 남긴다.
- commit 뒤 complete 전에 지워지면: put은 성공하지만 object는 없고
manifest·chunk가 남는다.
삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우(72edb55가 가정한
경우)는 수정 전에도 put이 `CONFLICT`로 실패하고 bytes가 남지 않았다.
고른 방법: partition 단위 Web Lock
(`<mutationLockName>:partition:<a>:<ns>:<p>`)을 둔다. 모든 put·delete는
`withTransactionLock` 안에서 journal `begin`부터 끝날 때까지 shared로
쥐고, partition 삭제는 디렉터리·journal 두 단계를 exclusive로 쥔 채 한다.
mutation은 삭제 전체보다 앞이거나 뒤에만 놓인다. 진행 중이던 put은 끝난
뒤 삭제가 지우고, 삭제가 lock을 요청한 뒤 온 put은 삭제 뒤에 돈다.
lock 순서는 partition lock → origin lease 하나뿐이라 교착이 없다
(per-transaction lock은 `ifAvailable`이라 기다리지 않는다). 기다리는
동안 purge `signal`을 abort하면 `ABORTED`를 반환한다.
버린 대안:
- commitPut `CONFLICT`면 보상: commitPut 전 경우만 고치고 chunk와
commit 뒤 경우가 남는다. 또 port가 "CONFLICT = 아무것도 commit 안 됨"을
약속하지 않아 동봉 구현에 기대는 숨은 결합이 생긴다.
- commit까지 origin lease 쥐기: lease는 worker 안에 있고 journal은 page
쪽이다. 두 번째 단계(row 삭제)가 lease를 쓰지 않아 commitPut 전 경우가
그대로다.
- row를 먼저 지우고 디렉터리를 나중에: 그 사이 begin한 put이 디렉터리
단계 전에 FINISH하면 파일 없는 COMMITTED row가 생긴다. 중간 실패 뒤
재호출로 이어서 끝나는 성질도 잃는다.
- 디렉터리 → row → 디렉터리: 같은 이유로 파일 없는 commit이 생긴다.
위험·한계:
- 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle
bound(05-07)까지 삭제를 붙잡는다. 수정 전에도 그 put은 origin lease를
쥐고 있어 디렉터리 단계가 같은 시간을 기다렸다.
- reconcile은 partition lock을 쥐지 않는다. reconcile은 파일을 새로 쓰지
않으므로(검증·정리·finalize만) 삭제와 겹쳐도 bytes를 남기지 않는다고
보았고, 이 경우는 테스트하지 않았다.
- put·delete마다 Web Lock 요청이 하나 늘어난다.
- offline-indexeddb 레시피 gzip 37,327 → 37,423 B(한도 38,500).
- 공개 타입·배럴 변경 없음.
검증:
- RED(수정 전, put 결과 단언을 넣기 전): 새 it.each 5건 중 3건 실패.
디렉터리를 put BEGIN 전에 지운 경우만 실패했다.
markFilesReady 앞: chunk 1개 남음. commitPut 앞: staging receipt·chunk·
manifest 남음. complete 앞: chunk·manifest 남음.
삭제 전체가 FINISH~commit 사이인 2건은 통과(put CONFLICT, bytes 0).
"put은 삭제 앞에 끝난다" 단언을 더한 뒤 수정 전 코드: 5건 모두 실패.
- GREEN: 5건 + abort 테스트 1건 통과. 같은 5건 10회 반복 10/10.
- `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts
tests/recipes` 136건 통과.
- tsc app·test·web-worker·recipes 통과. 바꾼 파일 eslint 통과.
`check-adapter-inventory` PASS, `check-optional-recipes`(source) PASS,
`verify-documentation-readiness` PASS_SCOPED.
- 미실행: `check:browser-file-storage-boundaries`·`check:architecture`
(pnpm 필요), Playwright OPFS spec(webServer가 pnpm).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
문제: `check:remediation-ledger`가 3건 실패한다.
TR-02: tests/unit/presigned-transfer.test.ts does not mention TR-02
TR-03: tests/unit/image-cdn-runtime.test.ts does not mention X-AUDIT-01 or X-AUDIT-02
TR-04: tests/unit/resumable-upload-runtime.test.ts does not mention TR-04
원인은 ID 표시가 지워진 것이 아니다. 2026-09-18 테스트 분할(`5cc41467`,
`ec7f20e2`)이 세 테스트를 표시째 다른 파일로 옮겼고, 원장과 dispositions
JSON은 옛 파일을 가리킨 채 남았다. 지금 위치:
TR-02 → tests/unit/presigned-transfer-delivery.test.ts:220
TR-03 이미지 probe → tests/unit/image-cdn-browser-probe.test.ts:579 (X-AUDIT-02)
TR-04 → tests/unit/resumable-upload-runtime-teardown.test.ts:80
분할 전 파일(`5cc41467^`)에 같은 주석과 테스트가 있었음을 확인했다.
고른 방법: 원장 행이 테스트가 실제로 있는 파일을 가리키게 한다.
`docs/operations/adapter-remediation-dispositions.json`의 evidence 3곳과
`docs/operations/adapter-remediation-ledger.md`의 같은 행 3개를 고치고,
머리말의 "옮긴 suite" 메모에 이번 분할을 더했다. 앞 절의 실행 명령은 그
실행이 쓴 파일 그대로 둔다(그 시점 기록).
버린 대안: 옛 파일에 TR-02·TR-04·X-AUDIT ID를 적기. 그 파일에는 해당
테스트가 없어서, 검사기가 막으려는 "관계없는 suite를 가리켜 증거처럼
보이기"를 그대로 만든다. 검사기와 markers 규칙은 바꾸지 않았다.
위험·한계: 테스트를 다시 쪼개거나 옮기면 같은 식으로 깨진다. 이 검사는
게이트 밖이라 그때도 아무도 모른다. `config/ci/ungated-scripts.json`의
이 검사 사유("Later fixes removed those markers … reports stale claims")는
이제 사실과 다르지만 이 커밋 범위 밖이라 고치지 않았다.
검증:
- RED(`ec7435c`): `node scripts/check-remediation-ledger.ts` 3건 실패, exit 1
- GREEN: "25 dispositions joined …; 0 open; evidence paths verified", exit 0
- 증거 suite 5개 77건 통과(`node scripts/run-vitest.ts run` 해당 파일)
- `verify-documentation-readiness.ts` PASS_SCOPED, `check-ci-contract.ts` PASS,
`check-adapter-inventory.ts` PASS, `tests/unit/ungated-scripts.test.ts` 10건 통과
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.
고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
"§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
.dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.
위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.
검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
.dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
문제: 레시피 번들 예산을 수정마다 100 B씩 올려 왔다. 한도가 늘 직전
측정값이라 예산 초과가 "왜 커졌나"를 묻는 신호가 되지 못했다. 이번 수정
묶음 뒤 offline-indexeddb(37,327 > 36,900)와 realtime(40,902 > 40,900)이
넘었고, file-transfer는 여유가 47 B였다. remediation ledger는 예전 값
56,100을 적지 않아 check:remediation-ledger가 실패하고 있었다.
방법: 리뷰 결정(README 14절 0929/05-04)대로, 측정값 + 3%를 100 B 단위로
올린 값으로 한 번 정한다. 그 뒤 3% 안의 증가는 예산을 고치지 않고, 넘는
증가는 커밋 본문에 이유를 쓰고 같은 규칙으로 다시 정한다.
- file-transfer 56,053 → 57,800, offline-indexeddb 37,327 → 38,500,
realtime 40,902 → 42,200, service-worker-pwa 9,716 → 10,100
- 규칙·이유·측정 표는 optional-adapter-recipes.md의 예산 절에 둔다.
JSON은 주석을 받지 않아서다.
- realtime 문서 두 곳은 숫자 대신 정본 위치를 가리킨다. VD-10은 결정
기록이라 그대로 둔다.
버린 대안: 수정마다 100 B 인상(지금 방식), 레시피 예산에서 kernel 제외
(kernel 증가를 놓친다).
위험: 3% 여유 안에서는 회귀가 조용히 쌓인다. 예산 값을 표와 JSON 두
곳에 적으므로, 다음 인상 때 표도 같이 고쳐야 한다(ledger는
check:remediation-ledger가 file-transfer 값을 대조한다).
검증: check:optional-recipes:source PASS(4 budgets), verify:documentation
PASS_SCOPED, check:remediation-ledger의 예산 실패 사라짐(TR-02~04 기존
3건은 그대로, 게이트 밖).
문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.
고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
`STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
- 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
(0929 05-03)와 같은 조건이다.
- 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
- 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
손상 행도 지워진다. scope binding 행은 남긴다.
- 보고: `partitionDeleted: true`, `corruptObjects`,
`moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.
위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
`corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
report에는 `corruptTransactions`(필수)와 `corruptObjects`·
`partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
`STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
`listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
`CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
177 files 2,523건 통과, `tests/contract` 41건 통과.
`tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
`check:architecture`(pnpm 필요), Playwright OPFS spec.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
문제
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
문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로
싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고,
헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는
보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만
넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조"
줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를
싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다.
고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미
했다.
- V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드
sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를
싣는다. observation의 correlationId와 같은 값이다.
- 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다.
- 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩.
버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는
metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가
이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다.
위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을
조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안
컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로
두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은
이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼).
검증:
- RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS
200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수
없습니다."는 보이지만 "Unable to find an element with the text: 지원
참조: 29d7f444-…"로 실패.
- GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id).
tests/features·unit·integration·component 242 files 2975 tests,
tests/contract·runtime-schema·architecture 13 files 109 tests 통과.
tsc app·test, eslint(바꾼 파일), verify-documentation-readiness,
check-adapter-inventory, check-registries 통과.
Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04
문제: 운영 문서(browser-file-storage-recovery.md 8절)는 "활성화는
페이지의 requestActivation()으로만 일어나므로 새 worker 활성화를
멈추려고 따로 할 일은 없다"고 적는다. 브라우저는 scope의 탭이 모두
닫히면 waiting 워커를 스스로 활성화한다. 운영자가 이 문장을 믿고
결함 있는 waiting 워커를 두면, 탭을 닫았다 연 사용자부터 그 워커를
쓰고 대응(REMOVE_REGISTRATION)이 늦어진다.
RED(문서-코드 대조): install은 skipWaiting()을 부르지 않는다
(service-worker-entry.ts). requestActivation()은 src에서 정의
(service-worker-page-controller.ts, contracts/service-worker.ts)만 있고
부르는 곳이 없다. 저장소 e2e 주석(service-worker-update.spec.ts)과
리뷰 실험 8(chromium·webkit)은 탭을 모두 닫으면 B가 활성화되고
reload만으로는 waiting에 남는 것을 보였다. 같은 저장소의
release-cache-rollback.md는 이미 "every tab of the scope closes or a
page calls requestActivation()"으로 맞게 적는다.
고른 방법: 문장을 두 활성화 경로(requestActivation 성공, scope의 탭이
모두 닫힘)와 reload만으로는 활성화되지 않는다는 점, 템플릿의 기본
경로, 결함 있는 waiting 워커에 대한 조치(다음 release로 교체 또는
REMOVE_REGISTRATION)로 고친다. 코드는 바꾸지 않는다.
버린 대안: 없음. 리뷰가 문서 정정 하나만 제시했다.
위험·한계: 이번에 브라우저 실험을 다시 하지 않았다. 근거는 표준 SW
수명주기, 저장소 e2e 주석, 리뷰 실험 8이다. firefox는 Playwright에서
페이지가 제어되지 않아 확인 범위 밖이다.
검증:
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- `grep -rln requestActivation src tests` -> src는 정의 2파일뿐.
Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-02, 7.2절
문제
docs/operations/performance-evidence.md는 다운스트림이 첫 기능 전에 예산을
정할 때 보는 유일한 자료다. 그런데 2026-09-25 측정을 그대로 적고 있다.
기준선 196,573 B(예산의 96%, 여유 약 8,200 B), "`index` 93.5 KB,
`preload-helper` 28.5 KB(zod 포함)", "dynamic import chunk는 lazy다".
verify:documentation은 수치를 보지 않아 통과한다.
문서와 코드 대조 (RED 대신)
- 298201f 빌드(build-frontend.ts, classifyViteJavascript + gzipSync 기본
수준, check:bundle과 같은 계산): 초기 JS 16개 파일 202,509 B
(VITE_BUILD_ID=local-build), 202,522 B(gitea-123456-1). 여유 약 2,280 B
- `index` 864 B, `preload-helper` 675 B. 문서의 청크 이름별 크기가 모두
틀렸다
- 분류기(scripts/lib/classify-vite-bundle.ts)는 entry가 직접 dynamic
import하는 boot·render-boot-failure도 초기로 센다. 문서 문장과 반대다
고른 방법
- 표를 현재 측정으로 바꾸고 측정 커밋(298201f)과 빌드 ID 조건을 적는다.
- 청크 이름 대신 출처별(react-dom·react-router·zod·@tanstack·react·
템플릿 src) 크기를 적는다. sourcemap 빌드에서 minify 바이트를 원래 모듈에
나눠 붙이고 묶음마다 gzip했다. rolldown이 공용 청크에 모듈 하나의 이름을
붙여서 청크 이름으로 판단하면 엉뚱한 곳을 줄이게 된다는 설명을 둔다.
- 15-01 뒤 기능 하나의 증가량(참조 모양 +650~750 B, 298201f 커밋 측정)과
그 상한 테스트를 적는다. 다운스트림이 "몇 개 더 들어가나"를 바로 본다.
- 분류 규칙 문장을 분류기와 맞춘다.
버린 대안
- check:bundle이 bundle.json에 출처별 합계를 남기게 자동화: 빌드마다
sourcemap 빌드가 한 번 더 필요하다. 리뷰도 "가능하면"으로 적었고, 문서
수치를 맞추는 이번 범위를 넘는다.
위험·한계
- 15-01 커밋 본문의 202,361 B와 이번 측정이 148 B 다르다. 같은 커밋의 빌드
차이(빌드 정보·ID)로 보이나 원인은 확인하지 않았다.
- 출처별 표는 sourcemap 빌드(VITE_BUILD_ID=gitea-123456-1)에서 쟀다.
sourceMappingURL 주석은 빼고 셌다.
- production 프로필 빌드와 pnpm 경로의 check:bundle(generate-supply-chain이
pnpm list를 부른다)은 돌리지 않았다.
검증
- verify-documentation-readiness: PASS_SCOPED
- 다른 문서에 옛 수치(196,573, 96%, 8,200) 없음(git grep)
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-02
문제
.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
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.
고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
needs after", 다르면 "evidence explains after=..., the change is
after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
registry-governance tamper 사례)에 after를 넣었다.
버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
하지 않았다.
위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
적어야 한다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
("rejects evidence written for another value", "requires the explained
value": expected [] to deeply equal [...]). X3 변이로 check-registries
"11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
after=\"/examples/reference-resources/items/:resourceId\", the change is
after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
"11 registries PASS". registry-compatibility·registry-governance·
release-artifacts·second-api-feature-registries 53/53 통과.
compatibility fixtures 11 PASS. verify-documentation-readiness
PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.
고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.
버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.
위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.
검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
as unfinished"가 `- "moreObjectsAvailable": true`
`+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
check-optional-recipes PASS.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
문제
package.json에 어디서도 부르지 않는 script 4개가 있다.
- scan:security:fixture: FE-GATE-013은 이것 대신 check:security:fixtures를
돈다. supply-chain.test.ts는 "게이트에 없어야 한다"고 단언하는데 script는
남아 있다. 게이트 밖 script 검사는 check|verify|test|drill|review만 봐서
scan:을 놓쳤다.
- build:profile: 이름과 달리 generate-runtime-config.ts만 돈다.
- generate:contract-set: 참조 0건.
- build:app-only: vite build와 매니페스트만 만든다. build-frontend.ts의
계약 세트·런타임 설정·Service Worker 단계가 빠진 dist가 나온다. 참조는
product-index-entrypoints 테스트의 진입점 목록 하나다.
참조 확인(새 기준 298201f, docs/reviews 제외): package.json 정의와 위 두
테스트 말고는 config/ci/gates.json, 생성 workflow, scripts, docs 어디에도
없다. 아래 세 script가 부르던 파일(generate-runtime-config.ts,
generate-contract-set.ts, generate-build-manifest.ts)은 build-frontend.ts가
그대로 부른다.
고른 방법
- 네 script를 지우고 진입점 목록에서 build:app-only를 뺀다.
- VERIFICATION_SCRIPT에 scan을 더한다. 게이트가 닿지 않는 scan:* script는
ungated-scripts.json 항목 없이는 check:ci에서 실패한다. 지금 남은
scan:security는 build:release-candidate를 거쳐 게이트가 닿는다.
- docs/operations/ci-quality-gates.md의 접두어 목록에 scan:*을 더한다.
버린 대안
- build:app-only를 build:vite-only로 이름만 바꾸기: 남길 사용처를 찾지
못했다.
- 접두어 대신 "게이트 밖 모든 script는 예외 목록에": dev·storybook·
update:*까지 목록에 올라가 목록이 커진다(리뷰 대안 비교와 같다).
- check:feature-index 정리(리뷰 개선 (4)): 지우기와 이유 문구 고치기 중
하나를 고르는 일이라 이번에 하지 않았다.
위험·한계
- 개인 습관으로 이 script를 쓰던 사람은 build-frontend.ts나 node
scripts/...를 직접 불러야 한다.
- 게이트 명령은 바뀌지 않아 CI 계약 기준선은 그대로다.
검증
- RED: 새 테스트 "rejects a scan script that no gate reaches"가 실패
(expected [ …(2) ] to deep equally contain '…: scan:orphan'). 정규식만
넓히면 저장소 검사 "reaches every verification script …"가
scan:security:fixture 한 건으로 실패.
- GREEN: ungated-scripts·product-index-entrypoints·supply-chain·
ci-workflow-generation 4파일 457/457 통과. check:ci의 세 단계를 pnpm
없이 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS(27 gates), generate-ci-workflow --check PASS.
tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-05
FE-GATE-021..025 rebuilt from source and drilled that build, so the drilled
bytes were not the promoted release. production_gate now downloads the
promoted-release artifact, extracts it against immutable_build's digest and
runs each drill with --release-root; the CI contract rejects a rebuild.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
check-ci-contract only caught test files outside the gates; check:* scripts
such as check:request-fanout and check:remediation-ledger ran nowhere. The
new check reads config/ci/ungated-scripts.json; three checks are now wired
into FE-GATE-010 and FE-GATE-012 and the rest carry a reason.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
One run decided the release gate, the interaction included Playwright round
trips, and a server already on 4173 was measured instead of the build. Runs
now repeat with every sample kept, time the interaction in the page, use
--strictPort and check the served build, and stop the whole preview group.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
The template's default screens use 96% of the initial JS budget, and nothing
said so, nor that CSS is excluded, which gzip level applies, or that the lab
interaction is one run including the Playwright round trip.
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>
The runbook still listed the auth fail-close, total deadline and bounded
decoder as not implemented and said an unauthenticated request could be
sent. Section 1 is now a status table with code locations, 5.1 and 6.0
describe V3, and 6.3 points at the same-key resend and its limits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The runbook named failure codes the adapter stopped using and promised a
resume and a quarantine reconcile never does. It now states the put's own
code with RECONCILE, the skipped and failed row counts, and what reconcile
really does per phase. The worker never sent EFFECT_UNKNOWN and the client
refused it, so the cleanup effect type and its two adapter branches go.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>