0a00a5d092487fdd03ab421d4daac15abccbe762
789
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
0a00a5d092 |
chore(review): 1103 realtime·SW 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 04-01 04-02 04-04 04-06 06-01~06-04 |
||
|
|
4f19cd9e8b |
test(service-worker): 살아남던 워커 보호 장치 변이 4건을 테스트로 잡는다
문제
워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번
리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect:
"error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의
CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8).
고른 방법
- service-worker-runtime.test.ts에 테스트 3건을 더한다.
- install이 자산마다 cache no-store, credentials omit, redirect error로
요청한다(M1).
- 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은
client의 drain 응답은 세지 않는다(M3, M9).
- active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8).
- 동작은 바꾸지 않는다.
위험·한계
- N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를
흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다.
검증
- service-worker-runtime 64건 통과.
- 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고
되돌렸다.
- 바꾼 파일 eslint, check:types:test 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04
|
||
|
|
c3aa5eba35 |
docs(recipes): Service Worker 레시피가 오프라인 셸을 약속하지 않게 한다
문제 catalog의 service-worker-pwa trigger는 "a measured offline-shell requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이 있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는 navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며, 설계는 cached index.html fallback을 금지한다(closed deep design 18.8). catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게 알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례). 고른 방법 - 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인 셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품 capability"를 적는다. failureKinds의 offline-fallback을 offline-navigation-network-error로 바꾼다. - 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시 증명할 e2e 단언과 성질, 동기화 충돌)를 적는다. - 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가 금지한 동작이고 재검토 조건(제품 요구)이 아직 없다. 위험·한계 - catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다. 검증 - json-schema 테스트 6건 통과, check:remediation-ledger· check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03 |
||
|
|
3bc690d3fb |
test(realtime): WebSocket 구독별 초당 event 상한을 테스트로 고정한다
문제 WebSocket 연결은 구독마다 1초 창에 maxEventsPerSecond(256, server가 알린 값과 작은 쪽)를 넘는 event가 오면 EVENT_RATE_EXCEEDED recovery를 요청하고 QUEUE_OVERFLOW로 닫는다. 이를 확인하는 테스트가 없어 검사를 꺼도 모든 테스트가 통과한다(리뷰 변이 R7, 두 라운드째). 설계 11절 상한표에도 행이 없다. 고른 방법 - 상한을 2로 낮춘 연결에서 2개 → 1초 뒤 2개(열림 유지) → 1개 더(닫힘, EVENT_RATE_EXCEEDED)를 보내는 테스트 1건을 더한다. 창 초기화와 상한 값 출처까지 한 테스트가 본다. - 설계 11절 상한표에 행 하나를 더한다. 위험·한계 - 동작은 바꾸지 않았다. 실제 서버 부하로는 확인하지 않았다. 검증 - 새 테스트 통과(websocket-connection 24건). - 변이 3건 모두 검출: 상한 검사 끄기(R7), 1초 창 초기화 삭제, 협상된 상한 대신 256 고정. - 바꾼 파일 eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 1101/04-03 |
||
|
|
0cc2553381 |
docs(operations): 워커 제거 1단계를 최대 미방문 기간 이상 유지하라고 적는다
문제 자기 해제 service-worker.js는 REMOVE_REGISTRATION release만 낸다 (build-frontend.ts). 다음 단계 release에는 워커 파일이 없어 update 검사가 404로 실패한다. PURGE_OWNED_RESOURCES는 부팅한 페이지만 다시 unregister하고, null은 아무것도 하지 않는다. 1단계 기간에 오지 않은 사용자에게 부팅을 막는 워커나 옛 워커가 남는다(리뷰 1103 실험 L3). 운영 문서는 세 단계 순서만 적고 각 단계 유지 기간이 없다. 고른 방법 - 0929/06-06의 최소 방향 중 문서 한 줄을 고른다. SW runbook 8절과 release-cache-rollback.md 4단계에 "1단계를 최대 미방문 기간 이상 유지, 그 뒤 남은 사용자가 보이면 1단계를 다시 배포"를 적는다. - 버린 대안: 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을 맞추기. 빌드·hosting 검사·e2e를 함께 바꿔야 해서 이월 항목의 작은 수정 범위를 넘는다. 위험·한계 - 동작은 그대로다. 유지 기간을 지키는지는 운영자 몫이다. 검증 - 문서와 코드(build-frontend.ts, service-worker-page-controller.ts PURGE_OWNED_RESOURCES 분기, service-worker-removal.ts)를 대조했다. - verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-06 |
||
|
|
5d0f5ad7f8 |
docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다
문제 heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지 않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은 유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7). 훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신, isReconnectAttemptResetEligible)을 같이 읽어야 안다. 고른 방법 - 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에 같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을 만들라고 적는다. 동작은 바꾸지 않는다. 위험·한계 - 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다. 검증 - 바꾼 파일 eslint 통과. 주석만 바꿨다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04 |
||
|
|
5b2106df25 |
docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(
|
||
|
|
615da352b9 |
docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다
문제 짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API, NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는 text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는 subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금 되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다. 고른 방법 - 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을 두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세 길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한 줄로 링크한다. - 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를 금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3). StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는 없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로 적었다. - 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지 않았다. 제품 결정이다. - 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라 함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다. 위험·한계 - 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가 바뀌면 표가 낡는다. 재검토 조건에 적었다. - 실제 연결은 실행하지 않았다(리뷰와 같음). 검증 - verify:documentation PASS_SCOPED. documentation-readiness· changelog-review-ids 테스트 15건 통과. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02 |
||
|
|
b4ae4c1ed3 |
docs(operations): waiting 기간에 소유 캐시가 쌓이는 것과 정리 시점을 적는다
문제 캐시를 지우는 곳은 activate 하나다(현재 + 마커가 가장 높은 직전 1개). 템플릿은 requestActivation()을 부르지 않으므로 활성화는 그 scope의 탭이 모두 닫혀야 일어난다. 그 사이 release마다 새 후보가 waiting 워커를 밀어내지만 밀려난 캐시는 남는다(리뷰 실험 L2: A 활성 + 탭 유지에서 B, C를 받으면 소유 캐시 3개, 활성화 뒤 2개). 운영 문서는 "현재 + 직전 1개"만 말해 waiting 기간의 캐시 수가 보이지 않는다. 고른 방법 - 리뷰 5.1 판단대로 (a) 문서만 고친다. SW runbook 8절에 쌓이는 규칙, 예, 크기 상한, 쿼터에 닿았을 때의 결과, 줄이는 방법 (requestActivation 화면)과 install이 지우지 않는 이유를 적는다. release-cache-rollback.md SW 1단계에 한 문장과 링크를 둔다. - 버린 대안: (b) install 성공 뒤 "무마커 + 이번 후보 아님 + 활성 캐시 아님"을 지우기. install하는 워커는 활성 캐시 이름을 모르고, 마커 쓰기에 실패한 활성 캐시는 후보와 구별되지 않는다. (c) 이번 후보를 뺀 무마커 캐시를 모두 지우기. 그 활성 캐시를 지워 직전 캐시 보존 성질을 깬다. 위험·한계 - 쌓이는 동작 자체는 그대로다. 사전 캐시가 1 MiB를 넘고 release가 잦아 지면 (b)를 다시 본다(리뷰 재검토 조건). - 브라우저 종료로 활성화되는지는 확인하지 않았다. 검증 - 문서와 코드(service-worker-lifecycle.ts onActivate, service-worker-static-assets.ts QUOTA_EXCEEDED, service-worker.ts assetSetBytes)를 대조했다. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-04 |
||
|
|
7144653109 |
docs(operations): 워커 스크립트 헤더 검사 범위를 지금 코드에 맞춘다
문제 SW runbook(browser-file-storage-recovery.md 8절)은 "verify:hosting-headers는 파일이 있는지만 보고 이 헤더는 보지 않는다"고 적는다. 지금은 워커를 싣는 빌드에서 serviceWorker surface가 필수이고 Cache-Control이 no-cache가 아니면 FAIL이다(cache-policy.json serviceWorker, verify-hosting-headers.ts). release-cache-rollback.md는 맞게 적어 두 운영 문서가 반대로 말한다. 고른 방법 - 그 문장을 live 모드가 /service-worker.js의 no-cache를 확인한다로 고친다. fixture 모드가 UNVERIFIED라는 것과, 하위 경로 base는 probe가 아직 받지 않아 손으로 확인해야 한다는 것을 함께 적는다. 위험·한계 - 하위 경로 문장은 0929/13-06이 고쳐지면 지워야 한다. 검증 - 문서와 코드(cache-policy.json, verify-hosting-headers.ts, hosting-probe.ts classifyLiveHostingBaseUrl)를 대조했다. Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-01 |
||
|
|
0f58abbd32 |
fix(hosting): live probe가 사전 캐시 확장자마다 Content-Type을 확인한다
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.
고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
결과는 surface hashedAsset.<ext>, header content-type이다.
verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
(c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
— 검출이 없다(리뷰 5.2).
위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.
검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
|
||
|
|
a145f30b48 |
fix(web-push): dot segment가 든 registry path를 생성 때 거절한다
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.
고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).
위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
둬야 한다(리뷰 재검토 조건).
검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
6파일 76건 통과.
- 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
|
||
|
|
af000673ef |
fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다
문제 브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이 transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은 execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로 낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고 예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE 행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로 화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인", WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를 기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양). 고른 방법 - 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader 거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로 바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다. - poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는 execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다. executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다. - 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다. - 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만 조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이 없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3). 위험·한계 - 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo 안 소비자는 테스트뿐이다. - 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시 불린다. 상한은 maxAttempts·maxElapsed 그대로다. - 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로 보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다 (before/after 테스트 그대로 통과). 검증 - 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime 단위 241건 통과. - check:types 통과, 바꾼 파일 eslint 통과. BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute 거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은 던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던 조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04 |
||
|
|
a65df74046 |
fix(realtime)!: bounded poll을 V3 descriptor에 묶어 실행기 재시도를 막는다
문제 BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2, protocol, semantics, replayPolicy, retry, transportMaxAttempts, authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다. assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와 대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다. poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P). 고른 방법 - coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다. 실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다 (http-execution-v3.ts retryCeiling). 그래서 생성 때 retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청 한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다. - 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT, retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는 maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다. - V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립 (composeContractContributions)이 GET·HEAD에서 이미 거절한다. - 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는 retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은 객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기 옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가 재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이 없다. 위험·한계 - 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다. - 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에 넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고 적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다. - 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용 operation을 따로 등록해야 한다. 검증 - 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과. - 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError, retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서 poll 3회 = 요청 3회. - 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사 삭제) 모두 검출. - check:types 통과, 바꾼 파일 eslint 통과. BREAKING CHANGE: BoundedPollOperationContract를 지운다. createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의 둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다. 조립된 행(composeContractContributions(...).httpByOperationId.get(id))을 넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다. execute 안에서는 같은 descriptor를 실행기에 넘긴다. Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01 |
||
|
|
004a205748 |
docs(review): 리뷰가 놓친 merge 게이트 결함 2건을 더한다
문제
리뷰 README 10.1절의 게이트 목록은 merge stage 전체가 아니었다.
coverage 증거 검사, storybook, a11y, browser-capabilities, CI env 값의
e2e가 빠졌다. 리뷰를 맡긴 세션이 병합의 한쪽 부모 8c39e77에서
`ci:gate FE-GATE-NNN` 14개를 돌려, 실제 러너에서 항상 실패하는 merge
게이트 두 개를 찾았다.
고른 방법
- 11-06: tests/e2e/compact-smoke.spec.ts:18이 build id를 "local-build"로
고정하고, workflow는 VITE_BUILD_ID를 gitea-<run>-<attempt>로 준다.
FE-GATE-008이 CI에서 항상 실패한다.
- 12-09: scripts/lib/ci-artifact-validator.ts:79-91의 .strict() schema가
istanbul-lib-coverage 3.2.2 summary의 branchesTrue를 거절한다.
FE-GATE-005가 테스트가 모두 통과해도 실패한다.
- 두 결함의 코드를 e40684b에서 다시 읽고, README 13절에 36.3 양식으로
적었다. 사용 결정, P1 표, 개선 순서 2, 관점 21, 색인(90건), 미검증,
오케스트레이터 실수(10.5)에 반영했다. 등급은 02-06과 같은 기준으로
Medium·P1이다.
- 셋째 결함(FE-GATE-020)은 02-06과 같아 따로 세지 않았다.
worktree 안 checkout·inotify 부족은 환경 조건이라 결함으로 세지
않았다.
위험·한계
- e40684b에서 ci:gate를 실행하지 않았다. 재현은
|
||
|
|
9c521ecd75 |
docs(review): 2026-11-03 프론트 전체 성숙도 리뷰를 기록한다
문제 V2 HTTP 경로를 지운 뒤( |
||
|
|
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절)에 적는다. |
||
|
|
93c81dfc6f |
docs: 사라진 V2 동작 셋의 판정과 되살린 것을 기록한다
문제 14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가 사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성 검사도 같이 사라졌다. 고른 방법 14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep design) 8절이다. - 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은 문장은 리뷰 대상으로 남긴다. - KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만 되살렸다( |
||
|
|
c05f41a63e |
fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다
문제 V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로 끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본 (2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는 network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과 어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝 백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2). 고른 방법 - backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE. - Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면 AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget· MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을 다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고 키를 지킨다. 버린 대안 - V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이 응답 없는 실패 뒤 재시도를 금지한다. - 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자 재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시 보내지 않았다. 위험·한계 - retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다. - Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다. 검증 - RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고 PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과. - GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다. - check:types, lint, check:architecture, test:unit 2,568, test:integration 117, test:component 245, tests/features 99 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
365d8c3c02 |
fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제 브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기 요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을 가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD 밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤 V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키 전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을 POST에 붙여도 조립이 통과한다. 고른 방법 assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아, 쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에 x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아 거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와 같다). 버린 대안 - 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필 (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다. - 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자 요청 시점까지 미룬다. 위험·한계 - 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한 실패다(CHANGELOG [보안]). - 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시 실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회). 검증 - RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie profile requires no CSRF header" 실패(조립이 통과). - GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는 조립된다. - check:types, lint, check:architecture, check:registries, test:unit 2,568, test:integration 117, test:component 245 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
dcadc0be92 |
docs: V2 HTTP 경로 삭제를 CHANGELOG와 리뷰 기록에 적는다
문제 048f490(V2 클라이언트 삭제)과 12f3bb7(V2 API 행 삭제)은 공개 이름을 깨는 변경인데 CHANGELOG 미출시 절에 행이 없고, "먼저 할 일" 절의 기능 모양 옮기기 순서가 아직 apiContract(V2 API 필드 네 개)를 만들라고 적는다. 리뷰 README 14.6의 "V2와 남은 차이"도 V2가 있는 것으로 적는다. 고른 방법 - CHANGELOG: [계약] BREAKING 행 둘(지운 이름, 옮기는 법, memento-web 영향)을 더하고, "먼저 할 일" 1·3번을 schemas 하나로 고쳤다. - 리뷰 README 14.7: 사용자 지시, 지우기 전·후 도식, 두 커밋이 지운 것과 바꾼 것, 레지스트리 재승인 digest, 초기 JS 변화, 사라진 V2 전용 동작, 남긴 BoundedPollOperationContract, 다운스트림 영향. 14.6의 차이 절에 지금은 없다고 적었다. 위험·한계 - 다운스트림 동기화 방법은 CHANGELOG의 문장뿐이다. memento-web을 직접 옮겨 보지는 않았다. 검증 - verify:documentation PASS_SCOPED. - tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
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에 넘긴다. |
||
|
|
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으로 실행한다.
|
||
|
|
bf86fe5cd0 |
docs(contract): 4.2절의 400·422 행을 짝 백엔드 거절 표에 맞춘다
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다.
|
||
|
|
8c39e77376 |
docs(delivery): 정적 배포 문서에 HTTP/2 서빙 전제를 적는다 (1101/14.4)
문제: 3f9c087은 초기 청크를 묶지 않는 근거로 "템플릿은 HTTP/2 이상으로 서빙한다"를 정했다. 그런데 이 전제는 작업 기록인 performance-evidence.md 에만 있다. 호스팅을 정하는 사람이 읽는 현재 계약 문서(static-delivery.md) 에는 서빙 프로토콜 이야기가 없다. 고른 방법: static-delivery.md 끝에 한 단락을 더한다. HTTP/2 이상으로 서빙한다는 것, HTTP/1.1에서 늦어지는 정도(Fast 3G 약 1초), HTTP/2에서의 차이(100 ms 미만), HTTP/1.1만 되는 제품이 할 일을 적고 측정 기록으로 링크한다. 버린 대안: README의 배포 절에 적기. README는 배포 변수와 명령을 다루고, 호스트 동작은 static-delivery.md가 다룬다. 위험·한계: 수치는 2026-11-03 한 번의 측정이다. 셸이 바뀌면 달라진다. 검증: node scripts/verify-documentation-readiness.ts PASS_SCOPED |
||
|
|
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 통과.
|
||
|
|
267c72459e |
test(e2e): 빠진 페이지와 같이 preload한 청크의 WebKit 경고를 허용한다 (1101/14.3)
문제 webkit에서 old-tab-chunk-recovery.spec.ts가 가끔 실패한다. WebKit은 문서의 load 이벤트 3초 뒤에 한 번, 아직 쓰지 않은 link preload마다 경고를 남기고 strict console 검사가 그 경고를 실패로 본다. - A 탭에서 B를 배포하고 플랫폼 화면을 누르면, Vite preload helper가 페이지 청크와 그 청크가 import하는 badge·card·schema-registry·server-state를 같이 preload한다. 페이지 청크가 404라 import가 실패하고, 같이 받은 청크는 끝까지 쓰이지 않는다. 복구가 release manifest를 읽는 동안 A 문서가 load+3초를 넘기면 경고 4줄이 나온다. B 탭의 UI 화면에서도 같은 일이 생긴다 (text-field). - 그 청크들은 플랫폼 화면이 실제로 import한다(.vite/manifest.json). 앱이 쓰지 않는 청크를 preload하는 것이 아니다. 경고는 테스트가 일부러 지운 청크의 결과다. - 08-08과의 관계: 원인이 아니다. 08-08 전( |
||
|
|
fbd93ac9a8 |
docs: 거절 적용 여부를 백엔드 기준 표로 바꾼 것을 매뉴얼과 기록에 적는다
문제 3261208이 V2·V3의 거절 판정을 계약 문서 6.1절 표로 바꿨다. 매뉴얼 02 4절은 아직 "422 전부와 필드 목록 400은 적용 안 됨, 그 밖은 classifyProblem"으로 적고, 리뷰 README 14.6 판정 표, 14.4의 검증 거절 줄, CHANGELOG의 |
||
|
|
846955498d |
fix(apps): 두 기능 라우트가 같은 경로를 쓰면 조립 때 막는다 (1101/14.4)
문제: 7d85589는 플랫폼 라우트가 가리는 기능 라우트를 막지만, 기능 라우트 둘이 같은 경로를 쓰는 경우는 막지 않는다. 라우터는 순위가 같은 경로를 선언 순서로 고르므로 뒤의 라우트는 그려지지 않는다. 메뉴와 레지스트리에는 그 라우트가 나온다. 파라미터 이름(`:orderId`와 `:itemId`)은 순위를 바꾸지 않으므로 이름만 다른 경로도 같은 경로다. R-B가 남긴 것으로 보고했다. 고른 방법: 같은 함수(assertFeatureRoutesReachOwningContext)에서 플랫폼 검사를 통과한 라우트마다 파라미터 이름을 지운 경로 모양을 기록하고, 이미 있으면 두 라우트와 기능 이름을 담아 throw한다. 앱 모듈을 평가할 때 실패하므로 09-06·09-03 검사와 같이 fail-closed다. APP_HOME 대체는 이 함수의 앞쪽 continue로 빠지고, 두 기능이 같은 플랫폼 라우트를 가져가는 경우는 기존 검사(withoutTakenOverPlatformRoutes)가 막는다. 버린 대안: 레지스트리 검사(check:routes)에서 경로 중복 보기. 그 검사는 route ID 중복만 보고, 라우터가 실제로 어떤 순위로 고르는지는 모른다. 위험·한계: 일부만 겹치는 경로(`/a/new`와 `/a/:id`)는 라우터가 정적 경로를 먼저 고르므로 막지 않는다. 그 경우는 accepts 테스트로 고정했다. splat(`*`) 기능 라우트끼리의 겹침은 모양 비교로만 본다. 검증: - RED: 새 테스트 2건 중 "같은 경로 거절"이 실패(22/23 통과) - GREEN: tests/architecture와 라우트 component 테스트 75건 통과 - tests/unit·component·integration·features 253파일 3,153건 통과 - tsc app·test, eslint 통과 |
||
|
|
7c8cb19e94 |
fix(routes): 등록 라우트 없는 URL의 적재 실패를 UNREGISTERED_ROUTE로 적는다 (1101/14.3)
문제: context gateway가 라우트 적재 실패를 `ui.render.failed`로 남길 때
`route_id`를 URL에서 고른다. 고르는 곳이 세 군데이고 결과가 서로 다르다.
- 청크 누락이 아닌 실패: `registeredRouteIdAt(...) ?? routeModule.id`.
레지스트리의 NOT_FOUND splat이 모든 URL에 맞아서 등록 라우트가 없는 URL은
`NOT_FOUND`가 되고 대체값은 한 번도 쓰이지 않는다. 운영에서는 not-found
화면이 깨진 것처럼 읽혀 플랫폼 담당에게 간다. 실제로 실패한 것은 context의
라우트 모듈이다.
- 복구하지 못한 청크 실패: 늘 `routeModule.id`(context id). telemetry는
`route_id`를 `^[A-Z][A-Z0-9_]{0,63}$`로만 받는다. 그래서 이 이벤트는
`invalid-attribute-value`로 버려진다(`projectTelemetryEvent`로 확인).
- 레이아웃 청크 실패: `?? "NOT_FOUND"`. 레이아웃 아래 context는 등록 경로에만
붙어서 지금은 닿지 않는 값이다.
이 진단이 구분해야 하는 것은 둘이다. 어느 화면(그래서 어느 기능)이 실패했나,
그리고 not-found 화면 자체가 실패했나. 그 값은 telemetry까지 가야 한다.
고른 방법: 세 곳이 `failedRouteIdAt(pathname)` 하나를 쓴다. URL의 등록
라우트 id를 쓰고, 등록 라우트가 없으면(NOT_FOUND만 맞으면) 명시값
`UNREGISTERED_ROUTE`(`UNREGISTERED_ROUTE_ID`, src/contracts/routes.ts)를
쓴다. 등록 URL의 청크 실패는 context id 대신 그 라우트 id가 된다. 라우트
id로 소유 기능과 context를 찾을 수 있다. 청크 복구의 chunkId 선택은 바꾸지
않았다.
버린 대안:
- context id(`routeModule.id`, 원래 의도한 대체값): 실패한 모듈을 정확히
가리키지만 telemetry가 버린다. 받게 하려면 `route_id` 문법을 소문자
kebab까지 넓혀야 한다. 그러면 `api.request.failed` 등 모든 이벤트의
`route_id` 검사가 약해진다.
- context id를 대문자 snake로 바꿔 쓰기: 숨은 이름 규칙이 생기고 실제 라우트
id와 섞인다.
- `context_id` 속성 추가: 진단·telemetry 허용 목록과 레지스트리 기준선을
바꿔야 한다. 기준선 재승인은 이 작업 범위가 아니다.
위험·한계:
- 등록 라우트가 없는 URL의 실패는 어느 context인지 진단에 남지 않는다. 같은
결함은 그 context의 등록 URL에서도 나므로 그 보고로 찾는다.
- [계약] `ui.render.failed`의 `route_id`에 `UNREGISTERED_ROUTE` 값이 생긴다.
복구하지 못한 context 라우트 청크 실패는 context id 대신 라우트 id를 적는다.
`route_id` 이름과 허용 문법은 그대로다.
- 기능이 `UNREGISTERED_ROUTE`라는 route id를 선언하면 구분되지 않는다. 막지
않았다.
검증:
- RED: context-boundary-diagnostics "unregistered handle" 1건이
`"route_id": "NOT_FOUND"`로 실패. context-route-gateway 새 2건이
`"route_id": "context-offline"`로 실패(8건 중 3 실패).
- GREEN: 두 파일과 context-layouts 14건 통과. 각 보고는 telemetry 투영
(`projectTelemetryEvent`)도 통과한다.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
runtime-schema,integration,scripts,scale}(pnpm을 띄우는 3개 제외) 306
files, 3,572건 통과.
- tsc app·test 통과. 바꾼 파일 eslint 통과. check-registries,
check-diagnostics 통과. verify-documentation-readiness PASS_SCOPED.
|
||
|
|
7d85589ec1 |
fix(apps): 플랫폼 라우트가 가리는 기능 라우트를 조립 때 막는다 (1101/14.4)
문제: 라우터는 `AppShell` 아래 플랫폼 라우트를 모든 context보다 먼저 붙인다.
그래서 기능 라우트를 플랫폼 라우트도 받으면 오류 없이 플랫폼 화면이 나온다.
React Router `matchRoutes`로 라우터와 같은 구조를 만들어 확인했다.
- 같은 경로: context `examples/*`의 `/examples/ui`는 `EXAMPLES_UI`가 받는다.
레이아웃 아래에서도 순위가 같으면 앞에 있는 `AppShell`이 이긴다.
- `APP_HOME`이 아닌 id로 선언한 `/`는 플랫폼 홈이 받는다(
|
||
|
|
27f45233f9 |
test(layouts): 모든 레이아웃의 skip link와 main 하나를 실행으로 검사한다 (1101/14.4)
문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).
고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
`loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
`loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.
버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.
위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
`AppShell`만 돈다.
검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
("expected to have a length of 1 but got +0"). AppShell skip link href를
`#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
PASS_SCOPED.
|
||
|
|
326120867c |
fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제 계약 문서 6.1절( |
||
|
|
d0414c85f9 |
fix(contracts): 런타임 설정 키마다 FE-REG-ENV 행을 요구한다 (1101/09-02)
문제: config.json V2 스키마의 키 중 RELEASE_ID와 BUILD_ID에는 FE-REG-ENV(ENV_REGISTRY) 행이 없다. 이를 잡는 검사도 없다. 그래서 제품이 PRODUCT_RUNTIME_CONFIG_FIELDS에만 키를 더하고 PRODUCT_ENV_REGISTRY 행을 빠뜨려도 check:registries가 그 키를 보지 못한다. ece944d를 검토하다 찾았다. 고른 방법: - tests/unit/env-registry-coverage.test.ts를 더한다. runtimeConfigV2 ArtifactSchema의 모든 최상위 키에 phase "runtime" 행이 있어야 한다. 제품 필드는 withProductFields로 같은 shape에 들어가므로 같이 검사된다. - RELEASE_ID, BUILD_ID 행을 public-metadata, 선택, 기본값 null로 더한다. 빌드가 config.json에 쓰는 릴리스 신원이고, VITE_BUILD_ID와 같은 분류다. 버린 대안: check-registries.ts에서 검사하기. 그 검사기는 registry-governance.json에 적힌 레지스트리 export를 같은 규칙으로 읽는 일반 검사기다. 스키마와 레지스트리를 맞대는 규칙을 넣으면 FE-REG-ENV 하나만을 위한 분기가 생긴다. 테스트 하나로 같은 실패를 낸다. 위험·한계: V1 전용 키(API_CONTRACT_VERSION)는 검사하지 않는다. 그 행은 FE-REG-ENV 변경 증거로 지워졌고, V1 reader는 지울 예정이다. 행을 더한 것은 additive라 기준선을 고치지 않는다. 검증: - RED: 새 테스트가 ["RELEASE_ID", "BUILD_ID"]를 보고하며 실패 - GREEN: 통과. env 관련 unit 4파일 43건 통과 - node scripts/check-registries.ts: 11 registries PASS, additive - tsc app·test, eslint 통과 |
||
|
|
ece944d08b |
feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)
문제
09-02(
|
||
|
|
17fa8d1f65 |
fix(realtime): live-poll handoff 마감 실패를 13.1의 kind로 보고한다 (04-02)
문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다. live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로 보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가 조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다. - switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER - activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER - checkpoint 마감: IDLE_TIMEOUT/RECOVER - close drain 마감: IDLE_TIMEOUT/CLOSE 고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고 operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다. - quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의 apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다. APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은 분기를 `quiescenceFailure` 하나로 합쳤다. - checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가 throw할 때와 같은 kind다. - close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두 분기를 하나로 합쳤다. - 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지 않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과 retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의 RECEIVE·SUBSCRIBE(전송 idle)뿐이다. 버린 대안: - retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는 어휘다. 재시도 판단 변경은 따로 정한다. - close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가 settle하지 않았는데 "닫힘"으로 읽힌다. 위험·한계: - 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을 보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 소비자는 없다(AVAILABLE_NOT_COMPOSED). - handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다. - 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는 true다. 13.1 표에 둘 다 적었다. - realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200). 검증: - RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로 넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9 passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll quiescence, activateProbe quiescence, checkpoint). - GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files, 231 passed. - tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과, `check-optional-recipes`(source) PASS, `verify-documentation-readiness` PASS_SCOPED, `check-adapter-inventory` PASS. - 미실행: `check:architecture`(pnpm 필요). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4 |
||
|
|
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 |
||
|
|
8a09c90379 |
fix(forms): 짝 백엔드 필드 검증 code마다 문구를 보인다 (1101/14.4)
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.
고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.
버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
(check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
목록은 테스트에 SHA와 함께 적었다.
위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
청크에 있다.
검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
"Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
|
||
|
|
ed0e4b1923 |
docs(contract): 거절 code별 적용 여부를 백엔드 코드로 정한다 (1101/14.4)
문제
"검증 거절은 적용 안 됨" 판정(
|
||
|
|
f3b87b3f02 |
docs: 생성한 기능이 짝 백엔드 Envelope를 읽는다는 결정과 결과를 적는다
문제 매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진 제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1" operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503 흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다. 고른 방법 - 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드 problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정 표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의 처리 칸은 14.6을 가리킨다. - 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고, Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다. - 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름. - CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언, V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다. - 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는 범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다. - 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을 backend-envelope.ts로 고쳤다. 버린 대안 - 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다. 위험·한계 - 문서의 게이트 결과는 이 커밋 직전 트리( |
||
|
|
bd83b496cc |
fix(http): V3 Envelope 진단이 V2와 같은 멱등성 거절 reason을 싣는다
문제 V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400 IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로 남긴다( |
||
|
|
7db32e1343 |
fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.
고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
프레임을 확인한다. outputValidator는 data(키가 없으면 null),
problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
<base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
답한다.
버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.
위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
check:registries, check:diagnostics, check:i18n, check:ci 통과.
test:unit 2,604, test:component 244, test:integration 200 통과.
tests/features·tests/contract 124건 통과.
test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
Envelope로 답하는 목록 화면 테스트 3건 포함).
test:sample-removal 23개 검사 통과.
check:bundle 통과(203,321 / 204,800 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
|
||
|
|
2eb010ae88 |
chore(ci): 정비 원장 검사를 게이트 밖에 두는 이유를 지금 사실로 고친다 (1101/14.3)
문제: config/ci/ungated-scripts.json은 check:remediation-ledger를 게이트
밖에 두는 이유로 "표시가 지워져 지금 커밋에서 낡은 주장을 보고한다"를
적는다.
|
||
|
|
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건 통과
|
||
|
|
7ee1df56f1 |
test(component): UI 갤러리 화면의 검증·상태 전환을 component 테스트로 막는다 (1101/14.4)
문제: `src/presentation/examples/ui-gallery-page.tsx`는 component 커버리지가 0%였다. e2e(`tests/e2e/ui-gallery.spec.ts`, 폼 검증과 모달 포커스 2건)와 시각 회귀만 이 화면을 봤다. 화면이 primitive에 연결한 규칙(공백 이름 거절, 알림 줄 문구, 알림 숨김·다시 표시, 모달 확인만 알림 줄을 바꿈, 메뉴의 toast)은 게이트 안 단위 실행에서 아무도 확인하지 않았다. 고른 방법: `tests/component/starter-ui-gallery-page.test.tsx` 9건. 화면을 LocaleProvider만으로 그리고 사용자 동작(user-event)으로 확인한다. 섹션 5개와 토큰 7개 렌더, 버튼 3개의 알림 문구, 빈 이름·공백 이름 거절과 trim한 이름 수락, controlled 입력 6종, 알림 숨김·복원, 모달의 취소·닫기·확인, 메뉴 두 항목, 수동 탭 활성화, tooltip 설명. 파일 이름은 starter 화면 테스트 규칙 (`docs/architecture/starter-experience.md`, `starter-*.test.tsx`)을 따라 화면을 지울 때 같이 지운다. 버린 대안: 스냅샷 테스트. 문구가 바뀔 때마다 깨지고 동작은 확인하지 않는다. 앱 라우터(`/examples/ui`)로 띄우기. 라우팅은 router 테스트가 보고, 이 화면은 provider가 locale 하나만 필요하다. 화면 코드는 고치지 않았다. 위험·한계: primitive 자체 동작(포커스 트랩, Esc, 화살표 이동)은 각 primitive 테스트와 e2e가 보고 여기서는 다시 세지 않는다. jsdom이라 실제 레이아웃과 `showModal()`의 top layer는 확인하지 않는다(e2e 몫). 검증: - 커버리지(`node scripts/run-vitest.ts run tests/component --coverage --coverage.include=src/presentation/examples/ui-gallery-page.tsx`): 전 lines 0/38, functions 0/19, branches 0/8 후 lines 38/38, functions 19/19, branches 8/8 (100%) - 일부러 화면을 깨 봄(되돌림): fieldError의 trim 제거, 알림 onDismiss 무효화, 메뉴 "상태 확인" onSelect 무효화 → 9건 중 3건 실패 - tests/component 전체 38파일 253건 통과 - `npx eslint` 새 파일, `npx tsc --project tsconfig.test.json --noEmit` 통과 |
||
|
|
ec7435c3f7 |
docs(review): 최종 게이트와 매뉴얼 재실험에서 찾은 것을 적는다
문제: 결정 반영 묶음을 다 합친 뒤의 게이트 결과, 매뉴얼만으로 기능을
추가한 재실험 결과, 그 과정에서 찾은 결함이 리뷰 README와 CHANGELOG에
없었다.
방법:
- 리뷰 README 14.3에 세 가지를 더했다.
- create:feature와 참조 기능(V3 실행기)이 짝 백엔드 Envelope 응답을
읽지 못한다(High, P1, 결정 필요라 남김).
- 매뉴얼 재실험 결과: 막힘 5건, 예고된 실패 1건. 막힘은 매뉴얼에 메웠다.
- webkit old-tab-chunk-recovery 간헐 실패.
- 14.5에
|
||
|
|
5c2f8b875c |
docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(
|
||
|
|
7c7ef32bb7 |
docs(changelog): 결정 반영 묶음의 계약 변경과 결과를 적는다
문제: 2026-11-03 결정(리뷰 README 14절)에 따라 만든 커밋 40여 개가 CHANGELOG 미출시 절과 리뷰 README에 없었다. 다운스트림은 CHANGELOG의 [계약]·BREAKING 행으로 가져갈 수정을 고른다. CHANGELOG 11행은 0.2.0 해시가 main에서 다를 수 있다고 적었지만 52개 모두 main에서 닿는다. 방법: - CHANGELOG 보안·계약 표에 BREAKING 2건(1101/08-03, 0929/05-03)과 [계약] 28건을 더했다. file-transfer 예산 행은 새 예산 규칙 행으로 바꿨다. - 백엔드 리뷰에서 온 ID는 "백엔드 리뷰 1101/02-01"로 적어 이 repo의 같은 번호와 섞이지 않게 했다. - 알려진 제한에서 풀린 것(registry-baseline source, OPFS 여러 페이지 purge)을 지우고 남은 위험을 더했다. - 11행 해시 문장을 사실대로 고치고, docs/reviews/를 지운 복사본은 원본 repo에서 ID를 찾는다고 적었다. - 리뷰 README에 14.2 결과, 14.3 새로 찾은 것, 14.4 남은 문제를 더했다. 위험: 행 수가 많아 다운스트림이 놓칠 수 있다. BREAKING은 표시 열 맨 앞에 둔다. 검증: tests/unit/changelog-review-ids.test.ts 통과(라운드 없는 ID 0). 표의 각 행 열 수를 확인했다(기존 이스케이프 행 1개 제외). |
||
|
|
e121a1a0e7 |
docs: 입구 문서가 새 기능 추가 매뉴얼을 가리킨다 (1101/16-01)
문제: docs/manual/을 더했지만 입구 문서(README.md, docs/README.md)가 링크하지 않아 찾을 수 없고, verify:documentation도 매뉴얼을 검사하지 않았다. 방법: docs/README.md 1절의 세부 규칙 목록에 manual/과 manual/reference/를 링크한다. 1절에서 링크한 문서는 verify:documentation(FE-GATE-017)이 경로· script·게이트 ID 실재를 검사한다. 루트 README의 Documentation 절에는 create:feature에서 시작하는 안내 한 줄을 둔다. 버린 대안: 입구 문서 표에 매뉴얼을 더하기 — 표는 계약을 정하는 문서 목록이고 매뉴얼은 그 계약을 쓰는 절차라 세부 목록에 둔다. 검증: verify-documentation-readiness PASS_SCOPED. documentReferences에 매뉴얼 8개 파일이 모두 들어가고 빠진 경로·script·게이트 ID 0. 문서 관련 단위 테스트 3파일 17건 통과. |
||
|
|
8b2048763b |
docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제 - 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와 폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패 메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다. 리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다. - create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일 (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다. 고른 방법 - docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과 안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일, reference/ 4개(create-feature, global-ids, patterns, errors). - 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다 정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을 적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트 밖 라우트는 이제 앱 모듈이 적재 때 거부한다). - 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로 바꿨다. - 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY, 게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿 docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은 design-docs의 conventions/feature-design-principles.md를 번호로만 가리킨다. - 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지 않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는 것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만 더한다. - 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조 페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다. - 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고 지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기 (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기 (메시지로 문서를 검색할 수 없다). 위험·한계 - docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는 verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래 .md만 검사하므로 reference/도 따로 링크해야 한다. - 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절 번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다. - 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만 둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능 테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다. - "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시 돌리지 않았다. 검증 - docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고 node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서 모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다. - 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두 말하며 FAIL_UNVERIFIED. - 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고, 42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩 코드에서 확인했다. - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과. |