@mmerterden/multi-agent-pipeline 14.1.1 → 14.2.1

package/CHANGELOG.md

@@ -16,6 +16,126 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [14.2.1] - 2026-07-30
+
+### Changed
+
+- **`testflight-validation` merged into a new `/multi-agent:store-ready`, and the
+  Android side brought to parity.** The iOS archive audit existed twice with
+  identical arguments  -  `ios_app_store_audit({archive_path, rules: "all"})` in the
+  command's Gate 1 and again inside `sim-test.md`'s `store-ready` scenario. Two
+  copies of one call is how the second door grew with no Gate 2, no Gate 3 and no
+  Android equivalent. There is now one implementation.
+  Gates are symmetric per platform, because the failure modes are: a malformed
+  package, a package the store itself refuses, and a policy a human enforces.
+
+  | Gate | iOS | Android |
+  |---|---|---|
+  | 1 Static | `ios_app_store_audit`, 18 rules | `android_apk_audit` + `google-play-compliance`, 21 rules |
+  | 2 Authoritative | `altool --validate-app` | `SKIPPED` |
+  | 3 Policy | `app-store-review` vs source | `play-store-review` vs source |
+
+  Gate 2's asymmetry is reported as an asymmetry rather than smoothed over: Play's
+  authoritative check exists only server-side, through a Publishing API draft edit,
+  and the pipeline ships no client for it. An Android run therefore clears at most
+  2 of 3 and never prints `passed`. `bundletool validate` is Gate 1 and is not
+  promoted to fill the hole.
+  The running-app sweep became Step A rather than a separate errand  -  a build can
+  be structurally perfect and still ship an unreadable screen  -  and it degrades to
+  `SKIPPED (no booted device)` instead of halting the package validation.
+
+  Nothing was removed. `testflight-validation` is a thin iOS-pinned alias (removing
+  a command is a breaking change to the slash-command surface), and
+  `test "store-ready"` still resolves, now as a hand-off. `sim-test.md` keeps only
+  the pointer, so a dark-mode run no longer loads altool and credential-tier prose
+  it never needs.
+
+### Added
+
+- **Four fixed-scenario `test-*` commands.** `/multi-agent:test-dark-mode`,
+  `:test-accessibility`, `:test-dynamic-type` and `:test-screenshots [locale]` pin a
+  scenario the quoted-tag form made you remember and quote. Typing `test-` now
+  autocompletes the matrix list instead of returning a single entry whose tags live
+  only in the help text. The scenario-tag form is unchanged and not deprecated -
+  each command is an alias for it, delegating to the same `sim-test.md`, so there is
+  one implementation and no forked logic. Same pattern the mode aliases already use
+  (`:dev-autopilot` = `--dev autopilot`).
+  `screenshot <lang>` became `test-screenshots [locale]` rather than
+  `test-screenshot-tr`: the locale is a parameter, and freezing one language into a
+  command name buys one command per language. `store-ready` deliberately got no
+  alias - it takes an optional archive path, and its 18-rule audit is the same one
+  `/multi-agent:testflight-validation` runs as its first gate, so the alias would
+  have advertised a second door onto a duplicate.
+
+### Fixed
+
+- **Copilot's `purge` could not see a single worktree.** It discovered them with
+  `find {repo}/.worktrees/ -name "agent-state.json"`, and no worktree carries that
+  file: Phase 0 writes state to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`.
+  Verified on a repo with two live task worktrees  -  the marker scan returns zero
+  while `purge.sh`'s own directory enumeration finds both. So the skill reported
+  "nothing to purge" as success with real worktrees on disk. The Claude Code command
+  had already been fixed by delegating to `purge.sh`; the Copilot mirror never
+  received that fix, which is the second time a repaired Claude-side surface left its
+  Copilot counterpart behind in this release.
+  It now delegates to the script and explicitly forbids re-introducing a
+  marker-file scan.
+- **The stale log location survived in four more places** after `clear-logs` was
+  redirected. `shared/core/multi-agent` told Phase 0 to create `agent-log.md` and
+  `agent-state.json` inside `.worktrees/PROJ-{id}/`, told `:resume` to look for state
+  there, and printed that path as the report location; `phase-0-init` said "create log
+  dir" without naming one, 49 lines above the line that does. All four now name
+  `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, the path the tracker,
+  `prune-logs.sh` and `:resume` actually read.
+  `status` and `log` keep their worktree scan as a legacy fallback: it finds nothing
+  on a current tree, but it is harmless and would still serve an old one.
+
+- **`clear-logs` scanned a path nothing writes to, and help advertised it as a
+  slash command that does not exist.** It looked for
+  `.worktrees/PROJ-*/agent-log.md` and `agent-state.json`; Phase 0 has written both
+  to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/` since the layout moved.
+  Against the current tree the scan matches zero files, so the op reported "logs
+  cleared, deleted 0" as success while every real log stayed on disk  -  worse than a
+  missing command, because it reads as done. There was also no `clear-logs` command
+  directory, so the `/multi-agent:clear-logs` entry in the Copilot help pointed at a
+  slash command that was never installed.
+  The name is kept as a redirect to `prune-logs` rather than deleted, so an existing
+  invocation lands somewhere correct. `prune-logs` and `garbage-collect` now appear
+  in the Copilot help, matching the Claude Code side. This is the `finish` → `ship`
+  class of drift the inventory gate's own comment describes, in the files that gate
+  does not parse.
+- **`sim-test.md` advertised two scenarios it never implemented.** `"biometric"` and
+  `"performance"` sat in the activation block with no implementation section, so
+  reaching either fell through to the general sweep and was reported as the scenario
+  asked for. Neither can be built symmetrically today: biometric has `ios_biometric`
+  and no Android counterpart, launch timing has `android_launch_time` and no iOS
+  counterpart, and the file auto-detects platform  -  so each would work on one
+  platform and silently do nothing on the other. Both rows are withdrawn with the
+  reason recorded in place, rather than shipped as half-features or left advertised.
+  Advertised scenarios and implemented sections now match one to one.
+- **`help` never documented two shipped commands.** `testflight-validation` and
+  `ios-coding-standard` existed in the tree, installed correctly, and appeared in no
+  block of `help/SKILL.md` in either language - `ios-coding-standard` was reachable
+  only because it also sat in `prefs.global.routines`, i.e. it read as a personal
+  routine rather than a first-party command. Both are now in the EN and TR Post-Hoc
+  sections. A command absent from help is a command nobody runs.
+- **Rule count drifted between the two language blocks.** The TR block advertised a
+  17-rule iOS store audit against the EN block's 18 and `ios_app_store_audit`'s
+  actual 18. The TR reader was being given a number no code produces.
+
+### Changed
+
+- **`DESC_CEILING` 78000 -> 81000**, with the paired pin in
+  `test/context-budget-gate.test.mjs` moved in the same commit, as that test
+  requires. Not a bump to silence a red gate: at 78000 the surface had **16 bytes**
+  of headroom, so any new command failed regardless of how tersely it was described,
+  while the gate's own average check sat at 320 against its 420 ceiling - the signal
+  that the tree grew rather than that descriptions are padded. The alternative was
+  shaving routing text off eight unrelated `shared/external` skills to fund four
+  commands, which trades a real capability for a cosmetic number. Both the gate and
+  the test now carry the ceiling's history inline so the next raise has to argue for
+  itself. Cost is honest: ~470 always-on tokens per run.
+
 ## [14.1.1] - 2026-07-30
 
 Three defects that all shared one shape: a name written in one place and read in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "14.1.1",
+  "version": "14.2.1",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/deploy.md

@@ -43,7 +43,10 @@ Run through the iOS deployment checklist before App Store submission.
 ### 6. Archive & Upload
 
 - [ ] Archive with Release configuration
-- [ ] Run App Store compliance scan: `/archive-guard <archive>` (uses `ios_app_store_audit` MCP tool)
+- [ ] Run pre-submission validation: `/multi-agent:store-ready --archive=<archive>`  -  three gates
+      (static audit, Apple's own `altool --validate-app`, guideline review vs source).
+      `/archive-guard <archive>` is the quick single-gate form when only the static
+      audit is wanted.
 - [ ] Upload via Xcode Organizer or `xcrun altool`
 - [ ] Verify in App Store Connect
 

package/pipeline/commands/multi-agent/SKILL.md

@@ -72,7 +72,7 @@ Lib scripts (`~/.claude/lib/`):
 | `log [id]` | Show task log |
 | `resume [id]` | Resume paused task |
 | `kill [id]` | Delete worktree (logs preserved). Confirm first |
-| `clear-logs` | Clean global log directory. Keep counter |
+| `clear-logs` | **Superseded  -  redirect, do not run.** Say so and route to `prune-logs`. It targeted `.worktrees/PROJ-*/agent-log.md`, a path nothing has written to since logs moved to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`; running it would report deleting nothing as success. |
 | `purge` | Worktree + logs + counter  -  full reset (double confirm) |
 | `review [#N\|repo#N\|PR-url\|branch]` | Parallel review of a PR or branch diff; with no input (interactive) lists open GitHub + Bitbucket PRs to multi-select. Posts per-finding inline comments + approve/needs-work on PRs. No worktree. |
 | `review-jira [KEY\|url]` | Grade a Jira issue's readiness for the pipeline (scope / AC / repro / design / API / stack), then post the gaps as a Jira comment. Read-only on code. |
