@mmerterden/multi-agent-pipeline 12.4.0 → 12.6.0

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

@@ -1,7 +1,7 @@
 ---
-description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, and website."
-description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo ve website."
-argument-hint: "[release] [--platform=<macos|linux|windows>]"
+description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the dev-toolkit MCP server."
+description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo, website ve dev-toolkit MCP sunucusu."
+argument-hint: "[release] [dev-toolkit] [--platform=<macos|linux|windows>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 ---
 
@@ -15,8 +15,9 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | Arg | Meaning |
 |---|---|
-| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website. |
-| `release` | Full sync + version bump + tag + npm publish + website deploy |
+| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, dev-toolkit MCP server. |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (includes the dev-toolkit ship path) |
+| `dev-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `--platform=<macos\|linux\|windows>` | Override automatic platform detection. For CI / cross-platform smoke. |
 | `"change description"` | Apply the description to every target at once |
 
@@ -28,6 +29,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
+| 5 | dev-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
 
 ## Platform Support (macOS / Linux / Windows)
 
@@ -56,13 +58,14 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 42 sub-command skills)
 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/,
                      bump changed plugins' patch version, commit + push the plugins repo)
+Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
-Step 6: Report      Summary: synced targets, platform, changed files, deploy status
+Step 6: Report      Summary: synced targets, platform, changed files, deploy status, dev-toolkit version
 ```
 
 If nothing is stale → report "All targets up to date" and stop.
@@ -73,6 +76,7 @@ If nothing is stale → report "All targets up to date" and stop.
 |-------|----------|
 | (no args) | Full ecosystem sync (default) |
 | `release` | Full sync + version bump + tag + npm publish + website deploy |
+| `dev-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `"change description"` | Apply the description to EVERY target at once |
 
 ---
@@ -207,6 +211,107 @@ Never author skills directly in the plugins repo's `knowledge/` — they will be
 
 ---
 
+## Dev-Toolkit Sync (Step 3d)
+
+The companion MCP server (`dev-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 `dev-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: dev-toolkit gates failed"
+elif [ -f scripts/gates.sh ]; then
+  bash scripts/gates.sh || echo "ABORT: dev-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 -m "{type}(v$NEW): {what changed}"    # that repo's own commit convention
+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**: `npm.pkg.github.com` authenticates with a GitHub PAT carrying `write:packages` (logical key `github`), `registry.npmjs.org` with an npm token (logical key `npm`). Picking the wrong one fails with a 401 that reads like a missing package.
+
+```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.
+
+**Approval**: outside autopilot and outside `release`, ask before shipping.
+
+> "dev-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.
+
+---
+
 ## Website Sync (Step 4)
 
 Propagate pipeline version, phase count, model count, and feature descriptions to the website.
@@ -242,9 +347,10 @@ When invoked with the `release` argument:
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags -> release.yml auto-publish
-7. WEBSITE       Version + features -> {website-host}
-8. COPILOT       Copilot CLI instructions + skills sync
-9. Report        Summary: version, touched repos, deploy status
+7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
+8. WEBSITE       Version + features -> {website-host}
+9. COPILOT       Copilot CLI instructions + skills sync
+10. Report       Summary: version, touched repos, deploy status
 ```
 
 ---
@@ -257,10 +363,10 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**42 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
@@ -281,6 +387,7 @@ routines, save, scan, search, setup, stack, status, sync, test, uninstall, updat
 | `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 |
+| dev-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

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

@@ -35,6 +35,6 @@ Pass `$ARGUMENTS` through verbatim  -  sim-test.md decides which test matrix to
 
 - **iOS**: Xcode + a booted Simulator (`xcrun simctl list | grep Booted`)
 - **Android**: Android SDK + a running emulator or USB device (`adb devices`)
-- **MCP**: the `dev-toolkit` MCP server must be installed (tool names start with `mcp__dev_toolkit__`)
+- **MCP**: the `dev-toolkit` MCP server must be installed (tool names start with `mcp__dev-toolkit__`)
 
 For manual-test mode (checkout the task branch + Xcode-open hint), see `/multi-agent:manual-test`.

