From bdda84f8440d336e0258b3776ae488850335c3bd Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 10:49:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20desktop=20FE-GATE-013=EC=9D=84=20?= =?UTF-8?q?=EC=A1=B0=EA=B1=B4=EB=B6=80=EB=A1=9C=20merge=20=ED=8C=90?= =?UTF-8?q?=EC=A0=95=EC=97=90=EC=84=9C=20=EB=B9=BC=EA=B8=B0=EB=A1=9C=20?= =?UTF-8?q?=EC=A0=95=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: FE-GATE-013을 멈춤 기준에서 어떻게 셀지가 결정 대기라, desktop에서 merge 판정을 하면 매번 「merge 가능 여부는 소유자가 정한다」로 끝났다. desktop의 ssh 셸은 비특권 user namespace를 막아 test:system 사전 점검이 호스트 원인으로 실패한다. 고른 방법: 소유자 결정(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정했다(2026-11-12). - merge 판정에서 빼는 조건 둘: 실패가 사전 점검의 user namespace 제한 하나뿐이고, `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0. - 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다. - decisions.md: 3.1절(열린 결정)에서 빼고 2.2절에 결정·버린 안·재검토 조건을 적었다. evidence.md 행에 결정 번호를 더했다. - gates.md 3절의 보고 문구, improve.md 멈춤 조건 3, operate.md 4.1절, new-feature.md 완료 기준, desktop-gates 스킬 6단계를 새 규칙으로 고쳤다. 버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기. 그 runner가 아직 없어 모든 PR의 merge 판정이 막힌다. 위험: desktop에서 test:system의 provider 테스트는 여전히 돌지 않는다. 그 몫의 결함은 runner가 FE-GATE-013을 돌 때까지 merge 판정에서 안 보인다. 뒤 명령 목록을 옮겨 적지 않고 gates.json `commandIds`를 가리킨다. 검증: python3 scripts/check-work-docs.py OK(지난 ID 줄 0), python3 -m unittest discover -s scripts/tests 71개 통과. 문서 검사는 desktop에서 돌린다. --- .claude/skills/desktop-gates/SKILL.md | 2 +- docs/work/evidence.md | 2 +- docs/work/improve.md | 2 +- docs/work/new-feature.md | 2 +- docs/work/operate.md | 2 +- docs/work/reference/decisions.md | 4 ++-- docs/work/reference/gates.md | 7 ++++++- 7 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md index 34359fc9..f2f74502 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은 desktop에서 호스트 제약(user namespace)으로 실패한다. `parts`로 뒤 명령 결과를 함께 적는다. 실패가 그 제약 하나뿐이고 뒤 명령이 모두 rc=0일 때만 merge 판정에서 뺀다(`docs/work/reference/gates.md` 3절). 7. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 8. 보고에는 단계·게이트, rc, 시간, 핵심 숫자, 직전 부하, 트리 해시, 로그 경로를 적는다(`docs/work/operate.md` 8절 표). diff --git a/docs/work/evidence.md b/docs/work/evidence.md index d0b60e66..8fc68a4f 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 desktop 판정(`gates.md` 3절) | ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패. 2026-11-12에 조건부로 merge 판정에서 빼기로 정함 | 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절 | diff --git a/docs/work/improve.md b/docs/work/improve.md index 3ea01600..def94d42 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절 방법). desktop의 FE-GATE-013은 같은 절의 두 조건(실패가 호스트 제약 하나뿐, 뒤 명령 모두 rc=0)을 채우면 빼고 세고, 같은 절 문구로 보고한다. - 채워도 바로 끝내지 않는다. 그 라운드의 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..3d0124ba 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-013은 [reference/gates.md](reference/gates.md) 3절 조건을 채워 빼고 그 문구로 적었다) FE-GATE-026도 통과했다. - 이 기능을 지운 사본이 통과한다(`test:sample-removal -- --feature=`). - 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면 `CHANGELOG.md` 미출시 절에 적었다. diff --git a/docs/work/operate.md b/docs/work/operate.md index d83221c2..7c2aca28 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)). +- **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절). - **노트북에서 꼭 돌려야 하면** 노트북 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 <파일>`. diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 6066a1c0..80e9a1c2 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -56,6 +56,7 @@ | WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다 | 1103 README 14.7절 | | 1105 결정 D7 | 2026-11-05 | 초기 JS 예산을 204,800 B에서 206,848 B로 올린다 | 1105 README 16.2절 | | 1106 결정 D9·D10 | 2026-11-06 | 초기 JS 예산 206,848 B를 그대로 두고 근거·되돌림 규칙을 `docs/operations/performance-evidence.md`에 둔다(D9). 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝나도 훅이 결과 불명과 키를 지킨다. 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(D10과 보완 둘, 판정 `src/contracts/errors.ts` `isRefusedOnEveryAttempt`) | 1106 README 16.2절 | +| 결정 D8 FE-GATE-013 판정 | 2026-11-12 | desktop에서 FE-GATE-013의 실패가 사전 점검의 user namespace 제한(bwrap) 하나뿐이고 `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0이면, merge 판정에서 그 실패를 호스트 원인으로 빼고 센다. 게이트 「충족」은 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 센다. 버린 안: runner에서 통과할 때까지 merge 판정을 미충족으로 두기(그 runner가 아직 없어 모든 PR의 merge 판정이 막힌다). 재검토: 조건을 갖춘 runner가 merge 단계를 돌게 되면 desktop 예외가 아직 필요한지 다시 본다. 판정 방법은 `gates.md` 3절 | 소유자 결정 e(2026-11-11, 「그 조건이 되는 실행 환경을 찾아 초록으로」)에 따라 총괄이 권하는 안으로 정함(2026-11-12, repo 밖). 관련 발견 1105/12-01 | | 구조·기술 결정 기록 | 2026-07-26~ | `VD-01`~(빈 번호 있음) | `docs/adr/` | ## 3. 결정 대기 쓰는 법 @@ -75,14 +76,13 @@ ### 3.1 지금 열린 결정 대기 -2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다. +2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다. D8은 2026-11-12에 정해 2.2절로 옮겼다. | 번호 | 결정 | 관련 | 결정할 사람 | 출처 | | --- | --- | --- | --- | --- | | 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..1db8d0ef 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -68,7 +68,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`)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([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`으로 낸다. 시스템 설정은 바꾸지 않는다. +**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 가능이 아니다. + +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이다. + +보고 문구는 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0)」이다. 이것은 merge 판정이지 게이트 충족이 아니다. FE-GATE-013의 「충족」은 그 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 적는다. 시스템 설정은 바꾸지 않는다. ## 4. CI env에서만 나는 실패