문제: 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에서 금지).
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.
고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
<값>; contrast needs an opaque oklch(L C H), hue in degrees with or
without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.
위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.
검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
"names the value it cannot compute …" 메시지 불일치, "-apple-system"
expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
/ 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR
Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지
않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는
글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel
diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다.
고른 방법 (리뷰 4.1절 c′, 사용자 결정):
- tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리
(truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다.
playwright.visual.config.ts가 use.launchOptions.env로 그 파일을
FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI
workflow는 바꾸지 않았다.
- 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault,
autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와
sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고).
- visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를
chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고
CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다.
다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지
않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로
감싼다. test:visual:update도 같은 검사를 먼저 거친다.
버린 대안:
- fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고,
Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는
Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다.
그래서 탐침도 앱 페이지 안에 넣는다.
- document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다.
- /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와
Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다.
리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다.
- 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각.
위험·한계:
- 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면
이름 검사는 통과하고 pixel diff로 실패할 수 있다.
- generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation
Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트
(예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는
visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다.
- 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도
보인다. 탐침 4종이 바뀌면 검사가 잡는다.
- Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다.
- 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를
넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다.
- 골든은 다시 찍지 않았다.
검증 (같은 dist, flock, `npx playwright test --config
playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만
vite preview로 바꾼 로컬 사본으로 실행):
- 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu):
5 failed, toHaveScreenshot diff(46,356 px, 4%)
- 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께
latin=DejaVu Sans, korean=WenQuanYi Zen Hei
- RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run.
같은 설치 안내 + "The font probe page did not render"
- GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5)
- 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy,
sub-pixel-rgb 제외): 6 passed
- 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이
5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed
- tsc(app·node·test), eslint, check-test-evidence --source-only PASS,
verify-documentation-readiness PASS_SCOPED, vitest supply-chain과
tests/architecture 53 passed
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절
AsyncSurface drew auth-required, forbidden and not-found query failures with
its own copy while the gallery used AccessSurface. Both now use one set, and
a state surface without a handler shows no dead button.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
theme.css (1435 lines) is now an import-order entry point: tailwind, the
three token files, then styles/theme/{base,shell,primitives,templates,
pages,responsive}.css holding the original rules verbatim and in the same
order (components-layer chunks each wrap their part in
`@layer components`). check-design-system now reads every CSS file under
styles/ so the undefined-token check still covers the moved rules; the
design-system doc names the new layout.
Verified: `corepack pnpm build` before and after produce the same CSS
asset, dist/assets/index-6KRF2bCu.css, byte-identical (cmp and sha256
bdaa8521...). A probe undefined token in theme/pages.css fails
check:design-system. Lane gates pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>