create-cmp-cli 0.11.0 → 0.13.0

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/SystemState.kt

@@ -0,0 +1,113 @@
+package __PACKAGE__.testing
+
+import android.content.Context
+import android.media.AudioManager
+import androidx.test.platform.app.InstrumentationRegistry
+
+/**
+ * Snapshot/restore of device audio state (ringer mode, Do Not Disturb) so audio-routing
+ * behavior can be asserted — "does the alert still sound when the phone is on silent?"
+ * is THE question that shipped broken repeatedly, because ringer mode only exists on a
+ * device and every JVM tier is deaf to it.
+ *
+ * Being honest about what instrumentation can and cannot control:
+ *
+ *  CAN (this file):
+ *   - Read and set the ringer mode. Setting SILENT/VIBRATE via AudioManager flips the
+ *     device through DND on modern Android, so both knobs are driven through the shell
+ *     (`cmd notification set_dnd`, `settings global zen_mode`) with the instrumentation's
+ *     shell uid ([Shell.exec]) — no notification-policy grant dance, works on a stock emulator.
+ *   - Read/set DND (zen mode) as a global: off / priority-only / total-silence / alarms-only.
+ *   - Observe playback routing: which stream/usage an active player is on
+ *     (AudioManager.activePlaybackConfigurations — see PlatformBehaviorSeamTest for the
+ *     assertion shape: a sound with USAGE_ALARM is what survives a silenced ringer).
+ *
+ *  CANNOT (manual tier — document the claim in your spec, verify it by hand per release):
+ *   - OEM sound policy: whether a channel's sound reaches the alarm stream on a Samsung
+ *     is Samsung's decision; assert your app plays with USAGE_ALARM, not that a given
+ *     handset makes air move.
+ *   - Physical volume keys / hardware mute switches, Bluetooth routing, and whether the
+ *     speaker is audible — there is no API for "a human heard it".
+ *   - Lock-screen rendering: whether a takeover actually draws over a locked, OEM-skinned
+ *     screen stays manual. Doze delivery, by contrast, stopped being a manual rehearsal
+ *     when [DozeControl] landed — force the idle state and watch the alarm arrive.
+ *
+ * Plain helpers, not a TestRule: state here is two scalars, and an explicit
+ * snapshot-in-@Before / restore-in-@After (or [withRingerMode]) keeps the mechanism
+ * visible in the test. Wrap it in a rule when a suite grows enough tests to justify one.
+ */
+object SystemState {
+
+    /** The restorable slice of device audio state. */
+    data class Snapshot(val ringerMode: Int, val zenMode: Int)
+
+    /** DND (zen) global values — `settings get global zen_mode`. */
+    const val ZEN_OFF = 0
+    const val ZEN_PRIORITY_ONLY = 1
+    const val ZEN_TOTAL_SILENCE = 2
+    const val ZEN_ALARMS_ONLY = 3
+
+    private val audio: AudioManager
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+            .getSystemService(Context.AUDIO_SERVICE) as AudioManager
+
+    /** Capture the current ringer + DND state. Take it BEFORE the test mutates anything. */
+    fun snapshot(): Snapshot = Snapshot(ringerMode = audio.ringerMode, zenMode = readZen())
+
+    /** Put the device back exactly as [snapshot] found it — call from @After, always. */
+    fun restore(s: Snapshot) {
+        setZen(s.zenMode)
+        setRingerMode(s.ringerMode)
+    }
+
+    /**
+     * Set the ringer mode (AudioManager.RINGER_MODE_NORMAL / _VIBRATE / _SILENT).
+     * SILENT is driven as alarms-only DND + the mode itself — on API 23+ that is what the
+     * volume-key gesture actually does, and it is the honest reproduction of "the user
+     * silenced the phone" (alarms are still allowed to sound; a total-silence test should
+     * say so explicitly via [setZen] with [ZEN_TOTAL_SILENCE]).
+     */
+    fun setRingerMode(mode: Int) {
+        when (mode) {
+            AudioManager.RINGER_MODE_SILENT -> setZen(ZEN_ALARMS_ONLY)
+            else -> setZen(ZEN_OFF)
+        }
+        // Best-effort after the zen change; on emulators this lands reliably. Poll-check
+        // rather than trust: callers get the real mode back and can assume-skip if the
+        // device refused (an OEM with a hardware mute state may).
+        audio.ringerMode = mode
+    }
+
+    /** Set DND directly (one of the ZEN_* constants). Shell-driven; applies globally. */
+    fun setZen(zen: Int) {
+        val arg = when (zen) {
+            ZEN_PRIORITY_ONLY -> "priority"
+            ZEN_TOTAL_SILENCE -> "none"
+            ZEN_ALARMS_ONLY -> "alarms"
+            else -> "off"
+        }
+        Shell.exec("cmd notification set_dnd $arg")
+    }
+
+    /** The device's current DND global (ZEN_* value; unreadable/absent reads as off). */
+    fun readZen(): Int =
+        Shell.exec("settings get global zen_mode").trim().toIntOrNull() ?: ZEN_OFF
+
+    /**
+     * Run [block] with the ringer in [mode], restoring the full snapshot afterwards even
+     * when the block throws — the composable form for a single-assertion test:
+     *
+     *   SystemState.withRingerMode(AudioManager.RINGER_MODE_SILENT) {
+     *     // trigger the alert path, then assert a player is active with USAGE_ALARM
+     *   }
+     */
+    fun <T> withRingerMode(mode: Int, block: () -> T): T {
+        val before = snapshot()
+        return try {
+            setRingerMode(mode)
+            block()
+        } finally {
+            restore(before)
+        }
+    }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/TimeWarp.kt

@@ -0,0 +1,114 @@
+package __PACKAGE__.testing
+
+import android.os.SystemClock
+
+/**
+ * Device-clock manipulation for the on-device tier — the primitive that turns "the alarm
+ * ladder is unit-tested to the minute" into "we watched the alarm actually arrive".
+ *
+ * Why this exists: scheduled delivery is the one claim the other helpers still could not
+ * close. [AlarmAsserts] proves REGISTRATION (the OS holds the alarm), unit tests prove the
+ * ladder's arithmetic, and yet "the notification arrives at 08:00" shipped untested every
+ * time — nobody waits two days inside a test run. Warping the device clock past the
+ * trigger time makes delivery observable in seconds: schedule for T, warp to T+ε, and the
+ * OS either fires the alarm or it doesn't. The same mechanism makes DST transitions and
+ * date rollovers ([withTimeZone]) a test input instead of a twice-a-year production
+ * surprise.
+ *
+ * EMULATOR-ONLY, NON-NEGOTIABLE — every entry point runs [assumeOnEmulator] first:
+ * warping a real phone's clock corrupts the owner's world, not just the test's — alarms
+ * re-fire or vanish, TLS certificates fall outside their validity window, auth tokens
+ * expire or refuse to, and messaging apps reorder history. A QA emulator is disposable
+ * state; a person's device never is. On a non-emulator the guard SKIPs (assumption
+ * violation), never fails — the suite stays honest about where it can run.
+ *
+ * Constraints the code can't show:
+ *  - No root involved. `adb root` is refused on production (user-build) images, including
+ *    the stock Play-image AVDs — but `cmd alarm set-time` / `set-timezone` work from the
+ *    SHELL uid, which is exactly what [Shell.exec]'s UiAutomation channel provides.
+ *    Time-warp proofs therefore run on any stock emulator, no special image.
+ *  - Network time sync fights the warp: with `auto_time` on, the device re-corrects the
+ *    clock underneath the test. Every warp is bracketed — sync off, warp, run, restore,
+ *    sync back on — and the restore runs in `finally`, so a crashed block still leaves
+ *    the device usable for the next test.
+ *  - The restore is not "set the clock back to what it was": real time keeps passing
+ *    while the block runs, and restoring the ORIGINAL instant would leave the clock
+ *    slow by the block's duration (compounding across a suite). The restore target is
+ *    `original + elapsed`, with elapsed measured on [SystemClock.elapsedRealtime] —
+ *    the monotonic clock, immune to the warp itself.
+ *  - Inside a warped block, bound your waits on monotonic time (`CountDownLatch.await`,
+ *    [SystemClock.elapsedRealtime]), never on `System.currentTimeMillis()` — wall-clock
+ *    deadlines computed before the warp are nonsense after it.
+ */
+object TimeWarp {
+
+    /**
+     * SKIPs the test unless it is running on an emulator (`ro.kernel.qemu == 1`).
+     * Called by every warp entry point; call it yourself at the top of a warp test so
+     * the skip names the test, not a helper frame. See the header for why a real
+     * device is refused: a warped personal phone breaks the owner's alarms, tokens,
+     * and messaging — QA emulators only.
+     */
+    fun assumeOnEmulator() {
+        Shell.assumeOnEmulator(
+            "TimeWarp runs only on emulators (ro.kernel.qemu != 1 here). Warping a real " +
+                "device's clock corrupts its owner's alarms, TLS validity, and auth " +
+                "tokens — run this suite on a stock QA AVD instead.",
+        )
+    }
+
+    /**
+     * Run [block] with the device wall clock set to [targetEpochMillis], restoring
+     * everything afterwards even when the block throws:
+     *
+     *   1. `auto_time` off — otherwise network time sync re-corrects mid-block;
+     *   2. `cmd alarm set-time target` — the warp (shell uid, root-free);
+     *   3. the block — schedule/await/assert;
+     *   4. finally: `set-time (original + elapsed)` then `auto_time` back on.
+     *
+     * The restore adds the block's real duration (monotonic-measured) to the original
+     * instant so the device clock never falls behind true time — see the header.
+     */
+    fun <T> withWarpedClock(targetEpochMillis: Long, block: () -> T): T {
+        assumeOnEmulator()
+        val autoTimeBefore = readGlobal("auto_time")
+        val originalEpochMillis = System.currentTimeMillis()
+        val startElapsed = SystemClock.elapsedRealtime()
+        Shell.exec("settings put global auto_time 0")
+        try {
+            Shell.exec("cmd alarm set-time $targetEpochMillis")
+            return block()
+        } finally {
+            val elapsed = SystemClock.elapsedRealtime() - startElapsed
+            Shell.exec("cmd alarm set-time ${originalEpochMillis + elapsed}")
+            Shell.exec("settings put global auto_time ${autoTimeBefore ?: "1"}")
+        }
+    }
+
+    /**
+     * Run [block] with the device in time zone [olsonId] (e.g. `"Pacific/Chatham"`,
+     * `"America/New_York"`), restoring the original zone and `auto_time_zone` afterwards
+     * even when the block throws. This is the DST/date-rollover assertion primitive:
+     * combine with [withWarpedClock] to place the device just before a transition and
+     * watch what a "tomorrow at 08:00" schedule actually does. No elapsed-time math here
+     * — a zone, unlike a clock, does not drift while the block runs.
+     */
+    fun <T> withTimeZone(olsonId: String, block: () -> T): T {
+        assumeOnEmulator()
+        val autoZoneBefore = readGlobal("auto_time_zone")
+        val originalZone = Shell.exec("getprop persist.sys.timezone").trim()
+        Shell.exec("settings put global auto_time_zone 0")
+        try {
+            Shell.exec("cmd alarm set-timezone $olsonId")
+            return block()
+        } finally {
+            if (originalZone.isNotEmpty()) {
+                Shell.exec("cmd alarm set-timezone $originalZone")
+            }
+            Shell.exec("settings put global auto_time_zone ${autoZoneBefore ?: "1"}")
+        }
+    }
+
+    /** A global setting's current value, or null when unset — see [Shell.readSetting]. */
+    private fun readGlobal(key: String): String? = Shell.readSetting("global", key)
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/di/AppModule.kt

@@ -5,7 +5,7 @@ import __PACKAGE__.domain.repository.ItemRepository
 import __PACKAGE__.domain.usecase.GetItemsUseCase
 import __PACKAGE__.presentation.home.HomeViewModel
 // cmp:anchor di-imports
-import org.koin.core.module.dsl.viewModelOf
+import org.koin.core.module.dsl.viewModel
 import org.koin.dsl.module
 
 val repositoryModule = module {
@@ -19,7 +19,10 @@ val useCaseModule = module {
 }
 
 val viewModelModule = module {
-    viewModelOf(::HomeViewModel)
+    // Explicit factories only — never reflection-based viewModelOf (ARCH-14): it silently
+    // ignores constructor default parameter values, turning a compile-time wiring error
+    // into a runtime resolution crash. One get() per constructor dependency.
+    viewModel { HomeViewModel(get()) }
     // cmp:anchor di-viewmodels
 }
 

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppBottomBar.kt

@@ -118,7 +118,7 @@ internal fun NavItem(
             .clip(RoundedCornerShape(8.dp))
             .clickable(onClick = onClick)
             // a11y: guarantee the 48dp minimum touch target regardless of label width
-            // (the inspector's audit_a11y flags anything smaller).
+            // (the verify lane's a11y step flags anything smaller).
             .defaultMinSize(minWidth = 48.dp, minHeight = 48.dp)
             // Durable selection handle (tests/E2E select by testTag, never display text).
             .semantics { testTag = navItemTag(label) }

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppButton.kt

@@ -11,7 +11,7 @@ import androidx.compose.ui.unit.dp
 /**
  * The filled call-to-action button: M3 `Button` with a 48 dp minimum touch target
  * applied. Stock M3 buttons sit below that floor by default; wrapping them here clears
- * WCAG 2.2 SC 2.5.8 and the harness's `audit_a11y` bar once, for every call site.
+ * WCAG 2.2 SC 2.5.8 and the verify lane's a11y bar once, for every call site.
  */
 @Composable
 fun AppPrimaryButton(

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppIconButton.kt

@@ -13,7 +13,7 @@ import androidx.compose.ui.graphics.vector.ImageVector
  * The registry's icon button: M3 `IconButton` held to the 48 dp touch-target floor.
  *
  * Stock M3 `IconButton` defaults to a 40x40 dp target — below WCAG 2.2 SC 2.5.8 and this
- * harness's own `audit_a11y` bar — so every raw use is a violation waiting to be measured
+ * verify lane's own a11y bar — so every raw use is a violation waiting to be measured
  * (and historically why a text link masqueraded as a back button). This wrapper clears the
  * floor once, by construction, the same way [AppPrimaryButton] does for filled buttons.
  *

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -378,6 +378,64 @@ class ArchitectureConformanceTest {
         )
     }
 
+    // SPEC: ARCH-13
+    @Test
+    fun `ARCH-13 ambient time is read only inside the designated time provider`() {
+        // The classic "inject the clock" rule. Ambient time reads make rendered structure
+        // and test evidence a function of WHEN you run them — a golden tree that passes at
+        // 23:00 and fails at 09:00 with no code change, an assertion that only reds out
+        // across a midnight boundary. Time is injected from one provider (a package ending
+        // in `.core.time`) so tests can pin it; everywhere else these APIs are banned.
+        // Scanned at reference level (imports AND fully-qualified inline calls), the same
+        // pragmatic granularity as the layer-boundary rules above. Covers kotlinx-datetime
+        // and kotlin.time (`Clock.System`), the JVM clock (`System.currentTimeMillis`),
+        // java.time (`LocalDate.now()` et al.), and the ambient zone
+        // (`TimeZone.currentSystemDefault()`) — the zone is time-of-run state too.
+        val ambientTime = Regex(
+            """Clock\.System|System\.currentTimeMillis|LocalDate\.now\s*\(|LocalDateTime\.now\s*\(|""" +
+                """LocalTime\.now\s*\(|Instant\.now\s*\(|TimeZone\.currentSystemDefault\s*\("""
+        )
+        val offenders = sources(commonMain)
+            .filterNot { it.path.replace(File.separatorChar, '/').contains("/core/time/") }
+            .filter { file -> nonCommentLines(file).any { ambientTime.containsMatchIn(it) } }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-13", "ambient time APIs (Clock.System, System.currentTimeMillis, *.now(), " +
+                    "TimeZone.currentSystemDefault()) are called only inside the designated time " +
+                    "provider (a `core/time` package) — everywhere else, time is an injected value.",
+                offenders,
+                "inject a clock/time provider (constructor parameter, wired in di/) that lives in " +
+                    "`core/time`, and read the current moment through it — never ambiently. Tests then " +
+                    "pin the provider instead of inheriting the wall clock.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-14
+    @Test
+    fun `ARCH-14 ViewModels are registered with explicit viewModel factories - viewModelOf is banned`() {
+        // Koin's reflection-based `viewModelOf(::X)` silently ignores Kotlin default
+        // parameter values: it resolves EVERY constructor parameter from the graph, so a
+        // ViewModel that compiles and previews fine crashes at runtime resolution the
+        // first time a defaulted parameter matters (the default masked a dependency the
+        // graph never registered). An explicit `viewModel { X(get(), …) }` factory states
+        // each dependency and fails at compile time instead.
+        val offenders = sources(commonMain)
+            .filter { file -> nonCommentLines(file).any { it.contains("viewModelOf") } }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-14", "ViewModels are registered with explicit `viewModel { … }` factories — " +
+                    "reflection-based `viewModelOf` is banned (it silently ignores constructor " +
+                    "default parameter values; failures move from compile time to runtime resolution).",
+                offenders,
+                "replace `viewModelOf(::XViewModel)` with `viewModel { XViewModel(get(), …) }` " +
+                    "(import org.koin.core.module.dsl.viewModel), one get() per constructor dependency.",
+            )
+        )
+    }
+
     // SPEC: SHELL-05
     @Test
     fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {

package/template/docs/ARCHITECTURE.md

@@ -21,6 +21,7 @@ app").
 | Maintainability | An AI session adds a feature; the lane names any layer violation as a clause, not a style nit | `[enforced: ARCH-01..05]` |
 | Reliability | A source fails; the failure crosses layers as a typed `DomainError`, never a raw exception, and the screen shows a mapped error state | `[enforced: ARCH-06/07/08]` |
 | Reliability (offline) | Network drops mid-session; cached Room data still renders, UI shows degraded state | `[advisory]` today — `NetworkMonitor` and Room ship as infrastructure (§4, §7) but no repository wires the cache-first fallback yet; clause candidate |
+| Reliability (platform behavior) | A feature that alarms or notifies actually alerts on a real device — the claim crosses the process boundary instead of stopping at a green JVM | instrumented tier (`androidInstrumentedTest`, lane step `androidChecks`); platform-behavior spec clauses cite instrumented tests, never desktop ones |
 | Interaction capability (a11y) | Every interactive element is perceivable by assistive tech and automation | `[enforced: SHELL-04 + A11y gates]` |
 | Security | The debug inspector HTTP server (§3) never ships in a release build | `[advisory]` today — true by source-set placement (`androidDebug`), not yet gated; clause candidate (`DEBUG-01`) |
 
@@ -79,6 +80,7 @@ app").
 | `androidMain` | Android entry point (`AppApplication`), platform `actual`s. |
 | `androidDebug` | Debug-only additions layered on `androidMain` — the inspector HTTP server, crash recorder, DB inspector. Never in `androidRelease`. |
 | `androidRelease` | Release-only twins (currently a no-op inspector stub) that make the `androidDebug` additions compile out cleanly. |
+| `androidInstrumentedTest` | The on-device behavior tier: platform facts no JVM test can see (alarms, notifications, PendingIntent identity, audio routing) asserted in the app's real process — generic helpers in `testing/`, exemplar in `PlatformBehaviorSeamTest`. Runs via the lane's `androidChecks` step (`connectedDebugAndroidTest`; SKIPs without a device). See `docs/TESTING.md` §"The instrumented tier". |
 | `iosMain` | iOS entry point (`MainViewController.kt`, `KoinHelper.kt`), platform `actual`s. |
 | `desktopMain` | The JVM tier: dev-client window/hot-reload, the preview-render harness, and desktop DI — **harness infrastructure**, not a shipped app target (project ADR `0003`). |
 | `desktopTest` | Conformance gates (this document's enforced clauses), Compose UI Tests, golden-tree structural baselines — the fast, device-free verification tier. |
@@ -180,7 +182,7 @@ Three named scenarios ground that loop in what actually happens on this codebase
    Room when `NetworkMonitor.isOnline` is false. Both pieces of infrastructure exist (§3, §7);
    no repository reads them today — hence the offline goal's `[advisory]` status in §1.
 3. **Navigate + process death.** `AppNavHost` (single-Activity/single-`ComposeUIViewController`)
-   owns the back stack; each screen's `ViewModel` (scoped via `viewModelOf`/Koin) survives
+   owns the back stack; each screen's `ViewModel` (a Koin `viewModel { }` factory) survives
    configuration change but not process death — a killed-and-restored process re-runs cold
    start and reloads from the repository, the same path as scenario 1.
 
@@ -232,7 +234,22 @@ injected, not hardcoded, so tests can pass a test dispatcher. Do **not** add `wi
 around calls that are already main-safe by contract; it's dead weight that hides where the
 real guarantee lives.
 
-### DI `[advisory]`
+### Time (inject the clock) `[enforced: ARCH-13]`
+
+**Ambient time reads are banned outside the designated time provider.** `Clock.System`,
+`System.currentTimeMillis`, `LocalDate.now()` / `LocalDateTime.now()` / `LocalTime.now()` /
+`Instant.now()`, and `TimeZone.currentSystemDefault()` may be referenced only inside a
+`core/time` package (the one place allowed to touch the wall clock; a fresh scaffold ships
+no time usage at all, so the package appears with your first time-dependent feature).
+Everywhere else, the current moment arrives as an **injected value** — a clock/time-provider
+interface declared in `core/time` and wired through Koin like any other dependency.
+
+The rationale is determinism of evidence: an ambient time read makes rendered structure and
+test results a function of *when* you run them — a golden tree that passes at 23:00 and
+fails at 09:00 with no code change, a "today" grouping that flips across a midnight
+boundary, a defaulted `Clock.System` constructor parameter that no test can pin. Injected
+time gives tests one seam to freeze, and gives every screen's rendered output a single
+source of "now" the harness can control.
 
 One Koin module per concern: `repositoryModule` / `useCaseModule` / `viewModelModule`
 (`di/AppModule.kt`, common to every platform), plus one platform module for platform-only
@@ -243,6 +260,21 @@ no service-locator lookups inside domain or presentation code. Platform modules
 `actual`-backed singletons (`NetworkMonitor`, `AppDatabase`) that common modules then depend on
 via the domain-facing interface, not the concrete platform type.
 
+**ViewModels are registered with explicit `viewModel { … }` factories; reflection-based
+`viewModelOf` is disallowed** `[enforced: ARCH-14]`. Koin's `viewModelOf` silently ignores
+Kotlin constructor default parameter values — a ViewModel that compiles and previews fine
+crashes at runtime resolution the first time a defaulted parameter matters (the default was
+masking a dependency the graph never registered). An explicit factory states every
+dependency (`viewModel { XViewModel(get(), …) }`) and fails at compile time instead.
+
+Shared-vs-per-destination ViewModel scope is an **intent** decision no static rule can make
+for you `[advisory]`: a screen that default-instantiates its own ViewModel gets a fresh
+instance per destination, so state silently resets on re-entry. State meant to be shared
+across screens must be scoped explicitly — register it once and resolve the same instance
+at each destination (e.g. a `single { … }`-scoped holder, or a factory resolved against a
+shared owner) rather than letting each screen construct its own. Decide the scope when you
+introduce the ViewModel, not after the reset surprises you.
+
 ### Logging `[advisory — no shared logger ships today]`
 
 The scaffold ships **no cross-platform logging library**. The only logging present is Koin's
@@ -274,6 +306,13 @@ map `ItemEntity` → the domain `Item` inside `data/` — and schema changes get
 bump. `fallbackToDestructiveMigration` is a scaffold-stage convenience; replace it before
 shipping user data you can't afford to lose.
 
+Room's exported schema history (`composeApp/schemas/`) is **append-only**
+`[enforced: schemaHistory lane step]`: every version below the current highest is a frozen
+record of a database that shipped, and migrations are validated against those exact bytes.
+The lane fails if a historical `<version>.json` is rewritten or deleted (`git checkout --
+<file>` restores it); only the current highest version — the live, in-progress schema — may
+change between commits.
+
 ### Design tokens `[enforced: ARCH-05]`
 
 `presentation/theme/` (`Tokens.kt`, `Theme.kt`, `Typography.kt`, `Shape.kt`) is the only source

package/template/docs/TESTING.md

@@ -9,6 +9,7 @@ copy their shape.
 | Conformance gates (ARCH clauses) | `composeApp/src/desktopTest/…/conformance` | same task |
 | Screen behavior — Compose UI Test (spec-cited) | `composeApp/src/desktopTest/…/presentation` | same task |
 | Golden trees (structure) | `qa/golden/` + `HomeGoldenTreeTest` | same task |
+| Instrumented behavior (platform facts) | `composeApp/src/androidInstrumentedTest` | `./gradlew :composeApp:connectedDebugAndroidTest` (device attached) |
 <!-- >>> cmp:feature e2e -->
 | E2E smoke (few) | `qa/e2e/*.yaml` (Maestro) | `maestro test qa/e2e/smoke.yaml` |
 <!-- <<< cmp:feature e2e -->
@@ -47,6 +48,82 @@ Every durable test cites the spec clause it verifies (`// SPEC: HOME-02` — see
 Never delete, weaken, or `@Ignore` a failing test to get green. Fix the behavior — or if the
 test is genuinely wrong, change it and say so explicitly in your PR/summary.
 
+## The instrumented tier — platform behavior
+
+This seam exists because platform behavior escapes every desktop tier. Alarms,
+notifications, lock-screen/full-screen intents, notification channels, PendingIntent
+identity, audio routing, process death, and runtime permissions are OS facts:
+`desktopTest` runs on a JVM, golden trees pin structure, the conformance suite is static,
+and the E2E smoke taps UI without asserting anything about the shade or the alarm table.
+A feature whose whole point is "the phone alerts" can ship fully green from every other
+tier and never alert — that class of defect escaped to production repeatedly before this
+tier existed. When your feature touches alarms, notifications, or locks, its behavior
+test lives here.
+
+**What belongs here:** claims only the OS can witness — a notification actually reached
+the shade, a channel holds the importance the feature needs, N logical alarms occupy N
+PendingIntent slots, the alert path plays with `USAGE_ALARM` on a silenced ringer, the
+app survives process death, a permission-gated path degrades correctly.
+
+**What does not:** logic (→ `commonTest`), rendered structure (→ golden trees),
+architecture rules (→ conformance), UI journeys (→ E2E flows). If a JVM test can prove
+it, a JVM test is where it goes — this tier is the most expensive seat in the house.
+
+**Cost model:** needs a device/emulator, so it runs at checkpoint cadence — the lane's
+`androidChecks` step (`connectedDebugAndroidTest`) SKIPs honestly when no device is
+attached and runs in `local`/`ci` when one is, with the `release` profile adding the
+release-APK smoke on top. It is not an inner-loop tier; don't reach for it per-edit.
+
+**The helpers** (`androidInstrumentedTest/…/testing/`), small and composable — see
+`PlatformBehaviorSeamTest` for the exemplar shape:
+
+- `NotificationAsserts` — bounded-poll wait for a posted notification (id/tag or
+  predicate), channel-exists with an importance floor, full-screen-intent capability
+  (API-aware).
+- `AlarmAsserts` — the OS alarm table (`dumpsys alarm`) parsed per-package;
+  alarm-registered and N-distinct-alarms assertions (the PendingIntent-identity
+  collision, caught mechanically).
+- `SystemState` — snapshot/restore of ringer mode and DND so audio-routing claims are
+  testable; its header is honest about what instrumentation cannot control (OEM sound
+  policy, "a human heard it") — those stay a documented manual tier.
+
+### Runtime state control — put the system into the state the claim is about
+
+The observation helpers above answer "what did the OS do?"; this organ family answers
+the prior question — "can the test even reach the state the claim is about?" Most
+unprovable mobile claims are unprovable exactly because the state is hard to reach: you
+would have to wait hours for Doze, ship to a user who denies the permission, drop the
+network by hand, or hope the OS reclaims your process while you watch. Each organ
+reaches one such state on demand — emulator-only (every entry point SKIPs on a real
+device), root-free on stock user-build images (every shell command verified from the
+shell uid), and bracket-shaped (`withX { }` — snapshot, act, restore in `finally`) so
+organs compose:
+
+- `TimeWarp` — the device clock and time zone ("the 08:00 alarm actually arrives", DST).
+- `DozeControl` — forced light/deep idle; composed with TimeWarp it proves
+  `setExactAndAllowWhileIdle` does what its name promises (the flagship exemplar in
+  `RuntimeStateSeamTest`).
+- `PermissionControl` — the denied state (the fresh-install default) as a test input;
+  one-way grants. Its header documents the trap that shapes it: revoking a held runtime
+  permission kills the holding process — this seam's own process.
+- `ProcessControl` — real OS-driven activity destruction and saved-state rebuild
+  (don't-keep-activities — flipped live via the same binder call the Developer-options
+  toggle uses, because `settings put global always_finish_activities` alone is read only
+  at boot; verified on API 35); honest about why in-process "kill my own process" is
+  structurally impossible under instrumentation.
+- `NetworkControl` — offline (airplane mode) and per-transport wifi/data brackets; the
+  path to proving `core/connectivity/NetworkMonitor` tracks the world.
+- `ConfigControl` — dark mode, font scale, per-app locale (API 33+); configuration
+  change as the other state-loss lever.
+
+What device-state control cannot reproduce, honestly: the path INTO a state (real Doze's
+descent ladder and maintenance windows — forced idle teleports and holds), OEM policy
+(battery managers, sound routing, skinned lock screens), app-standby buckets, real-network
+character (bandwidth, captive portals, flaky RSSI — emulator transports are the host's
+connection wearing costumes), true cold-process start under instrumentation, and anything
+whose proof is a human's senses. Each organ's header states its own gaps; a green test is
+evidence for exactly the state the organ produced, nothing wider.
+
 <!-- >>> cmp:feature e2e -->
 ## E2E
 
@@ -70,3 +147,91 @@ asserts are for static post-navigation elements only.
 attached. It writes the evidence receipt to `qa/evidence/latest.json`; **commit the receipt
 with your change.** SKIPped steps are recorded honestly — green-with-gaps is visible, never
 silent.
+
+**`--fast` is the lane's inner loop.** `node qa/verify.mjs --fast` runs the resolved
+profile minus the device/release tier (`releaseBuild`, `tokenDrift`, `e2eSmoke`,
+`androidChecks`, `releaseSmoke`) — unconditionally, device attached or not. It exists
+because device/release evidence is the scarce, slow tier (R8 compile, emulator, Maestro,
+instrumented runner): batch it at the checkpoint, don't pay for it on every small edit.
+The rest of the profile runs cheaply, three ways:
+
+- **Unchanged pure-Node steps are reused, not re-run.** `specCoverage`, `approvals`,
+  `componentStories`, `reachability`, and `archDoc` are pure functions of files on disk;
+  a fast run reuses each one's last PASS when a content hash of its declared inputs is
+  unchanged, shown as `⚡ name: CACHED (unchanged since …)`. Only a PASS is ever reused —
+  a FAIL or SKIP always re-runs — and the cache
+  (`composeApp/build/.cmp-step-cache.json`) is a gitignored cache, never evidence: the
+  full lane never reads it (it always executes every step; it only writes entries so the
+  next fast run benefits).
+- **Gradle's up-to-date checks stand.** The full lane forces test execution with
+  `--rerun` (evidence integrity — a receipt must attest tests that ran). A fast receipt
+  is already declared non-evidence, so fast mode omits the flag and unchanged test tasks
+  cost nothing.
+- **Unit tests are scoped to the change.** Changed `.kt` files (git diff + untracked)
+  map to `--tests "*<feature>*"` filters, reported honestly in the step line and the
+  receipt. Broad-impact changes — build files, DI, theme/tokens, shared components,
+  `qa/` itself, anything outside `composeApp/src` — disable filtering and run the whole
+  suite, as does any uncertain case (no git, unmappable change): fail open, never fail
+  silent. A filtered fast run can miss a cross-feature regression by design; the full,
+  unfiltered suite at the checkpoint is what decides done.
+
+A fast run is mechanically unable to claim done — its receipt records `"mode": "fast"`,
+derives **no** evidence rung, and `qa/receipt-check.mjs` (the Stop hook, CI, pre-push)
+refuses it by name. Iterate on `--fast`; run the full lane once, deliberately, when the
+change is done.
+
+**Watch mode makes the inner loop resident.** `node qa/watch.mjs` watches
+`composeApp/src`, `specs/`, and `qa/` and re-runs `node qa/verify.mjs --fast` (as a
+subprocess — it inherits every fast-mode economy above for free) on every save, debounced
+so a multi-file save storm triggers one run and changes landing mid-run coalesce into
+exactly one follow-up. Each run re-prints the step table with any failing step's reason
+verbatim — the errors-on-save loop an IDE gives a human, for the agent. What it is **not**:
+evidence. It runs the fast tier only, so nothing it produces can satisfy the done-gate,
+and every run says so in a standing footer; the checkpoint remains one deliberate full
+`node qa/verify.mjs` run. Coordination: it never launches while a verify lane
+(`.cmp-lane-in-progress`) or a preview-daemon render (`.cmp-render-in-progress`) holds the
+project — it waits and coalesces, so watch mode, the preview daemon, and the lane can all
+be resident on one project without two Gradle invocations ever colliding. `--once` runs a
+single coordinated pass for scripting; `--json` emits one JSON object per run for
+programmatic consumption.
+
+## One device, one driver
+
+The machine typically has ONE Android device/emulator, and it is the scarcest, slowest,
+most fragile resource the harness touches — two concurrent drivers produce wedged adbd,
+`device offline` while `adb devices` looks fine, crossed app state, and false reds that
+have nothing to do with the app. So device evidence is **batched, never an inner loop**:
+the lane sequences its device steps (`tokenDrift` live tier, `e2eSmoke`, `androidChecks`,
+`releaseSmoke`) once, last — don't hand-run `connectedDebugAndroidTest`, `maestro test`,
+or `adb install` mid-task to "check something".
+
+Mechanically, the first device step takes a **machine-global lease** on the device's adb
+serial (`<os tmpdir>/create-cmp/device-leases/<serial>.json` — `qa/lib/device-lease.mjs`
+documents the contract), held until the lane exits. It is machine-global on purpose: two
+different projects (a scratch app in /tmp, the real one) share the same emulator, and
+per-project markers cannot see each other.
+
+**Contention is a SKIP, never a FAIL** — nothing is broken; another run legitimately holds
+the device, and the reason names it: `held by "verify lane e2eSmoke" (pid 4711,
+/tmp/scratch-x, 2m ago)`. A SKIPped device step does not buy its rung, so contention
+visibly *lowers* the evidence level (L2 falls back to L1) instead of corrupting the run —
+re-run when the holder finishes to earn the full rung. To see who holds a device:
+`cat "${TMPDIR:-/tmp}/create-cmp/device-leases/<serial>.json"`. A crashed holder never
+wedges the machine: a lease whose pid is dead, or older than 30 minutes, is silently
+reclaimed by the next run. The live inspector tier (`connect_live`,
+`navigate_and_inspect`) checks the same lease and refuses to drive a leased device by
+naming the holder instead of failing with a mysterious transport error.
+
+## The evidence ladder
+
+Every PASS receipt names its rung (`evidenceLevel` in the receipt; derived by
+`qa/lib/evidence-level.mjs` from which steps actually ran and PASSed — never declared, and
+a SKIPped step never buys a rung: an unsigned-keystore `releaseSmoke` SKIP is not L3). The
+rung is the coarse grade; the per-step list stays the fine print. A FAILed lane has no rung.
+
+| Rung | What it proves | What it does NOT prove |
+|---|---|---|
+| **L0 scaffold** | Stamp-time green: the build compiles and the unit tests pass. | Nothing about conformance, rendered structure, a11y, or the release variant — and nothing on a device. |
+| **L1 desktop** | Full static + JVM evidence: build, unit tests, conformance, golden trees, a11y, release COMPILE, and the pure-Node gates. | That the app runs on a device at all — no APK was installed or driven; platform behavior (alarms, notifications) is invisible from this rung. |
+| **L2 device** | L1 plus executed on-device evidence: the debug APK installed and driven (`e2eSmoke`), instrumented platform assertions (`androidChecks`), and/or live token drift. | That the release variant behaves (R8 differs from debug — that is L3's job), nor that alarms/notifications actually land unless an instrumented behavior test asserts them. |
+| **L3 release** | L2 plus `releaseSmoke` PASSed: the signed release APK installed and driven on a device. | Real-backend behavior (the emulator/dev backend is a documented tier boundary — see the instrumented-tier section) and store-review compliance. |

package/template/gradle/libs.versions.toml

@@ -22,6 +22,14 @@ compose-hot-reload = "1.1.1"
 coil = "3.1.0"
 androidx-core = "1.15.0"
 androidx-activity = "1.10.1"
+# ── Android instrumentation tier (androidInstrumentedTest). The alarm table, the
+# ── notification shade, channels, and audio routing are OS facts no JVM test can see —
+# ── this tier is the only evidence that crosses the process boundary onto a real device.
+androidx-test-runner = "1.6.2"
+androidx-test-core = "1.6.1"
+androidx-test-ext-junit = "1.2.1"
+androidx-uiautomator = "2.3.0"
+junit4 = "4.13.2"
 
 [libraries]
 # Compose Multiplatform
@@ -82,6 +90,13 @@ androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidx
 androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activity" }
 android-desugar-jdk = { module = "com.android.tools:desugar_jdk_libs", version = "2.1.3" }
 
+# Android instrumentation (androidInstrumentedTest — the on-device behavior tier)
+androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" }
+androidx-test-core = { module = "androidx.test:core", version.ref = "androidx-test-core" }
+androidx-test-ext-junit = { module = "androidx.test.ext:junit", version.ref = "androidx-test-ext-junit" }
+androidx-uiautomator = { module = "androidx.test.uiautomator:uiautomator", version.ref = "androidx-uiautomator" }
+junit4 = { module = "junit:junit", version.ref = "junit4" }
+
 # Test
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
 koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }