From a593feb2525761262d2e0ca3b5c80c6a386736d8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 11:01:39 +0900 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=EC=9E=90=EC=8B=9D=20?= =?UTF-8?q?=ED=94=84=EB=A1=9C=EC=84=B8=EC=8A=A4=20=EC=8B=9C=ED=97=98=20tim?= =?UTF-8?q?eout=EA=B3=BC=20=ED=9D=94=EB=93=A4=EB=A6=AC=EB=8D=98=20?= =?UTF-8?q?=EC=8B=9C=ED=97=98=20=EB=91=98=EC=9D=98=20=EA=B3=A0=EC=B9=A8?= =?UTF-8?q?=EC=9D=84=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 정리 단계 절에 이 브랜치의 범위를 넣었다. 먼저 할 일 17을 더했다: 기본 timeout인 Vitest 시험이 자식 프로세스를 띄우면 실패하니, 다운스트림은 자기 시험에 childProcessTimeout(<잰 ms>)을 준다. 옮긴 뒤 확인 1에는 test:integration과 17단계를 더했다. 계약 표 한 줄과, 그 밖의 수정에 guardian lease 고침과 archive 시험의 임시 파일 경합 고침을 한 줄씩 적었다. 검증(desktop): verify:documentation, test:unit. --- CHANGELOG.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 415ef9ce..19965034 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,7 +43,7 @@ ## 미출시 — `48c7695b` → 정리 단계 -2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지), 문서 체계 후속(브랜치 `claude/fe-b-docs-followup`, `8acf07c2`부터 브랜치 끝까지. 브랜치 `claude/fe-b-docs-followup-2`, `1b3eee41`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. +2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`), 4단계에 남은 R2·R5 검사(브랜치 `chore/layout-rules-r2-r5`, `3f64c689`부터 브랜치 끝까지), 문서 체계 후속(브랜치 `claude/fe-b-docs-followup`, `8acf07c2`부터 브랜치 끝까지. 브랜치 `claude/fe-b-docs-followup-2`, `1b3eee41`부터 브랜치 끝까지), 자식 프로세스 시험 timeout(브랜치 `fix/child-process-test-timeouts`, `91962e24`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. ### 먼저 할 일 (BREAKING) @@ -73,13 +73,14 @@ 14. **merge 단계 job 이름이 바뀌었다.** 게이트마다 하나이던 행렬 job(`FE-GATE-NNN / <이름>`)이 `merge / static checks`(`merge_static`), `merge / tests`(`merge_test`), `merge / browser tests`(`merge_browser`) 셋이 됐다. 게이트는 job 안의 단계 이름(`FE-GATE-NNN / <이름>`)으로 남는다. Gitea 브랜치 보호의 필수 검사를 옛 job 이름으로 걸었으면 새 job 셋으로 바꾼다. 증거 업로드 이름도 `FE-GATE-NNN-`에서 `merge-static-`·`merge-test-`·`merge-browser-`으로 바뀌었다 (`0739f26b`) 15. **코드에 적은 루트 경로 목록을 등록부 집합으로 바꾼다.** R2 검사가 등록부를 쓰는 7곳이 아니라 추적되는 코드 파일 전체를 본다. 루트 항목(이나 그 안 경로)만 담은 문자열 배열에 추적되는 루트 이름이 둘 이상이면 `tests/unit/repository-layout.test.ts`가 `choose a set from config/repository-layout.json with selectRepositoryPaths`로 실패한다. 템플릿의 19개 목록은 집합 12개로 옮겼다. 자기 목록은 맞는 집합을 고르거나, 없으면 `scripts/lib/repository-layout.ts`의 `REPOSITORY_LAYOUT_SETS`와 등록부 `sets` 설명에 집합을 더해 고른다. 시험이 메모리 안에 만드는 가상 저장소의 경로 목록(실제 루트 항목을 옮겨도 바뀌지 않는 것)은 `tests/unit/repository-layout.test.ts`의 `MADE_UP_REPOSITORY_LISTS`에 파일·목록·이유를 적는다. 사본이 건너뛰는 `node_modules`·`dist` 같은 추적 안 하는 항목은 종류 `untracked`, `optional: true`로 적는다(매뉴얼 03 E절 R1·R2) (`3f64c689`) 16. **샘플을 목록에 둔 프로젝트는 게이트 대상이 샘플 소유가 아닌지 본다.** R5 검사가 문자열 검색 대신 대상의 소유자를 따라간다: goto 경로 → 라우트 표의 기능, workshop story id → stories 파일, spec의 import → 불러오는 파일, 게이트 명령 → package script와 경로 인자, `sourceFeature` → 기능. `config/ci/gates.json`의 수동 a11y 기록이 라우트 표에 없는 라우트를 가리켜도 실패한다(지운 기능의 기록을 남긴 경우) (`1f57c38e`) +17. **자식 프로세스를 띄우는 자기 시험에 잰 timeout을 준다.** 기본 timeout(10초)인 Vitest 시험이 자식 프로세스를 띄우면 `tests/setup.ts`가 그 호출에서 `spawnSync(<명령>) ran in a test on the default 10000 ms timeout`처럼 실패시킨다. 시험이 import한 helper나 스크립트가 띄워도 같다. desktop에서 그 시험의 가장 긴 실행을 재서 `childProcessTimeout()`(`tests/helpers/child-process-timeout.ts`)을 시험이나 describe에 준다. 템플릿의 시험은 그렇게 고쳤다(`docs/work/reference/testing.md` 2절) (`91962e24`) 7. **자기 문서를 새 문서 검사에 맞춘다.** `verify:documentation`(FE-GATE-017)이 살아 있는 문서 전부(루트 `README.md`, `docs/` 아래 기록 밖 문서, 모듈 README)를 본다: 본문이 한국어인지, 「~한다」 체인지, 버전·개수를 복사하지 않았는지, 적은 경로·script·게이트 ID가 있는지. 루트 README는 `## 프로젝트 구조`부터 `## 규칙과 기여`까지 정해진 절을 순서대로 가져야 하고, `docs/README.md`는 `docs/` 아래 모든 폴더를 표 첫 칸 `폴더/`로 덮어야 한다. 자기 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 맨 위에 머리 블록을 단다(형식은 템플릿 `docs/README.md` 3절). 한 번에 다 고칠 수 없으면 걸린 줄을 `scripts/docs-system-exceptions.txt`에 기준선으로 적고 그 지문을 `scripts/lib/docs-system.ts`의 `FROZEN`에 넣는다. 그 목록은 줄기만 한다 (`7a9aefdf`) 8. **README의 바뀐 절 이름을 따른다.** 「Files you can delete after copying」은 「복사한 뒤 지워도 되는 것」이다. `verify:documentation`이 이 제목 아래 표의 첫 칸으로 지워도 되는 경로를 읽는다. 자기 README를 템플릿 README로 받았으면 이 제목을 지킨다 (`7a9aefdf`) #### 옮긴 뒤 확인 -1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`(5·9·11·15·16단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다). +1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`·`test:integration`(5·9·11·15·16·17단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다). - 검사기의 음성 fixture 명령 15개와 ungated 검사(`check:ci:gating`)는 PR이 아니라 브랜치 push의 FE-GATE-029(`main_gate`)에서 돈다. 새 시험 파일이나 검증 script를 게이트에 걸지 않으면 PR은 통과하고 main push가 실패한다. 로컬에서는 `corepack pnpm ci:gate FE-GATE-029`로 미리 본다 (`f6b2b96c`). 2. 시각 골든: 갤러리 두 장(`design-system-gallery-dark`, `state-surfaces-light`)은 이제 Storybook 정적 빌드의 story를 찍는다. 자기 골든을 다시 찍은 프로젝트는 `corepack pnpm test:visual:update`로 그 둘을 다시 찍는다. 3. `/examples/ui`·`/examples/states`·`/examples/auth`를 열던 자기 e2e는 플랫폼 라우트나 자기 화면으로 옮긴다. 템플릿의 그런 spec은 옮겼다(아래 표). @@ -100,6 +101,7 @@ | [계약] | 저장소 배치 규칙 R1~R10을 매뉴얼 03 E절에 적고, 기계로 볼 수 있는 것을 게이트에 넣었다: R1·R2·R7(파일)·R9 `tests/unit/repository-layout.test.ts`, R3 `tests/unit/tracked-artifacts.test.ts`, R4·R5 `tests/unit/example-feature-rules.test.ts`(이상 FE-GATE-005), R6·R7(문서) `verify:documentation`(FE-GATE-017, 산출물에 `layoutRuleViolations`), R8 FE-GATE-003 | `docs/manual/03-outside-feature-folder.md`, `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts` | `e902e657` | | [계약] **BREAKING** | R2 검사를 추적되는 코드 파일 전체로 넓히고 남은 루트 경로 목록 19개를 등록부 집합 12개로 옮겼다. 등록부에 종류 `untracked`가 생겼다. R5 검사는 게이트 대상을 라우트 표·stories 파일·import·package script 그래프·규모 기록 필드로 따라가 소유자를 본다. 위 "먼저 할 일" 15·16 | `config/repository-layout.json`, `scripts/lib/repository-layout.ts`, `tests/unit/repository-layout.test.ts`, `tests/unit/example-feature-rules.test.ts` | `3f64c689`, `1f57c38e` | | [계약] **BREAKING** | merge 단계 job 14개(게이트마다 행렬 하나)를 셋으로 합쳤다. job마다 설치를 한 번 하고 게이트를 차례로 돈다. 앞 게이트가 실패해도 다음 게이트가 돈다(`if: ${{ !cancelled() }}`). release 단계는 세 job을 모두 기다린다. 위 "먼저 할 일" 14 | `config/ci/gates.json` `jobs`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `0739f26b` | +| [계약] **BREAKING** | 기본 timeout인 Vitest 시험이 자식 프로세스를 띄우면 실패한다. 자식 프로세스를 띄우던 시험 91개에 desktop에서 잰 가장 긴 실행의 15배를 30초 단위로 올린 timeout을 줬다. CPU 10% 제한에서 main은 그중 11개가 10초 timeout으로 실패했고 고친 뒤 통과했다. 위 "먼저 할 일" 17 | `tests/setup.ts`, `tests/helpers/child-process-timeout.ts`, `tests/` | `91962e24` | | [계약] **BREAKING** | 새 단계 `main`(`MAIN_READY`, 승격을 막지 않음)과 게이트 FE-GATE-029 `checker-self-tests`. FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거, `check:ci`의 ungated 검사(`check:ci:gating`으로 뗌)를 옮겼다. merge 단계 명령 참조 64 → 49. 음성 타입 fixture(`check:types:fixtures`)는 src 타입 계약 시험이라 merge에 남겼다. CI 계약 기준선 파일은 지웠다. 위 "먼저 할 일" 13 | `config/ci/gates.json`, `scripts/check-ci-gating.ts`, `scripts/lib/promotion-readiness.ts` | `f6b2b96c` | | [계약] **BREAKING** | 문서 체계 검사가 생겼다. `verify:documentation`이 백엔드 `check-docs.py`와 같은 규칙 여섯(language, head, number, map, readme, style)을 `scripts/lib/docs-system.ts`로 돌리고, 참조 검사의 대상이 `docs/README.md` 1절이 링크한 문서에서 살아 있는 문서 전부로 넓어졌다. pull request에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts`가 이 repo로 `verify:documentation`을 돌리므로 문서가 걸리면 merge 단계가 실패한다. 예외 목록(`scripts/docs-system-exceptions.txt`)은 비어 있고 줄기만 한다. 위 "먼저 할 일" 7 | `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`, `scripts/docs-system-exceptions.txt`, `docs/README.md` | `7a9aefdf` | | [계약] | 문서를 수명으로 나눠 옮겼다. 설계서는 `docs/design/`(옛 `docs/superpowers/specs/`와 `docs/architecture/`의 목표 설계 16개는 `<작성일>-<이름>-design.md`로), 계획서는 `docs/history/plans/`(옛 `docs/superpowers/plans/`, 루트 `SPEC.md`는 `docs/history/plans/2026-09-25-review-fix-round/`), 결정 기록 VD는 `docs/adr/`(번호 그대로)다. 기록 67개에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 코드 주석의 문서 경로도 고쳤다. 위 "먼저 할 일" 옮기기 전 | `docs/design/`, `docs/history/`, `docs/adr/`, `.dependency-cruiser.json`, `tests/component/router.test.tsx` | `99e76e87`, `e632b230`, `9540bf81`, `75fad73a`, `2b8a348c` | @@ -130,6 +132,8 @@ - desktop의 FE-GATE-013은 실패가 user namespace 제한 하나뿐이고 `scripts/verify.sh parts FE-GATE-013`의 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다. 게이트 충족은 조건을 갖춘 runner에서 통과한 것으로만 센다(`docs/work/reference/gates.md` 3절, 결정 색인 2.2절). 열린 결정에서 뺐다 (`bdda84f8`). - 스킬이 인용하는 절 이름·번호가 그 문서에 있는지 `scripts/tests/test_claude_setup.py`가 대조한다. 번역으로 사라진 절을 가리키던 9곳을 지금 제목으로 고쳤다. 자기 문서의 절 이름을 바꾸면 그 절을 인용하는 스킬도 같이 고친다 (`1b3eee41`). - `config/ci/ungated-tests.json`의 `reason`을 한국어로 옮겼다 (`ac19de85`). +- provider guardian 시험(`tests/integration/provider-guardian-transaction.test.ts`)이 부하 때 lease 만료로 SIGKILL되던 것을 고쳤다. lease가 시험 대상이 아닌 곳은 시험 timeout만큼 주고, 만료와 마감 직전 publish를 보는 두 시험은 desktop에서 잰 값으로 정했다. 마감 직전 시험은 guardian이 load를 마친 뒤 마감이 시작되는 직접 프로토콜로 옮겼다. CPU 20% 제한에서 고치기 전 5회 모두 실패, 고친 뒤 5회 모두 통과 (`77c01b03`). +- `tests/integration/security-followup-archive.test.ts`가 checkout의 `artifacts/`를 복사하는 동안 다른 시험이 쓰던 원자적 쓰기의 임시 파일이 rename되면 ENOENT로 실패하던 것을 고쳤다. 복사가 `.<이름>.<무작위>.tmp`를 건너뛴다. 임시 파일을 계속 만드는 프로세스를 옆에 두고 돌리면 고치기 전 3회 중 2회 실패, 고친 뒤 3회 모두 통과 (`db4c632d`). ### 알려진 제한