루트 항목 하나를 옮기려면 코드 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절
문제: .gitignore가 artifacts/를 확장자별로만 무시한다(*.json, *.xml,
*.txt, *.sarif, *.log). 규칙에 없는 확장자가 새어 들어와 화면 캡처 3개
(artifacts/local-preview/*.png)와 커버리지 보고서 10개
(artifacts/tests/coverage-gateway/)가 추적된다. 읽는 코드·게이트·문서는
없다(git grep 'local-preview', 'coverage-gateway' 0건, 리뷰 기록 제외).
0929/14-01이 찾았고 2026-11-06 리뷰까지 '일부'로 남았다.
고른 방법:
- 13개를 지운다.
- artifacts/를 폴더째 무시하고 .gitkeep 2개와 수동 a11y 기록
(artifacts/tests/a11y-manual/*.md)만 다시 넣는다. git은 무시한 폴더
아래 파일을 다시 넣지 못해서, 지나가는 폴더마다 다시 넣고 그 내용을
다시 무시한다. 확장자·폴더별 옛 규칙은 모두 이 안에 들어가 지웠다.
- tests/unit/tracked-artifacts.test.ts가 git ls-files artifacts를 허용
목록과 대조한다. git add -f로 넣은 파일도 잡는다.
버린 대안:
- artifacts/** 와 !artifacts/**/ 꼴: git에서는 같게 되지만
verify:documentation이 .gitignore를 읽는 방식
(scripts/verify-documentation-readiness.ts generated())이
!artifacts/**/ 를 "artifacts 아래 전부 다시 넣음"으로 읽는다. 그러면
문서가 이름 부르는 생성 산출물(artifacts/quality/... 등)이 없는 경로로
실패한다(코드 읽기로 확인).
- 확장자 규칙에 *.png, *.html, *.info를 더하기: 다음 새 확장자에서 같은
일이 난다.
위험·한계: a11y 기록 말고 사람이 쓴 파일을 artifacts/에 두면 이제
무시된다. 지금 추적 파일 12개는 모두 허용 목록 안이다. 다운스트림은 지운
13개를 고치지 않았으면 병합이 그대로 지운다.
검증(desktop, 네 커밋의 끝 30a379f에서 한 번. 커밋마다 따로 돌리지는
않았다. 로그 ~/l1-layout-cleanup-logs/):
- tracked-artifacts.test.ts: 지금 트리 통과. 지운 png 3개를 index에
되돌리면 실패하고 그 3개를 낸다. 허용 목록 밖 note.txt를 git add -f
하면 실패하고 그 파일을 낸다.
- 새 .gitignore를 빈 저장소에 두고 산출물 15개를 만든 뒤 git add -A:
.gitkeep 2개와 a11y .md 1개만 추적된다(노트북).
- git ls-files artifacts: 12개(.gitkeep 2, a11y-manual/*.md 10).
- corepack pnpm test:unit: 212 files, 3091 tests 통과.
verify:documentation: PASS_SCOPED. check:architecture, check:types,
lint, check:ci, check:adapter-inventory: exit 0.
Refs: design-docs repo-structure/04-frontend-layout.md 9.2절 1단계