@mmerterden/multi-agent-pipeline 14.1.0 → 14.2.1

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

@@ -1,219 +1,46 @@
 ---
-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."
-description-tr: "TestFlight / App Store yüklemesi öncesi doğrulama (iOS, yalnızca lokal). Repo + branch seç, sonra ya build'i sen ver ya da koşu archive alsın; üç kapıyı geç: statik 18-kurallı archive denetimi, Apple'ın kendi `altool --validate-app`'i, ve App Store Review Guidelines'a karşı guideline incelemesi. Her kapı için ayrı verdict, ITMS kodları ilgili kurala eşlenmiş. Sadece doğrular  -  asla yüklemez."
+description: "iOS-pinned alias of store-ready: same three gates on an iOS build, one implementation. Validates a TestFlight / App Store package, never uploads. Use when an iOS build is about to go to TestFlight, or a submission was rejected and you need why."
+description-tr: "store-ready komutunun iOS'a sabitlenmiş alias'ı: iOS build'inde aynı üç kapı, tek implementasyon. TestFlight / App Store paketini doğrular, asla yüklemez."
 argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --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
 ---
 
-# /multi-agent:testflight-validation  -  pre-submission validation
+# /multi-agent:testflight-validation  -  iOS alias for store-ready
 
-Catch, before you upload, what App Store Connect would send back after you do.
+This command is an alias. The implementation it used to carry was merged into
+`/multi-agent:store-ready`, which runs the same three gates on iOS and adds the
+Android side, so there is one flow to maintain instead of two that had already
+started to drift.
 
-**Local-only.** No commits, no push, no PR, no channels. The worktree exists only
-to archive without touching your working tree.
+The name is kept because it is the one people reach for when the target is
+TestFlight, and removing a command is a breaking change to the slash-command
+surface.
 
-**It never uploads.** Only `--validate-app` is ever invoked, never `--upload-app`.
-A validation run must not be able to ship a build by accident.
+## Dispatcher
 
-## Why three gates and not one
-
-Each gate sees something the others structurally cannot. Reporting one of them as
-"the check" is how a build passes locally and gets rejected anyway.
-
-| Gate | What runs | Needs | Sees | Blind to |
-|---|---|---|---|---|
-| **1. Static** | `ios_app_store_audit` (18 rules, real ITMS codes) | an `.xcarchive` | privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, binary size | anything that depends on the App Store Connect account |
-| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | an `.ipa` + credentials | unregistered bundle ID, profile that does not match the app record, **a version+build pair already used**, entitlements not provisioned for the App ID | the Review Guidelines  -  Apple's validator does not read them |
-| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT flow, privacy policy, account deletion, IAP rules, purpose-string wording, permission justification | anything not visible in source |
-
-Gate 2 is the only one that asks Apple, and Gate 3 is the only one that covers the
-rejections a human reviewer writes. Most "we passed validation and still got
-rejected" cases are Gate 3 findings.
-
-## Step 0  -  parse input
-
-| Input | Meaning |
-|---|---|
-| (empty) | ask which repo (Step 1) |
-| `my-ios-app` or a path | that repo |
-| `--ipa=<path>` | Mode B with an `.ipa`; Gate 1 cannot run (see Step 3) |
-| `--archive=<path>` | Mode B with an `.xcarchive`; all three gates run |
-| `--resume` | continue the last run from its state file |
-
-State lives at `$HOME/.claude/logs/multi-agent/<task_id>/agent-state.json` with
-`taskId = TFV-<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` where the stack is iOS. 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.
-   - `Archive from this branch` (Mode A)  -  needs a distribution certificate and
-     profile in the keychain, and takes as long as a release archive.
-
-## Step 2  -  pre-flight, before anything expensive
-
-Report every line; a missing prerequisite is a halt, not a warning.
-
-```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** |
-
-Credentials come from `/multi-agent:setup`; never prompt for a secret value in
-chat. If nothing is configured, tell the user which of the two tiers they can set
-up and that tier 2 needs no elevated App Store Connect role.
-
-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.
-
-## Step 3  -  obtain the build
-
-### Mode B  -  a build you supply
-
-- `.xcarchive` → Gate 1 runs on it. To reach Gate 2 the archive must be exported,
-  so run `ios_export_ipa` (see Mode A step 3 for the signing inputs).
-- `.ipa` only → **Gate 1 is reported `SKIPPED (needs .xcarchive)`.** The static
-  audit reads archive structure that 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.
-
-### Mode A  -  archive 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 and workspace/project from prefs; ask if ambiguous.
-3. Archive:
-   `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.
-4. 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 export halts with the parsed errors. The usual 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 audit
-
-`ios_app_store_audit({archive_path, rules: "all"})`.
-
-`error` findings are blocking; `warning` is advisory. Group the output by severity
-and keep each finding's ITMS code  -  Gate 2 may return the same code, and seeing
-it in both places tells the user it is real rather than a heuristic.
-
-## Step 5  -  Gate 2, Apple's own validation
-
-`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.** The verdict line
-  for the whole run must read `2 of 3 gates cleared, 1 skipped`, not `passed`.
-
-Gate 2 is the only gate that catches a build number already used  -  the most
-common wasted upload  -  so when it fails on that, say so plainly and name the next
-free build number.
-
-## Step 6  -  Gate 3, guideline review
-
-Load the `app-store-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:
-
-| 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 |
-
-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 `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` and print a
-summary. Structure:
+Read this file and apply its instructions:
 
 ```
-Verdict: <N> of 3 gates cleared[, <M> skipped]
-Build:   <ipa or archive 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>
-
-Advisory
-  ...
-
-Not run
-  Gate 1: needs an .xcarchive; only an .ipa was supplied
+$HOME/.claude/commands/multi-agent/store-ready/SKILL.md
 ```
 
-Rules for the report:
+Run it with **platform pinned to `ios`** and skip its platform-detection step. Pass
+`$ARGUMENTS` through verbatim: `--ipa=`, `--archive=`, a repo name or path, and
+`--resume` all mean exactly what they mean there.
 
-- A skipped gate is never folded into the pass count. The verdict line states the
-  skip.
-- Every blocking finding carries a file path or an ITMS code. A finding the user
-  cannot act on is noise.
-- 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"`.
+`--aab=` / `--apk=` are Android inputs and are not valid here. If one is supplied,
+do not silently switch platform  -  say the Android inputs belong to
+`/multi-agent:store-ready`, and stop.
 
-## Step 8  -  offer the next action, do not take it
+## What you get
 
-Print, and stop:
+Unchanged from before the merge, on the iOS path:
 
-- the exact `xcrun altool --upload-app` command for when the gates are clear, so
-  uploading stays an explicit human act
-- `/multi-agent:testflight-validation --resume` to re-run after fixes
-- `/multi-agent:fix-bug` when Gate 3 produced code-level findings
+| Gate | What runs | Needs |
+|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules, real ITMS codes) | an `.xcarchive` |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | an `.ipa` + credentials |
+| **3. Policy** | `app-store-review` skill vs repo source | repo checkout |
 
-Never upload, never bump the build number, never commit.
+A skipped gate is never folded into the pass count, and the run never uploads. The
+report lands in `~/StoreChecks/ios-<repo>-<branch>-<timestamp>/report.md`.

package/pipeline/commands/sim-test.md

@@ -35,12 +35,36 @@ For Android: use `mcp__dev-toolkit__android_*` tools
 /multi-agent test "accessibility"      -> accessibility audit (visual + MCP audit tool)
 /multi-agent test "dynamic type"       -> large text test
 /multi-agent test "screenshot tr"      -> locale screenshots
