create-cmp-cli 0.10.1 → 0.12.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/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt

@@ -2,6 +2,7 @@ package __PACKAGE__.presentation.navigation
 
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.ui.Modifier
 import androidx.navigation.NavType
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
@@ -10,6 +11,9 @@ import androidx.navigation.navArgument
 // Nav 2.9 (multiplatform): backStackEntry.arguments is a SavedState, not an Android Bundle.
 // Read it via the androidx.savedstate.read extension, NOT Bundle.getString().
 import androidx.savedstate.read
+// Kept OUTSIDE the screen-imports block below: the tab rewriter (src/lib/tabs.mjs) replaces
+// exactly those two lines with the configured tabs' screen imports.
+import __PACKAGE__.presentation.components.exposeTestTagsForAutomation
 import __PACKAGE__.presentation.home.HomeScreen
 import __PACKAGE__.presentation.profile.ProfileScreen
 
@@ -38,7 +42,18 @@ fun AppNavHost() {
         }
     }
 
-    NavHost(navController = navController, startDestination = Screen.Shell.route) {
+    // Expose Compose testTags to the platform automation layer (Android resource-ids / iOS
+    // accessibilityIdentifiers) for the WHOLE graph. The property is inherited by descendants,
+    // so it belongs on the graph root, not on a destination: applied inside AppShell it would
+    // cover the tabs and nothing else, leaving every destination registered directly here
+    // (detail screens, trays) with testTags no id-selector can see — e2e flows could not
+    // assert arrival on them at all. Here, a destination added later inherits it without
+    // anyone remembering to. Desktop: no-op.
+    NavHost(
+        navController = navController,
+        startDestination = Screen.Shell.route,
+        modifier = Modifier.exposeTestTagsForAutomation(),
+    ) {
         composable(Screen.Shell.route) {
             val tabs = appTabs(
                 home = {

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt

@@ -10,7 +10,6 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import __PACKAGE__.presentation.components.AppBottomBar
 import __PACKAGE__.presentation.components.BaseScreen
-import __PACKAGE__.presentation.components.exposeTestTagsForAutomation
 
 /**
  * Generic bottom-nav shell. Parameterized by a [tabs] list — NOT role-hardcoded.
@@ -27,10 +26,8 @@ fun AppShell(tabs: List<AppTab>) {
     var selected by rememberSaveable { mutableIntStateOf(0) }
 
     BaseScreen(
-        // Expose Compose testTags to the platform automation layer (Android resource-ids /
-        // iOS accessibilityIdentifiers) so Appium/uiautomator id-selectors and the
-        // cmp-test-generated suites find them; covers the whole subtree. Desktop: no-op.
-        modifier = Modifier.exposeTestTagsForAutomation(),
+        // testTag exposure for automation is applied once on the NavHost in AppNavHost.kt —
+        // the graph root, so every destination inherits it, not just these tabs.
         // The bottom bar owns the navigation-bar inset; the body must not also pad it.
         applyNavBarPadding = false,
         bottomBar = {

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