package/pipeline/commands/sim-test.md

@@ -1,6 +1,6 @@
 ---
 description: "Mobile UI Bug Hunter  -  iOS Simulator (simctl) + Android Emulator (adb)  -  auto-detects platform"
-allowed-tools: Agent, Bash, Read, Write, Edit, TaskCreate, TaskUpdate, TaskList, TaskGet, mcp__dev_toolkit__ios_list_devices, mcp__dev_toolkit__ios_boot_device, mcp__dev_toolkit__ios_screenshot, mcp__dev_toolkit__ios_tap, mcp__dev_toolkit__ios_swipe, mcp__dev_toolkit__ios_type_text, mcp__dev_toolkit__ios_launch_app, mcp__dev_toolkit__ios_terminate_app, mcp__dev_toolkit__ios_list_apps, mcp__dev_toolkit__ios_go_home, mcp__dev_toolkit__ios_set_appearance, mcp__dev_toolkit__ios_set_content_size, mcp__dev_toolkit__ios_set_locale, mcp__dev_toolkit__ios_open_url, mcp__dev_toolkit__ios_status_bar, mcp__dev_toolkit__ios_push_notification, mcp__dev_toolkit__ios_grant_permission, mcp__dev_toolkit__ios_revoke_permission, mcp__dev_toolkit__ios_reset_permissions, mcp__dev_toolkit__ios_set_location, mcp__dev_toolkit__ios_clear_location, mcp__dev_toolkit__ios_set_increase_contrast, mcp__dev_toolkit__ios_record_video, mcp__dev_toolkit__ios_add_media, mcp__dev_toolkit__ios_keychain_reset, mcp__dev_toolkit__ios_get_app_container, mcp__dev_toolkit__ios_erase_device, mcp__dev_toolkit__ios_get_ui_tree, mcp__dev_toolkit__android_list_devices, mcp__dev_toolkit__android_screenshot, mcp__dev_toolkit__android_tap, mcp__dev_toolkit__android_swipe, mcp__dev_toolkit__android_type_text, mcp__dev_toolkit__android_key_event, mcp__dev_toolkit__android_launch_app, mcp__dev_toolkit__android_stop_app, mcp__dev_toolkit__android_list_packages, mcp__dev_toolkit__android_go_home, mcp__dev_toolkit__android_go_back, mcp__dev_toolkit__android_get_ui_tree, mcp__dev_toolkit__android_set_dark_mode, mcp__dev_toolkit__android_set_font_scale, mcp__dev_toolkit__android_set_locale, mcp__dev_toolkit__android_set_location, mcp__dev_toolkit__android_grant_permission, mcp__dev_toolkit__android_revoke_permission, mcp__dev_toolkit__android_record_screen, mcp__dev_toolkit__android_install_apk, mcp__dev_toolkit__android_uninstall_app, mcp__dev_toolkit__android_logcat, mcp__dev_toolkit__android_get_screen_size, mcp__dev_toolkit__android_open_url, mcp__dev_toolkit__android_clear_app_data
+allowed-tools: Agent, Bash, Read, Write, Edit, TaskCreate, TaskUpdate, TaskList, TaskGet, mcp__dev-toolkit__ios_list_devices, mcp__dev-toolkit__ios_boot_device, mcp__dev-toolkit__ios_screenshot, mcp__dev-toolkit__ios_tap, mcp__dev-toolkit__ios_swipe, mcp__dev-toolkit__ios_type_text, mcp__dev-toolkit__ios_launch_app, mcp__dev-toolkit__ios_terminate_app, mcp__dev-toolkit__ios_list_apps, mcp__dev-toolkit__ios_go_home, mcp__dev-toolkit__ios_set_appearance, mcp__dev-toolkit__ios_set_content_size, mcp__dev-toolkit__ios_set_locale, mcp__dev-toolkit__ios_open_url, mcp__dev-toolkit__ios_status_bar, mcp__dev-toolkit__ios_push_notification, mcp__dev-toolkit__ios_grant_permission, mcp__dev-toolkit__ios_revoke_permission, mcp__dev-toolkit__ios_reset_permissions, mcp__dev-toolkit__ios_set_location, mcp__dev-toolkit__ios_clear_location, mcp__dev-toolkit__ios_set_increase_contrast, mcp__dev-toolkit__ios_record_video, mcp__dev-toolkit__ios_add_media, mcp__dev-toolkit__ios_keychain_reset, mcp__dev-toolkit__ios_get_app_container, mcp__dev-toolkit__ios_erase_device, mcp__dev-toolkit__ios_get_ui_tree, mcp__dev-toolkit__android_list_devices, mcp__dev-toolkit__android_screenshot, mcp__dev-toolkit__android_tap, mcp__dev-toolkit__android_swipe, mcp__dev-toolkit__android_type_text, mcp__dev-toolkit__android_key_event, mcp__dev-toolkit__android_launch_app, mcp__dev-toolkit__android_stop_app, mcp__dev-toolkit__android_list_packages, mcp__dev-toolkit__android_go_home, mcp__dev-toolkit__android_go_back, mcp__dev-toolkit__android_get_ui_tree, mcp__dev-toolkit__android_set_dark_mode, mcp__dev-toolkit__android_set_font_scale, mcp__dev-toolkit__android_set_locale, mcp__dev-toolkit__android_set_location, mcp__dev-toolkit__android_grant_permission, mcp__dev-toolkit__android_revoke_permission, mcp__dev-toolkit__android_record_screen, mcp__dev-toolkit__android_install_apk, mcp__dev-toolkit__android_uninstall_app, mcp__dev-toolkit__android_logcat, mcp__dev-toolkit__android_get_screen_size, mcp__dev-toolkit__android_open_url, mcp__dev-toolkit__android_clear_app_data
 ---
 
 # Mobile UI Bug Hunter
