docs: 문서 체계를 백엔드와 같게 하고 살아 있는 문서를 한국어로 옮긴다 #15

Merged
donghyeon.kang merged 20 commits from donghyeon.kang/claude/fe-b-docs-korean-645f55 AGit into main 2026-11-11 21:51:57 +00:00
Owner

무엇을, 왜

소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.2절·3.4절 D5): 두 템플릿의 살아 있는 문서는 본문까지 한국어로 쓰고, 기록은 수명으로 나눠 docs/history/·docs/design/·docs/adr/에 한국어 머리 블록을 달아 둔다. 백엔드는 끝났고(main), 프론트는 README와 입구 문서가 영어였고 docs/README.md는 "README와 입구 문서는 영어"라는 반대 규칙을 적어 두었다.

이 PR은 정본 design-docs conventions/docs-system.md v1을 프론트에 적용한다.

  1. 분류: docs/**와 루트·src·artifacts의 .md 243개를 살아 있는 문서·결정 기록·설계서·기록·리뷰로 나눴다(아래 분류표). 하네스 PR #13이 더한 문서(AGENTS.md, src/*/AGENTS.md, .claude/, docs/work/, docs/ledger/, 양식 둘)는 그 PR이 분류했고 모두 살아 있는 문서다.
  2. 옮기기: 설계서 25개 → docs/design/, 계획서 19개 → docs/history/plans/(먼저 옮긴 4개와 합쳐 23개), VD 23개 → docs/adr/(번호 유지). 기록 67개에 머리 블록을 달고 본문은 고치지 않았다(옮겨서 깨진 상대 링크의 대상만 고쳤다). SPEC.md의 공통 완료 기준은 하네스 PR #13이 작업 매뉴얼 docs/work/improve.md 5절로 옮겼고, 그 뒤 SPEC.md를 그 라운드 계획서 옆으로 옮겼다(D5). 이 브랜치가 먼저 만든 사본 docs/manual/reference/done-criteria.md는 겹쳐서 지웠다. 루트 항목 등록부는 프론트에 없다.
  3. 번역: 살아 있는 문서 41개를 고쳤다(하네스 문서의 경로·검사 범위 줄 고침은 따로 센다). 그중 약 30개가 영어였거나 영어 문단을 가졌다(약 3,500줄을 새로 씀). 루트 README는 6.1절 필수 절 순서로 다시 썼고(「프로젝트 구조」「문서 지도」 포함, 「복사한 뒤 지워도 되는 것」 유지), docs/README.md는 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·검사 규칙으로 다시 썼다. 설정 파일 5개의 설명 칸 260개도 옮겼다(읽는 코드를 먼저 확인).
  4. 검사: verify:documentation(FE-GATE-017, merge 단계)이 언어·머리 블록·숫자 복사·문서 지도·README 절·문체를 PR 단계에서 실패로 본다. 참조 검사(경로·링크·script·게이트 ID)는 살아 있는 문서 전부로 넓혔다. 예외 목록은 비어 있다.

결과: 살아 있는 문서의 영어 문서 0, 머리 블록·상태 칸 없는 기록 0, 깨진 링크·없는 인라인 경로 0(살아 있는 문서 기준).

고른 방법과 버린 대안

검사를 어디에 두나 — verify:documentation 안에 TypeScript로 옮김(권함, 고름).

  • 백엔드 scripts/check-docs.py의 규칙 여섯(language·head·number·map·readme·style)을 같은 이름·문턱·예외 의미로 scripts/lib/docs-system.ts에 옮겼다. verify-documentation-readiness.ts가 부른다.
  • 참조·링크 검사는 새로 만들지 않고 이미 있는 것(짝 백엔드 pin 트리 조회, 지운 샘플·생성 산출물·지운 기록 허용)을 그대로 쓰고 대상만 넓혔다. 같은 검사를 두 벌 두지 않으려는 것이다.
  • 버린 안 1 — 새 게이트·package script 추가: config/ci/gates.json과 CI 계약의 개수·해시(contract-baseline.json), workflow 생성물을 바꿔야 한다. 그 파일은 같은 시간에 도는 정리 3단계·CI 세션의 범위다.
  • 버린 안 2 — check-docs.py를 그대로 복사: 프론트 도구와 CI 이미지는 Node뿐이다. 참조 검사의 프론트 쪽 규칙(지운 샘플, pin)이 TS에 이미 있어 두 언어로 갈라진다.
  • 프론트에만 있는 차이(근거는 코드 주석):
    • VD는 처음부터 한국어로 썼고 번역하지 않았으므로 결정 기록 머리 문구는 「원문이다」 쪽을 쓴다(번역 문구도 받는다, docs-system 4.1).
    • docs/reviews/adapters/INVENTORY.md는 리뷰 폴더 안이지만 check:adapter-inventory가 대조하는 살아 있는 목록이라 살아 있는 문서로 본다.
    • artifacts/tests/a11y-manual/*.md는 정해진 영어 키 형식의 게이트 입력이라 문서로 보지 않는다(백엔드의 resources 예외와 같은 뜻).
    • docs/architecture/review-evidence.md는 다른 작업 공간 경로를 적은 2026-07-18 리뷰 사본이라 참조·숫자 검사에서 뺀다(CHANGELOG.md와 같은 HISTORY_HOLDERS).
    • 숫자 검사는 Spring Boot 대신 package.json·.nvmrc의 프레임워크 버전과 게이트·recipe·adapter 개수를 본다.
    • 복사한 프로젝트가 docs/history/를 지워도 지도 검사가 통과하도록 README 「복사한 뒤 지워도 되는 것」의 경로를 지도 검사도 받는다.

목표 설계 문서(docs/architecture/의 14개, styling·testing의 2개)를 설계서로 분류해 옮김. 기존 docs/README.md가 이미 "목표 설계 — 구현됐다는 뜻이 아니다"로 나눠 두었고, 02-docs.md W5가 "architecture/ 목표 설계 분리"를 정했다. 살아 있는 문서로 남기면 약 16,500줄을 번역하고 계속 코드에 맞춰야 한다. 버린 안: 제자리에 두고 번역. backend-api-and-server-state-contract.md는 4.1·6·6.1절이 실행 규칙이고 pin·테스트가 읽어서 살아 있는 문서로 남겼다.

원장(operations/adapter-remediation-ledger.md)은 살아 있는 문서로 둠. config/ci/ungated-scripts.json은 "history record"라 부르지만 check:remediation-ledger가 시험 파일 표식과 대조해서 테스트를 옮기면 같이 고쳐야 한다. 그리고 docs/history/는 코드가 읽지 않는다는 약속(tests/unit/deletable-history-documents.test.ts)이 있어 코드가 읽는 파일을 둘 수 없다. 같은 이유로 review-ledger.json·review-evidence.md도 제자리다.

PR 단계에서 실패하게 하는 곳. verify:documentation의 CI job(FE-GATE-017 documentation_gate)은 workflow_dispatch로 documentation 단계를 고를 때만 돈다. 그래서 merge 단계 FE-GATE-005의 tests/unit/documentation-readiness.test.ts에 「이 repo 그대로 verify:documentation을 한 번 돌려 통과」 시험을 더했다. 버린 안: FE-GATE-017을 merge 단계로 옮기는 것(config/ci/gates.json과 CI 계약 기준선, workflow 생성물을 바꾼다. 정리 3단계·CI 세션이 merge job을 셋으로 합치는 중이라 그쪽이 정할 일이다). 이 시험은 제거 드릴 사본에서는 돌지 않는다(그 파일은 scripts/lib/removal-fixture.ts의 문서 시험 목록에 이미 있다).

커밋 순서는 이동(내용 변경 없는 git mv) → 참조 수정 → 완료 기준 → SPEC 이동 → 머리 블록 → 링크 보정 → 검사(+입구 문서) → 번역 3묶음 → 설정 → CHANGELOG → main 합치기(하네스 PR #13) → 하네스 문서 맞추기 → 완료 기준 사본 지우기 → 줄임표 자리표시자 → 지도 링크 정리 → 시험 시간 한도 → main 합치기(PR #14·#16) → CHANGELOG다. PR을 연 뒤라 force push 없이 main을 merge로 받았다(brief가 force push를 금한다). 검사 커밋은 아직 옮기지 않은 문서 42줄을 예외 기준선(FROZEN 지문)으로 두고, 번역 커밋마다 줄을 지워 마지막에 0이 된다(백엔드와 같은 "줄기만 하는" 방식). README와 그 src 폴더 설명을 글자로 대조하는 layers.md·overview.md·foundation.md는 검사 커밋에 같이 넣었다.

위험과 영향

  • 파생 서비스(BREAKING): 이 범위를 받으면 자기 살아 있는 문서가 영어거나 「~합니다」 체면 verify:documentation이 실패한다. 옛 문서 경로를 가리킨 자기 문서도 깨진다. CHANGELOG.md 정리 단계 미출시 절 「먼저 할 일」 7·8과 옛 경로 찾기 명령을 적었다. 두 다운스트림에 받아 보지는 않았다.
  • 중간 커밋: 이동 커밋(99e76e87)은 내용을 바꾸지 않아 링크가 깨진 채다(의도). 커밋별 결과는 아래 「검증」에 있다.
  • 하네스 PR #13과 합친 것: main(d1b9c087)을 merge로 받았다. 충돌은 README.md·docs/README.md 둘이었고, 이 브랜치의 한국어 판에 #13이 더한 AGENTS.md·docs/work/·docs/ledger/·docs/vision.md·docs/problem-statement.md 줄과 지워도 되는 표 행을 넣었다. #13이 더한 살아 있는 문서(AGENTS.md, src/*/AGENTS.md, .claude/, docs/work/, docs/ledger/, 양식 둘)는 모두 이 검사를 통과한다. 다만 그 문서 중 문서 체계를 설명하는 줄(옛 경로, 「docs/README.md 1절 묶음」이라는 옛 검사 범위, README의 옛 절 이름)은 이 PR이 고쳤다(docs(work) 커밋). #13의 template-contract-documents 시험은 지워도 되는 표를 docs/history/ 행으로 찾게 바꿨다. docs/work/evidence.md는 백엔드처럼 근거 기록이라 참조·숫자 검사에서 뺐다.
  • 새로 살아 있는 문서가 된 하네스 파일 하나가 경로 검사에 걸렸다: scripts/hooks/README.md의 node scripts/…. 줄임표 「…」를 자리표시자로 보게 경로 검사를 고쳤다(문서 검사 쪽은 이미 그랬다). 그리고 docs/README.md가 제거 드릴 사본에 없는 루트 CLAUDE.md를 링크해 사본에서 실패해서 링크를 이름으로 바꿨다.
  • 정리 3·4단계 PR #14와 CI 재편 PR #16: main(38c0dc7d)을 다시 merge로 받았다(e9e98b8a). 충돌 아홉 파일은 두 PR이 영어 판에서 바꾼 것을 이 PR의 한국어 판에 넣어 풀었다: a11y 기록 경로(docs/accessibility/route-reviews/, 문서 검사의 NOT_DOCUMENT도 따라 바꿈), merge job 셋과 지운 CI 계약 기준선, main 단계 FE-GATE-029, 합친 음성 fixture script, config/schemas/. #14의 배치 규칙 검사(R6·R7)는 「현재 문서」를 문서 검사의 checkedForDrift로 고른다. 루트 등록부 config/repository-layout.json의 SPEC.md 항목(「문서 체계 작업이 이력 폴더로 옮기고 이 항목을 뺀다」)을 뺐다. #14가 옛 경로의 테스트 전략 문서를 고친 것은 이름 바뀜을 따라 기록(docs/design/)에 들어와서, 기록은 옮길 때의 글로 되돌렸다. config/ci/는 이 PR이 고치지 않았다(그래서 ungated-scripts.json reason은 아직 영어다).
  • 생성 코드 주석: create-feature.ts가 만드는 context-module.ts JSDoc의 인용 절 이름이 「소유 선언」으로 바뀐다. 그 글자를 비교하는 테스트는 없다.
  • 판단이 필요한 상태 값: VD-09·11·13은 git으로 보면 결정 뒤 본문이 고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 「채택」이다. 「채택(보완)」으로 올릴지는 소유자 판단이다. 상태 줄이 없던 설계서 21개·계획서 14개는 「확인 안 함」이다.
  • 번역하며 찾은, 고치지 않은 낡은 내용(번역은 뜻을 바꾸지 않는다는 규칙 때문, 후속): contract-ownership.md의 계약 파일 "39개"(지금 44개), capability-consumer-experience.md의 Local Draft 두 번째 소비자 서술(지금은 fixture), static-delivery.md의 "예시 feature 기준" 초기 JS, .dependency-cruiser.json:254의 layers.md §4(번호 없는 문서), FE-RB-002 제목과 runbooks.json title 차이, ci-quality-gates.md의 zod 고친 버전 4.6.6과 이유 칸 4.6.7, 같은 문서 FE-GATE-016 문단의 자리가 어긋난 두 문장, scripts/drill-runbook.ts 복구 항목 이름(영어)과 runbooks.json(한국어)의 언어 차이. 기록 안의 깨진 상대 링크 22개는 옮기기 전부터 깨져 있었고 기록이라 두었다.

