/flame-harness-contract

name: flame-harness-contract
description: Phase 4 — propose verifiable completion criteria and mandatory hard gates; reach AGREED (1-pass default, multi-round negotiation in --strict).
argument-hint: ""
allowed-tools: [Agent, Read, Write, Edit, Bash]

flame-harness-contract

Phase 4 of the flutter-flame-harness pipeline. Reads the PRD and design doc, proposes verifiable completion criteria (Mandatory Hard Gates + Functional Criteria), and marks the contract AGREED before handing off to the generator.

All file schemas (`config.md`, `state.md`, `contract.md`) are defined in `docs/harness-protocol.md` — refer to that document as the single source of truth. Do not redefine schemas here.

---

Input

1. Read `docs/harness/config.md`

Extract:

| Key | Use | |---|---| | `app_name` | Contract title header | | `app_slug` | Used to identify the game | | `strict_mode` | If `true`, run `--strict` negotiation; if `false` (or absent), run default 1-pass |

2. Read the latest PRD

Find the most recent file matching `docs/harness/plans/*-prd.md` (sort by filename descending, take the first). Abort with a clear message if none exists.

3. Read the design doc

Find the most recent file matching `docs/harness/plans/*-design.md` (sort by filename descending, take the first). Abort if none exists.

---

Mandatory Hard Gates

These 8 criteria are non-negotiable and must appear verbatim in every `contract.md`. A FAIL on any one results in an immediate FAIL verdict, regardless of other passing criteria.

> **Source:** `docs/harness-protocol.md` §3 — Mandatory Hard Gates block. Always cite; never > restate differently.

1. `flutter analyze` returns zero issues. 2. `flutter test` — all tests pass. 3. No TODO, stub, or placeholder in game logic (grep-checkable). 4. All tuning constants centralized in `game_config.dart` — no magic numbers in gameplay code. 5. Game content (enemies / levels / waves) is defined as data, not hardcoded. 6. Localization complete for all configured locales — `default_language`, plus English when `default_language` ≠ `en` — no missing l10n keys. 7. Core loop works end to end: start → play → win/lose → restart. 8. Runs on a simulator/emulator with zero crashes and zero console errors.

Copy these 8 lines verbatim into the `## Mandatory Hard Gates` section of `contract.md`. Do not paraphrase, reorder, or omit any gate.

Platform-Robustness Gates

In addition to the 8 core gates above, every contract includes a `## Platform-Robustness Gates` section requiring the patterns in `docs/game-gotchas.md` (cite it). These are mandatory:

• **R1 Audio safe**: all audio calls in try/catch (missing asset never crashes); frequent SFX use an

`AudioPool` (not per-call `FlameAudio.play()`); BGM stops on game-over, app-background, and teardown.

• **R2 Haptics safe** (if the game uses haptics): a `Haptics` helper with platform guard + throttle +

`enabled` toggle + try/catch; gameplay never calls `HapticFeedback.*` raw.

• **R3 Lifecycle**: app host implements `WidgetsBindingObserver`; on background → `pauseEngine()` +

BGM pause; resume reverses; teardown cleans up audio/timers.

• **R4 Performance**: no per-frame `world.children.whereType<...>()` in a hot path (cache once per

frame); `Paint`/shaders not recreated per frame.

• **R5 App branding**: a custom icon + splash are generated (not the default Flutter art), the icon

is opaque (no alpha), and the localized app display name (`CFBundleDisplayName`/`android:label`) is set to `app_name` — not "Runner"/the slug.

• **R6 Native config**: orientation locked **natively** to `config.orientation` (the unused

orientation removed — no launch rotate); iPhone-only (`TARGETED_DEVICE_FAMILY = 1`, no iPad); `ITSAppUsesNonExemptEncryption = false`; root back-button = SnackBar double-press-to-exit; bundle id **byte-identical** across iOS (`PRODUCT_BUNDLE_IDENTIFIER`) and Android (`applicationId`) == `config.bundle_id` (lowercase, no `_`/`-`).

• **R7 Assets & CI**: the game ships with audio (synthesized or sourced) + visuals (code-drawn or

cleaned sprites) and **no missing-asset references** (every `pubspec.yaml` asset exists); a `.github/workflows` CI (analyze + test) is present.

• **R8 Store graphics**: Android Play listing has the required **hi-res icon (512×512)** and

**feature graphic (1024×500)** placed for `supply` (`metadata/android/<locale>/images/icon.png` + `featureGraphic.png`); iOS has localized screenshots.

• **R9 Durable save**: persistence survives reinstall **and** device transfer (not `shared_preferences`

alone) — a `SaveRepository` mirrors the save blob to iOS Keychain (`flutter_secure_storage`, `first_unlock`) + Android Block Store (`play_services_block_store`) + a `shared_preferences` cache, reading durable-first and writing all tiers in try/catch; `PreferencesService` routes through it.

• **R10 Accessibility & safety baseline**: no effect flashes faster than 3×/second (photosensitive

safety); OS Reduce Motion (`MediaQuery.disableAnimations`) is read and damps screen-shake/particles/ flashing; menu/overlay buttons are ≥48×48 dp with `Semantics` labels (icon-only buttons especially); in-game HUD keeps `withNoTextScaling`. (Full in-game screen-reader support is out of scope.)

• **R11 Test depth**: beyond `flutter test` merely passing, the game ships **≥3 system unit tests**

(score/spawn/difficulty/economy — real logic), **≥1 widget test** (a menu/overlay renders + a button taps), and **≥1 integration test** (core loop: boot → play → game-over). Mirrors the shipped games; prevents a green `flutter test` that actually covers nothing.

---

Functional Criteria

Per-game acceptance criteria derived from the PRD. Each criterion must be verifiable by one of:

• **Command** — a shell command whose exit code or output proves the criterion (e.g.,

`grep -r "TODO" lib/` returns no matches).

• **Screenshot** — a labelled screenshot that visually confirms the criterion.
• **Code path** —