Merge lane K: CI, guardrails and release fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 23:42:40 +09:00
co-authored by Claude Opus 5.5
88 changed files with 2049 additions and 746 deletions
+46 -8
View File
@@ -1,6 +1,6 @@
# CI quality-gate orchestration
`config/ci/gates.json` is the executable registry for all 26 gates and the sole
`config/ci/gates.json` is the executable registry for all 27 gates and the sole
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
strict v2 contract; it is not an independent configuration authority. Update
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
@@ -35,9 +35,20 @@ canonical `check:ci`를 돌린다(`scripts/lib/removal-fixture.ts`의
`check:ci`는 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지도 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
한다. 지금은 `tests/scale`의 규모 테스트 13개만 있다(리뷰 11-03에서 PR tier로
옮길 때 뺀다). 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
재면 모든 workload가 noise floor 아래라 이차 누적을 놓친다. 조합 timing은
산출물(`artifacts/scale/pr/composition-s0-s2.json`)에 기록만 한다.
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
이 tier에만 있는 테스트 6개는 `ungated-tests.json`에 이유와 함께 남아 있다.
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
@@ -83,6 +94,16 @@ The gate runner checks the same inherited environment names before loading the
contract or entering the execution callback, so they cannot reach a child gate
process.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install
hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가
부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`,
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
파일 머리 주석에도 있다.
The dependency graph is:
```text
@@ -94,9 +115,11 @@ MERGE_READY
DOCUMENTATION_READY (off-chain)
```
`check:architecture`는 dependency-cruiser 결과와 별도로 Babel parser/Node
resolver 기반 `staticImportGraph`를 `artifacts/quality/dependency-report.json`에
기록한다. TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
@@ -269,7 +292,20 @@ promotion, and field evidence through aggregation.
Runbook jobs write to the stable path
`artifacts/runbooks/<runbook-id>/record.json`; the dynamic release identity is
stored inside the record. This keeps gate evidence lookup independent from
stored inside the record.
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
it against the local `dist/` build; it reads no `public/` placeholder, so a
missing build fails. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
without provider evidence the production stage stays open. That is the intended
result: a local drill cannot show that the promoted release can be rolled back.
FE-GATE-016 (`rollback-drill`) is retired because it ran the same FE-RB-005
drill as FE-GATE-025 (`RETIRED_GATE_IDS` in `scripts/contracts/ci-gates.ts`). This keeps gate evidence lookup independent from
slashes or other provider-specific characters in `RELEASE_ID`, while each
workflow artifact remains scoped to its own run.
@@ -335,7 +371,9 @@ Repository variables required by higher tiers:
- `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the
`ubuntu-latest` runner label; the workflow exposes it to gates as
`CI_RUNNER_IMAGE` (required by every tier)
- `HOSTING_BASE_URL` for live header verification
- `HOSTING_BASE_URL` for live header verification of the deployed promoted
release (FE-GATE-019, production stage). Without it the gate fails; the
local fixture result is `UNVERIFIED`
- `APP_PROFILE` for the runtime profile the release candidate is built from
(`local`, `development`, `staging`, `production`;
`scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty
+36
View File
@@ -10,6 +10,42 @@ Performance evidence is deliberately split by measurement context:
release-specific production samples over 28 days and evaluates p75 LCP, CLS,
and INP against 2.5 s, 0.10, and 200 ms.
## 번들 예산의 기준선과 여유
리뷰 13-14. 예산은 `config/performance/budgets.json`에 있고
`scripts/check-bundle.ts`가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의
96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.
| 항목 | 값 |
|---|---|
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
| 템플릿 기준선(2026-09-25 측정) | 196,573 gzip bytes. 빌드 ID가 번들에 들어가므로 빌드마다 수백 바이트 달라진다(196,386~196,623 관측) |
| 여유 | 약 8,200 bytes(4%) |
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 가장 큰 lazy chunk는 약 8 KB |
초기 JS 9개 파일 중 세 개가 대부분이다. `index` 93.5 KB, `design-system`
65.6 KB, `preload-helper` 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다.
측정 조건:
- 초기 파일은 Vite manifest의 entry와 그 static import다
(`scripts/lib/classify-vite-bundle.ts`). dynamic import chunk는 lazy다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.5 KB gzip)는 예산에 들어가지
않는다.
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
작다. 예산은 gzip 기준 그대로 둔다.
- Node·pnpm·runner 이미지는 `artifacts/performance/bundle.json`의 `context`에
기록된다.
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
`vite preview`로 띄워 한 번만 잰다. named interaction 시간은 Node의
`performance.now()`로 Playwright 클릭부터 heading 대기까지 재므로 Playwright
왕복 시간이 들어간다. 한 번 측정한 값은 흔들린다. 경계 근처 값으로 판단할
때는 여러 번 돌려 중앙값을 본다.
The field minimum eligible-sample threshold is intentionally unresolved until
a privacy-approved telemetry baseline exists. Therefore the field command
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
+47 -6
View File
@@ -12,6 +12,32 @@ cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
HTML alone, or declaring recovery from cache-purge completion is prohibited.
Recovery is established by old/new reachability probes.
Before deploying a promoted release later, or rolling back to one, re-verify
its promoted bundle (the five files uploaded by the `promotion` job) with the
archived mode (review 13-04). Provider evidence expires two hours after issue,
so the normal mode refuses any release promoted before that. The archived mode
still checks signatures, digests and the exact five members, and judges
freshness at the release's recorded promotion time
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
```bash
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
PROVENANCE_PUBLIC_KEY_PATH=... PROVENANCE_KEY_ID=... \
EXPECTED_PROMOTION_RUN_ID=<run id> EXPECTED_PROMOTION_RUN_ATTEMPT=<attempt> \
EXPECTED_PROMOTION_SOURCE_REVISION=<commit> \
EXPECTED_PROMOTION_ARCHIVE_SHA256=<archive sha256> \
corepack pnpm verify:promotion -- --root <promoted bundle directory> --archived
mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.tar.gz -C <release dir>
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
```
The expected values come from the release record, not from the bundle. The
drill then checks that release's build/config/manifest tuple and its assets,
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
are recorded, because those happen outside this repository.
The provider-independent cache defaults are:
- hashed assets: `public, max-age=31536000, immutable`
@@ -26,9 +52,24 @@ HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
`Content-Type` still fails the hosting gate.
`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
requires the artifact to report `mode: "live"`. The live target must be its
canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
200 without leaving that origin before its cache, content-type, and security
headers can count as deployment evidence.
`corepack pnpm verify:hosting-headers` compares the declared headers with a
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
`mode: "live"` can pass. The live target must be its canonical, non-loopback
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
origin before its cache, content-type, and security headers can count as
deployment evidence. The hashed asset it requests is the entry script named by
the served `index.html`, so it checks the release that is actually deployed.
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
`PROD_PROMOTION_READY`). It runs after `promotion` and after the project has
deployed the promoted release. This repository's workflow stops at promotion:
uploading the release, switching the active pointer, and the post-switch smoke
are the project's provider adapter, chosen with the hosting provider.
Keep a retired release's hashed assets reachable while any open tab may still
request them. The minimum is the previous release while the next one is
active (the rolling window modeled in `tests/release/release-fixture.ts`).
Size it to the longest session the product supports; a tab older than that
depends on the reload-once recovery (FE-RB-002).