@mmerterden/multi-agent-pipeline 12.10.0 → 13.0.0

package/pipeline/skills/shared/core/multi-agent-testflight-validation/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: multi-agent-testflight-validation
+language: en
+description: "Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --validate-app`, and a Review-Guidelines check. ITMS codes are mapped to the rule each implies. Validates only, never uploads. Use when a build is about to go to TestFlight, or a submission was rejected and you need why."
+user-invocable: true
+argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --resume"
+---
+
+# multi-agent-testflight-validation  -  pre-submission validation
+
+Catch, before you upload, what App Store Connect would send back after you do.
+
+**Local-only**: no commits, no push, no PR, no channels. **It never uploads**  -  only
+`--validate-app` is ever invoked, never `--upload-app`.
+
+## Why three gates
+
+Each sees something the others structurally cannot, so reporting one as "the check"
+is how a build passes locally and gets rejected anyway.
+
+| Gate | Runs | Needs | Sees | Blind to |
+|---|---|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules) | `.xcarchive` | privacy manifest, required-reason API, Info.plist, signing, entitlements, embedded SDK, IPv6, debug leak | anything account-dependent |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | `.ipa` + credentials | unregistered bundle ID, profile/app-record mismatch, **version+build already used**, entitlement not provisioned | the Review Guidelines |
+| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT, privacy policy, account deletion, IAP, purpose-string wording | anything not in source |
+
+Most "we passed validation and still got rejected" cases are Gate 3 findings:
+Apple's validator does not read the Review Guidelines.
+
+## Flow
+
+**0. Input.** `(empty)` → ask · `my-ios-app`/path → that repo · `--ipa=<path>` →
+Mode B without Gate 1 · `--archive=<path>` → Mode B with all gates · `--resume`.
+State at `~/.claude/logs/multi-agent/<task_id>/agent-state.json`,
+`taskId = TFV-<repo>-<yyyymmddHHMM>`. Register phases with
+`bash ~/.copilot/scripts/phase-tracker.sh` and render with
+`phase-tracker.sh render` at every boundary.
+
+**1. Pickers.** Repo (iOS entries in `prefs.projects`; a single match auto-resolves,
+and the breadcrumb says so) → branch → mode. Print
+`Step <i>/<n>: <what this decides>` for each. On `git fetch` failure do **not**
+silently use a cached ref, and **classify the failure before naming a cause**:
+`could not read Password` / `Authentication failed` / `403` is a credential
+problem, not a network one, and a VPN cannot fix it; `Could not resolve host` /
+`Operation timed out` is the network. Show the stderr line verbatim next to your
+classification, then offer the remedy that matches it. Only the network case gets
+the continue-on-a-stale-ref option: for a credential failure, staleness is
+unrelated to what broke.
+
+**2. Pre-flight.** `xcrun --find altool` and `xcodebuild -version`; a missing
+prerequisite halts. Resolve credentials and name the active tier in the report:
+tier 1 ASC API key (key id + issuer id from the keychain via
+`prefs.global.keychainMapping`, `.p8` at
+`~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8`), tier 2 Apple ID +
+app-specific password by keychain reference, tier 3 none → **Gate 2 is `SKIPPED`
+and the verdict line says so**. Credentials come from `/multi-agent:setup`; never
+prompt for a secret value in chat. Tier 2 needs no elevated App Store Connect
+role, which matters when API-key creation is not permitted on the account.
+
+**3. Obtain the build.**
+- Mode B `.xcarchive` → Gate 1 runs; export with `ios_export_ipa` to reach Gate 2.
+- Mode B `.ipa` only → **Gate 1 `SKIPPED (needs .xcarchive)`**. The static audit
+  reads archive structure an `.ipa` does not carry. Do not present a two-gate run
+  as a full pass.
+- Mode A → worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` (**never under
+  `$HOME`**) → `ios_xcodebuild({action: "archive", configuration: "Release",
+  destination: "generic/platform=iOS"})`  -  the simulator default would produce a
+  non-distributable archive  -  then `ios_export_ipa({method:
+  "app-store-connect", team_id, ...})`. Leave `allow_provisioning_updates` off
+  unless asked: it lets xcodebuild create or modify profiles in the developer
+  account, which a validation run has no business doing.
+
+**4. Gate 1.** `ios_app_store_audit({archive_path, rules: "all"})`. `error` blocks,
+`warning` advises. Keep each ITMS code  -  Gate 2 may return the same one, and that
+agreement tells the user it is real.
+
+**5. Gate 2.** `ios_testflight_validate({ipa_path, platform: "ios", <creds>})`.
+Render the verdict as returned: `PASS` / `FAIL` (each issue with ITMS code, mapped
+guideline, hint) / `SKIPPED` (with the reason, **never as a pass**). This is the
+only gate that catches an already-used build number  -  the most common wasted
+upload  -  so when it fails on that, name the next free build number.
+
+**6. Gate 3.** Load `app-store-review` and check, with an evidence path each:
+purpose strings (present, specific, matching actual use) · `PrivacyInfo.xcprivacy`
+(exists, declares required-reason APIs, matches linked SDKs) · ATT before any
+tracking · in-app account deletion when accounts are created · privacy policy
+reachable · IAP through StoreKit with no external purchase path · Sign in with
+Apple alongside third-party social login. Mark `pass` / `fail` /
+`not-applicable`, and `not-applicable` needs a reason  -  an unexamined area is not
+a pass.
+
+**7. Report.** `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` plus a
+printed summary:
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Build:   <path>  ·  <bundle id> <version> (<build>)
+Auth:    tier <1|2|none>  ·  <method>
+
+Gate 1  static audit        PASS | FAIL (<n> blocking, <n> advisory) | SKIPPED (<reason>)
+Gate 2  Apple validation    PASS | FAIL (<n> issues) | SKIPPED (<reason>)
+Gate 3  guideline review    PASS | FAIL (<n> findings) | <n> not-applicable
+
+Blocking  -  fix before uploading
+  [ITMS-90683] Info.plist: NSCameraUsageDescription missing
+      guideline 5.1.1 Data Collection and Storage
+      <hint>  ·  <file:line>
+
+Not run
+  Gate 1: needs an .xcarchive; only an .ipa was supplied
+```
+
+A skipped gate is never folded into the pass count. Every blocking finding carries
+a file path or an ITMS code. No AI or assistant attribution anywhere; real
+newlines, no HTML entities.
+
+**8. Offer, do not act.** Print the exact `xcrun altool --upload-app` command for
+when the gates are clear (uploading stays an explicit human act), plus
+`--resume` after fixes and `/multi-agent:fix-bug` for code-level Gate 3 findings.
+Never upload, never bump the build number, never commit.