@@ -82,6 +82,8 @@ Lib scripts (`~/.claude/lib/`):
 | `channels [PR-url\|#N\|Jira-url\|Jira-id] [--channels pr,jira,confluence,wiki] [--content normal,test,auto-diff,note] [--message "..."]` | Post task report to multi-select channels (PR description, Jira comment, Confluence page, Wiki pages) with multi-select content sources. Humanizer pass per-channel. Bitbucket PR updates use reviewer-preserving PUT. Phase 7 delegates to this command; also invocable post-hoc for fixes made outside the pipeline. No worktree. |
 | `create-jira ["desc"] [figma-url] [swagger-url]` | Create a standards-compliant Jira issue: asks the type (**Task** / **Bug** / **Story**), mines the project's recent same-type issues for conventions (summary format, labels, priority, test-scenario style), detects the active sprint, drafts from a standard template with auto-sizing sections (Design Reference / API Contract / Screenshots appear only when their source is given), asks about unknown fields, then full draft preview + explicit approval before create. No worktree, no commits. |
 | `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test/SKILL.md` delegate. |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots [locale]` | Fixed-scenario aliases for the four parameterless / single-parameter `test` scenarios, so the tag autocompletes instead of having to be quoted. Each delegates to the same `sim-test.md` with its scenario pinned; behaviour is identical to the quoted form, which is not deprecated. |
+| `store-ready [repo] [--archive=\|--ipa=\|--aab=\|--apk=] [--skip-sweep]` | Pre-submission store readiness for a built **package**, iOS and Android, local-only. Three symmetric gates per platform  -  static package audit, the store's own validator, policy review vs repo source  -  plus the running-app sweep as Step A. A skipped gate is never folded into the pass count, and an Android run clears at most 2 of 3 because Play's authoritative check is server-side only. Validates only, never uploads. `testflight-validation` is the iOS-pinned alias; `test "store-ready"` hands off here. |
 | `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
 | `design-check [scope]` | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module → mock-support feasibility gate (halts if unsupported) → **scenario inventory** (every launch arg / scenario case / scenario code / fixture / deep link becomes a countable target with file+line evidence) → scope resolve (empty = module, screen, `screen@variant`, target id, Figma URLs, `--resume`) → worktree Debug build + mock launch → drive EACH target by its own driver, capturing tap-reachable sub-states with it → per-variant pixel + px-spacing + typography + color compare → report (side-by-side + annotated overlay + stacked findings + fix prompt) exported to `~/DesignChecks/` as HTML + PDF (+ Confluence if enabled). **Coverage gate**: a target is audited or skipped with a concrete reason, else the run is reported INCOMPLETE with the missing ids. No commits, no CI. |
 | `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
@@ -113,7 +115,7 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | `help` | `$HOME/.claude/commands/multi-agent/help/SKILL.md` |
 | `channels` | `$HOME/.claude/commands/multi-agent/channels/SKILL.md` |
 | `sync` | `$HOME/.claude/commands/multi-agent/sync/SKILL.md` |
-| `clear-logs` | Handled inline  -  scan + delete agent-log.md/agent-state.json files |
+| `clear-logs` | Handled inline  -  redirect to `prune-logs`, see the routing note |
 | `review` | `$HOME/.claude/commands/multi-agent/review/SKILL.md` |
 | `review-jira` | `$HOME/.claude/commands/multi-agent/review-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
 | `review-issue` | `$HOME/.claude/commands/multi-agent/review-issue/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
@@ -136,10 +138,11 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | Token lookup needed | `$HOME/.claude/multi-agent-refs/keychain.md` |
 | Audit tools (Phase 5/6) | `$HOME/.claude/multi-agent-refs/audit-guide.md` |
 | `test` | `$HOME/.claude/commands/sim-test.md` (colon-form `/multi-agent:test` uses the delegate at `commands/multi-agent/test/SKILL.md`) |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots` | `$HOME/.claude/commands/sim-test.md`, scenario pinned by the command name (delegates at `commands/multi-agent/test-*/SKILL.md`) |
 | `manual-test` | `$HOME/.claude/commands/multi-agent/manual-test/SKILL.md` |
 | `design-check` | `$HOME/.claude/commands/multi-agent/design-check/SKILL.md` |
 
