@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

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).