@walwal-harness/cli 2.0.0 → 2.3.0

package/skills/evaluator-functional-flutter/references/scoring-rubric.md

@@ -0,0 +1,132 @@
+---
+docmeta:
+  id: scoring-rubric
+  title: Flutter Functional Evaluation 스코어링 루브릭
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-evaluator-functional-flutter
+  inputs:
+    - documentId: react-evaluator-scoring-rubric
+      uri: ../../evaluator-functional/references/scoring-rubric.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 53
+          targetRange:
+            startLine: 32
+            endLine: 160
+  tags:
+    - evaluator
+    - flutter
+    - scoring
+    - rubric
+---
+
+# Flutter Functional Evaluation 스코어링 루브릭
+
+## 차원별 채점
+
+| 차원 | 가중치 | 하드 임계값 | 측정 방법 |
+|------|--------|------------|----------|
+| Static Analysis | 25% | warning/error 0개 | `flutter analyze --no-fatal-infos` |
+| Test Pass Rate | 25% | 100% | `flutter test` 모든 스위트 |
+| API Contract 준수 | 25% | 100% | rest_api.dart vs api-contract.json 대조 — 불일치 즉시 FAIL |
+| Anti-Pattern 청결 | 15% | 위반 0건 | static-check-rules.md 의 FL-01 ~ FL-08 |
+| Contract Criteria 충족률 | 10% | 80% | sprint-contract.md FE 기준 통과 수 / 전체 |
+
+**어떤 차원이든 하드 임계값 미달 → 스프린트 FAIL**
+
+## 차원별 점수 계산
+
+### Static Analysis (25점)
+
+| 결과 | 점수 |
+|------|------|
+| error 0, warning 0 | 25 |
+| error 0, warning 1~2 | 0 (하드 임계값 미달 → FAIL) |
+| error 1+ | 0 (즉시 FAIL) |
+
+info 수준은 점수에 반영하지 않지만 보고서에 카운트 기록.
+
+### Test Pass Rate (25점)
+
+```
+score = 25 * (passed / total)
+```
+
+- `total == 0` (테스트 존재하지 않음) → **0점 + FAIL** (Coverage gate)
+- `fromJson/toJson` 왕복 테스트 누락 (이번 스프린트 추가분) → **FAIL**
+
+### API Contract 준수 (25점)
+
+```
+score = 25 * (matched_endpoints / total_endpoints)
+```
+
+불일치 허용 없음 — 1개라도 불일치면 즉시 FAIL (하드 임계값 100%).
+
+매칭 체크:
+- method (GET/POST/PUT/DELETE)
+- path (변수명 포함)
+- path param → `@Path(...)` 매핑
+- body → `@Body() XxxBody`
+- response 타입 → 계약 스키마의 code/data/errors 구조
+
+### Anti-Pattern 청결 (15점)
+
+```
+score = 15 * (passed_rules / total_rules)
+```
+
+- 8개 룰 중 1개라도 FAIL → **0점 + 스프린트 FAIL**
+- 위반 0건이면 15점
+
+### Contract Criteria 충족률 (10점)
+
+```
+score = 10 * (passed_criteria / total_criteria)
+```
+
+- 80% 미달 → FAIL
+- 개별 기준의 실패 사유를 "Failures Detail"에 기록
+
+## Total
+
+```
+total = static_analysis + test_pass + api_contract + anti_pattern + contract_criteria
+verdict = PASS (if all hard thresholds met AND total >= 80) else FAIL
+```
+
+## failure_location 라우팅
+
+Flutter 앱은 항상 FE 재작업이므로:
+
+| location | 재작업 대상 |
+|----------|-----------|
+| `frontend` (기본) | `generator-frontend-flutter` |
+
+예외: API Contract 불일치가 **서버 측 계약 오류**로 확인된 경우 → Planner에게 계약 수정 요청 필요.
+이 경우 evaluation에 `## Change Request` 섹션 추가.
+
+## evaluation-functional.md 헤더
+
+```markdown
+# Flutter Functional Evaluation: Sprint [N]
+
+## Date: [YYYY-MM-DD]
+## Verdict: PASS / FAIL
+## Attempt: [N] / 10
+## Stack: flutter
+
+## Total Score: [N] / 100
+| Dimension | Score | Threshold | Status |
+| Static Analysis | X/25 | warning=0 | PASS/FAIL |
+| Test Pass Rate | X/25 | 100% | PASS/FAIL |
+| API Contract | X/25 | 100% | PASS/FAIL |
+| Anti-Pattern | X/15 | 0 violations | PASS/FAIL |
+| Contract Criteria | X/10 | 80% | PASS/FAIL |
+```

