문제
docs/README.md 3절은 루트의 SPEC.md·tasks/를 "2026-09-25 라운드가 쓰는
중이라 docs/ 밖에 그대로 둔다"고 적는다. 그 라운드는 0.2.0(2026-09-27)으로
끝났다. 이유가 낡아서 복사한 프로젝트가 지워도 되는지, 템플릿이 왜 루트에
작업 기록을 두는지 알 수 없다(0929/14-01 잔여).
고른 방법
- 이유를 지금 사실로 고쳤다: 라운드는 끝났고, 그때 리뷰 문서가 이 경로
(`SPEC.md:18` 등)로 가리키므로 옮기지 않는다. 지워도 되는 기록이라는
것은 README "Files you can delete after copying"이 그대로 적는다.
- 버린 대안: 두 기록을 docs/superpowers/ 아래로 옮기기. docs/reviews/의
지난 리뷰가 루트 경로로 가리키는데, 리뷰 이력은 고치지 않는다.
위험·한계
- 위치는 그대로라 복사 대상 루트에 작업 기록이 남는다. 지우는 것은
복사한 프로젝트의 몫이다(README 표). 0929/14-01은 일부로 남는다.
검증
- desktop batch에서 확인: corepack pnpm verify:documentation
Refs: 0929/14-01
문제
CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능
폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세
폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과
FE-GATE-005의 documentation-readiness "passes the documents as they are"가
"starter-experience.md names paths that do not exist"로 실패한다(리뷰
14-R1). 그 문서가 안내한 드릴(test:sample-removal
--feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를
적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다.
PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿
문서를 고치면 동기화마다 그 줄이 충돌한다.
고른 방법
- 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그
기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그
경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트
폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라
feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴
채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는
폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다.
- tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용
기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다.
- 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소
사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의
verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로
지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의
잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히
실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에
더했다.
- PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙),
docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더,
generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다.
- 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또
좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가
없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c)
FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새
unit 테스트가 merge 단계에서 본다.
위험·한계
- 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit
시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다.
- 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다.
알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다.
- RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal --
--feature=platform-examples-feature
Refs: 1105/14-01
문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.
고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
`git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.
위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
"not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
the working tree", "reports the references as not verified when the
checkout does not have the pinned commit", "fails a link out of the
repository into a repository that is not paired".
Refs: 1105/12-02
문제
docs/README.md는 목표 설계 문서의 기능이 지금 동작하는지 문서 안의
상태 값으로 확인하라고 한다. 그런데 2026-11-03에 지운 V2 구성요소가
여전히 COMPOSED다(VD-23 머리, VD-24 머리, api-contract-schema-mapper
원장 세 행). VD-23은 "401 recovery는 replay-safe operation만 한 번
수행한다"를 적는데, 정본 8.4(FRT-D016)와 코드는 숨은 refresh-and-replay를
하지 않는다. 코드 주석 다섯 곳이 이 VD-23을 근거로 가리킨다. 지금 실행
규칙인 6.1절(쓰기 전 거절 표)은 "backend implementation pending"인 목표
설계 문서에 있어 verify:documentation 검사 밖이다.
고른 방법
- VD-23: 정본 우선 안내를 붙이고, V2 baseline을 REMOVED(048f490·12f3bb7)로,
V3 contract executor를 COMPOSED로 적는다. 401 문장을 정본 8.4 문장으로
바꾸고, 2절 defineRestOperation 앞에 삭제 안내를 둔다.
- VD-24 머리와 api-contract-schema-mapper 원장의 V2 행을 REMOVED로, shared
executor 행을 V3 실행기 설명으로 바꾼다.
- backend-api-and-server-state-contract.md 상태 줄에 4.1·6·6.1절은 지금
실행 규칙이라고 적고, docs/README.md 1절에서 그 절을 링크한다. 그 결과
이 문서도 경로 검사를 받으므로, 백엔드 repo 경로 7곳에
clean-architecture-backend-template/ 접두어를 붙였다.
- 버린 대안: 6.1절을 docs/contracts/로 옮기기. 백엔드 pin·답 표 JSON·
backend-envelope.ts 주석이 이 절을 가리켜 같이 고쳐야 할 곳이 늘어난다.
위험·한계
- 원장 행의 나머지 문장과 VD-23 본문에는 V2 시기 서술이 남아 있다.
상태 값과 401 규칙만 맞췄고, 남은 서술은 "V2 기록"이라고 표시했다.
검증
- git grep "401 recovery는 auth-required" -- docs/architecture: 0건.
- verify:documentation PASS_SCOPED, documentation-readiness·
changelog-review-ids 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-03, 03-adapters-http-state.md 03-06
문제
verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서
`corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의
명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장
docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께
지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도
알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger
사유는 "It passes at this commit"이라는 시점 문장을 담았다.
고른 방법
- 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서
명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash,
sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고,
--flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로
경로로 보지 않는다.
- 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick
경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이
있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not
verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다.
보고서 schema에 그 칸을 더했다.
- 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고,
ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을
고쳤다.
- 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고
오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛
경로를 적어 예외가 늘어난다.
위험·한계
- 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다.
- 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이
있는 개발 환경에서만 된다.
- 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다.
검증
- RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소
없음 보고) 실패.
- 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가
"names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation
PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified).
check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
문제: docs/manual/을 더했지만 입구 문서(README.md, docs/README.md)가
링크하지 않아 찾을 수 없고, verify:documentation도 매뉴얼을 검사하지
않았다.
방법: docs/README.md 1절의 세부 규칙 목록에 manual/과 manual/reference/를
링크한다. 1절에서 링크한 문서는 verify:documentation(FE-GATE-017)이 경로·
script·게이트 ID 실재를 검사한다. 루트 README의 Documentation 절에는
create:feature에서 시작하는 안내 한 줄을 둔다.
버린 대안: 입구 문서 표에 매뉴얼을 더하기 — 표는 계약을 정하는 문서
목록이고 매뉴얼은 그 계약을 쓰는 절차라 세부 목록에 둔다.
검증: verify-documentation-readiness PASS_SCOPED. documentReferences에
매뉴얼 8개 파일이 모두 들어가고 빠진 경로·script·게이트 ID 0.
문서 관련 단위 테스트 3파일 17건 통과.
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.
고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
"§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
.dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.
위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.
검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
.dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
문제: 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
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
check-ci-contract only caught test files outside the gates; check:* scripts
such as check:request-fanout and check:remediation-ledger ran nowhere. The
new check reads config/ci/ungated-scripts.json; three checks are now wired
into FE-GATE-010 and FE-GATE-012 and the rest carry a reason.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Current contracts, target designs and work history shared one tree with no
index. docs/README.md sorts them, names the files gates read, and marks the
history folders; README lists what a copy can delete. SPEC.md and tasks/ stay
in place because this round still uses them (D-16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>