-/multi-agent test "store-ready"        -> full audit: visual + accessibility + archive/APK compliance
-/multi-agent test "biometric"          -> Face ID / Touch ID flow test
-/multi-agent test "performance"        -> launch time + scroll performance
+/multi-agent test "store-ready"        -> hands off to /multi-agent:store-ready (package validation)
 /sim-test                              -> standalone (same thing)
 ```
 
+Not offered, deliberately  -  `"biometric"` and `"performance"` were listed here with
+no implementation section, so reaching one fell through to the general sweep and got
+reported as the scenario asked for. Neither can be implemented symmetrically today:
+biometric has an iOS tool (`ios_biometric`) and no Android counterpart, and launch
+timing has `android_launch_time` and no iOS counterpart. Platform is auto-detected,
+so either one would work on one platform and silently do nothing on the other. They
+come back when the missing side exists, not before  -  do not re-add the rows to make
+the list look complete.
+
+Four scenarios also have a fixed-scenario command that pins the tag, so it does not
+have to be typed or quoted. They arrive here with the scenario already resolved  -
+treat them as identical to the quoted form:
+
+```
+/multi-agent:test-dark-mode            -> scenario "dark mode"
+/multi-agent:test-accessibility        -> scenario "accessibility"
+/multi-agent:test-dynamic-type         -> scenario "dynamic type"
+/multi-agent:test-screenshots [locale] -> scenario "screenshot <locale>", locale defaults to tr
+```
+
+`store-ready` is not one of them, and does not belong to this file at all: it
+validates a built package on either platform and lives at
+`/multi-agent:store-ready`. The `"store-ready"` tag is kept as a hand-off so an
+existing invocation still lands somewhere correct. `/multi-agent:testflight-validation`
+is the iOS-pinned alias of that same command.
+
 ## Flow
 
 ### Step 1  -  Device & App Discovery
@@ -121,43 +145,28 @@ Call: ios_set_locale(language: "<lang>", bundle_id: "...")
 
 **"store-ready":**
 
-Runs visual + accessibility pass AND dispatches the platform-matching compliance skill so the build is pre-validated against Apple / Google store requirements before submission.
+Not implemented here. `store-ready` validates a built **package**, which is a
+different job from driving a running app, and it is owned by one command on both
+platforms:
 
 ```
-Platform detection:
-  cwd contains .xcodeproj OR Package.swift             -> iOS
-  cwd contains build.gradle OR build.gradle.kts        -> Android
-  Otherwise                                            -> error: "store-ready needs an iOS or Android project"
-
-Step A  -  run the standard visual + accessibility sweep (light + dark + large text).
-
-Step B  -  dispatch compliance skill:
-  iOS:
-    Load $HOME/.claude/skills/apple-archive-compliance/SKILL.md
-    Prereq: @mmerterden/dev-toolkit-mcp ≥ v2.9.0 (provides ios_app_store_audit MCP tool)
-             -  installable via npm; standalone ArchiveGuard binary deprecated in v8.4.0
-    Artifact: pick newest .xcarchive under ~/Library/Developer/Xcode/Archives/**
-              OR accept explicit path argument after "store-ready"
-    Invoke:   mcp__dev-toolkit__ios_app_store_audit({ archive_path: <path>, rules: "all" })
-              OR (Node fallback): 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))))"
-              Humanize via --lang en (promptLanguage is locked to "en"; pass --lang=tr explicitly to opt into Turkish)
-  Android:
-    Load $HOME/.claude/skills/google-play-compliance/SKILL.md
-    Prereq: bundletool, aapt2, apksigner in PATH (Android SDK build-tools)
-    Artifact: newest .aab under **/build/outputs/bundle/**/*.aab
-              OR explicit path argument
-    Invoke:   bundletool validate + dump manifest, aapt2 dump badging,
-              apksigner verify, ABI/native scan
-  Merge findings with UI-hunter findings -> single report, severity-grouped.
-
-Step C  -  humanize via `--lang en` by default (promptLanguage is locked to "en"; pass --lang=tr explicitly to opt into Turkish), group by severity
-  (error = blocker, warning = risk, info = hygiene), link each finding to the
-  Apple ITMS / Play policy reference supplied by the skill catalog.
-
-Step D  -  offer `/multi-agent:channels` follow-up so findings can land in
-  Jira / Confluence / Wiki / PR body via the normal Phase 7 machinery.
+$HOME/.claude/commands/multi-agent/store-ready/SKILL.md
 ```
 
+Read that file and follow it. Pass through any artifact path given after
+`store-ready` as its `--archive=` / `--ipa=` / `--aab=` / `--apk=` input.
+
+Its Step A is the visual + accessibility sweep in this file  -  it calls back here
+for the running-app half, then runs three gates per platform that nothing in this
+file can do: the static package audit, the store's own validator, and a policy
+review against repo source. It merges both halves into one severity-grouped report
+and offers the `/multi-agent:channels` follow-up.
+
+The archive-compliance audit used to be duplicated here, invoking
+`ios_app_store_audit` with exactly the arguments the store-ready command's Gate 1
+uses. Two copies of one call is how the iOS path grew a second door with no Gate 2,
+no Gate 3 and no Android parity, so the copy is gone rather than kept in sync.
+
 **No argument (full test):**
 
 - Run light mode -> all screens

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,14 +6,15 @@
 
 ---
 
-## 1. Command Inventory (44 commands)
+## 1. Command Inventory (49 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, forget, garbage-collect,
 help, ios-coding-standard, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, ship, stack, status, sync, test, testflight-validation, uninstall, update
+routines, save, scan, search, setup, ship, stack, status, store-ready, sync, test, test-accessibility,
+test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation, uninstall, update
 ```
 
 Categories:

