@mmerterden/multi-agent-pipeline 20.13.0 → 20.15.0

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

@@ -15,8 +15,7 @@ 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.
+A worktree, when needed, only archives without touching your working tree.
 
 **It never ships.** iOS runs `--validate-app`, never `--upload-app`. Android
 never commits a Play edit: when Google Play is onboarded, Gate 2 uploads the
@@ -26,12 +25,17 @@ accident.
 
 **Input**: $ARGUMENTS
 
+## Gotchas
+
+- A skipped gate is reported as skipped with its reason, never folded into a pass: a green static audit says nothing about what the store's validator will say.
+- The Play throwaway edit is deleted whether validation passes or fails.
+- Gate 3 reads source, not the binary: a policy finding cites `file:line` in the repo the package was built from.
+
 ## 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.
+Each gate sees what the others cannot, so no single one is "the check". The
+failure modes are the same on both platforms: a malformed package, a package the
+store refuses, a policy a human enforces.
 
 | Gate | Sees | Blind to |
 |---|---|---|
@@ -47,12 +51,10 @@ a package the store itself refuses, and a policy a human enforces.
 | 2 Authoritative | `ios_testflight_validate({ipa_path, platform: "ios", <credentials>})` → `xcrun altool --validate-app`, plus `store_asc_next_build_number` for whether the build number is already used. Needs an `.ipa` + credentials | With `google_play` onboarded: `store_play_validate_bundle({package_name, bundle_path})`  -  Google validates the `.aab` in a throwaway Publishing API edit that is then deleted, never committed. Without it, Play's check exists only server-side and nothing local reproduces it, so this gate reports `SKIPPED (no local Play validator)` with the reason `Google Play not onboarded`. Do not substitute `bundletool validate`  -  that is Gate 1 |
 | 3 Policy | `ai-ios-toolkit:app-store-review` skill vs repo source | `ai-android-toolkit: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: Gate 2 runs only when
-Google Play is onboarded and the user approves the upload into a throwaway edit.
-Without both, an Android run clears at most 2 of 3 gates and must never print
-`passed`.
+Gate 2's asymmetry is reported, not smoothed over. On iOS it is the only gate that
+catches a version+build pair already used. On Android it runs only with Google Play
+onboarded and the throwaway-edit upload approved; without both, an Android run
+clears at most 2 of 3 gates and never prints `passed`.
 
 The `store_*` tools need `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.17.0. On an
 older server they are absent, and each branch below that uses one falls back to
@@ -94,22 +96,13 @@ English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
 
 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 pipeline's own 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.
