chore(layout): 정리 1단계로 버려진 파일·이력·nginx 조각을 정리한다 #11

Merged
donghyeon.kang merged 4 commits from chore/layout-1-cleanup into main 2026-11-07 15:14:49 +00:00
Owner

무엇을, 왜

소유자가 2026-11-07에 두 템플릿 정리를 지시했다. 이 PR은 프론트 배치 정리 세 단계 중 1단계(정리)다. 판정 근거는 design-docs repo-structure/04-frontend-layout.md(S4 조사) 2·4·9.2절이고, 소유자가 권하는 안(C안, 세 단계, 단계마다 PR 하나)을 승인했다(design-docs repo-structure/README.md 3.4절).

바꾼 것은 넷이다. 커밋도 하나씩이다.

  1. 85f941c4 아무도 읽지 않는 산출물 13개를 지우고 artifacts/를 폴더째 무시한다.
    • 지운 것: artifacts/local-preview/의 화면 캡처 3개, artifacts/tests/coverage-gateway/의 커버리지 HTML 10개. 0929 리뷰 14-01이 찾았고, 그 뒤 리뷰 네 번 내내 '일부'로 남았다.
    • .gitignore는 확장자별 규칙을 버리고 폴더째 무시한다. 남기는 추적 파일은 .gitkeep 2개와, 사람이 쓰고 a11y 게이트가 읽는 수동 검토 기록 artifacts/tests/a11y-manual/*.md 10개뿐이다.
    • tests/unit/tracked-artifacts.test.ts가 이 목록을 지킨다. 목록 밖 파일이 추적되면 test:unit이 실패한다.
  2. 0805910c 아무도 읽지 않는 config/schemas/의 JSON Schema 4개를 지운다.
    • 산출물 검사는 scripts/contracts/release-artifacts.ts의 zod가 한다. 4개 모두 zod 정본과 대조한 결과는 커밋 본문에 있다.
    • 그런데도 2026-11-05에 손으로 고친 일이 있었다(81701ad). 읽는 곳 없는 사본을 맞추는 일이 이미 생기고 있었다.
  3. 429b8d88 루트의 tasks/와 .superpowers/ 기록을 docs/history/로 옮긴다.
    • tasks/ 5개 → docs/history/plans/2026-09-25-review-fix-round/(lanes/ 유지)
    • .superpowers/ 보고 1개 → docs/history/evidence/2026-08-01-runtime-correctness-remediation/
    • .md 5개 맨 위에 design-docs conventions/docs-system.md 4.1절의 머리 블록(9줄)을 달았다. 블록을 빼면 원문과 바이트가 같다. setup-lane.sh는 실행 파일이라 머리 블록 없이 100% rename으로 옮겼다(권한 100755 유지).
    • docs/README.md 지도에 history/ 행(옛 경로 → 새 경로)과 「기록 문서의 머리 블록」 절을 더했다. 루트 README.md의 지울 수 있는 파일 행도 고쳤다.
    • tests/unit/deletable-history-documents.test.ts는 이제 docs/history를 읽는 코드도 막는다. 루트 tasks/ 패턴은 지켜야 할 폴더가 없고 제품의 tasks/ 경로 문자열을 잘못 잡을 수 있어 뺐다.
  4. 121e1125 nginx 설정 예시를 지우고 호스트가 지킬 조건만 남긴다.
    • docs/operations/release-cache-rollback.md의 「Example: nginx on a single server」(nginx 설정 77줄)를 지웠다. 그 자리에 「운영 환경이 지켜야 할 조건」 19개를 문장으로 두었다. 조건마다 FE-GATE-019가 재는지, 아무도 재지 않는지를 적었다. 값의 정본은 config/hosting/*.json이다.
    • 지운 설정을 한 줄씩 조건 번호에 대응시킨 표는 커밋 본문에 있다.
    • docs/architecture/static-delivery.md의 nginx 링크는 이 조건 절을 가리킨다.
    • docs/operations/ci-quality-gates.md의 runner 요구 문장은 남겼다. 호스트를 바꾸는 AppArmor profile 본문과 sysctl 줄만 지웠다. 고치는 방법은 scripts/check-system-test-prerequisites.ts가 출력한다.

고른 방법과 버린 대안

  • nginx 설정은 다른 repo(project-infra, cicd-platform)로 복사하지 않고 지웠다.
    • 백엔드도 같은 날 "인프라 실행 파일은 지우고, 운영 환경에 요구하는 조건만 문서로 남긴다"로 정했다.
    • 아무도 시험하지 않는 설정 사본을 다른 repo에 만들면 갈라진 복사본이 하나 더 생긴다(S4 가정 F5).
    • S4 문서는 "project-infra로 옮긴다"였다. 이 판단은 프론트 총괄이 바꿨고, 백엔드 총괄이 동의했다.
  • .gitignore는 흔한 꼴인 artifacts/** + !artifacts/**/를 쓰지 않았다. scripts/verify-documentation-readiness.ts가 .gitignore를 직접 해석하는데, 그 꼴은 그 해석에서 모든 산출물을 되살린다. 그래서 폴더마다 다시 넣고 다시 무시하는 꼴로 썼다.
  • config/schemas/ 4개는 schemas/로 옮기거나 zod에서 생성하지 않았다. 읽는 곳이 없는 파일을 옮기거나 생성하면 지킬 것 없는 사본이 하나 더 생긴다. 스키마 자리를 한 곳으로 모으는 일은 3단계다.
  • 기록 문서 안의 옛 경로(docs/superpowers/plans/2026-08-02-*.md, docs/reviews/2026-09-25-maturity-review/)는 고치지 않았다. 기록은 본문을 고치지 않는다(docs-system 1절). docs/README.md 지도에 옛 경로 → 새 경로를 적었다.

위험과 영향

  • SPEC.md는 이 PR에서 옮기지 않았다. 소유자 결정은 "SPEC.md·tasks/·.superpowers/는 이력 폴더로 옮긴다. SPEC.md의 공통 완료 기준은 먼저 매뉴얼로 옮긴다"이다. 그 기준이 갈 작업 매뉴얼 docs/work/improve.md는 이 프로그램의 뒤 단계에서 만든다. 그래서 SPEC.md 이동은 docs/work/improve.md를 만드는 단계의 brief에 넣는다. 그때까지 SPEC.md:17, :60, :67은 tasks/의 옛 경로를 가리킨다.
  • 호스트에서 아무도 재지 않는 조건이 19개 중 11개다(7, 8, 10, 11, 12, 13, 15, 16, 17, 18, 19번). FE-GATE-019는 200 응답, 진입 스크립트 하나, 확장자별 첫 파일 하나만 본다. 오류 응답의 헤더, 나머지 파일의 캐시·압축, 404 동작, 전환 도중 섞임, 롤백 결과는 재지 않는다. 지운 nginx 예시도 CI가 돌리지 않았으므로, 잃은 검사는 없다. 재는 범위를 넓히는 일은 따로 남는다.
  • verify:documentation이 .gitignore를 git과 같게 읽는다는 가정이 생겼다. 기존 시험과 verify:documentation 통과로만 확인했다. .gitignore를 다시 바꿀 때는 그 해석기도 같이 본다.
  • tracked-artifacts.test.ts는 시험 환경에 git이 있다고 가정한다(git ls-files).
  • 다운스트림(tech-log, memento)은 지운 파일을 고치지 않았으면 그대로 받는다. CHANGELOG.md 줄은 2단계 PR에서 1단계와 함께 적는다.
  • docs/README.md 「기록 문서의 머리 블록」 절은 문서 체계 프론트 적용(docs-system 9.2절)의 일부를 먼저 넣은 것이다.

검증

하위 세션이 desktop에서 끝 트리(30a379f, 트리가 121e1125와 같다)로 돌렸다. 로그는 desktop ~/l1-layout-cleanup-logs/에 있다.

명령 결과
corepack pnpm check:architecture exit 0
corepack pnpm check:types exit 0
corepack pnpm lint exit 0
corepack pnpm test:unit exit 0, 212 files, 3,091 tests
corepack pnpm verify:documentation exit 0, PASS_SCOPED
corepack pnpm check:ci exit 0
corepack pnpm check:adapter-inventory exit 0
git grep -n '^```nginx' 0줄

새 시험이 실패를 잡는지도 봤다:

  • tracked-artifacts: 지운 png 3개를 되돌리면 exit 1, 목록 밖 note.txt를 git add -f하면 exit 1
  • deletable-history-documents: 코드가 docs/history를 읽게 하면 exit 1

