Commit Graph
100 Commits
Author SHA1 Message Date
DongHyeonka 46dfe23f69 fix(bundle): 예산을 넘으면 넘은 한도와 초과량을 출력하고 초기 파일 수를 막는다
문제: 초기 JS가 예산을 넘으면 check:bundle은
"Bundle budget or manifest integrity failed: " 한 줄만 쓰고 콜론 뒤가
비어 있었다. 측정값과 한도는 artifacts/performance/bundle.json에만 있어
예산 실패인지 manifest 무결성 실패인지, 몇 바이트 넘었는지 알 수 없었다.
또 초기 JS 파일 수에는 상한이 없어 08-08처럼 파일을 16개에서 25개로
늘리는 변경도 모든 게이트를 통과했다. 템플릿은 HTTP/2를 전제로 초기
청크를 나눠 두었는데, 파일 수를 늘리는 결정이 어디에도 드러나지 않았다.

고른 방법: 예산 실패와 무결성 실패를 다른 문장으로 쓴다. 예산 실패는
넘은 한도마다 측정값·한도·초과량을 한 줄로 쓴다
(describeBundleBudgetFailures). config/performance/budgets.json에
initialJsFiles(지금 25)를 두고 check:bundle이 entry를 포함한 초기 파일
수를 센다. bundle.json 스키마는 측정값·한도·결과와 자가 검사 fixture를
하나씩 더 가진다. 두 변경은 같은 함수와 스키마를 고치므로 한 커밋에
넣었다.
버린 대안: 파일 수를 문서에만 적기. 08-08이 그 상태에서 파일을 늘렸다.

위험·한계: 초기 파일을 하나라도 늘리는 변경은 이제 budgets.json을 같이
고쳐야 통과한다. 그것이 목적이다. HTTP/2 확인 자체는 이 커밋에 없다
(13-02에서 probe에 넣는다).

