문제: `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>
A put holds the origin-wide mutation lock from BEGIN to FINISH, and the page
waited on its source with no bound, so one stalled source blocked every
tab's writes until their lock wait failed. Each wait for source bytes is now
bounded by putIdleTimeoutMs; the put fails NOT_READABLE (retryable) and its
compensation releases the lock. The port now says writes are one at a time.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An older tab that met a schema a newer release had upgraded got
MIGRATION_FAILED / READ_ONLY, but could not even read, and operators were sent
to the migration runbook. The VersionError on open now yields UNSUPPORTED /
ONLINE_ONLY with status INCOMPATIBLE, reads and writes give the same answer,
and the OPFS journal answers the same way.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dependency-cruiser 18 cannot parse TypeScript 7, so it cruised no module, passed,
and its report and the docs claimed it checked the layers. The import graph is
the only checker; .dependency-cruiser.json stays as its rule file (D-11).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One corrupt sidecar or receipt stopped every later sweep or prune, so
expired rows stayed on the device and receipts grew until all writes failed
LIMIT_EXCEEDED. Both now leave the corrupt row, count it and report it as one
CORRUPT_DATA observation, and keep a budget they cannot account for as it is.
A malformed budget row in prune now fails as CORRUPT_DATA, not MIGRATION_FAILED.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Icon vendor, design-system deep import and realtime composition were regular
expressions beside graph rules, and the regex missed relative deep imports
inside presentation. They are graph rules with fixtures now, with the
components/ui facades and page-templates named. package-script-graph.ts stays;
the reason is recorded.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A LOGOUT or ACCOUNT_DELETION purge removed object directories only; chunk
bytes stayed until a GC 24 h later that might never run for that user.
Once every object is gone the purge now sweeps the partition's unreferenced
chunks at once and reports how the sweep ended. Chunks the journal or a
staged put still references are kept.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
V3 read the response x-correlation-id and dropped it, and untraced requests
sent no id, so a support reference could not be matched to a server log.
Each logical execution now sends one x-correlation-id; failures carry the
echoed value as requestId and diagnostics record it as correlation_id.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LOGOUT and ACCOUNT_DELETION purged row by row and so needed an open that a
corrupt budget or binding row always rejected, leaving personal rows on the
device. After authority approval, a purge that finds the dataset rejected by
admission now deletes that partition's own database and reports it; healthy
datasets and other partitions are untouched.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No CI job ran any scale tier, and every tier past pr compares timings only on
the baseline CPU. The pr tier checks counts, bounds and growth shape; it now
includes S2 composition, since S0/S1 stay under the noise floor and let a
quadratic accumulation through. The ungated-test check reads tier paths.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drills held constant true verdicts and read public/ placeholders, so they
passed with no build or with JS assets deleted. They now check the local dist,
mark boot, live traffic and provider steps UNVERIFIED (exit 3), and FE-GATE-016
is retired because it repeated FE-GATE-025's FE-RB-005 drill.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The signed review is per release candidate, so the merge gate could never pass.
FE-GATE-009 now checks only the record format; the checked-in records are
source-controlled evidence, not command output.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tests/architecture, tests/release, tests/scripts, the top-level
tests/features files and the browser-soak contract now run in
test:coverage (FE-GATE-005); check:adapter-inventory joins FE-GATE-010
and the image resolve-signal type fixture joins FE-GATE-003 (baseline
updated). check:ci fails on a test file no gate command reaches unless
config/ci/ungated-tests.json gives a reason; only the tests/scale suite
is listed, pending 11-03. defineFeatureModule's id mismatch is tested.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The generator rendered only gateIds[0] for non-matrix jobs, so
immutable_build never ran FE-GATE-027 and the snapshot test pinned that.
Each owned gate now gets its own run step, check:ci rejects a workflow in
which any contract gate has no run step, and release admission refuses
APP_PROFILE != RELEASE_TARGET. Both variables are documented.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gate/command/artifact counts and the gate-shape SHA-256 were code
constants, so any real removal or addition failed check:ci and removal
fixtures passed only in a relaxed mode. They now live in
config/ci/contract-baseline.json (owner, reason) with
update:ci-contract-baseline; update:registry-baseline wraps the existing
registry script. Removal fixtures re-baseline and run canonical check:ci
and check:registries; CI_CONTRACT_MODE, --reduced-removal-fixture and
check:registries:structure are gone. ci-quality-gates.md lists the
baselines a new project resets.
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>
createBrowserCrossContextInvalidationFromHost returned undefined without any
diagnostic when the cache epoch was invalid or secure random was missing, and
bootstrap built the epoch as `release.${releaseId}`, so any release ID with
`+`, `/`, `@` or over the length limit silently turned cross-tab
invalidation off.
- The host factory now reports OPEN/FAILED/NONE with the new reasons
INVALID_CACHE_EPOCH or SECURE_RANDOM_UNAVAILABLE before returning
undefined (the zero-topic build still probes nothing and reports nothing).
- New crossContextCacheEpochForRelease() derives `release.<fnv1a-64 hex>`
from the release ID; bootstrap uses it (one call-site change in
src/bootstrap/runtime-adapters.ts).
- The observation reason union gains two members (additive); the ops runbook
lists them.
Verified: two new unit tests failed before (no observation; missing epoch
helper) and pass now. Lane gates, reference-feature and V3 integration tests,
and check:diagnostics pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The default policy has allowedVaryHeaderNames: [], so any Vary header was
POLICY_REJECTED. nginx `gzip_vary` and most CDNs send
`Vary: Accept-Encoding` on JS and CSS, so the default policy could not
stage real assets. Accept-Encoding is a forbidden request header, so a
policy could not allowlist it as a request header either.
validateVary now skips `accept-encoding`. No script-built Request carries
that header, so the stored and lookup requests both lack it and Cache.match
still matches exactly. Every other Vary name keeps the existing checks.
A policy whose allowedResponseHeaderNames lacked `content-type` passed
assertPublicCachePolicy, but activation re-validates the stored
Content-Type, so every activation failed as INTEGRITY_FAILED. The policy
check now rejects it. The ops runbook lists both rules.
Verified: "stages, activates and looks up a Vary: Accept-Encoding response
with the default policy" (stage returned ok:false) and "rejects a policy
that strips Content-Type from stored responses" (no throw) failed before
the fix and pass now. check:architecture, check:types:app,
check:types:test, lint, test:component, verify:documentation pass.
test:unit passes except removal-fixture, which needs generated
artifacts/release files that a fresh worktree lacks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A tab whose BroadcastChannel postMessage failed once called
closeBroadcast(), which also removed its receive listener. Publishers
that broadcast successfully never write a storage pulse, so from then on
the tab missed every other tab's event while reporting
ACTIVE_STORAGE_FALLBACK. A tab whose BroadcastChannel failed to open had
the same blind spot and the same healthy-looking status.
Per D-4 there is no dual broadcast+storage publishing. Instead:
- A publish failure only sets broadcastPublishFailed. Later publishes go
to storage, and the channel stays open for receiving.
- BROADCAST_OPEN_FAILED now yields the additive status
DEGRADED_STORAGE_FALLBACK (the union lives in the adapter and is only
passed through by bootstrap). A browser without BroadcastChannel at all
keeps ACTIVE_STORAGE_FALLBACK, because every tab there uses storage.
- A successful storage publish recomputes the status instead of forcing
ACTIVE_STORAGE_FALLBACK, so it cannot hide the degraded state.
Existing tests fixed: "falls back when BroadcastChannel open or publish
fails" and "enters explicit local-only degradation when every transport
fails" expected ACTIVE_STORAGE_FALLBACK for a tab whose channel failed to
open. The ops runbook lists the new status.
Verified: "keeps receiving broadcasts after its own broadcast publish
fails" (received [] instead of [BROADCAST]) and the open-failure status
assertion (ACTIVE_STORAGE_FALLBACK) failed before the fix and pass now.
check:architecture, check:types:app, check:types:test, lint,
test:component, verify:documentation pass. test:unit passes except
removal-fixture, which needs generated artifacts/release files that a
fresh worktree lacks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cgroup test read the live process tree with one `ps` per pid and asserted
while the provider was running. That was a race it used to win only because the
sandbox was slow; now a whole run finishes in a few hundred milliseconds and
`systemctl show` alone costs longer than the thing it describes. It records the
tree from `/proc` every 5ms and asserts on the recording once the run is over,
because the assertions were always about what the run contained.
That restructuring immediately paid for itself: the supervisor had been failing
to launch the sandbox at all, and the test was dying on the observation before
it ever checked the exit code.
It could not say why, because the supervisor consumed the child's output solely
to enforce a byte cap and then discarded it — `exit=1` and nothing else. It now
keeps the lines the sandbox tooling itself emits (`bwrap:`, `prlimit:`,
`systemd-run:`, `systemctl:`), which cannot carry provider credentials because
the provider command and its secrets travel in the args file. The failure now
reads:
sandboxed external provider failed: exit=1; sandbox reported:
bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted
which is a host restriction — `kernel.apparmor_restrict_unprivileged_userns=1`
— reproducible in two lines of shell containing none of this repository's code,
and recorded in the ledger as such rather than carried as a product defect.
Suites that spawn processes, build archives and sign evidence were given a 30s
budget. The 10s default is sized for pure-JS unit tests; raising it globally
would hide a genuinely hung test.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nineteen findings across release admission, the provider sandbox, removability,
browser and visual evidence, architecture boundaries and documentation, each
named by defect rather than symptom, with the four removal fixtures' before and
after counts.
Three tests stay red and are recorded as such rather than claimed: the live
process-tree observation of a running sandbox, which now loses a race it used to
win only because the sandbox was slow, and two that time out at their 10s budget
under parallel load while passing in isolation. Lab performance produces
evidence for the first time and that evidence misses its budget; no budget was
moved to hide it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
FE-GATE-020 proves a capability can be removed by rebuilding the whole project
without it. The fixture it built could not get that far, and the failures all
came from the fixture rather than from anything about removability.
It was not a repository. The supply-chain inventory is defined as the tracked
file set, so it asks `git ls-files` what the project contains; with no
repository to ask, generation failed and took every provider suite down with
it. It is now initialised on preparation and committed after the removal — not
before, or the index would still list the files the removal deleted.
It had no `.gitignore`, so once it did have a repository, every generated
artifact and every linked module landed in the index and the inventory refused
the fixture for tracked and generated paths colliding. It carries the ignore
rules now, and therefore records the same tracked set as the repository it was
copied from.
Each removal script kept its own copy-target list and they had drifted: the
reference-feature fixture omitted `playwright.capabilities.config.ts`, which the
inventory requires. There is one list now. It also gained the install and
workspace identity — `.npmrc`, the lockfile, the workspace file — without which
the fixture is a different project, and the release evidence a candidate is
assembled from, without which no candidate can be built at all.
A tracked root the removal deletes is no longer required of the result: the
optional-recipe fixture deletes `recipes/`, and the inventory policy demanded
it back. Roots that are gone are pruned from the fixture's policy.
Two smaller causes. A platform integration file asserted the reference feature's
own route ids, so removing the feature left it importing a deleted module —
typecheck, the test run, coverage and the residue scan all failed on that one
misplaced assertion, which now lives in the feature's test tree. And the
canonical exact-count authority was re-imposed on a contract the fixture
deliberately reduces, failing the fixture for the reduction it exists to prove;
`CI_CONTRACT_MODE` already marked those runs and is now honoured by default.
The reference-feature fixture goes from failing before its first assertion to
1,612 passing with one failure, and that one is the live process-tree
observation test already red on the main tree.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>