@@ -22,8 +22,8 @@ Auto-detects platform: iOS (simctl) or Android (adb). No external apps needed.
 5. If argument contains "android" or "ios" -> use that
 ```
 
-For iOS: use `mcp__dev_toolkit__ios_*` tools
-For Android: use `mcp__dev_toolkit__android_*` tools
+For iOS: use `mcp__dev-toolkit__ios_*` tools
+For Android: use `mcp__dev-toolkit__android_*` tools
 
 **Android extras**: `get_ui_tree` returns XML with bounds/text/resource-id (uiautomator dump), `logcat` for crash detection, `go_back` button.
 
@@ -134,11 +134,11 @@ Step A  -  run the standard visual + accessibility sweep (light + dark + large t
 Step B  -  dispatch compliance skill:
   iOS:
     Load pipeline/skills/shared/core/apple-archive-compliance/SKILL.md
-    Prereq: @mmerterden/dev-toolkit-mcp ≥ v2.4 (provides ios_app_store_audit MCP tool)
+    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" })
+    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:

package/pipeline/lib/credential-store.sh

@@ -84,10 +84,39 @@ require_cmd() {
   fi
 }
 
+# --- Logical key -> backend key --------------------------------------------
+# Callers pass a LOGICAL key ("github", "jira", "figma_pat"). The actual
+# Keychain / libsecret / Credential Manager entry is named by
+# prefs.global.keychainMapping, so a lookup that uses the logical key verbatim
+# finds nothing whenever the two differ -  silently, because a missing entry and
+# a missing mapping look identical from here. Resolve the mapping first and fall
+# back to the logical key when no mapping exists (backward compatible with
+# entries whose name already equals the logical key).
+PREFS_FILE="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+resolve_key() {
+  local logical="$1" mapped=""
+  if [ -f "$PREFS_FILE" ] && command -v python3 >/dev/null 2>&1; then
+    mapped=$(python3 -c '
+import json, sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        prefs = json.load(fh)
+except Exception:
+    sys.exit(0)
+name = prefs.get("global", {}).get("keychainMapping", {}).get(sys.argv[2])
+if isinstance(name, str) and name.strip():
+    sys.stdout.write(name.strip())
+' "$PREFS_FILE" "$logical" 2>/dev/null || true)
+  fi
+  printf '%s' "${mapped:-$logical}"
+}
+
 # --- Subcommands ------------------------------------------------------------
 do_get() {
   local key="${1:-}"
   [ -z "$key" ] && { echo "usage: $0 get <key>" >&2; exit 3; }
+  key=$(resolve_key "$key")
   if delegate_to_python; then
     local val rc
     val=$(python3 "$KEYCHAIN_PY" get "$key" 2>/dev/null) || rc=$?
@@ -128,6 +157,8 @@ if (\$c) { \$c.GetNetworkCredential().Password }
 do_set() {
   local key="${1:-}" val="${2:-}"
   [ -z "$key" ] && { echo "usage: $0 set <key> <value|->" >&2; exit 3; }
+  # Resolve through the same mapping as do_get so set/get stay symmetric.
+  key=$(resolve_key "$key")
   # "-" means: read the secret from stdin (keeps it off argv).
   if [ "$val" = "-" ]; then
     val=$(cat)
@@ -173,6 +204,7 @@ New-StoredCredential -Target '$key_esc' -UserName '${USER:-${USERNAME:-claude}}'
 do_delete() {
   local key="${1:-}"
   [ -z "$key" ] && { echo "usage: $0 delete <key>" >&2; exit 3; }
+  key=$(resolve_key "$key")
   if delegate_to_python; then
     python3 "$KEYCHAIN_PY" delete "$key" >/dev/null 2>&1 || true
     return 0

package/pipeline/lib/extract-conventions.sh

@@ -63,6 +63,7 @@ budget_exhausted() {
 
 # ---- skip dirs ----------------------------------------------------------------
 SKIP_PRUNE_ARGS=(
+  -path '*/.worktrees' -prune -o
   -path '*/.build' -prune -o
   -path '*/DerivedData' -prune -o
   -path '*/Pods' -prune -o

package/pipeline/lib/repo-cache.sh

@@ -212,6 +212,7 @@ print(json.dumps(out))
       find "$root" -maxdepth "$MAXDEPTH" -type d -name ".git" \
         \( -path "*/node_modules/*" -prune -o -path "*/.build/*" -prune -o \
            -path "*/DerivedData/*" -prune -o -path "*/Pods/*" -prune -o \
+           -path "*/.worktrees/*" -prune -o \
            -path "*/.next/*" -prune -o -print \) 2>/dev/null \
         | while read -r gitdir; do
             [ -n "$gitdir" ] || continue

package/pipeline/lib/shadow-git.sh

@@ -110,6 +110,13 @@ do_init() {
   if [ -f "$project_root/.gitignore" ]; then
     cat "$project_root/.gitignore" >> "$sd/.git/info/exclude"
   fi
+  # `.worktrees/` is forced-excluded too: worktrees live INSIDE the repo at
+  # <repo>/.worktrees/<id>/ and each carries a `.git` gitlink, so a blanket
+  # `add -A` would record every worktree as a "Subproject commit" and churn a
+  # fresh gitlink into every per-tool-call snapshot. The real clone keeps this
+  # out of its own index via .git/info/exclude; the shadow repo has its own
+  # exclude file and must repeat the rule. This mirrors the traversal-prune
+  # contract in phase-0-init.md (never descend into .worktrees on a tree walk).
   cat >> "$sd/.git/info/exclude" <<EOF
 node_modules/
 Pods/
@@ -119,6 +126,7 @@ DerivedData/
 .gradle/
 __pycache__/
 .venv/
+.worktrees/
 *.log
 EOF
   # Initial author setup  -  keep separate from user's global git identity to

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

@@ -6,10 +6,10 @@
 
 ---
 
-## 1. Command Inventory (41 commands)
+## 1. Command Inventory (42 commands)
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
@@ -43,7 +43,7 @@ Two parallel shared/core skills under `pipeline/skills/shared/core/` wrap extern
 
 | Skill | Path | Tool wrapper | Rules |
 |---|---|---|---|
-| `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/dev-toolkit-mcp` ≥ v2.4) | 17 (Apple ITMS + App Store Review Guidelines) |
+| `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/dev-toolkit-mcp` ≥ v2.9.0) | 18 (Apple ITMS + App Store Review Guidelines) |
 | `google-play-compliance` | `pipeline/skills/shared/core/google-play-compliance/` | bundletool + aapt2 + apksigner | 21 (4 categories: Technical / Security / Privacy / Hygiene) |
 
 Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 4 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh` (46 assertions).

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