-**Modifier flags** (`--dev`, `--local`, `autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `clear-logs`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.
+**Modifier flags** (`--dev`, `--local`, `autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.
 
 **How**: After routing, `Read` the relevant file and follow its instructions. Only load what the current action needs.
 

package/pipeline/commands/multi-agent/help/SKILL.md

@@ -119,6 +119,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
   /multi-agent:refactor       Adapted best-practices + bug hunt + upstream-drift + dev-toolkit MCP research -> one plan, approval, dev + sync
+  /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Pre-submission store readiness,
+                              iOS + Android, local-only. Three symmetric gates per platform: static package audit,
+                              the store's own validator, policy review vs repo source. Plus the running-app sweep.
+                              A skipped gate is never counted as a pass. Validates only, never uploads.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  iOS-pinned alias of :store-ready, kept because it is
+                              the name you reach for when the target is TestFlight. Same three gates, one implementation.
+  /multi-agent:ios-coding-standard [module]  Audit an iOS module against the 99-rule coding-standard registry -> remediation
+                              plan + one-page onboarding summary -> hand off to dev / dev-local. Read-only, never edits source.
 
 Setup & Maintenance:
 
@@ -156,11 +164,22 @@ Interactive Launchers:
 UI Testing (standalone  -  not part of pipeline phases):
 
   /multi-agent:test                  Full simulator test (screenshot all screens)
-  /multi-agent:test "dark mode"      Dark mode bug test
-  /multi-agent:test "accessibility"  Accessibility audit (labels, tap targets, contrast)
-  /multi-agent:test "dynamic type"   Large text size test
-  /multi-agent:test "screenshot tr"  App Store screenshots in Turkish
-  /multi-agent:test "store-ready"    App Store guideline pre-flight check
+
+  Fixed-scenario commands  -  no quoting, and they autocomplete off `test-`:
+
+  /multi-agent:test-dark-mode        Dark mode bug test
+  /multi-agent:test-accessibility    Accessibility audit (labels, tap targets, contrast)
+  /multi-agent:test-dynamic-type     Large text size test
+  /multi-agent:test-screenshots [tr] App Store screenshot set in a locale (default tr)
+
+  The scenario-tag form still works and is not deprecated  -  each command above is
+  an alias for it.
+
+  /multi-agent:test "dark mode" | "accessibility" | "dynamic type" | "screenshot <lang>"
+
+  `store-ready` is NOT a UI test: it validates a built package, on iOS and Android,
+  through three gates per platform, and lives at /multi-agent:store-ready. The old
+  /multi-agent:test "store-ready" [path] tag still works and hands off there.
 
   Uses xcrun simctl / adb (native, no external app needed).
   Booted simulator/emulator required. Auto-detects bundle ID from project.
@@ -362,6 +381,14 @@ Post-Hoc & Side-Channel:
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
   /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift + dev-toolkit MCP araştırması -> tek plan, onay, dev + sync
+  /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Yükleme öncesi store hazırlığı,
+                              iOS + Android, yalnızca lokal. Platform başına 3 simetrik kapı: statik paket denetimi,
+                              store'un kendi doğrulayıcısı, kaynağa karşı politika incelemesi. Artı çalışan-app sweep'i.
+                              Atlanan kapı asla pass sayılmaz. Sadece doğrular, asla yüklemez.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  :store-ready'nin iOS'a sabitlenmiş alias'ı; hedef
+                              TestFlight olduğunda akla gelen isim olduğu için korunuyor. Aynı 3 kapı, tek implementasyon.
+  /multi-agent:ios-coding-standard [modül]  Bir iOS modülünü 99 kurallık kodlama-standardı registry'sine göre denetler -> düzeltme
+                              planı + tek sayfalık onboarding özeti -> dev / dev-local'e devreder. Read-only, kaynağı hiç düzenlemez.
 
 Setup & Maintenance:
 
@@ -399,11 +426,22 @@ Rutinler (kendi tekrar eden işlerin):
 UI Testing (standalone  -  pipeline fazlarından bağımsız):
 
   /multi-agent:test                  Tam simulator testi (tüm ekran screenshot'ları)
-  /multi-agent:test "dark mode"      Dark mode bug testi
-  /multi-agent:test "accessibility"  Erişilebilirlik denetimi (label/tap-target/kontrast)
-  /multi-agent:test "dynamic type"   Büyük metin boyutu testi
-  /multi-agent:test "screenshot tr"  App Store screenshot seti (Türkçe locale)
-  /multi-agent:test "store-ready"    App Store guideline pre-flight kontrolü
+
+  Sabit-senaryo komutları  -  tırnak gerekmez, `test-` ile autocomplete'e düşer:
+
+  /multi-agent:test-dark-mode        Dark mode bug testi
+  /multi-agent:test-accessibility    Erişilebilirlik denetimi (label/tap-target/kontrast)
+  /multi-agent:test-dynamic-type     Büyük metin boyutu testi
+  /multi-agent:test-screenshots [tr] Belirtilen dilde App Store screenshot seti (default tr)
+
+  Senaryo etiketli form çalışmaya devam eder, kaldırılmadı  -  yukarıdaki komutların
+  her biri onun alias'ı.
+
+  /multi-agent:test "dark mode" | "accessibility" | "dynamic type" | "screenshot <dil>"
+
+  `store-ready` bir UI testi DEĞİL: üretilmiş paketi platform başına üç kapıdan
+  geçirerek doğrular, iOS + Android, ve /multi-agent:store-ready altında. Eski
+  /multi-agent:test "store-ready" [path] etiketi çalışır ve oraya devreder.
 
   xcrun simctl / adb kullanır (harici app gerekmez).
   Booted simulator/emulator şart. Bundle ID proje'den otomatik algılanır.
@@ -458,7 +496,7 @@ Temel Özellikler:
   Multi-Repo       Repo başına worktree, repo başına identity, commit öncesi entegrasyon build'i
   Identity Routing Repo origin URL'sinden git kimliği seçimi (kurumsal vs kişisel)
   Issue Safety     Issue'lar asla auto-close edilmez (GitHub + Jira için 4 onay gerekir)
-  Store Compliance /multi-agent:test "store-ready"  -  iOS için 17 kurallık audit (ITMS / Privacy Manifest /
+  Store Compliance /multi-agent:test "store-ready"  -  iOS için 18 kurallık audit (ITMS / Privacy Manifest /
                    code signing / debug-tool leak / IPv6 / SDK list / vb.) + Android için 21 kurallık audit
   Bilingual        EN + TR  -  outputLanguage assistant açıklamasını değiştirir; promptLanguage en kilitli
 

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -116,7 +116,7 @@ These are the RECOMMENDED key names. When creating NEW keys, use these. But exis
 
 > Multi-agent setup onboards **both** Figma tokens because the pipeline's 3-tier Figma access chain (see `$HOME/.claude/rules/figma-pipeline.md`) uses them in priority order: Tier 1 = MCP (`figma_mcp`), Tier 2 = REST PAT (`figma`), Tier 3 = user screenshot fallback. Missing either token forces a downshift; missing both leaves Tier 3 as the only path. The Tier 2 logical key is `figma`, not `figma_pat`: `figma_pat` is the pre-v13.6 name that `migrate-prefs.mjs` consolidates away, and writing a new mapping under it means the next migration deletes it.
 
-> The four App Store Connect entries are **iOS-only and optional**: skip them all and the pipeline still works, it just reports Gate 2 of `/multi-agent:testflight-validation` as `SKIPPED` (never as a pass). They mirror the Figma 3-tier shape  -  Tier 1 = API key (`appstore_connect_key_id` + `appstore_connect_issuer_id`), Tier 2 = Apple ID + app-specific password (`appstore_connect_apple_id` + `appstore_connect_password_item`), Tier 3 = nothing configured. **Offer Tier 2 first when the user says they cannot create an API key**: creating one needs an Admin or App Manager role in App Store Connect, while an app-specific password is generated by the account holder at `appleid.apple.com` with no team permission at all. Two of these hold identifiers rather than secrets (key id, issuer id) and one holds a keychain ITEM NAME, not a password  -  they still go through the mapping layer so every credential is read the same way. Onboarding mechanics in Step 3b.
+> The four App Store Connect entries are **iOS-only and optional**: skip them all and the pipeline still works, it just reports Gate 2 of `/multi-agent:store-ready` as `SKIPPED` (never as a pass). They mirror the Figma 3-tier shape  -  Tier 1 = API key (`appstore_connect_key_id` + `appstore_connect_issuer_id`), Tier 2 = Apple ID + app-specific password (`appstore_connect_apple_id` + `appstore_connect_password_item`), Tier 3 = nothing configured. **Offer Tier 2 first when the user says they cannot create an API key**: creating one needs an Admin or App Manager role in App Store Connect, while an app-specific password is generated by the account holder at `appleid.apple.com` with no team permission at all. Two of these hold identifiers rather than secrets (key id, issuer id) and one holds a keychain ITEM NAME, not a password  -  they still go through the mapping layer so every credential is read the same way. Onboarding mechanics in Step 3b.
 
 **1c. Resolution logic (per service):**
 

package/pipeline/commands/multi-agent/store-ready/SKILL.md

@@ -0,0 +1,340 @@
+---
+description: "Pre-submission store readiness for a built package, iOS and Android, local-only. Three symmetric gates per platform: a static package audit, the store's own authoritative validation, and a policy review against repo source. Separate verdict per gate, a skipped gate never counted as a pass. Validates only, never uploads. Use when a build is about to go to TestFlight or a Play track, or when a submission was rejected and the reason is not obvious."
+description-tr: "Üretilmiş paketin yükleme öncesi store hazırlığı, iOS + Android, yalnızca lokal. Platform başına üç simetrik kapı: statik paket denetimi, store'un kendi doğrulayıcısı, ve kaynağa karşı politika incelemesi. Kapı başına ayrı verdict, atlanan kapı asla pass sayılmaz. Sadece doğrular, asla yüklemez."
+argument-hint: "[repo]  -  empty = pick; repo name or path; --ipa= | --archive= | --aab= | --apk=; --skip-sweep; --resume"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__dev-toolkit__ios_app_store_audit, mcp__dev-toolkit__ios_export_ipa, mcp__dev-toolkit__ios_testflight_validate, mcp__dev-toolkit__ios_xcodebuild, mcp__dev-toolkit__ios_xcresult, mcp__dev-toolkit__android_apk_audit, mcp__dev-toolkit__ios_screenshot, mcp__dev-toolkit__ios_get_ui_tree, mcp__dev-toolkit__ios_set_appearance, mcp__dev-toolkit__ios_set_content_size, mcp__dev-toolkit__android_screenshot, mcp__dev-toolkit__android_get_ui_tree, mcp__dev-toolkit__android_set_dark_mode, mcp__dev-toolkit__android_set_font_scale
+---
+
+# /multi-agent:store-ready  -  pre-submission validation, iOS + Android
+
+Catch, before you upload, what App Store Connect or the Play Console would send
+back after you do.
+
+**Local-only.** No commits, no push, no PR, no channels unless you ask at the end.
+A worktree, when one is needed, exists only to archive without touching your
+working tree.
+
+**It never uploads.** iOS runs `--validate-app`, never `--upload-app`. Android
+never commits a Play edit. A validation run must not be able to ship a build by
+accident.
+
+**Input**: $ARGUMENTS
+
+## Why three gates, and why the same three on both platforms
+
+Each gate sees something the others structurally cannot, and reporting one of them
+as "the check" is how a build passes locally and gets rejected anyway. The shapes
+are the same on iOS and Android because the failure modes are: a malformed package,
+a package the store itself refuses, and a policy a human enforces.
+
+| Gate | Sees | Blind to |
+|---|---|---|
+| **1. Static** | package structure, manifests, signing, declared APIs and SDKs | anything depending on the store account |
+| **2. Authoritative** | what the store's own validator says about this exact binary | written policy  -  no validator reads it |
+| **3. Policy** | consent flows, deletion paths, purchase routing, disclosures | anything not visible in source |
+
+### Gate matrix
+
+| Gate | iOS | Android |
+|---|---|---|
+| 1 Static | `ios_app_store_audit({archive_path, rules: "all"})`  -  18 rules with real ITMS codes. Needs an `.xcarchive`. Reference: `apple-archive-compliance` skill | `android_apk_audit` plus the `google-play-compliance` skill's 21 rules: `bundletool validate` + manifest dump, `aapt2 dump badging`, `apksigner verify`, ABI / native scan. Needs an `.aab` (an `.apk` narrows it, see Step 3) |
+| 2 Authoritative | `ios_testflight_validate({ipa_path, platform: "ios", <credentials>})` → `xcrun altool --validate-app`. Needs an `.ipa` + credentials | **No client shipped.** Play's authoritative check exists only server-side, through a Publishing API draft edit that is validated and then abandoned. The pipeline has no tool for it, so this gate reports `SKIPPED (no local Play validator)` and the report says so. Do not substitute `bundletool validate`  -  that is Gate 1 |
+| 3 Policy | `app-store-review` skill vs repo source | `play-store-review` skill vs repo source |
+
+Gate 2's asymmetry is real and is reported as an asymmetry, not smoothed over. On
+iOS it is the only gate that catches a version+build pair already used  -  the most
+common wasted upload. On Android nothing local reproduces it, so an Android run
+clears at most 2 of 3 gates and must never print `passed`.
+
+## Step 0  -  parse input, detect platform
+
+| Input | Meaning |
+|---|---|
+| (empty) | ask which repo (Step 1) |
+| `my-app` or a path | that repo |
+| `--archive=<path>` | iOS, build supplied; all three gates can run |
+| `--ipa=<path>` | iOS, build supplied; Gate 1 reports `SKIPPED (needs .xcarchive)` |
+| `--aab=<path>` | Android, build supplied; Gate 1 + 3 run |
+| `--apk=<path>` | Android; Gate 1 runs the subset that does not need a bundle, and says which rules it could not apply |
+| `--skip-sweep` | skip Step A, when no simulator / emulator is available or only the package matters |
+| `--resume` | continue the last run from its state file |
+
+Platform detection when no build flag is given:
+
+```
+cwd or repo contains .xcodeproj / .xcworkspace / Package.swift   -> iOS
+cwd or repo contains build.gradle / build.gradle.kts             -> Android
+both                                                            -> ask which
+neither -> halt: "store-ready needs an iOS or Android project"
+```
+
+State lives at `$HOME/.claude/logs/multi-agent/<task_id>/agent-state.json` with
+`taskId = SR-<repo>-<yyyymmddHHMM>`. Register phases with the tracker
+(`$HOME/.claude/multi-agent-refs/tracker-contract.md`) so `:resume` and `:status`
+work like any other run.
+
+## Step 1  -  pickers (native, always)
+
+Use `AskUserQuestion` for every step  -  never a numbered text menu. Questions and
+descriptions render in `prefs.global.outputLanguage`; `label` and `header` stay
+English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
+`Step <i>/<n>: <what this decides>` breadcrumb for each.
+
+1. **Repo**  -  from `prefs.projects` matching the detected platform. A single match
+   auto-resolves (say so in the breadcrumb, do not silently skip the step).
+2. **Branch**  -  the branch to validate. Resolution order:
+   - `git fetch --prune` first, capturing **stderr**. **If the fetch fails, do not
+     silently fall back to a cached ref**, and **classify before naming a cause**  -
+     the same rule as the `/multi-agent:dev` remote gate:
+
+     | stderr contains | Cause | Remedy |
+     |---|---|---|
+     | `could not read Password`, `Authentication failed`, `403` | credential | store the PAT in the credential helper or switch the remote to SSH. **A VPN cannot fix this**, and the base ref being stale is unrelated to what broke  -  do not offer the cached-ref fallback. |
+     | `Could not resolve host`, `Operation timed out`, `Connection refused` | network | retry / continue on the cached ref with an explicit warning / switch remote / abort, per `$HOME/.claude/multi-agent-refs/rules.md` |
+     | `Repository not found`, `404` | wrong remote | show `git remote -v` and ask |
+
+     Always print the observed stderr line next to the classification. Asserting
+     `unreachable (VPN/DNS)` for a missing-credential error that returns in under a
+     second sends the user to fix something that was never broken.
+   - Offer the current branch, the default branch, and any `release/*` /
+     `tkdevelop/*` heads.
+3. **Mode**  -  how the build is obtained:
+   - `Supply a build` (Mode B, default)  -  fastest, no signing needed in-run.
+   - `Build from this branch` (Mode A)  -  iOS needs a distribution certificate and
+     profile in the keychain; Android needs the release signing config. Takes as
+     long as a real release build.
+
+## Step 2  -  pre-flight, before anything expensive
+
+Report every line; a missing prerequisite is a halt, not a warning.
+
+**iOS:**
+
+```bash
+xcrun --find altool >/dev/null 2>&1 || echo "MISSING: altool (install Xcode)"
+xcodebuild -version | head -1
+```
+
+Then resolve credentials, and **state which tier is active in the report**:
+
+| Tier | Source | Effect |
+|---|---|---|
+| 1 | ASC API key  -  key id + issuer id from the keychain via `prefs.global.keychainMapping`, `.p8` at `~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8` | Gate 2 runs |
+| 2 | Apple ID + app-specific password, referenced as a keychain item | Gate 2 runs |
+| 3 | neither | **Gate 2 reports `SKIPPED`, and the run says so in the verdict line** |
+
+Multi-provider accounts need `--provider-public-id`. When it is not in prefs, run
+`ios_testflight_validate({list_providers: true})` once and ask which provider.
+
+**Android:**
+
+```bash
+command -v bundletool >/dev/null || echo "MISSING: bundletool"
+command -v aapt2      >/dev/null || echo "MISSING: aapt2 (Android SDK build-tools)"
+command -v apksigner  >/dev/null || echo "MISSING: apksigner (Android SDK build-tools)"
+```
+
+There is no credential tier to resolve: Gate 2 has no local client, so it is
+`SKIPPED` by construction rather than by configuration. Say which of the two it is
+ -  a user who thinks a credential would unlock it will go looking for one.
+
+Credentials come from `/multi-agent:setup`; never prompt for a secret value in
+chat.
+
+## Step A  -  running-app sweep (unless `--skip-sweep`)
+
+The gates read a package; this reads the app. A build can be structurally perfect
+and still ship an unreadable screen, so the sweep stays part of store readiness
+rather than being a separate errand.
+
+Requires a booted simulator / emulator. When none is available, report
+`Sweep: SKIPPED (no booted device)` and continue to the gates  -  never halt the
+package validation for it, and never silently omit the line.
+
+Delegate to the UI Bug Hunter flow (`$HOME/.claude/commands/sim-test.md`) for the
+mechanics, running the light + dark + large-text passes over every screen. Merge
+its findings into the single report at Step 7, severity-grouped alongside the gate
+findings.
+
+## Step 3  -  obtain the build
+
+### Mode B  -  a build you supply
+
+- **iOS `.xcarchive`** → Gate 1 runs on it. To reach Gate 2 the archive must be
+  exported, so run `ios_export_ipa` (see Mode A for the signing inputs).
+- **iOS `.ipa` only** → **Gate 1 is `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; say which gate did not run and why, and offer to re-run with the
+  archive.
+- **Android `.aab`** → Gate 1 runs in full.
+- **Android `.apk` only** → Gate 1 runs the rules that do not need a bundle and
+  **lists the rules it could not apply**. An `.apk` cannot answer bundle-level
+  questions (per-ABI splits, dynamic features, Play App Signing expectations).
+
+When no path is given, pick the newest artifact and print which one you picked:
+
+```
+iOS:     newest .xcarchive under ~/Library/Developer/Xcode/Archives/**
+Android: newest .aab under **/build/outputs/bundle/**/*.aab
+```
+
+Never validate an artifact whose provenance you did not state. "The newest archive"
+is a guess the user must be able to correct.
+
+### Mode A  -  build from the branch
+
+1. Worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` on the chosen branch.
+   **Never under `$HOME`**, never a direct checkout of the main working tree.
+2. Resolve the scheme / module and workspace / project from prefs; ask if ambiguous.
+3. Build:
+   - **iOS**: `ios_xcodebuild({workspace|project, scheme, action: "archive", configuration: "Release", destination: "generic/platform=iOS"})`.
+     Note the destination: the simulator default would produce an archive that
+     cannot be exported for distribution.
+   - **Android**: `./gradlew bundleRelease` (or the release variant the module
+     declares). A debug-signed bundle fails Gate 1 signing rules for the wrong
+     reason  -  if no release signing config resolves, halt and say so rather than
+     auditing a debug artifact.
+4. **iOS export**:
+   `ios_export_ipa({archive_path, output_dir, method: "app-store-connect", team_id, provisioning_profiles?, signing_style?})`.
+   Leave `allow_provisioning_updates` off unless the user asks: it lets xcodebuild
+   create or modify profiles in the developer account, which a validation run has no
+   business doing.
+5. A failed build or export halts with the parsed errors. The usual iOS causes are a
+   missing distribution certificate, a profile that does not match the bundle ID, or
+   `signing_style: "manual"` with no `provisioning_profiles` map.
+
+## Step 4  -  Gate 1, static package audit
+
+- **iOS**: `ios_app_store_audit({archive_path, rules: "all"})`. Consult the
+  `apple-archive-compliance` skill for what each rule means.
+
+  Needs `@mmerterden/dev-toolkit-mcp` ≥ v2.9.0, which provides the tool. When the
+  MCP server is not registered, the same 18 rules run directly from the package:
+
+  ```bash
+  node -e "import('@mmerterden/dev-toolkit-mcp/tools/ios-app-store-audit/index.js').then(m => m.runAudit({ archivePath: '<path>', rules: 'all' }).then(r => console.log(JSON.stringify(r))))"
+  ```
+
+  Use the fallback only when the tool is genuinely absent, and say in the report
+  which path ran  -  a rule set that silently differed between two invocations is
+  worse than a missing gate.
+- **Android**: `android_apk_audit` on the artifact, plus the
+  `google-play-compliance` skill's 21 rules  -  `bundletool validate` and manifest
+  dump, `aapt2 dump badging`, `apksigner verify`, ABI / native scan.
+
+`error` findings are blocking; `warning` is advisory. Group by severity and keep
+each finding's ITMS / Play policy code  -  Gate 2 may return the same code on iOS,
+and seeing it in both places tells the user it is real rather than a heuristic.
+
+## Step 5  -  Gate 2, the store's own validation
+
+**iOS**: `ios_testflight_validate({ipa_path, platform: "ios", <credential args>})`.
+Render the verdict exactly as returned:
+
+- `PASS`  -  Apple accepted the binary for delivery.
+- `FAIL`  -  list each issue with its ITMS code, the mapped guideline, and the hint.
+- `SKIPPED`  -  print the reason. **Never render this as a pass.**
+
+Gate 2 is the only gate that catches a build number already used  -  so when it
+fails on that, say so plainly and name the next free build number.
+
+**Android**: report `SKIPPED (no local Play validator)` with one line on why: the
+authoritative check is a Play Publishing API draft edit, the pipeline ships no
+client for it, and no local tool substitutes. `bundletool validate` is Gate 1 and
+reporting it here would fake a cleared gate.
+
+## Step 6  -  Gate 3, policy review
+
+Load the platform's review skill and review the repo against it. This is the gate
+that catches what a human reviewer rejects, so it reads source, not the binary.
+
+**iOS**  -  `app-store-review`:
+
+| Area | Evidence to gather |
+|---|---|
+| Purpose strings | every `NS*UsageDescription` in Info.plist  -  present, specific, user-facing, and matching what the code actually does with the data |
+| Privacy manifest | `PrivacyInfo.xcprivacy` exists, declares required-reason APIs, and matches the SDKs actually linked |
+| Tracking | if any tracking API or SDK is present, an ATT prompt exists and runs before collection |
+| Account deletion | if the app creates accounts, an in-app deletion path exists (guideline 5.1.1(v)) |
+| Privacy policy | reachable in-app and in the metadata |
+| IAP | anything unlocking features goes through StoreKit, with no external purchase path |
+| Sign in with Apple | present when a third-party social login is offered |
+
+**Android**  -  `play-store-review`:
+
+| Area | Evidence to gather |
+|---|---|
+| Permissions | every `uses-permission` justified by a feature, no sensitive permission without its declaration form |
+| Data safety | the declared data-safety answers match what the code collects and transmits |
+| Target API level | meets the current Play requirement for new releases |
+| Privacy policy | reachable in-app and in the listing |
+| Billing | anything unlocking features goes through Play Billing, with no external purchase path |
+| Account deletion | if the app creates accounts, an in-app deletion path exists, plus the web deletion URL Play requires |
+| Content rating | the questionnaire answers match the app's actual content |
+| Signing | Play App Signing configured, upload key distinct from the app signing key |
+
+For each: `pass` / `fail` / `not-applicable` with the evidence path that justifies
+it. `not-applicable` needs a reason  -  an unexamined area is not a pass.
+
+## Step 7  -  report
+
+Write to `~/StoreChecks/<platform>-<repo>-<branch>-<timestamp>/report.md` and print
+a summary.
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Platform:<ios|android>
+Build:   <artifact path>  ·  <bundle id / applicationId> <version> (<build>)
+Auth:    tier <1|2|none>  ·  <method>          (iOS only)
+Sweep:   <n> findings | SKIPPED (<reason>)
+
+Gate 1  static audit        PASS | FAIL (<n> blocking, <n> advisory) | SKIPPED (<reason>)
+Gate 2  store validation    PASS | FAIL (<n> issues) | SKIPPED (<reason>)
+Gate 3  policy 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>
+
+Advisory
+  ...
+
+Not run
+  Gate 2: no local Play validator  -  authoritative check is server-side only
+```
+
+Rules for the report:
+
+- A skipped gate is never folded into the pass count. The verdict line states the
+  skip. An Android run therefore reads `2 of 3 gates cleared, 1 skipped` at best.
+- Every blocking finding carries a file path or a store code. A finding the user
+  cannot act on is noise.
+- Humanize via `--lang en` by default (`promptLanguage` is locked to `"en"`); pass
+  `--lang=tr` explicitly to opt into Turkish.
+- No AI or assistant attribution anywhere, per
+  `$HOME/.claude/rules/git-conventions.md`.
+- Real newlines, no HTML entities, per
+  `$HOME/.claude/multi-agent-refs/rules.md "External System Outputs"`.
+
+## Step 8  -  offer the next action, do not take it
+
+Print, and stop:
+
+- the exact upload command for when the gates are clear, so uploading stays an
+  explicit human act:
+  - iOS: `xcrun altool --upload-app ...`
+  - Android: the Play Console upload, or the `gradle publish` task the project
+    declares  -  never run it
+- `/multi-agent:store-ready --resume` to re-run after fixes
+- `/multi-agent:channels` to land the findings in Jira / Confluence / Wiki / PR
+- `/multi-agent:fix-bug` when Gate 3 produced code-level findings
+
+Never upload, never commit a Play edit, never bump the build number, never commit.
+
+## Related surfaces
+
+`/multi-agent:testflight-validation` is a thin alias onto this command, kept so the
+iOS-only name keeps working; it resolves here with the platform pinned to iOS.
+`/multi-agent:test "store-ready"` also resolves here. There is one implementation.