frontend-quality-gates / merge / static checks (pull_request) Successful in 1m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 22m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m54s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
문제: 작업 매뉴얼·루트 지침·스킬이 「desktop의 FE-GATE-013은 호스트 제약
실패로 적고 merge 가능 여부는 소유자가 정한다(결정 대기 D8)」라고 적고
있다. 1d3eb901 뒤로 workflow와 scripts/verify.sh는 이 게이트를
scripts/run-in-system-container.sh 안에서 돌리고, 다른 게이트처럼 rc로
센다. CHANGELOG에는 이 브랜치의 변경이 없다.
고른 방법:
- gates.md 3절 문단을 「시스템 컨테이너 안에서 돈다」로 바꾸고, AGENTS.md
·improve.md·new-feature.md·operate.md·desktop-gates 스킬의 기록법
문구를 그 절을 가리키게 고친다.
- decisions.md: 소유자 결정(2026-11-11, design-docs template-program
README 5절 e)을 2.1절 행으로 더하고 열린 결정 대기 D8을 닫는다.
evidence.md의 근거 행을 새 규칙 이름과 runner 사건으로 고친다.
- docs/operations/ci-quality-gates.md, docs/testing/taxonomy.md,
README.md에 컨테이너 경로와 그 한계(root라 비특권 userns 조건은 증명하지
않음, privileged를 막는 runner에서는 깨짐)를 적는다.
- CHANGELOG 미출시 절에 이 브랜치의 변경을 적는다.
위험·한계: desktop·runner에서 FE-GATE-013이 실제로 초록인지는 이 브랜치
끝의 merge 단계 실행으로 확인한다.
검증: 노트북 scripts/verify.sh docs rc=0. desktop verify:documentation
PASS_SCOPED, 문서를 읽는 시험 넷(changelog-review-ids,
documentation-readiness, template-contract-documents,
deletable-history-documents) 29개 통과.
114 lines
13 KiB
Markdown
114 lines
13 KiB
Markdown
# 게이트
|
|
|
|
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 검사 몇 개(package script, 2절 표), 통합 때는 몇 개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 [../operate.md](../operate.md) 4.1절이다.
|
|
|
|
```text
|
|
작업 중 바뀐 테스트 파일 하나 (2절)
|
|
커밋 전 검사(package script) (2절)
|
|
묶음 끝·통합 + 검사 더 (2절)
|
|
merge 판정 scripts/verify.sh merge (stage 전부, CI env) (3절)
|
|
리뷰 시작 merge 단계 + documentation 단계 (3절)
|
|
```
|
|
|
|
게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이고 설명은 `docs/operations/ci-quality-gates.md`다. 이 문서는 그 목록을 다시 적지 않는다.
|
|
|
|
## 1. 진입점 `scripts/verify.sh`
|
|
|
|
```text
|
|
scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>] [--dry-run]
|
|
```
|
|
|
|
| 단계 | 하는 일 | 기본 위치 |
|
|
| --- | --- | --- |
|
|
| `docs` | 작업 매뉴얼 검사(`scripts/check-work-docs.py`)와 장부 형식 | 여기(노트북) |
|
|
| `hooks` | repo 훅·검사기·장부 시험(`python3 -m unittest discover -s scripts/tests`) | 여기 |
|
|
| `gate <ID>…` | 게이트마다 `corepack pnpm ci:gate <ID>`, CI env로 | desktop |
|
|
| `parts <ID>` | 그 게이트의 명령(`commandIds`)을 하나씩 끝까지. 음성 fixture(`expect: fail`)는 정해진 종료 코드면 통과 | desktop |
|
|
| `script <이름>… [-- 인자…]` | package script를 하나씩(예: `verify:documentation`). `--` 뒤 인자는 script가 하나일 때만 넘긴다(예: `scripts/verify.sh script test:sample-removal -- --feature=<id>`) | desktop |
|
|
| `exec -- <명령…>` | 명령 하나. 한 테스트 파일(`node scripts/run-vitest.ts run <파일>`)이나 package script가 아닌 node 스크립트 | desktop |
|
|
| stage id | `config/ci/gates.json` `stages`의 그 단계 `gateIds` 전부 | desktop |
|
|
|
|
- stage id는 계약 파일에서 읽는다. 단계가 바뀌면 스크립트를 고치지 않아도 따라간다. `--dry-run`은 돌릴 명령만 보인다.
|
|
- 게이트·stage는 실패가 있어도 끝까지 돌고 게이트마다 `<이름> rc=<n> <초>s` 한 줄을 남긴다. 하나라도 실패하면 rc=1이다. 종료 코드 2는 사용법, 4는 원격 준비 실패다.
|
|
- 잘못된 단계·게이트 ID는 desktop에 보내기 전에 노트북에서 거절한다.
|
|
- desktop에서 바뀐 파일(생성 명령, 기준선 다시 쓰기의 결과)은 로그 폴더의 `changes.patch`에 남는다. `--apply-back`을 주면 그 패치를 노트북 작업 트리에 얹는다. 예: `scripts/verify.sh script create:feature --apply-back -- <id> --with-create`.
|
|
- `VERIFY_SNAPSHOT=1`을 주면 `artifacts`·`dist`·`test-results`를 로그 폴더의 `snapshot/`에 복사한다. 리뷰어가 함께 읽는 사본이다.
|
|
- 환경 변수로 바꿀 수 있는 것(호스트, 원격 checkout, 기준 ref, 잠금, 로그 폴더, node 경로)은 스크립트 머리 주석에 있다. 복사한 프로젝트는 [../operate.md](../operate.md) 4.1절과 이 값만 자기 환경으로 바꾼다.
|
|
|
|
## 2. 언제 무엇을
|
|
|
|
- 패키지 스크립트는 `corepack pnpm <script>`로 돌린다. `npm run`으로 돌리면 제거 드릴이 pnpm을 가정해 모든 검사가 `Unknown command`로 실패한다.
|
|
- 테스트 파일 하나는 `node scripts/run-vitest.ts run <file>`로 돌린다. 이 runner가 `src/.generated/`를 먼저 만든다. `pnpm exec vitest run <file>`은 그 단계를 건너뛰어 import 오류로 실패하고, `pnpm test:unit -- <file>`은 범위를 좁히지 않는다(`docs/testing/taxonomy.md`).
|
|
- 실패를 경고로 낮추지 않는다. `continue-on-error`나 경고만 내는 스크립트를 쓰지 않는다.
|
|
|
|
| 때 | 돌릴 것 |
|
|
| --- | --- |
|
|
| 작업 중 | 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나 |
|
|
| 커밋 전(작업마다) | `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` |
|
|
| 묶음 끝·통합 | 위에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build` |
|
|
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 |
|
|
| merge 가능이라고 말하기 전 | `scripts/verify.sh merge`(3절) |
|
|
| 리뷰 시작 | `scripts/verify.sh merge`와 `scripts/verify.sh documentation`(FE-GATE-017) |
|
|
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) |
|
|
| 공급망·release 경로를 바꿀 때 | `scripts/verify.sh release` |
|
|
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks` |
|
|
|
|
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
|
|
|
|
## 3. merge 가능 판정
|
|
|
|
"merge 가능"은 다음 방법으로만 말한다(소유자 지시 2026-11-03). 고른 스크립트 목록이 다 통과했다는 것은 근거가 아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 일이 있다.
|
|
|
|
1. **대상:** `config/ci/gates.json`의 `stages` 중 `merge`의 `gateIds` 전부.
|
|
2. **명령:** 게이트마다 `corepack pnpm ci:gate <ID>`. workflow도 같은 명령을 쓴다. `scripts/verify.sh merge`가 그것을 돈다.
|
|
3. **env:** workflow 전역 env와 같은 꼴(`CI=true`, `VITE_COMMIT_SHA` 40자리, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest). `CI=true`를 빼지 않는다. 빼고 "통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 일이 있다. `SOURCE_DATE_EPOCH`는 `ci:gate`가 HEAD에서 만든다.
|
|
4. **작업 폴더:** 깨끗한 checkout. `scripts/verify.sh`의 desktop worktree가 그것이다. 노트북 checkout은 `.claude/worktrees/`를 품고 있어 `test:system`의 repo 복사와 vite 파일 감시가 깨진다.
|
|
5. **한 게이트 안의 명령:** `ci:gate`는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 `scripts/verify.sh parts <ID>`로 돌린다.
|
|
6. **기록:** 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다. 게이트 로그는 `artifacts/quality/gates/`의 `FE-GATE-0NN.txt`에 쌓이고, `scripts/verify.sh`가 desktop 로그 폴더의 `gate-artifacts/`로 복사한다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다.
|
|
|
|
**가끔 떨어지는 게이트.** 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다([testing.md](testing.md) 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
|
|
|
|
**FE-GATE-013은 시스템 컨테이너 안에서 돈다.** provider sandbox는 systemd user manager와 bubblewrap을 쓴다. CI의 job 컨테이너에는 둘 다 없고, desktop ssh 셸은 비특권 user namespace가 막혀 있다. 그래서 계약(`config/ci/gates.json`의 `hostEnvironment`)이 이 게이트를 `scripts/run-in-system-container.sh` 안에서 돌게 하고, workflow와 `scripts/verify.sh`가 같은 길을 쓴다. 래퍼는 일회용 privileged systemd 컨테이너(`config/ci/system-container.Dockerfile`)를 띄워 작업 트리를 복사하고 root로 돌린 뒤 `artifacts/`를 되가져온다. Docker가 필요하다(CI는 runner의 dind, desktop은 호스트 Docker). 이 게이트도 다른 게이트처럼 rc로 센다(소유자 결정 2026-11-11, [decisions.md](decisions.md) 2.1절). 컨테이너 안은 root라 「비특권 runner에서 bwrap user namespace」 조건 자체는 증명하지 않는다. 실패하면 `scripts/verify.sh parts FE-GATE-013`으로 명령마다 보고, `SYSTEM_CONTAINER_KEEP=1`이면 컨테이너를 남긴다. 호스트 시스템 설정은 바꾸지 않는다.
|
|
|
|
## 4. CI env에서만 나는 실패
|
|
|
|
로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(결함 패턴 G3).
|
|
|
|
| 모양 | 기준 |
|
|
| --- | --- |
|
|
| e2e가 build id를 `"local-build"`로 고정해 workflow의 `VITE_BUILD_ID`와 어긋났다 | merge 판정은 3절 env로만 한다 |
|
|
| workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어 merge 게이트 다섯 개가 실제 CI에서만 실패했다 | 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다. 테스트용 로컬 빌드 식별값은 `scripts/lib/build-environment.ts`가 한 곳에서 준다 |
|
|
| `CI=true`가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 했다 | 같음 |
|
|
|
|
## 5. 검사가 PASS인데 그 뒤가 실패
|
|
|
|
사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(결함 패턴 G5). 예: 사전 점검이 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로 돌리지 않아 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어졌다. git worktree에서 `.git` 때문에 실패하는 단계를 사전 점검이 PASS로 냈다.
|
|
|
|
기준: 사전 점검은 **본 단계가 쓰는 것과 같은 방법으로** 한 번 실행해 본다. 실패하면 원인 이름을 붙여 멈춘다. 존재 여부만 보는 점검은 PASS가 아니라 "확인 안 함"(`UNVERIFIED`)으로 적는다.
|
|
|
|
## 6. 게이트를 믿을 조건 — 거짓 통과 막기
|
|
|
|
- 검사가 실제 대상과 비교하는지 본다. 자기 산출물, 이전 release, 상수 `true`, 오류 화면, fixture 전용 규칙을 보고 통과하면 거짓 통과다(결함 패턴 G7).
|
|
- 검사기 자신을 지키는 음성 fixture가 있어야 한다. 통제는 통과 fixture와 거절 fixture가 둘 다 있어야 검증된다(`docs/testing/taxonomy.md`). 아키텍처 검사기가 0개 모듈을 훑고 통과한 일 뒤로 `check:architecture`는 자체 그래프와 고정 fixture를 쓴다.
|
|
- 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 코드에 상수 `true` 판정을 두지 않는다.
|
|
- 게이트를 고친 뒤 그 게이트가 막던 결함을 다시 넣어(변이) 실패하는지 본다.
|
|
- 게이트 실행 뒤 `git status`가 비어야 한다. 비지 않으면 고정 출력 경로·추적 파일 쓰기 결함이다(결함 패턴 G4).
|
|
|
|
## 7. 문서 검사
|
|
|
|
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 `scripts/verify-documentation-readiness.ts`, `scripts/lib/docs-system.ts`와 `docs/README.md` 5절이다.
|
|
|
|
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 머리 블록만 본다.
|
|
- **보는 것:** 언어(한국어인가), 문체(「~한다」), 숫자 복사, 기록의 머리 블록, 문서 지도와 루트 README 필수 절. 그리고 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
|
|
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md`의 지워도 되는 파일 표)은 없어도 된다.
|
|
- **짝 백엔드 경로:** `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
|
|
- **도는 곳:** FE-GATE-017은 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다. `tests/unit/documentation-readiness.test.ts`가 이 repo 그대로 한 번, 문서를 복사해 여러 번 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을 만드는 FE-GATE-020의 드릴도 문서를 복사해 돌린다(복사 목록은 `scripts/lib/removal-fixture.ts`). 그래서 살아 있는 문서의 경로 하나, 영어 문단 하나가 merge를 막는다.
|
|
- **돌리는 법:** desktop에서 `scripts/verify.sh script verify:documentation`. 설치가 끝난 worktree라 pnpm이 재설치 대기로 멈추지 않는다.
|
|
- 작업 매뉴얼의 분량·이력 ID·뼈대는 `verify:documentation`이 보지 않는다. `scripts/verify.sh docs`가 본다.
|
|
|
|
## 8. 게이트·검사 스크립트를 더할 때
|
|
|
|
- 새 게이트·명령은 `config/ci/gates.json`에 더하고 workflow는 생성기로 다시 만든다(`check:ci`가 대조한다). 손으로 workflow만 고치지 않는다.
|
|
- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다.
|
|
- 새 package script가 어느 게이트에서도 돌지 않으면 `check:ci:gating`(main 단계 FE-GATE-029)이 실패한다. PR에서는 돌지 않고 main에 push한 뒤 돈다. 예외는 이유와 함께 `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).
|