검증: tests/unit/check-bundle-output.test.ts가 손으로 만든 빌드 출력에
check-bundle.ts를 돌려 통과·초기 바이트 초과·lazy 초과·파일 수 초과·
무결성 실패의 출력을 본다(고치기 전 4건 실패). bundle-artifact-contract,
performance-budgets 통과. 실제 빌드에서 check:bundle PASS(25 / 25 files).

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-03, 15-05
2026-11-04 20:22:27 +09:00
DongHyeonka e40684b4e1 chore(review): 리뷰 기준으로 두 작업 브랜치를 합친다
문제
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절)에 적는다.
2026-11-03 22:49:20 +09:00
DongHyeonka 12f3bb7862 refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제
기능 하나가 같은 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에
넘긴다.
2026-11-03 21:37:48 +09:00
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
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으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka 3f9c087798 docs(performance): 초기 청크 수의 HTTP/1.1 비용을 재고 묶지 않는 근거를 적는다 (1101/14.4)
문제
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 통과.
2026-11-03 20:47:52 +09:00
DongHyeonka e5b7b3e857 fix(storage): partition 삭제가 다른 탭의 진행 중인 put을 기다린다 (0929/05-01)
문제: 손상 때문에 끝나지 못한 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
2026-11-03 20:22:49 +09:00
DongHyeonka 13350875c6 fix(docs): 정비 원장 TR-02~04 증거를 테스트가 옮겨 간 파일로 바꾼다 (1101/14.3)
문제: `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건 통과
2026-11-03 20:09:49 +09:00
DongHyeonka b26517e6f2 fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 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 필요).
2026-11-03 07:17:49 +09:00
DongHyeonka 313f9bac3e chore(recipes): 레시피 예산을 측정값 + 3%로 정하고 규칙을 적는다 (0929/05-04)
문제: 레시피 번들 예산을 수정마다 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건은 그대로, 게이트 밖).
2026-11-03 07:00:41 +09:00
DongHyeonka 72edb55475 fix(storage): 손상 행을 건너뛰고 끝나지 못한 삭제는 partition을 지운다 (0929/05-01)
문제: 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
2026-11-03 01:23:05 +09:00
DongHyeonka 16202fd48d fix(docs): 현재 계약 문서의 경로·명령·게이트 ID를 검사한다 (14-05)
문제: 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에서 금지).
2026-11-03 01:13:16 +09:00
DongHyeonka de379ea78d ci(release): FE-GATE-019가 승격 후보를 배포된 release와 대조한다 (1101/13-01)
문제
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
2026-11-03 00:56:00 +09:00
DongHyeonka 4ada84e1ec fix(registry): 맞는 변경이 없는 breaking 증거 행을 실패로 막는다 (0929/07-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
2026-11-03 00:55:33 +09:00
DongHyeonka 849d000342 fix(http): 결과 불명 쓰기에 보낸 요청 id를 지원 참조로 싣는다 (0929/03-04)
문제: 바인딩은 서버가 돌려준 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
2026-11-03 00:53:16 +09:00
DongHyeonka b28e290965 docs(operations): SW 활성화 조건에 탭을 모두 닫는 경로를 적는다 (06-02)
문제: 운영 문서(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절
2026-11-01 22:49:38 +09:00
DongHyeonka 8c7bcdaba5 docs(performance): 번들 기준선과 분류 규칙을 15-01 뒤 빌드에 맞춘다 (1101/15-02)
문제
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
2026-11-01 22:49:13 +09:00
DongHyeonka b3af26fc0e fix(release): 배포된 config.json 사본을 바꾸기 전에 검사한다 (1101/13-05)
문제
.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
2026-11-01 22:49:13 +09:00
DongHyeonka 629c8f045e fix(hosting): 호스팅 검사가 SPA fallback과 SW 스크립트 헤더를 본다 (1101/13-04)
문제
라우터는 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
2026-11-01 22:49:13 +09:00
DongHyeonka 5e6be9a92f fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
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
2026-11-01 22:35:54 +09:00
DongHyeonka 68e88b081d fix(opfs): 객체를 못 지운 purge가 완료와 chunk sweep을 보고하지 않는다 (0929/05-02)
문제: 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
2026-11-01 22:25:41 +09:00
DongHyeonka 98b9682241 chore(scripts): 쓰지 않는 npm script 4개를 지우고 scan:도 게이트 검사한다 (12-05)
문제
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
2026-11-01 22:16:26 +09:00
donghyeon-kaandClaude Opus 5.5 fa3de53106 ci(release): drill the downloaded promoted archive in the production stage (13-03)
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>
2026-09-27 14:25:53 +09:00
donghyeon-kaandClaude Opus 5.5 15a946fc46 ci(gates): require every verification package script to run in a gate or name why not (12-04)
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>
2026-09-27 14:14:42 +09:00
donghyeon-kaandClaude Opus 5.5 81d2b84c7b docs: correct drifted counts and state what verify:documentation checks (14-07)
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>
2026-09-27 13:34:53 +09:00
donghyeon-kaandClaude Opus 5.5 4805e56ab1 Merge lane/J: test system (10-02, 10-04~10-07, 11-04~11-08, F-2, F-4, F-12, 00-03)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:28:55 +09:00
donghyeon-kaandClaude Opus 5.5 8e5c51e813 perf(lab): repeat lab runs, judge the median and pin the measured server (11-07)
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>
2026-09-27 13:14:03 +09:00
DongHyeonkaandClaude Opus 5.5 9f2305a562 fix(service-worker): ship a self-unregistering worker for REMOVE_REGISTRATION (06-03)
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>
2026-09-26 00:21:02 +09:00
DongHyeonkaandClaude Opus 5.5 ed112e56ab Merge lane K: CI, guardrails and release fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:42:40 +09:00
DongHyeonkaandClaude Opus 5.5 a55a15861e docs(performance): record the bundle budget baseline, headroom and conditions (13-14)
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>
2026-09-25 23:21:36 +09:00
DongHyeonkaandClaude Opus 5.5 1b0f1b3c22 Merge lane E: browser storage and adapter kernel fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:05:41 +09:00
DongHyeonkaandClaude Opus 5.5 a263d8cc4a fix(release): run the hosting header gate on the deployed release, fixture is UNVERIFIED (13-05)
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>
2026-09-25 23:03:23 +09:00
DongHyeonkaandClaude Opus 5.5 839205c134 feat(release): re-verify a promoted release in archived mode (13-04)
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>
2026-09-25 22:58:37 +09:00
DongHyeonkaandClaude Opus 5.5 0e54e838c6 docs(runbook): bring the HTTP recovery runbook to the V3 code (03-08)
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>
2026-09-25 22:54:36 +09:00
DongHyeonkaandClaude Opus 5.5 4d8ceade21 fix(storage): match the OPFS runbook to the adapter and drop the dead EFFECT_UNKNOWN branch (05-09)
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>
2026-09-25 22:44:51 +09:00
DongHyeonkaandClaude Opus 5.5 2b24f6d8f0 fix(storage): fail a put whose source stalls so the OPFS origin lock is freed (05-07)
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>
2026-09-25 22:41:31 +09:00
DongHyeonkaandClaude Opus 5.5 7f45afac7d fix(storage): report a future IndexedDB schema as INCOMPATIBLE and online-only (05-06)
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>
2026-09-25 22:37:40 +09:00
DongHyeonkaandClaude Opus 5.5 39b9fbffb7 fix(architecture): stop running dependency-cruiser, which checked zero modules (12-05)
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>
2026-09-25 22:37:21 +09:00
DongHyeonkaandClaude Opus 5.5 b87ab5ee8e fix(storage): let retention sweep and receipt prune step over a corrupt row (05-05)
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>
2026-09-25 22:33:44 +09:00
DongHyeonkaandClaude Opus 5.5 7f2a1607f3 refactor(architecture): move regex import rules into the import graph (12-10, 12-08)
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>
2026-09-25 22:33:14 +09:00
DongHyeonkaandClaude Opus 5.5 6ab564f376 fix(storage): sweep a purged OPFS partition's chunks without the GC grace (05-04)
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>
2026-09-25 22:29:07 +09:00
DongHyeonkaandClaude Opus 5.5 c5da3cf001 fix(http): send a request id and carry the server correlation id to failures (03-03)
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>
2026-09-25 22:27:42 +09:00
DongHyeonkaandClaude Opus 5.5 3e37fbf0ed fix(storage): delete a partition's IndexedDB dataset when an authorized purge cannot open it (05-03)
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>
2026-09-25 22:24:55 +09:00
DongHyeonkaandClaude Opus 5.5 45ee231bb0 ci: run the CPU-independent scale PR tier in FE-GATE-005 (11-03)
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>
2026-09-25 22:23:01 +09:00
DongHyeonkaandClaude Opus 5.5 7f889a6d83 fix(release): record unobserved runbook drill verdicts as UNVERIFIED (11-01, 13-03)
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>
2026-09-25 22:15:59 +09:00
DongHyeonkaandClaude Opus 5.5 7298275271 ci: move the signed manual a11y review to release gate FE-GATE-028 (08-06)
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>
2026-09-25 22:07:53 +09:00
DongHyeonkaandClaude Opus 5.5 840de45ee7 ci: run every test file in a gate or name why not (12-04, 09-11)
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>
2026-09-25 21:47:10 +09:00
DongHyeonkaandClaude Opus 5.5 239b22ae1a fix(ci): run every gate a non-matrix job owns and refuse profile/target mismatch (12-02, 13-01)
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>
2026-09-25 21:36:27 +09:00
DongHyeonkaandClaude Opus 5.5 0114b1e58b fix(ci): move CI contract counts and gate hash to an owned baseline file (14-02)
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>
2026-09-25 21:34:12 +09:00
DongHyeonkaandClaude Opus 5.5 d1a57ae949 fix(build): let the hosting gate accept the selected ACTIVE worker (R3-6)
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>
2026-09-24 15:42:09 +09:00
DongHyeonkaandClaude Opus 5.5 63ce5f6486 fix(cross-context): report an inactive host and hash the release epoch (Q-6.2-9)
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>
2026-09-24 13:39:59 +09:00