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
+6
View File
@@ -10,6 +10,12 @@ registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
blank identity/timestamp/signature fields, pending verdicts, mismatched release
IDs, or missing routes.
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
it is required once per release candidate, not on every merge. The merge gate
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
and a record marked `reviewed` must be complete.
This list is not maintained by hand: `verify:documentation` compares it against
the installed route registry and fails when a registered route is absent. It
said six routes while ten were registered, which put the platform overview and
@@ -206,7 +206,7 @@ src/shared/api
### 1.2 계층 방향
현재 `config/architecture/layers.json`의 방향을 유지한다.
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
```text
domain -> domain only
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
- registry scanner는 TS registry의 required field, uniqueness와 reference를
검증한다.
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
@@ -38,9 +38,18 @@
## 경계와 검증
- 제품 코드는 `presentation/design-system/index`만 import한다.
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
undefined token과 tooltip-only required information fixture를 거절한다.
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
않는 `PaginationLandmarkContext`를 읽는다.
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
import, raw palette, undefined token과 tooltip-only required information
fixture를 거절한다.
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
검증한다.
@@ -65,7 +65,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
| --- | --- | --- | --- |
| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
| 계층 의존 방향 | 준비됨 | dependency-cruiser + TS-aware static graph, unresolved/parse/layer/cycle negative fixture | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| 계층 의존 방향 | 준비됨 | TS-aware static graph(`scripts/check-architecture.ts`, 규칙 `.dependency-cruiser.json`), unresolved/parse/layer/cycle negative fixture. dependency-cruiser 자체는 TS 7을 해석하지 못해 실행하지 않음(12-05) | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| application facade | 준비됨 | module-augmented feature input registry, typed output catalog, provider, production composition test | feature별 input contribution과 제거 gate 유지 |
| REST HTTP client | 준비됨 + hardening delta | reference vertical의 path/search/body projection, attempt timeout/retry, abort/cleanup은 `COMPOSED` | auth fail-close/final invariant, total deadline, bounded decoder, status/media/CSRF/conditional/pagination은 `DESIGNED_NOT_IMPLEMENTED` |
| Browser RPC 공통 계약/runtime | 준비됨/미조립 | V3 operation/profile registry, typed application port, bounded unary/server-stream lifecycle와 unavailable adapter는 `AVAILABLE_NOT_COMPOSED` | actual descriptor/generated client, protocol transport, proxy/provider/browser conformance |
+40 -13
View File
@@ -25,6 +25,15 @@ The following edges are forbidden:
- an adapter to presentation, bootstrap internals, or another concrete adapter
- feature domain/application to its presentation or outbound adapter, and
feature presentation to its outbound adapter
- a module presentation may import to a concrete adapter: files outside a
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
The graph checks one edge at a time, so a re-export there would carry an
adapter into presentation with every other rule passing. The one exception is
the type-only `src/features/feature-adapter-contribution.ts`
- presentation to `src/apps` or `src/contexts`, except
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
(`presentation-does-not-import-apps-or-contexts`)
## The adapter kernel
@@ -35,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for:
the bounded-capacity guard
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
failure constructors
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
invalidation transport and its types. Any adapter may import it; today
`query-cache` does
Each rule above is enforced by `check:architecture`, including the kernel
carve-out, so this table and the executable rules cannot drift apart. Two edges
are still open and are named explicitly in `.dependency-cruiser.json` rather
than left silent: the generic presentation modules that read the installed
registries today, and the two collaborator types `query-cache` reads from
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
fails the gate.
carve-out, so this table and the executable rules cannot drift apart.
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
exempted path in `pathNot`, and the reason, owner and revisit condition in
`comment` (review 12-07). Besides the kernel, the exceptions are:
- the generic presentation modules that read the installed registries today
(`generic-presentation-does-not-compose-the-product`). The list names exact
files, so a new module that reads a registry fails the gate
- `src/presentation/adapters/query`, the TanStack Query binding
(`presentation-does-not-know-adapters`)
- `src/presentation/routes/app-router.tsx` importing the app
(`presentation-does-not-import-apps-or-contexts`)
- the design-system facades (`design-system-is-reached-through-its-index`)
## 어댑터 그룹의 공개 경계
@@ -63,10 +83,15 @@ fails the gate.
위한 것이다.
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
않는다. 두 런타임이 각자 독립적으로 제거 가능하고
(`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다.
규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가
이것이다.
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
경계다.
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
@@ -83,8 +108,9 @@ application APIs augment the generic typed input registry. Concrete output
ports are composed in bootstrap and stay hidden behind the application facade.
Project-selected capabilities still implement the same output boundaries.
`check:architecture` keeps dependency-cruiser's report and adds the
authoritative TypeScript-aware graph below it:
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
parse TypeScript 7 and checked zero modules (review 12-05):
```json
{
@@ -103,7 +129,8 @@ authoritative TypeScript-aware graph below it:
```
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
and JSDoc import references. It applies the path rules from
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
source imports, and fails closed on JavaScript-family source/specifiers,
unsupported rule shapes, unresolved imports, parse failures, error-severity
@@ -130,6 +130,15 @@ Web Push를 함께 설치하지 않는다.
integration test를 작성한다.
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
browser support와 runbook을 갱신한다.
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
아래 기능을 막는다(리뷰 13-08).
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
`img-src`에 `blob:`을 더한다.
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
smoke를 늘린다.
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
별도 project catalog에서 `INSTALLED`로 바꾼다.
+3 -2
View File
@@ -53,8 +53,9 @@ and exact input type.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared `Result`/`AppFailure` contract.
The architecture gate analyzes TS/TSX imports independently of
dependency-cruiser, rejects local JavaScript-family specifiers and executable
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
+5
View File
@@ -29,5 +29,10 @@ sequenceDiagram
CI->>Browser: boot, route, API, and reload-loop smoke
```
In this repository the workflow stops at promotion. The upload, pointer switch
and smoke steps above belong to the project's provider adapter; after it has
deployed the promoted release, FE-GATE-019 probes the live headers (review
13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
@@ -52,7 +52,9 @@ TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파
1. ESLint가 product와 negative fixture의 `ts`/`tsx`를 모두 검사한다.
2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
3. `check:architecture`의 import 그래프가 TS/TSX를 해석한다. 규칙은
`.dependency-cruiser.json`에 있지만 dependency-cruiser는 실행하지 않는다.
TypeScript 7을 해석하지 못해 0개 모듈을 검사했기 때문이다(리뷰 12-05).
4. `scripts/check-registries.ts`가 TS/TSX를 검색한다.
5. `config/contracts/registry-governance.json`과 승인 baseline은 `.ts/.tsx`
source 경로를 사용한다.
+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).
+5
View File
@@ -11,3 +11,8 @@ Close only when compatibility and release-coherence gates pass, critical smoke
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
the restored release ID. Pointer-switch or cache-purge completion alone is not
recovery evidence.
Verify the prior release before switching to it: `verify:promotion -- --root
<bundle> --archived` and `drill:runbook -- FE-RB-005 --release-root <extracted
archive>`. The commands and inputs are in
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md).
+17 -1
View File
@@ -7,7 +7,23 @@ maps are prohibited defaults.
`config/hosting/security-headers.json` is the declared header set. Hosting
verification compares that declaration with live responses. CSP deliberately
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
remain compatible with that baseline.
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
`securitypolicyviolation` event or console error (review 13-08). One
violation is known: zod probes `Function("")` on its first object schema and
the policy refuses it. Parsing still works, but the default build reports the
violation on every boot until zod is configured `jitless` before the first
schema is built. `z.config` in the entry module is too late, because the
bundler evaluates the shared chunks that build schemas first. The smoke sets
zod's global config before page scripts run so it can catch every other
violation; the spec comment names when to remove that. Features that are off by
default need CSP additions when a project selects them; see step 9 in
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
header generated per environment at deploy time, because those values are set
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
exist yet; a project that deploys should add it with its provider adapter.
Route guards are UX hints and client validation does not replace backend
authorization or validation.
+69
View File
@@ -39,6 +39,75 @@ Changing it requires `DEPENDENCY_BASELINE_OWNER` and
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
rejected.
## 무엇을 증명하고 무엇을 증명하지 않는가
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
것으로 읽지 않는다.
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|---|---|---|
| SBOM(`artifacts/release/sbom.cdx.json`) | lockfile에 고정된 설치 그래프(`pnpm list --depth Infinity`, `scripts/generate-supply-chain.ts`)와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
| 번들 패키지 목록(`artifacts/quality/vite-module-inventory.json`의 `packages`) | 배포 번들에 모듈이 하나 이상 들어간 패키지의 `name@version`. Vite가 번들에 넣은 모듈에서 바로 만든다(`scripts/lib/vite-module-inventory.ts`) | 패키지 안의 어떤 코드가 실행되는지, 취약점 없음 |
| local provenance(`artifacts/release/provenance.json`) | dist digest, lockfile, source set, SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음, 빌드한 주체. 서명이 없는 자기 보고다(`builder.id`가 `local:`, `invocationId`가 `LOCAL_UNSIGNED`). `predicateType`이 SLSA provenance v1이어도 SLSA 수준을 뜻하지 않는다 |
| 외부 provenance 서명 | 지정 키 보유자가 이 run, source revision, 후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음 |
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
## 최소 구성과 전체 구성
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
| 구성 | 켜는 것 | 보장하는 것 | 보장하지 않는 것 |
|---|---|---|---|
| 최소 구성(provider 없음) | merge·release stage 게이트, `immutable_build`(FE-GATE-015·027). provider 변수는 비워 둔다 | lockfile 무결성과 설치 스크립트 차단, SBOM과 local provenance의 digest 정합, secret scan, 재현 빌드, 후보 archive의 exact member와 digest, release 대상 환경 승인(FE-GATE-027) | 외부 취약점 검사, 서명된 provenance. provider job은 명령과 키가 없어 실패하고, `promotion` job은 두 provider job의 성공을 요구하므로 돌지 않는다. 승격은 사람이 결정한다 |
| 전체 구성 | 위 전부와 `vulnerability_provider`·`provenance_provider`·`promotion` job, 아래 runner 조건과 provider 키 | 위 전부와, 지정 키 보유자가 이 후보 digest·run·source에 서명했다는 것, 승격된 exact-five bundle(`verify:promotion`) | provider가 성실히 검사했는지, 빌드 job 격리(위 "무엇을 증명하고" 표 참고) |
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
### provider 신뢰 키 교체와 폐기
신뢰 키는 repo 변수 `VULNERABILITY_PUBLIC_KEY_PATH`·`VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`·`PROVENANCE_KEY_ID`가 가리키는 공개 키 파일이다
(`scripts/lib/provider-trust.ts`). 두 provider는 서로 다른 키를 써야 한다
(`assertDistinctProviderTrust`). 승격 기록은 키 ID·지문과 trust policy
SHA-256을 남긴다.
교체 순서:
1. provider가 새 키 쌍을 만들고 공개 키만 넘긴다.
2. 새 공개 키 파일을 runner가 읽을 수 있는 경로에 두고, 두 변수를 새 경로와 새
key ID로 한꺼번에 바꾼다. 키 ID는 새 값을 쓴다. 이전 ID를 재사용하면 기록만
보고 어느 키였는지 구분할 수 없다.
3. provider 쪽 서명 키를 새 키로 바꾼 뒤 release를 한 번 돌려 `promotion`이
통과하는지 확인한다.
4. 이전 공개 키 파일은 지우지 않고 보관한다. 이전 키로 승격된 release를 나중에
배포하거나 그 release로 롤백할 때 `verify:promotion -- --archived`가 그 키를
요구한다(`docs/operations/release-cache-rollback.md`).
폐기 순서(키 유출 등):
1. 해당 변수에서 그 키를 즉시 뺀다. 그 키로 서명된 새 승격은 이때부터 실패한다.
2. 보관 중인 이전 공개 키 파일도 지운다. 그 키로만 서명된 과거 release는
`verify:promotion -- --archived`를 통과하지 못한다.
3. 그런 release를 다시 써야 하면 새 키로 provider 검증을 다시 받는다. 같은 후보
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
## External promotion controls
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
@@ -1103,8 +1103,11 @@ validate한다.
외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가
실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다.
현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이
문서는 이를 production/field gate로 이동시키지 않는다.
signed manual accessibility review는 release gate `FE-GATE-028`이다
(`config/ci/gates.json`, 리뷰 08-06). 사람의 서명은 릴리스 후보 하나에 대해
하므로 merge마다 요구할 수 없다. merge gate `FE-GATE-009`는 자동 axe 검사와
기록 형식 검사(`review:a11y-manual -- --format-only`,
`scripts/lib/manual-a11y-evidence.ts`의 `validateManualA11yRecordFormat`)만 한다.
### 16.4 병렬화와 shard