From f6e2560e4dd200eb5f36ed283de67d1a3f4944b1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 19:52:09 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20FE-GATE-013=EC=9D=B4=20=EC=8B=9C?= =?UTF-8?q?=EC=8A=A4=ED=85=9C=20=EC=BB=A8=ED=85=8C=EC=9D=B4=EB=84=88?= =?UTF-8?q?=EC=97=90=EC=84=9C=20=EB=8F=84=EB=8A=94=20=EA=B2=83=EC=9D=84=20?= =?UTF-8?q?=EC=A7=80=EC=B9=A8=EA=B3=BC=20=EC=9A=B4=EC=98=81=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 작업 매뉴얼·루트 지침·스킬이 「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개 통과. --- .claude/skills/desktop-gates/SKILL.md | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 29 +++++++++++++++++++++++++++ README.md | 2 +- docs/operations/ci-quality-gates.md | 15 ++++++++++++++ docs/testing/taxonomy.md | 2 +- docs/work/evidence.md | 2 +- docs/work/improve.md | 2 +- docs/work/new-feature.md | 2 +- docs/work/operate.md | 4 ++-- docs/work/reference/decisions.md | 4 ++-- docs/work/reference/gates.md | 2 +- 12 files changed, 56 insertions(+), 12 deletions(-) diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md index 9a9ca150..ecec0e92 100644 --- a/.claude/skills/desktop-gates/SKILL.md +++ b/.claude/skills/desktop-gates/SKILL.md @@ -19,6 +19,6 @@ description: 이 프론트 repo에서 pnpm·게이트·테스트·빌드·브라 - 먼저 무엇을 돌릴지만 보려면 `--dry-run`. 4. 스크립트가 하는 일: 지금 트리를 패치로 보내고, desktop 공유 checkout에서 새 worktree를 만들어 같은 트리인지 해시로 보고, 깨끗한 커밋 하나로 만들어 오프라인 설치 뒤 `flock /tmp/claude-gates/heavy.lock` 아래 CI env(`CI=true` 등)로 돌린다. 공유 checkout의 브랜치와 stash는 건드리지 않는다. push하지 않는다. 5. 결과를 읽는다: desktop `/tmp/claude-gates/<작업 이름>/summary.txt`(첫 줄이 트리 해시), 게이트별 로그, `gate-artifacts/`, `status-after.txt`(비어 있어야 한다). -6. FE-GATE-013은 desktop에서 호스트 제약(user namespace)으로 실패한다. "호스트 제약 실패"로 적고 `parts`로 뒤 명령 결과를 함께 적는다. +6. FE-GATE-013은 `scripts/verify.sh`가 시스템 컨테이너(`scripts/run-in-system-container.sh`) 안에서 돌린다. 다른 게이트와 같이 rc로 적는다. 실패하면 `parts`로 명령마다 본다. 7. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 8. 보고에는 단계·게이트, rc, 시간, 핵심 숫자, 직전 부하, 트리 해시, 로그 경로를 적는다(`operate.md` 8절 표). diff --git a/AGENTS.md b/AGENTS.md index b714275f..29125b76 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ ## 검증 - 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다. -- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. desktop의 FE-GATE-013은 `docs/work/reference/gates.md` 3절 문구로 적는다. +- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. FE-GATE-013은 `scripts/run-in-system-container.sh` 안에서 돈다(`docs/work/reference/gates.md` 3절). - 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북). ## 일하는 방식 diff --git a/CHANGELOG.md b/CHANGELOG.md index ad0075ef..a233cd47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,35 @@ - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +## 미출시 — `db6a6eb6` → CI를 runner에서 초록으로, merge 시간 줄이기 + +Gitea runner에서 merge 단계를 초록으로 만들고, worker를 늘리지 않고 같은 시험을 두 번 도는 곳과 job마다 같은 것을 내려받는 곳을 없앤다. 제품 코드는 바뀌지 않는다. + +### 먼저 할 일 + +- FE-GATE-013은 `scripts/run-in-system-container.sh`가 띄우는 privileged systemd 컨테이너 안에서 돈다. 자기 runner가 job에서 Docker로 privileged 컨테이너를 띄울 수 없으면 이 게이트가 실패한다. 그런 runner면 `docs/operations/ci-quality-gates.md` FE-GATE-013 절의 호스트 조건을 갖춘 runner에서 돌린다. +- merge / browser tests job이 Playwright 공식 이미지(`config/ci/gates.json`의 `browser-install.image`, digest 고정)에서 돈다. `@playwright/test`를 올릴 때 이 digest도 같은 버전으로 바꾼다(`tests/unit/ci-browser-image.test.ts`가 막는다). +- devDependencies에서 `dependency-cruiser`가 빠진다. 그 CLI를 따로 쓰고 있었으면 다시 더한다. + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +| --- | --- | --- | --- | +| [계약] | 게이트 필드 `hostEnvironment`(`"system-container"`)를 더한다. 생성기와 `scripts/verify.sh`가 그 게이트를 `scripts/run-in-system-container.sh`로 감싸고, 실행 검사는 계약이 정한 접두어로 돈 줄만 센다. FE-GATE-013에 준다 | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `scripts/verify.sh`, `scripts/run-in-system-container.sh`, `config/ci/system-container.Dockerfile` | `1d3eb901` | +| [계약] | `browser-install` 단계에 `image`(Playwright 레지스트리 noble 태그 + digest)를 더한다. 생성기는 그 job의 container와 job env `CI_RUNNER_IMAGE`로 그리고, 단계는 글꼴만 설치한다. gate-sequence job에만 둔다 | 같은 파일, `tests/unit/ci-browser-image.test.ts` | `92abfd20` | + +### 그 밖의 변경 + +| 변경 | 영향 경로 | 커밋 | +| --- | --- | --- | +| `fixture-node-modules` 시험이 「CI 아님」 설치를 `CI=false`로 흉내 낸다. runner의 벤더 변수(`GITEA_ACTIONS` 등) 때문에 FE-GATE-005·020이 runner에서만 실패했다 | `tests/unit/fixture-node-modules.test.ts` | `ddfcb6f6` | +| `scripts/verify.sh parts`가 게이트 명령의 `args`를 넘긴다 | `scripts/verify.sh`, `scripts/tests/test_verify.py` | `79a225b6` | +| `check:browser-file-storage-boundaries`가 fixture마다 eslint를 띄우지 않고 ESLint API 한 번으로 같은 판정을 한다 | `scripts/check-browser-file-storage-boundaries.ts` | `0d8e4f5a` | +| FE-GATE-020 드릴이 한 복사본에서 같은 시험 파일을 두 번 돌지 않는다: scaffold 드릴은 `test:coverage`가 도는 plain suite를 빼고, feature-removal은 `test:all` 대신 `test:coverage` 밖에 남는 suite만 더 돈다 | `scripts/lib/feature-scaffold-drill.ts`, `scripts/test-sample-removal.ts`, `tests/unit/removal-drill-test-paths.test.ts` | `b4210753` | +| 쓰지 않는 `dependency-cruiser`를 지우고 의존성 기준선을 다시 승인한다 | `package.json`, `pnpm-lock.yaml`, `config/security/dependency-baseline*.json` | `66138440` | +| vitest setup이 DOM이 있는 시험 파일에만 Testing Library를 불러온다 | `tests/setup.ts` | `1f09c1cc` | +| tests/system의 provider 기준 사본이 `.claude/` 아래 추적 파일을 복사한다(`.claude/worktrees`만 뺀다). 이 결함으로 FE-GATE-013의 provider 시험이 공급망 생성에서 멈췄다 | `tests/system/ci-runner/ci-artifact-contract.test.ts` | `f90ffb6c` | + ## 미출시 — `8327e221` → 하네스와 작업 매뉴얼 2026-11-07 소유자가 정한 Claude Code 작업 환경(하네스)을 백엔드 템플릿과 같은 방식으로 둔다(design-docs `harness/01-harness-design.md` 13절). 루트 지침 `AGENTS.md`(정본)와 `CLAUDE.md`(가져오기), `.claude/`(규칙·스킬·서브에이전트·권한·훅), 작업 매뉴얼 `docs/work/`, 검증 진입점 `scripts/verify.sh`, 장부 `docs/ledger/`다. 제품 코드와 게이트 동작은 바뀌지 않는다. diff --git a/README.md b/README.md index 28124130..c79142ab 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ done ``` - FE-GATE-008과 FE-GATE-009는 Playwright 브라우저가 필요하다. FE-GATE-012는 먼저 앱을 빌드한다. -- FE-GATE-013은 bubblewrap이 비특권 user·network namespace를 만들 수 있는 Linux 호스트가 필요하다. Ubuntu 23.10 이후는 기본으로 거절한다. 첫 단계가 그렇게 알려 주고, 고치는 법은 `docs/operations/ci-quality-gates.md`에 있다. +- FE-GATE-013은 systemd와 bubblewrap이 있는 호스트가 필요해 `scripts/run-in-system-container.sh`가 띄우는 privileged systemd 컨테이너 안에서 돈다. Docker가 그런 컨테이너를 띄울 수 있어야 한다. 위 반복문에서는 `scripts/run-in-system-container.sh corepack pnpm ci:gate -- FE-GATE-013`으로 돌린다. 자세한 조건은 `docs/operations/ci-quality-gates.md`에 있다. - `config/ci/product-gates.json`에 적은 제품 검사(`PRODUCT-GATE-NNN`)는 workflow의 `product_merge_gate` job에서 돌고, release 단계가 그 job을 기다린다. workflow처럼 돌리려면 workflow의 환경을 먼저 준다. `CI=true`이면 실행기와 release 빌드가 CI 빌드 식별값을 요구한다. 테스트가 사본으로 만드는 빌드(fixture 빌드, 시각 골든 빌드, 브라우저 시험의 dev 서버)는 이 값과 상관없이 로컬 빌드로 돈다(`scripts/lib/build-environment.ts`의 `localBuildEnvironment`). 깨끗한 clone에서 돌린다. `ci:gate`는 게이트의 첫 실패 명령에서 멈춘다. diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 2dcc4a8a..241fe720 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -208,6 +208,21 @@ sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로 출력한다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 소유자가 고른다. 호스트를 바꾸는 설정 파일과 명령은 runner를 만드는 쪽의 인프라 repo가 갖는다. +**이 템플릿이 FE-GATE-013을 돌리는 곳.** 호스트 설정을 바꾸지 않고, 게이트를 +일회용 privileged systemd 컨테이너 안에서 돌린다. 계약의 FE-GATE-013 +`hostEnvironment: "system-container"`를 보고 생성 workflow와 +`scripts/verify.sh`가 `scripts/run-in-system-container.sh`로 게이트를 감싼다. +래퍼는 `config/ci/system-container.Dockerfile`(Ubuntu 24.04, systemd PID 1, +root linger, bubblewrap)로 이미지를 만들고, 작업 트리·git 이력·호출한 쪽의 +node와 corepack을 복사해 root로 돌린 뒤 `artifacts/`를 되가져온다. CI에서는 +runner의 Docker proxy가 안쪽 dind daemon에 컨테이너를 띄운다. + +- root는 호스트의 user namespace 제한을 받지 않는다. 그래서 이 길은 「비특권 + runner에서 bwrap userns」 조건 자체를 증명하지 않는다. 그 조건이 필요한 + release 단계 provider job은 아직 job 컨테이너에서 돈다. +- runner가 privileged 컨테이너를 막는 설정(rootless dind 등)으로 바뀌면 이 + 길이 깨진다. 그때는 위 조건을 갖춘 전용 runner(VM 등)로 옮긴다. + 각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에 실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`, `pids.max=64`, `cpu.max="100000 100000"`을 확인한다. 내부 process에는 core 0, diff --git a/docs/testing/taxonomy.md b/docs/testing/taxonomy.md index 8349cc95..5a61bea3 100644 --- a/docs/testing/taxonomy.md +++ b/docs/testing/taxonomy.md @@ -12,7 +12,7 @@ script로 낮추지 않는다. | capability contract | `pnpm test:contract` | 재사용하는 capability의 소비자 계약 | `artifacts/tests/contract.xml` | | component | `pnpm test:component` | React·hook·UI 동작 | `artifacts/tests/component.xml` | | integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, 조립된 browser-runtime 경계, 자식 프로세스·파일 시스템·IPC 통합 | `artifacts/tests/integration.xml` | -| system / CI runner | `pnpm test:system` | systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제를 갖춘 호환 Linux host. 그 host에서 bubblewrap이 권한 없는 user namespace와 network namespace를 만들 수 있어야 한다 | `artifacts/tests/system.xml` | +| system / CI runner | `pnpm test:system` | systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제를 갖춘 호환 Linux host. 그 host에서 bubblewrap이 권한 없는 user namespace와 network namespace를 만들 수 있어야 한다. CI와 `scripts/verify.sh`는 FE-GATE-013을 `scripts/run-in-system-container.sh`가 띄우는 컨테이너 안에서 돌린다 | `artifacts/tests/system.xml` | | end-to-end | `pnpm test:e2e` | 버전을 고정한 브라우저 엔진 | `artifacts/tests/e2e/` | | accessibility | `pnpm test:a11y` | 버전을 고정한 브라우저 엔진 | `artifacts/tests/a11y.json` | diff --git a/docs/work/evidence.md b/docs/work/evidence.md index d0b60e66..989f8302 100644 --- a/docs/work/evidence.md +++ b/docs/work/evidence.md @@ -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건 실패 | 1105/12-01, 1105 README 11.1절, 1106 README 1절 | +| FE-GATE-013을 시스템 컨테이너에서(`gates.md` 3절) | desktop ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패. runner job 컨테이너에는 systemd·bubblewrap이 없어 사전 점검에서 실패(2026-11-08~11 run 56·80·81) | 1105/12-01, 1105 README 11.1절, 1106 README 1절 | | 대조 허용치 < 여유(`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절 | diff --git a/docs/work/improve.md b/docs/work/improve.md index 3ea01600..4a6b408f 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -86,7 +86,7 @@ 1. 그 라운드의 새 High 0. 2. 그 라운드의 새 P1 0. -3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). FE-GATE-013을 어떻게 셀지는 결정 대기라, 그동안은 같은 절의 문구로 보고하고 멈출지는 소유자가 정한다. +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 「각자 유지」). diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 607d12b9..94e51db7 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -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도 통과했다. - 이 기능을 지운 사본이 통과한다(`test:sample-removal -- --feature=`). - 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면 `CHANGELOG.md` 미출시 절에 적었다. diff --git a/docs/work/operate.md b/docs/work/operate.md index d83221c2..6234457d 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -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`으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([reference/decisions.md](reference/decisions.md)). +- **FE-GATE-013.** `scripts/verify.sh`가 이 게이트를 시스템 컨테이너(`scripts/run-in-system-container.sh`) 안에서 돌린다. 호스트 Docker가 privileged 컨테이너를 띄운다. 호스트 시스템 설정은 바꾸지 않는다. 실패하면 `scripts/verify.sh parts FE-GATE-013`으로 명령마다 끝까지 돌려 본다([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 -- `, `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. 하지 말 것 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 6066a1c0..e4c3c573 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -43,6 +43,7 @@ | O-18 | 2026-11-07 | Agent 금지를 두지 않는다. 결과만 받는 일(검색, 구조 리뷰, 실행 검증, 단순화 제안)은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션이다 | 같은 문서 13절 Q5 | `delegate.md` 4.3절 | | O-19 | 2026-11-07 | 루트 `AGENTS.md`·`CLAUDE.md`(와 `.claude/`, `docs/work/`)는 템플릿 계약이다. 복사한 프로젝트가 받는다. 지워도 되는 문서 목록에 넣지 않는다 | 같은 문서 13절 Q4 | `structure.md` 4절, `operate.md` 4.4절 | | O-20 | 2026-11-08 | 프론트 편집 훅은 노트북에서 표준 라이브러리 정적 검사만 한다. 포맷·린트·타입은 desktop `scripts/verify.sh`에서 돈다. 설계 13절 Q6(편집 훅에서 한 파일 포맷·린트)과 다른 점은 프론트 린터가 pnpm·`node_modules`를 써서 "pnpm은 desktop에서만"(O-10)과 부딪치기 때문이다 | 하네스 적용 brief(백엔드 총괄, 2026-11-08) | `scripts/hooks/README.md` | +| O-21 | 2026-11-11 | FE-GATE-013은 조건이 되는 실행 환경을 찾아 초록으로 만든다(권하는 안으로 반영). 이 repo는 일회용 privileged systemd 컨테이너 안에서 돌리고 멈춤 기준에 그대로 센다. 결정 대기 D8을 닫는다 | design-docs `template-program/README.md` 5절 e | `gates.md` 3절 | ### 2.2 기술 결정 (리뷰 라운드) @@ -68,7 +69,7 @@ | 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 | | 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 | | 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 프론트 소유자 + reviewer 등 | -| 결정 전까지 | 임시 처리와 보고 방법(예: `gates.md` 3절의 FE-GATE-013 기록 방법) | +| 결정 전까지 | 임시 처리와 보고 방법(예: 결정 전에 쓸 보고 문구와 그 문구를 둔 곳) | | 재검토 조건 | 어떤 규모·버전·계약 변화가 결론을 바꾸나 | 결정 표에 들어갈 것: 고른 것과 이유(무엇을 지키는지로), 버린 대안과 버린 이유, 확인한 사실 / 기록된 의도 / 추론의 구분, 재검토 조건. @@ -82,7 +83,6 @@ | D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 | | D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 | | D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 | -| D8 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지(호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족) | 1105/12-01 | 소유자 | 같음 | | D11 | 생성 기능 설치 상태의 브라우저 merge 게이트 | 1105/16-03 | 템플릿 담당 | 같음 | | D6(1105) | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. `ci:gate` 두 실행은 아직 같은 `dist`·`artifacts/`를 쓴다 | 1105/12-04 | 프론트 소유자 | 1105 README 7절, 1106 README 2.3절 | diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index d92af0f2..e9f6be4e 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -68,7 +68,7 @@ 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`)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([decisions.md](decisions.md)). 결정 전까지 merge 판정 보고는 이 문구로 쓴다: 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약 실패(뒤 명령 결과 첨부). merge 가능 여부는 소유자가 정한다(FE-GATE-013을 멈춤 기준에서 어떻게 셀지의 결정 대기, [decisions.md](decisions.md) 3.1절)」. 뒤 명령 결과는 `scripts/verify.sh parts FE-GATE-013`으로 낸다. 시스템 설정은 바꾸지 않는다. +**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에서만 나는 실패