루트에 역할이 겹치는 폴더·설정이 있었다. schemas/(JSON Schema 5개)가 config/ 옆에 따로 있고, 출력 폴더 artifacts/에 사람이 쓴 a11y 기록이, 호스트 계약 폴더 config/hosting/에 시험 fixture가 섞였다.
음성 타입 fixture 23개가 옵션이 같은 tsconfig 23개·package script 23개·게이트 명령 23개를 따로 가졌다. tsconfig.web-worker.json은 0파일을 검사하고 통과했다.
루트 경로 목록이 코드 7곳에 따로 박혀 있었다(04 문서 2.4절). 루트 항목 하나를 옮기면 7곳을 같이 고쳐야 했다.
이런 지적을 소유자가 먼저 말하기 전에 잡을 규칙과 검사가 없었다.
고른 방법과 버린 대안
커밋 여섯 개와 main을 받는 merge 하나다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).
bf485f44 음성 타입 fixture 실행기 하나(scripts/check-type-fixtures.ts, check:types:fixtures). fixture 첫 줄 // expect: TS2322가 기대다. fixture마다 .tmp/type-fixtures/에 한 파일 tsconfig를 써서 tsc를 돈다. 판정은 전과 같다(tsc exit 1과 error TS<code>:). recipes tsconfig는 test로 합치고 web-worker tsconfig는 지웠다(D4). check:types 끝의 check-typecheck-inputs.ts가 0파일 tsconfig를 막는다(R8).
버린 것: TypeScript API로 한 프로세스에서 돌리기. 이 repo의 TypeScript 7.0(네이티브판)은 JS API가 없다. 위반마다 @ts-expect-error(5.3절 (나))는 오류 코드 고정을 잃는다.
79dc945a 루트 등록부 config/repository-layout.json + scripts/lib/repository-layout.ts(R1·R2). 항목마다 종류·역할·읽는 곳과, 들어가는 목록(sets, 항목 안 경로는 setPaths)을 적는다. 7곳 중 코드 6곳은 집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이 같은지 본다. schemas/ → config/schemas/, a11y 기록 → docs/accessibility/route-reviews/, hosting 응답 fixture → tests/fixtures/hosting/.
버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸기. 정책 파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 릴리스 증거 계약이 바뀐다.
등록부의 하위 경로(setPaths)는 04 문서 가정 F6(「어느 목록이 등록부에 없는 항목을 담는다」)이 실제로 맞아서 더했다. vite 입력의 scripts/lib/run-isolation.ts, 비밀값 검사의 .gitea/workflows/quality-gates.yml, 복사 대상의 docs/accessibility/route-reviews가 그 예다.
e902e657 11절 R1~R10 중 기계 검사가 「예」인 것을 표의 게이트 칸대로 넣었다. 규칙 문장은 docs/manual/03-outside-feature-folder.md E절, Worker tsconfig 추가 단계(D4)는 같은 문서 C절이다.
규칙
검사
게이트
R1 등록부에 없는 루트 항목
tests/unit/repository-layout.test.ts
FE-GATE-005
R2 루트 경로 목록은 등록부에서
같은 시험(7곳이 모듈을 쓰고 리터럴 목록이 없는지, 정책 사본이 같은지)
FE-GATE-005
R3 artifacts/는 .gitkeep만
tests/unit/tracked-artifacts.test.ts
FE-GATE-005
R4 샘플 목록은 빌드·시험 drill로 증명
tests/unit/example-feature-rules.test.ts
FE-GATE-005
R5 게이트 대상이 샘플이 아님
같은 시험(visual·e2e goto, 증거 경로, config/scale/)
FE-GATE-005
R6 매뉴얼이 샘플 경로를 안 가리킴
verify:documentation
FE-GATE-017
R7 인프라 설정 없음
파일: repository-layout 시험 / 문서: verify:documentation(nginx·hcl·kind: Deployment)
FE-GATE-005 / 017
R8 0파일 검사 실패
check-typecheck-inputs.ts, fixture 0개면 실행기 실패
FE-GATE-003
R9 옵션이 같은 tsconfig 쌍 금지
repository-layout 시험
FE-GATE-005
R10 루트 *.md 등록
R1에 포함
FE-GATE-005
8d9cb621 CHANGELOG 정리 단계 절에 다운스트림이 할 일 7~12.
c54c3813docs/README.md 표의 옛 a11y 기록 경로. 문서 검사는 .gitignore가 무시하는 경로를 생성 출력으로 보고 넘겨 못 잡았다.
16eb200f 하네스 PR #13이 더할 루트 .gitattributes를 등록부에 optional로 미리 적었다. 두 PR이 어느 순서로 병합돼도 R1 시험이 깨지지 않게 한다.
568f3328 하네스 PR #13이 들어간 main(d1b9c087)을 받는 merge. 충돌 둘을 풀었다.
scripts/lib/removal-fixture.ts: main은 문서 복사 목록에 AGENTS.md를 더했고, 이 브랜치는 그 목록을 등록부 fixture-documents 집합으로 바꿨다. 등록부의 AGENTS.md 항목에 그 집합을 적었다.
tests/unit/template-feature-removal-documents.test.ts: main이 더한 AGENTS.md와 옛 a11y 기록 폴더 중 AGENTS.md만 남겼다(a11y 기록은 이 PR에서 docs/로 옮겼다).
등록부의 AGENTS.md·.claude·.gitattributes에서 optional을 빼고 역할을 실제 내용으로 고쳤다. #13이 더한 하위 항목은 루트 항목이 담는다: docs/work/·docs/vision.md·docs/problem-statement.md는 docs(fixture-documents), src/*/AGENTS.md는 src, scripts/hooks/·scripts/verify.sh·scripts/check-work-docs.py는 scripts가 담는다(scripts의 typescript-only 집합 검사는 .js 계열만 막아 .sh·.py는 통과한다). 추적되는 루트 항목과 등록부 항목이 서로 남는 것 없이 같다.
#13이 더한 파일 중 이 PR이 옮기거나 지운 경로·명령(schemas/, 지운 tsconfig 둘, 옛 a11y 기록 경로, 지운 fixture script)을 가리키는 줄은 없다(git grep).
위험과 영향
다운스트림: 루트 등록부에 자기 루트 항목을 더해야 한다(없으면 R1 시험 실패). 음성 타입 fixture에 첫 줄 기대를 써야 한다. CHANGELOG 「먼저 할 일」 7~12. 두 제품에 적용해 보지 않았다.
recipe가 이제 vite/client 타입이 있는 프로그램에서 검사된다. recipe가 import.meta.env를 쓰면 전에는 실패했고 이제는 통과한다(설계 5.1절이 받아들인 것).
R2 검사는 7곳만 본다. 그 밖에 루트 이름 둘 이상을 담은 문자열 배열이 약 20곳 남았다(뜻이 다른 목록이라 옮기지 않았다). R5는 문자열 검색이다.
하네스 PR #13이 더한 AGENTS.md·CLAUDE.md·.claude/·.gitattributes는 등록부에 역할과 함께 있다(7번). SPEC.md는 등록부에 남겼다. 문서 체계 작업(fe-b)이 옮기며 항목을 뺀다.
다른 세션 소관 파일 중 고친 줄(옮긴 경로·지운 명령을 가리키던 줄만): README.md(a11y 경로 1줄), docs/README.md(1줄), docs/manual/01-add-a-feature.md, docs/manual/03-outside-feature-folder.md(brief가 정한 규칙 절 포함), docs/manual/reference/{create-feature,errors}.md, docs/architecture/{optional-adapter-recipes,starter-experience}.md, docs/testing/frontend-platform-testing-strategy.md, docs/operations/adapter-remediation-ledger.md, docs/accessibility/manual-checklist.md.
R13(리뷰 가이드의 「저장소 배치」 점검)은 design-docs 몫이라 넣지 않았다.
FE-GATE-013은 desktop 호스트의 bwrap user namespace 조건으로 rc=1이다(알려진 호스트 조건). 부분 실행 결과를 아래에 적는다.
검증
main(#13) 병합 뒤 다시 돌린 것 — head 568f3328, 2026-11-11 20:30~21:01, desktop FEA/c, workflow CI env, 공유 잠금 아래. 로그 desktop /tmp/claude-gates/fea-v4/.
rc=1, 1초(호스트 bwrap 조건, 아래와 같다). 부분 실행: 시스템 vitest 115개 중 18 실패 · 61 통과 · 36 건너뜀(실패·건너뜀 모두 ci-artifact-contract.test.ts), verify:reproducible-build · build:release-candidate · verify:local-evidence · check:supply-chain:fixtures · check:supply-chain:provider-fixtures · check:security:fixtures · check:browser-security 모두 rc=0
FE-GATE-017 documentation
rc=0
아래는 main을 받기 전(16eb200f까지)의 결과다.
모두 desktop(~/workspace/clean-architecture-frontend-template-lanes/FEA/c, 공유 checkout은 건드리지 않음), workflow의 CI env(CI=true, VITE_COMMIT_SHA, RELEASE_ID 등), 공유 잠금 아래. 로그는 desktop /tmp/claude-gates/fea-pra-1/, fea-pra-2/, fea-c3/. merge 게이트는 c54c3813에서 돌렸다. 16eb200f는 등록부에 optional 항목 하나를 더할 뿐이라 커밋별 검사만 다시 돌렸다.
rc=1, 2초. desktop 호스트가 bwrap user namespace를 막아 사전 점검에서 멈춘다(알려진 호스트 조건). 부분 실행: 시스템 vitest 18 실패/97 통과(18개 모두 ci-artifact-contract.test.ts provider 시험, 2단계와 같은 수), verify:reproducible-build·build:release-candidate·verify:local-evidence·check:supply-chain:fixtures·check:supply-chain:provider-fixtures·check:security:fixtures·check:browser-security 모두 rc=0
FE-GATE-017
rc=0
1차 실행(2e610e57)에서는 FE-GATE-005·020이 실패했다. CHANGELOG에 리뷰 ID를 라운드 없이(07-05) 적어 changelog-review-ids 시험이 걸렸다. 0925/07-05로 고쳐 커밋을 다시 쌓았다(push 전).
9.3절 3단계 검증: src/application/ports/telemetry-port.ts의 emit 인자를 TelemetryEventName에서 string으로 넓히자 check:types:fixtures가 rc=1, invalid-diagnostics-port.ts가 error TS2578: Unused '@ts-expect-error' directive로 FAIL. 되돌린 뒤 git status 0줄. 변이 없이는 23개 모두 PASS이고, 각 fixture의 기대 코드(TS2322·TS2339·TS2739·TS2345·TS2741·TS2353·TS1360·TS2554, 1개는 pass)가 실행기 출력에 그 진단 줄 그대로 나온다.
루트 모양(git ls-tree --name-only HEAD): main을 받기 전(16eb200f) 폴더 10(.gitea .storybook artifacts config docs public recipes scripts src tests), 파일 30으로 9.1절의 29~30과 같았다. main을 받은 뒤(568f3328) 하네스 PR #13이 더한 .claude/·AGENTS.md·.gitattributes로 폴더 11, 파일 32다. SPEC.md가 문서 체계 작업에서 빠지면 31.
2단계 PR #12, 위에 쌓은 CI 재편 PR #16(브랜치 chore/ci-merge-jobs)
병합 때 맞출 곳: 문서 체계 PR #15가 같은 문서 줄을 한국어로 다시 썼다. 두 번째로 병합하는 쪽이 그쪽 글을 기준으로 경로만 바꾼다. #15의 scripts/lib/docs-system.tsNOT_DOCUMENT의 a11y 기록 경로도 docs/accessibility/route-reviews/로 바꿔야 한다
## 무엇을, 왜
2026-11-07 소유자가 승인한 프론트 저장소 정리의 3단계(합치기)와 4단계(배치 규칙)다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정 `repo-structure/README.md` 3.4절).
- 루트에 역할이 겹치는 폴더·설정이 있었다. `schemas/`(JSON Schema 5개)가 `config/` 옆에 따로 있고, 출력 폴더 `artifacts/`에 사람이 쓴 a11y 기록이, 호스트 계약 폴더 `config/hosting/`에 시험 fixture가 섞였다.
- 음성 타입 fixture 23개가 옵션이 같은 tsconfig 23개·package script 23개·게이트 명령 23개를 따로 가졌다. `tsconfig.web-worker.json`은 0파일을 검사하고 통과했다.
- 루트 경로 목록이 코드 7곳에 따로 박혀 있었다(04 문서 2.4절). 루트 항목 하나를 옮기면 7곳을 같이 고쳐야 했다.
- 이런 지적을 소유자가 먼저 말하기 전에 잡을 규칙과 검사가 없었다.
## 고른 방법과 버린 대안
커밋 여섯 개와 main을 받는 merge 하나다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).
1. `bf485f44` 음성 타입 fixture 실행기 하나(`scripts/check-type-fixtures.ts`, `check:types:fixtures`). fixture 첫 줄 `// expect: TS2322`가 기대다. fixture마다 `.tmp/type-fixtures/`에 한 파일 tsconfig를 써서 tsc를 돈다. 판정은 전과 같다(tsc exit 1과 `error TS<code>:`). recipes tsconfig는 test로 합치고 web-worker tsconfig는 지웠다(D4). `check:types` 끝의 `check-typecheck-inputs.ts`가 0파일 tsconfig를 막는다(R8).
- 버린 것: TypeScript API로 한 프로세스에서 돌리기. 이 repo의 TypeScript 7.0(네이티브판)은 JS API가 없다. 위반마다 `@ts-expect-error`(5.3절 (나))는 오류 코드 고정을 잃는다.
2. `79dc945a` 루트 등록부 `config/repository-layout.json` + `scripts/lib/repository-layout.ts`(R1·R2). 항목마다 종류·역할·읽는 곳과, 들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다. 7곳 중 코드 6곳은 집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이 같은지 본다. `schemas/` → `config/schemas/`, a11y 기록 → `docs/accessibility/route-reviews/`, hosting 응답 fixture → `tests/fixtures/hosting/`.
- 버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸기. 정책 파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 릴리스 증거 계약이 바뀐다.
- 등록부의 하위 경로(`setPaths`)는 04 문서 가정 F6(「어느 목록이 등록부에 없는 항목을 담는다」)이 실제로 맞아서 더했다. vite 입력의 `scripts/lib/run-isolation.ts`, 비밀값 검사의 `.gitea/workflows/quality-gates.yml`, 복사 대상의 `docs/accessibility/route-reviews`가 그 예다.
3. `e902e657` 11절 R1~R10 중 기계 검사가 「예」인 것을 표의 게이트 칸대로 넣었다. 규칙 문장은 `docs/manual/03-outside-feature-folder.md` E절, Worker tsconfig 추가 단계(D4)는 같은 문서 C절이다.
| 규칙 | 검사 | 게이트 |
|---|---|---|
| R1 등록부에 없는 루트 항목 | `tests/unit/repository-layout.test.ts` | FE-GATE-005 |
| R2 루트 경로 목록은 등록부에서 | 같은 시험(7곳이 모듈을 쓰고 리터럴 목록이 없는지, 정책 사본이 같은지) | FE-GATE-005 |
| R3 `artifacts/`는 `.gitkeep`만 | `tests/unit/tracked-artifacts.test.ts` | FE-GATE-005 |
| R4 샘플 목록은 빌드·시험 drill로 증명 | `tests/unit/example-feature-rules.test.ts` | FE-GATE-005 |
| R5 게이트 대상이 샘플이 아님 | 같은 시험(visual·e2e `goto`, 증거 경로, `config/scale/`) | FE-GATE-005 |
| R6 매뉴얼이 샘플 경로를 안 가리킴 | `verify:documentation` | FE-GATE-017 |
| R7 인프라 설정 없음 | 파일: repository-layout 시험 / 문서: `verify:documentation`(```nginx```·```hcl```·`kind: Deployment`) | FE-GATE-005 / 017 |
| R8 0파일 검사 실패 | `check-typecheck-inputs.ts`, fixture 0개면 실행기 실패 | FE-GATE-003 |
| R9 옵션이 같은 tsconfig 쌍 금지 | repository-layout 시험 | FE-GATE-005 |
| R10 루트 *.md 등록 | R1에 포함 | FE-GATE-005 |
4. `8d9cb621` CHANGELOG 정리 단계 절에 다운스트림이 할 일 7~12.
5. `c54c3813` `docs/README.md` 표의 옛 a11y 기록 경로. 문서 검사는 `.gitignore`가 무시하는 경로를 생성 출력으로 보고 넘겨 못 잡았다.
6. `16eb200f` 하네스 PR #13이 더할 루트 `.gitattributes`를 등록부에 optional로 미리 적었다. 두 PR이 어느 순서로 병합돼도 R1 시험이 깨지지 않게 한다.
7. `568f3328` 하네스 PR #13이 들어간 main(`d1b9c087`)을 받는 merge. 충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를 더했고, 이 브랜치는 그 목록을 등록부 `fixture-documents` 집합으로 바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main이 더한 `AGENTS.md`와 옛 a11y 기록 폴더 중 `AGENTS.md`만 남겼다(a11y 기록은 이 PR에서 `docs/`로 옮겼다).
- 등록부의 `AGENTS.md`·`.claude`·`.gitattributes`에서 optional을 빼고 역할을 실제 내용으로 고쳤다. #13이 더한 하위 항목은 루트 항목이 담는다: `docs/work/`·`docs/vision.md`·`docs/problem-statement.md`는 `docs`(`fixture-documents`), `src/*/AGENTS.md`는 `src`, `scripts/hooks/`·`scripts/verify.sh`·`scripts/check-work-docs.py`는 `scripts`가 담는다(`scripts`의 `typescript-only` 집합 검사는 `.js` 계열만 막아 `.sh`·`.py`는 통과한다). 추적되는 루트 항목과 등록부 항목이 서로 남는 것 없이 같다.
- #13이 더한 파일 중 이 PR이 옮기거나 지운 경로·명령(`schemas/`, 지운 tsconfig 둘, 옛 a11y 기록 경로, 지운 fixture script)을 가리키는 줄은 없다(`git grep`).
## 위험과 영향
- 다운스트림: 루트 등록부에 자기 루트 항목을 더해야 한다(없으면 R1 시험 실패). 음성 타입 fixture에 첫 줄 기대를 써야 한다. CHANGELOG 「먼저 할 일」 7~12. 두 제품에 적용해 보지 않았다.
- recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다. recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다(설계 5.1절이 받아들인 것).
- R2 검사는 7곳만 본다. 그 밖에 루트 이름 둘 이상을 담은 문자열 배열이 약 20곳 남았다(뜻이 다른 목록이라 옮기지 않았다). R5는 문자열 검색이다.
- 하네스 PR #13이 더한 `AGENTS.md`·`CLAUDE.md`·`.claude/`·`.gitattributes`는 등록부에 역할과 함께 있다(7번). `SPEC.md`는 등록부에 남겼다. 문서 체계 작업(fe-b)이 옮기며 항목을 뺀다.
- 다른 세션 소관 파일 중 고친 줄(옮긴 경로·지운 명령을 가리키던 줄만): `README.md`(a11y 경로 1줄), `docs/README.md`(1줄), `docs/manual/01-add-a-feature.md`, `docs/manual/03-outside-feature-folder.md`(brief가 정한 규칙 절 포함), `docs/manual/reference/{create-feature,errors}.md`, `docs/architecture/{optional-adapter-recipes,starter-experience}.md`, `docs/testing/frontend-platform-testing-strategy.md`, `docs/operations/adapter-remediation-ledger.md`, `docs/accessibility/manual-checklist.md`.
- R13(리뷰 가이드의 「저장소 배치」 점검)은 design-docs 몫이라 넣지 않았다.
- FE-GATE-013은 desktop 호스트의 bwrap user namespace 조건으로 rc=1이다(알려진 호스트 조건). 부분 실행 결과를 아래에 적는다.
## 검증
**main(#13) 병합 뒤 다시 돌린 것** — head `568f3328`, 2026-11-11 20:30~21:01, desktop `FEA/c`, workflow CI env, 공유 잠금 아래. 로그 desktop `/tmp/claude-gates/fea-v4/`.
| 대상 | 결과 |
|---|---|
| 커밋별 test:unit · check:types · check:ci · lint · verify:documentation | 5개 모두 rc=0 |
| FE-GATE-001·002·003·004·006·007·009·010·011·012 | rc=0 |
| FE-GATE-005 unit | rc=0 (230초) |
| FE-GATE-008 e2e | rc=0 (203초) |
| FE-GATE-020 removability | rc=0 (1,087초) |
| FE-GATE-013 security | rc=1, 1초(호스트 bwrap 조건, 아래와 같다). 부분 실행: 시스템 vitest 115개 중 18 실패 · 61 통과 · 36 건너뜀(실패·건너뜀 모두 `ci-artifact-contract.test.ts`), verify:reproducible-build · build:release-candidate · verify:local-evidence · check:supply-chain:fixtures · check:supply-chain:provider-fixtures · check:security:fixtures · check:browser-security 모두 rc=0 |
| FE-GATE-017 documentation | rc=0 |
아래는 main을 받기 전(`16eb200f`까지)의 결과다.
모두 desktop(`~/workspace/clean-architecture-frontend-template-lanes/FEA/c`, 공유 checkout은 건드리지 않음), workflow의 CI env(`CI=true`, `VITE_COMMIT_SHA`, `RELEASE_ID` 등), 공유 잠금 아래. 로그는 desktop `/tmp/claude-gates/fea-pra-1/`, `fea-pra-2/`, `fea-c3/`. merge 게이트는 `c54c3813`에서 돌렸다. `16eb200f`는 등록부에 optional 항목 하나를 더할 뿐이라 커밋별 검사만 다시 돌렸다.
**커밋마다** test:unit · check:types · check:ci · lint · verify:documentation
| 커밋 | 결과 |
|---|---|
| `bf485f44` | 5개 모두 rc=0 |
| `79dc945a` | 5개 모두 rc=0 |
| `e902e657` | 5개 모두 rc=0 |
| `8d9cb621` | 5개 모두 rc=0 |
| `c54c3813` | 5개 모두 rc=0 (test:unit 3,117개) |
| `16eb200f` | 5개 모두 rc=0 |
**merge 게이트 14개 + 문서 게이트** (`ci:gate`)
| 게이트 | 결과 |
|---|---|
| FE-GATE-001·002·003·004·006·007·008·009·010·011·012 | rc=0 (`2e610e57`에서. `c54c3813`과는 CHANGELOG 한 줄만 다르고 이 게이트들은 CHANGELOG를 읽지 않는다) |
| FE-GATE-005 | rc=0 (`c54c3813`, 151초) |
| FE-GATE-020 | rc=0 (`c54c3813`, 1,213초, drill 다섯 개. 샘플 목록이 비어 `sample removal: SKIP`) |
| FE-GATE-013 | rc=1, 2초. desktop 호스트가 bwrap user namespace를 막아 사전 점검에서 멈춘다(알려진 호스트 조건). 부분 실행: 시스템 vitest 18 실패/97 통과(18개 모두 `ci-artifact-contract.test.ts` provider 시험, 2단계와 같은 수), verify:reproducible-build·build:release-candidate·verify:local-evidence·check:supply-chain:fixtures·check:supply-chain:provider-fixtures·check:security:fixtures·check:browser-security 모두 rc=0 |
| FE-GATE-017 | rc=0 |
1차 실행(`2e610e57`)에서는 FE-GATE-005·020이 실패했다. CHANGELOG에 리뷰 ID를 라운드 없이(`07-05`) 적어 `changelog-review-ids` 시험이 걸렸다. `0925/07-05`로 고쳐 커밋을 다시 쌓았다(push 전).
**9.3절 3단계 검증**: `src/application/ports/telemetry-port.ts`의 `emit` 인자를 `TelemetryEventName`에서 `string`으로 넓히자 `check:types:fixtures`가 rc=1, `invalid-diagnostics-port.ts`가 `error TS2578: Unused '@ts-expect-error' directive`로 FAIL. 되돌린 뒤 `git status` 0줄. 변이 없이는 23개 모두 PASS이고, 각 fixture의 기대 코드(TS2322·TS2339·TS2739·TS2345·TS2741·TS2353·TS1360·TS2554, 1개는 pass)가 실행기 출력에 그 진단 줄 그대로 나온다.
**루트 모양**(`git ls-tree --name-only HEAD`): main을 받기 전(`16eb200f`) 폴더 10(`.gitea .storybook artifacts config docs public recipes scripts src tests`), 파일 30으로 9.1절의 29~30과 같았다. main을 받은 뒤(`568f3328`) 하네스 PR #13이 더한 `.claude/`·`AGENTS.md`·`.gitattributes`로 폴더 11, 파일 32다. `SPEC.md`가 문서 체계 작업에서 빠지면 31.
## 리뷰어가 볼 곳
- `config/repository-layout.json`, `scripts/lib/repository-layout.ts`, `tests/unit/repository-layout.test.ts`: 등록부와 R1·R2·R7·R9.
- `scripts/check-type-fixtures.ts`, `scripts/check-typecheck-inputs.ts`: 실행기와 R8.
- `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts`: R6·R7 문서 검사와 산출물 칸.
- 기계적으로 바꾼 것: fixture 23개 첫 줄(gates.json의 기대 진단에서 만듦), 경로 바꾸기(`schemas/artifacts` → `config/schemas/artifacts` 등)는 `git grep`과 perl 치환으로 했다. 기준 `ad3a071f`.
## 관련
- design-docs `repo-structure/04-frontend-layout.md` 5.3·9.2·9.3·11절, `repo-structure/README.md` 3.4절(D4)
- 2단계 PR #12, 위에 쌓은 CI 재편 PR #16(브랜치 `chore/ci-merge-jobs`)
- 병합 때 맞출 곳: 문서 체계 PR #15가 같은 문서 줄을 한국어로 다시 썼다. 두 번째로 병합하는 쪽이 그쪽 글을 기준으로 경로만 바꾼다. #15의 `scripts/lib/docs-system.ts` `NOT_DOCUMENT`의 a11y 기록 경로도 `docs/accessibility/route-reviews/`로 바꿔야 한다
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).
고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
`scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
`files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).
버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.
위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).
검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).
Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
`scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
`config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
`.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
`tests/fixtures/hosting/response-headers.json`.
버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.
위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).
검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
`kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
보지 않는다. 산출물 `documentation-review.json`에
`layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
`check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.
위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.
검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
정리 단계 미출시 절에 3단계(합치기)와 4단계(배치 규칙 검사)를
더한다. 다운스트림이 할 일 7~12(음성 타입 fixture 기대 줄, 지운
tsconfig, a11y 기록과 스키마 이동, 루트 등록부, CI 계약 기준선)와 계약
표 세 줄, 알려진 제한 둘(R2가 보는 범위, R5의 문자열 검색)을 적었다.
위험: 다운스트림에 적용해 보지 않았다(절의 알려진 제한과 같다).
검증(desktop): `tests/unit/changelog-review-ids.test.ts`를 포함한
test:unit.
Refs: design-docs repo-structure/04-frontend-layout.md 9.2절
`docs/README.md` 표가 수동 a11y 기록을 아직 `artifacts/tests/a11y-manual/`로
가리킨다. 기록은 `docs/accessibility/route-reviews/`로 옮겼다(79dc945a).
`verify:documentation`은 `.gitignore`가 무시하는 경로를 생성 출력으로 보고
넘겨서 이 줄을 잡지 못했다.
검증(desktop): verify:documentation, test:unit.
하네스 PR(#13)이 루트에 `.gitattributes`(작업 장부 파일의 병합 규칙)를
더한다. 이 PR이 먼저 들어가고 그 PR이 나중에 들어가면 등록부에 없는
루트 항목이 생겨 `tests/unit/repository-layout.test.ts`(R1)가 실패한다.
`AGENTS.md`·`.claude`처럼 optional 항목으로 미리 적는다. 없으면 고르는
집합이 없어 다른 검사에 영향이 없다.
검증(desktop): test:unit, check:ci, verify:documentation.
main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
2026-11-07 소유자가 승인한 프론트 저장소 정리의 3단계(합치기)와 4단계(배치 규칙)다(design-docs
repo-structure/04-frontend-layout.md9.2절, 결정repo-structure/README.md3.4절).schemas/(JSON Schema 5개)가config/옆에 따로 있고, 출력 폴더artifacts/에 사람이 쓴 a11y 기록이, 호스트 계약 폴더config/hosting/에 시험 fixture가 섞였다.tsconfig.web-worker.json은 0파일을 검사하고 통과했다.고른 방법과 버린 대안
커밋 여섯 개와 main을 받는 merge 하나다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).
bf485f44음성 타입 fixture 실행기 하나(scripts/check-type-fixtures.ts,check:types:fixtures). fixture 첫 줄// expect: TS2322가 기대다. fixture마다.tmp/type-fixtures/에 한 파일 tsconfig를 써서 tsc를 돈다. 판정은 전과 같다(tsc exit 1과error TS<code>:). recipes tsconfig는 test로 합치고 web-worker tsconfig는 지웠다(D4).check:types끝의check-typecheck-inputs.ts가 0파일 tsconfig를 막는다(R8).@ts-expect-error(5.3절 (나))는 오류 코드 고정을 잃는다.79dc945a루트 등록부config/repository-layout.json+scripts/lib/repository-layout.ts(R1·R2). 항목마다 종류·역할·읽는 곳과, 들어가는 목록(sets, 항목 안 경로는setPaths)을 적는다. 7곳 중 코드 6곳은 집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이 같은지 본다.schemas/→config/schemas/, a11y 기록 →docs/accessibility/route-reviews/, hosting 응답 fixture →tests/fixtures/hosting/.setPaths)는 04 문서 가정 F6(「어느 목록이 등록부에 없는 항목을 담는다」)이 실제로 맞아서 더했다. vite 입력의scripts/lib/run-isolation.ts, 비밀값 검사의.gitea/workflows/quality-gates.yml, 복사 대상의docs/accessibility/route-reviews가 그 예다.e902e65711절 R1~R10 중 기계 검사가 「예」인 것을 표의 게이트 칸대로 넣었다. 규칙 문장은docs/manual/03-outside-feature-folder.mdE절, Worker tsconfig 추가 단계(D4)는 같은 문서 C절이다.tests/unit/repository-layout.test.tsartifacts/는.gitkeep만tests/unit/tracked-artifacts.test.tstests/unit/example-feature-rules.test.tsgoto, 증거 경로,config/scale/)verify:documentationverify:documentation(nginx·hcl·kind: Deployment)check-typecheck-inputs.ts, fixture 0개면 실행기 실패8d9cb621CHANGELOG 정리 단계 절에 다운스트림이 할 일 7~12.c54c3813docs/README.md표의 옛 a11y 기록 경로. 문서 검사는.gitignore가 무시하는 경로를 생성 출력으로 보고 넘겨 못 잡았다.16eb200f하네스 PR #13이 더할 루트.gitattributes를 등록부에 optional로 미리 적었다. 두 PR이 어느 순서로 병합돼도 R1 시험이 깨지지 않게 한다.568f3328하네스 PR #13이 들어간 main(d1b9c087)을 받는 merge. 충돌 둘을 풀었다.scripts/lib/removal-fixture.ts: main은 문서 복사 목록에AGENTS.md를 더했고, 이 브랜치는 그 목록을 등록부fixture-documents집합으로 바꿨다. 등록부의AGENTS.md항목에 그 집합을 적었다.tests/unit/template-feature-removal-documents.test.ts: main이 더한AGENTS.md와 옛 a11y 기록 폴더 중AGENTS.md만 남겼다(a11y 기록은 이 PR에서docs/로 옮겼다).AGENTS.md·.claude·.gitattributes에서 optional을 빼고 역할을 실제 내용으로 고쳤다. #13이 더한 하위 항목은 루트 항목이 담는다:docs/work/·docs/vision.md·docs/problem-statement.md는docs(fixture-documents),src/*/AGENTS.md는src,scripts/hooks/·scripts/verify.sh·scripts/check-work-docs.py는scripts가 담는다(scripts의typescript-only집합 검사는.js계열만 막아.sh·.py는 통과한다). 추적되는 루트 항목과 등록부 항목이 서로 남는 것 없이 같다.schemas/, 지운 tsconfig 둘, 옛 a11y 기록 경로, 지운 fixture script)을 가리키는 줄은 없다(git grep).위험과 영향
vite/client타입이 있는 프로그램에서 검사된다. recipe가import.meta.env를 쓰면 전에는 실패했고 이제는 통과한다(설계 5.1절이 받아들인 것).AGENTS.md·CLAUDE.md·.claude/·.gitattributes는 등록부에 역할과 함께 있다(7번).SPEC.md는 등록부에 남겼다. 문서 체계 작업(fe-b)이 옮기며 항목을 뺀다.README.md(a11y 경로 1줄),docs/README.md(1줄),docs/manual/01-add-a-feature.md,docs/manual/03-outside-feature-folder.md(brief가 정한 규칙 절 포함),docs/manual/reference/{create-feature,errors}.md,docs/architecture/{optional-adapter-recipes,starter-experience}.md,docs/testing/frontend-platform-testing-strategy.md,docs/operations/adapter-remediation-ledger.md,docs/accessibility/manual-checklist.md.검증
main(#13) 병합 뒤 다시 돌린 것 — head
568f3328, 2026-11-11 20:30~21:01, desktopFEA/c, workflow CI env, 공유 잠금 아래. 로그 desktop/tmp/claude-gates/fea-v4/.ci-artifact-contract.test.ts), verify:reproducible-build · build:release-candidate · verify:local-evidence · check:supply-chain:fixtures · check:supply-chain:provider-fixtures · check:security:fixtures · check:browser-security 모두 rc=0아래는 main을 받기 전(
16eb200f까지)의 결과다.모두 desktop(
~/workspace/clean-architecture-frontend-template-lanes/FEA/c, 공유 checkout은 건드리지 않음), workflow의 CI env(CI=true,VITE_COMMIT_SHA,RELEASE_ID등), 공유 잠금 아래. 로그는 desktop/tmp/claude-gates/fea-pra-1/,fea-pra-2/,fea-c3/. merge 게이트는c54c3813에서 돌렸다.16eb200f는 등록부에 optional 항목 하나를 더할 뿐이라 커밋별 검사만 다시 돌렸다.커밋마다 test:unit · check:types · check:ci · lint · verify:documentation
bf485f4479dc945ae902e6578d9cb621c54c381316eb200fmerge 게이트 14개 + 문서 게이트 (
ci:gate)2e610e57에서.c54c3813과는 CHANGELOG 한 줄만 다르고 이 게이트들은 CHANGELOG를 읽지 않는다)c54c3813, 151초)c54c3813, 1,213초, drill 다섯 개. 샘플 목록이 비어sample removal: SKIP)ci-artifact-contract.test.tsprovider 시험, 2단계와 같은 수), verify:reproducible-build·build:release-candidate·verify:local-evidence·check:supply-chain:fixtures·check:supply-chain:provider-fixtures·check:security:fixtures·check:browser-security 모두 rc=01차 실행(
2e610e57)에서는 FE-GATE-005·020이 실패했다. CHANGELOG에 리뷰 ID를 라운드 없이(07-05) 적어changelog-review-ids시험이 걸렸다.0925/07-05로 고쳐 커밋을 다시 쌓았다(push 전).9.3절 3단계 검증:
src/application/ports/telemetry-port.ts의emit인자를TelemetryEventName에서string으로 넓히자check:types:fixtures가 rc=1,invalid-diagnostics-port.ts가error TS2578: Unused '@ts-expect-error' directive로 FAIL. 되돌린 뒤git status0줄. 변이 없이는 23개 모두 PASS이고, 각 fixture의 기대 코드(TS2322·TS2339·TS2739·TS2345·TS2741·TS2353·TS1360·TS2554, 1개는 pass)가 실행기 출력에 그 진단 줄 그대로 나온다.루트 모양(
git ls-tree --name-only HEAD): main을 받기 전(16eb200f) 폴더 10(.gitea .storybook artifacts config docs public recipes scripts src tests), 파일 30으로 9.1절의 29~30과 같았다. main을 받은 뒤(568f3328) 하네스 PR #13이 더한.claude/·AGENTS.md·.gitattributes로 폴더 11, 파일 32다.SPEC.md가 문서 체계 작업에서 빠지면 31.리뷰어가 볼 곳
config/repository-layout.json,scripts/lib/repository-layout.ts,tests/unit/repository-layout.test.ts: 등록부와 R1·R2·R7·R9.scripts/check-type-fixtures.ts,scripts/check-typecheck-inputs.ts: 실행기와 R8.scripts/verify-documentation-readiness.ts,scripts/contracts/release-artifacts.ts: R6·R7 문서 검사와 산출물 칸.schemas/artifacts→config/schemas/artifacts등)는git grep과 perl 치환으로 했다. 기준ad3a071f.관련
repo-structure/04-frontend-layout.md5.3·9.2·9.3·11절,repo-structure/README.md3.4절(D4)chore/ci-merge-jobs)scripts/lib/docs-system.tsNOT_DOCUMENT의 a11y 기록 경로도docs/accessibility/route-reviews/로 바꿔야 한다