Files
clean-architecture-frontend…/docs
DongHyeonka efe11f1581 test(contracts): 탐침이 닿지 않는 스키마는 방향만 요구한다
문제: e7b1b01 뒤 정책 테스트는 HTTP 자리 스키마의 행이
unknownFieldPolicy를 빼면 실패하고, 적으면 탐침 결과와 비교한다. 탐침이
객체에 닿지 못하는 검증기(두 탐침을 모두 루트에서 거절: `responseBody:
"NONE"` 출력의 z.undefined(), 문자열·null 본문)는 결과가 UNREACHED다.
행 타입은 REJECT_UNKNOWN·STRIP_UNKNOWN만 받으므로, 그런 operation은 행을
어떻게 적어도 통과하지 못한다. 칸을 빼면 `row states no
unknownFieldPolicy`, STRIP_UNKNOWN을 적으면 `row STRIP_UNKNOWN, validator
UNREACHED`다. 템플릿에는 그런 operation이 없어 다운스트림에서 난다.

고른 방법: 리뷰의 가장 작은 방향. 탐침 결과가 UNREACHED인 자리는 정책
비교에서만 빼고, direction은 그대로 요구한다. 두 검사를 슬롯·행을 받는
함수(directionProblems, policyProblems)로 꺼내, 설치된 descriptor 검사와
가짜 스키마 검사가 같은 함수를 쓴다. 새 describe가 z.undefined() 같은
NoContent 검증기로 탐침이 UNREACHED인지, 행이 direction을 빼면 실패하는지,
정책을 빼거나 적어도 통과하는지 본다. 매뉴얼 01, errors.md, CHANGELOG
1106 절의 먼저 할 일 1과 07-02 행에 적었다.
검사를 느슨하게 한 것이 아닌 이유: 탐침은 객체가 없는 스키마의 모르는
필드 정책을 판정할 수 없다. 그 자리의 비교는 맞는 답이 없는 질문이었다.
e7b1b01 전에는 칸을 빼면 이 자리 전체를 건너뛰었다. 지금은 direction을
요구하므로 그때보다 넓다. 객체에 닿는 스키마의 정책 비교는 그대로다.
버린 대안: 행 타입에 객체가 아닌 본문용 값을 더한다. src/contracts의
SchemaDefinition 모양, 분류기, 기준선이 함께 바뀐다.

위험·한계: 행이 UNREACHED 스키마에 적은 정책 값은 아무도 검사하지 않는다.
루트에서 이슈 하나로 거절하는 union(zod `invalid_union`, 예:
strict 객체 | null)도 UNREACHED가 되어 정책 비교에서 빠진다(추론, 실행하지
않음). 고친 곳이 테스트 파일 자신이라 RED는 테스트 파일만으로
만들 수 없다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts

Refs: 1106/07-02 (diff review DR-04)
2026-11-06 07:58:07 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

verify:documentation은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 .md 전부)에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와 셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(clean-architecture-backend-template)의 경로와 링크는 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다. 이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝 checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과 artifacts/quality/documentation-review.json에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를 가리키지 않으면(저장소 이름 오타 포함) 실패한다. CHANGELOG.md는 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 scripts/verify-documentation-readiness.ts다. 복사한 프로젝트가 지울 수 있는 템플릿 기능(참조 기능, 예제 화면. 목록은 scripts/lib/removable-template-features.ts)의 경로와 script는 그 기능이 설치돼 있을 때 (src/features/<id>/feature-module.ts가 있을 때) 검사하고, 지운 뒤에는 없어도 된다.

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
repo 루트의 artifacts/tests/a11y-manual/ 라우트별 기록 verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다. reviews/adapters/는 지우지 않는다: INVENTORY의 행과 operations/adapter-remediation-ledger.md가 그 안의 리뷰로 링크한다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 그 라운드는 0.2.0(CHANGELOG.md)으로 끝났다. 그때 리뷰 문서(reviews/2026-09-25-maturity-review/)가 이 경로(SPEC.md:18 등)로 가리키므로 옮기지 않는다