검증

desktop에서 workflow env(CI=true, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE)로 돌렸다. merge 단계는 scripts/verify.sh merge --on here, 무거운 실행은 flock /tmp/claude-gates/heavy.lock으로 감쌌다. 그 시각 desktop은 여러 세션이 함께 써서 load가 9~25였다.

main 38c0dc7d(PR #13·#14·#16)을 받은 head — merge 단계 e9e98b8a, 다시 돌린 것 bbbc6abd(CHANGELOG 커밋 하나 차이)

게이트 rc 메모
FE-GATE-001 manifest-lockfile 0
FE-GATE-002 lint 0
FE-GATE-003 typecheck 0
FE-GATE-004 runtime-schema 0
FE-GATE-005 unit 0
FE-GATE-006 component 0
FE-GATE-007 integration 0
FE-GATE-008 e2e 0 e9e98b8a에서 firefox old-tab-chunk-recovery 하나가 시험 서버 연결 거부(ECONNREFUSED)로 실패. bbbc6abd 다시 돌려 0
FE-GATE-009 accessibility 0
FE-GATE-010 architecture 0
FE-GATE-011 build 0
FE-GATE-012 bundle 0
FE-GATE-013 security 1 desktop 호스트 조건(알려짐, docs/work/reference/gates.md 3절). verify.sh parts FE-GATE-013: test:system만 사전 조건(bwrap RTM_NEWADDR)에서 멈추고 나머지 명령은 0
FE-GATE-020 removability 0 e9e98b8a에서 기능 생성 드릴 안 coverage 실행의 provider-guardian-transaction(소켓 시험) 하나가 실패. 따로 두 번 돌리면 22/22 통과. bbbc6abd 다시 돌려 0
FE-GATE-029 checker-self-tests (main 단계) 0
verify:documentation (FE-GATE-017) 0 문서 검사 여섯 걸림 0, 예외 0
check:remediation-ledger (게이트 밖) 0
scripts/verify.sh docs, scripts/verify.sh hooks OK 하네스 검사기와 훅 시험
실행 뒤 git status 바뀐 파일 0
  • 앞서 하네스 PR #13만 받은 head(5f10f928·7b09c215)에서도 merge 단계를 돌렸다. 그때 실패한 것과 처리: FE-GATE-009 firefox axe 시험 시간 초과(다시 돌려 0), FE-GATE-020 기능 생성 드릴 안 documentation-readiness 사례 셋 10초 초과(이 PR의 원인. 7b09c215에서 시간 한도 60초), 같은 게이트의 extreme-scale-registry 증가율 측정(따로 돌리면 통과·실패·통과로 흔들림, 다시 돌려 0).
  • 위 다시 돌린 실패들은 모두 부하가 큰 때 시간·연결에 민감한 시험이고, 이 PR이 바꾼 코드(문서, 문서 검사기, 그 시험)와 닿지 않는다. 문서 시험의 시간 초과만 이 PR 탓이었고 고쳤다.
  • 문서 시험 12파일 108개 통과(docs-system, documentation-readiness, template-feature-removal-documents, deletable-history-documents, template-contract-documents, feature-tracked-files, backend-contract-pin-document, changelog-review-ids, runbook-contract, json-schema, repository-layout, manual-a11y-evidence).
  • 줄임표 고침(743f6fcc)은 RED→GREEN을 봤다: 고치기 전 verify-documentation-readiness.ts로 자리표시자 사례가 실패하고, 고친 뒤 통과한다.
  • 검사기 자기 시험 tests/unit/docs-system.test.ts: 판정 조건마다 그 조건만 잡는 실패 입력이 있다.
  • 커밋별: 11-08 실행에서 검사 커밋(7a9aefdf)부터 그 위 커밋까지 verify:documentation 0·문서 시험 0. 이동만 담은 커밋(99e76e87)부터 링크 보정(2b8a348c)까지는 의도적으로 깨진다. merge 뒤 커밋은 위 표가 head 기준이다.

리뷰어가 볼 곳

  • scripts/lib/docs-system.ts, scripts/verify-documentation-readiness.ts(참조 대상 확대, 「복사한 뒤 지워도 되는 것」 읽기), tests/unit/docs-system.test.ts, tests/unit/deletable-history-documents.test.ts(검사기를 그 약속의 대상에서 뺀 이유)
  • README.md, docs/README.md, merge 커밋(fb446e47)과 하네스 문서를 맞춘 docs(work) 커밋
  • scripts/check-remediation-ledger.ts(절 제목 상수, 한국어 「모두 닫혔다」 대안)
  • scripts/verify-documentation-readiness.ts의 경로 후보 거르기(줄임표 「…」), tests/unit/documentation-readiness.test.ts의 VERIFY_TIMEOUT
  • 기계적으로 만든 부분: 이동(git mv, 매핑은 커밋 99e76e87 본문), 링크 다시 쓰기(옮기기 전 트리 ad3a071f로 대상을 풀어 새 위치 기준 상대 경로로), 머리 블록(파일마다 값을 정한 표로 삽입, 블록을 빼면 원문 바이트가 같다), 예외 기준선(커밋마다 그 트리에서 검사기를 돌려 생성). 번역은 영역별로 나눠 했고 파일마다 검사기와 python 대조(백틱·링크·코드 블록·번호 제목)로 확인했다. 이동·링크·머리 블록·번역이 한 PR이라 크다(커밋·PR 규칙 5.1절의 기계적 변경 예외). 커밋 단위로 보면 된다.

관련

분류표 (파일마다)
종류 수
살아 있음 46
결정 기록 23
설계서 25
기록·계획서 23
기록·증거 1
문서 아님(게이트 입력) 3
기록·리뷰(제자리) 122
종류 지금 경로 옛 경로 상태(머리 블록) 처리
살아 있음 CHANGELOG.md 제자리, 이미 한국어(이 단계 항목과 README 절 이름만 고침)
살아 있음 CLAUDE.md 제자리, 이미 한국어
살아 있음 PRODUCT.md 제자리, 한국어로 옮김
살아 있음 README.md 제자리, 한국어로 다시 씀
살아 있음 docs/README.md 제자리, 한국어로 다시 씀
살아 있음 docs/accessibility/manual-checklist.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/backend-api-and-server-state-contract.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/capability-consumer-experience.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/contract-ownership.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/frontend-application-foundation.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/layers.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/optional-adapter-recipes.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/overview.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/review-evidence.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/scale-architecture.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/starter-experience.md 제자리, 한국어로 옮김
살아 있음 docs/architecture/static-delivery.md 제자리, 한국어로 옮김
살아 있음 docs/contracts/compatibility.md 제자리, 한국어로 옮김
살아 있음 docs/manual/01-add-a-feature.md 제자리, 이미 한국어(경로·인용만 고침)
살아 있음 docs/manual/02-decision-tables.md 제자리, 이미 한국어(경로·인용만 고침)
살아 있음 docs/manual/03-outside-feature-folder.md 제자리, 이미 한국어(경로·인용만 고침)
살아 있음 docs/manual/04-paired-backend-session.md 제자리, 이미 한국어
살아 있음 docs/manual/README.md 제자리, 이미 한국어(경로·인용만 고침)
살아 있음 docs/manual/reference/create-feature.md 제자리, 이미 한국어
살아 있음 docs/manual/reference/errors.md 제자리, 이미 한국어
살아 있음 docs/manual/reference/global-ids.md 제자리, 이미 한국어
살아 있음 docs/manual/reference/patterns.md 제자리, 이미 한국어(경로·인용만 고침)
살아 있음 docs/operations/adapter-remediation-ledger.md 제자리, 한국어로 옮김
살아 있음 docs/operations/api-contract-and-server-state-recovery.md 제자리, 한국어로 옮김
살아 있음 docs/operations/browser-file-storage-recovery.md 제자리, 한국어로 옮김
살아 있음 docs/operations/browser-transfer-recovery.md 제자리, 한국어로 옮김
살아 있음 docs/operations/ci-quality-gates.md 제자리, 한국어로 옮김
살아 있음 docs/operations/client-cache-and-storage-recovery.md 제자리, 한국어로 옮김
살아 있음 docs/operations/performance-evidence.md 제자리, 한국어로 옮김
살아 있음 docs/operations/release-cache-rollback.md 제자리, 한국어로 옮김
살아 있음 docs/reviews/adapters/INVENTORY.md 제자리, 이미 한국어
살아 있음 docs/runbooks/FE-RB-001.md 제자리, 한국어로 옮김
살아 있음 docs/runbooks/FE-RB-002.md 제자리, 한국어로 옮김
살아 있음 docs/runbooks/FE-RB-003.md 제자리, 한국어로 옮김
살아 있음 docs/runbooks/FE-RB-004.md 제자리, 한국어로 옮김
살아 있음 docs/runbooks/FE-RB-005.md 제자리, 한국어로 옮김
살아 있음 docs/security/browser-boundary.md 제자리, 한국어로 옮김
살아 있음 docs/security/supply-chain.md 제자리, 한국어로 옮김
살아 있음 docs/styling/design-tokens.md 제자리, 한국어로 옮김
살아 있음 docs/testing/taxonomy.md 제자리, 한국어로 옮김
살아 있음 src/adapters/browser-transfer/image-cdn/README.md 제자리, 한국어로 옮김
결정 기록 docs/adr/VD-01-typescript-lint-tooling.md docs/architecture/decisions/VD-01-typescript-lint-tooling.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-03-react-router-data-mode.md docs/architecture/decisions/VD-03-react-router-data-mode.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-04-native-form-facade.md docs/architecture/decisions/VD-04-native-form-facade.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-05-icon-and-headless-ui.md docs/architecture/decisions/VD-05-icon-and-headless-ui.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-06-intl-typed-message-catalog.md docs/architecture/decisions/VD-06-intl-typed-message-catalog.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-07-diagnostics-and-telemetry-exporter.md docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-08-storybook-and-visual-evidence.md docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-09-supply-chain-evidence.md docs/architecture/decisions/VD-09-supply-chain-evidence.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-10-optional-capability-recipes.md docs/architecture/decisions/VD-10-optional-capability-recipes.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-11-browser-file-and-origin-storage.md docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-12-presigned-transfer-and-image-cdn.md docs/architecture/decisions/VD-12-presigned-transfer-and-image-cdn.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-13-client-cache-scope-and-persistence.md docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-14-resumable-download-and-background-transfer.md docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-15-origin-storage-lifecycle-and-migration.md docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-23-api-transport-selection-and-rest-execution.md docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-24-runtime-schema-and-boundary-mapper.md docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-25-server-state-cache-lifecycle.md docs/architecture/decisions/VD-25-server-state-cache-lifecycle.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-26-persisted-graphql-operation.md docs/architecture/decisions/VD-26-persisted-graphql-operation.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-27-grpc-web-unary-and-server-stream.md docs/architecture/decisions/VD-27-grpc-web-unary-and-server-stream.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md 채택(보완) 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md docs/architecture/decisions/VD-29-connect-web-and-browser-protobuf-runtime.md 채택 옮김 + 머리 블록(본문 그대로)
결정 기록 docs/adr/VD-30-protobuf-contract-and-rest-gateway.md docs/architecture/decisions/VD-30-protobuf-contract-and-rest-gateway.md 채택 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-design-system-platform-design.md docs/styling/design-system-platform.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-frontend-platform-capability-review-design.md docs/architecture/frontend-platform-capability-review.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md docs/architecture/frontend-platform-implementation-roadmap.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-frontend-platform-testing-strategy-design.md docs/testing/frontend-platform-testing-strategy.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md docs/architecture/frontend-ports-adapters-and-boundaries.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-routing-pages-and-patterns-design.md docs/architecture/routing-pages-and-patterns.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-26-typescript-state-and-data-flow-design.md docs/architecture/typescript-state-and-data-flow.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-27-browser-file-and-origin-storage-design.md docs/architecture/browser-file-and-origin-storage.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md docs/architecture/api-contract-schema-mapper-and-server-state.md 채택 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-28-client-cache-and-storage-design.md docs/architecture/client-cache-and-storage.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md docs/architecture/protobuf-browser-transport-and-rest-gateway.md 채택 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-28-server-file-capability-infrastructure-design.md docs/architecture/server-file-capability-infrastructure.md 채택 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md docs/architecture/browser-data-capability-completion-ledger.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md 채택 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md docs/architecture/presigned-transfer-and-image-cdn.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md docs/architecture/realtime-events-web-push-and-bounded-polling.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-07-31-platform-overview-page-design.md docs/superpowers/specs/2026-07-31-platform-overview-page-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-08-01-refactoring-review-remediation-design.md docs/superpowers/specs/2026-08-01-refactoring-review-remediation-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-08-01-runtime-integrity-refactor-design.md docs/superpowers/specs/2026-08-01-runtime-integrity-refactor-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-08-02-platform-owned-frontend-assurance-delivery-design.md docs/superpowers/specs/2026-08-02-platform-owned-frontend-assurance-delivery-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-08-02-provider-raw-guardian-design.md docs/superpowers/specs/2026-08-02-provider-raw-guardian-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-08-02-v8-coverage-counter-contract-design.md docs/superpowers/specs/2026-08-02-v8-coverage-counter-contract-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-09-16-adapter-barrel-boundary-design.md docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-09-16-indexeddb-kernel-promotion-design.md docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
설계서 docs/design/2026-09-20-memento-frontend-template-bootstrap-design.md docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md 확인 안 함 옮김 + 머리 블록(본문 그대로)
기록·계획서 docs/history/plans/2026-07-31-platform-overview-completion.md docs/superpowers/plans/2026-07-31-platform-overview-completion.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-http-worker-adapter-remediation.md docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-quality-architecture-remediation.md docs/superpowers/plans/2026-08-01-quality-architecture-remediation.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-release-boot-integrity.md docs/superpowers/plans/2026-08-01-release-boot-integrity.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-release-evidence-remediation.md docs/superpowers/plans/2026-08-01-release-evidence-remediation.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-runtime-correctness-remediation.md docs/superpowers/plans/2026-08-01-runtime-correctness-remediation.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-01-scope-owned-server-state.md docs/superpowers/plans/2026-08-01-scope-owned-server-state.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-cicd-frontend-assurance-delivery.md docs/superpowers/plans/2026-08-02-cicd-frontend-assurance-delivery.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-counter-bearing-coverage-provenance.md docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md 끝남 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-frontend-platform-consumer-migration.md docs/superpowers/plans/2026-08-02-frontend-platform-consumer-migration.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-promotion-security-review-fixes.md docs/superpowers/plans/2026-08-02-promotion-security-review-fixes.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-provider-raw-guardian.md docs/superpowers/plans/2026-08-02-provider-raw-guardian.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-security-finalizer.md docs/superpowers/plans/2026-08-02-security-finalizer.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-test-assurance-frontend-capabilities.md docs/superpowers/plans/2026-08-02-test-assurance-frontend-capabilities.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-02-v8-coverage-counter-contract.md docs/superpowers/plans/2026-08-02-v8-coverage-counter-contract.md 끝남 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-08-13-adapter-remediation.md docs/superpowers/plans/2026-08-13-adapter-remediation.md 확인 안 함 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-09-16-adapter-barrel-boundary.md docs/superpowers/plans/2026-09-16-adapter-barrel-boundary.md 끝남 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-09-16-indexeddb-kernel-promotion.md docs/superpowers/plans/2026-09-16-indexeddb-kernel-promotion.md 끝남 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-09-25-review-fix-round/SPEC.md SPEC.md 끝남 옮김 + 머리 블록
기록·계획서 docs/history/plans/2026-09-25-review-fix-round/handoff.md 끝남 이미 옮김(정리 1단계), 머리 블록 있음
기록·계획서 docs/history/plans/2026-09-25-review-fix-round/lanes/LANE-BRIEF.md 끝남 이미 옮김(정리 1단계), 머리 블록 있음
기록·계획서 docs/history/plans/2026-09-25-review-fix-round/plan.md 끝남 이미 옮김(정리 1단계), 머리 블록 있음
기록·계획서 docs/history/plans/2026-09-25-review-fix-round/todo.md 끝남 이미 옮김(정리 1단계), 머리 블록 있음
기록·증거 docs/history/evidence/2026-08-01-runtime-correctness-remediation/task-5-report.md 보관 이미 옮김(정리 1단계), 머리 블록 있음
문서 아님(게이트 입력) artifacts/tests/a11y-manual/APP_HOME.md 제자리. 정해진 영어 키 형식(scripts/lib/manual-a11y-evidence.ts)이라 검사 대상에서 뺀다
문서 아님(게이트 입력) artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md 제자리. 정해진 영어 키 형식(scripts/lib/manual-a11y-evidence.ts)이라 검사 대상에서 뺀다
문서 아님(게이트 입력) artifacts/tests/a11y-manual/NOT_FOUND.md 제자리. 정해진 영어 키 형식(scripts/lib/manual-a11y-evidence.ts)이라 검사 대상에서 뺀다
기록·리뷰 docs/reviews/2026-09-17-senior-frontend-architecture-review.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-23-domain-scale-horizontal-scaling-review.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-23-extreme-scale-acceptance.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-23-extreme-scale-baseline-map.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/ (7개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-23-release-coherence-baseline.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-24-src-full-review.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-25-maturity-review/ (16개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-09-29-maturity-review/ (15개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-11-01-maturity-review/ (17개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-11-01-ui-design-audit.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-11-03-maturity-review/ (17개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-11-05-maturity-review/ (17개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/2026-11-06-maturity-review/ (17개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md (1개) 제자리. 머리 블록은 아직 요구하지 않는다
기록·리뷰 docs/reviews/adapters/ (7개) 제자리. 머리 블록은 아직 요구하지 않는다
사고 순서 흔적 (크기: 큼, 설계 승인됨)
  1. 목적: 살아 있는 문서를 한국어로, 기록을 수명으로 나눠 머리 블록을 단다. 성공은 영어 살아 있는 문서 0, 상태 없는 기록 0, 깨진 참조 0, 게이트 통과.
  2. 선행 사례: 백엔드 1단계·번역 단계(main docs/README.md, check-docs.py, docs-check.yml), 프론트 정리 1단계(PR #11의 docs/history/ 머리 블록), 02-docs.md의 외부 사례 16곳(설계 단계에서 끝남, 그 문서로 대체).
  3. 방법: 백엔드의 기록 분리 → 머리 블록 → 검사(기준선) → 번역 순서와 줄기만 하는 예외 목록을 가져왔다. 백엔드처럼 별도 workflow를 두는 것은 버렸다(프론트는 게이트 계약이 workflow를 생성한다).
  4. 필요한 정보: 문서를 읽는 코드 9곳과 시험(README 「Files you can delete」 정규식, layers.md 표 문장 대조, starter-experience.md 표 자르기, 6.1절 표, 원장 절 제목·정규식, 문서 바꿔 넣는 시험 문자열), docs/history/를 코드가 읽지 않는다는 약속.
  5. 격차: 시작 시 K1 영어 판정 살아 있는 문서 24개, 머리 블록 없는 기록 67개, 지도 빠진 폴더 15개, README 필수 절 7개 없음, 높임 문체 20줄, 숫자 복사 3곳.
  6. 만들고 시험: 위 「검증」. 예측(착수 보고) p30 5시간·p50 7시간·p80 10시간, 실측 약 6시간(11-08 16:4022:50, 그중 desktop 잠금 대기와 네트워크 끊김 약 3시간) + 재개 뒤 main 합치기 두 번(PR #13, #14·#16)과 게이트 약 10시간(11-11 20:2011-12 06:15, 그중 desktop 잠금 대기 약 6시간).
## 무엇을, 왜 소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.2절·3.4절 D5): 두 템플릿의 살아 있는 문서는 본문까지 한국어로 쓰고, 기록은 수명으로 나눠 `docs/history/`·`docs/design/`·`docs/adr/`에 한국어 머리 블록을 달아 둔다. 백엔드는 끝났고(main), 프론트는 README와 입구 문서가 영어였고 `docs/README.md`는 "README와 입구 문서는 영어"라는 반대 규칙을 적어 두었다. 이 PR은 정본 design-docs `conventions/docs-system.md` v1을 프론트에 적용한다. 1. **분류**: `docs/**`와 루트·`src`·`artifacts`의 `.md` 243개를 살아 있는 문서·결정 기록·설계서·기록·리뷰로 나눴다(아래 분류표). 하네스 PR #13이 더한 문서(`AGENTS.md`, `src/*/AGENTS.md`, `.claude/`, `docs/work/`, `docs/ledger/`, 양식 둘)는 그 PR이 분류했고 모두 살아 있는 문서다. 2. **옮기기**: 설계서 25개 → `docs/design/`, 계획서 19개 → `docs/history/plans/`(먼저 옮긴 4개와 합쳐 23개), VD 23개 → `docs/adr/`(번호 유지). 기록 67개에 머리 블록을 달고 본문은 고치지 않았다(옮겨서 깨진 상대 링크의 대상만 고쳤다). `SPEC.md`의 공통 완료 기준은 하네스 PR #13이 작업 매뉴얼 `docs/work/improve.md` 5절로 옮겼고, 그 뒤 `SPEC.md`를 그 라운드 계획서 옆으로 옮겼다(D5). 이 브랜치가 먼저 만든 사본 `docs/manual/reference/done-criteria.md`는 겹쳐서 지웠다. 루트 항목 등록부는 프론트에 없다. 3. **번역**: 살아 있는 문서 41개를 고쳤다(하네스 문서의 경로·검사 범위 줄 고침은 따로 센다). 그중 약 30개가 영어였거나 영어 문단을 가졌다(약 3,500줄을 새로 씀). 루트 README는 6.1절 필수 절 순서로 다시 썼고(「프로젝트 구조」「문서 지도」 포함, 「복사한 뒤 지워도 되는 것」 유지), `docs/README.md`는 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·검사 규칙으로 다시 썼다. 설정 파일 5개의 설명 칸 260개도 옮겼다(읽는 코드를 먼저 확인). 4. **검사**: `verify:documentation`(FE-GATE-017, merge 단계)이 언어·머리 블록·숫자 복사·문서 지도·README 절·문체를 PR 단계에서 실패로 본다. 참조 검사(경로·링크·script·게이트 ID)는 살아 있는 문서 전부로 넓혔다. 예외 목록은 비어 있다. 결과: 살아 있는 문서의 영어 문서 0, 머리 블록·상태 칸 없는 기록 0, 깨진 링크·없는 인라인 경로 0(살아 있는 문서 기준). ## 고른 방법과 버린 대안 **검사를 어디에 두나 — `verify:documentation` 안에 TypeScript로 옮김(권함, 고름).** - 백엔드 `scripts/check-docs.py`의 규칙 여섯(language·head·number·map·readme·style)을 같은 이름·문턱·예외 의미로 `scripts/lib/docs-system.ts`에 옮겼다. `verify-documentation-readiness.ts`가 부른다. - 참조·링크 검사는 새로 만들지 않고 이미 있는 것(짝 백엔드 pin 트리 조회, 지운 샘플·생성 산출물·지운 기록 허용)을 그대로 쓰고 대상만 넓혔다. 같은 검사를 두 벌 두지 않으려는 것이다. - 버린 안 1 — 새 게이트·package script 추가: `config/ci/gates.json`과 CI 계약의 개수·해시(`contract-baseline.json`), workflow 생성물을 바꿔야 한다. 그 파일은 같은 시간에 도는 정리 3단계·CI 세션의 범위다. - 버린 안 2 — `check-docs.py`를 그대로 복사: 프론트 도구와 CI 이미지는 Node뿐이다. 참조 검사의 프론트 쪽 규칙(지운 샘플, pin)이 TS에 이미 있어 두 언어로 갈라진다. - 프론트에만 있는 차이(근거는 코드 주석): - VD는 처음부터 한국어로 썼고 번역하지 않았으므로 결정 기록 머리 문구는 「원문이다」 쪽을 쓴다(번역 문구도 받는다, docs-system 4.1). - `docs/reviews/adapters/INVENTORY.md`는 리뷰 폴더 안이지만 `check:adapter-inventory`가 대조하는 살아 있는 목록이라 살아 있는 문서로 본다. - `artifacts/tests/a11y-manual/*.md`는 정해진 영어 키 형식의 게이트 입력이라 문서로 보지 않는다(백엔드의 resources 예외와 같은 뜻). - `docs/architecture/review-evidence.md`는 다른 작업 공간 경로를 적은 2026-07-18 리뷰 사본이라 참조·숫자 검사에서 뺀다(`CHANGELOG.md`와 같은 `HISTORY_HOLDERS`). - 숫자 검사는 Spring Boot 대신 `package.json`·`.nvmrc`의 프레임워크 버전과 게이트·recipe·adapter 개수를 본다. - 복사한 프로젝트가 `docs/history/`를 지워도 지도 검사가 통과하도록 README 「복사한 뒤 지워도 되는 것」의 경로를 지도 검사도 받는다. **목표 설계 문서(`docs/architecture/`의 14개, styling·testing의 2개)를 설계서로 분류해 옮김.** 기존 `docs/README.md`가 이미 "목표 설계 — 구현됐다는 뜻이 아니다"로 나눠 두었고, 02-docs.md W5가 "architecture/ 목표 설계 분리"를 정했다. 살아 있는 문서로 남기면 약 16,500줄을 번역하고 계속 코드에 맞춰야 한다. 버린 안: 제자리에 두고 번역. `backend-api-and-server-state-contract.md`는 4.1·6·6.1절이 실행 규칙이고 pin·테스트가 읽어서 살아 있는 문서로 남겼다. **원장(`operations/adapter-remediation-ledger.md`)은 살아 있는 문서로 둠.** `config/ci/ungated-scripts.json`은 "history record"라 부르지만 `check:remediation-ledger`가 시험 파일 표식과 대조해서 테스트를 옮기면 같이 고쳐야 한다. 그리고 `docs/history/`는 코드가 읽지 않는다는 약속(`tests/unit/deletable-history-documents.test.ts`)이 있어 코드가 읽는 파일을 둘 수 없다. 같은 이유로 `review-ledger.json`·`review-evidence.md`도 제자리다. **PR 단계에서 실패하게 하는 곳.** `verify:documentation`의 CI job(FE-GATE-017 `documentation_gate`)은 workflow_dispatch로 documentation 단계를 고를 때만 돈다. 그래서 merge 단계 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts`에 「이 repo 그대로 `verify:documentation`을 한 번 돌려 통과」 시험을 더했다. 버린 안: FE-GATE-017을 merge 단계로 옮기는 것(`config/ci/gates.json`과 CI 계약 기준선, workflow 생성물을 바꾼다. 정리 3단계·CI 세션이 merge job을 셋으로 합치는 중이라 그쪽이 정할 일이다). 이 시험은 제거 드릴 사본에서는 돌지 않는다(그 파일은 `scripts/lib/removal-fixture.ts`의 문서 시험 목록에 이미 있다). **커밋 순서**는 이동(내용 변경 없는 `git mv`) → 참조 수정 → 완료 기준 → SPEC 이동 → 머리 블록 → 링크 보정 → 검사(+입구 문서) → 번역 3묶음 → 설정 → CHANGELOG → main 합치기(하네스 PR #13) → 하네스 문서 맞추기 → 완료 기준 사본 지우기 → 줄임표 자리표시자 → 지도 링크 정리 → 시험 시간 한도 → main 합치기(PR #14·#16) → CHANGELOG다. PR을 연 뒤라 force push 없이 main을 merge로 받았다(brief가 force push를 금한다). 검사 커밋은 아직 옮기지 않은 문서 42줄을 예외 기준선(`FROZEN` 지문)으로 두고, 번역 커밋마다 줄을 지워 마지막에 0이 된다(백엔드와 같은 "줄기만 하는" 방식). README와 그 src 폴더 설명을 글자로 대조하는 `layers.md`·`overview.md`·`foundation.md`는 검사 커밋에 같이 넣었다. ## 위험과 영향 - **파생 서비스(BREAKING)**: 이 범위를 받으면 자기 살아 있는 문서가 영어거나 「~합니다」 체면 `verify:documentation`이 실패한다. 옛 문서 경로를 가리킨 자기 문서도 깨진다. `CHANGELOG.md` 정리 단계 미출시 절 「먼저 할 일」 7·8과 옛 경로 찾기 명령을 적었다. 두 다운스트림에 받아 보지는 않았다. - **중간 커밋**: 이동 커밋(`99e76e87`)은 내용을 바꾸지 않아 링크가 깨진 채다(의도). 커밋별 결과는 아래 「검증」에 있다. - **하네스 PR #13과 합친 것**: main(`d1b9c087`)을 merge로 받았다. 충돌은 README.md·`docs/README.md` 둘이었고, 이 브랜치의 한국어 판에 #13이 더한 `AGENTS.md`·`docs/work/`·`docs/ledger/`·`docs/vision.md`·`docs/problem-statement.md` 줄과 지워도 되는 표 행을 넣었다. #13이 더한 살아 있는 문서(`AGENTS.md`, `src/*/AGENTS.md`, `.claude/`, `docs/work/`, `docs/ledger/`, 양식 둘)는 모두 이 검사를 통과한다. 다만 그 문서 중 문서 체계를 설명하는 줄(옛 경로, 「docs/README.md 1절 묶음」이라는 옛 검사 범위, README의 옛 절 이름)은 이 PR이 고쳤다(`docs(work)` 커밋). #13의 `template-contract-documents` 시험은 지워도 되는 표를 `docs/history/` 행으로 찾게 바꿨다. `docs/work/evidence.md`는 백엔드처럼 근거 기록이라 참조·숫자 검사에서 뺐다. - **새로 살아 있는 문서가 된 하네스 파일 하나가 경로 검사에 걸렸다**: `scripts/hooks/README.md`의 `node scripts/…`. 줄임표 「…」를 자리표시자로 보게 경로 검사를 고쳤다(문서 검사 쪽은 이미 그랬다). 그리고 `docs/README.md`가 제거 드릴 사본에 없는 루트 `CLAUDE.md`를 링크해 사본에서 실패해서 링크를 이름으로 바꿨다. - **정리 3·4단계 PR #14와 CI 재편 PR #16**: main(`38c0dc7d`)을 다시 merge로 받았다(`e9e98b8a`). 충돌 아홉 파일은 두 PR이 영어 판에서 바꾼 것을 이 PR의 한국어 판에 넣어 풀었다: a11y 기록 경로(`docs/accessibility/route-reviews/`, 문서 검사의 `NOT_DOCUMENT`도 따라 바꿈), merge job 셋과 지운 CI 계약 기준선, main 단계 FE-GATE-029, 합친 음성 fixture script, `config/schemas/`. #14의 배치 규칙 검사(R6·R7)는 「현재 문서」를 문서 검사의 `checkedForDrift`로 고른다. 루트 등록부 `config/repository-layout.json`의 SPEC.md 항목(「문서 체계 작업이 이력 폴더로 옮기고 이 항목을 뺀다」)을 뺐다. #14가 옛 경로의 테스트 전략 문서를 고친 것은 이름 바뀜을 따라 기록(`docs/design/`)에 들어와서, 기록은 옮길 때의 글로 되돌렸다. `config/ci/`는 이 PR이 고치지 않았다(그래서 `ungated-scripts.json` reason은 아직 영어다). - **생성 코드 주석**: `create-feature.ts`가 만드는 `context-module.ts` JSDoc의 인용 절 이름이 「소유 선언」으로 바뀐다. 그 글자를 비교하는 테스트는 없다. - **판단이 필요한 상태 값**: VD-09·11·13은 git으로 보면 결정 뒤 본문이 고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 「채택」이다. 「채택(보완)」으로 올릴지는 소유자 판단이다. 상태 줄이 없던 설계서 21개·계획서 14개는 「확인 안 함」이다. - **번역하며 찾은, 고치지 않은 낡은 내용**(번역은 뜻을 바꾸지 않는다는 규칙 때문, 후속): `contract-ownership.md`의 계약 파일 "39개"(지금 44개), `capability-consumer-experience.md`의 Local Draft 두 번째 소비자 서술(지금은 fixture), `static-delivery.md`의 "예시 feature 기준" 초기 JS, `.dependency-cruiser.json:254`의 `layers.md §4`(번호 없는 문서), `FE-RB-002` 제목과 `runbooks.json` title 차이, `ci-quality-gates.md`의 zod 고친 버전 4.6.6과 이유 칸 4.6.7, 같은 문서 FE-GATE-016 문단의 자리가 어긋난 두 문장, `scripts/drill-runbook.ts` 복구 항목 이름(영어)과 `runbooks.json`(한국어)의 언어 차이. 기록 안의 깨진 상대 링크 22개는 옮기기 전부터 깨져 있었고 기록이라 두었다. ## 검증 desktop에서 workflow env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`)로 돌렸다. merge 단계는 `scripts/verify.sh merge --on here`, 무거운 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감쌌다. 그 시각 desktop은 여러 세션이 함께 써서 load가 9~25였다. **main `38c0dc7d`(PR #13·#14·#16)을 받은 head — merge 단계 `e9e98b8a`, 다시 돌린 것 `bbbc6abd`(CHANGELOG 커밋 하나 차이)** | 게이트 | rc | 메모 | |---|---|---| | FE-GATE-001 manifest-lockfile | 0 | | | FE-GATE-002 lint | 0 | | | FE-GATE-003 typecheck | 0 | | | FE-GATE-004 runtime-schema | 0 | | | FE-GATE-005 unit | 0 | | | FE-GATE-006 component | 0 | | | FE-GATE-007 integration | 0 | | | FE-GATE-008 e2e | 0 | `e9e98b8a`에서 firefox `old-tab-chunk-recovery` 하나가 시험 서버 연결 거부(`ECONNREFUSED`)로 실패. `bbbc6abd` 다시 돌려 0 | | FE-GATE-009 accessibility | 0 | | | FE-GATE-010 architecture | 0 | | | FE-GATE-011 build | 0 | | | FE-GATE-012 bundle | 0 | | | FE-GATE-013 security | 1 | desktop 호스트 조건(알려짐, `docs/work/reference/gates.md` 3절). `verify.sh parts FE-GATE-013`: `test:system`만 사전 조건(bwrap `RTM_NEWADDR`)에서 멈추고 나머지 명령은 0 | | FE-GATE-020 removability | 0 | `e9e98b8a`에서 기능 생성 드릴 안 coverage 실행의 `provider-guardian-transaction`(소켓 시험) 하나가 실패. 따로 두 번 돌리면 22/22 통과. `bbbc6abd` 다시 돌려 0 | | FE-GATE-029 checker-self-tests (main 단계) | 0 | | | `verify:documentation` (FE-GATE-017) | 0 | 문서 검사 여섯 걸림 0, 예외 0 | | `check:remediation-ledger` (게이트 밖) | 0 | | | `scripts/verify.sh docs`, `scripts/verify.sh hooks` | OK | 하네스 검사기와 훅 시험 | | 실행 뒤 `git status` | 바뀐 파일 0 | | - 앞서 하네스 PR #13만 받은 head(`5f10f928`·`7b09c215`)에서도 merge 단계를 돌렸다. 그때 실패한 것과 처리: FE-GATE-009 firefox axe 시험 시간 초과(다시 돌려 0), FE-GATE-020 기능 생성 드릴 안 `documentation-readiness` 사례 셋 10초 초과(이 PR의 원인. `7b09c215`에서 시간 한도 60초), 같은 게이트의 `extreme-scale-registry` 증가율 측정(따로 돌리면 통과·실패·통과로 흔들림, 다시 돌려 0). - 위 다시 돌린 실패들은 모두 부하가 큰 때 시간·연결에 민감한 시험이고, 이 PR이 바꾼 코드(문서, 문서 검사기, 그 시험)와 닿지 않는다. 문서 시험의 시간 초과만 이 PR 탓이었고 고쳤다. - 문서 시험 12파일 108개 통과(`docs-system`, `documentation-readiness`, `template-feature-removal-documents`, `deletable-history-documents`, `template-contract-documents`, `feature-tracked-files`, `backend-contract-pin-document`, `changelog-review-ids`, `runbook-contract`, `json-schema`, `repository-layout`, `manual-a11y-evidence`). - 줄임표 고침(`743f6fcc`)은 RED→GREEN을 봤다: 고치기 전 `verify-documentation-readiness.ts`로 자리표시자 사례가 실패하고, 고친 뒤 통과한다. - 검사기 자기 시험 `tests/unit/docs-system.test.ts`: 판정 조건마다 그 조건만 잡는 실패 입력이 있다. - 커밋별: 11-08 실행에서 검사 커밋(`7a9aefdf`)부터 그 위 커밋까지 `verify:documentation` 0·문서 시험 0. 이동만 담은 커밋(`99e76e87`)부터 링크 보정(`2b8a348c`)까지는 의도적으로 깨진다. merge 뒤 커밋은 위 표가 head 기준이다. ## 리뷰어가 볼 곳 - `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`(참조 대상 확대, 「복사한 뒤 지워도 되는 것」 읽기), `tests/unit/docs-system.test.ts`, `tests/unit/deletable-history-documents.test.ts`(검사기를 그 약속의 대상에서 뺀 이유) - `README.md`, `docs/README.md`, merge 커밋(`fb446e47`)과 하네스 문서를 맞춘 `docs(work)` 커밋 - `scripts/check-remediation-ledger.ts`(절 제목 상수, 한국어 「모두 닫혔다」 대안) - `scripts/verify-documentation-readiness.ts`의 경로 후보 거르기(줄임표 「…」), `tests/unit/documentation-readiness.test.ts`의 `VERIFY_TIMEOUT` - 기계적으로 만든 부분: 이동(`git mv`, 매핑은 커밋 `99e76e87` 본문), 링크 다시 쓰기(옮기기 전 트리 `ad3a071f`로 대상을 풀어 새 위치 기준 상대 경로로), 머리 블록(파일마다 값을 정한 표로 삽입, 블록을 빼면 원문 바이트가 같다), 예외 기준선(커밋마다 그 트리에서 검사기를 돌려 생성). 번역은 영역별로 나눠 했고 파일마다 검사기와 python 대조(백틱·링크·코드 블록·번호 제목)로 확인했다. 이동·링크·머리 블록·번역이 한 PR이라 크다(커밋·PR 규칙 5.1절의 기계적 변경 예외). 커밋 단위로 보면 된다. ## 관련 - design-docs `conventions/docs-system.md` v1, `repo-structure/README.md` 3.2절·3.4절 D5, `repo-structure/02-docs.md` 3.4·4.5·8.5절 - 백엔드 본보기: 백엔드 템플릿 main의 `docs/README.md`, `scripts/check-docs.py` - 앞 단계: 정리 1단계 PR #11, 2단계 PR #12 <details> <summary>분류표 (파일마다)</summary> | 종류 | 수 | |---|---| | 살아 있음 | 46 | | 결정 기록 | 23 | | 설계서 | 25 | | 기록·계획서 | 23 | | 기록·증거 | 1 | | 문서 아님(게이트 입력) | 3 | | 기록·리뷰(제자리) | 122 | | 종류 | 지금 경로 | 옛 경로 | 상태(머리 블록) | 처리 | |---|---|---|---|---| | 살아 있음 | `CHANGELOG.md` | | | 제자리, 이미 한국어(이 단계 항목과 README 절 이름만 고침) | | 살아 있음 | `CLAUDE.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `PRODUCT.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `README.md` | | | 제자리, 한국어로 다시 씀 | | 살아 있음 | `docs/README.md` | | | 제자리, 한국어로 다시 씀 | | 살아 있음 | `docs/accessibility/manual-checklist.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/backend-api-and-server-state-contract.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/capability-consumer-experience.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/contract-ownership.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/frontend-application-foundation.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/layers.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/optional-adapter-recipes.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/overview.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/review-evidence.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/scale-architecture.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/starter-experience.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/architecture/static-delivery.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/contracts/compatibility.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/manual/01-add-a-feature.md` | | | 제자리, 이미 한국어(경로·인용만 고침) | | 살아 있음 | `docs/manual/02-decision-tables.md` | | | 제자리, 이미 한국어(경로·인용만 고침) | | 살아 있음 | `docs/manual/03-outside-feature-folder.md` | | | 제자리, 이미 한국어(경로·인용만 고침) | | 살아 있음 | `docs/manual/04-paired-backend-session.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `docs/manual/README.md` | | | 제자리, 이미 한국어(경로·인용만 고침) | | 살아 있음 | `docs/manual/reference/create-feature.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `docs/manual/reference/errors.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `docs/manual/reference/global-ids.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `docs/manual/reference/patterns.md` | | | 제자리, 이미 한국어(경로·인용만 고침) | | 살아 있음 | `docs/operations/adapter-remediation-ledger.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/api-contract-and-server-state-recovery.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/browser-file-storage-recovery.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/browser-transfer-recovery.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/ci-quality-gates.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/client-cache-and-storage-recovery.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/performance-evidence.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/operations/release-cache-rollback.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/reviews/adapters/INVENTORY.md` | | | 제자리, 이미 한국어 | | 살아 있음 | `docs/runbooks/FE-RB-001.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/runbooks/FE-RB-002.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/runbooks/FE-RB-003.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/runbooks/FE-RB-004.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/runbooks/FE-RB-005.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/security/browser-boundary.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/security/supply-chain.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/styling/design-tokens.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `docs/testing/taxonomy.md` | | | 제자리, 한국어로 옮김 | | 살아 있음 | `src/adapters/browser-transfer/image-cdn/README.md` | | | 제자리, 한국어로 옮김 | | 결정 기록 | `docs/adr/VD-01-typescript-lint-tooling.md` | `docs/architecture/decisions/VD-01-typescript-lint-tooling.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-03-react-router-data-mode.md` | `docs/architecture/decisions/VD-03-react-router-data-mode.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-04-native-form-facade.md` | `docs/architecture/decisions/VD-04-native-form-facade.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-05-icon-and-headless-ui.md` | `docs/architecture/decisions/VD-05-icon-and-headless-ui.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-06-intl-typed-message-catalog.md` | `docs/architecture/decisions/VD-06-intl-typed-message-catalog.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-07-diagnostics-and-telemetry-exporter.md` | `docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-08-storybook-and-visual-evidence.md` | `docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-09-supply-chain-evidence.md` | `docs/architecture/decisions/VD-09-supply-chain-evidence.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-10-optional-capability-recipes.md` | `docs/architecture/decisions/VD-10-optional-capability-recipes.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-11-browser-file-and-origin-storage.md` | `docs/architecture/decisions/VD-11-browser-file-and-origin-storage.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-12-presigned-transfer-and-image-cdn.md` | `docs/architecture/decisions/VD-12-presigned-transfer-and-image-cdn.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-13-client-cache-scope-and-persistence.md` | `docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-14-resumable-download-and-background-transfer.md` | `docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-15-origin-storage-lifecycle-and-migration.md` | `docs/architecture/decisions/VD-15-origin-storage-lifecycle-and-migration.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-16-browser-transfer-composition-and-image-delivery.md` | `docs/architecture/decisions/VD-16-browser-transfer-composition-and-image-delivery.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-23-api-transport-selection-and-rest-execution.md` | `docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-24-runtime-schema-and-boundary-mapper.md` | `docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-25-server-state-cache-lifecycle.md` | `docs/architecture/decisions/VD-25-server-state-cache-lifecycle.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-26-persisted-graphql-operation.md` | `docs/architecture/decisions/VD-26-persisted-graphql-operation.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-27-grpc-web-unary-and-server-stream.md` | `docs/architecture/decisions/VD-27-grpc-web-unary-and-server-stream.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-28-realtime-events-web-push-and-bounded-polling.md` | `docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md` | 채택(보완) | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-29-connect-web-and-browser-protobuf-runtime.md` | `docs/architecture/decisions/VD-29-connect-web-and-browser-protobuf-runtime.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 결정 기록 | `docs/adr/VD-30-protobuf-contract-and-rest-gateway.md` | `docs/architecture/decisions/VD-30-protobuf-contract-and-rest-gateway.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-design-system-platform-design.md` | `docs/styling/design-system-platform.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-frontend-platform-capability-review-design.md` | `docs/architecture/frontend-platform-capability-review.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.md` | `docs/architecture/frontend-platform-implementation-roadmap.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` | `docs/testing/frontend-platform-testing-strategy.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md` | `docs/architecture/frontend-ports-adapters-and-boundaries.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-routing-pages-and-patterns-design.md` | `docs/architecture/routing-pages-and-patterns.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` | `docs/architecture/typescript-state-and-data-flow.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-27-browser-file-and-origin-storage-design.md` | `docs/architecture/browser-file-and-origin-storage.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md` | `docs/architecture/api-contract-schema-mapper-and-server-state.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-28-client-cache-and-storage-design.md` | `docs/architecture/client-cache-and-storage.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md` | `docs/architecture/protobuf-browser-transport-and-rest-gateway.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-28-server-file-capability-infrastructure-design.md` | `docs/architecture/server-file-capability-infrastructure.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md` | `docs/architecture/browser-data-capability-completion-ledger.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md` | `docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md` | 채택 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md` | `docs/architecture/presigned-transfer-and-image-cdn.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md` | `docs/architecture/realtime-events-web-push-and-bounded-polling.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-07-31-platform-overview-page-design.md` | `docs/superpowers/specs/2026-07-31-platform-overview-page-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-08-01-refactoring-review-remediation-design.md` | `docs/superpowers/specs/2026-08-01-refactoring-review-remediation-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-08-01-runtime-integrity-refactor-design.md` | `docs/superpowers/specs/2026-08-01-runtime-integrity-refactor-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-08-02-platform-owned-frontend-assurance-delivery-design.md` | `docs/superpowers/specs/2026-08-02-platform-owned-frontend-assurance-delivery-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-08-02-provider-raw-guardian-design.md` | `docs/superpowers/specs/2026-08-02-provider-raw-guardian-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-08-02-v8-coverage-counter-contract-design.md` | `docs/superpowers/specs/2026-08-02-v8-coverage-counter-contract-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-09-16-adapter-barrel-boundary-design.md` | `docs/superpowers/specs/2026-09-16-adapter-barrel-boundary-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-09-16-indexeddb-kernel-promotion-design.md` | `docs/superpowers/specs/2026-09-16-indexeddb-kernel-promotion-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 설계서 | `docs/design/2026-09-20-memento-frontend-template-bootstrap-design.md` | `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md` | 확인 안 함 | 옮김 + 머리 블록(본문 그대로) | | 기록·계획서 | `docs/history/plans/2026-07-31-platform-overview-completion.md` | `docs/superpowers/plans/2026-07-31-platform-overview-completion.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-http-worker-adapter-remediation.md` | `docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-quality-architecture-remediation.md` | `docs/superpowers/plans/2026-08-01-quality-architecture-remediation.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-release-boot-integrity.md` | `docs/superpowers/plans/2026-08-01-release-boot-integrity.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-release-evidence-remediation.md` | `docs/superpowers/plans/2026-08-01-release-evidence-remediation.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-runtime-correctness-remediation.md` | `docs/superpowers/plans/2026-08-01-runtime-correctness-remediation.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-01-scope-owned-server-state.md` | `docs/superpowers/plans/2026-08-01-scope-owned-server-state.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-cicd-frontend-assurance-delivery.md` | `docs/superpowers/plans/2026-08-02-cicd-frontend-assurance-delivery.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-counter-bearing-coverage-provenance.md` | `docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md` | 끝남 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-frontend-platform-consumer-migration.md` | `docs/superpowers/plans/2026-08-02-frontend-platform-consumer-migration.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-promotion-security-review-fixes.md` | `docs/superpowers/plans/2026-08-02-promotion-security-review-fixes.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-provider-raw-guardian.md` | `docs/superpowers/plans/2026-08-02-provider-raw-guardian.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-security-finalizer.md` | `docs/superpowers/plans/2026-08-02-security-finalizer.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-test-assurance-frontend-capabilities.md` | `docs/superpowers/plans/2026-08-02-test-assurance-frontend-capabilities.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-02-v8-coverage-counter-contract.md` | `docs/superpowers/plans/2026-08-02-v8-coverage-counter-contract.md` | 끝남 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-08-13-adapter-remediation.md` | `docs/superpowers/plans/2026-08-13-adapter-remediation.md` | 확인 안 함 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-09-16-adapter-barrel-boundary.md` | `docs/superpowers/plans/2026-09-16-adapter-barrel-boundary.md` | 끝남 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-09-16-indexeddb-kernel-promotion.md` | `docs/superpowers/plans/2026-09-16-indexeddb-kernel-promotion.md` | 끝남 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-09-25-review-fix-round/SPEC.md` | `SPEC.md` | 끝남 | 옮김 + 머리 블록 | | 기록·계획서 | `docs/history/plans/2026-09-25-review-fix-round/handoff.md` | | 끝남 | 이미 옮김(정리 1단계), 머리 블록 있음 | | 기록·계획서 | `docs/history/plans/2026-09-25-review-fix-round/lanes/LANE-BRIEF.md` | | 끝남 | 이미 옮김(정리 1단계), 머리 블록 있음 | | 기록·계획서 | `docs/history/plans/2026-09-25-review-fix-round/plan.md` | | 끝남 | 이미 옮김(정리 1단계), 머리 블록 있음 | | 기록·계획서 | `docs/history/plans/2026-09-25-review-fix-round/todo.md` | | 끝남 | 이미 옮김(정리 1단계), 머리 블록 있음 | | 기록·증거 | `docs/history/evidence/2026-08-01-runtime-correctness-remediation/task-5-report.md` | | 보관 | 이미 옮김(정리 1단계), 머리 블록 있음 | | 문서 아님(게이트 입력) | `artifacts/tests/a11y-manual/APP_HOME.md` | | | 제자리. 정해진 영어 키 형식(`scripts/lib/manual-a11y-evidence.ts`)이라 검사 대상에서 뺀다 | | 문서 아님(게이트 입력) | `artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md` | | | 제자리. 정해진 영어 키 형식(`scripts/lib/manual-a11y-evidence.ts`)이라 검사 대상에서 뺀다 | | 문서 아님(게이트 입력) | `artifacts/tests/a11y-manual/NOT_FOUND.md` | | | 제자리. 정해진 영어 키 형식(`scripts/lib/manual-a11y-evidence.ts`)이라 검사 대상에서 뺀다 | | 기록·리뷰 | `docs/reviews/2026-09-17-senior-frontend-architecture-review.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-23-domain-scale-horizontal-scaling-review.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-23-extreme-scale-acceptance.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-23-extreme-scale-baseline-map.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/` (7개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-23-release-coherence-baseline.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-24-src-full-review.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-25-maturity-review/` (16개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-09-29-maturity-review/` (15개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-11-01-maturity-review/` (17개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-11-01-ui-design-audit.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-11-03-maturity-review/` (17개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-11-05-maturity-review/` (17개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/2026-11-06-maturity-review/` (17개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` (1개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | | 기록·리뷰 | `docs/reviews/adapters/` (7개) | | | 제자리. 머리 블록은 아직 요구하지 않는다 | </details> <details> <summary>사고 순서 흔적 (크기: 큼, 설계 승인됨)</summary> 1. 목적: 살아 있는 문서를 한국어로, 기록을 수명으로 나눠 머리 블록을 단다. 성공은 영어 살아 있는 문서 0, 상태 없는 기록 0, 깨진 참조 0, 게이트 통과. 2. 선행 사례: 백엔드 1단계·번역 단계(main `docs/README.md`, `check-docs.py`, `docs-check.yml`), 프론트 정리 1단계(PR #11의 `docs/history/` 머리 블록), 02-docs.md의 외부 사례 16곳(설계 단계에서 끝남, 그 문서로 대체). 3. 방법: 백엔드의 기록 분리 → 머리 블록 → 검사(기준선) → 번역 순서와 줄기만 하는 예외 목록을 가져왔다. 백엔드처럼 별도 workflow를 두는 것은 버렸다(프론트는 게이트 계약이 workflow를 생성한다). 4. 필요한 정보: 문서를 읽는 코드 9곳과 시험(README 「Files you can delete」 정규식, `layers.md` 표 문장 대조, `starter-experience.md` 표 자르기, 6.1절 표, 원장 절 제목·정규식, 문서 바꿔 넣는 시험 문자열), `docs/history/`를 코드가 읽지 않는다는 약속. 5. 격차: 시작 시 K1 영어 판정 살아 있는 문서 24개, 머리 블록 없는 기록 67개, 지도 빠진 폴더 15개, README 필수 절 7개 없음, 높임 문체 20줄, 숫자 복사 3곳. 6. 만들고 시험: 위 「검증」. 예측(착수 보고) p30 5시간·p50 7시간·p80 10시간, 실측 약 6시간(11-08 16:40~22:50, 그중 desktop 잠금 대기와 네트워크 끊김 약 3시간) + 재개 뒤 main 합치기 두 번(PR #13, #14·#16)과 게이트 약 10시간(11-11 20:20~11-12 06:15, 그중 desktop 잠금 대기 약 6시간). </details>
donghyeon.kang added 12 commits 2026-11-08 13:55:25 +00:00
문제: 프론트 docs/는 지금 동작을 설명하는 문서와 쓴 때의 기록이 한
폴더에 섞여 있다. docs/architecture/에는 현재 계약 10개와 목표 설계
14개, 결정 기록 VD 23개가 같이 있고, 설계서·계획서는 플러그인 이름
폴더(docs/superpowers/)에 있다. 문서 체계 규칙(design-docs
conventions/docs-system.md v1, 2026-11-07 소유자 결정)은 수명으로
나누고 폴더 이름을 백엔드와 같게 하라고 정한다.

고른 방법: 내용 변경 없이 git mv만 담는다. git이 이름 바뀜을 알아보고
리뷰어가 이동과 내용 변경을 따로 볼 수 있게 하려는 것이다. 참조 수정과
머리 블록은 다음 커밋들이 한다.
- docs/superpowers/specs → docs/design/, plans → docs/history/plans/
- docs/architecture/ 목표 설계 13개와 styling·testing의 목표 설계
  2개 → docs/design/<작성일>-<이름>-design.md (2026-07-30 결정 정본은
  이름 그대로)
- docs/architecture/decisions/VD-* → docs/adr/ (번호 유지)

위험: 이 커밋만으로는 옮긴 문서를 가리키는 링크와 경로가 깨진다.
다음 커밋이 고친다. 게이트가 읽는 파일(review-ledger.json,
review-evidence.md, adapter-remediation-ledger.md, INVENTORY.md)은
옮기지 않았다. docs/history/는 복사한 프로젝트가 지워도 된다는 약속
(tests/unit/deletable-history-documents.test.ts)이 있어서 코드가 읽는
파일을 둘 수 없다. SPEC.md는 공통 완료 기준을 매뉴얼로 옮긴 뒤 따로
옮긴다.

검증: git status가 이름 바뀜(R) 66개만 보인다.
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을
가리킨다.

고른 방법: 기계적으로 바꾼다.
- 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고,
  대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다.
  옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은
  링크 대상뿐이다(백엔드 1단계와 같은 예외).
- 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`,
  `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과
  CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와
  review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토
  작업 공간의 출처 표시라 그대로 둔다.

위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는
없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다.

검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록,
CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시
쓴다) 밖에서 0건.
문제: 2026-09-25 리뷰 수정 라운드의 요구사항 SPEC.md는 라운드가
0.2.0으로 끝난 기록인데, 그 안의 「공통 완료 기준」(RED→GREEN, 변이
확인, 게이트, INVENTORY, kernel 위치, 포트 추가만, 커밋 하나, 문서
주장의 코드 위치)은 지금도 쓰는 규칙이다. 기록으로 옮기면 규칙이
지울 수 있는 이력 안에만 남는다(소유자 결정 D5, 2026-11-07).

고른 방법: docs/manual/reference/done-criteria.md로 옮기고 매뉴얼
README 표에 더한다. 게이트 여덟 개를 적은 원문 3·4번은 매뉴얼 규칙
(원칙 8, 목록을 복사하지 않음)에 맞춰 정본 config/ci/gates.json과
`ci:gate`를 가리키게 바꿨다. 작업 매뉴얼(docs/work/)은 하네스 세션이
만드는 중이라 이 변경은 개발 매뉴얼에 둔다.

위험: 하네스 세션이 docs/work/에 같은 기준을 두면 둘 중 하나를
가리키게 정리해야 한다.

검증: 문서만 바뀐다. 경로는 뒤의 verify:documentation 실행에서 본다.
문제: SPEC.md는 끝난 2026-09-25 리뷰 수정 라운드의 요구사항이다. 기록인데
저장소 루트에 있어 지금 쓰는 문서처럼 보인다.

고른 방법: 공통 완료 기준을 앞 커밋에서 매뉴얼로 옮겼으므로, 내용 변경
없이 같은 라운드의 계획서 폴더로 옮긴다(소유자 결정 D5). 루트 항목
등록부는 이 repo에 없어서 고칠 곳이 없다.

위험: 루트 README와 docs/README.md의 SPEC.md 줄은 뒤 커밋이 다시 쓴다.

검증: git status가 이름 바뀜 하나만 보인다.
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
문제: 링크를 고친 앞 커밋은 옮긴 파일의 옛 위치를 지금 트리에서
찾았다. 그래서 VD와 superpowers 계획서 안에서 나가는 상대 링크
28개(예: VD-14의 `../../operations/…`)는 옛 위치 기준 그대로 남아
없는 곳을 가리킨다.

고른 방법: 옛 위치를 `git diff --name-status -M ad3a071f HEAD`의 이름
바뀜으로 다시 구해, 옮기기 전에는 풀리던 링크만 새 위치 기준으로 다시
쓴다. 옮기기 전에도 깨져 있던 링크 22개는 쓴 때의 글이라 그대로 둔다.
고친 것은 링크 대상뿐이다.

위험: 없음에 가깝다. 기록 본문의 글자는 바뀌지 않는다.

검증: 같은 스크립트를 다시 돌려 「옮기기 전엔 풀리던 깨진 링크」 0건.
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md,
starter-experience.md, capability-consumer-experience.md,
contract-ownership.md, static-delivery.md, review-evidence.md는 본문이
영어이고, backend-api-and-server-state-contract.md와
optional-adapter-recipes.md에는 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드
주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은
그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서
고친다.
- tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를
  자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`)
- 「Ownership declarations」「Adding a feature」를 인용한 주석
  (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과
  docs/manual의 절 이름 인용
- optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게
  바꾼다(number 검사)

위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라
새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다.
review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다.

검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로
비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외
목록에서 지웠다.
문제: docs/operations의 release-cache-rollback.md와
adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와
ci-quality-gates.md에도 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가
읽으므로 같은 변경에서 스크립트를 맞춘다.
- `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로
- 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어
  대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다
- 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는
  그대로다
- ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을
  `package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사)

위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다.
desktop에서 손으로 돌려 확인했다.

검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가
있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어
예외 목록에서 지웠다.
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
문제: recipe 카탈로그(config/recipes/frontend-capability-recipes.json),
runbook 등록(config/runbooks/runbooks.json), 규모 상한
(config/scale/feature-shape-ceilings.json), 짝 백엔드 pin의 `fact`,
secret scan 허용 이유의 설명 칸이 영어다. 소유자 결정(2026-11-07):
레지스트리의 설명 칸은 번역하되 그 칸을 읽는 테스트를 먼저 찾는다.

고른 방법: 칸마다 읽는 코드를 찾아, 비었는지만 보거나 자유 문자열로
산출물에 복사하는 칸만 옮긴다. 키, 배열 길이, 순서, 식별자·상태·경로·
명령·숫자는 그대로다.
- 옮기지 않은 칸: registry-baseline.json의 `trigger`·`compatibilityRole`
  (승인 파일이 그 사본의 digest를 고정한다), 승인·변경 증거 파일의
  `reason`(쓴 때의 기록), benchmark-baseline.json의 승인 이유,
  feature-shape-ceilings의 `axes[].axis`(테스트가 영어 리터럴로
  비교한다), 값이나 이름뿐인 칸. config/ci/는 정리 3단계·CI 세션
  범위라 보지 않았다.

위험: scripts/drill-runbook.ts의 복구 확인 항목 이름은 아직 영어라 설정과
코드의 언어가 다르다. 비교하지는 않는다.

검증: 다섯 파일 모두 HEAD와 키 경로·순서·배열 길이가 같다.
json-schema·runbook-contract·feature-shape-growth·backend-contract-pin
시험을 desktop에서 돌렸다.
문제: 이 범위는 파생 서비스가 받을 때 할 일이 있다. 옛 문서 경로를 가리킨
자기 문서는 깨지고, verify:documentation이 살아 있는 문서 전부의 언어·
문체·숫자·README 절·문서 지도를 보게 돼 영어 문서를 가진 프로젝트는
게이트가 실패한다. README 절 이름도 바뀌었다.

고른 방법: 정리 단계 미출시 절에 범위를 더하고, 「먼저 할 일」에 옛 경로
찾기와 7·8단계(문서 검사에 맞추기, 바뀐 README 절 이름)를, 표에 [계약]
행 셋(검사, 문서 이동, README)을, 그 밖의 수정에 번역·원장 검사·완료
기준·설정 설명 칸을 적는다.

위험: 두 다운스트림에 받아 보지 않았다. 행의 커밋 해시는 이 브랜치의
지금 해시다. 병합 전에 다시 rebase하면 고친다.

검증: 문서 검사 여섯이 0건이다. changelog-review-ids 시험은 desktop에서
돌린다.
donghyeon.kang added 8 commits 2026-11-11 21:13:42 +00:00
하네스 PR #13(main d1b9c087)을 받는다. 충돌은 README.md와 docs/README.md
둘이다. 이 브랜치가 두 파일을 한국어로 다시 썼고, #13이 영어 판에
AGENTS.md·docs/work/·docs/ledger/를 가리키는 줄과 지워도 되는 표 행을 더했다.
이 브랜치 판을 바탕으로 #13이 더한 것을 한국어로 넣었다.
- README: 최상위 표에 AGENTS.md·.claude/, 문서 지도에 AGENTS.md·docs/work/·
  docs/vision.md·docs/problem-statement.md·docs/ledger/, 지워도 되는 표에서
  CLAUDE.md를 빼고 docs/ledger/estimates.jsonl을 더함, 새 서비스로 시작하기와
  규칙과 기여의 CLAUDE.md 줄을 AGENTS.md 기준으로
- docs/README.md: 1절 「처음 읽을 문서」에 ../AGENTS.md·work/·work/reference/
  링크(#13의 template-contract-documents 시험이 본다), 지도에 work/·ledger/
  행, 폴더 밖 문서에 AGENTS.md·vision.md·problem-statement.md, 2절 살아 있는
  문서 목록
문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서
체계의 옛 모습을 적는다.
- 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트
  `SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md`
- 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래
  .md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어·
  문체·숫자·머리 블록도 본다
- 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README
  절 이름(「Support scope」, 「Updating a copied project」)
- #13의 template-contract-documents 시험은 README 지워도 되는 표를
  `docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다

고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md,
docs/work의 docs-writing·operate·research-design·reference 다섯,
docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다.
docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고
`HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다.

위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을
바꾸지 않으려는 것이다.

검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가
기록·CHANGELOG·출처 표시 밖에서 0건.
문제: 이 브랜치는 SPEC.md의 공통 완료 기준을
docs/manual/reference/done-criteria.md로 옮겼다. 하네스 PR #13은 같은 기준을
작업 매뉴얼 docs/work/improve.md 5절로 옮겼다. 같은 규칙의 사본이 둘이면
하나만 고쳐져 갈라진다.

고른 방법: 소유자 결정 D5가 말한 「매뉴얼」은 일하는 순서를 정하는 작업
매뉴얼(docs/work/) 쪽이 맞아서 개발 매뉴얼 사본을 지운다. 매뉴얼 README의
그 행과 CHANGELOG 줄을 고친다.

위험: 없음에 가깝다. 사본은 이 브랜치에서 생겼고 다른 문서가 가리키지
않는다.

검증: `git grep -n done-criteria`가 CHANGELOG의 이력 줄 밖에서 0건.
문제: 하네스 PR #13이 더한 scripts/hooks/README.md는 `node scripts/…`처럼
줄임표 「…」(U+2026)로 「아무 스크립트」를 적는다. 참조 검사가 살아 있는
문서 전부로 넓어지자 verify:documentation이 `scripts/…`를 없는 경로로
잡아 실패한다. 경로 검사는 `...`만 자리표시자로 알고 「…」는 몰랐다.
같은 repo의 문서 검사(scripts/lib/docs-system.ts의 PLACEHOLDER)는 이미
「…」를 자리표시자로 본다.

고른 방법: verify-documentation-readiness.ts의 경로 후보 거르기에 「…」를
더해 두 검사를 맞춘다. 버린 안: 하네스 문서의 표기를 바꾸는 것(같은 표기를
다른 문서도 쓸 수 있고, 검사 둘이 다르게 판정하는 것이 원인이다).

위험: 「…」가 든 진짜 경로는 검사에서 빠진다. 파일 이름에 「…」를 쓰는
일은 없다고 본다.

검증: documentation-readiness 시험의 자리표시자 사례에 `node scripts/…`를
더했다. 고치기 전 코드에서는 그 사례가 실패하고 고친 뒤 통과한다(desktop).
문제: 기능 제거 드릴과 template-feature-removal-documents 시험은 repo
사본에서 verify:documentation을 돈다. 사본은 scripts/lib/removal-fixture.ts의
목록만 복사하고, 하네스 PR #13 뒤로 그 목록에 루트 CLAUDE.md가 없다.
docs/README.md 「폴더 밖 문서」가 `../CLAUDE.md`를 마크다운 링크로 가리켜
사본에서 없는 경로로 실패한다(.claude/rules/docs.md가 금하는 꼴).

고른 방법: CLAUDE.md와 PRODUCT.md 두 행을 링크 대신 인라인 코드 이름으로
적는다. 버린 안: 사본 목록에 CLAUDE.md를 더하는 것(목록은 드릴이 지우지
않는 문서만 담는다는 하네스 쪽 결정이다).

위험: 지도에서 그 두 파일로 바로 가는 링크가 없어진다. 이름은 그대로다.

검증: template-feature-removal-documents 시험이 desktop에서 통과한다.
문제: tests/unit/documentation-readiness.test.ts의 사례마다
verify:documentation을 새 프로세스로 띄운다. 이 브랜치에서 그 검사가 살아
있는 문서 전부를 읽게 돼 한 번 도는 시간이 늘었고, 부하가 큰 desktop(load
25)에서 FE-GATE-020의 기능 생성 드릴이 사본 안에서 이 파일을 돌릴 때 세
사례가 기본 시간 10초를 넘겨 실패했다. 같은 사례는 부하가 낮을 때 1~8초다.

고른 방법: 이 파일의 사례에 저장소 관례대로 시간 한도 60초를 준다
(`VERIFY_TIMEOUT`). 그리고 livingDocuments가 문서 내용을 읽지 않고 경로만
고르게 해 한 번 도는 일을 줄인다. 버린 안: vitest 전역 testTimeout을
올리는 것(다른 시험의 멈춤을 늦게 알게 된다).

위험: 진짜로 멈춘 검사를 60초 뒤에야 알게 된다.

검증: desktop에서 이 파일과 FE-GATE-005·FE-GATE-020을 다시 돌린다.
정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
docs(changelog): 하네스·정리 3·4단계를 받은 뒤의 문서 체계 고침을 적는다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m20s
frontend-quality-gates / merge / tests (pull_request) Failing after 14m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 8m33s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
bbbc6abd98
문제: 정리 단계 미출시 절이 main을 두 번 받은 뒤 더한 문서 체계 고침(하네스
문서 맞추기, 줄임표 자리표시자, 시험 시간 한도, a11y 기록 경로)을 적지 않는다.

고른 방법: 「그 밖의 수정」에 세 줄을 더한다. 계약 행은 바뀌지 않는다.

검증: changelog-review-ids 시험과 verify:documentation을 desktop에서 본다.
donghyeon.kang merged commit db6a6eb6fb into main 2026-11-11 21:51:57 +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#15