문제: 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이 되어 예외
목록에서 지웠다.
문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는
상대 링크 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건.
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.
고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
verify:documentation, check:i18n, check:design-system을 돈다
(FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
(c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.
위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).
검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
documentation-readiness 14건 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
문제: src/platform·src/apps·src/contexts의 구조·소유·예산·실행·
텔레메트리 규칙과 코드 주석 "Spec §N"의 근거가 2026-09-23 설계서
하나에만 있다. 그 설계서는 docs/reviews/ 안의 계획 묶음에 들어 있어
README가 복사 뒤 지워도 된다고 한 범위 안이다. 현재 계약 목록
(docs/README.md §1)에는 src/platform을 다루는 문서가 없다.
고른 방법: 설계서를 docs/architecture/scale-architecture.md로 복사한다
(git mv가 아니라 복사라 이력 묶음은 그대로 남는다). 본문 §1~§55는
영어 원문 그대로 두고 절 번호를 바꾸지 않는다. 맨 위에 상태 머리말을
붙인다: 현재 계약인 범위, 출처(커밋 6f6c48e와 원래 경로, git show로
보는 법), 코드와 달라진 곳을 절 끝 "> 2026-11-03 현재:"로 적는 규칙.
절 상태 표는 현재 계약(코드 참조) 41, 현재 계약 10, 기록만 4
(§40·§51·§53·§54), 미확인 0이다. 코드와 다른 18개 절에 차이를 한두
줄로 적었다(예: §4 최상위 domain/ 없음, §11 TrafficBudget에 deadline
없음, §40 부팅 게이트 없음, §47 CI는 pr 단계만). docs/README.md §1의
세부 규칙 목록에 새 문서를 더한다.
버린 대안: 필요한 절만 새로 쓰기. 68곳 넘는 주석의 절 번호 대응표가
필요해지고 원문과 갈라진다. 이력을 지우지 말라고 정책을 바꾸기
(리뷰 5.1절 (c)). 동기화 비용과 문서 섞임이 그대로 남는다.
위험·한계: 절 대조는 각 절을 가리키는 모듈의 타입·머리 주석·테스트
이름을 읽는 수준이다. 동작을 실행해 확인하지 않았다. 원문의 "Status:
Design approved…"와 예정 경로 줄은 머리말로 바꿨다. 예정 경로가 없는
파일을 가리켜 verify:documentation의 경로 검사에 걸리기 때문이다.
이 커밋만으로는 코드 주석이 아직 이름 없는 "Spec §N"이다. 다음
커밋이 바꾼다.
검증:
- 본문 비교: 원문 §1 이후와 새 문서 §1 이후의 diff에서 지운 줄 0,
"> 2026-11-03 현재" 메모 외에 더한 줄 0
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
(처음 "src/domain"을 백틱으로 적어 FAIL, 문구를 고쳐 PASS)
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
tests/unit/deletable-history-documents.test.ts: 15 passed