@@ -450,7 +450,7 @@ fi
 
 If the path is still registered and healthy after the heal, enter + pull instead of re-adding (existing behavior). Only when `worktree add` still fails after the heal do the rollback / collision flow in the multi-repo block below.
 
-**Worktree residue guard (required once per repo, idempotent):** every worktree dir contains a `.git` file, so a blanket `git add -A` / `git add .` in the parent tree records `.worktrees/{id}` as a gitlink ("Subproject commit ...") that pollutes the branch and later needs a manual removal commit. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise in shared repos):
+**Worktree residue guard (required once per repo, idempotent):** every worktree dir holds a `.git` file, so a blanket `git add -A` in the parent tree records `.worktrees/{id}` as a gitlink that pollutes the branch. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise):
 
 ```bash
 ex="$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
@@ -458,6 +458,14 @@ mkdir -p "$(dirname "$ex")"
 grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"
 ```
 
+**Traversal-prune contract:** the exclude guard covers only the git INDEX, not
+filesystem scans. Since each worktree is a full checkout, an unpruned tree walk
+double-processes every file and can re-stage gitlinks. So `.worktrees` joins the
+skip set (`node_modules`, `Pods`, `.build`, `DerivedData`, `.next`): every
+`find`, walker, or `git add -A` MUST prune it. Already applied in the Step 2
+scan, `shadow-git.sh` excludes, and the shared walkers (`extract-conventions.sh`,
+`repo-cache.sh`, `repo-map.mjs`); add it to any new tree walk too.
+
 **v2.1.0+ Multi-Repo Worktree Setup**:
 
 When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (worktrees are cheap; serial keeps git index sane and surfaces collisions one at a time):

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -164,7 +164,7 @@ For each task (respecting dependency order):
    **Preferred  -  MCP tool (token-efficient, dev-toolkit-mcp ≥ 2.3.0):**
    ```
    acquire_build_lock "$TASK_ID"
-   mcp__dev_toolkit__ios_xcodebuild({
+   mcp__dev-toolkit__ios_xcodebuild({
      project: "{projectPath}",        // or workspace
      scheme: "{scheme}",
      configuration: "Release",
@@ -173,7 +173,7 @@ For each task (respecting dependency order):
    })
    release_build_lock
    ```
