@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/multi-agent-refs/store-ready/gates.md

@@ -0,0 +1,139 @@
+# store-ready: the three gates, input flags and Gate 2 detail
+
+<!-- toc -->
+- [Why three gates, and why the same three on both platforms](#why-three-gates-and-why-the-same-three-on-both-platforms)
+- [Gate matrix](#gate-matrix)
+- [Input](#input)
+- [Step A: why the sweep belongs here](#step-a-why-the-sweep-belongs-here)
+- [Gate 1: severity](#gate-1-severity)
+- [Gate 2](#gate-2)
+- [Gate 3: scope](#gate-3-scope)
+<!-- /toc -->
+
+Read by `/multi-agent:store-ready` before Step 0. The command file keeps the step
+order, the skip and never-ship rules; this file holds the gate model, the input
+table and the Gate 2 procedure per platform.
+
+## Why three gates, and why the same three on both platforms
+
+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 |
+|---|---|---|
+| **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 |
+
+A validation run must not be able to ship a build by accident: iOS runs
+`--validate-app`, never `--upload-app`; when Google Play is onboarded, Android Gate 2
+uploads the bundle into a throwaway edit that is validated and deleted, only after
+the user approves that plan.
+
+## 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`, 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 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 that uses one falls back to the
+behaviour it has without the credential.
+
+## Input
+
+| 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"
+```
+
+Branch picker options after the fetch: the current branch, the default branch, and
+any `release/*` / `tkdevelop/*` heads. Mode B (supply a
+build) is fastest and needs no signing in-run; Mode A (build from the branch) needs a
+distribution certificate and profile in the keychain on iOS, the release signing
+config on Android, and takes as long as a real release build.
+
+## Step A: why the sweep belongs here
+
+The gates read a package; the sweep 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. It delegates the mechanics to the UI
+Bug Hunter flow and merges its findings into the single Step 7 report,
+severity-grouped alongside the gate findings.
+
+## Gate 1: severity
+
+`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. The
+iOS direct-package fallback runs only when the audit tool is genuinely absent, and
+the report says which path ran.
+
+## Gate 2
+
+**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.
+
+**Build number** (App Store Connect onboarded, `store_status` reports
+`appStoreConnect.configured`): find the app with `store_asc_apps` by the archive's
+bundle id, then `store_asc_next_build_number({app_id, version: <CFBundleShortVersionString>})`.
+Report the archive's `CFBundleVersion` as `already used` (not above the highest
+uploaded one, with the suggested next) or `free`. Read-only; it never changes the
+project. Without the credential, skip this line and say why.
+
+**Android, Google Play onboarded, attended run.** Call
+`store_play_validate_bundle({package_name: <applicationId>, bundle_path: <.aab>})`
+without `confirm`. It returns the plan only: it would open an edit, upload the
+bundle, validate the edit, then delete it, committing nothing and changing no
+track. Show that plan to the user and ask (picker, `question` / `description` in
+`outputLanguage`, `header` `Play check`, labels `Validate on Play` / `Skip`).
+Only on **Validate on Play**, call it again with `confirm: true`. Render the
+verdict from `valid`: `true` → `PASS`, `false` → `FAIL` with the returned
+`error`. On **Skip**, report `SKIPPED (no local Play validator)` with the reason
+`user declined the upload`.
+
+**Android otherwise** (unattended, or not onboarded): do not call the tool; report
+`SKIPPED (no local Play validator)` with the reason from the Step 2 states.
+
+`bundletool validate` is Gate 1 in every case; reporting it here would fake a
+cleared gate.
+
+Google does not document whether an upload into a discarded edit reserves its
+`versionCode`; fastlane's `validate_only` runs the same sequence as a pre-release
+check. If the real upload is later refused as "already used", raise `versionCode`.
+
+## Gate 3: scope
+
+This is the gate that catches what a human reviewer rejects, so it reads source,
+not the binary. Both review skills cover a `Crash symbolication` row (dSYM upload
+step / `mapping.txt` upload).

package/pipeline/multi-agent-refs/store-ready/report.md

@@ -1,7 +1,8 @@
 # store-ready: report template
 
-Read by `/multi-agent:store-ready` for Step 7. The report rules stay in the
-command file; this is the layout they apply to.
+Read by `/multi-agent:store-ready` for Steps 7 and 8. The command file keeps
+the skip and attribution rules; this file holds the layout, the full report
+rules and the next actions Step 8 prints.
 
 Write to `~/StoreChecks/<platform>-<repo>-<branch>-<timestamp>/report.md` and print
 a summary.
@@ -38,3 +39,40 @@ Before rollout (human inputs, not verified)
   Rollback / forward-fix owner: <name>
   Forward-fix plan: <one line>
 ```
+
+## Rules
+
+- A skipped gate is never folded into the pass count. The verdict line states the
+  skip. An Android run whose Gate 2 did not 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.
+- The `Before rollout` block (phased rollout, `Halt thresholds`, rollback /
+  forward-fix owner, forward-fix plan) is filled by a human, never inferred. When it
+  is left unfilled the verdict line gains the suffix `, rollout plan missing`.
+- The printed summary carries the verdict line, per-gate status, Blocking / Advisory /
+  Not run / Open questions, and the `Before rollout` block.
+- 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"`.
+
+## Next actions
+
+Step 8 prints these and stops:
+
+- 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
+- the enabled stack plugin's `fix-bug` skill (`ai-ios-toolkit:fix-bug` or the stack
+  equivalent) when Gate 3 produced code-level findings
+
+`/multi-agent:testflight-validation` is a thin alias onto the command, kept so the
+iOS-only name keeps working; it resolves there with the platform pinned to iOS.
+`/multi-agent:test "store-ready"` also resolves there. There is one implementation.

package/pipeline/multi-agent-refs/sync/office.md

@@ -0,0 +1,10 @@
+# Office Check (Step 3e)
+
+Read by `/multi-agent:sync` at Step 3e of every sync and at step 9c of a release.
+
+The office panel ships with the pipeline, so a sync carries it by checking it, not by copying it:
+
+1. `node ~/multi-agent-pipeline/pipeline/scripts/office-build.mjs --check`: the committed page is what `pipeline/office-src` builds to, and `office/toolkit.json` carries the toolkit version in `docs/facts.json`. Either stale fails the sync until it is rebuilt and committed; a release that regenerates facts rebuilds the office right after.
+2. After the install steps, compare `pipeline/office/index.html` with the installed copies (`~/.claude/office/`, and the Copilot and Codex trees when installed), byte for byte, plus the asset list. A difference means the install is behind: run `node install.js --installed` and compare again.
+3. Report the toolkit version the installed `office/toolkit.json` carries: it is what the office Tools window starts, and it moves forward with every release.
+4. An office server that is already running picks the update up by itself: the open page shows a reload banner, and `/multi-agent:office-on` replaces a server whose code changed. Nothing to restart by hand.

package/pipeline/multi-agent-refs/sync/overview.md

@@ -0,0 +1,61 @@
+# Sync Overview: targets, shared sections, tokens
+
+Read by `/multi-agent:sync` before Step 1.5 (DETECT) to know every target's
+path and direction, and before any step that switches GitHub identity or
+publishes.
+
+## Targets
+
+| # | Target | Path | Direction |
+|---|-------|-----|-----|
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
+| 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
+| 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
+| 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
+| 4 | Website | `{owner}/{website-host}` | <- version + features |
+| 5 | multi-agent-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
+
+## Sync rules (Claude <-> Copilot)
+
+1. **Read first**  -  understand every target's current state before making any change
+2. **Preserve file structure**  -  each target has its own format:
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
+   - `copilot-instructions.md`: general development instructions + pipeline summary section
+   - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
+3. **Sync the shared sections** (Claude ↔ Copilot):
+   - Pipeline entries table (base / :autopilot)
+   - Project detection (URL-based + cwd-based)
+   - Figma pipeline flow
+   - Git conventions (author, branch, commit format)
+   - Keychain management (registry, naming convention, multi-agent pattern)
+4. **Do not duplicate**  -  summary in Copilot, full spec in Claude. Keep this distinction.
+5. **Report**  -  show a short diff summary after sync
+
+## Keychain Token Access
+
+| Operation | Token Source |
+|-------|---------------|
+| `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
+| `gh` CLI (work) | `{user}_<work-label>` gh auth (Keychain)  -  see `prefs.global.accounts[]` |
+| npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
+| multi-agent-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
+
+```bash
+gh auth switch --user {owner}  # for personal repos
+```
+
+## Website files (Step 4)
+
+| File | What to sync |
+|-------|--------------|
+| `src/lib/i18n.tsx` | Phase count, model count, feature descriptions (EN + TR) |
+| `src/data/projects.ts` | Version number, tagline, description, feature list |
+
+## Sub-command paths
+
+| Claude Code | Copilot CLI |
+|-------------|-------------|
+| `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
+
+**Claude -> Copilot**: add SKILL.md frontmatter (`name`, `description`, `user-invocable: true`, `argument-hint`)
+**Copilot -> Claude**: simplify the frontmatter (`description` + `allowed-tools`), add `$ARGUMENTS`

package/pipeline/multi-agent-refs/sync/repo.md

@@ -0,0 +1,91 @@
+# Pipeline Repo Sync (Step 3)
+
+Read by `/multi-agent:sync` before Step 3 (REPO), and before writing or reviewing
+any synced shell script.
+
+## Platform support (macOS only)
+
+Only macOS is supported (ADR-0012). `package.json` declares `os: ["darwin"]`, which npm enforces on the root package, so this tree cannot be installed elsewhere, and a detection table for other hosts would describe a case that cannot occur.
+
+**Contract for synced shell scripts.** The runtime is BSD userland and bash 3.2,
+and that is a stricter constraint than "cross-platform", not a looser one:
+
+1. Path handling: always quote (`"$f"`); use `$HOME`, never `/Users/...`.
+2. `grep -P` is banned. BSD grep has no `-P`: it exits 2, and with `2>/dev/null`
+   that reads as "found nothing". Use `-E`.
+3. Timestamps: `stat -c %Y` FIRST, then `stat -f %m`. GNU-first ordering is
+   required because `stat -f` is a valid GNU flag (`--file-system`) that
+   succeeds and prints something that is not a timestamp.
+4. Hashes: `sha256sum || shasum`, in that order. The gate fails a file that
+   names either alone.
+5. `find` traversal: `-prune` for `node_modules`, `Pods`, `.build`,
+   `DerivedData`, `.next`.
+6. Sed / awk: POSIX-portable. `-E`, never `-r`; `sed -i ''` on BSD.
+7. Keychain I/O: always via `~/.claude/lib/credential-store.sh get|set`, never
+   `security` directly - the wrapper is what keeps a secret off argv.
+8. Verification: after Step 3 (REPO), `bash -n` every shell script in
+   `pipeline/lib/` and `pipeline/scripts/`.
+
+## Repo sync rules
+
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
+2. **Target**: `~/multi-agent-pipeline/pipeline/`
+3. **Genericization** (must be applied BEFORE writing to the target):
+   - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
+   - Personal names/emails -> generic placeholder
+   - Branch names -> `develop`
+   - Project names -> `my-app`
+   - `{JIRA_HOST}`, `{BITBUCKET_HOST}`, `{CONFLUENCE_HOST}`, `{CORP_DOMAIN}` stay as-is
+   - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results
+4. **File mapping**:
+   ```
+   ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
+   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
+   ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
+   ~/.claude/agents/*.md                  -> pipeline/agents/
+   ```
+5. **Files NOT synced** (local-only, may contain personal data):
+   - `~/.claude/multi-agent-preferences.json`
+   - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
+   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
+   - `~/.claude/settings.json`
+   - `~/.claude/office/`  -  the office panel flows the other way: its source is the repo (`pipeline/office-src`, built by `office-build.mjs` into `pipeline/office`), and the installer copies it to each host. Never copy it from `~/.claude` into the repo; Step 3e checks it instead
+   - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
+   - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`.
+     ```bash
+     grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
+     # backstop: corporate refs only (generic ai-ios-toolkit is fine)
+     grep -rniE "ai-(ios-engineering|mobile)-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
+       ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
+     ```
+   - **Installed-tree artifacts.** Picker descriptions are Turkish with a
+     `description-en:` sidecar when `outputLanguage=tr`, and fable-tier agents
+     carry `model: opus` while `fableEnabled` is off. The repo always gets the
+     English form and `model: fable`, so normalize after copying:
+     ```bash
+     # normalize: restore English descriptions, strip description-en sidecars
+     node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \
+       --dir ~/multi-agent-pipeline/pipeline/commands/multi-agent
+     grep -rl "^description-en:" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: description-en sidecar leaked into pipeline/commands"; exit 1; } || true
+     # backstop: repo description lines must be English (Turkish-diacritics proxy)
+     grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
+       && { echo "ABORT: localized description leaked into pipeline/commands"; exit 1; } || true
+     node ~/multi-agent-pipeline/pipeline/lib/agent-model-sync.mjs --dir ~/multi-agent-pipeline/pipeline/agents --fable-on
+     ```
+
+6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
+   ```bash
+   # bash -n: parse-level syntax check on every shell script
+   find ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts \
+        -name "*.sh" -type f -exec bash -n {} \;
+   # Should print nothing  -  any output is a portability regression.
+
+   # Portability grep: flag known non-portable constructs introduced post-sync.
+   grep -rnE "stat -f[^[:space:]]+[^|]|sed -i[^[:space:]'\"]" \
+        ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts || true
+   # Each hit needs an explicit GNU/BSD fallback per the Platform Support contract.
+   ```
+   Gate failure -> abort push, surface the file + line, fix in the `~/.claude/` source first, re-sync.

package/pipeline/multi-agent-refs/update/details.md

@@ -0,0 +1,83 @@
+# update: details and sample output
+
+Read by `/multi-agent:update` before writing the step 6 summary, or when a step
+fails and its reasoning matters.
+
+## Why doctor runs after the install
+
+An update is the moment the layout changes, so it is the moment a layout check
+is worth most: a script that moved, a host tree that did not get the copy, a
+version stamp that disagrees with the package.
+
+## Why the download pins the scope (step 3)
+
+`--registry` does NOT override a scope mapping. A user-level .npmrc line like
+`@scope:registry=https://npm.pkg.github.com` wins over it, so the download hits
+the wrong registry, fails with `notarget`, and `--silent` hides why. Pinning the
+scope is the setting that actually loses to nothing.
+
+The tarball path is taken from `npm pack`'s own output, never a glob: an older
+tarball left in `$UPD_DIR` would be extracted instead, and the run would install
+the version it was trying to leave.
+
+The registry is read with `curl`, not `npm view`, because `npm view` can answer
+from a stale local cache.
+
+## What `--installed` refreshes
+
+`--installed` refreshes exactly the CLI targets that already carry a version
+stamp (`$HOME/.claude/.pipeline-version`, `$HOME/.copilot/.pipeline-version`,
+`$HOME/.codex/.pipeline-version`) and adds none: an update never installs
+Copilot CLI or Codex CLI on a machine that only had Claude Code. With no stamp at
+all it installs Claude Code. Each refreshed target gets the new version stamp.
+
+## Retired adapters (step 4c)
+
+Cursor, Antigravity and Copilot Chat adapters are no longer targets; the pipeline
+targets Claude Code, Copilot CLI and Codex CLI. Per-project adapter files
+(`.cursor/`, `.agent/`, `.github/copilot-instructions.md`) live in the user's
+repos and are left untouched.
+
+## Writing the step 6 summary
+
+The JSON holds every release between the old and the new version (not only the
+last one) and, for each plugin the refresh moved, that plugin's releases. Turn it
+into a short note in `outputLanguage`, written for the person using the
+pipeline, not for its maintainers:
+
+- First line: `✓ Updated: v<CUR> → v<NEW>`, then one line per updated plugin
+  (`ai-ios-toolkit 0.20.0 → 0.21.0`).
+- Then up to four groups, each only when it has entries: **New** (added),
+  **Fixed**, **Changed**, **Removed** (Turkish: Yeni, Düzeltilen, Değişen,
+  Kaldırılan). Put security entries first under Fixed.
+- One plain sentence per item about what the user notices or can now do. Merge
+  items that say the same thing; leave out internal-only entries (smoke tests,
+  CI, refactors, budgets, docs) unless they change what a user sees. At most
+  about eight items per group; when more were dropped, say how many and that the
+  full list is in the CHANGELOG.
+- Last line, when anything needs action: what to do (restart Claude Code for
+  plugin changes, run a command a release asks for).
+
+With empty notes and no plugin updates, print only the version line.
+
+## Sample output
+
+```
+Current: v15.6.0   Latest: v15.7.0
+  -> npm pack @{npm-scope}/multi-agent-pipeline@15.7.0
+  -> node install.js --installed (Claude Code; no Copilot CLI or Codex CLI stamp, not installed)
+  -> migrate-prefs.mjs (0 changes  -  already v2.6.0)
+
+✓ Updated: v15.6.0 → v15.7.0
+  ai-ios-toolkit 0.19.0 → 0.20.0
+
+New
+  - iOS design review: critiques a screen against the HIG from screenshots.
+Fixed
+  - The usage report reads the tracker as it is written.
+Restart Claude Code to load the updated plugins.
+
+Verification:
+  schema-validation: 27/27 pass
+  cross-cli-behavior: 14/14 pass
+```