merge 게이트 14개는 총괄이 desktop에서 121e1125로 돌렸다(ci:gate, workflow와 같은 CI 환경 변수). 로그는 desktop /tmp/claude-gates/121e112-ci/, /tmp/claude-gates/121e112-013-parts/에 있다.

게이트 결과 시간
FE-GATE-001~012 모두 rc=0 005 135s, 008 201s, 010 63s
FE-GATE-020 rc=0 1,258s
FE-GATE-013 rc=1, 사전 점검에서 멈춤 2s

FE-GATE-013은 이 변경과 상관없는 호스트 제약이다. desktop이 비특권 user·network namespace를 막아서(kernel.apparmor_restrict_unprivileged_userns=1, bwrap: loopback: Failed RTM_NEWADDR) 사전 점검이 멈춘다. PR #8과 같은 상태다. 사전 점검 뒤 부분을 따로 돌린 결과:

  • tests/system: 115건 중 97건 통과. 실패 18건은 모두 tests/system/ci-runner…의 provider sandbox(bwrap) 테스트다.
  • 나머지 명령 7개(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이다.

실행 뒤 desktop checkout은 fix/maturity-review-2026-11-03으로 돌아갔고 git status가 비어 있다.

리뷰어가 볼 곳

  • .gitignore: 폴더마다 다시 넣고 다시 무시하는 꼴. 새 산출물 폴더가 생겨도 추적되지 않는지.
  • docs/operations/release-cache-rollback.md:130 「운영 환경이 지켜야 할 조건」: 지운 설정의 요구가 빠짐없는지, "재는 쪽" 판정이 FE-GATE-019 코드(scripts/verify-hosting-headers.ts, scripts/lib/hosting-probe.ts)와 맞는지.
  • docs/history/ 머리 블록 5개: 상태·작성일·현재 정본 칸.

관련

  • 기준: main 48c7695b(PR #5·#7·#8·#9 병합 뒤).
  • 정본: design-docs repo-structure/04-frontend-layout.md(S4), repo-structure/README.md 3.4절, conventions/docs-system.md.
  • 다음: 2단계(샘플 역할 이전·삭제)는 이 브랜치 위에 쌓는다.
## 무엇을, 왜 소유자가 2026-11-07에 두 템플릿 정리를 지시했다. 이 PR은 프론트 배치 정리 세 단계 중 1단계(정리)다. 판정 근거는 design-docs `repo-structure/04-frontend-layout.md`(S4 조사) 2·4·9.2절이고, 소유자가 권하는 안(C안, 세 단계, 단계마다 PR 하나)을 승인했다(design-docs `repo-structure/README.md` 3.4절). 바꾼 것은 넷이다. 커밋도 하나씩이다. 1. `85f941c4` 아무도 읽지 않는 산출물 13개를 지우고 `artifacts/`를 폴더째 무시한다. - 지운 것: `artifacts/local-preview/`의 화면 캡처 3개, `artifacts/tests/coverage-gateway/`의 커버리지 HTML 10개. 0929 리뷰 14-01이 찾았고, 그 뒤 리뷰 네 번 내내 '일부'로 남았다. - `.gitignore`는 확장자별 규칙을 버리고 폴더째 무시한다. 남기는 추적 파일은 `.gitkeep` 2개와, 사람이 쓰고 a11y 게이트가 읽는 수동 검토 기록 `artifacts/tests/a11y-manual/*.md` 10개뿐이다. - `tests/unit/tracked-artifacts.test.ts`가 이 목록을 지킨다. 목록 밖 파일이 추적되면 `test:unit`이 실패한다. 2. `0805910c` 아무도 읽지 않는 `config/schemas/`의 JSON Schema 4개를 지운다. - 산출물 검사는 `scripts/contracts/release-artifacts.ts`의 zod가 한다. 4개 모두 zod 정본과 대조한 결과는 커밋 본문에 있다. - 그런데도 2026-11-05에 손으로 고친 일이 있었다(`81701ad`). 읽는 곳 없는 사본을 맞추는 일이 이미 생기고 있었다. 3. `429b8d88` 루트의 `tasks/`와 `.superpowers/` 기록을 `docs/history/`로 옮긴다. - `tasks/` 5개 → `docs/history/plans/2026-09-25-review-fix-round/`(`lanes/` 유지) - `.superpowers/` 보고 1개 → `docs/history/evidence/2026-08-01-runtime-correctness-remediation/` - `.md` 5개 맨 위에 design-docs `conventions/docs-system.md` 4.1절의 머리 블록(9줄)을 달았다. 블록을 빼면 원문과 바이트가 같다. `setup-lane.sh`는 실행 파일이라 머리 블록 없이 100% rename으로 옮겼다(권한 100755 유지). - `docs/README.md` 지도에 `history/` 행(옛 경로 → 새 경로)과 「기록 문서의 머리 블록」 절을 더했다. 루트 `README.md`의 지울 수 있는 파일 행도 고쳤다. - `tests/unit/deletable-history-documents.test.ts`는 이제 `docs/history`를 읽는 코드도 막는다. 루트 `tasks/` 패턴은 지켜야 할 폴더가 없고 제품의 `tasks/` 경로 문자열을 잘못 잡을 수 있어 뺐다. 4. `121e1125` nginx 설정 예시를 지우고 호스트가 지킬 조건만 남긴다. - `docs/operations/release-cache-rollback.md`의 「Example: nginx on a single server」(nginx 설정 77줄)를 지웠다. 그 자리에 「운영 환경이 지켜야 할 조건」 19개를 문장으로 두었다. 조건마다 FE-GATE-019가 재는지, 아무도 재지 않는지를 적었다. 값의 정본은 `config/hosting/*.json`이다. - 지운 설정을 한 줄씩 조건 번호에 대응시킨 표는 커밋 본문에 있다. - `docs/architecture/static-delivery.md`의 nginx 링크는 이 조건 절을 가리킨다. - `docs/operations/ci-quality-gates.md`의 runner 요구 문장은 남겼다. 호스트를 바꾸는 AppArmor profile 본문과 `sysctl` 줄만 지웠다. 고치는 방법은 `scripts/check-system-test-prerequisites.ts`가 출력한다. ## 고른 방법과 버린 대안 - nginx 설정은 다른 repo(project-infra, cicd-platform)로 복사하지 않고 지웠다. - 백엔드도 같은 날 "인프라 실행 파일은 지우고, 운영 환경에 요구하는 조건만 문서로 남긴다"로 정했다. - 아무도 시험하지 않는 설정 사본을 다른 repo에 만들면 갈라진 복사본이 하나 더 생긴다(S4 가정 F5). - S4 문서는 "project-infra로 옮긴다"였다. 이 판단은 프론트 총괄이 바꿨고, 백엔드 총괄이 동의했다. - `.gitignore`는 흔한 꼴인 `artifacts/**` + `!artifacts/**/`를 쓰지 않았다. `scripts/verify-documentation-readiness.ts`가 `.gitignore`를 직접 해석하는데, 그 꼴은 그 해석에서 모든 산출물을 되살린다. 그래서 폴더마다 다시 넣고 다시 무시하는 꼴로 썼다. - `config/schemas/` 4개는 `schemas/`로 옮기거나 zod에서 생성하지 않았다. 읽는 곳이 없는 파일을 옮기거나 생성하면 지킬 것 없는 사본이 하나 더 생긴다. 스키마 자리를 한 곳으로 모으는 일은 3단계다. - 기록 문서 안의 옛 경로(`docs/superpowers/plans/2026-08-02-*.md`, `docs/reviews/2026-09-25-maturity-review/`)는 고치지 않았다. 기록은 본문을 고치지 않는다(docs-system 1절). `docs/README.md` 지도에 옛 경로 → 새 경로를 적었다. ## 위험과 영향 - **`SPEC.md`는 이 PR에서 옮기지 않았다.** 소유자 결정은 "`SPEC.md`·`tasks/`·`.superpowers/`는 이력 폴더로 옮긴다. `SPEC.md`의 공통 완료 기준은 먼저 매뉴얼로 옮긴다"이다. 그 기준이 갈 작업 매뉴얼 `docs/work/improve.md`는 이 프로그램의 뒤 단계에서 만든다. 그래서 **`SPEC.md` 이동은 `docs/work/improve.md`를 만드는 단계의 brief에 넣는다.** 그때까지 `SPEC.md:17`, `:60`, `:67`은 `tasks/`의 옛 경로를 가리킨다. - 호스트에서 아무도 재지 않는 조건이 19개 중 11개다(7, 8, 10, 11, 12, 13, 15, 16, 17, 18, 19번). FE-GATE-019는 200 응답, 진입 스크립트 하나, 확장자별 첫 파일 하나만 본다. 오류 응답의 헤더, 나머지 파일의 캐시·압축, 404 동작, 전환 도중 섞임, 롤백 결과는 재지 않는다. 지운 nginx 예시도 CI가 돌리지 않았으므로, 잃은 검사는 없다. 재는 범위를 넓히는 일은 따로 남는다. - `verify:documentation`이 `.gitignore`를 git과 같게 읽는다는 가정이 생겼다. 기존 시험과 `verify:documentation` 통과로만 확인했다. `.gitignore`를 다시 바꿀 때는 그 해석기도 같이 본다. - `tracked-artifacts.test.ts`는 시험 환경에 git이 있다고 가정한다(`git ls-files`). - 다운스트림(tech-log, memento)은 지운 파일을 고치지 않았으면 그대로 받는다. `CHANGELOG.md` 줄은 2단계 PR에서 1단계와 함께 적는다. - `docs/README.md` 「기록 문서의 머리 블록」 절은 문서 체계 프론트 적용(docs-system 9.2절)의 일부를 먼저 넣은 것이다. ## 검증 하위 세션이 desktop에서 끝 트리(`30a379f`, 트리가 `121e1125`와 같다)로 돌렸다. 로그는 desktop `~/l1-layout-cleanup-logs/`에 있다. | 명령 | 결과 | |---|---| | `corepack pnpm check:architecture` | exit 0 | | `corepack pnpm check:types` | exit 0 | | `corepack pnpm lint` | exit 0 | | `corepack pnpm test:unit` | exit 0, 212 files, 3,091 tests | | `corepack pnpm verify:documentation` | exit 0, PASS_SCOPED | | `corepack pnpm check:ci` | exit 0 | | `corepack pnpm check:adapter-inventory` | exit 0 | | `git grep -n '^```nginx'` | 0줄 | 새 시험이 실패를 잡는지도 봤다: - `tracked-artifacts`: 지운 png 3개를 되돌리면 exit 1, 목록 밖 `note.txt`를 `git add -f`하면 exit 1 - `deletable-history-documents`: 코드가 `docs/history`를 읽게 하면 exit 1 merge 게이트 14개는 총괄이 desktop에서 `121e1125`로 돌렸다(`ci:gate`, workflow와 같은 CI 환경 변수). 로그는 desktop `/tmp/claude-gates/121e112-ci/`, `/tmp/claude-gates/121e112-013-parts/`에 있다. | 게이트 | 결과 | 시간 | |---|---|---| | FE-GATE-001~012 | 모두 rc=0 | 005 135s, 008 201s, 010 63s | | FE-GATE-020 | rc=0 | 1,258s | | FE-GATE-013 | rc=1, 사전 점검에서 멈춤 | 2s | FE-GATE-013은 이 변경과 상관없는 호스트 제약이다. desktop이 비특권 user·network namespace를 막아서(`kernel.apparmor_restrict_unprivileged_userns=1`, `bwrap: loopback: Failed RTM_NEWADDR`) 사전 점검이 멈춘다. PR #8과 같은 상태다. 사전 점검 뒤 부분을 따로 돌린 결과: - `tests/system`: 115건 중 97건 통과. 실패 18건은 모두 `tests/system/ci-runner…`의 provider sandbox(bwrap) 테스트다. - 나머지 명령 7개(`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이다. 실행 뒤 desktop checkout은 `fix/maturity-review-2026-11-03`으로 돌아갔고 `git status`가 비어 있다. ## 리뷰어가 볼 곳 - `.gitignore`: 폴더마다 다시 넣고 다시 무시하는 꼴. 새 산출물 폴더가 생겨도 추적되지 않는지. - `docs/operations/release-cache-rollback.md:130` 「운영 환경이 지켜야 할 조건」: 지운 설정의 요구가 빠짐없는지, "재는 쪽" 판정이 FE-GATE-019 코드(`scripts/verify-hosting-headers.ts`, `scripts/lib/hosting-probe.ts`)와 맞는지. - `docs/history/` 머리 블록 5개: 상태·작성일·현재 정본 칸. ## 관련 - 기준: main `48c7695b`(PR #5·#7·#8·#9 병합 뒤). - 정본: design-docs `repo-structure/04-frontend-layout.md`(S4), `repo-structure/README.md` 3.4절, `conventions/docs-system.md`. - 다음: 2단계(샘플 역할 이전·삭제)는 이 브랜치 위에 쌓는다.
donghyeon.kang added 4 commits 2026-11-07 15:13:49 +00:00
문제: .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단계
문제: config/schemas/에 산출물 JSON Schema 4개가 있다. 코드·테스트·
workflow·문서 어디서도 경로나 $id(ART-FE-FIELD-WEB-VITALS@1,
ART-FE-LAB@1, ART-FE-003@1, ART-FE-RUNBOOK-DRILL@2)로 읽지 않는다
(git grep, CHANGELOG·리뷰 기록 제외). 산출물을 실제로 검사하는 것은
scripts/contracts/release-artifacts.ts의 zod schema다. 그런데도
81701ad(2026-11-05)가 lab 칸을 더하면서 이 파일도 손으로 고쳤다. 읽는
곳 없는 사본을 맞추는 일이 생긴다.

schemas/의 생성 스키마와 비교: scripts/generate-artifact-schemas.ts가
만드는 4개(build-manifest, dependency-inventory, registry-snapshot,
supply-chain-verification)와 이름·대상이 겹치는 것이 없다. 그래서 각
파일을 그 산출물의 zod 정본과 대조했다.
- field-web-vitals ↔ fieldWebVitalsArtifactSchema: 최상위 칸 9개와
  context 칸 9개가 같다. zod가 더 엄격하다(window.days = 28,
  consentRequired = true, 숫자 범위, 하위 객체 strict).
- lab-performance ↔ labPerformanceArtifactSchema: zod는 context·metrics를
  아무 객체로 받는다. JSON만 context 필수 칸 7개, metrics 필수 칸 5개,
  fixtures 2개 이상을 적었다. context 칸 7개는
  scripts/lib/performance-budgets.ts evaluateLabBudget가 없으면 실패로
  판정한다. metrics 5칸과 fixtures 3개는 scripts/test-performance.ts가
  늘 만든다.
- release-verification ↔ releaseVerificationArtifactSchema: zod가 더
  엄격하다(artifact.releaseId 필수, fixture 칸 strict). JSON만 fixtures
  2개 이상을 적었다. scripts/verify-release.ts는
  config/release/coherence-fixtures.json의 4개를 쓴다.
- runbook-drill-record ↔ runbookRecordArtifactSchema: 칸이 같다. zod는
  result가 판정들의 합과 맞는지도 본다. JSON만 recoveryAssertions 4개
  이상을 적었다. scripts/drill-runbook.ts의 runbook 5개는 모두 4개를
  만든다.
JSON에만 있는 최소 개수 셋은 지금 만드는 쪽이 늘 채우지만 아무도
검사하지 않는다. 이 파일도 읽는 곳이 없어 지워도 검사가 줄지 않는다.

버린 대안: schemas/로 옮기거나 zod에서 생성하기. 읽는 곳이 없는 파일을
옮기거나 생성하면 지킬 것 없는 사본이 하나 더 생긴다. 스키마 자리를 한
곳으로 모으는 일은 3단계(schemas/ → config/schemas/)다.

위험·한계: 다운스트림이 이 파일을 외부 도구에 물렸다면 그쪽이 끊긴다.
템플릿 안에는 그런 곳이 없다.

검증: git grep으로 경로와 $id 넷을 찾아 0건(CHANGELOG·리뷰 기록 제외).
desktop(네 커밋의 끝 30a379f, 로그 ~/l1-layout-cleanup-logs/):
check:types, test:unit(212 files, 3091 tests), check:ci, lint exit 0.

Refs: design-docs repo-structure/04-frontend-layout.md 2.1절, 9.2절
문제: 끝난 작업의 기록이 루트 폴더 둘에 따로 있다. tasks/는 2026-09-25
리뷰 수정 라운드(v0.2.0으로 끝남)의 계획·작업 목록·인계·레인 지시서와
레인 준비 스크립트 5개, .superpowers/는 2026-08-01 런타임 정합성 수정의
작업 보고 1개다. 읽는 코드는 없다(tests/unit/deletable-history-
documents.test.ts가 지킨다). 소유자가 2026-11-07 백엔드와 같이 이력
폴더로 옮기기로 정했다.

고른 방법:
- tasks/ → docs/history/plans/2026-09-25-review-fix-round/ (lanes/ 유지),
  .superpowers/sdd/2026-08-01-runtime-correctness-remediation/
  task-5-report.md → docs/history/evidence/2026-08-01-runtime-correctness-
  remediation/. 폴더 이름은 docs-system 2절과 백엔드를 따른다.
- .md 5개 맨 위에 docs-system 4.1절 머리 블록 9줄(빈 줄 포함, 백엔드와
  같은 모양)을 단다. 본문은 바꾸지 않았다: 블록 9줄을 빼면 옛 파일과
  바이트가 같다(cmp). setup-lane.sh는 실행 파일(첫 줄 shebang)이라 블록을
  달지 않고 그대로 옮긴다(R100). 같은 폴더 LANE-BRIEF.md의 블록이 그
  파일을 설명한다.
- 상태: 계획서 넷은 끝남. 기계 규칙(체크 상자가 모두 표시돼야 끝남)으로는
  plan·todo가 확인 안 함이지만, 이력이 라운드의 끝을 정한다(CHANGELOG
  0.2.0, 태그 v0.2.0 2026-09-27). 증거는 보관.
- 작성일: plan·todo는 2026-09-25. git이 처음 더한 날(ea0f01f,
  2026-09-24)은 이 파일이 앞 라운드(src 리뷰) 계획이던 때이고, 지금
  본문은 c5f379b(2026-09-25)가 통째로 다시 썼다. handoff는 본문 날짜 줄
  (2026-09-26 01:10), LANE-BRIEF는 git이 처음 더한 날(54ba358,
  2026-09-26), 보고는 git이 처음 더한 날(d9afccd, 2026-08-02).
- docs/README.md: 3절 지도에 history/ 행을 더하고 옛 경로 → 새 경로를
  적는다. 블록 첫 줄이 가리키는 「기록 문서의 머리 블록」 절(4절)을
  더한다. ../tasks/ 링크는 없앴다. README.md의 "Files you can delete
  after copying" 행도 docs/history/로 바꾼다.
- deletable-history-documents.test.ts: docs/history 패턴을 더하고
  tasks/ 패턴은 뺀다. 루트 tasks/가 없어져 그 패턴이 지킬 문서가 없고,
  남기면 제품의 "tasks/..." 라우트·폴더 문자열을 잘못 잡는다.
버린 대안: 옮긴 파일을 가리키는 다른 기록(docs/superpowers/plans/
2026-08-02-*.md, docs/reviews/2026-09-25-maturity-review/, SPEC.md)의
옛 경로를 고치기. 기록 본문은 고치지 않는다(docs-system 1절). 대신 지도
행에 옛 경로를 적었다.

위험·한계: SPEC.md는 이번에 옮기지 않는다. 27~37줄 「공통 완료 기준」을
작업 매뉴얼(docs/work/improve.md, 뒤 단계)로 옮긴 뒤 같은 폴더로 보낸다.
secret-scan-policy.json의 trackedRoots와 루트 경로 목록 7곳에는 tasks,
.superpowers가 없어 바꿀 것이 없다.

검증:
- 옮긴 .md 5개: 첫 9줄을 빼면 옛 파일과 cmp가 같다. git diff -M이
  R091~R100 rename으로 잡고 지운 줄은 0이다.
- desktop(네 커밋의 끝 30a379f, 로그 ~/l1-layout-cleanup-logs/):
  deletable-history-documents.test.ts는 지금 트리에서 통과하고, 테스트
  폴더에 "docs/history/plans"를 담은 파일 하나를 두면 그 줄을 내며
  실패한다. verify:documentation: PASS_SCOPED. test:unit 3091 tests 통과.

Refs: design-docs repo-structure/04-frontend-layout.md 2.1절, 9.2절;
design-docs conventions/docs-system.md 2·4절
문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로
있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single
server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이
아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도
호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다.

고른 방법:
- nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를
  문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live
  모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은
  절 이름·같은 언어(한국어)다.
- 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7;
  listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types →
  10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17;
  index.html → 3·6; try_files fallback → 4·6; config.json·
  release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18;
  없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15;
  .map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / →
  1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19.
- static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다.
- ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권
  user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는
  방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은
  scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로
  바꾼다. 그 스크립트가 같은 세 방법을 출력한다.
버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기.
아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다).

위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일,
10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의
전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니
재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서
없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다.

검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그
~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의
경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함),
test:unit 3091 tests 통과.

Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
donghyeon.kang merged commit f33e4778bb into main 2026-11-07 15:14:49 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#11