docs(review): record the calls deferred during the maturity review round
FOLLOW-UP.md lists, with priority and code locations, what this round left as it is although practice would not: raised bundle budgets and the near-full initial JS budget, the ungated remediation ledger check, the readSubject breaking change, load-flaky tests, gaps outside the completion criteria, and test-side workarounds. README section 11 links it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
f753669333
commit
af3d8e6ffe
@@ -0,0 +1,93 @@
|
||||
# 성숙도 리뷰(2026-09-25) 반영 뒤 남긴 판단과 후속 작업
|
||||
|
||||
2026-09-28 기준, `main` `f753669`(태그 `v0.2.0`)에 남아 있는 것을 적는다. 리뷰 발견은 모두 닫혔다(`README.md` 10·11절). 아래는 "실무 기준이라면 이렇게 두지 않았겠지만, 이번 라운드에서는 이렇게 두었다"고 판단한 것들이다. 다음 리뷰 라운드는 이 문서에서 출발한다.
|
||||
|
||||
우선순위는 P1(다음 작업 전에 처리), P2(다음 라운드), P3(기회가 될 때)이다.
|
||||
|
||||
## 1. 기준을 고치는 대신 한도를 올리거나 목록에 넣은 것
|
||||
|
||||
| 우선 | 항목 | 현재 상태 | 왜 이렇게 두었나 | 다음 행동 |
|
||||
|---|---|---|---|---|
|
||||
| P1 | 초기 JS 예산 | `check:bundle` 203,481 / 204,800 gzip bytes. 여유 약 1.3KB | 11-04 측정에서 실제 모양 기능 하나가 초기 JS를 약 2.9KB 늘린다(`config/scale/feature-shape-growth.json`). 이번 라운드는 측정과 기록까지만 했다 | 기능을 하나 더 넣으면 게이트가 실패한다. 초기 청크에 들어가는 기능 코드를 route 청크로 옮기거나, 예산 근거를 다시 정한다 |
|
||||
| P2 | 레시피 번들 예산 인상 | realtime 40,000 → 40,900(`2c5e268`), file-transfer 55,600 → 55,700(`4b0e44a`). offline-indexeddb 36,891 / 36,900(여유 9바이트) | 기존 규칙(측정값을 100바이트 단위로 올림)을 따랐다. 코드를 줄이지 않고 한도를 맞췄다 | 레시피마다 늘어난 원인을 보고 줄일 수 있는지 본다. offline-indexeddb는 다음 수정에서 바로 넘는다 |
|
||||
| P2 | `check:remediation-ledger` | 실패한다. 게이트 제외 목록(`config/ci/ungated-scripts.json`)에 이유와 함께 있다 | 리뷰 전(`4626b73`)부터 실패했다. 2026-09-18 리팩터링 뒤 테스트 마커(TR-02~TR-04, X-AUDIT-01·02)가 빠졌고, 원장(`docs/operations/adapter-remediation-ledger.md`)의 file-transfer 예산 문구가 옛 값이다 | 원장을 현재 코드에 맞추거나, 역사 기록으로 보고 검사를 없앤다. 맞춘 뒤에는 게이트에 연결한다 |
|
||||
|
||||
제외 목록의 나머지 16개(`check:scale:*`, `verify:extreme-scale`, `test:all` 등)는 로컬 단축 명령이거나 CI가 나눠서 돌리는 묶음이라 빠진 검사가 아니다.
|
||||
|
||||
## 2. 프로젝트 원칙과 어긋나게 들어간 것
|
||||
|
||||
| 우선 | 항목 | 내용 | 다음 행동 |
|
||||
|---|---|---|---|
|
||||
| P2 | `readSubject` 필수화(`c6300e9`) | 계획의 원칙은 "공개 포트는 추가만 한다"인데, 이 변경은 `ExternalSessionOwner.readSubject()`와 `SessionGateway.getSubject()`를 필수로 바꾼다. "전부 main에 합친다"는 지시로 병합했고, CHANGELOG 0.2.0에 [계약]으로 표시했다 | 복사한 프로젝트를 위한 이행 절차(없는 owner는 `integration-failed`로 닫힘)를 README 업데이트 절에 한 줄 더 적는다. 앞으로 같은 종류의 변경은 선택 필드 → 경고 → 필수의 단계를 둘지 정한다 |
|
||||
|
||||
## 3. 원인을 고치지 않고 환경 탓으로 넘긴 테스트
|
||||
|
||||
| 우선 | 테스트 | 관찰 | 다음 행동 |
|
||||
|---|---|---|---|
|
||||
| P1 | `tests/integration/provider-guardian-transaction.test.ts` | 부하가 높을 때 시간 초과. 검증 중 20번에 2번 실패 | 시간 의존 대기를 없애거나 fake timer로 바꾼다 |
|
||||
| P1 | `tests/component/runtime-application.test.tsx` | 부하 평균 약 18~22에서 heading이 `aria-busy` 상태로 남아 실패. 단독 재실행은 통과 | 첫 대기 조건을 10-02와 같은 방식으로 고친다 |
|
||||
| P2 | `http-execution-v3-live-authority` 테스트 | 검증 중 한 번 실패 | 재현 조건을 찾는다 |
|
||||
| P2 | 10-02 후속 | reference-page 첫 대기는 고쳤지만, 무거운 부하에서 같은 파일의 다른 테스트가 한 번 실패했고 메시지가 여전히 "element not found"다 | 같은 파일의 나머지 대기도 같은 방식으로 바꾼다 |
|
||||
| P3 | `tests/system/ci-runner/ci-artifact-contract.test.ts` | 단독으로도 10초 시간 초과가 난 적이 있다(레인 C 보고). 공통 게이트 밖이다 | 시간 한도나 fixture 크기를 조정한다 |
|
||||
|
||||
CI를 켜면(U-1) 이 테스트들이 무작위로 머지를 막는다. CI를 켜기 전에 P1 두 건을 처리한다.
|
||||
|
||||
## 4. 완료 기준은 만족하지만 실무 기준으로 빈틈이 있는 것
|
||||
|
||||
검증 단계(`README.md` 11절)에서 "충족, 단 기준 밖 빈틈"으로 적은 것들이다.
|
||||
|
||||
### 범위를 좁혀 닫은 것
|
||||
|
||||
| 우선 | ID | 빈틈 | 위치 |
|
||||
|---|---|---|---|
|
||||
| P2 | 06-05 | SW 업데이트 설치 실패, `observe`, `health()`는 연결하지 않았다. 레시피 문서에 "없다"고 적었다 | `src/adapters/service-worker/service-worker-page-controller.ts` `watchForUpdates`, `docs/architecture/optional-adapter-recipes.md` |
|
||||
| P2 | 13-03 | 운영 단계는 승격 archive의 SHA만 대조한다. 서명 재검증(`verify:promotion --archived`)은 promotion job에서만 돈다. 실제 Gitea runner에서 돈 적이 없다(U-1) | `config/ci/gates.json` production_gate |
|
||||
| P3 | 05-10 | 임의로 넓힌 id 정책은 생성 시점에 막지 못하고, BEGIN_PUT에서 `INVALID_INPUT`으로 거절한다 | `src/adapters/storage/opfs/opfs-policy.ts` `isWritableObjectId` |
|
||||
| P3 | 01-06 | 하한은 skew를 반영하지 않는다(사용자 결정). 서버 수명 ≥ 최소 잔여 수명 + skew 조건을 문서로 둔다. 서버 시각 추정이나 상대 수명(`ttlMs`) 계약이 생기면 다시 본다 | `docs/architecture/presigned-transfer-and-image-cdn.md` 172행 부근 |
|
||||
| P3 | 09-08 | 코드로 막지 않고 주석으로 닫았다(리뷰가 허용한 대안) | `src/features/local-draft-feature/domain/local-draft.ts` (`8784354`) |
|
||||
| P3 | 12-12 | `noUnusedLocals`만 켰다. `noUnusedParameters`는 켜지 않았다 | `tsconfig.base.json` |
|
||||
| P3 | 14-07 | 틀린 수치를 지우고 검사 범위를 적었다. `verify:documentation`이 검사하는 범위는 그대로 좁다 | `docs/operations/ci-quality-gates.md` |
|
||||
| P3 | 07-07 | 리뷰가 선택으로 제안한 `no-deprecated` lint를 켜지 않았다 | `eslint.config.ts` |
|
||||
| P3 | 09-07 | 기능 제거 검증이 lint, `check:i18n`, e2e를 건너뛴다 | `scripts/test-sample-removal.ts` |
|
||||
|
||||
### 테스트가 약한 것
|
||||
|
||||
| 우선 | ID | 빈틈 |
|
||||
|---|---|---|
|
||||
| P2 | 07-03 | V2 행이 하나도 없어도 V2/V3 일치 테스트가 통과한다. V3에만 있는 operation도 보지 않는다 |
|
||||
| P3 | 01-11 | probe 재사용 테스트가 공개 이미지만 쓴다. capability가 필요한 비공개 이미지 경로는 테스트가 없다 |
|
||||
| P3 | 05-03 | 손상된 budget 행만 테스트한다. 손상된 binding 행은 테스트하지 않는다 |
|
||||
| P3 | 06-10 | Vite SW 설정이 `dist/config.json`을 읽도록 바뀐 부분에 단위 테스트가 없다(입력 해석 함수만 테스트) |
|
||||
| P3 | 08-04 | en-US 브라우저 검사가 목록·폼 화면만 본다. 상세·상태 화면은 보지 않는다 |
|
||||
| P3 | 08-07 | 요청 ID가 화면에 뜨는지만 보고, 같은 ID의 진단 이벤트는 확인하지 않는다 |
|
||||
|
||||
### 나중에 조용히 깨질 수 있는 것
|
||||
|
||||
| 우선 | ID | 빈틈 | 위치 |
|
||||
|---|---|---|---|
|
||||
| P2 | 06-08 | 이전 릴리스 fallback이 Vite 기본 폴더명 `assets/`를 하드코딩한다. `build.assetsDir`를 바꾸면 fallback이 조용히 꺼진다 | `src/adapters/service-worker/service-worker-static-assets.ts:66` `BUILD_ASSET_DIRECTORY` |
|
||||
| P3 | 01-09 | 바이트 한도 검사는 조립 코드가 transport에 `maxPartCount`를 넘길 때만 동작한다 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` |
|
||||
| P3 | 01-03 | 업로드 PUT에 idle 제한이 없다. 멈춘 5 MiB part는 크기 기반 마감(약 110초)에서야 끝난다. 리뷰가 허용한 선택지다 | `src/adapters/browser-transfer/resumable-upload/` |
|
||||
| P3 | 03-03 | 서버가 correlation 헤더를 되돌려 주지 않으면 실패의 `requestId`가 비어 있다 | `src/adapters/http/client.ts` (requestId 해석), `src/adapters/http/http-execution-v3.ts` |
|
||||
| P3 | 02-09 | 문서의 줄 번호 참조(`server-state-scope-runtime.ts:148`)가 이미 `:154`로 밀렸다. 이 문서는 `verify:documentation` 대상이 아니다 | `docs/architecture/client-cache-and-storage.md` |
|
||||
|
||||
## 5. 테스트 쪽 우회
|
||||
|
||||
| 우선 | 항목 | 내용 | 다음 행동 |
|
||||
|---|---|---|---|
|
||||
| P2 | `tests/browser-capabilities/resumable-upload.spec.ts:7` | `PAGE_ORIGIN`에 포트 4174가 박혀 있다. 설정 파일의 포트를 바꾸면 CORS로 실패한다. 이번 검증은 파일을 잠시 고쳐 돌린 뒤 되돌렸다 | Playwright `baseURL`에서 origin을 읽는다 |
|
||||
| P3 | `tests/e2e/service-worker-update.spec.ts` | 빌드 B가 route chunk를 하나 바꾸도록 not-found 페이지에 export를 덧붙인다(`0289e0b`). 앱 동작은 정상이고, 09-02 뒤로 build ID가 route chunk에 들어가지 않아 생긴 조치다 | 두 빌드를 만드는 도우미에 "route chunk를 바꾸는 변경"을 공식 옵션으로 둔다 |
|
||||
| P3 | fixture의 pnpm 설치 검사(F-4, F-12) | fixture가 pnpm을 부를 때 `pnpm_config_verify_deps_before_run=false`로 설치 검사를 끈다(`scripts/lib/fixture-node-modules.ts:41`). fixture가 공유 `node_modules`를 링크로 쓰는 구조는 그대로다 | fixture 전용 설치나 읽기 전용 링크를 검토한다 |
|
||||
| P3 | 00-03의 이미 남은 임시 폴더 | 테스트는 이제 자기 임시 폴더를 지운다. 수정 전에 쌓인 약 2,400개(`repository-inventory-*`, `sw-assets-*` 등)는 `/tmp`에 남아 있다 | 호스트에서 한 번 지운다 |
|
||||
|
||||
## 6. 사용자 몫(변동 없음)
|
||||
|
||||
`SPEC.md` "범위 밖"과 `tasks/todo.md` 끝에 있다. U-1(Gitea Actions·runner·required check), U-2(수동 접근성 검토 10건), U-3(태그 `v0.2.0` push), U-4(작성자 외 기능 추가 기록, staging 공급망 smoke), U-5(백엔드 멱등 키 계약 확인), F-11(SBOM의 `scheduler@0.27.0` 분류와 의존성 기준선 재승인).
|
||||
|
||||
## 7. 권하는 처리 순서
|
||||
|
||||
1. 초기 JS 예산(1절 P1). 다음 기능 추가가 여기서 막힌다.
|
||||
2. 부하 flaky 테스트 두 건(3절 P1). CI를 켜기(U-1) 전에 처리한다.
|
||||
3. `check:remediation-ledger` 정리와 게이트 연결(1절).
|
||||
4. 하드코딩 두 건: `resumable-upload.spec.ts`의 포트, 06-08의 `assets/`(4·5절 P2).
|
||||
5. 나머지 P2, 그다음 P3.
|
||||
@@ -402,5 +402,6 @@ opt-in 런타임(realtime, OPFS, Web Push, browser-transfer)은 기본 구성에
|
||||
- 결정으로 종료: 01-06. 하한까지 skew를 완화하면 시계가 정확한 기기에서도 서버에서 이미 만료된 capability를 받아들인다. 상한만 `maxClockSkewMs`를 반영하고, 하한은 "서버 수명 ≥ 최소 잔여 수명 + skew" 조건을 `docs/architecture/presigned-transfer-and-image-cdn.md`에 둔다.
|
||||
- 브라우저 검증 범위: e2e 전체와 browser-capabilities를 chromium·firefox·webkit에서 돌렸다(visual·storybook은 설정상 chromium만). 처음에는 호스트에 WebKit 시스템 라이브러리(libevent, libavif)가 없었고, 설치한 뒤(2026-09-28) WebKit에서만 난 실패 1건을 `b1a36ab`로 고쳤다. 구 탭 청크 복구 spec이 WebKit의 import 실패 문구를 허용하지 않았다.
|
||||
- 로컬에서 확인할 수 없는 것: 13-03의 production 단계 archive 다운로드와 12-01의 CI 실행은 Gitea runner에서 확인해야 한다(U-1).
|
||||
- 남긴 판단과 후속 작업: 완료 기준은 만족했지만 실무 기준으로 미룬 것(예산 인상, 게이트 제외, 부하 flaky, 기준 밖 빈틈, 테스트 우회)은 [`FOLLOW-UP.md`](FOLLOW-UP.md)에 우선순위와 함께 적었다.
|
||||
- 사용자 몫: U-1~U-5, F-11(SBOM의 `scheduler@0.27.0` 분류, 의존성 기준선 재승인).
|
||||
- 리뷰 범위 밖에서 확인한 것: `check:remediation-ledger`는 `4626b73`에서도 실패한다(2026-09-18 리팩터링 뒤 테스트 마커와 예산 문구가 원장과 어긋남). `config/ci/ungated-scripts.json`에 이유를 적어 두었다.
|
||||
|
||||
Reference in New Issue
Block a user