docs: align AI guard guide with current runtime contract
This commit is contained in:
1 parent
dea3083dfa
commit
d18e3c3380
1 file changed
+5
-3
@@ -12,12 +12,14 @@ JSON schemaVersion 2는 기존 `status`, exit code, 원본 `issues`를 유지하
|
||||
|
||||
## Theme Token 검사
|
||||
|
||||
현재 확장 규칙은 아래 [CSS Intent와 동적 Token 검사](#css-intent와-동적-token-검사-2026-10-10)를 함께 적용한다. 현재 suite는 Guard 75개·증거 연결 20개·요구사항 연결 5개다. 아래 63개/11개 및 51개/46개 테스트 수와 안정화 설명은 당시 기록이다.
|
||||
현재 확장 규칙은 아래 [CSS Intent와 동적 Token 검사](#css-intent와-동적-token-검사-2026-10-10)를 함께 적용한다. 2026-10-11 최신 자동 회귀는 Guard 94개·증거 연결 20개·요구사항 연결 5개, 합계 **119/119 PASS**다([최종 Baseline 근거](../reports/hmdesign-v2-final-baseline-2026-10-11.md#최신-guardcomponent-및-foundation-증거)). 과거 75개는 CSS Intent·동적 Token 확장 당시 `scripts/ai-generation-guard.test.mjs`의 테스트 사례 수이며 Guard 규칙 수나 Runtime Theme 입력 수가 아니다. 아래 63개/11개 및 51개/46개 테스트 수와 안정화 설명도 당시 기록이다. 이후 수량은 세 테스트 파일의 실제 사례와 실행 로그의 `tests/pass/fail/skipped`를 대조한다. 자동 회귀 PASS는 Guard Runtime·소비 CSS Design Intent의 NOT VERIFIED를 해소하지 않는다.
|
||||
|
||||
`TOKEN-001`: CSS 선언 값, JSX style 문자열, Tailwind 임의 값·v4 shorthand의 `var(--hm-...)` 참조가 연결된 공개 Theme/Status CSS 또는 소비 CSS/inline custom property 선언에 없으면 FAIL. 사용되지 않은 파일이나 다른 lazy Story의 선언은 빌리지 않는다. fallback 색이 있어도 없는 HM token은 FAIL이다. 파싱 불가 public CSS 정의는 NOT VERIFIED. 계산된 HM 참조는 유한 후보 전체를 확인하고, 해석 불가 참조는 `TOKEN-002` NOT VERIFIED다. selector별 cascade·실제 computed value는 브라우저 확인 대상이다. HM 이외 변수도 수집하지만, 연결 선언이 없는 외부 host 변수는 HM 미정의 FAIL과 구분하여 NOT VERIFIED로 남긴다.
|
||||
|
||||
`tokenEvidence`는 entry별 연결 정의 수와 검사한 참조를 제공한다. 공개 Token의 정답은 실제 연결 CSS 및 [Runtime 계약표](runtime-theme-contract.md)다. Component mapping은 runtime JSON key와 같은 집계가 아니다. 별도 토큰·색상은 추가하지 않는다.
|
||||
|
||||
현재 Runtime Theme 공개 입력은 [contract.ts](../../packages/ui/src/theme/contract.ts)의 `runtimeThemeContract` 최상위 Key **94개**다. `type: "color"` 92개는 [Default Theme JSON](../../themes/default.json)의 `tokens` Key 92개와 대응하며, `type: "radius"` 2개는 package에서 관리한다. 계약 변경 시 이 객체의 Key·type별 개수와 JSON `tokens` Key 집합을 대조하여 재집계한다. Guard는 실제 bootstrap에 연결된 CSS 선언과 사용 참조를 검사하므로 검사 범위를 Runtime 입력 94개로 제한하지 않는다. Guard 회귀 사례 94개와 Runtime 입력 94개는 집계 대상이 달라 서로 연동되는 수량이 아니다.
|
||||
|
||||
`node scripts/public-theme-tokens.mjs`로 연결된 공개 CSS의 선언 목록을 JSON으로 출력한다. 기준 Commit `3ebc84e32cf91298a2a4d8046753244c499fd719`에서 **1,203개 고유 `--hm-*` 선언명**이며 Runtime JSON 입력 Key 94개와 다르다. 집계 범위는 `@hm-design/ui/theme.css` + `@hm-design/ui/dashboard-status.css`의 연결 CSS이고 `definitionCount` / `incomplete: false`를 확인한다. selector마다 반복된 선언의 총 행 수나 Guard 규칙 수가 아니며 CSS가 바뀌면 위 명령으로 재집계한다.
|
||||
|
||||
보존된 검증은 기존 전체 범위 **FAIL 0 / NOT VERIFIED 16건**과 최신 변경 범위 **FAIL 0 / NOT VERIFIED 12건**으로 서로 다른 scope·source fingerprint의 기록이다. 둘을 합치거나 전체 PASS로 표현하지 않는다. 원본 CSS styleEvidence는 STATIC PASS / RUNTIME NOT VERIFIED / DESIGN_INTENT PASS / FINAL NOT VERIFIED이며 결합 styleVerification의 NOT VERIFIED도 유지한다. Native role widget은 `REUSE-006`으로 근거 검토를 요구하고 일반 콘텐츠 HTML은 허용한다.
|
||||
@@ -32,7 +34,7 @@ node scripts/guard-evidence.mjs guard.json runtime.json
|
||||
|
||||
결합 결과는 정적 PASS + 일치하는 해시 + 네 viewport PASS + 핵심 동작 PASS일 때만 PASS다. 정적 FAIL, native/CSS intent의 미검증은 제거하지 않는다. 소스·공개 계약 변경 시 이전 증거는 NOT VERIFIED다. Runtime JSON은 제출된 검사 증거이며 도구가 독립 인증하거나 모든 상태를 보장하는 것은 아니다. `guard-evidence.test.mjs`가 오래된 증거, 누락 viewport/동작, 정적 FAIL/미검증 보존을 검사한다. 원본 `status`와 결합 결과를 혼용하지 않는다.
|
||||
|
||||
`--result`의 React bootstrap 증명이 없거나 RENDER-001이면 결합 PASS를 허용하지 않는다. 결합 결과도 원본 FULL_SCREEN/PARTIAL scope를 그대로 상속한다. 당시 확장은 Guard 51+12=63개, 증거 연결 5+6=11개였다. 이후 CSS Intent·동적 Token 확장으로 현재 Guard 75개·증거 연결 20개이며, 요구사항 연결 5개는 별도 suite다. 과거 결과는 당시 기록으로 보존한다.
|
||||
`--result`의 React bootstrap 증명이 없거나 RENDER-001이면 결합 PASS를 허용하지 않는다. 결합 결과도 원본 FULL_SCREEN/PARTIAL scope를 그대로 상속한다. 당시 확장은 Guard 51+12=63개, 증거 연결 5+6=11개였다. 이후 CSS Intent·동적 Token 확장 당시 Guard 75개·증거 연결 20개였으며, 요구사항 연결 5개는 별도 suite다. 최신 자동 회귀 수량은 위 Theme Token 검사 절을 따른다. 과거 결과는 당시 기록으로 보존한다.
|
||||
|
||||
재현 가능한 예제: `examples/ai-quality`의 10개 독립 bootstrap. `node scripts/verify-quality-runtime.mjs`는 각 실제 dist 화면을 검사하고 Guard·Runtime·결합 JSON과 캡처를 `_local/quality-20261010`에 각각 기록한다. Playwright 경로는 `HM_PLAYWRIGHT_DIR`, Chrome 실행 경로는 `HM_CHROME_PATH`, 서버 URL은 `HM_QUALITY_URL`로 명시한다. 실패 범위 재검사는 인자로 화면 ID를 전달한다.
|
||||
|
||||
@@ -188,7 +190,7 @@ node scripts/guard-evidence.mjs <새 guard.json> <동일 source/contract의 새
|
||||
node --test scripts/ai-generation-guard.test.mjs scripts/guard-evidence.test.mjs scripts/guard-requirements.test.mjs
|
||||
```
|
||||
|
||||
전체 292 Story 재렌더나 신규 AI 화면/모델 호출은 필요 없다. 기존 63/11개 본문은 보존하고 현재 Guard 75개·증거 연결 20개·요구사항 연결 5개를 함께 검사한다. 과거 원본 FAIL/NOT VERIFIED 증거는 보존하고 새로운 결과를 별도 위치에 저장한다.
|
||||
전체 292 Story 재렌더나 신규 AI 화면/모델 호출은 필요 없다. 기존 63/11개 본문은 보존하며, 이 확장 당시 회귀는 Guard 75개·증거 연결 20개·요구사항 연결 5개였다. 최신 자동 회귀 수량은 위 Theme Token 검사 절을 따른다. 과거 원본 FAIL/NOT VERIFIED 증거는 보존하고 새로운 결과를 별도 위치에 저장한다. 문서만 수정하고 검사 소스·계약·화면이 불변이면 유효한 기존 PASS 로그를 재사용하며 정상 suite를 반복하지 않는다.
|
||||
|
||||
## 2026-10-10 필수 스타일 누락 (R1)
|
||||
|
||||
|
||||
Reference in new issue
Block a user