-   Returns one line: `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`. On failure, drill in only when needed via `mcp__dev_toolkit__ios_xcresult({id, mode: "errors"})`. Saves thousands of tokens per build cycle vs. raw xcodebuild output.
+   Returns one line: `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`. On failure, drill in only when needed via `mcp__dev-toolkit__ios_xcresult({id, mode: "errors"})`. Saves thousands of tokens per build cycle vs. raw xcodebuild output.
 
    **Fallback  -  raw xcodebuild** (when MCP server is unavailable):
    ```bash

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -414,11 +414,12 @@ At the end of every fix/rework round (each Phase 3 re-entry that resolved accept
 
 ```bash
 node pipeline/scripts/learnings-ledger.mjs add --kind fact \
-  --statement "<one-line root cause: what class of mistake produced the finding and why (<=140 chars)>" \
+  --statement "<one-line rule/what-to-do so this class of finding does not recur (<=140 chars)>" \
+  --diagnosis "<the causal WHY the failure happened, one line>" \
   --scope "<file-or-area glob from the finding>" --task "$TASK_ID"
 ```
 
-Statement shape: root cause, not symptom  -  "force-unwrapped optional in async callback path", not "fixed crash in LoginView". Dedup built in (exit 2 = already stored, skip). Lessons re-enter Phase 1 + triage via `learnings-ledger.mjs brief`.
+Statement shape: the durable rule/root cause, not the symptom  -  "force-unwrapped optional in async callback path", not "fixed crash in LoginView". Always pass `--diagnosis` with the causal why (Reflexion: the verbal reason prevents recurrence; a bare outcome does not). Dedup built in (exit 2 = already stored). Lessons re-enter Phase 1 + triage via `learnings-ledger.mjs brief` (renders diagnosis as "(why: ...)").
 
 Progress line: `    → writing lesson to learnings ledger ({N} entries)`
 

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -103,6 +103,16 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:finish` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs").
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
+   - **Heal stale admin state first** (same contract as Phase 0  -  step 3's
+     `worktree remove` or an interrupted run can leave a stale entry, so a bare
+     re-add fails with `already exists`/`already registered`):
+     ```bash
+     git -C "$PROJECT_ROOT" worktree prune 2>/dev/null || true
+     if git -C "$PROJECT_ROOT" worktree list --porcelain | grep -qF "{worktree-path}"; then
+       git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
+     fi
+     ```
+     Phase 0's `.worktrees/` residue guard is already in `.git/info/exclude`  -  no re-add.
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 3
@@ -116,12 +126,12 @@ Before or during user testing, run device-level audits via Bash if user requests
 
 | Check               | When              | Command                                   |
 | ------------------- | ----------------- | ----------------------------------------- |
