interface TestResult {
  success: boolean;
  verdict:  ' pass '   |  ' fail '   |  ' unknown ' ;   // tri-state — `unknown` 은 PASS 가 아니다
  summary: TestSummary;
  failures: TestFailure[];
  skips: TestSkip[];                      // 건너뜀·시간 초과 전수 목록 — 비어 있어야 verdict: ' pass '   가능
  coverage?: CoverageReport;
  backend_tests?: BackendTestResult;
  fixed_tests: string[];
  autoFix: AutoFixReport;                 // 위임된 루프의 내구 보고 (호출 지점이 읽는다)
}

interface TestSummary {
  total: number;
  passed: number;
  failed: number;
  skipped: number;
  timedOut: number;      // 개별 30s 초과로 중단된 수 — skipped 와 별도로 센다
  duration: string;
}

interface TestSkip {
  id: string;            // ` < file > :: < test name > ` — 파일만으로는 무엇이 빠졌는지 알 수 없다
  reason:
    |  ' individual-timeout-30s ' 
     |  ' suite-budget-exhausted ' 
     |  ' explicit-skip '           // `skip:` / `@Skip` 이 소스에 있었다
    |  ' non-fixable ' ;
}

interface AutoFixReport {
  roundsUsed: number;        // 0..3 — 실제로 돈 attempt 수
  testsWeakened: string[];   // 단정/`skip:`/타임아웃 상향을 건드린 흔적. 비어 있지 않으면 verdict: ' fail ' 
   filesTouched: string[];
}

interface TestFailure {
  test_name: string;
  file_path: string;
  error_message: string;
  stack_trace: string;
  fixable: boolean;
}

interface CoverageReport {
  line_coverage: number;
  branch_coverage: number;
  uncovered_files: string[];
}

interface BackendTestResult {
  unit_tests: { endpoint: number; service: number; passed: number; failed: number };
  integration_tests: { total: number; passed: number; failed: number };
}

# Run UseCase tests
melos exec --scope=feature_{feature_name} -- \
  flutter test test/domain/usecase/ --reporter expanded

# Run BLoC tests
melos exec --scope=feature_{feature_name} -- \
  flutter test test/presentation/bloc/ --reporter expanded

┌─────────────────────────────────────────────────────────┐
│  Step 0: Existing Test Verification (Baseline) ⚠️        │
├─────────────────────────────────────────────────────────┤
│  - Run all existing tests for related packages           │
│  - On failure → fix implementation code or existing tests first │
│  - Record baseline pass rate (for regression verification) │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 0.5: Check Test Existence and Delegate Creation    │
├─────────────────────────────────────────────────────────┤
│  [Frontend test check]                                   │
│  - UseCase test files exist? → Call unit-test-agent if missing │
│  - BLoC test files exist? → Call bloc-test-agent if missing │
│  [Backend test check - on Backend changes]               │
│  - Endpoint tests exist? → serverpod-test-agent if missing │
│  - Service logic tests exist? → serverpod-test-agent if missing │
│  - Integration tests exist? → Call serverpod-test-agent if missing │
│  ⚠️ PR creation blocked if tests are not written         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 1: Prepare Test Environment                        │
├─────────────────────────────────────────────────────────┤
│  $ melos run build                                      │
│  - Verify code generation complete                       │
│  - Verify no analysis errors                             │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Run Unit Tests                                  │
├─────────────────────────────────────────────────────────┤
│  $ melos exec --scope=feature_{name} --                 │
│      flutter test test/domain/usecase/                  │
│  - Verify UseCase logic                                  │
│  - Verify Mock setup                                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Run BLoC Tests                                  │
├─────────────────────────────────────────────────────────┤
│  $ melos exec --scope=feature_{name} --                 │
│      flutter test test/presentation/bloc/               │
│  - Verify State transitions                              │
│  - Verify Event handling                                 │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3.5: Run Backend Tests (on Backend changes) ⚠️     │
├─────────────────────────────────────────────────────────┤
│  [Unit tests]                                            │
│  $ melos exec --scope=kobic_server --                   │
│      dart test test/unit/{feature}/                     │
│  - Verify endpoint logic                                 │
│  - Verify service business logic                         │
│  [Integration tests]                                     │
│  $ melos exec --scope=kobic_server --                   │
│      dart test test/integration/{feature}/              │
│  - withServerpod-based E2E verification                  │
│  - Auth/permission verification                          │
│  - CRUD flow verification                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: (Retired) BDD Widget Tests                      │
├─────────────────────────────────────────────────────────┤
│  BDD .feature scenarios no longer generate widget tests. │
│  They run only as Patrol E2E under app/{app}/            │
│  integration_test/ — outside this feature-scoped agent.  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Result Analysis and Auto-Fix                    │
├─────────────────────────────────────────────────────────┤
│  IF failed tests exist:                                  │
│    - Analyze failure cause                               │
│    - Determine if auto-fix is possible                   │
│    - Attempt auto-fix (up to 3 times) — contract L-TR-autofix │
│    - prog: failing count strictly decreases each attempt │
│      unchanged count → end loop immediately (no 3rd burn) │
│    - Return {roundsUsed, testsWeakened[], filesTouched[]} │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 6: Verification Gate (required before PR) ⚠️       │
├─────────────────────────────────────────────────────────┤
│  verdict: pass | fail | unknown   (undet:fail)           │
│  - Frontend: UseCase test ≥ 1 passed                     │
│  - Frontend: BLoC test ≥ 1 passed                        │
│  - (On Backend changes) Backend unit tests passed        │
│  - (On Backend changes) Backend integration tests passed │
│  - Regression check: Existing test pass rate ≥ baseline  │
│  - summary.skipped + summary.timedOut === 0              │
│      else → verdict = unknown (not pass)                 │
│  - autoFix.testsWeakened === []                          │
│  ⚠️ PR creation blocked on fail **and** on unknown       │
└─────────────────────────────────────────────────────────┘