package/skills/evaluator-functional-flutter/references/static-check-rules.md

@@ -0,0 +1,99 @@
+---
+docmeta:
+  id: static-check-rules
+  title: Flutter 정적 검증 룰 (Anti-Pattern Gate)
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-evaluator-functional-flutter
+  inputs:
+    - documentId: flutter-anti-patterns
+      uri: ../../generator-frontend-flutter/references/anti-patterns.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 1
+            endLine: 280
+          targetRange:
+            startLine: 32
+            endLine: 180
+  tags:
+    - evaluator
+    - flutter
+    - static-check
+    - anti-pattern
+---
+
+# Flutter 정적 검증 룰
+
+Generator의 `anti-patterns.md` 를 Source of Truth 로 삼아 정적 검증을 수행한다.
+Generator가 신규 룰을 추가하면 Evaluator는 자동으로 그 룰을 따르게 된다 — **두 문서 간 drift 금지.**
+
+## 실행 방법
+
+**Evaluator는 반드시** `skills/generator-frontend-flutter/references/anti-patterns.md` 의
+"셀프 체크 스크립트" 섹션을 **파일로 읽어서 그대로 실행**한다. 하네스의 단일 진실 원칙.
+
+```bash
+# anti-patterns.md 에서 bash 블록만 추출해서 실행
+awk '/^```bash$/,/^```$/' skills/generator-frontend-flutter/references/anti-patterns.md
+```
+
+## 룰 요약 (Evaluator가 결과를 표로 정리)
+
+| Rule ID | 설명 | 명령 | Fail 조건 |
+|---------|------|------|----------|
+| FL-01 | 웹 API 직접 참조 | `grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/` | 매치 1+ |
+| FL-02 | print/console 남발 | `grep -rn "^\s*print(" lib/ integrated_data_layer/lib/` | 매치 1+ |
+| FL-03 | 하드코딩 색상 (신규) | `git diff --name-only --diff-filter=A HEAD~N..HEAD \| grep '\.dart$' \| xargs grep -n "Color(0x"` | 매치 1+ (`ColorManager` 참조 제외) |
+| FL-04 | StatefulWidget 직접 API 호출 | 수동 감사 — `_page.dart` 에 `dataLayer\|DataLayer` 호출이 있는데 짝 `_page_vm.dart` 없음 | 패턴 발견 |
+| FL-05 | bridges/ 신규 참조 | `git diff HEAD~N..HEAD \| grep "^+.*bridges/"` | 매치 1+ |
+| FL-06 | 하드코딩 한글 (신규 UI) | `git diff --name-only --diff-filter=AM HEAD~N..HEAD \| grep 'lib/ui/.*\.dart$' \| xargs grep -n "Text('[가-힣]"` | 매치 1+ |
+| FL-07 | JsonSerializable includeIfNull 누락 | `grep -rn "@JsonSerializable" integrated_data_layer/lib/2_data_sources/remote/request/body/ \| grep -v "includeIfNull: false"` | 매치 1+ |
+| FL-08 | API 키/시크릿 하드코딩 | `grep -rEn "(api[_-]?key\|secret\|token)\s*=\s*['\"][A-Za-z0-9]{16,}['\"]" lib/ integrated_data_layer/lib/` | 매치 1+ |
+
+> `HEAD~N` 의 N은 sprint_commits 수 — `git log --format=%h HEAD~sprint_start..HEAD` 로 결정.
+
+## FL-04 수동 감사 방법
+
+```bash
+# 1. 신규/수정된 page 파일 목록
+PAGES=$(git diff --name-only HEAD~N..HEAD | grep '_page\.dart$')
+
+# 2. 각 page에서 API 호출 존재 여부
+for p in $PAGES; do
+  if grep -q "dataLayer\|DataLayer" "$p"; then
+    vm="${p%_page.dart}_page_vm.dart"
+    if [ -f "$vm" ] && grep -q "dataLayer\|DataLayer" "$vm"; then
+      echo "OK (VM handles API): $p"
+    else
+      echo "FAIL (page calls API without VM): $p"
+    fi
+  fi
+done
+```
+
+VM이 없고 페이지가 직접 호출하면 **FL-04 FAIL**.
+
+## 결과 집계
+
+```markdown
+## Step 4: Anti-Pattern
+
+| Rule | Status | Count | Files |
+|------|--------|-------|-------|
+| FL-01 dart:html | PASS/FAIL | 0 | - |
+| FL-02 print | PASS/FAIL | 0 | - |
+| FL-03 color hardcode | PASS/FAIL | 0 | - |
+| FL-04 stateful API call | PASS/FAIL | 0 | - |
+| FL-05 bridges/ new | PASS/FAIL | 0 | - |
+| FL-06 ko hardcode | PASS/FAIL | 0 | - |
+| FL-07 includeIfNull missing | PASS/FAIL | 0 | - |
+| FL-08 secret hardcode | PASS/FAIL | 0 | - |
+
+Overall: PASS / FAIL
+```
+
+**어떤 룰이든 FAIL 1건 → Step 4 전체 FAIL → 스프린트 FAIL** (하드 임계값: 위반 0건).