-| Accessibility audit | UI changes        | `mcp__dev_toolkit__ios_accessibility_audit` (or `swift ui-tree-dumper.swift`) |
-| Biometric test      | Auth flow changes | `mcp__dev_toolkit__ios_biometric` (or `xcrun simctl keychain biometric-match`) |
+| Accessibility audit | UI changes        | `mcp__dev-toolkit__ios_accessibility_audit` (or `swift ui-tree-dumper.swift`) |
+| Biometric test      | Auth flow changes | `mcp__dev-toolkit__ios_biometric` (or `xcrun simctl keychain biometric-match`) |
 | Launch time         | Android project   | `adb shell am start -W`                   |
 | Visual test         | Any UI changes    | `/multi-agent test` (sim-test)            |
-| Snapshot regression | Component / pixel-stable UI changes | `mcp__dev_toolkit__ios_visual_diff` (dev-toolkit-mcp ≥ 2.3.0) |
-| App Store screenshots | `taskType === screenshot` | `mcp__dev_toolkit__ios_status_bar({preset: "clean"})` before each capture |
+| Snapshot regression | Component / pixel-stable UI changes | `mcp__dev-toolkit__ios_visual_diff` (dev-toolkit-mcp ≥ 2.3.0) |
+| App Store screenshots | `taskType === screenshot` | `mcp__dev-toolkit__ios_status_bar({preset: "clean"})` before each capture |
 
 Results included in Phase 7 report. MCP tools preferred when available  -  concise structured output, lower token cost.
 

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

@@ -149,6 +149,8 @@ Each phase doc is lazy-loaded  -  only the current phase's spec is in context. B
 
 Token estimate: `ceil(chars / 4)`. Budget covers phase-\*.md files only. Guides, rules, and agents are loaded separately on demand.
 
