docs: 문서 체계 후속으로 VD 보완 표시와 낡은 서술을 고친다 #20

Merged
donghyeon.kang merged 5 commits from donghyeon.kang/claude/fe-b-docs-followup AGit into main 2026-11-12 01:43:20 +00:00
5 Commits
Author SHA1 Message Date
DongHyeonka 36eb6b0b35 docs(changelog): 문서 체계 후속 고침을 정리 단계 절에 적는다
frontend-quality-gates / merge / browser tests (pull_request) Successful in 11m27s
frontend-quality-gates / merge / tests (pull_request) Failing after 15m24s
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
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m56s
문제: VD 보완 표시, 낡은 서술 고침, drill 복구 항목 이름, ungated
reason 번역이 변경 이력에 없다. drill 이름은 record.json의 값을 바꾸고,
자기 runbooks.json을 고친 다운스트림은 drill도 같이 고쳐야 한다.

고른 방법: 같은 동기화 단위인 「정리 단계」 절 머리에 이 브랜치 범위를
더하고, 「그 밖의 수정」에 네 줄을 더한다.

위험: 커밋 해시는 이 브랜치의 것이다. 병합 방식이 merge commit이라 main에서도
같은 해시로 찾을 수 있다.

검증: 문서 검사는 desktop에서 돌린다.
2026-11-12 09:41:13 +09:00
DongHyeonka b824195cdc docs(ci): ungated-scripts.json의 reason을 한국어로 옮긴다
문제: config/ci/ungated-scripts.json의 reason 18개가 영어다. 설정 파일의
사람이 읽는 설명 칸은 한국어로 쓴다(docs/README.md 2절).

고른 방법: 읽는 코드를 먼저 봤다. scripts/lib/ungated-scripts.ts는 빈
문자열만 막고, tests/unit/ungated-scripts.test.ts는 check:feature-index의
reason에 verify:extreme-scale이 들어 있는지만 본다. 그래서 script 이름·
경로·명령·게이트 ID·리뷰 ID는 그대로 두고 문장만 옮겼다. 옮기다 본
verify:extreme-scale의 「24 scripts」는 실제 23개라 숫자 대신
EXTREME_SCALE_GATES를 가리킨다.

위험: 같은 형식의 config/ci/ungated-tests.json reason은 범위 밖이라 영어로
남았다.

검증: diff가 reason 18줄뿐이다(키·순서·항목 수 같음). ungated-scripts
시험과 check:ci:gating은 desktop에서 돌린다.
2026-11-12 09:40:51 +09:00
DongHyeonka 6571d8cb9d fix(runbook): drill 복구 항목 이름을 runbooks.json과 같게 한다
문제: scripts/drill-runbook.ts의 복구 확인 항목 이름은 영어 리터럴이고,
config/runbooks/runbooks.json의 recoveryEvidence는 2026-11-08에 한국어로
옮겼다. 둘을 비교하는 곳이 없어 record.json과 UNVERIFIED 줄이 runbook에
없는 이름을 쓴다. 앞으로 한쪽만 고쳐도 아무 신호가 없다.

고른 방법: 다섯 drill의 항목 이름 20개를 recoveryEvidence 문자열로 바꾸고,
이름과 순서가 recoveryEvidence와 같은지 보는 시험을 runbook-drill.test.ts에
더한다. 판정 근거 문구(evidence)와 오류 메시지는 영어 그대로다.
버린 대안: drill이 recoveryEvidence를 위치로 읽어 이름을 붙이는 방법은
코드에서 항목과 판정의 짝이 보이지 않고, 설정 순서를 바꾸면 조용히
어긋난다.

위험: artifacts/runbooks/<id>/record.json의 assertion 값이 한국어가 된다.
record schema는 빈 문자열만 막으니 통과하지만, 그 값을 영어로 읽는 바깥
도구가 있으면 바꿔야 한다. 이 repo에는 없다.

검증: desktop에서 node scripts/run-vitest.ts run tests/unit/runbook-drill.test.ts
— 고치기 전 새 시험 5개 실패(RED), 고친 뒤 runbook-drill 14개·
runbook-contract 2개 통과(GREEN).
2026-11-12 09:40:51 +09:00
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다.
- capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」,
  「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture
  (tests/fixtures/indexeddb-consumer)다.
- static-delivery: initialJavascript.files가 「예시 feature 기준」이라고
  한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고
  적는다.
- .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다.
- runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어
  원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다.
- ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다.
  4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds").
- 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로
  문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다.

고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다.
Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를
쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부
title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과
날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다.

위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로).
cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을
비교하는 시험은 없다.

검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json,
layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은
desktop에서 돌린다.
2026-11-12 09:40:51 +09:00
DongHyeonka 8acf07c2f6 docs(adr): VD-09·11·13을 채택(보완)으로 올리고 보완 절을 단다
문제: 세 결정 기록은 결정한 뒤 본문을 제자리에서 고쳤지만 본문에 날짜가
붙은 보완 메모가 없어, 2026-11-08 머리 블록을 달 때 기계 규칙대로
「채택」이 됐다. 머리 블록은 본문이 결정한 때의 원문이라고 말하지만
실제로는 고친 뒤의 내용이다.

고른 방법: git 이력에서 결정 뒤 본문을 바꾼 커밋을 찾아 상태를
「채택(보완)」으로 올리고, 맨 아래 「보완」 절에 날짜·커밋·바뀐 절을
적는다(docs/README.md 2절). 본문은 고치지 않는다. 처음 커밋한 본문을
보는 git show 명령도 적는다.
- VD-09: 2026-07-30 6c52cdb9(스크립트 경로 .mjs→.ts),
  2026-08-02 92e5cace(결정 6~11번, 도식, 검증, Rollback)
- VD-11: 2026-09-18 ec7f20e2(case 수 고정 문단을 규칙으로 바꿈)
- VD-13: 2026-11-06 02a761f0(Web Storage key 이름을 정본 가리키기로)
6f6c48eb(2026-09-24)는 이력을 다시 시작한 커밋이라 세 본문 모두 그
앞 커밋과 내용이 같다. 그래서 보완에 넣지 않았다.

위험: 둘째 줄 「본문은 결정한 때의 원문이다」는 검사기가 고정한 문구라
그대로다. 보완 절의 첫 인용 블록이 실제 사정을 적는다.

검증: 각 커밋의 diff를 git diff <앞>:<경로> <뒤>:<경로>로 읽었다. 인용한
커밋 다섯 개가 모두 main의 조상이다. 문서 검사는 desktop에서 돌린다.
2026-11-12 09:40:51 +09:00