+2. **Branch**  -  the branch to validate. Run `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** (credential / network / wrong remote), printing
+   the observed stderr line next to the classification. A credential failure never
+   gets the cached-ref fallback. Then offer the current branch, the default branch,
+   and any `release/*` / `tkdevelop/*` heads.
+   Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/preflight.md`. Read it for the fetch-failure table.
 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
@@ -120,33 +113,17 @@ English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
 
 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 and `.p8` in the Keychain (`appstore_connect_key_id`, `appstore_connect_issuer_id`, `appstore_connect_private_key`), read by the toolkit through the store reference file. `store_status` reports it as `appStoreConnect.configured` | Gate 2 runs; call `ios_testflight_validate` with neither `api_key_id` nor `apple_id` so it uses that key |
-| 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.
+**iOS**: `altool` and `xcodebuild` must resolve. Then resolve credentials and
+**state which tier is active in the report**: tier 1 ASC API key (`store_status`
+reports `appStoreConnect.configured`), tier 2 Apple ID + app-specific password,
+tier 3 neither, where **Gate 2 reports `SKIPPED`, and the run says so in the verdict
+line**. Multi-provider accounts need `--provider-public-id`; ask when it is not in prefs.
 
-**Android:**
+**Android**: `bundletool`, `aapt2` and `apksigner` must resolve.
 
-```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)"
-```
+Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/preflight.md`. Read it for Step 2 (commands, tier table, provider lookup).
 
-Then resolve whether Gate 2 can run. Call `store_status` (no probe) and read
+Then resolve whether Android Gate 2 can run. Call `store_status` (no probe) and read
 `googlePlay.configured`:
 
 | State | Gate 2 |
@@ -155,8 +132,7 @@ Then resolve whether Gate 2 can run. Call `store_status` (no probe) and read
 | `googlePlay.configured: true` and `MULTI_AGENT_UNATTENDED=1` | `SKIPPED (no local Play validator)`, reason: the toolkit refuses the upload in an unattended run |
 | not configured, or no `store_status` tool | `SKIPPED (no local Play validator)`, reason: `Google Play not onboarded` (`/multi-agent:setup` Step 3d) |
 
-Say which one it is: a user without the credential will go looking for one, and
-one with it needs to know why Gate 2 did not run.
+Say which one it is.
 
 Credentials come from `/multi-agent:setup`; never prompt for a secret value in
 chat.
@@ -178,81 +154,30 @@ 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
-```
+Mode B (supply a build) and Mode A (build from the branch). Full procedure:
+`$HOME/.claude/multi-agent-refs/store-ready/build.md`. Read it for Step 3. Rules that hold either way:
 
-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}/.worktrees/{taskId}` on the chosen branch (phase-0-init.md Step 6 convention; the `.worktrees` segment is fixed, not a preference).
-   **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.
+- **iOS `.ipa` only** → **Gate 1 is `SKIPPED (needs .xcarchive)`**; never present a
+  two-gate run as a full pass. An Android `.apk` **lists the rules it could not apply**.
+- Never validate an artifact whose provenance you did not state; print which one you picked.
+- Mode A worktree at `{projectRoot}/.worktrees/{taskId}`, **never under `$HOME`**, never
+  a direct checkout of the main working tree.
+- iOS archives with `destination: "generic/platform=iOS"`. Android with no release
+  signing config halts; never audit a debug artifact.
+- Leave `allow_provisioning_updates` off unless the user asks.
+- A failed build or export halts with the parsed errors.
 
 ## 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/multi-agent-toolkit-mcp` ≥ v3.0.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/multi-agent-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.
-
-  Then, whichever path ran, count `<archive>/dSYMs/*.dSYM`. Zero is a blocking
-  finding: `[SYMBOLS] archive carries no dSYM; crash reports will not symbolicate`,
-  with the hint `DEBUG_INFORMATION_FORMAT = dwarf-with-dsym` for the Release
-  configuration. This check runs from the package alone and does not need the
-  MCP tool.
-- **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.
+- **iOS**: `ios_app_store_audit({archive_path, rules: "all"})`, per the
+  `apple-archive-compliance` skill. The direct-package fallback runs only when the
+  tool is genuinely absent, and the report says which path ran. An archive with no
+  dSYM (`<archive>/dSYMs/*.dSYM` count zero) is a blocking `[SYMBOLS]` finding.
+- **Android**: `android_apk_audit` plus the `google-play-compliance` skill's 21 rules.
+  A `minifyEnabled true` module whose build produced no `mapping.txt` is a blocking
+  `[SYMBOLS]` finding.
 
-  Then, when the module has `minifyEnabled true` and the bundle build produced no
-  `mapping.txt`, raise the same class of blocking finding:
-  `[SYMBOLS] minified bundle carries no mapping.txt; crash reports will not
-  deobfuscate`. This check reads the module config and the build output alone
-  and does not need the MCP tool.
+Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/gate-1-static.md`. Read it for Gate 1.
 
 `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,
@@ -304,32 +229,9 @@ check. If the real upload is later refused as "already used", raise `versionCode
 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**  -  `ai-ios-toolkit: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 |
-| Crash symbolication | a dSYM upload step exists: an Xcode run-script calling `upload-symbols`, or a Crashlytics / Sentry / Datadog upload in CI |
-
-**Android**  -  `ai-android-toolkit: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 |
-| Crash symbolication | a `mapping.txt` upload exists: the Firebase Crashlytics Gradle plugin, or the Play App Bundle deobfuscation file |
+**iOS**  -  `ai-ios-toolkit:app-store-review`; **Android**  -  `ai-android-toolkit:play-store-review`.
+Both cover a `Crash symbolication` row (dSYM upload step / `mapping.txt` upload).
+Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/gate-3-policy.md`. Read it for Gate 3 (the per-platform area tables).
 
 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.
@@ -337,40 +239,10 @@ 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  -  Google Play not onboarded; the authoritative check is server-side only
-
-Open questions
-  Gate 2 (Android): versionCode <n> went to a discarded edit; Google does not document whether that reserves it
-
-Before rollout (human inputs, not verified)
-  Phased rollout: <1% -> 10% -> 50% -> 100% | full>
-  Halt thresholds: crash-free < 99.5% (iOS, Android) or ANR > 0.47% (Android) => pause the rollout
-  Rollback / forward-fix owner: <name>
-  Forward-fix plan: <one line>
-```
+a summary: verdict line, per-gate status, Blocking / Advisory / Not run / Open
+questions, and the `Before rollout` block (phased rollout, `Halt thresholds`,
+rollback / forward-fix owner, forward-fix plan).
+Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/report.md`. Read it for Step 7 (the report layout).
 
 Rules for the report:
 

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

@@ -24,6 +24,13 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `"change description"` | Apply the description to every target at once |
 
+## Gotchas
+
+- The pre-push gate is timing-sensitive: under heavy load a deadline test fails closed. Re-run it on a quiet machine; never push with `--no-verify`.
+- `npm publish` answering 202 means the registry is still processing. Verify with the registry's dist-tags before moving `required`, which is asked for every release.
+- The installed tree is localized (Turkish descriptions, `model: opus` while fable is off). Normalize before copying into the repo, or the public tree ships the local form.
+- Synced shell runs on BSD userland: BSD grep has no Perl-regex flag, and `sed` has no `\b` or `\|`. A pattern that silently matches nothing reads as "clean".
+
 ## Targets
 
 | # | Target | Path | Direction |
@@ -66,7 +73,7 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 61 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 63 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -99,7 +106,6 @@ Step 0 gate rules and why: `features/doctor.md`.
 4. **Do not duplicate**  -  summary in Copilot, full spec in Claude. Keep this distinction.
 5. **Report**  -  show a short diff summary after sync
 
-
 ---
 
 ## Pipeline Repo Sync Rules (CRITICAL)
@@ -168,274 +174,15 @@ Step 0 gate rules and why: `features/doctor.md`.
 
 ## Codex Sync (Step 2b)
 
-Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
-*transform* of the Claude tree, not a mirror of it, and the transform is real work:
-
-- the sub-command specs become reference files, because Codex silently truncates
-  its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
-- every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
-  `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
-- the personas under `agents/` are regenerated as TOML with a model + reasoning-effort mapping
-- shared state (`logs/`, prefs, `knowledge/`) is deliberately NOT retargeted
-
-That logic lives in `install/codex.mjs` and is gate-locked by
-`smoke-codex-install.sh`. Re-describing it here in prose would give the pipeline two
-definitions of the same transform, and the prose copy would be the one that rots. So
-the step runs the installer's Codex target:
-
-```bash
-cd "$HOME/multi-agent-pipeline"
-node install.js --codex
-```
-
-**Verify** (the installer is quiet about correctness, only about counts):
-
-```bash
-# exactly one pipeline skill: more than one means the skills block will truncate
-ls -1 "$HOME/.codex/skills" | grep -c '^multi-agent$'          # want 1
-# every sub-command reachable as a ref
-find "$HOME/.codex/multi-agent-refs/commands" -name SKILL.md | wc -l   # want the command count
-# no reference left pointing at a tree a Codex-only install does not have
-grep -rhoE '(\$HOME|~)/\.claude/(agents|scripts|lib|schemas|commands|multi-agent-refs|rules)' \
-  "$HOME/.codex/skills" "$HOME/.codex/multi-agent-refs" | sort -u   # want empty
-```
-
-**MCP**: the installer runs `codex mcp add multi-agent-toolkit` itself. It is idempotent, and
-it is skipped with a warning when `codex` is not on `PATH` -  never hand-edit
-`~/.codex/config.toml`, which Codex owns (marketplace and plugin state live there
-too).
-
-**Order matters**: run this AFTER Step 3 (REPO), because the installer reads the repo
-tree. Running it before means Codex gets the previous revision.
-
----
+Full procedure: `$HOME/.claude/multi-agent-refs/sync/codex.md`. Read it before Step 2b; it runs after Step 3.
 
 ## Stack-Plugin Sync (Step 3c)
 
-Stack skills are distributed as versioned plugins in the `mmerterden/multi-agent-plugins` marketplace. The pipeline's `pipeline/skills/shared/external/` is the **single authoring source**; the marketplace is a derived, versioned publish artifact. This step rebuilds it and publishes only when something changed.
-
-**Source of truth:** author/vendor knowledge skills in `pipeline/skills/shared/external/` (the pipeline's own phases also consume them). The plugins' authored lifecycle skills (`index` / `reference` / `workflow` / `tools`) live in the plugins repo and are never touched by sync.
-
-**Flow:**
-
-```bash
-PLUGINS_REPO="$HOME/multi-agent-plugins"
-[ ! -d "$PLUGINS_REPO/.git" ] && gh repo clone mmerterden/multi-agent-plugins "$PLUGINS_REPO"
-cd "$PLUGINS_REPO" && git pull origin main
-
-# 1. Preview what would change (routing + version bumps), no writes:
-node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs" --dry-run
-
-# 2. Apply: rebuild each stack plugin's knowledge/ from shared/external,
-#    regenerate plugin.json skills[], bump the patch version of any plugin
-#    whose skill set changed. Cross-stack skills -> ai-common-toolkit;
-#    Apple/Xcode-only skills -> iOS plugin only.
-node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
-```
-
-**Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent - a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which refreshes the catalog with `claude plugin marketplace update multi-agent-plugins`, then runs `claude plugin update` for each installed plugin).
-
-**Help + README freshness (mandatory when the generator reported any change):**
-
-1. Every plugin ships a `tools/help` skill that renders its catalog LIVE from `plugin.json`, so it needs no per-skill edits - but verify each changed plugin still registers it (`grep -c "./skills/tools/help" plugins/<name>/.claude-plugin/plugin.json` = 1) and that a new plugin gets one before publish.
-2. Plugin README tables sync through `python3 tools/bump.py <plugin> --set <version>`; run `python3 tools/bump.py --check` and treat DRIFT as a blocker.
-3. `python3 tools/validate.py` must be clean (it also enforces the CHANGELOG heading for every bumped version - write the entry, do not backdate).
-4. When the pipeline's command surface changed in the same sync (new/renamed `/multi-agent:*` commands), confirm `commands/multi-agent/help/SKILL.md` and both pipeline READMEs (`README.md`, `README.tr.md`) were updated in Step 3 before pushing here.
-
-**Publish (only if the generator reported bumps):**
-
-```bash
-cd "$PLUGINS_REPO"
-if ! git diff --quiet; then
-  # Identity: routed for {owner} (platformIdentityRouting). Never a literal: this file
-  # installs everywhere and would misattribute a downstream user's commits.
-  git config user.name  "{identity.name}"
-  git config user.email "{identity.email}"
-  git add -A
-  git commit -m "chore: rebuild stack plugins from pipeline shared/external"
-  gh auth switch --user {owner} 2>/dev/null || true
-  git push origin main
-fi
-```
-
-Never author skills directly in the plugins repo's `knowledge/` - they will be overwritten on the next rebuild. Author in `shared/external`, then run this step.
-
----
+Full procedure: `$HOME/.claude/multi-agent-refs/sync/stack-plugins.md`. Read it before Step 3c.
 
 ## Dev-Toolkit Sync (Step 3d)
 
-The companion MCP server (`multi-agent-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship  -  otherwise the pipeline documents a tool no consumer has.
-
-**Resolution**: identical to `/multi-agent:refactor` Step 0c  -  `prefs.global.devToolkit` first, then auto-detect from the `mcpServers` registration (`~/.claude.json`, `~/.claude/settings.json`), then skip. `enabled: false` skips.
-
-**Detect movement**:
-
-```bash
-DT="<resolved localPath>"; cd "$DT"
-git fetch origin --quiet 2>/dev/null || true
-DIRTY=$(git status --porcelain)
-AHEAD=$(git log --oneline @{u}..HEAD 2>/dev/null | wc -l | tr -d ' ')
-VER=$(node -p "require('./package.json').version")
-TAGGED=$(git tag --list "v$VER")
-```
-
-Moved = `DIRTY` non-empty, or `AHEAD` > 0, or no tag for `VER`. Nothing moved -> report `multi-agent-toolkit: up to date (v$VER)` and continue with the sync.
-
-**Ship gates**  -  all must pass before commit or publish. A gate failure aborts THIS step only, reported with file + line; the rest of the sync continues.
-
-**Prefer the repo's own gate script.** When the toolkit ships one (`npm run gates`, or `scripts/gates.sh`), run THAT and skip the inline list below - the repo owns the definition, this skill only owns the requirement. The inline gates are the fallback for a repo that has none, and the checklist the gate script itself must cover.
-
-```bash
-cd "$DT"
-if node -e "process.exit(require('./package.json').scripts?.gates ? 0 : 1)" 2>/dev/null; then
-  npm run gates || echo "ABORT: multi-agent-toolkit gates failed"
-elif [ -f scripts/gates.sh ]; then
-  bash scripts/gates.sh || echo "ABORT: multi-agent-toolkit gates failed"
-else
-  : # run the inline gates below
-fi
-```
-
-1. **Syntax**: `node --check index.js` plus every `tools/**/*.js`.
-2. **Boot + inventory**: handshake the server over stdio and count the registered tools.
-
-```bash
-TOOLS=$(printf '%s\n' \
-  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"sync","version":"1"}}}' \
-  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
-  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
-  | node index.js 2>/dev/null \
-  | node -e 'let b="";process.stdin.on("data",d=>b+=d).on("end",()=>{const m=b.split("\n").filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).find(x=>x&&x.id===2&&x.result&&x.result.tools);console.log(m?m.result.tools.length:0)})')
-[ "${TOOLS:-0}" -gt 0 ] || echo "ABORT: the toolkit served 0 tools"
-```
-
-3. **Advertised-count match**: `$TOOLS` must equal every advertised count (`package.json` `description`, the `README.md` header and its per-family rows). Fix the docs, never the gate  -  a stale count has shipped before.
-4. **Packaging**: every directory the server loads at runtime must be inside `files[]`. A missing entry publishes a broken package (this has already caused one patch release).
-
-```bash
-PACK=$(npm pack --dry-run 2>&1)
-for d in tools/*/; do printf '%s' "$PACK" | grep -q "$d" || echo "ABORT: $d missing from files[]"; done
-```
-
-5. **stdout hygiene**: `grep -rn "console\.log(" index.js tools/` must be empty  -  stdout carries the JSON-RPC frames, diagnostics belong on `console.error`.
-6. **Personal-data scan**: no absolute `/Users/<name>` paths, no tokens, no corporate hostnames in the shipped files.
-7. **Version contract**: every pipeline-side minimum (the `cross-cli-contract.md` tool table, `design-check`'s MCP requirement, `apple-archive-compliance`) must be satisfied by the version about to ship. A newly added tool that a pipeline skill now needs -> bump that declared minimum in the pipeline during this same sync.
-
-**Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool (pipeline minimums depend on the surface).
-
-**Ship**:
-
-```bash
-gh auth switch --user {owner}
-git add -A
-git commit -F "/tmp/release-msg-$NEW.txt"   # "{type}(v$NEW): {what changed}", written with the file tool
-git tag "v$NEW" && git push origin main --tags
-```
-
-Publish to the registry declared in `publishConfig` through a throwaway userconfig. Never edit `~/.npmrc`, and never a bare `npm publish`  -  it lands on whichever registry the ambient config happens to name.
-
-**The token depends on the registry AND on the package scope.** The registry picks
-the credential *type*; the scope picks the *account*. Resolving on host alone
-misroutes on any machine with more than one GitHub identity, which is the common
-case for anyone with a work and a personal account.
-
-| Registry | Credential type | Account chosen by |
-|---|---|---|
-| `npm.pkg.github.com` | GitHub PAT with `write:packages` (Classic; fine-grained PATs are not fully supported for Packages) | the package scope, e.g. `@{owner}` → the `{owner}` account's PAT |
-| `registry.npmjs.org` | npm token (logical key `npm`) | the npm account that owns the scope |
-
-Resolve the scope first, then the key:
-
-```bash
-SCOPE=$(node -p "(require('./package.json').name.match(/^@([^/]+)/)||[])[1] || ''")
-# Prefer a scope-specific mapping; fall back to the generic key only when the
-# machine has exactly one GitHub identity.
-KEY=$(node -e '
-  const fs=require("fs"),os=require("os"),p=os.homedir()+"/.claude/multi-agent-preferences.json";
-  const km=(JSON.parse(fs.readFileSync(p,"utf8")).global||{}).keychainMapping||{};
-  const scope=process.argv[1];
-  process.stdout.write(km[`github_${scope}`] ? `github_${scope}` : "github");
-' "$SCOPE")
-```
-
-**Pre-flight the scope, do not learn it from a 403.** GitHub tells you a token's
-scopes on any authenticated request, so check before uploading rather than after:
-
-```bash
-scope_ok() {  # $1 = token; prints the login, non-zero when write:packages is absent
-  local hdrs; hdrs=$(curl -sI -H "Authorization: token $1" https://api.github.com/user)
-  printf '%s' "$hdrs" | grep -i '^x-oauth-scopes:' | grep -q 'write:packages'
-}
-```
-
-**Candidate order for a `npm.pkg.github.com` publish.** The scope matters more than
-where the token is stored, and the two are not correlated: on a machine with a work
-and a personal identity, the hand-made PAT in the credential store may be the wrong
-account or the right account without `write:packages`, while the `gh` CLI's own
-OAuth token for that account often has it.
-
-1. `github_<scope>` from `keychainMapping` (a PAT deliberately onboarded for this scope)
-2. `gh auth token -u <scope>`  -  gh's stored OAuth token for that account
-3. the generic `github` key  -  only when the machine has one GitHub identity
-
-Take the first candidate that passes `scope_ok` AND whose `login` matches the
-package scope. If none qualifies, stop before `npm publish` and report which
-candidates were tried, what login each resolved to, and which scope was missing.
-That report is the actionable output; a 403 body is not.
-
-Measured on this machine, which is why the order is what it is:
-
-| Candidate | login | scopes |
-|---|---|---|
-| `keychainMapping.github` | corporate EMU account | cannot publish to a personal scope under any grant |
-| the personal PAT in the store | personal | `admin:public_key, gist, read:org, repo`  -  no `write:packages` |
-| `gh auth token -u {owner}` | personal | `gist, read:org, repo, workflow, write:packages` ✓ |
-
-**Two 403s mean two different things, and neither says "wrong token" plainly:**
-
-- `Unauthorized: As an Enterprise Managed User, you cannot access this content`  -
-  the resolved token belongs to a corporate EMU account, which cannot publish to a
-  personal scope at all. The mapping points at the wrong identity. Map the personal
-  account's PAT under `github_<scope>` and re-run; do not "fix" this by granting
-  the EMU token more scopes, because no scope makes an EMU account able to write
-  to a personal namespace.
-- `The token provided does not match expected scopes`  -  right account, missing
-  permission. The PAT needs **Classic** with `write:packages` (plus `repo` for a
-  private package). Regenerate it at
-  `https://github.com/settings/tokens/new?scopes=write:packages,read:packages,repo`
-  and re-onboard via `/multi-agent:setup`.
-
-Report which of the two it was. "Permission denied" alone sends the user to
-regenerate a token that was never the problem.
-
-```bash
-NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
-REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
-HOST=${REG#https://}; HOST=${HOST%/}
-case "$HOST" in npm.pkg.github.com*) KEY=github ;; *) KEY=npm ;; esac
-TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
-[ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
-printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
-npm publish --userconfig "$NPMRC"
-```
-
-Verify the publish landed: on GitHub Packages `npm view <package> version --userconfig "$NPMRC"`; on npmjs read the registry directly (`curl -s https://registry.npmjs.org/<package>/latest`) rather than `npm view`, which can answer from a stale cache.
-
-**Required release** (optional; ask first even in `release` mode, it halts every older install): `npm dist-tag add "$(node -p "require('./package.json').name")@$VER" required --userconfig "$NPMRC"`. Out of band, so promote or demote any time. Contract: `multi-agent-refs/rules.md` "Supported Version Gate".
-
-**Approval**: outside autopilot and outside `release`, ask before shipping.
-
-> "multi-agent-toolkit moved (N changed files, M unpushed commits, v$VER). What should I do?"
-
-- Commit + push (no publish)
-- Commit + push + publish v$NEW
-- Skip this step
-
-With `release`, or in autopilot, run the full ship path without asking. If the working copy holds band-E work from `/multi-agent:refactor` that was never approved, do not ship it silently  -  report it and ask.
-
-**Consumer note**: a path-based stdio registration (`node <localPath>/index.js`) picks the change up on the next MCP restart with no reinstall; a packaged registration (`npx <package>`) needs the published version. State which one the resolved config uses in the Step 6 report.
-
----
+Full procedure: `$HOME/.claude/multi-agent-refs/sync/dev-toolkit.md`. Read it before Step 3d, and for `/multi-agent:sync multi-agent-toolkit`.
 
 ## Website Sync (Step 4)
 
@@ -493,15 +240,15 @@ same specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**61 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**63 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
 autopilot-status, build-optimize, channels, complaint-analysis, create-jira,
-design-check, diff-explain, doctor, feedback, forget, garbage-collect, graph, help,
+design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help,
 ios-coding-standard, issue, jira, kill, language, log,
 manual-test, model, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
-routines, save, scaffold, scan, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test,
+routines, save, scaffold, scan, scenario-audit, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test,
 test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
 testflight-validation, uninstall, update
 ```