# Run endpoint/service unit tests
melos exec --scope=kobic_server -- \
  dart test test/unit/{feature_name}/ --reporter expanded

# Run withServerpod integration tests
melos exec --scope=kobic_server -- \
  dart test test/integration/{feature_name}/ --reporter expanded

1. Parse failure message
   ↓
2. Classify failure type
   ↓
3. Determine if fixable
   ↓
4. Generate fix code
   ↓
5. Apply fix
   ↓
6. Re-run test
   ↓
7. Verify success/failure

inv:      auto-fix 는 test setup / finder / import 만 수정한다 — 단정(expect/verify) 변경,
          `skip:`/`@Skip` 삽입, 개별/스위트 타임아웃 상향, 프로덕션 코드 변경은 금지.
          위반 흔적은 autoFix.testsWeakened[] 에 기록되고 그 자체로 Step 6 게이트 fail 이다
prog:     failing = 남은 실패 테스트 수. 매 attempt 강한 감소 (failing_n  <   failing_{n-1})
          no-prog: 개수가 그대로면 남은 예산을 같은 수정에 쓰지 않고 즉시 루프 종료 →
          Rung 2 (3단 stall ladder: ../sequential-workflow.md)
term:     failing === 0            # prog: 와 같은 단위
budget:   inner 3 attempts / 호출당 outer 재진입 0회 (Task 호출 1회 = 이 루프 1회)
exhaust:  남은 실패를 failures[] 에 두고 verdict: ' fail '   반환 — 경고 후 계속 금지,
          `skip:` 삽입으로 failing 을 0 으로 만드는 것 금지
resume:   테스트 재실행 실측으로 failing 을 다시 세어 위치를 판정한다
          (대화 카운터는 /clear 를 못 넘으므로 예산이 아니다)
log:      attempt 당 한 줄  " #2: failing=5→2 touched=3 "   + 종료 시
          {roundsUsed, testsWeakened[], filesTouched[]} 를 결과에 실어 반환

# Test specific Feature only
melos exec --scope=feature_{feature_name} -- flutter test

# Or
melos run test --scope=feature_{feature_name}

# Test with coverage
melos run test:with-html-coverage

# Single file test
melos exec --scope=feature_{feature_name} -- \
  flutter test test/domain/usecase/get_posts_usecase_test.dart

╔════════════════════════════════════════════════════════╗
║  Test Results: feature_community                       ║
╠════════════════════════════════════════════════════════╣
║  Unit Tests (UseCase):                                 ║
║    ✅ GetPostsUseCase: 5 passed                        ║
║    ✅ GetPostUseCase: 3 passed                         ║
║    ✅ CreatePostUseCase: 4 passed                      ║
║                                                        ║
║  BLoC Tests:                                           ║
║    ✅ PostListBloc: 8 passed                           ║
║    ✅ PostDetailBloc: 6 passed                         ║
║    ❌ PostFormBloc: 4 passed, 1 failed                 ║
║                                                        ║
╠════════════════════════════════════════════════════════╣
║  Summary: 30/31 passed (96.8%)                         ║
║  Skipped: 0   Timed-out: 0                             ║
║  Duration: 45.3s  (suite budget 45.3s/10m)             ║
║  Coverage: 85.2% (lines)                               ║
║  Auto-fix: rounds 1/3, weakened 0, files 2             ║
║  Verdict: FAIL  (1 failed)                             ║
╚════════════════════════════════════════════════════════╝

╔════════════════════════════════════════════════════════╗
║  Skipped / Timed-out (verdict = UNKNOWN)               ║
╠════════════════════════════════════════════════════════╣
║  post_form_bloc_test.dart::submits draft after 3 taps  ║
║    reason: individual-timeout-30s                      ║
║  community_detail.feature::deep link opens detail       ║
║    reason: suite-budget-exhausted                      ║
╠════════════════════════════════════════════════════════╣
║  skipped=1  timedOut=1  → Step 6 조건 6 미충족          ║
║  ⚠️ PR 차단. 같은 목록을 PR body `## Test Skips` 에 복사 ║
╚════════════════════════════════════════════════════════╝

╔════════════════════════════════════════════════════════╗
║  Failed Test Details                                   ║
╠════════════════════════════════════════════════════════╣
║  File: post_form_bloc_test.dart                        ║
║  Test: should emit error state when validation fails   ║
║                                                        ║
║  Error:                                                ║
║    Expected: PostFormError(message:  " Title required " )  ║
║    Actual:   PostFormError(message:  " 제목을 입력하세요 " )  ║
║                                                        ║
║  Fixable: ✅ Yes (message mismatch)                    ║
║  Auto-fix: Applied                                     ║
╚════════════════════════════════════════════════════════╝

1. Check analysis errors
2. Re-run code generation
3. If still failing → report failure

budget:   individual 30s per test / suite 10min per invocation (재진입 0회)
exhaust:  suite 10min 소진 → 남은 테스트를 실행하지 않고 즉시 종료하고, 미실행 전부를
          skips[] 에 reason: ' suite-budget-exhausted '   로 적재한 뒤 verdict: ' unknown '   반환.
          부분 결과를 pass 로 승격하지 않는다 (경고 후 계속 금지)
log:       " suite 8m12s/10m · skipped=1 timedOut=2 "   + skips[] 전수( < file > :: < test > , reason)
          를 결과 박스와 PR body 양쪽에 남긴다 (콘솔은 내구 기록이 아니다)