package/pipeline/multi-agent-refs/knowledge.md

@@ -56,7 +56,7 @@ Knowledge files grow over time. Maintenance rules:
 - 90-day-old entries are considered "stale"  -  not used without verification
 - Stale check: orchestrator checks file mtime during Phase 1 knowledge injection
 - Stale entries are added to the prompt with a "STALE  -  verify before relying" tag
-- `clear-logs` does not touch knowledge  -  only deletes logs and state
+- `prune-logs` does not touch knowledge  -  only deletes logs and state
 - `purge` does not touch knowledge either  -  separate command: `/multi-agent clear-knowledge {project}`
 
 ---

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -73,7 +73,7 @@ Used for: input parsing, branch naming, commit messages.
 |---|---|---|---|
 | Project picked (Step 2) | `global.recentProjects` | `[{path, label, count, lastUsed}]` | 20 |
 | Multi-repo group picked or saved (Step 2) | `global.recentGroups` | `[{label?, repos[], count, lastUsed}]` | 10 |
-| Branch picked (Step 3) | `global.recentBranches[{projectKey}]` | `[{name, lastUsed}]` (TTL `settings.branchTtlDays`, default 15d) | implicit (TTL prunes) |
+| Branch picked (Step 3) | `global.recentBranches[{projectKey}]` | `[{branch, lastUsed, count?}]` (TTL `settings.branchTtlDays`, default 15d) | 10 (TTL also prunes) |
 | Service ping (any external API call) | `global.serviceStatus[{service}]` | `{ok, checkedAt, reason?}` (TTL `settings.serviceStatusCacheSeconds`, default 300s) | n/a |
 | Git identity routed (Step 6a) | `projects[{name}].lastIdentity` | int (index into `global.identities`) | n/a |
 
@@ -261,7 +261,10 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
    header: "Base branch"
    options: origin/develop (Recommended, reused from last run) | origin/main | release/8.4.0 | Other
    ```
-7. User picks → store as `baseBranch`. Save to `prefs.projects[{project}].branches` (dedup, max 10).
+7. User picks → store as `baseBranch`, and append `{branch, lastUsed, count?}` to
+   `prefs.global.recentBranches[{projectKey}]` (dedup by `branch`, cap 10) - what the TTL
+   filter below reads. Key is `branch`, not `name`. Never the legacy
+   `projects[{project}].branches`.
 
 **MUST: this step is not skippable (BLOCKING).** The only legitimate skip is rule 4
 above - `baseBranch` already supplied in the input. Everything else asks. A run once
@@ -277,7 +280,7 @@ which still writes the fields - it does not leave them unset.
 
 **TTL filter for recent branches**:
 
-- `prefs.global.recentBranches[{projectKey}][]` carries `{name, lastUsed}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
+- `prefs.global.recentBranches[{projectKey}][]` carries `{branch, lastUsed, count?}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
 - Stale entries (>TTL) are pruned in-place during the read  -  keeps the picker uncluttered without a separate cleanup pass.
 - The filtered "Recent" list precedes the fresh `git branch -r` list; cap at 5 visible recent entries.
 
@@ -403,7 +406,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 `worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
 
