svharness 0.8.0

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-audit/references/search-playbook.md

@@ -0,0 +1,303 @@
+# Search Playbook
+
+Use this playbook to gather evidence quickly, then verify by reading representative files.
+
+**Always scope ripgrep to Kotlin sources** with `-g '*.kt' -g '*.kts'` (or the `Grep` tool's `glob` parameter / `type: kotlin`) — the regexes below are written for Kotlin and produce noise on JVM/Java/JS files. For build-config searches, use `-g '*.gradle*' -g '*.toml'` instead.
+
+## 1. Map The Repo First
+
+Before category scoring, locate:
+
+- Gradle settings and module declarations
+- Android app and feature modules
+- likely Compose source folders
+- shared component or design-system directories
+- theme packages
+- screen packages
+- ViewModels and state holders
+- test and preview directories
+
+Useful targets often include:
+
+- `app/`
+- `feature*/`
+- `core/ui/`
+- `designsystem/`
+- `ui/components/`
+- `ui/screens/`
+- `presentation/`
+
+## 2. Confirm Compose Surface Area
+
+Search for:
+
+- `@Composable`
+- `MaterialTheme`
+- `setContent`
+- `ComposeView`
+- `remember`
+- `mutableStateOf`
+
+If Compose usage is sparse, state that clearly in the report and reduce confidence.
+
+## 3. Performance Checks
+
+### Search For
+
+- `remember\(`
+- `derivedStateOf`
+- `LazyColumn|LazyRow|LazyVerticalGrid|LazyHorizontalGrid|LazyVerticalStaggeredGrid|LazyHorizontalStaggeredGrid`
+- `items\(`
+- `itemsIndexed\(`
+- `rememberLazyListState`
+- `animate`
+- `offset\(`
+- `drawBehind`
+- `sortedWith|sortedBy|filter|map|associate|groupBy`
+- stability annotations and immutable collections: `@Stable`, `@Immutable`, `kotlinx\.collections\.immutable`, `ImmutableList`, `PersistentList`, `persistentListOf`, `compose_compiler_config`
+- skipping opt-outs: `@NonSkippableComposable`, `@DontMemoize`
+- typed state factories: `mutableIntStateOf`, `mutableLongStateOf`, `mutableFloatStateOf`, `mutableDoubleStateOf`
+- composition-marker annotations: `@ReadOnlyComposable`, `@NonRestartableComposable`
+- baseline / profile setup: `baselineProfile`, `ProfileInstaller`, `androidx\.profileinstaller`, `baseline-prof\.txt`
+- deprecated/legacy APIs: `accompanist-pager`, `accompanist-swiperefresh`, `accompanist-flowlayout`, `accompanist-systemuicontroller`, `animateItemPlacement\(`
+- config-derived reads inside `remember {}`: `LocalConfiguration`, `LocalDensity`, `LocalLayoutDirection`
+- `\.indexOf\(|\.lastIndexOf\(|\.indexOfFirst\s*\{` inside lazy item factories
+- `Canvas\s*\(` and `Spacer\s*\(` — check each hit for an explicit `size` / `height` / `aspectRatio` on the modifier; bare `fillMaxSize()` on a drawing surface can enter draw with `Size.Zero`
+- `ReportDrawnWhen\s*\{` — positive signal for startup metrics
+- `enableEdgeToEdge\s*\(` — positive signal; also confirms the project is not reaching for the deprecated `accompanist-systemuicontroller`
+
+### Red Flags To Verify
+
+- expensive list transforms inside composable bodies
+- expensive work passed directly to `items(...)`
+- `Lazy*` items without `key =` where item identity can move or reorder — see the lazy-list-without-key heuristic at the bottom of this section
+- scroll or animation state read high in the tree
+- fast-changing values passed to non-lambda modifiers when a layout/draw-phase alternative exists
+- backwards writes — *writing to state that has already been read in the same composition body* (this is the precise definition; reading after writing is fine)
+- `mutableStateOf<Int>` / `<Long>` / `<Float>` / `<Double>` — the typed factories avoid boxing
+- raw `List`/`Map`/`Set` parameters on widely reused composables when `kotlinx.collections.immutable` is already a dependency
+- `@NonSkippableComposable` / `@DontMemoize` without a justifying comment
+- `remember { … }` whose body reads `LocalConfiguration` / `LocalDensity` / `LocalLayoutDirection` without listing that source as a key — cached value goes stale on rotation/foldable/font-scale changes
+- `indexOf(...)` / `lastIndexOf(...)` / `indexOfFirst { ... }` called inside a `LazyListScope` item factory — O(n²) scrolling cost and crash risk if identity moves; prefer `itemsIndexed`
+- `animateItemPlacement()` usage on Compose 1.7+ — replaced by `Modifier.animateItem()`
+- Accompanist libraries where first-party replacements exist: `accompanist-pager` → `HorizontalPager` / `VerticalPager`; `accompanist-swiperefresh` → `PullToRefreshBox`; `accompanist-flowlayout` → `FlowRow` / `FlowColumn`; `accompanist-systemuicontroller` → `enableEdgeToEdge()`
+
+### Positive Signals
+
+- `remember(keys)` around expensive calculations
+- `derivedStateOf` used for scroll-triggered UI thresholds
+- lambda modifiers such as `Modifier.offset { ... }`, `Modifier.graphicsLayer { ... }`, `Modifier.drawBehind { ... }`
+- draw/layout phase reads instead of full recomposition for rapidly changing values
+- `@Stable` / `@Immutable` on data classes used as composable params
+- `ImmutableList` / `PersistentList` for collection params
+- `compose_compiler_config.conf` to mark third-party types stable
+- baseline-profile modules or profile installer setup when app maturity suggests it matters
+
+### Lazy-List-Without-Key Heuristic
+
+There's no clean single regex for this. Use a two-step approach:
+
+1. Find files that use a lazy layout: `rg -l 'Lazy(Column|Row|VerticalGrid|HorizontalGrid|VerticalStaggeredGrid|HorizontalStaggeredGrid)\b' -g '*.kt'`
+2. Within each file, look for `items(` / `itemsIndexed(` invocations that omit `key =`. Useful multiline pattern: `rg -U --multiline-dotall 'items(?:Indexed)?\([^)]*\)' -g '*.kt'` and read each hit for a `key =` argument.
+
+Manually verify before deducting — `items(count: Int)` overloads and small static lists that never reorder are not bugs.
+
+### Duplicate-Lazy-Key Heuristic
+
+Compose throws `IllegalArgumentException: Key ... was already used` when a `Lazy*` layout sees two items with the same key. Root causes in production code: backend returning duplicate IDs, merging streams (e.g. WebSocket reconnect), or `Pager` + `LazyColumn` combinations where the same item appears in overlapping pages.
+
+There is no clean regex. Walk `items(..., key = ...)` / `itemsIndexed(..., key = ...)` hits and read the surrounding context:
+
+- is the list source a merge / combine / concatenation of multiple flows?
+- does the backend spec guarantee ID uniqueness?
+- is the key computed from `hashCode()` on a non-`data class`?
+
+When uniqueness is not guaranteed, flag as a latent crash and suggest a dedup index or a synthesized key like `"${source}-${id}"`.
+
+### Scaffold Inner-Padding Heuristic
+
+`Scaffold` exposes `innerPadding` to its content lambda. If the content ignores it, elements are drawn behind the `TopAppBar` or `BottomAppBar`. Search for `Scaffold(` and read each hit — the content lambda parameter should be applied to the root-most child via `Modifier.padding(innerPadding)` (or `.consumeWindowInsets(innerPadding)`). If a `Scaffold { }` discards the padding parameter with `_ ->` or omits it entirely while nesting non-trivial content, flag it.
+
+### Strong Skipping Mode Check
+
+Confirm the project's compiler version:
+
+- `rg -n 'kotlin\s*=\s*"' -g '*.toml'` and `rg -n 'org\.jetbrains\.kotlin' -g '*.gradle*'` to find the Kotlin version
+- Strong Skipping is on by default at Kotlin **2.0.20+**; below that, stability inference matters more and unstable params more aggressively block skipping
+
+## 4. State Management Checks
+
+### Search For
+
+- `mutableStateOf`
+- `mutableIntStateOf|mutableLongStateOf|mutableFloatStateOf|mutableDoubleStateOf`
+- `mutableStateListOf|mutableStateMapOf`
+- `rememberSaveable`
+- `mapSaver|listSaver|@Parcelize|Saver`
+- `collectAsStateWithLifecycle`
+- `collectAsState`
+- `observeAsState`
+- `subscribeAsState`
+- `MutableState<`
+- `State<`
+- `mutableListOf|mutableMapOf|mutableSetOf|ArrayList`
+- `CompositionLocal`
+- `compositionLocalOf|staticCompositionLocalOf`
+- `ViewModel`
+- `viewModel\(` — log invocation depth (screen entry vs. deep tree)
+- `mutableStateOf` / `mutableIntStateOf` etc. declared as members of a class extending `ViewModel` (not inside a composable)
+- `Channel<` / `receiveAsFlow\(\)` / `consumeAsFlow\(\)` exposed from a `ViewModel` for UI events
+- `\.stateIn\s*\(` — positive signal; check for `WhileSubscribed(5_000)` or similar timeout
+- `rememberSaveable` invoked inside a `Lazy(Column|Row|VerticalGrid|HorizontalGrid|VerticalStaggeredGrid|HorizontalStaggeredGrid)` item factory
+
+### Red Flags To Verify
+
+- duplicated state across parent/child or sibling composables
+- shared state held too low in the tree
+- reusable components with unnecessary internal state
+- Android UI code using `collectAsState()` where `collectAsStateWithLifecycle()` is a better fit (skip this rule on Compose Multiplatform code paths)
+- non-observable mutable collections used as state (`mutableListOf` mutated in place)
+- `mutableListOf` / `mutableMapOf` wrapped in a `MutableState` instead of `mutableStateListOf` / `mutableStateMapOf` — element changes won't trigger recomposition
+- `mutableStateOf<Int|Long|Float|Double>` instead of the typed factory (autoboxing)
+- `MutableState<T>` params in reusable components
+- `State<T>` params where a value or lambda would be more flexible
+- `remember { ... }` with no `key` for a value that depends on inputs (stale cache)
+- `rememberSaveable { mutableStateOf(SomeNonBundleable(...)) }` without a `Saver` — restoration silently fails
+
+### Positive Signals
+
+- clear stateful wrapper + stateless reusable composable split
+- state hoisted to the lowest common reader / highest writer
+- related state hoisted together
+- lifecycle-aware collection of flows in Android UI
+- plain state-holder classes for larger screens or app shells
+
+## 5. Side Effects Checks
+
+### Search For
+
+- `LaunchedEffect`
+- `DisposableEffect`
+- `SideEffect`
+- `rememberUpdatedState`
+- `produceState`
+- `snapshotFlow`
+- `rememberCoroutineScope`
+- `\.launch\s*[\({]` — catches both `scope.launch {` and `scope.launch(Dispatchers.IO) {`
+- `Thread\(`
+- `GlobalScope`
+- `LifecycleEventObserver`
+- `BackHandler`
+- `NavHost`, `composable\(` (in nav graphs), `navController\.navigate`
+- string-based nav routes: `composable\(\s*"` and `navigate\(\s*"` (suggest type-safe `@Serializable` routes on Navigation Compose 2.8+)
+
+### Red Flags To Verify
+
+- work started directly in composition body
+- navigation, snackbar, analytics, or repository calls triggered during composition instead of from an effect or event path
+- `navController.navigate(...)` invoked in composition body — must come from an event handler or `LaunchedEffect`
+- `LaunchedEffect(Unit)` / `LaunchedEffect(true)` is **not** suspicious on its own (the "run once" pattern is idiomatic). Only flag it when the body captures parameter or state values that may change without `rememberUpdatedState`
+- `DisposableEffect` with empty or suspicious cleanup
+- listener/observer registration without `onDispose`
+- effect keys too broad or too narrow
+- `rememberCoroutineScope()` used to launch keyed/long-lived work that belongs in a `LaunchedEffect`
+- `snapshotFlow { ... }` invoked outside an effect, or used to compute a value that `derivedStateOf` would handle more cheaply
+- `derivedStateOf { a + b }`-style misuse — when input frequency ≈ output frequency it is pure overhead (the official antipattern)
+
+### Positive Signals
+
+- `rememberUpdatedState` used for long-lived effects that should keep latest callbacks
+- `DisposableEffect` paired with clear cleanup
+- `SideEffect` used only to publish state to non-Compose code after successful composition
+- `produceState` or equivalent used for converting external async sources into Compose state
+- `snapshotFlow { ... }` collected from inside a `LaunchedEffect` for Compose-state → Flow conversions
+- `rememberCoroutineScope()` used only for event-driven work (button taps, gesture handlers)
+
+## 6. Composable API Quality Checks
+
+Focus on shared components and internal UI kit code, not every screen.
+
+### Search For
+
+- shared component directories such as `components`, `commonui`, `designsystem`, `ui/components`
+- function signatures around `@Composable`
+- `modifier: Modifier =`
+- `Modifier = Modifier\.` — non-no-op modifier defaults
+- `MutableState<`
+- `State<`
+- `CompositionLocal`
+- `compositionLocalOf|staticCompositionLocalOf` — definitions
+- `CompositionLocalProvider` — provision sites
+- ViewModels in CompositionLocal: `compositionLocalOf<.*ViewModel`, `staticCompositionLocalOf<.*ViewModel`
+- `viewModel\(` — invocation sites; flag when called below the screen entry composable
+- slot APIs and receiver scopes: `RowScope\.`, `ColumnScope\.`, `BoxScope\.`, `content:\s*@Composable`
+- modifier authoring: `Modifier\.composed\s*\{` (discouraged), `Modifier\.Node`, `ModifierNodeElement`
+- movable content: `movableContentOf`, `movableContentWithReceiverOf`
+- variant smells: `\bstyle:\s*\w+Style\b` — single-component-with-style-enum
+- `Basic` prefix: `fun Basic[A-Z]\w+\s*\(`
+- lazy list `contentType`: `contentType\s*=` inside `items(` / `itemsIndexed(` calls — its presence on heterogeneous lists is a positive signal; its absence on heterogeneous lists is a deduction
+
+### Red Flags To Verify
+
+- shared components missing a `modifier`
+- `modifier` not being the first optional parameter
+- `modifier` default not equal to `Modifier` (e.g. `modifier: Modifier = Modifier.padding(8.dp)` — caller's modifier silently loses the padding)
+- multiple modifier parameters on one component
+- modifier applied to a child instead of the root-most emitted UI, and not as the *first* link in the chain
+- nullable params used to mean "choose internal default" (expose a `ComponentDefaults` object instead)
+- component-specific configuration hidden behind implicit locals
+- huge multipurpose components that should be layered or split
+- behavior added as parameters that should be modifiers (`onClick`, `clipToCircle`)
+- a single component with a `style: ButtonStyle` enum-like parameter instead of distinct `ContainedButton` / `OutlinedButton` / `TextButton` components
+- custom modifiers built with `Modifier.composed { ... }` (discouraged in favor of `Modifier.Node`)
+- `MutableState<T>` params — replace with `value: T` (immediate read) or `value: () -> T` (deferred) plus `onValueChange: (T) -> Unit`
+- `@Composable` UI-emitting functions named in lowerCamelCase or returning a non-Unit value (style guide violation)
+
+### Positive Signals
+
+- required params first, then `modifier`, then optional params, then trailing content lambda
+- explicit config exposed as parameters with meaningful defaults via a `ComponentDefaults` object
+- focused component responsibilities
+- internal wrappers built on simpler lower-level components
+- slot lambdas (`content: @Composable RowScope.() -> Unit`) for flexible composition
+- `Basic*` variants alongside opinionated public versions
+- distinct components per visual variant (no `style` enum)
+- `movableContentOf` used to preserve slot lifecycle across structural moves
+- custom modifiers authored with `Modifier.Node` / `ModifierNodeElement`
+
+### Modifier-Order Smell
+
+No clean regex. When reading shared components, watch for `Modifier.padding(...).clickable {}` vs `Modifier.clickable {}.padding(...)` — they produce different ripple bounds and hit areas. Flag when the choice looks accidental in a reusable component (the wrong order is almost always a bug there; in a one-off screen it may be intentional).
+
+## 7. Read Representative Files
+
+For each category, read enough code to cover:
+
+- at least one screen
+- at least one shared component area
+- at least one state-owning area such as a ViewModel or state-holder
+- any suspicious files surfaced by search
+
+Do not rely on one "bad" file to characterize the entire repo.
+
+## 8. Merge Repeated Findings
+
+Prefer:
+
+- "7 shared components miss `modifier`"
+
+over:
+
+- seven separate bullets saying the same thing
+
+Still keep 2-4 concrete file examples to justify the systemic finding.
+
+## 9. Out-Of-Scope Cases
+
+Stop or narrow scope if:
+
+- the repo is not Android Jetpack Compose
+- Compose is only present in demo or sample code
+- the user asked to audit only one module or feature
+
+In those cases, explain the limitation and score only the relevant surface area.

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-audit/scripts/compose-reports.init.gradle

@@ -0,0 +1,58 @@
+// Gradle init script injected by the Jetpack Compose audit skill.
+//
+// Purpose: enable Compose Compiler reports + metrics for every module that
+// applies the Compose Compiler plugin, without modifying the user's build
+// files. Each module's output lands in <module>/build/compose_audit/.
+//
+// Usage (from the skill, not the user):
+//   ./gradlew <task> --init-script <path-to-this-file> --no-daemon
+//
+// Two code paths:
+//   A. Modern Compose Compiler Gradle plugin (Kotlin 2.0+) — configures the
+//      `composeCompiler { }` extension directly.
+//   B. Legacy compiler-plugin argument fallback — injects reportsDestination
+//      and metricsDestination via Kotlin compile task free args. Works on
+//      older toolchains that still apply the compiler plugin manually.
+//
+// The script is defensive: failures in one module must not fail the build.
+
+allprojects { project ->
+    project.afterEvaluate {
+        def reportDir = new File(project.buildDir, "compose_audit")
+
+        // Path A: modern Compose Compiler Gradle plugin.
+        def composeExt = project.extensions.findByName("composeCompiler")
+        if (composeExt != null) {
+            try {
+                reportDir.mkdirs()
+                composeExt.reportsDestination.set(reportDir)
+                composeExt.metricsDestination.set(reportDir)
+                project.logger.lifecycle("compose-audit: reports -> ${reportDir}")
+                return
+            } catch (Throwable e) {
+                project.logger.warn("compose-audit: composeCompiler extension found but could not be configured: ${e.message}")
+            }
+        }
+
+        // Path B: legacy compiler-args fallback for projects that apply the
+        // Compose compiler plugin the old way (pre-Kotlin-2.0).
+        def anyConfigured = false
+        project.tasks.matching { it.name.startsWith("compile") && it.name.contains("Kotlin") }.configureEach { task ->
+            try {
+                def opts = task.hasProperty("compilerOptions") ? task.compilerOptions : null
+                if (opts == null) return
+                opts.freeCompilerArgs.addAll([
+                    "-P", "plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=${reportDir.absolutePath}",
+                    "-P", "plugin:androidx.compose.compiler.plugins.kotlin:metricsDestination=${reportDir.absolutePath}",
+                ])
+                reportDir.mkdirs()
+                anyConfigured = true
+            } catch (Throwable ignored) {
+                // Silent — task may not be a Kotlin compile task.
+            }
+        }
+        if (anyConfigured) {
+            project.logger.lifecycle("compose-audit: reports -> ${reportDir} (legacy compiler-args path)")
+        }
+    }
+}

package/templates/android-compose/skeleton/agent-env/skills/harness-compose-state/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: harness-compose-state
+description: Jetpack Compose 状态管理与副作用的深度指引。覆盖 StateFlow/SharedFlow 收集、LaunchedEffect/DisposableEffect/SideEffect 选用、rememberUpdatedState 防过期、produceState 桥接非 Compose API。刚性约束由 rules 加载，本技能聚焦正确选用和常见陷阱。
+---
+
+# Compose 状态与副作用 — 实现指引
+
+## 概述
+
+状态管理是 Compose 开发中最容易出 bug 的领域。本技能聚焦如何正确选用状态 API 和副作用 API，以及常见陷阱。
+
+> **刚性约束已由 rules 加载，本技能不再重复。** 详见：
+> - `harness-compose-mandatory` — 无状态 Composable、副作用约束
+> - `harness-coroutines-scope` — collectAsStateWithLifecycle、SharedFlow replay 约束
+
+---
+
+## 副作用 API 选用指南
+
+| API | 场景 | 特点 |
+|-----|------|------|
+| `LaunchedEffect(key)` | 需要协程的副作用（网络、数据库） | key 变化时取消旧协程、启动新协程 |
+| `DisposableEffect(key)` | 需要清理的绑定（注册/注销监听器） | 提供 `onDispose` 清理块 |
+| `SideEffect {}` | 每次成功重组后执行的非挂起操作 | 不常用，通常 `LaunchedEffect(Unit)` 更好 |
+| `rememberUpdatedState` | 防止 LaunchedEffect 内 lambda 过期 | 不重启 Effect，只更新引用 |
+| `produceState` | 将非 Compose API 桥接为 State | 内部启动协程，emit 到 State |
+| `derivedStateOf` | 派生计算型状态 | 只在结果变化时触发重组 |
+
+---
+
+## LaunchedEffect — 协程副作用
+
+```kotlin
+// 根据 key 重启
+@Composable
+fun UserProfile(userId: String, viewModel: UserViewModel) {
+    LaunchedEffect(userId) {
+        viewModel.loadUser(userId)  // userId 变化时自动取消旧的、启动新的
+    }
+}
+
+// "运行一次"模式（惯用写法，不需要 rememberUpdatedState 包裹）
+@Composable
+fun DataLoader(viewModel: MyViewModel) {
+    LaunchedEffect(Unit) {
+        viewModel.loadInitialData()
+    }
+}
+```
+
+## DisposableEffect — 需要清理的绑定
+
+```kotlin
+@Composable
+fun LifecycleAwareComponent(lifecycle: Lifecycle) {
+    DisposableEffect(lifecycle) {
+        val observer = LifecycleEventObserver { _, event -> /* 处理 */ }
+        lifecycle.addObserver(observer)
+        onDispose { lifecycle.removeObserver(observer) }
+    }
+}
+```
+
+## rememberUpdatedState — 防过期
+
+```kotlin
+// ❌ 危险：LaunchedEffect 内捕获的 value 可能过期
+@Composable
+fun SearchScreen(onTimeout: () -> Unit) {
+    LaunchedEffect(Unit) {
+        delay(5000)
+        onTimeout()  // 5 秒后调用的是启动时的旧 lambda
+    }
+}
+
+// ✅ 安全：rememberUpdatedState 保持最新引用
+@Composable
+fun SearchScreen(onTimeout: () -> Unit) {
+    val currentOnTimeout by rememberUpdatedState(onTimeout)
+    LaunchedEffect(Unit) {
+        delay(5000)
+        currentOnTimeout()  // 始终调用最新的 lambda
+    }
+}
+```
+
+## produceState — 桥接非 Compose API
+
+```kotlin
+@Composable
+fun loadUser(userId: String): State<Result<User>> {
+    return produceState(initialValue = Result.loading(), key1 = userId) {
+        val result = userRepository.getUser(userId)
+        value = result
+    }
+}
+```
+
+---
+
+## StateFlow 与 SharedFlow 在 Compose 中的使用
+
+### 持久状态 → StateFlow
+
+```kotlin
+// ViewModel 中
+private val _uiState = MutableStateFlow(UiState())
+val uiState: StateFlow<UiState> = _uiState.asStateFlow()
+
+// Compose 中收集
+val state by viewModel.uiState.collectAsStateWithLifecycle()
+```
+
+### 一次性事件 → SharedFlow
+
+```kotlin
+// ViewModel 中
+private val _effects = MutableSharedFlow<Effect>(replay = 0)  // replay=0 是强制约束
+val effects: SharedFlow<Effect> = _effects.asSharedFlow()
+
+// Compose 中收集
+LaunchedEffect(Unit) {
+    viewModel.effects.collect { effect ->
+        when (effect) {
+            is Effect.ShowToast -> { /* 显示 Toast */ }
+            is Effect.Navigate -> { /* 导航 */ }
+        }
+    }
+}
+```
+
+### 从 Flow 派生 StateFlow
+
+```kotlin
+val searchResults: StateFlow<List<Item>> = _searchQuery
+    .debounce(300)
+    .filter { it.length >= 2 }
+    .flatMapLatest { query -> searchRepository.search(query) }
+    .stateIn(
+        scope = viewModelScope,
+        started = SharingStarted.WhileSubscribed(5000),
+        initialValue = emptyList()
+    )
+```
+
+---
+
+## 常见陷阱
+
+### 1. collectAsState vs collectAsStateWithLifecycle
+
+```kotlin
+// ❌ 不感知生命周期，后台仍在收集
+val state by viewModel.uiState.collectAsState()
+
+// ✅ 感知生命周期，后台暂停收集
+val state by viewModel.uiState.collectAsStateWithLifecycle()
+```
+
+### 2. SharedFlow replay > 0
+
+```kotlin
+// ❌ 新订阅者会收到旧事件
+MutableSharedFlow<Effect>(replay = 1)
+
+// ✅ 一次性消费
+MutableSharedFlow<Effect>(replay = 0)
+```
+
+### 3. 在 Reducer 中执行副作用
+
+```kotlin
+// ❌ Reducer 内触发导航
+is Event.Saved -> {
+    navigator.navigate(Home)  // 副作用！
+    state.copy(isSaved = true)
+}
+
+// ✅ 副作用放 EffectHandler
+override val effectHandler = EffectHandler { event, emit ->
+    when (event) {
+        is Event.Saved -> emit(Effect.NavigateHome)
+        else -> {}
+    }
+}
+```
+
+---
+
+## 必须遵守的约束规则
+
+> rules 引用路径：`../rules/<rule-name>.mdc`
+
+- harness-compose-mandatory
+- harness-coroutines-scope
+- harness-mvi-layering