@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/core/google-play-compliance/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: google-play-compliance
+language: en
+description: "Google Play Store publication compliance — bundletool + aapt2 + apksigner orchestration + 21-rule policy catalog with Play Console error codes + humanizer templates. Consumed by: /multi-agent:test 'store-ready' (primary dispatch), Phase 4 Security Auditor (catalog cross-ref on AndroidManifest / build.gradle / proguard / signing diffs), /multi-agent:review (PR citation), /multi-agent:channels (PR body auto-augmentation). Wiring enforced by smoke-compliance-skills.sh."
+user-invocable: true
+argument-hint: '[bundle-path] [--threshold=error|warning|info] [--format=markdown|json] [--lang=en|tr]  — no-arg: picks most recent .aab from app/build/outputs/bundle/release/'
+---
+
+# google-play-compliance — Google Play Store Publication Compliance Skill
+
+Pre-submission compliance check for Android App Bundle (`.aab`) and APK artifacts. Unlike the iOS side (single MCP-tool wrapper around `ios_app_store_audit`), Android has **no single official scanner** — this skill orchestrates Google's own tools (`bundletool`, `aapt2`, `apksigner`, `adb`) plus a curated policy catalog to produce an equivalent pre-flight report.
+
+**The catalog is the value.** The 21-rule knowledge base reflects current Google Play policies (target API requirements, 64-bit enforcement, data safety rules, permission policies). Tool invocations gather the evidence; this skill maps it against policy and humanizes.
+
+## Primary consumers
+
+| Consumer | How it uses this skill |
+|---|---|
+| `/multi-agent:test "store-ready"` (Android) | Main entry point — runs the tools, renders the full report |
+| Phase 4 Security Auditor (Android review) | Reads the rule catalog for cross-reference when diff touches AndroidManifest.xml, gradle config, or signing |
+| `/multi-agent:review` | On Android diffs, cites Play policy refs next to flagged changes (e.g. new `MANAGE_EXTERNAL_STORAGE` without justification) |
+| `/multi-agent:channels` | When PR is release-relevant, appends compliance warnings to PR body |
+
+## Dispatch
+
+### Prerequisite detection
+
+```bash
+MISSING=()
+command -v bundletool >/dev/null 2>&1 || MISSING+=("bundletool")
+command -v aapt2 >/dev/null 2>&1 || MISSING+=("aapt2")
+command -v apksigner >/dev/null 2>&1 || MISSING+=("apksigner")
+command -v jq >/dev/null 2>&1 || MISSING+=("jq")
+
+# bundletool may not be on PATH — check common locations
+if [ -z "$(command -v bundletool)" ]; then
+  for candidate in /opt/homebrew/bin/bundletool /usr/local/bin/bundletool "$HOME/Library/bundletool.jar"; do
+    [ -x "$candidate" ] || [ -f "$candidate" ] && BUNDLETOOL="$candidate" && break
+  done
+fi
+
+if [ "${#MISSING[@]}" -gt 0 ]; then
+  echo "Missing tools: ${MISSING[*]}"
+  echo ""
+  echo "Install options:"
+  echo "  brew install bundletool aapt2"
+  echo "  # aapt2 + apksigner also ship with Android SDK Build-Tools:"
+  echo "  #   \$ANDROID_HOME/build-tools/<version>/"
+  echo "  brew install jq"
+  exit 2
+fi
+```
+
+### Bundle resolution
+
+```bash
+BUNDLE_PATH="$1"
+if [ -z "$BUNDLE_PATH" ]; then
+  # No arg → find recent .aab files in gradle output dirs
+  RECENT=$(find . -maxdepth 6 -path '*/build/outputs/bundle/release/*.aab' -type f 2>/dev/null | \
+           xargs -I{} stat -f '%m %N' {} 2>/dev/null | sort -rn | head -5 | cut -d' ' -f2-)
+  if [ -z "$RECENT" ]; then
+    echo "No .aab found. Build one: ./gradlew bundleRelease"
+    exit 2
+  fi
+  echo "Recent bundles:"
+  echo "$RECENT" | nl -w2 -s'. '
+  read -p "Select [1-5, enter=1]: " PICK
+  PICK=${PICK:-1}
+  BUNDLE_PATH=$(echo "$RECENT" | sed -n "${PICK}p")
+fi
+
+if [ ! -f "$BUNDLE_PATH" ]; then
+  echo "Bundle not found: $BUNDLE_PATH"
+  exit 2
+fi
+```
+
+### Invocation (evidence gathering)
+
+```bash
+TMPDIR=$(mktemp -d -t play-compliance-XXXX)
+trap "rm -rf $TMPDIR" EXIT
+
+# 1. Bundle validation (bundletool)
+bundletool validate --bundle="$BUNDLE_PATH" > "$TMPDIR/bundle-validate.txt" 2>&1 || true
+
+# 2. Base manifest extraction
+bundletool dump manifest --bundle="$BUNDLE_PATH" > "$TMPDIR/manifest.xml" 2>&1
+
+# 3. Build universal APK for scanning
+bundletool build-apks --bundle="$BUNDLE_PATH" --mode=universal --output="$TMPDIR/universal.apks" 2>/dev/null
+unzip -o -q "$TMPDIR/universal.apks" -d "$TMPDIR/apks/" 2>/dev/null
+UNIVERSAL_APK="$TMPDIR/apks/universal.apk"
+
+# 4. APK metadata via aapt2
+aapt2 dump badging "$UNIVERSAL_APK" > "$TMPDIR/badging.txt" 2>&1
+aapt2 dump permissions "$UNIVERSAL_APK" > "$TMPDIR/permissions.txt" 2>&1
+aapt2 dump xmltree "$UNIVERSAL_APK" --file AndroidManifest.xml > "$TMPDIR/xmltree.txt" 2>&1
+
+# 5. Signature verification via apksigner
+apksigner verify --verbose "$UNIVERSAL_APK" > "$TMPDIR/signature.txt" 2>&1 || true
+
+# 6. Native ABI check
+unzip -l "$UNIVERSAL_APK" | grep 'lib/' > "$TMPDIR/native-libs.txt" || true
+
+# Now run the 21 rules against the gathered evidence (see Rule catalog below)
+# Output: /tmp/play-compliance-$$.json
+```
+
+## 21-Rule Policy Catalog
+
+Current Google Play policies + Play Console rejection codes. Sourced from `support.google.com/googleplay/android-developer/` — verify against current Play Console for the most up-to-date target API thresholds (they advance yearly).
+
+### A. Technical requirements (bundle / manifest)
+
+| # | ruleID | Play ref | What it checks | Default severity |
+|---|---|---|---|---|
+| 1 | `target-api-level` | Policy — Target API | `android:targetSdkVersion` ≥ 34 for new apps (Aug 2024+), ≥ 34 for updates (Nov 2024+). Lower → rejected. | error |
+| 2 | `native-64bit` | Policy — 64-bit | Every native `.so` has an `arm64-v8a` counterpart. `armeabi-v7a`-only rejected since Aug 2019. | error |
+| 3 | `app-bundle-format` | Policy — AAB | New apps must ship `.aab`. `.apk` uploads rejected on new apps since Aug 2021. | error |
+| 4 | `base-module-size` | Platform limit | Base APK from bundle ≤ 150 MB (bundletool `--mode=universal` size). Beyond → rejected. | error |
+| 5 | `package-visibility` | Android 11+ | If `targetSdkVersion ≥ 30` and code queries other packages, `<queries>` must be declared in manifest. | warning |
+| 6 | `foreground-service-types` | Android 14 | Every `<service android:foregroundServiceType="..."/>` type must match runtime usage. Missing = policy violation. | error |
+
+### B. Security
+
+| # | ruleID | Play ref | What it checks | Default severity |
+|---|---|---|---|---|
+| 7 | `app-signing` | Play App Signing | Signed with at least v2 scheme (apksigner verify --min-sdk-version). Enrollment in Play App Signing recommended. | error |
+| 8 | `cleartext-traffic` | Policy — Security | `android:usesCleartextTraffic="false"` OR Network Security Config explicitly lists cleartext domains. | warning |
+| 9 | `exported-components` | Android 12+ | Every `<activity>` / `<service>` / `<receiver>` with `<intent-filter>` must explicitly declare `android:exported="true"`. Missing → build fail on API 31+. | error |
+| 10 | `proguard-mapping` | — | Release build has `mapping.txt` (upload to Play Console for deobfuscation). `minifyEnabled = false` on release = warning. | warning |
+
+### C. Privacy / data
+
+| # | ruleID | Play ref | What it checks | Default severity |
+|---|---|---|---|---|
+| 11 | `dangerous-permissions` | Policy — Permissions | Every dangerous permission (`MANAGE_EXTERNAL_STORAGE`, `SYSTEM_ALERT_WINDOW`, `REQUEST_INSTALL_PACKAGES`, `PACKAGE_USAGE_STATS`, `QUERY_ALL_PACKAGES`) has justification in Play Console. | error |
+| 12 | `advertising-id` | Policy — Ad ID | If AdMob / advertising ID used (manifest `com.google.android.gms.permission.AD_ID`), must be declared in Data Safety form. Targeting API 33+ requires `AD_ID` permission. | warning |
+| 13 | `background-location` | Policy — Location | `ACCESS_BACKGROUND_LOCATION` declared → Play Console background location justification required (policy revoke risk). | error |
+| 14 | `data-safety-consistency` | Policy — Data safety | Manifest-declared permissions match Data Safety form (drift audit — manual; this rule flags permissions likely to trigger form updates). | warning |
+| 15 | `sensitive-permission-special-access` | Policy — Sensitive | `READ_SMS`, `RECEIVE_SMS`, `READ_CALL_LOG`, `WRITE_CALL_LOG`, `READ_CONTACTS`, `PROCESS_OUTGOING_CALLS` require special access from Play Console (Default handler use case). | error |
+
+### D. Release hygiene
+
+| # | ruleID | Play ref | What it checks | Default severity |
+|---|---|---|---|---|
+| 16 | `debug-tool-leak` | — | Release APK contains `com.squareup.leakcanary`, `com.facebook.stetho`, `com.github.chuckerteam.chucker`, `com.jakewharton.pidcat`, `com.github.anrwatchdog` (and variants) in DEX/META-INF. | error |
+| 17 | `log-statements` | — | Release APK has `Log.d` / `Log.v` / `Timber.d` call sites in bytecode. Should be stripped via ProGuard rules or build-type conditional. | warning |
+| 18 | `mock-endpoints` | — | Release APK manifest / resources contain dev/staging URL literals or test API key patterns (`dev.`, `staging.`, `test-api-key`, `Bearer test_`). | warning |
+| 19 | `minify-enabled` | Build config | Release build-type has `minifyEnabled = true` and `shrinkResources = true`. Both off = warning (size + deobfuscation impact). | warning |
+| 20 | `version-code-progression` | Platform req | `versionCode` in this bundle > last published versionCode on Play (requires Play Console API lookup or user-provided last version). | warning |
+| 21 | `app-links-verification` | Digital Asset Links | `<intent-filter android:autoVerify="true">` domains have reachable `/.well-known/assetlinks.json`. | info |
+
+## Severity mapping for consumers
+
+| Severity | What pipeline consumers do with it |
+|---|---|
+| `error` | **Blocker.** Play Console will reject the upload (or the bundle build will fail). Report as `blocking` in Phase 4 triage / channels PR body. |
+| `warning` | **Policy review risk.** Might not reject immediately but increases manual review chance + user trust hit. Surface in PR description. |
+| `info` | **Best practice.** Log only. Don't pollute PR body. |
+
+## Humanizer templates
+
+### EN (default; `--lang=en` or no flag — `promptLanguage` is locked to `"en"`)
+
+```markdown
+## Google Play Pre-flight Report
+
+**Bundle:** {bundleName} · **Scanned:** {timestamp}
+**Target API:** {targetSdkVersion} · **Min API:** {minSdkVersion} · **Version:** {versionName} (code {versionCode})
+**Status:** {passed ? "✅ All gates passed" : "❌ {errorCount} blocker(s), {warningCount} warning(s)"}
+
+### Blockers (Play Console will reject)
+{for each violation with severity=error, grouped by ruleID}
+
+#### `{ruleID}` — Play {playRef ?? "internal rule"}
+- **What:** {message}
+- **Where:** `{file}` {line ? "(line " + line + ")" : ""}
+- **Fix:** {suggestion ?? "See rule catalog"}
+
+### Warnings (increases review risk)
+{same format, severity=warning}
+
+### Informational
+{collapsible block, severity=info}
+
+---
+Ran via bundletool + aapt2 + apksigner — full JSON: /tmp/play-compliance-{pid}.json
+```
+
+### TR (explicit `--lang=tr` opt-in only)
+
+```markdown
+## Google Play Pre-flight Raporu
+
+**Bundle:** {bundleName} · **Tarandı:** {timestamp}
+**Target API:** {targetSdkVersion} · **Min API:** {minSdkVersion} · **Versiyon:** {versionName} (code {versionCode})
+**Durum:** {passed ? "✅ Tüm kontroller geçti" : "❌ {errorCount} blocker, {warningCount} uyarı"}
+
+### Bloker'lar (Play Console reject eder)
+{for each violation with severity=error, grouped by ruleID}
+
+#### `{ruleID}` — Play {playRef ?? "iç kural"}
+- **Ne:** {message}
+- **Nerede:** `{file}` {line ? "(satır " + line + ")" : ""}
+- **Çözüm:** {suggestion ?? "Kural katalogu'na bak"}
+
+### Uyarılar (review riski artırır)
+{same format, severity=warning}
+
+### Bilgi
+{collapsible block, severity=info}
+
+---
+bundletool + aapt2 + apksigner üzerinden tarandı — tam JSON: /tmp/play-compliance-{pid}.json
+```
+
+**Important:** `ruleID` + policy refs are NOT translated — global identifiers. Only `message`, `suggestion`, and section headings are humanized.
+
+## Integration patterns
+
+### `/multi-agent:test "store-ready"` (primary)
+
+sim-test.md's "store-ready" scenario on Android:
+1. Platform detect: `build.gradle` / `build.gradle.kts` present → Android
+2. Load this skill
+3. Follow Dispatch section — gather evidence via bundletool + aapt2 + apksigner
+4. Apply 21 rules against gathered evidence
+5. Render humanizer template per `--lang` flag (default `en`; `promptLanguage` is locked to `"en"`)
+6. Exit with `1` if any blockers, `0` otherwise (CI-friendly)
+
+### Phase 4 Security Auditor (optional, on-demand)
+
+When reviewing an Android PR, if diff touches ANY of:
+- `**/AndroidManifest.xml` (permissions / exported / targetSdk)
+- `**/build.gradle(.kts)` (signingConfig / minifyEnabled / targetSdkVersion)
+- `**/proguard-rules.pro`
+- `**/network_security_config.xml`
+
+then the reviewer **loads this skill's catalog** (not the tool chain) and cross-references flagged changes with the `ruleID` / Play ref table. Tool invocation is NOT required for diff review — just the catalog.
+
+### `/multi-agent:review` (opportunistic)
+
+On Android diffs, reviewer agent annotates new/changed permissions with their policy refs from the catalog (e.g. `MANAGE_EXTERNAL_STORAGE` → "Policy — Permissions, requires Play Console justification").
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `[bundle-path]` | Positional — specific `.aab` to scan. No arg → picker from recent `bundleRelease` outputs. |
+| `--threshold=error\|warning\|info` | Filter — default `info` (all). `error` = blockers only. |
+| `--format=markdown\|json` | Default `markdown` (humanized). `json` passes raw rule output. |
+| `--lang=en\|tr` | Humanizer output language for this run (default `en`; `promptLanguage` is locked to `"en"`, so `--lang=tr` is the only way to opt into Turkish). |
+| `--auto-pick` | Skip bundle picker, use most recent. |
+| `--last-version-code=N` | Supply last-published versionCode for `version-code-progression` rule (no Play Console lookup). |
+
+## Error handling
+
+| Condition | Behavior |
+|---|---|
+| bundletool / aapt2 / apksigner missing | Print brew / SDK install instructions, exit 2 |
+| No .aab found | Print `./gradlew bundleRelease` hint, exit 2 |
+| Bundle validate fails | Report as `bundletool-validate` blocker rule, continue other rules (best-effort) |
+| Universal APK build fails | Skip rules that need APK inspection (native-64bit, debug-tool-leak, log-statements); report partial set with note |
+| apksigner verify fails | Still report — `app-signing` rule fires as blocker |
+| `--lang` value invalid (not `en`/`tr`) | Fall back to `en`, log warning |
+
+## Examples
+
+### Primary: `/multi-agent:test "store-ready"`
+
+```
+# Full report on most recent bundle (auto-pick)
+/multi-agent:test "store-ready" --auto-pick
+
+# Specific .aab, blockers only, Turkish
+/multi-agent:test "store-ready" app/build/outputs/bundle/release/app-release.aab --threshold=error --lang=tr
+
+# Supply last version code for progression check
+multi-agent-test "store-ready" --last-version-code=142 --auto-pick
+
+# Raw JSON for CI
+/multi-agent:test "store-ready" --format=json --auto-pick
+```
+
+### Phase 4 Security Auditor (catalog cross-ref, no tool invocation)
+
+When a Phase 4 review diff touches Android release-relevant paths (`AndroidManifest.xml`, `build.gradle(.kts)`, `proguard-rules.pro`, `network_security_config.xml`), the security-auditor persona loads this skill's 21-rule policy catalog and cites matching ruleIDs next to its findings. No bundletool / aapt2 / apksigner invocation at review time — catalog reads are free.
+
+```
+# Example finding from Phase 4 Security Auditor (wired in v5.8.1):
+[BLOCKING] AndroidManifest.xml: new MANAGE_EXTERNAL_STORAGE permission added
+  (google-play-compliance / dangerous-permissions — Policy — Permissions)
+  File: app/src/main/AndroidManifest.xml:12
+  Fix: Remove the permission or add Play Console justification before submitting.
+       MANAGE_EXTERNAL_STORAGE triggers mandatory policy review on every update.
+```
+
+### `/multi-agent:review` (PR citation)
+
+```
+# Standard review — auto-loads Google catalog when diff touches Android release files
+/multi-agent:review
+
+# Review a specific branch
+/multi-agent:review feature/PROJ-67890-file-manager
+```
+
+Findings in the review report carry the same `(google-play-compliance / <ruleID> — <Play ref>)` format as Phase 4 — the review command reuses the catalog contract.
+
+### `/multi-agent:channels` (PR body auto-augmentation)
+
+```
+# Run the compliance scan first so its JSON lands in /tmp
+/multi-agent:test "store-ready" --auto-pick --last-version-code=142
+
+# Then deliver the report — channels auto-appends a Store compliance section
+#   to the PR body / Jira comment / Confluence page if the cache is < 6h old
+#   and at least one blocker or warning was found.
+/multi-agent:channels PROJ-67890 --channels pr,jira
+```
+
+The appended section is structured:
+
+```markdown
+### Store compliance
+
+⚠️ 3 blocker(s), 2 warning(s) — run /multi-agent:test "store-ready" for the full report.
+
+- `target-api-level` — Policy — Target API: targetSdkVersion = 33 but Play Console requires ≥ 34 for updates
+- `native-64bit` — Policy — 64-bit: lib/armeabi-v7a/libfoo.so has no arm64-v8a counterpart
+- `foreground-service-types` — Android 14: <service> missing android:foregroundServiceType
++ 2 more
+```
+
+## Notes
+
+- **Policy thresholds change yearly.** Target API level (currently 34) advances each August for new apps / November for updates. When a new Android version ships, update Rule #1 `target-api-level` with the new threshold.
+- **Not a substitute for Play Console pre-launch report.** This skill catches static issues (manifest, signing, size, debug tools). Dynamic issues (crashes, ANRs, security vulnerabilities) require Play Console's own pre-launch testing on real devices.
+- **Data Safety form audit is partial.** Rule #14 flags manifest permissions that commonly trigger form updates, but the actual form lives in Play Console and can't be fully cross-checked without the Play Developer API.
+
+## Version history
+
+- **v5.8.0** — Skill introduced. Orchestrates bundletool + aapt2 + apksigner, 21-rule catalog, EN+TR humanizer. Primary consumer only (`/multi-agent:test "store-ready"`).
+- **v5.8.1** — 3 additional consumer surfaces wired (Phase 4 Security Auditor cross-ref, `/multi-agent:review` citation, `/multi-agent:channels` PR-body auto-augmentation). Regression-locked by `smoke-compliance-skills.sh` (45 assertions).
+- **v6.0.0** — `language: en` frontmatter tag; 4-consumer Examples section expanded.