-**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json` at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, never inside the worktree:
 
 **Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
 

package/pipeline/schemas/prefs.schema.json

@@ -184,7 +184,7 @@
             },
             "appstore_connect_key_id": {
               "type": ["string", "null"],
-              "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:testflight-validation Gate 2. An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."
+              "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:store-ready Gate 2 (and its iOS alias /multi-agent:testflight-validation). An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."
             },
             "appstore_connect_issuer_id": {
               "type": ["string", "null"],

package/pipeline/schemas/token-budget.json

@@ -36,6 +36,6 @@
       "warn_tokens": 5600
     }
   },
-  "total_max_tokens": 52700,
-  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room."
+  "total_max_tokens": 52750,
+  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling."
 }

package/pipeline/scripts/build-stack-plugins.mjs

@@ -33,6 +33,7 @@ import {
   statSync,
 } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 
 const args = process.argv.slice(2);
 // Accepts both `--key value` and `--key=value`. The `=` form used to fall through to
@@ -251,6 +252,26 @@ for (const [plugin, want] of Object.entries(desired)) {
     pj.skills = newSkills;
     pj.version = newV;
     writeFileSync(pjPath, `${JSON.stringify(pj, null, 2)}\n`);
+
+    // The marketplace README carries a per-plugin table of version + skill count,
+    // and that table is what a human reads to know what is published. Bumping
+    // plugin.json without it drifted five of the five rows, silently, because the
+    // drift is only visible if someone runs the checker. `tools/bump.py` owns the
+    // table's format, so call it rather than reproducing the row layout here  -  a
+    // second formatter would be the one that rots.
+    const bumpTool = join(PLUGINS_REPO, "tools", "bump.py");
+    if (existsSync(bumpTool)) {
+      const r = spawnSync("python3", [bumpTool, plugin, "--set", newV], {
+        cwd: PLUGINS_REPO,
+        encoding: "utf8",
+      });
+      if (r.status !== 0) {
+        console.warn(
+          `  WARN ${plugin}: plugin.json is ${newV} but the README table was not synced ` +
+            `(bump.py exit ${r.status ?? "n/a"}). Run \`tools/bump.py --check\` in ${PLUGINS_REPO}.`,
+        );
+      }
+    }
   }
   report.push({
     plugin,

package/pipeline/scripts/migrate-prefs.mjs

@@ -270,6 +270,36 @@ function migrate(prefs) {
     out.global.recentBranches = {};
     changes.push("added empty recentBranches");
   }
+  // Carry the legacy per-project branch list into the canonical LRU. Phase 0 Step 3
+  // read global.recentBranches while its own step 7 wrote projects[].branches, so
+  // every branch a user ever picked landed in the field nothing reads and the
+  // "reused from last run" picker option stayed empty. Seeding here makes that
+  // history usable instead of stranding it. Idempotent: an existing entry for the
+  // same branch is never duplicated or overwritten.
+  //
+  // `lastUsed` is stamped with the migration time, not the real pick time, which the
+  // legacy field never recorded. Stamping the true unknown (epoch) would put every
+  // seeded entry outside settings.branchTtlDays and the TTL filter would prune it on
+  // the first read, making this carry-forward a no-op. `count: 0` marks the entry as
+  // seeded rather than observed, and the normal TTL retires anything the user does not
+  // actually pick again within the window.
+  const seededAt = new Date().toISOString();
+  for (const [projectKey, project] of Object.entries(out.projects ?? {})) {
+    if (!Array.isArray(project?.branches) || project.branches.length === 0) continue;
+    const lru = (out.global.recentBranches[projectKey] ??= []);
+    const known = new Set(lru.map((e) => e?.branch));
+    let seeded = 0;
+    for (const branch of project.branches) {
+      if (typeof branch !== "string" || !branch || known.has(branch)) continue;
+      if (lru.length >= 10) break;
+      lru.push({ branch, lastUsed: seededAt, count: 0 });
+      known.add(branch);
+      seeded += 1;
+    }
+    if (seeded > 0) {
+      changes.push(`seeded ${seeded} recentBranches entr${seeded === 1 ? "y" : "ies"} for ${projectKey} from legacy projects[].branches`);
+    }
+  }
   if (!Array.isArray(out.global.recentGroups)) {
     out.global.recentGroups = [];
     changes.push("added empty recentGroups");