Merge remote-tracking branch 'origin/main' into fix/r9-living-docs-sync
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s

# Conflicts:
#	AGENTS.md
#	docs/work/reference/decisions.md
This commit is contained in:
DongHyeonka
2026-11-13 04:30:07 +09:00
67 changed files with 1437 additions and 701 deletions
+1 -1
View File
@@ -45,7 +45,7 @@
| 경로를 백틱 밖으로 옮기지 않는다(`docs-writing.md` 4절) | 참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록 | 1105/14-03 |
| `npm run` 금지(`gates.md` 2절) | 제거 드릴을 `npm run`으로 돌려 모든 검사가 `Unknown command` | 1103 README 10.4절 |
| 임시 worktree의 `pnpm verify:documentation`(`delegate.md` 9절) | pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과 무효 | 1105 README 11.5절 |
| FE-GATE-013 desktop 판정(`gates.md` 3절) | ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패. 2026-11-12에 조건부로 merge 판정에서 빼기로 정함 | 1105/12-01, 1105 README 11.1절, 1106 README 1절, D8 |
| FE-GATE-013 실행 환경과 desktop 판정(`gates.md` 3절) | desktop ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패. runner job 컨테이너에는 systemd·bubblewrap이 없어 사전 점검에서 실패(2026-11-08~11 run 56·80·81). 2026-11-12 조건부 판정(D8)과 시스템 컨테이너 경로 | 1105/12-01, 1105 README 11.1절, 1106 README 1절, D8 |
| 대조 허용치 < 여유(`performance.md` 5절) | 허용 1%(약 2 KB) > 남은 여유 1,873 B | 1105/15-02 |
| 예산을 올리는 것은 결정(`performance.md` 5절) | 초기 파일 수 26 → 32, 초기 JS 204,800 → 206,848 B | 1103 README 14.6절 #4, 1105 README 16.2절 D7, 1106 README 16.2절 D9 |
| 기준선은 합친 끝에서 다시 잰다(`delegate.md` 4.2절) | 브랜치마다 맞던 초기 JS 기록이 합친 빌드에서 허용치를 넘음 | 1106 README 16.3절 |
+1 -1
View File
@@ -86,7 +86,7 @@
1. 그 라운드의 새 High 0.
2. 그 라운드의 새 P1 0.
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). desktop의 FE-GATE-013은 같은 절의 두 조건(실패가 호스트 제약 하나뿐, 뒤 명령 모두 rc=0)을 채우면 빼고 세고, 같은 절 문구로 보고한다.
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). FE-GATE-013은 시스템 컨테이너 안에서 돌아 같이 센다. 컨테이너를 띄울 수 없는 호스트에서만 같은 절의 두 조건으로 빼고 그 문구로 보고한다.
- 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 [reference/decisions.md](reference/decisions.md) 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다.
- 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」).
+1 -1
View File
@@ -39,7 +39,7 @@
- 생성 명령으로 시작했고, 템플릿 소유 파일을 생성 명령 밖에서 고치지 않았다(고쳤으면 큼으로 올려 결정을 받았다).
- 동작마다 테스트가 있고 RED → GREEN을 봤다.
- 초기 JS 기록이 빌드와 맞는다(`test:unit` 안의 대조).
- `scripts/verify.sh merge`가 통과했고(FE-GATE-013은 [reference/gates.md](reference/gates.md) 3절 조건을 채워 빼고 그 문구로 적었다) FE-GATE-026도 통과했다.
- `scripts/verify.sh merge`가 통과했고 FE-GATE-026도 통과했다(컨테이너를 띄울 수 없는 호스트의 FE-GATE-013은 [reference/gates.md](reference/gates.md) 3절 조건과 문구로 적었다).
- 이 기능을 지운 사본이 통과한다(`test:sample-removal -- --feature=<id>`).
- 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면 `CHANGELOG.md` 미출시 절에 적었다.
+2 -2
View File
@@ -35,7 +35,7 @@
- **공유 checkout을 건드리지 않는다.** desktop의 그 checkout은 다른 세션도 쓴다. 브랜치를 바꾸지 않고, `stash`를 건드리지 않는다. 어쩔 수 없이 그 checkout에서 돌려야 하면 잠금 안에서 바꾸고 끝나면 처음 브랜치로 되돌린 뒤 `git status`가 비었는지 본다.
- **잠금.** 무거운 실행은 하나씩 돈다. 백엔드 세션도 같은 desktop에서 같은 잠금을 쓴다. 다른 세션이 잠금을 쥐고 있으면 기다리고, 기다리는 동안 다른 일을 한다. 오래 걸리는 단계는 background로 띄우고 끝나기를 한 번 기다린다(짧은 간격으로 확인하지 않는다).
- **CI env.** `scripts/verify.sh`는 게이트를 workflow와 같은 꼴의 env로 돌린다: `CI=true`, `VITE_COMMIT_SHA`(그 worktree의 HEAD), `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`(`@sha256:` digest 꼴). `CI=true`를 빼면 CI에서만 나는 실패를 놓친다([reference/gates.md](reference/gates.md) 4절).
- **desktop의 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `test:system`의 provider 테스트가 호스트 원인으로 실패한다. 시스템 설정은 바꾸지 않는다. `scripts/verify.sh parts FE-GATE-013`으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 둘 다 맞고 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다. 게이트 충족은 조건을 갖춘 runner에서 통과한 것으로만 센다([reference/gates.md](reference/gates.md) 3절).
- **FE-GATE-013.** `scripts/verify.sh`가 이 게이트를 시스템 컨테이너(`scripts/run-in-system-container.sh`) 안에서 돌린다. 호스트 Docker가 privileged 컨테이너를 띄운다. 시스템 설정은 바꾸지 않는다. 컨테이너를 띄울 수 없는 호스트에서만 `VERIFY_HOST_ENVIRONMENT=off scripts/verify.sh parts FE-GATE-013`으로 호스트에서 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제(user namespace) 하나뿐이고 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다. 게이트 충족은 조건을 갖춘 실행 환경에서 통과한 것으로만 센다([reference/gates.md](reference/gates.md) 3절).
- **노트북에서 꼭 돌려야 하면** 노트북 checkout이 아니라 깨끗한 복제본(`git clone --no-hardlinks`, 그 뒤 `corepack pnpm install --frozen-lockfile --offline`)에서 돌리고 vite가 들어가는 게이트에 `CHOKIDAR_USEPOLLING=1`을 준다. 노트북 checkout의 `.claude/worktrees/`가 `test:system`의 repo 복사와 vite 파일 감시를 깨뜨린다.
- **desktop에서 파일을 만드는 명령**(생성 명령, 기준선 다시 쓰기)은 `--apply-back`으로 결과를 노트북 작업 트리에 받는다: `scripts/verify.sh script create:feature --apply-back -- <id>`, `scripts/verify.sh exec --apply-back -- <명령…>`. 바뀐 파일은 언제나 로그 폴더의 `changes.patch`에도 남는다.
- **한 테스트 파일**도 desktop에서: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`.
@@ -67,7 +67,7 @@
## 5. 완료 기준
- 돌린 단계마다 rc, 시간, 부하, 트리 해시, 로그 경로가 기록에 있다. 숫자는 로그에서 옮겼다.
- merge 가능을 말했으면 merge 단계 전부가 `CI=true` env로 통과했고(FE-GATE-013은 4.1절대로 적었다), 트리 해시가 PR head 트리와 같다.
- merge 가능을 말했으면 merge 단계 전부가 `CI=true` env로 통과했고, 트리 해시가 PR head 트리와 같다.
- desktop 공유 checkout의 브랜치와 `git status`가 실행 전과 같고, 만든 worktree가 지워졌다.
## 6. 하지 말 것
+1
View File
@@ -70,6 +70,7 @@
| round9 R9-D10 예산과 advisory | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). D1을 먼저 정한다: zod·react-router 갱신이 지금 초기 JS 예산 안에 들어가므로 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다. 버린 안: 예산만 먼저 내림 | 같음, 1106/15-01, 1103/13-03 |
| round9 R9-D11 `@a11y` 두 번 실행 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 그대로 둔다. 게이트마다 증거를 새로 만드는 계약이다. 결함 아님으로 닫는다. 버린 안: FE-GATE-009가 FE-GATE-008 결과를 쓰기 | 같음, 1112/03-10 |
| round9 R9-D12 CSS·라우트 lazy 합 예산 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 지금 값을 기록만 하고 예산은 두지 않는다. 다시 볼 때: 첫 공개 기능 라우트 lab. 버린 안: 예산 신설 | 같음, 1101/15-03 |
| 결정 p 선택 runtime 제거 드릴을 main 단계로 | 2026-11-12 | FE-GATE-020의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)을 새 게이트 FE-GATE-030으로 떼어 main 단계(`main_gate`)에서 돌린다. 기능 드릴(샘플 제거, scaffold)은 merge에 남는다. 이유: runner PR 1회 약 30분 가운데 7분쯤이고, worker를 늘리지 않고 merge 25분 목표에 닿는 길이 이것뿐이었다. 대가: 그 셋의 회귀를 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. 재검토: runner가 늘거나 드릴이 빨라져 merge에 다시 넣어도 25분 안이면 되돌린다 | 소유자 결정 p(2026-11-12, design-docs `template-program/README.md` 5절, W2-FE의 O1 권하는 안 채택) |
| 구조·기술 결정 기록 | 2026-07-26~ | `VD-01`~(빈 번호 있음) | `docs/adr/` |
## 3. 결정 대기 쓰는 법
+4 -2
View File
@@ -69,10 +69,12 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
**가끔 떨어지는 게이트.** 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다([testing.md](testing.md) 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
**desktop에서 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이 제한을 이름으로 대며 실패한다. merge 판정에서는 이 실패를 호스트 원인으로 보고 뺀다(소유자 결정 2026-11-11에 따라 2026-11-12에 정함, [decisions.md](decisions.md) 2.2절). 뺄 수 있는 조건은 둘이고, 하나라도 어기면 merge 가능이 아니다.
**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). 컨테이너 안에서 통과하면 다른 게이트처럼 통과로 센다(소유자 결정 2026-11-11: 조건이 되는 실행 환경을 찾아 초록으로). 컨테이너 안은 root라 「비특권 runner에서 bwrap user namespace」 조건 자체는 증명하지 않는다. 실패하면 `scripts/verify.sh parts FE-GATE-013`으로 명령마다 보고, `SYSTEM_CONTAINER_KEEP=1`이면 컨테이너를 남긴다. 호스트 시스템 설정은 바꾸지 않는다.
**컨테이너를 띄울 수 없는 호스트의 FE-GATE-013.** Docker가 없거나 privileged 컨테이너를 막는 호스트에서는 래퍼가 종료 코드 3으로 끝난다. 그런 호스트는 `VERIFY_HOST_ENVIRONMENT=off`를 주어 게이트를 호스트에서 돌리고 아래로 판정한다. desktop ssh 셸에서는 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이 제한을 이름으로 대며 실패한다. merge 판정에서는 이 실패를 호스트 원인으로 보고 뺀다(소유자 결정 2026-11-11에 따라 2026-11-12에 정함, [decisions.md](decisions.md) 2.2절). 뺄 수 있는 조건은 둘이고, 하나라도 어기면 merge 가능이 아니다.
1. FE-GATE-013의 실패가 사전 점검의 user namespace 제한 하나뿐이다.
2. `scripts/verify.sh parts FE-GATE-013`으로 돌린 뒤 명령(`config/ci/gates.json`의 FE-GATE-013 `commandIds`에서 `test-system` 다음 것)이 모두 rc=0이다.
2. `VERIFY_HOST_ENVIRONMENT=off scripts/verify.sh parts FE-GATE-013`으로 돌린 뒤 명령(`config/ci/gates.json`의 FE-GATE-013 `commandIds`에서 `test-system` 다음 것)이 모두 rc=0이다.
보고 문구는 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0)」이다. 이것은 merge 판정이지 게이트 충족이 아니다. FE-GATE-013의 「충족」은 그 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 적는다. 시스템 설정은 바꾸지 않는다.
+2 -2
View File
@@ -37,7 +37,7 @@
| 현재 계약 | `docs/README.md` 1절 지도의 「현재 계약」·「운영」 폴더 |
| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 |
| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md`, `docs/manual/reference/create-feature.md` |
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md`의 지워도 되는 파일 표, FE-GATE-020 |
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md`의 지워도 되는 파일 표, FE-GATE-020, FE-GATE-030 |
| 짝 백엔드와 맞춘 계약 | `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절, `config/contracts/backend-contract-pin.json` |
결함으로 보지 않는 것: 소비자 없는 코드와 빈 레지스트리, 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk `results`), 서버 메모리 상태·다중 인스턴스 경쟁(탭 사이 경쟁은 본다), 인터페이스가 많다·kernel이 크다는 사실만으로(가이드 35.2절 끝 문단).
@@ -108,7 +108,7 @@
| 24 | 네이밍 / 의미 성숙도 | 오류 code·상태 이름의 뜻 | |
| 25 | 조직 확장성 | 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용 | |
| 26 | Ownership 성숙도 | 규칙 `comment`의 담당·재검토 조건, 두 repo 사이 몫 | |
| 27 | 삭제 가능성 | 기능·recipe·선택 runtime 제거([structure.md](structure.md) 12절) | FE-GATE-020 |
| 27 | 삭제 가능성 | 기능·recipe·선택 runtime 제거([structure.md](structure.md) 12절) | FE-GATE-020, FE-GATE-030 |
| 28 | 회복 가능성 | 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback | FE-GATE-025 |
## 6. 다시 판정할 때
+2 -2
View File
@@ -114,7 +114,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
## 12. 제거 가능성
지울 수 있는 단위는 merge 게이트 FE-GATE-020의 드릴이 지킨다. 드릴 목록은 `config/ci/gates.json`의 FE-GATE-020 `commandIds`다.
지울 수 있는 단위는 드릴이 지킨다. 기능 드릴(샘플 제거, 생성 기능의 scaffold·제거)은 merge 게이트 FE-GATE-020, 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)은 main 단계 FE-GATE-030이다(소유자 결정 2026-11-12). 드릴 목록은 `config/ci/gates.json`의 두 게이트 `commandIds`다. 선택 runtime을 바꾼 PR은 merge에서 FE-GATE-030이 돌지 않으니 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다.
- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 목록(`scripts/lib/removal-fixture.ts`, 이 목록 하나만 쓴다)이 바뀐 구조를 아는지 본다. 그 목록에 `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 일이 있다(결함 패턴 G11).
- 드릴은 오래 걸린다(FE-GATE-020은 14~21분). desktop에서 잠금 아래 돌린다.
- 드릴은 오래 걸린다(desktop 2026-11-13 실측: FE-GATE-020과 FE-GATE-030 합쳐 약 10분 30초). desktop에서 잠금 아래 돌린다.
+1 -1
View File
@@ -105,4 +105,4 @@
- 빠른 계층(`tests/unit`)에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이면 전체가 느려진다(결함 패턴 T8).
- merge 단계가 같은 파일을 두 번 돌리지 않는지 본다.
- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 14~21분(2026-11-06·08 desktop 실측 822~1,245초)이다. job 상한(45분)과의 여유를 본다.
- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 선택 runtime 드릴 셋을 FE-GATE-030(main 단계)으로 넘기기 전 desktop 630초, runner 13분 13초였다(2026-11-13, PR #19). job 상한(45분)과의 여유를 본다.