+**Prompt caching (token learning-curve):** assemble each phase prompt as a stable, cacheable prefix (phase instructions + repo learnings brief + conventions + repo evidence) followed by the volatile task suffix, so repeated runs on a known repo pay cache-read price on the prefix. Full contract: `$HOME/.claude/multi-agent-refs/prompt-assembly.md`. The effect (rising cache ratio, falling tokens/task) is what `learning-curve.mjs` trends.
+
 ## SubPhase Convention
 
 When a specialized skill takes over a main pipeline phase, progress is reported as **SubPhases** nested under the parent. Top-level stays 8 phases (0-7); specialized flows get sub-phase detail.

package/pipeline/multi-agent-refs/prompt-assembly.md

@@ -0,0 +1,31 @@
+# Prompt assembly: stable-prefix caching (token learning-curve)
+
+Anthropic prompt caching is **prefix-based**: the longest unchanged leading span of a request is served from cache at a large discount on repeated calls. As the pipeline accumulates durable knowledge about a repo (conventions, learnings brief, repo evidence), that knowledge should become a near-free cached prefix instead of a growing per-run token cost. This is the mechanism that makes "knowing the repo better" literally cheaper each run.
+
+## The rule
+
+Assemble every phase prompt as two spans, in this order:
+
+1. **Stable prefix (cacheable, repo-stable, changes rarely):**
+   - system / role instructions for the phase
+   - the repo learnings brief (`learnings-ledger.mjs brief`)
+   - extracted conventions (Phase 1c) and the design/analysis doc when applicable
+   - repo structural evidence (the reuse-first buckets, Code Connect index)
+2. **Volatile suffix (task-specific, changes every run):**
+   - the specific task / issue / diff
+   - the current file(s) under edit
+   - per-run state and the immediate instruction
+
+Put the stable material FIRST and the volatile material LAST. Reordering volatile content into the middle of the prefix invalidates the cache for everything after it, so keep the boundary clean.
+
+## Why it matters
+
+- Repeated runs on the same repo pay roughly cache-read price (~10% of input) on the stable prefix instead of full price - the dominant per-run token cost once a repo is "known."
+- It turns accumulated learnings from a cost into an asset: more durable knowledge => bigger cached prefix => lower marginal cost, not higher.
+- The effect is visible in `metrics.jsonl` `tokens_cached` / `cache_ratio` and is exactly what `learning-curve.mjs` trends over time (rising cache ratio + falling tokens/task = the learning curve working).
+
+## Anti-patterns
+
+- Interleaving the task text with conventions/learnings (breaks the prefix).
+- Letting the stable prefix bloat past what the phase needs (context rot; cache a lean prefix, not everything - see the corpus merge/drop + progressive-disclosure discipline).
+- Regenerating repo evidence from scratch each run instead of reusing cached/learned artifacts (defeats both the cache and the learning curve).

package/pipeline/preferences-template.json

@@ -73,7 +73,12 @@
       "onExceed": "warn",
       "pricingModel": "opus"
     },
-    "derivedSkillSources": []
+    "derivedSkillSources": [],
+    "devToolkit": {
+      "enabled": true,
+      "mcpServerName": "dev-toolkit",
+      "registry": "github-packages"
+    }
   },
   "projects": {},
   "_figmaConfigTemplate": {
@@ -170,5 +175,17 @@
       "derivedFromVersion": "0.0.0",
       "upstreamRepoUrl": "https://github.com/<org>/<repo>"
     }
+  },
+  "_devToolkitTemplate": {
+    "_comment": "Optional. global.devToolkit points at the companion MCP server that serves the pipeline's device and browser tools. /multi-agent:refactor Step 0c researches current MCP practice and audits that repo against it (plan band E); /multi-agent:sync Step 3d ships it when it moved (gates, commit, publish). Leave localPath out and both commands auto-detect the repo from your mcpServers registration; set enabled:false to skip both.",
+    "_example": {
+      "enabled": true,
+      "label": "dev-toolkit MCP server",
+      "localPath": "$HOME/<repo-dir>",
+      "mcpServerName": "dev-toolkit",
+      "packageName": "@<scope>/<package>",
+      "registry": "github-packages",
+      "repoUrl": "https://github.com/<owner>/<repo>"
+    }
   }
 }