package/skills/generator-frontend-flutter/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: harness-generator-frontend-flutter
+description: "하네스 Flutter Frontend Generator. Flutter(Dart) + Riverpod + integrated_data_layer(Retrofit) 기반 모바일 앱을 구현한다. ARB 다국어, JsonSerializable, NotifierProvider 패턴 준수. api-contract.json이 Source of Truth — UI 추론 금지."
+disable-model-invocation: true
+---
+
+# Generator-Frontend-Flutter — Dart + Riverpod + integrated_data_layer
+
+## Session Boundary Protocol
+
+### On Start
+1. `.harness/progress.json` 읽기 — `next_agent`가 `"generator-frontend-flutter"`인지 확인
+2. `.harness/actions/pipeline.json`의 `fe_stack == "flutter"` 재확인 — 아니면 즉시 STOP + 사용자에게 불일치 보고
+3. progress.json 업데이트: `current_agent` → `"generator-frontend-flutter"`, `agent_status` → `"running"`, `updated_at` 갱신
+4. `failure` 필드 확인 — retry인 경우 평가 문서의 실패 사유 우선 읽기
+
+### On Complete
+1. progress.json 업데이트:
+   - `agent_status` → `"completed"`
+   - `completed_agents`에 `"generator-frontend-flutter"` 추가
+   - `next_agent` → `"evaluator-functional-flutter"`
+   - `failure` 필드 초기화
+2. `feature-list.json`의 해당 feature `passes`에 `"generator-frontend-flutter"` 추가
+3. `.harness/progress.log`에 요약 추가
+4. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
+5. 출력: `"✓ Generator-Frontend-Flutter 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`
+
+## Startup
+
+1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인 (Flutter 소유 경로)
+2. `.harness/gotchas/generator-frontend-flutter.md` 읽기 (없으면 skip) — **과거 실수 반복 금지**
+3. `pwd` + `.harness/progress.json` + `git log --oneline -20`
+4. `.harness/actions/api-contract.json` 읽기 — **서버 API 계약이 Source of Truth**
+5. `.harness/actions/feature-list.json` — `layer: "frontend"` 필터
+6. `pubspec.yaml` 확인 — Flutter 버전, Riverpod/Retrofit/json_serializable 의존성 존재 확인
+
+## AGENTS.md — 읽기 전용
+
+`[FE]` + `→ Generator-Frontend-Flutter` 소유 경로만 쓰기 가능. 일반적으로:
+- `lib/ui/pages/`, `lib/ui/component/`, `lib/l10n/`
+- `integrated_data_layer/lib/`, `integrated_data_layer/test/`
+- `assets/strings/`
+
+Backend 코드, `.harness/`, `AGENTS.md` 수정 금지.
+
+## Sprint Workflow
+
+1. **Sprint Contract FE 섹션 추가** — 페이지, VM, API 연동, 성공 기준
+2. **api-contract.json → Retrofit/JsonSerializable 변환**
+3. **구현** — 아래 4개 레퍼런스를 반드시 참조
+4. **코드 생성**: `flutter pub run build_runner build --delete-conflicting-outputs`
+5. **Self-Verification** — `flutter analyze` + `flutter test` 통과
+6. **Handoff** → Evaluator-Functional-Flutter
+
+## 개발론 레퍼런스 (점진적 로딩)
+
+| 문서 | 내용 | 언제 로드 |
+|------|------|----------|
+| [API Layer Pattern](references/api-layer-pattern.md) | integrated_data_layer 구조, Request/Response, Retrofit | API 연동 시 |
+| [Riverpod Pattern](references/riverpod-pattern.md) | Page+VM 쌍, NotifierProvider, family 패턴 | 페이지/위젯 구현 시 |
+| [i18n Pattern](references/i18n-pattern.md) | ARB 파일, LocaleAssist, 키 네이밍 | 문자열 추가 시 |
+| [Anti-Patterns](references/anti-patterns.md) | 금지 API, 하드코딩, bridges/, StatefulWidget 직접 호출 | 구현 완료 후 셀프 체크 |
+
+## 핵심 규칙
+
+### api-contract.json → Dart 변환 규칙
+
+- 각 엔드포인트 → `rest_api.dart`에 Retrofit 어노테이션 (`@GET`, `@POST`, `@PUT`, `@DELETE`)
+- Request body → `2_data_sources/remote/request/body/xxx_body.dart` (`@JsonSerializable(includeIfNull: false)`)
+- Response → `2_data_sources/remote/response/xxx_response.dart` (`ClueResponseImpl<T>` 상속 or 재사용)
+- **필수 지시가 없으면 모든 필드는 Nullable** — 서버가 언제든 필드를 누락할 수 있음
+- **기존 응답 타입 재사용 우선** — 동일 구조면 새 클래스 생성 금지
+- Repository 래퍼 메서드 추가 → `1_repositories/xxx_repository.dart`
+
+### UI / 상태관리
+
+- 모든 페이지 = `xxx_page.dart` + `xxx_page_vm.dart` 쌍
+- Page는 `ConsumerStatefulWidget` 또는 `ConsumerWidget`
+- VM은 `NotifierProvider<Notifier, State>` (다중 인스턴스는 `.family`)
+- State는 `Equatable` + `copyWith` 불변성
+- `ref.watch` (build 내) / `ref.read` (이벤트 핸들러, initState)
+- API 호출은 반드시 VM 안에서 `ref.read(dataLayer).xxx.method()`
+- Provider 네이밍: `p` + PascalCase + `Provider` (예: `pHomePageProvider`)
+
+### 다국어 (i18n)
+
+- 영문 전용 지시가 없는 한 **모든 사용자 노출 문자열은 ARB 경유 필수**
+- ARB: `lib/l10n/app_en.arb`, `app_ko.arb`, `app_ja.arb`
+- 코드 접근: `LocaleAssist().of.키이름`
+- 키 네이밍: camelCase (예: `doorOpen`, `networkError`)
+- 모든 언어 파일에 동일 키 동시 추가
+
+### 코드 생성
+
+Request Body / Response / rest_api.dart 수정 후 **반드시** 실행:
+
+```bash
+cd <integrated_data_layer 경로>
+flutter pub run build_runner build --delete-conflicting-outputs
+```
+
+## Self-Verification (Handoff 전)
+
+1. `flutter analyze` → 경고 0개 (info 수준은 허용, warning/error 금지)
+2. `flutter test` → 100% 통과
+3. integrated_data_layer의 새 Request Body / Response에 `fromJson`/`toJson` 왕복 테스트 존재
+4. `grep -rn 'dart:html\|universal_html\|print(\|console\.log' lib/ integrated_data_layer/lib/` → 0개
+5. `grep -rn "bridges/" lib/` → 신규 코드 내 참조 0개
+6. 하드코딩 색상(`Color(0xFF...`) → `ColorManager` 경유 확인
+7. 새 페이지/위젯은 `StatefulWidget`에서 직접 API 호출하지 않는지 확인 (VM/Provider 경유)
+
+## 금지 사항
+
+- Backend 코드 수정, 서버 API 경로 임의 변경
+- api-contract.json에 없는 엔드포인트 호출/추가
+- `dart:html`, `universal_html` 직접 참조
+- `print()` / `debugPrint` 남발 — `logger` 사용
+- 하드코딩 색상 → `ColorManager` 강제
+- `StatefulWidget` 내 직접 API 호출 → VM/Provider 경유
+- `bridges/` 신규 개발 — BLOC 기반 레거시, 유지보수만 허용
+- AI 추측으로 서버 응답 구조를 만들지 말 것 (계약이 Source of Truth)
+- API 키/시크릿 하드코딩
+
+## 명령어
+
+```bash
+flutter pub get                                                    # 의존성
+flutter run                                                        # 실행
+flutter test                                                       # 테스트
+flutter analyze                                                    # 정적 분석
+flutter pub run build_runner build --delete-conflicting-outputs    # 코드 생성
+```
+
+## After Completion
+
+1. sprint-contract.md의 FE 섹션에 완료 항목 체크
+2. Self-Verification 체크리스트 결과 요약
+3. Session Boundary Protocol On Complete 실행

package/skills/generator-frontend-flutter/references/anti-patterns.md

@@ -0,0 +1,288 @@
+---
+docmeta:
+  id: anti-patterns
+  title: Flutter Anti-Patterns & Forbidden APIs
+  type: output
+  createdAt: 2026-04-09T00:00:00Z
+  updatedAt: 2026-04-09T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-generator-frontend-flutter
+  inputs:
+    - documentId: clue-fe-flutter-skill
+      uri: ../../../../../moon_web/clue-fe-flutter.skill
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 62
+            endLine: 103
+          targetRange:
+            startLine: 32
+            endLine: 180
+  tags:
+    - flutter
+    - anti-patterns
+    - forbidden
+    - lint
+---
+
+# Flutter Anti-Patterns & Forbidden APIs
+
+**Generator는 구현 완료 전 이 문서를 보고 셀프 체크한다.**
+**Evaluator-Functional-Flutter 는 이 문서의 패턴을 `grep` 기반 정적 검증에 사용한다.**
+
+각 항목은 **패턴 → 이유 → 대체 방법** 형태.
+
+## 1. 웹 전용 API 직접 참조
+
+### 금지
+```dart
+import 'dart:html';
+import 'package:universal_html/html.dart';
+```
+
+### 이유
+Flutter 앱은 크로스 플랫폼 — 모바일 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
+Web 빌드 전용 코드가 필요하면 조건부 import 패턴을 사용한다.
+
+### 대체
+`package:web` 또는 `kIsWeb` 분기로 플랫폼 체크 후 조건부 import.
+
+### 검증
+```bash
+grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/
+```
+결과 0개여야 함.
+
+---
+
+## 2. print / console 남발
+
+### 금지
+```dart
+print("user clicked");
+debugPrint("response: $data");
+```
+
+### 이유
+프로덕션 빌드에 로그가 섞이면 성능/보안 문제. 통일된 로거가 없으면 분석 불가.
+
+### 대체
+프로젝트의 `logger` 모듈 사용 (`Logger().d()`, `.i()`, `.w()`, `.e()`).
+디버그 전용 출력도 `kDebugMode` 가드 필수.
+
+### 검증
+```bash
+grep -rn "^\s*print(" lib/ integrated_data_layer/lib/
+grep -rn "console\.log" lib/
+```
+
+---
+
+## 3. 하드코딩 색상
+
+### 금지
+```dart
+Container(color: Color(0xFF6682FF))
+Text('Hello', style: TextStyle(color: Colors.blue))
+```
+
+### 이유
+디자인 시스템 붕괴 + 다크모드/브랜딩 변경 시 전역 수정 불가.
+
+### 대체
+```dart
+Container(color: ColorManager.primary)
+Text('Hello', style: TextStyle(color: ColorManager.textPrimary))
+```
+
+`ColorManager` (또는 프로젝트의 Design Token) 경유 필수.
+
+### 검증
+```bash
+grep -rn "Color(0x" lib/ui/ | grep -v "ColorManager\|color_manager"
+```
+신규 파일에서 결과 0개여야 함 (레거시 파일은 예외).
+
+---
+
+## 4. StatefulWidget 내 직접 API 호출
+
+### 금지
+```dart
+class _MyPageState extends State<MyPage> {
+  @override
+  void initState() {
+    super.initState();
+    DataLayer.instance.ac.getExample(exampleId: 1).then((res) {  // ✗
+      setState(() { _data = res; });
+    });
+  }
+}
+```
+
+### 이유
+테스트 불가능, 상태 공유 불가, UI와 비즈니스 로직 결합.
+
+### 대체
+VM (`NotifierProvider`) 에 API 호출을 옮기고 Page는 `ConsumerWidget` 으로.
+상세 → [riverpod-pattern.md](./riverpod-pattern.md)
+
+### 검증
+`grep` 으로 자동 감지 어려움 — Evaluator가 신규 `*_page.dart` 파일에서
+`dataLayer\|DataLayer` 호출 패턴을 확인하고, 파트너 `*_page_vm.dart` 파일에
+동일 호출이 있는지 대조한다.
+
+---
+
+## 5. bridges/ 신규 사용
+
+### 금지
+```dart
+import 'package:clue_mobile_app/bridges/xxx.dart';
+```
+신규 코드에서 참조 금지.
+
+### 이유
+BLOC 기반 레거시 — Riverpod 마이그레이션 방침에 따라 유지보수만 허용.
+
+### 대체
+신규 상태관리는 `NotifierProvider` + `Notifier<State>`.
+
+### 검증
+신규/수정 파일의 git diff에서 `bridges/` import 추가 여부 확인.
+```bash
+git diff --name-only HEAD~1 | xargs grep -l "bridges/" 2>/dev/null
+```
+새로 추가된 줄이 있으면 FAIL.
+
+---
+
+## 6. 하드코딩 문자열 (다국어 미처리)
+
+### 금지
+```dart
+Text('취소')
+Text('로그인 실패')
+```
+
+### 이유
+i18n 원칙 위반 — 다국어 전환 시 즉시 깨짐.
+
+### 대체
+```dart
+Text(LocaleAssist().of.cancel)
+Text(LocaleAssist().of.loginFailed)
+```
+
+상세 → [i18n-pattern.md](./i18n-pattern.md)
+
+### 검증
+```bash
+grep -rn "Text('[가-힣ぁ-んァ-ヶ一-龯]" lib/ui/
+```
+신규 파일에서 결과 0개여야 함.
+
+---
+
+## 7. JsonSerializable 누락 / includeIfNull 잘못 설정
+
+### 금지
+```dart
+// @JsonSerializable 없이 수동 fromJson/toJson
+@JsonSerializable()  // includeIfNull 누락 → 기본값 true
+class UserBody { ... }
+```
+
+### 이유
+서버가 null 필드를 bad request 처리하는 API 계약 위배. 코드 생성 불일치.
+
+### 대체
+```dart
+@JsonSerializable(includeIfNull: false)
+class UserBody { ... }
+```
+
+Request Body는 **항상** `includeIfNull: false`.
+
+### 검증
+```bash
+grep -rn "@JsonSerializable" integrated_data_layer/lib/2_data_sources/remote/request/body/ | grep -v "includeIfNull: false"
+```
+결과 0개여야 함.
+
+---
+
+## 8. Non-null 남용
+
+### 금지
+```dart
+// 서버 응답에 대해 non-null 단정
+class ExampleData {
+  final String name;       // ✗ 필수 지시 없으면 Nullable
+  final int id;
+}
+```
+
+### 이유
+서버는 언제든 필드를 누락할 수 있음. non-null은 런타임 crash 유발.
+
+### 대체
+```dart
+class ExampleData {
+  final String? name;
+  final int? id;
+}
+```
+
+**필수 지시가 api-contract.json 에 명시된 필드만 non-null 허용.**
+
+---
+
+## 9. API 키 / 시크릿 하드코딩
+
+### 금지
+```dart
+const apiKey = "sk-1234567890abcdef";
+const Dio().options.headers['Authorization'] = 'Bearer xxx';
+```
+
+### 이유
+APK 디컴파일로 즉시 노출 — 보안 사고.
+
+### 대체
+`--dart-define` 또는 `flutter_dotenv` + `.env` (gitignore).
+런타임에 서버에서 발급받는 토큰 사용.
+
+### 검증
+```bash
+grep -rEn "(api[_-]?key|secret|token)\s*=\s*['\"][A-Za-z0-9]{16,}['\"]" lib/ integrated_data_layer/lib/
+```
+
+---
+
+## 셀프 체크 스크립트
+
+Generator는 handoff 전 다음 명령을 모두 실행하고 결과를 sprint-contract.md에 기록한다:
+
+```bash
+# 1. 웹 API 직접 참조
+grep -rn "dart:html\|universal_html" lib/ integrated_data_layer/lib/ || echo "OK"
+
+# 2. print 남발
+grep -rn "^\s*print(" lib/ integrated_data_layer/lib/ || echo "OK"
+
+# 3. 하드코딩 색상 (신규 파일만 — git diff 기반)
+git diff --name-only --diff-filter=A HEAD | grep '\.dart$' | xargs grep -n "Color(0x" 2>/dev/null || echo "OK"
+
+# 4. bridges/ 신규 참조
+git diff HEAD | grep "^+" | grep "bridges/" || echo "OK"
+
+# 5. JsonSerializable + includeIfNull 확인
+grep -rn "@JsonSerializable" integrated_data_layer/lib/2_data_sources/remote/request/body/ | grep -v "includeIfNull: false" || echo "OK"
+
+# 6. 하드코딩 한글 (신규 UI)
+git diff --name-only --diff-filter=AM HEAD | grep 'lib/ui/.*\.dart$' | xargs grep -n "Text('[가-힣]" 2>/dev/null || echo "OK"
+```
+
+모두 `OK` 여야 handoff 가능.