@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/README.md

@@ -2,24 +2,24 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 213 skills (60 core + 153 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 219 skills (61 core + 158 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  60 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
-- **`external/`**  -  153 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
+- **`core/`**  -  61 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`external/`**  -  158 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
 - Install destinations (ADR-0009): Claude Code gets NO local copy of `external/` - it loads those skills from the `multi-agent-plugins` marketplace, namespaced (`ai-<stack>-toolkit:<name>`); only the two compliance catalogs from `core/` land in `~/.claude/skills/`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. `external/` remains the single authoring source that `build-stack-plugins.mjs` publishes from.
 
 Source layout is logical grouping only  -  skill discovery at runtime is unchanged.
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  60
+- [Pipeline Orchestration](#pipeline-orchestration)  -  61
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  90
-- [Android / Kotlin](#android-kotlin)  -  13
+- [Android / Kotlin](#android-kotlin)  -  17
 - [Web](#web)  -  10
 - [Backend / API](#backend-api)  -  11
-- [Cross-cutting](#cross-cutting)  -  29
+- [Cross-cutting](#cross-cutting)  -  30
 
 ## Pipeline Orchestration
 
@@ -71,6 +71,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-save`](./core/multi-agent-save/) | `core` | Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick o |
 | [`multi-agent-scan`](./core/multi-agent-scan/) | `core` | Skill security scan: walks local skill directories against a tiered pattern catalog. Use when local skill directories need checking for unsa |
 | [`multi-agent-search`](./core/multi-agent-search/) | `core` | Log search across every agent-log.md with smart ranking and filters. Optional --semantic flag queries the per-repo triage corpus. Use when s |
+| [`multi-agent-security-review`](./core/multi-agent-security-review/) | `core` | Run a standalone defensive, static security review of a diff, branch or repo: run-scoped threat model, reviewer-shaped findings joined to OW |
 | [`multi-agent-setup`](./core/multi-agent-setup/) | `core` | First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up f |
 | [`multi-agent-stack`](./core/multi-agent-stack/) | `core` | Select the active stack(s) for this repo by enabling the matching marketplace plugin(s) in .claude/settings.json. Multi-select: pass several |
 | [`multi-agent-status`](./core/multi-agent-status/) | `core` | Show every multi-agent task's ID, phase, branch, and status. Use when asked what is running, or for an overview of every task. |
@@ -185,11 +186,15 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 
 | Skill | Group | Description |
 |-------|-------|-------------|
-| [`android_ui_verification`](./external/android_ui_verification/) | `external` | Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to |
 | [`android-architecture`](./external/android-architecture/) | `external` | Design and implement Clean Architecture with multi-module structure on Android. Covers domain/data/presentation layers, Hilt dependency inje |
+| [`android-build-quality-gates`](./external/android-build-quality-gates/) | `external` | Encode Android module and quality rules as build-failing Gradle tasks: layer-dependency checks, coverage floors, a Compose-stability gate, l |
+| [`android-datastore`](./external/android-datastore/) | `external` | Typed Jetpack DataStore as the modern SharedPreferences replacement: Preferences and typed stores, serializer-layer encryption, and migratio |
+| [`android-design-tokens-codegen`](./external/android-design-tokens-codegen/) | `external` | A single-source JSON to typed-Kotlin codegen pipeline for design tokens, UI-test ids, analytics events and deeplink manifests, run as Gradle |
 | [`android-jetpack-compose-expert`](./external/android-jetpack-compose-expert/) | `external` | Expert guidance for building modern Android UIs with Jetpack Compose, covering state management, navigation, performance, and Material Desig |
+| [`android-mvi-viewmodel`](./external/android-mvi-viewmodel/) | `external` | A reusable generic BaseViewModel<State, Intent, Event> for MVI Compose apps: StateFlow state, one-shot events over a rendezvous Channel, a s |
 | [`android-performance`](./external/android-performance/) | `external` | Optimize Android app performance with Baseline Profiles for startup, Compose stability annotations (@Stable, @Immutable, strong skipping), r |
 | [`android-security`](./external/android-security/) | `external` | Secure Android apps with ProGuard/R8 obfuscation, OkHttp certificate pinning, BiometricPrompt authentication, EncryptedSharedPreferences, Pl |
+| [`android-ui-verification`](./external/android-ui-verification/) | `external` | Automated end-to-end UI testing and verification on an Android Emulator using ADB. Use when an Android build needs driving on an emulator to |
 | [`compose-components`](./external/compose-components/) | `external` | Build Material 3 UI components and custom composables with Jetpack Compose. Covers TopAppBar, Scaffold, BottomSheet, SnackbarHost, slot-base |
 | [`compose-navigation`](./external/compose-navigation/) | `external` | Implement type-safe navigation in Jetpack Compose using Navigation 2.8+ with @Serializable routes, NavHost, composable<Route>, nested naviga |
 | [`compose-testing`](./external/compose-testing/) | `external` | Test Jetpack Compose UI with createComposeRule, semantic matchers (onNodeWithText, onNodeWithTag, onNodeWithContentDescription), actions (pe |
@@ -255,6 +260,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`localization-reuse-map`](./external/localization-reuse-map/) | `external` | >- |
 | [`pdfkit`](./external/pdfkit/) | `external` | Display and manipulate PDF documents using PDFKit. Use when embedding PDFView to show PDF files, creating or modifying PDFDocument instances |
 | [`search-first`](./external/search-first/) | `external` | \| |
+| [`security-review`](./external/security-review/) | `external` | Run a defensive, static security review of a diff or a repo: build a run-scoped threat model, find vulnerabilities joined to OWASP + CWE wit |
 | [`signal-community`](./external/signal-community/) | `external` | Check whether other people hit the same problem, via Stack Overflow and Hacker News (keyless) plus opt-in Reddit and X. Use when a bug repor |
 | [`skill-creator`](./external/skill-creator/) | `external` | Author and refine skills for a plugin/toolkit efficiently. Use when creating a new skill, trimming or splitting an existing one, writing a s |
 | [`spm-build-analysis`](./external/spm-build-analysis/) | `external` | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhead that slow Xcode builds. Use whe |

package/pipeline/skills/shared/external/android-architecture/SKILL.md

@@ -12,10 +12,12 @@ and Jetpack libraries from 2024-2025.
 ## Contents
 
 - [Multi-Module Structure](#multi-module-structure)
+- [Feature api/impl Split](#feature-apiimpl-split)
 - [Domain Layer](#domain-layer)
 - [Data Layer](#data-layer)
 - [Presentation Layer](#presentation-layer)
 - [Hilt Dependency Injection](#hilt-dependency-injection)
+- [Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)
 - [Mapper Pattern](#mapper-pattern)
 - [Do's and Don'ts](#dos-and-donts)
 - [Troubleshooting](#troubleshooting)
@@ -77,6 +79,33 @@ include(":feature:search")
 include(":feature:detail")
 ```
 
+## Feature api/impl Split
+
+For features that navigate to each other, split each one into two modules:
+
+- `:feature:x:api` -- only the cross-feature contract: `@Serializable` route
+  definitions and the entry-param models a caller needs to launch the feature.
+- `:feature:x:impl` -- screens, ViewModels, UI state, and DI wiring.
+
+A feature depends only on the `:api` of the features it navigates to, never
+their `:impl`:
+
+```kotlin
+// feature:home:impl/build.gradle.kts
+dependencies {
+    implementation(project(":feature:home:api"))
+    implementation(project(":feature:detail:api"))   // route + entry params only
+    // NEVER depend on :feature:detail:impl
+}
+```
+
+Because no `impl` module can see another `impl`, they stay mutually invisible,
+compile in parallel, and cannot form dependency cycles. The `:app` module wires
+them together (see
+[Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)).
+Full module layout and route contract:
+[references/patterns.md#feature-apiimpl-split](references/patterns.md#feature-apiimpl-split).
+
 ## Domain Layer
 
 The domain layer contains business logic with zero Android dependencies. It
@@ -231,6 +260,11 @@ sealed interface HomeUiState {
 }
 ```
 
+For the reusable base ViewModel seam these screen ViewModels extend -- immutable
+state as `StateFlow`, one-shot events, a single intent entry point, and
+centralized use-case execution -- see the `android-mvi-viewmodel` skill. Do not
+reimplement that base class here.
+
 ## Hilt Dependency Injection
 
 ### Application Setup
@@ -324,6 +358,36 @@ abstract class DispatcherModule {
 }
 ```
 
+## Cross-Module Navigation Graph Aggregation
+
+Each `:impl` module contributes its destinations to a shared `Set<NavGraph>` via
+Hilt multibinding; the host registers the whole set into one `NavHost`. The
+`:app` module never depends on any `:impl`.
+
+```kotlin
+fun interface NavGraph {
+    fun NavGraphBuilder.build(navController: NavHostController)
+}
+
+// In each :impl module
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class HomeNavModule {
+    @Binds
+    @IntoSet
+    abstract fun bindHomeNavGraph(impl: HomeNavGraph): NavGraph
+}
+
+// In :app -- register every contributed graph, naming no feature
+NavHost(navController, startDestination = HomeRoute) {
+    navGraphs.forEach { graph -> with(graph) { build(navController) } }
+}
+```
+
+This wires many feature modules into a single `NavHost` without the app module
+depending on every `impl`. Full host injection and per-feature contribution:
+[references/patterns.md#cross-module-navigation-graph-aggregation](references/patterns.md#cross-module-navigation-graph-aggregation).
+
 ## Mapper Pattern
 
 Mappers isolate layer boundaries. Each layer has its own model type.
@@ -372,9 +436,13 @@ class FlightMapper @Inject constructor() {
 - Define a `DispatcherProvider` interface for testable coroutine dispatchers
 - One use case per business operation
 - Use `sealed interface` for UI state to guarantee exhaustive `when` handling
+- Split each feature into `:api` (routes + entry params) and `:impl` (screens, ViewModels, DI)
+- Aggregate feature nav graphs into the host with Hilt `@IntoSet` multibinding
 
 ### Don'ts
 - Do not let feature modules depend on each other directly
+- Do not depend on another feature's `:impl` module -- depend on its `:api` only
+- Do not make the `:app` module reference feature `impl` modules in code
 - Do not put Android framework classes in the domain layer
 - Do not expose `MutableStateFlow` from ViewModels (expose read-only `StateFlow`)
 - Do not inject `Activity` or `Fragment` into ViewModels
@@ -402,6 +470,9 @@ class FlightMapper @Inject constructor() {
 - [ ] UI state is a `sealed interface` with Loading/Success/Error
 - [ ] Hilt modules use `@Binds` for interfaces, `@Provides` for instances
 - [ ] Feature modules do not depend on each other
+- [ ] Each feature is split into `:api` (routes/entry params) and `:impl` (screens/ViewModels/DI)
+- [ ] Feature `impl` modules depend only on other features' `api`, never their `impl`
+- [ ] Feature nav graphs aggregate into the host via Hilt `@IntoSet` multibinding
 - [ ] Mappers separate DTO/Entity/Domain models
 - [ ] Coroutine dispatchers are injectable via `DispatcherProvider`
 - [ ] No `GlobalScope` usage; all coroutines use structured concurrency

package/pipeline/skills/shared/external/android-architecture/references/patterns.md

@@ -0,0 +1,142 @@
+# Android Clean Architecture -- Reference Patterns
+
+Full code for the patterns summarized in `SKILL.md`. Load the section you need
+when implementing that specific structure.
+
+## Contents
+
+- [Feature api/impl Split](#feature-apiimpl-split)
+- [Cross-Module Navigation Graph Aggregation](#cross-module-navigation-graph-aggregation)
+
+## Feature api/impl Split
+
+Split every feature into an `:api` module (the cross-feature contract) and an
+`:impl` module (everything private to the feature).
+
+```
+:feature:home:api             # Serializable routes + entry-param models only
+:feature:home:impl            # Screens, ViewModels, UI state, DI
+:feature:search:api
+:feature:search:impl
+:feature:detail:api
+:feature:detail:impl
+```
+
+### The api module holds only the contract
+
+```kotlin
+// :feature:detail:api
+@Serializable
+data class DetailRoute(val id: String)
+
+@Serializable
+data class DetailEntryParams(val id: String, val source: String)
+```
+
+No screens, no ViewModels, no Compose dependency -- just the route and the
+models a caller needs to launch the feature.
+
+### The impl module holds everything private
+
+```kotlin
+// :feature:detail:impl -- not visible to any other feature
+@HiltViewModel
+class DetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val getDetailUseCase: GetDetailUseCase,
+) : ViewModel() {
+    private val route = savedStateHandle.toRoute<DetailRoute>()
+    // ... state, intents, events
+}
+
+@Composable
+internal fun DetailScreen(viewModel: DetailViewModel = hiltViewModel()) { /* ... */ }
+```
+
+### Dependency direction
+
+```kotlin
+// feature:home:impl/build.gradle.kts
+dependencies {
+    implementation(project(":feature:home:api"))
+    implementation(project(":feature:detail:api"))   // route + entry params only
+    implementation(project(":core:model"))
+    implementation(project(":core:ui"))
+    // NEVER implementation(project(":feature:detail:impl"))
+}
+```
+
+Because no `impl` module can see another `impl`, the graph of feature modules is
+acyclic by construction, the modules compile in parallel, and a caller can only
+couple to a feature through its published route and entry params.
+
+## Cross-Module Navigation Graph Aggregation
+
+Each `:impl` module contributes its destinations to a shared `Set<NavGraph>` via
+Hilt multibinding. The host module (`:app`) injects the full set and registers
+every contribution into one `NavHost`, without depending on any `:impl`.
+
+### The contribution contract
+
+```kotlin
+// :core:ui (or a :core:navigation module)
+fun interface NavGraph {
+    fun NavGraphBuilder.build(navController: NavHostController)
+}
+```
+
+### Each feature contributes its graph
+
+```kotlin
+// :feature:home:impl
+class HomeNavGraph @Inject constructor() : NavGraph {
+    override fun NavGraphBuilder.build(navController: NavHostController) {
+        composable<HomeRoute> {
+            HomeScreen()
+        }
+    }
+}
+
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class HomeNavModule {
+    @Binds
+    @IntoSet
+    abstract fun bindHomeNavGraph(impl: HomeNavGraph): NavGraph
+}
+```
+
+### The host registers the whole set
+
+```kotlin
+// :app
+@Composable
+fun AppNavHost(
+    navGraphs: Set<@JvmSuppressWildcards NavGraph>,
+    navController: NavHostController = rememberNavController(),
+    startDestination: Any = HomeRoute,
+) {
+    NavHost(navController = navController, startDestination = startDestination) {
+        navGraphs.forEach { graph -> with(graph) { build(navController) } }
+    }
+}
+```
+
+Injecting the set into the composable is done with a Hilt entry point or by
+passing it from an `@AndroidEntryPoint` activity:
+
+```kotlin
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+    @Inject lateinit var navGraphs: Set<@JvmSuppressWildcards NavGraph>
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent { AppNavHost(navGraphs = navGraphs) }
+    }
+}
+```
+
+Adding a feature to the app is now: add its `:impl` to the `:app` runtime
+classpath and its `@IntoSet` binding registers automatically. The `:app` module
+never names the feature in code.

package/pipeline/skills/shared/external/android-build-quality-gates/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: android-build-quality-gates
+description: "Encode Android module and quality rules as build-failing Gradle tasks: layer-dependency checks, coverage floors, a Compose-stability gate, lint-on-diff and screenshot validation. Use when a multi-module app needs enforceable boundaries and quality gates in the build, not in review."
+risk: safe
+source: multi-agent-pipeline
+date_added: "2026-09-21"
+---
+
+# Android Build Quality Gates
+
+A convention holds only while everyone remembers it. A gate holds because the
+build turns red without it. This skill covers the quality rules worth promoting
+from review comments into Gradle tasks that fail: layer boundaries, coverage
+floors, Compose stability, lint on changed files, and screenshot validation.
+
+Targets AGP 8.x, Gradle 8.x with the configuration cache, Kover 0.8+, and the
+Compose compiler Gradle plugin (Kotlin 2.0+). Copy-ready, full-length code for
+every gate lives in [references/patterns.md](references/patterns.md); this file
+carries the decisions and short snippets.
+
+## Contents
+
+- [Where gates live](#where-gates-live)
+- [Layer-dependency gate](#layer-dependency-gate)
+- [Coverage floor with Kover](#coverage-floor-with-kover)
+- [Compose-stability gate](#compose-stability-gate)
+- [Lint on diff](#lint-on-diff)
+- [Screenshot validation task](#screenshot-validation-task)
+- [Ratchet, do not wall](#ratchet-do-not-wall)
+- [Wiring gates into check](#wiring-gates-into-check)
+- [Do's and Don'ts](#dos-and-donts)
+- [Review Checklist](#review-checklist)
+
+## Where gates live
+
+Author gates once in a convention plugin under `build-logic`, then apply that
+plugin from each module. A gate copied into twenty `build.gradle.kts` files
+drifts; a gate in one convention plugin is a single source of truth. See
+`gradle-kotlin-dsl` for how the `build-logic` module and version catalog are
+set up; this skill only adds tasks inside it.
+
+Every gate follows the same three-part shape:
+
+1. A task (or a `verify`/`check`-typed configuration) that computes a fact about
+   the module: its dependency set, its coverage ratio, its unskippable
+   composables.
+2. An assertion that throws `GradleException` when the fact violates the rule.
+3. A wire into the `check` lifecycle (or a `finalizedBy` on an existing task) so
+   it runs without anyone remembering to call it.
+
+Keep the assertion message actionable: name the offending dependency, the
+current versus required number, the exact composable. A gate that fails with
+"verification failed" gets suppressed; one that says "module `feature-x` depends
+on `data-y`, which is not in its allowed set" gets fixed.
+
+## Layer-dependency gate
+
+Clean layering (feature -> domain -> data, never feature -> data directly, never
+domain -> feature) is the rule most often stated and least often enforced. Encode
+it by walking a module's resolved project dependencies and asserting each is in
+an allowed set for that module's layer.
+
+Register a task that reads the `implementation`/`api` configurations, keeps only
+`ProjectDependency` entries, and compares their paths against an allowlist:
+
+```kotlin
+val checkLayerDependencies by tasks.registering {
+    group = "verification"
+    val layer = project.moduleLayer()
+    val projectDeps = configurations
+        .matching { it.name in setOf("implementation", "api") }
+        .flatMap { it.dependencies.withType<ProjectDependency>() }
+        .map { it.path }
+    doLast {
+        val forbidden = projectDeps.filterNot { layer.allows(it) }
+        if (forbidden.isNotEmpty()) {
+            throw GradleException(
+                "$path ($layer) declares forbidden dependencies: $forbidden"
+            )
+        }
+    }
+}
+tasks.named("check").configure { dependsOn(checkLayerDependencies) }
+```
+
+Derive the layer from the module path or a convention (`feature-*`, `domain-*`,
+`data-*`) rather than a hand-maintained map, so a new module is governed the day
+it is created. The full version, including the layer enum, its `allows` matrix,
+and configuration-cache-safe capture of dependency paths, is in
+[references/patterns.md#layer-dependency-gate](references/patterns.md#layer-dependency-gate).
+
+Read dependency paths at configuration time into a local (as above), not inside
+`doLast` off the live `configurations` object, so the task stays compatible with
+the configuration cache.
+
+## Coverage floor with Kover
+
+A coverage number nobody enforces only decorates a report. Kover's verification
+rule turns it into a gate: below the floor, the build fails.
+
+Apply `org.jetbrains.kotlinx.kover` and declare a bound:
+
+```kotlin
+kover {
+    reports {
+        verify {
+            rule("Line coverage floor") {
+                minBound(60)
+            }
+        }
+    }
+}
+```
+
+Split instrumentation from aggregation. Each module applies the Kover plugin so
+its own classes are instrumented; a single aggregation module (or the root)
+depends on every measured module and owns the `verify` rule over the merged
+report. Verifying per module produces noisy, uneven thresholds; verifying the
+aggregate gives one honest project number. The aggregation wiring and per-module
+exclusion of generated code (`*_Factory`, `*Args`, `BuildConfig`, Hilt
+components) are in
+[references/patterns.md#coverage-floor-with-kover](references/patterns.md#coverage-floor-with-kover).
+
+Gate the floor behind a property so local `assembleDebug` stays fast and only CI
+(or an explicit run) pays for instrumented coverage:
+
+```kotlin
+tasks.named("check").configure {
+    if (providers.gradleProperty("enableCoverageVerification").isPresent) {
+        dependsOn("koverVerify")
+    }
+}
+```
+
+Run it in CI with `-PenableCoverageVerification`. Set the floor to the current
+measured value, not an aspirational one; see [Ratchet, do not wall](#ratchet-do-not-wall).
+
+## Compose-stability gate
+
+Unstable parameters silently defeat recomposition skipping and cause jank that
+no unit test catches. The Compose compiler can emit a stability report; parse it
+and fail when a composable that should skip cannot.
+
+First point the compiler's metrics and reports at a build directory via the
+Compose compiler Gradle plugin:
+
+```kotlin
+composeCompiler {
+    val dir = layout.buildDirectory.dir("compose-metrics")
+    metricsDestination.set(dir)
+    reportsDestination.set(dir)
+}
+```
+
+This produces `*-composables.txt` per module. Register a task that parses those
+files, collects every `restartable` composable marked `skippable` as its
+negation (i.e. the `restartable` but NOT `skippable` ones), and fails on any that
+is not in a per-module ignore-list. Finalize each Kotlin compile with it so the
+report is always fresh:
+
+```kotlin
+val checkComposeStability by tasks.registering(ComposeStabilityCheck::class) {
+    reportDir.set(layout.buildDirectory.dir("compose-metrics"))
+    ignoreFile.set(layout.projectDirectory.file("compose-stability-ignore.txt"))
+}
+tasks.withType<KotlinCompile>().configureEach {
+    finalizedBy(checkComposeStability)
+}
+```
+
+The ignore-list file holds fully-qualified composable names that are accepted
+exceptions (a composable that takes a third-party unstable type you cannot
+annotate). Each line is one accepted composable; anything unskippable and not
+listed fails the build. The full `ComposeStabilityCheck` task with the report
+parser and ignore-list matching is in
+[references/patterns.md#compose-stability-gate](references/patterns.md#compose-stability-gate).
+
+The report is only emitted when the compiler runs, which is why the check is
+`finalizedBy` the compile rather than a standalone task: a cached compile with no
+report means nothing changed, and the check reads the last report.
+
+## Lint on diff
+
+Full lint across a large multi-module project is minutes of wall time; running it
+on every commit trains people to skip the hook. Split it: a fast pre-commit gate
+over only the changed files, and full analysis in CI.
+
+At commit time, feed the static analyzer (detekt or Android Lint) the diff:
+
+```bash
+CHANGED=$(git diff --cached --name-only --diff-filter=d -- '*.kt' '*.kts')
+[ -z "$CHANGED" ] && exit 0
+./gradlew detektDiff -PdetektInput="$CHANGED"
+```
+
+Wire `detektDiff` to accept a file list and set the detekt `source` to just those
+paths, so the analyzer never walks the whole tree at commit time. In CI, run the
+full `detekt` / `lint` task with the baseline so nothing escapes. The pre-commit
+hook and the `detektDiff` task definition are in
+[references/patterns.md#lint-on-diff](references/patterns.md#lint-on-diff).
+
+Keep the two consistent: the same ruleset and the same baseline file drive both
+the diff run and the full run, so a commit that passes the hook does not surprise
+the author in CI.
+
+## Screenshot validation task
+
+Screenshot tests are only a gate when a mismatch fails the build. Author the
+tests with the mechanics in `compose-testing`; here, register the verification
+task and put it on the `check` path.
+
+Expose a single umbrella task so CI and local calls agree:
+
+```kotlin
+tasks.register("verifyScreenshots") {
+    group = "verification"
+    dependsOn(tasks.matching { it.name == "verifyRoborazziDebug" })
+}
+tasks.named("check").configure { dependsOn("verifyScreenshots") }
+```
+
+Record and verify are separate entry points: `recordScreenshots` regenerates
+golden images (run deliberately, reviewed in the diff), `verifyScreenshots`
+compares and fails. Never let `verify` fall back to recording on a missing
+golden, or the gate passes on the very case it exists to catch. The record/verify
+task pair and the CI upload of diff images on failure are in
+[references/patterns.md#screenshot-validation-task](references/patterns.md#screenshot-validation-task).
+
+## Ratchet, do not wall
+
+The failure mode of every gate above is the same: set the bar higher than the
+codebase currently clears, and the team disables the gate instead of meeting it.
+A gate that is always red is worse than no gate, because it also hides the
+regressions it was meant to catch.
+
+Seed each gate at the current state and let it only tighten:
+
+- Coverage: set `minBound` to the value measured today, then raise it in small
+  steps as tests land. Never open at a round aspirational number.
+- Compose stability: seed the ignore-list with every composable currently
+  unskippable, so the gate passes on day one and only new offenders fail. Shrink
+  the list over time; adding to it needs review.
+- Lint: generate a baseline of existing findings; the gate fails only on new
+  ones. Regenerating the baseline to bury a fresh finding is a review smell.
+- Layers: if a forbidden edge exists today, either fix it before turning the gate
+  on, or record it as a temporary allowed exception with a tracking reference,
+  never widen the whole allow-matrix.
+
+A ceiling that only moves down (ignore-lists, baselines) and a floor that only
+moves up (coverage) is the shape that survives contact with a real team.
+
+## Wiring gates into check
+
+Gates that are not on a lifecycle path do not run. Attach each to `check` (or a
+custom `qualityGates` aggregate task that `check` depends on) so a single
+`./gradlew check` runs every gate, and CI needs no bespoke task list.
+
+```kotlin
+val qualityGates by tasks.registering {
+    group = "verification"
+    dependsOn(
+        "checkLayerDependencies",
+        "checkComposeStability",
+        "verifyScreenshots",
+    )
+}
+tasks.named("check").configure { dependsOn(qualityGates) }
+```
+
+Keep the expensive, environment-dependent gates (instrumented coverage, full
+lint) behind properties so `check` stays usable locally, and turn them on in CI
+via `-P` flags. The full convention-plugin assembly that registers all gates is
+in [references/patterns.md#wiring-gates-into-check](references/patterns.md#wiring-gates-into-check).
+
+## Do's and Don'ts
+
+- Do author every gate in a `build-logic` convention plugin, applied per module.
+- Do make failure messages name the offender, the actual value, and the required
+  value.
+- Do capture configuration values (dependency paths, file lists) into locals at
+  configuration time for configuration-cache compatibility.
+- Do seed ignore-lists and baselines from the current state so the gate opens
+  green.
+- Don't verify coverage per module; aggregate, then verify once.
+- Don't let a screenshot `verify` task record missing goldens.
+- Don't set a floor above what the code clears today; a permanently red gate gets
+  switched off.
+- Don't duplicate the gate logic across module build files.
+- Don't run full lint at commit time; run it on the diff, full in CI.
+
+## Ownership Map
+
+This skill owns build-failing quality-gate tasks. It does not re-explain:
+
+- Typed `BuildConfig`, convention-plugin composition, version catalog, and
+  general build setup -> `gradle-kotlin-dsl`.
+- Authoring Compose screenshot tests, semantic matchers, and ViewModel tests ->
+  `compose-testing` (this skill only registers the verification task).
+- Codegen `--check` CI verification of generated design-token sources ->
+  `android-design-tokens-codegen`.
+
+## Review Checklist
+
+- [ ] Each gate lives in a convention plugin, not copied per module.
+- [ ] Layer gate derives layer from convention, governs new modules automatically.
+- [ ] Coverage uses a single aggregation report with one `verify` bound, gated by
+      a property.
+- [ ] Compose stability report points at a build dir, check is `finalizedBy` the
+      compile, ignore-list holds accepted exceptions only.
+- [ ] Lint runs on the diff at commit time, full with baseline in CI.
+- [ ] Screenshot `verify` fails on missing/changed goldens, never records.
+- [ ] Every gate is reachable from `check`; expensive ones sit behind `-P` flags.
+- [ ] Floors seeded at current state; ignore-lists/baselines only ratchet down.
+- [ ] Failure messages are actionable (offender + actual + required).