@walwal-harness/cli 4.0.0-alpha.2 → 4.0.0-alpha.20

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

@@ -1,173 +0,0 @@
----
-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. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `pwd` + `.harness/progress.json` + `git log --oneline -20`
-5. `.harness/actions/api-contract.json` 읽기 — **서버 API 계약이 Source of Truth**
-6. `.harness/actions/feature-list.json` — `layer: "frontend"` 필터
-7. `.harness/actions/pipeline.json` 의 **`fe_target`** 확인 (`web` | `mobile` | `desktop`)
-   - 이 값에 따라 허용되는 API, 빌드 명령, 안티패턴이 달라진다 (아래 "fe_target 분기" 섹션 참조)
-8. `pubspec.yaml` 확인 — Flutter 버전, Riverpod/Retrofit/json_serializable 의존성 존재 확인
-   - `fe_target = web` 인 경우 `flutter config --enable-web` 활성화 + `web/index.html` 존재 확인
-
-## 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 직접 호출 (fe_target 별 차이 포함) | 구현 완료 후 셀프 체크 |
-| [Flutter Web Pattern](references/flutter-web-pattern.md) | Web 전용 — `dart:html`/`package:web` 허용, 라우팅, 빌드, hosting | `fe_target = web` 일 때만 |
-
-## fe_target 분기
-
-`pipeline.json.fe_target` 에 따라 적용되는 규칙이 다르다:
-
-### `fe_target = web` (Flutter Web)
-
-- **빌드**: `flutter build web --release` / 개발 서버: `flutter run -d chrome`
-- **HTML/JS 인터롭 허용**: `dart:html`, `package:web`, `dart:js_interop` 사용 가능
-  - 단, 가능하면 cross-platform 코드를 우선하고 web 전용 코드는 `if (kIsWeb)` 가드 또는 conditional import
-- **라우팅**: `go_router` 권장 (URL 동기화). `Navigator 1.0` 의 `MaterialApp.routes` 도 OK 지만 hash routing 주의
-- **자산**: `web/index.html`, `web/manifest.json`, `web/icons/` 관리. SEO 가 필요하면 `<meta>` 태그 명시
-- **CORS**: 백엔드 API 가 `localhost:포트` 에서 다른 origin 일 수 있으므로 CORS 설정 확인
-- **Eval 흐름**: Playwright 기반 `evaluator-functional` + `evaluator-visual` 이 정상 작동 (브라우저 E2E + 시각 검증)
-- 상세 → [Flutter Web Pattern](references/flutter-web-pattern.md)
-
-### `fe_target = mobile` (Android / iOS)
-
-- **빌드**: `flutter build apk` / `flutter build ios` / 개발: `flutter run -d <device>`
-- **HTML/JS 인터롭 금지**: `dart:html`, `package:web`, `universal_html` 직접 참조 → 빌드 실패
-- **플랫폼 채널**: 네이티브 기능 사용 시 `MethodChannel` 또는 검증된 plugin 사용
-- **권한**: `AndroidManifest.xml` / `Info.plist` 에 권한 명시
-- **Eval 흐름**: 정적 분석 기반 `evaluator-functional-flutter` 사용 (Playwright 불가)
-
-### `fe_target = desktop` (macOS / Windows / Linux)
-
-- **빌드**: `flutter build macos` / `flutter build windows` / `flutter build linux`
-- **HTML/JS 인터롭 금지**: 모바일과 동일
-- **윈도우 관리**: `window_manager` 등 플러그인으로 윈도우 크기/위치 제어
-- **Eval 흐름**: 정적 분석 기반 `evaluator-functional-flutter` 사용
-
-## 핵심 규칙
-
-### 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

@@ -1,320 +0,0 @@
----
-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 직접 참조 (fe_target 별 차이)
-
-### `fe_target = mobile` 또는 `desktop` — 금지
-```dart
-import 'dart:html';                              // ✗
-import 'package:universal_html/html.dart';       // ✗
-import 'package:web/web.dart';                   // ✗ (가드 없으면)
-```
-
-### 이유
-Flutter 모바일/데스크톱 빌드에서 `dart:html` 참조는 즉시 빌드 실패한다.
-가드 없이 import 하면 cross-platform 코드가 깨진다.
-
-### 대체
-- `kIsWeb` 분기로 플랫폼 체크 후 조건부 import
-- `if (kIsWeb) { ... }` 가드 안에서만 web API 사용
-- 또는 conditional import (`stub.dart` / `web.dart` / `io.dart`)
-
-### `fe_target = web` — 허용 (단, 권장 패턴 준수)
-```dart
-import 'package:web/web.dart' as web;            // ✓ 권장 (modern)
-import 'dart:js_interop';                        // ✓ JS interop
-import 'dart:html';                              // ✓ (legacy, 신규 코드는 package:web 권장)
-```
-
-### Web 권장 패턴
-- 새 코드는 `package:web` + `dart:js_interop` 사용 (Flutter 3.7+ 에서 stable)
-- `dart:html` 은 legacy — 마이그레이션 대상이지만 즉시 금지는 아님
-- 가능하면 web 전용 코드를 별도 파일로 분리하고 conditional import:
-  ```dart
-  // _web_helper.dart 또는 conditional import
-  import 'platform_helper.dart'
-    if (dart.library.html) 'platform_helper_web.dart'
-    if (dart.library.io) 'platform_helper_io.dart';
-  ```
-
-### 검증
-```bash
-# fe_target = mobile/desktop: 0개여야 함
-grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/
-
-# fe_target = web: 매치 OK, 단 'kIsWeb' 가드 또는 conditional import 와 함께 쓰는지 인접 라인 확인
-```
-
----
-
-## 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에 기록한다.
-**`fe_target` 에 따라 1번 룰의 적용 여부가 달라진다.**
-
-```bash
-# fe_target 읽기
-FE_TARGET=$(jq -r '.fe_target // "web"' .harness/actions/pipeline.json 2>/dev/null || echo "web")
-
-# 1. 웹 API 직접 참조 — fe_target=web 이 아닐 때만 검사
-if [ "$FE_TARGET" != "web" ]; then
-  grep -rn "dart:html\|universal_html\|package:web" lib/ integrated_data_layer/lib/ || echo "OK (FL-01 mobile/desktop)"
-else
-  # web 타겟: 가드 없는 사용만 경고 (수동 검토)
-  grep -rn "dart:html\|package:web" lib/ | grep -v "kIsWeb\|conditional import" || echo "OK (FL-01 web — manual review)"
-fi
-
-# 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 가능.