@mmerterden/multi-agent-pipeline 16.31.0 → 17.0.0

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

@@ -817,13 +817,21 @@ Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` mark
    ```bash
    claude marketplace add {owner}/multi-agent-plugins 2>/dev/null || true
    ```
-2. Detect the project stack from markers and enable the matching plugin(s) plus the two always-on plugins in the project's `.claude/settings.json` `enabledPlugins`:
-   - `.xcodeproj` / `Package.swift` / `*.xcworkspace` → `ai-ios-toolkit`
-   - `build.gradle` / `settings.gradle` → `ai-android-toolkit`
-   - `package.json` with `react`/`next` → `ai-frontend-toolkit`
-   - `requirements.txt` / `pyproject.toml` / server `package.json` → `ai-backend-toolkit`
-   - **no clear marker → default `ai-ios-toolkit`**
-   `ai-common-toolkit@multi-agent-plugins` and `ai-analyst-toolkit@multi-agent-plugins` are always set `true` alongside the stack plugin: neither is stack-specific.
+2. Ask the detector, then derive. No marker list here: a second list is a second
+   answer, and this one defaulted to `ai-ios-toolkit` when nothing matched - how
+   a Next.js site and several Node CLIs ended up with the iOS toolkit.
+
+   ```bash
+   eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS, MA_STACK_WHY
+   node -e 'import(process.env.HOME+"/.claude/scripts/_stack-routing.mjs").then(m=>
+     console.log(m.pluginsForStacks(process.argv[1].split(" ").filter(Boolean)).plugins.join(" ")))' "$MA_STACKS"
+   ```
+
+   Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
+   `ai-analyst-toolkit` are in every answer, the empty one included: neither is
+   stack-specific. **No marker matched is an answer** - those two, not a guess.
+   A name the marketplace does not carry is dropped with `dropped[]` naming it,
+   so a toolkit that was never shipped is caught before it fails to load.
 3. Report the enabled set. To change later, run `/multi-agent:stack <ios|android|web|backend|...>` in the repo. Pipeline Phase 1 auto-detects the stack for its own routing regardless of enablement.
 
 The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork - nothing in the pipeline is coupled to a specific account.

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

@@ -29,17 +29,26 @@ This replaces the old `stack-swap.sh` mechanic that physically moved skill direc
 
 ## Stack → plugin map
 
-| Stack | Plugins enabled (all `@multi-agent-plugins`) |
-|---|---|
-| `ios` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-ios-toolkit` |
-| `android` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-android-toolkit` |
-| `web` / `frontend` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-frontend-toolkit` |
-| `backend` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-backend-toolkit` |
-| `mobile` | common + `ai-ios-toolkit` + `ai-android-toolkit` |
-| `fullstack` | common + `ai-frontend-toolkit` + `ai-backend-toolkit` |
-| `all` | common + all four stack toolkits |
-
-Multiple args union their plugin sets: `ios backend` → common + iOS + backend.
+Derived, not listed. `pluginsForStacks()` in `scripts/_stack-routing.mjs` owns
+it, and this file deliberately carries no copy: the mapping was written out by
+hand in four places, and every copy is a chance to get the one asymmetry wrong -
+the detector says `web`, the marketplace ships `ai-frontend-toolkit`.
+
+```bash
+node -e 'import(process.env.HOME+"/.claude/scripts/_stack-routing.mjs").then(m=>{
+  const st=process.argv.slice(1).flatMap(a=>m.expandStackArg(a));
+  if(!st.length){console.error("Unknown stack. One of: "+m.KNOWN_STACKS.join(" ")+" mobile fullstack all");process.exit(1);}
+  const r=m.pluginsForStacks(st);
+  if(r.dropped.length) console.error("not in the marketplace, dropped: "+r.dropped.join(" "));
+  console.log(r.plugins.join(" "));
+})' "$@"
+```
+
+`ai-common-toolkit` and `ai-analyst-toolkit` are in every answer, including the
+empty one: neither is stack-specific. Multiple args union their sets, and the
+aliases (`frontend`, `mobile`, `fullstack`, `all`) expand in the module so
+`/multi-agent:stack mobile` cannot mean one thing here and another in the
+installer.
 
 ## Behaviour
 
@@ -70,13 +79,6 @@ if ! claude marketplace list 2>/dev/null | grep -q "$MP"; then
     || echo "note: add the marketplace once with: claude marketplace add {owner}/multi-agent-plugins"
 fi
 
-COMMON="ai-common-toolkit@${MP}"
-ANALYST="ai-analyst-toolkit@${MP}"
-IOS="ai-ios-toolkit@${MP}"
-ANDROID="ai-android-toolkit@${MP}"
-WEB="ai-frontend-toolkit@${MP}"
-BACKEND="ai-backend-toolkit@${MP}"
-
 # Enable-mode only: with zero args the write rules below would set every stack
 # toolkit to false (nothing but the always-on pair is in $ON), silently wiping the repo's
 # selection. No args belongs to the picker / status path (Behaviour step 1).
@@ -85,20 +87,17 @@ if [ "$#" -eq 0 ]; then
   exit 0
 fi
 
-# resolve every arg through the alias table, union the ON set
-ON="$COMMON $ANALYST"
-for ARG in "$@"; do
-  case "$ARG" in
-    ios)              ON="$ON $IOS" ;;
-    android)          ON="$ON $ANDROID" ;;
-    web|frontend)     ON="$ON $WEB" ;;
-    backend)          ON="$ON $BACKEND" ;;
-    mobile)           ON="$ON $IOS $ANDROID" ;;
-    fullstack)        ON="$ON $WEB $BACKEND" ;;
-    all)              ON="$ON $IOS $ANDROID $WEB $BACKEND" ;;
-    *) echo "Unknown stack '$ARG'. One of: ios android mobile backend web fullstack all"; exit 1 ;;
-  esac
-done
+# resolve every arg and derive the ON set - one owner, see the map above.
+# The marketplace suffix is appended INSIDE node: `$ON` is a single string, and
+# re-splitting it in the shell to suffix each name is the zsh word-splitting trap
+# (`printf %s@x $ON` suffixes the whole string, not each word).
+ON=$(MP="$MP" node -e 'import(process.env.HOME+"/.claude/scripts/_stack-routing.mjs").then(m=>{
+  const st=process.argv.slice(1).flatMap(a=>m.expandStackArg(a));
+  if(!st.length){console.error("Unknown stack. One of: "+m.KNOWN_STACKS.join(" ")+" mobile fullstack all");process.exit(1);}
+  const r=m.pluginsForStacks(st);
+  if(r.dropped.length) console.error("not in the marketplace, dropped: "+r.dropped.join(" "));
+  console.log(r.plugins.map(p=>p+"@"+process.env.MP).join(" "));
+})' "$@") || exit 1
 ```
 
 After resolving `$ON`, edit `.claude/settings.json` (create `{ "enabledPlugins": {} }` if absent) so that:

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

@@ -22,7 +22,23 @@ Show every active and completed task as a table.
 3. **Parse state**  -  for each task:
    - `taskId`, `branch`, `currentPhase`, `status`, `startedAt`, `autopilot`
 
-4. **Render as a table**:
+3b. **Sort into three groups, and label them.** `in_progress` alone cannot tell
+   a run that is waiting for you from one that died, and on this machine that
+   difference covered 20 runs: 3 were holding at Phase 6/7 with their PR already
+   open, 11 were left at a Phase 0 question with nothing built, 6 stopped
+   mid-development. One "in progress" label for all three is what made a
+   finished job and a crashed one share a row.
+
+   | Group | Test | Action offered |
+   |---|---|---|
+   | Waiting on you | `status == "awaiting_input"`, or a `pr.url`, or phase 6/7 | `resume #N` - the work landed, it needs your answer |
+   | Stopped mid-development | anything else past phase 0 | `resume #N` or `kill #N` |
+   | Left at a question | phase 0 | `garbage-collect --abandoned` - nothing was built |
+
+   A run with no `status` is **not** placed in any group. Unknown is not a
+   finding, and calling it dead is the same false claim in the other direction.
+
+4. **Render as a table**, grouped per 3b, with the group as a section heading:
    ```
    🤖 Multi-Agent Tasks
 

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, website, and the multi-agent-toolkit MCP server. Use when work is finished and should be propagated across Claude Code, Copilot CLI, the repos, the website and the multi-agent-toolkit server."
 description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo, website ve multi-agent-toolkit MCP sunucusu."
-argument-hint: "[release] [multi-agent-toolkit] [--platform=<macos|linux|windows>]"
+argument-hint: "[release] [multi-agent-toolkit]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 ---
 
@@ -9,7 +9,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 
 **One command. Full ecosystem sync. No arguments needed.**
 
-When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and returns a result report. The host platform (macOS / Linux / Windows) is auto-detected; all dispatch commands stay platform-agnostic through `~/.claude/lib/credential-store.sh`.
+When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and returns a result report. macOS only (ADR-0012); credential access goes through `~/.claude/lib/credential-store.sh` so no call site names the keychain backend.
 
 **Input**: $ARGUMENTS (optional)
 
@@ -18,7 +18,6 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, multi-agent-toolkit MCP server. |
 | `release` | Full sync + version bump + tag + npm publish + website deploy (plus the multi-agent-toolkit ship path) |
 | `multi-agent-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 |
 
 ## Targets
@@ -32,25 +31,32 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | 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 |
 
-## Platform Support (macOS / Linux / Windows)
+## Platform Support (macOS only)
 
-The sync skill must run on all three platforms. Commands go through the platform-agnostic shell layer; the following compatibility rules are preserved for every target:
+v17.0.0 removed Linux and Windows (ADR-0012). `package.json` declares
+`os: ["darwin"]`, which npm enforces on the root package, so this tree cannot be
+installed elsewhere - a detection table for hosts that cannot run the installer
+would be a table the agent executes against a case that no longer exists.
 
-| Platform | Detection | Implication |
-|---|---|---|
-| macOS | `[[ "$OSTYPE" == "darwin"* ]]` | Default. BSD `stat -f %m`, `security` for Keychain. |
-| Linux | `[[ "$OSTYPE" == "linux"* ]]` | GNU `stat -c %Y`, `secret-tool` for Keychain (libsecret). |
-| Windows (Git Bash / MSYS2) | `[[ "$OSTYPE" == "msys" \|\| "$OSTYPE" == "cygwin" ]]` | `~` resolves to `/c/Users/<name>`. Powershell `CredentialManager` for Keychain. POSIX paths inside Git Bash. |
-| Windows (WSL) | `grep -qi microsoft /proc/version` | Linux toolchain inside WSL. Hostname format `WSL2-...`. |
-
-**Cross-platform contract for synced shell scripts:**
+**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. Timestamps: try BSD `stat -f` first, fall back to GNU `stat -c`  -  both already covered by `~/.claude/lib/repo-cache.sh` pattern.
-3. `find` traversal: include `-prune` for `node_modules`, `Pods`, `.build`, `DerivedData`, `.next`  -  same on every platform.
-4. Sed / awk: prefer POSIX-portable invocations. Avoid GNU-only `-i` without `''` on macOS or `-r` (use `-E` instead).
-5. Keychain I/O: always via `~/.claude/lib/credential-store.sh get|set`  -  never call `security` / `secret-tool` / `gcm` directly.
-6. Verification: after Step 3 (REPO), run `bash -n` on every shell script in `pipeline/lib/` and `pipeline/scripts/` to surface portability regressions early.
+2. `grep -P` is banned. BSD grep has no `-P`: it exits 2, and with `2>/dev/null`
+   that reads as "found nothing". Two gates have already shipped green for
+   exactly this reason. 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/`.
 
 ## Default Behavior (no arguments)
 
@@ -58,7 +64,6 @@ Run every step automatically:
 
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
-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 + 53 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 53 specs as refs + 8 agent TOML)
@@ -384,8 +389,8 @@ 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 |
-| `mmerterden_Github_Auth_Token` | personal | `admin:public_key, gist, read:org, repo`  -  no `write:packages` |
-| `gh auth token -u mmerterden` | personal | `gist, read:org, repo, workflow, write:packages` ✓ |
+| 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:**
 

package/pipeline/lib/account-resolver.sh

@@ -8,7 +8,7 @@
 # that precedes the provider segment. Examples:
 #   ${USER}_Github_Access_Token        -> prefix=${USER}
 #   ${USER}_Tktech_Github_Access_Token -> prefix=${USER}_Tktech
-#   personal_Github_Auth_Token        -> prefix=personal
+#   {prefix}_Github_Auth_Token         -> prefix={prefix}
 #
 # Usage:
 #   ./account-resolver.sh             # JSON array

package/pipeline/lib/stack-detect.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# stack-detect.sh  -  answer "what is this repo built with" from the repo itself.
+#
+# Why this exists: `/multi-agent:stack` writes `enabledPlugins` and a human picks
+# the stack. When that conversation never happens the repo inherits the global
+# setting, and on the machine this was written against only 3 of 25 checkouts had
+# ever had it - so a Next.js site and several Node CLIs were all routed to the iOS
+# toolkit. An unsupervised run has nobody to notice.
+#
+# So: infer, deterministically, from file markers - never a model call - so the
+# same repo always answers the same way and the answer can be shown with its
+# reason.
+#
+# This file answers ONE question: which of `ios android web backend` describes
+# this repo. It deliberately does not know plugin names. "Which plugin carries a
+# stack" is a different question with a different owner
+# (`pipeline/scripts/_stack-routing.mjs`), and the two were one table here until
+# that put a tenth copy of the stack-to-plugin mapping in the tree - the exact
+# duplication `multi-agent-refs/stack-skill-routing.md` exists to prevent.
+#
+# Usage:
+#   . stack-detect.sh; ma_stack_detect <repo-root>   # sets MA_STACKS, MA_STACK_WHY
+#   bash stack-detect.sh <repo-root>                 # prints KEY=VALUE
+#   bash stack-detect.sh --json <repo-root>
+#
+# Output: MA_STACKS is a space-separated subset of `ios android web backend`, in
+# that fixed order so two runs on the same repo produce the same string. Empty is
+# a real answer and means "no marker matched", NOT "not looked" - MA_STACK_WHY
+# distinguishes them, because a caller that cannot tell those apart will treat an
+# unreadable directory as a language-free repo.
+
+# Markers whose mere presence decides a stack, as data rather than a `case`
+# cascade: `stack:glob:maxdepth`. Adding a language is one line here, which is
+# the point - a contributor who has to edit control flow to add Rust will
+# instead widen somebody else's regex.
+#
+# Not every rule fits this shape, and forcing the two that do not would be worse
+# than keeping them in code: Android is decided by FILE CONTENT (Gradle alone is
+# a JVM service), and one package.json can be web, backend or both. Those two
+# run after the table, with their reasoning at the point of decision.
+MA_STACK_MARKERS="\
+ios:Package.swift:3
+ios:*.xcodeproj:3
+ios:*.xcworkspace:3
+ios:Podfile:3
+web:vite.config.*:3
+web:nuxt.config.*:3
+web:angular.json:3
+web:svelte.config.*:3
+backend:requirements.txt:3
+backend:pyproject.toml:3
+backend:go.mod:3
+backend:Cargo.toml:3
+backend:pom.xml:3"
+
+# Dependency names that decide which side of one package.json a repo is on. A
+# Next app with API routes is honestly both, so both may be recorded.
+MA_STACK_WEB_DEPS='"(react|next|vue|svelte|@angular/core|solid-js|astro|preact|remix)"[[:space:]]*:'
+MA_STACK_BACKEND_DEPS='"(express|fastify|@nestjs/core|koa|hapi|@trpc/server|apollo-server)"[[:space:]]*:'
+
+ma_stack_detect() {
+  local root="${1:-$PWD}"
+  MA_STACKS=""
+  MA_STACK_WHY=""
+
+  if [ -z "$root" ] || [ ! -d "$root" ]; then
+    MA_STACK_WHY="unreadable: $root"
+    return 1
+  fi
+  # Strip trailing slashes before anything builds a path from $root. `find`
+  # prints `<root>/x`, so a root ending in `/` makes every `-path "$root/$sub"`
+  # prune carry a double slash and match nothing - the submodule prune then
+  # silently does not fire, and a vendored Package.swift reports a Compose app
+  # as iOS. A caller passing a directory with a trailing slash is normal.
+  while [ "${root%/}" != "$root" ] && [ "$root" != "/" ]; do root="${root%/}"; done
+
+  # Submodule paths are pruned: a vendored checkout is somebody else's repo and
+  # its markers are not this repo's stack. Measured, not theorised - the Android
+  # app vendors the shared configuration repo, which ships a Package.swift, and a
+  # depth-first scan reported that Compose app as an iOS repo.
+  local _prunes=(
+    -name node_modules -o -name .build -o -name Pods -o -name build -o -name dist
+    -o -name .next -o -name .gradle -o -name DerivedData -o -name .worktrees
+    -o -name .git -o -name vendor -o -name Carthage
+  )
+  local _sub _subs=()
+  if [ -f "$root/.gitmodules" ]; then
+    while IFS= read -r _sub; do
+      [ -n "$_sub" ] && _subs+=(-o -path "$root/$_sub")
+    done <<< "$(sed -n 's/^[[:space:]]*path[[:space:]]*=[[:space:]]*//p' "$root/.gitmodules" 2>/dev/null)"
+  fi
+
+  # The repo ROOT is checked before anything deeper, and that ordering is the
+  # whole correctness argument: the root manifest is the repo's own declaration,
+  # while every deeper hit belongs to a submodule, a build output or a vendored
+  # dependency. Without it the answer is decided by `find` traversal order, which
+  # is arbitrary - it read a generated .next/package.json as a Next.js app's
+  # manifest and found no framework in it.
+  _ma_has() { # $1 = -name pattern; prints the first hit, empty when none
+    local _g
+    for _g in "$root"/$1; do
+      [ -e "$_g" ] && {
+        printf '%s\n' "$_g"
+        return 0
+      }
+    done
+    # No -mindepth here, deliberately. -mindepth suppresses predicate evaluation
+    # for shallower entries, so with -mindepth 2 the prune never fired on a
+    # depth-1 submodule directory and find walked straight into it. The root glob
+    # above already returned any root-level hit, so re-visiting depth 1 is free.
+    find "$root" -maxdepth "${2:-3}" \
+      -type d \( "${_prunes[@]}" "${_subs[@]}" \) -prune -o \
+      -name "$1" -print 2>/dev/null | head -1
+  }
+
+  _ma_add() { # $1 = stack, $2 = why-suffix
+    case " $MA_STACKS " in *" $1 "*) return 0 ;; esac
+    MA_STACKS="${MA_STACKS:+$MA_STACKS }$1"
+    _why="${_why:+$_why }$1<-$2"
+  }
+
+  local _why="" hit row stack pat depth
+
+  # --- table markers ----------------------------------------------------
+  while IFS=: read -r stack pat depth; do
+    [ -n "$stack" ] || continue
+    case " $MA_STACKS " in *" $stack "*) continue ;; esac
+    hit=$(_ma_has "$pat" "$depth")
+    [ -n "$hit" ] && _ma_add "$stack" "${hit##*/}"
+  done <<EOF
+$MA_STACK_MARKERS
+EOF
+
+  # --- android, by content ----------------------------------------------
+  # Gradle alone does NOT mean Android - a JVM service builds with Gradle too.
+  # AndroidManifest.xml or the Android Gradle plugin is what separates them, and
+  # getting this wrong loads the Compose toolkit onto a Spring repo.
+  # AndroidManifest.xml lives at <module>/src/main/, which is depth 4 in every
+  # multi-module app, so this one search goes deeper than the rest.
+  hit=$(_ma_has "AndroidManifest.xml" 5)
+  if [ -z "$hit" ]; then
+    # A version catalogue is where a modern build declares the Android plugin;
+    # the root build.gradle.kts of the reference app names it nowhere.
+    local g
+    for g in "$root/gradle/libs.versions.toml" "$(_ma_has 'build.gradle*')" "$(_ma_has 'settings.gradle*')"; do
+      [ -n "$g" ] && [ -f "$g" ] || continue
+      if grep -qE "com\.android\.(application|library)|androidx|\bagp\b" "$g" 2>/dev/null; then
+        hit="$g"
+        break
+      fi
+    done
+  fi
+  [ -n "$hit" ] && _ma_add "android" "${hit##*/}"
+
+  # --- web / backend, by dependency -------------------------------------
+  local pkg
+  pkg=$(_ma_has "package.json")
+  if [ -n "$pkg" ]; then
+    local is_web=0
+    grep -qE "$MA_STACK_WEB_DEPS" "$pkg" 2>/dev/null && is_web=1
+    [ "$is_web" -eq 1 ] && _ma_add "web" "package.json"
+    if grep -qE "$MA_STACK_BACKEND_DEPS" "$pkg" 2>/dev/null; then
+      _ma_add "backend" "package.json"
+    elif [ "$is_web" -eq 0 ]; then
+      # A package.json with no web framework is still a Node project, and the
+      # backend toolkit is the one that covers Node. Reporting nothing here would
+      # send the caller to its no-marker fallback for a repo whose language is
+      # not in doubt.
+      _ma_add "backend" "package.json(node)"
+    fi
+  fi
+
+  # Fixed order, so the same repo always yields the same string.
+  local ordered="" s
+  for s in ios android web backend; do
+    case " $MA_STACKS " in *" $s "*) ordered="${ordered:+$ordered }$s" ;; esac
+  done
+  MA_STACKS="$ordered"
+  MA_STACK_WHY="${_why:-no marker matched}"
+  unset -f _ma_has _ma_add
+  return 0
+}
+
+if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
+  _json=0
+  case "${1:-}" in --json)
+    _json=1
+    shift
+    ;;
+  esac
+  ma_stack_detect "${1:-$PWD}" || true
+  if [ "$_json" -eq 1 ]; then
+    _arr=""
+    for _s in $MA_STACKS; do _arr="${_arr:+$_arr,}\"$_s\""; done
+    printf '{"stacks":[%s],"why":"%s"}\n' "$_arr" "$MA_STACK_WHY"
+  else
+    printf 'MA_STACKS=%s\n' "$(printf '%q' "$MA_STACKS")"
+    printf 'MA_STACK_WHY=%s\n' "$(printf '%q' "$MA_STACK_WHY")"
+  fi
+fi

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

@@ -297,20 +297,39 @@ Modifier flags are orthogonal and compose:
 
 ---
 
-## 7. Platform Guards (macOS / Linux / WSL)
+## 7. Platform Guards (macOS)
 
-All three CLIs run on macOS, Linux and Windows, so any command may execute on any of them. (This line used to say Claude Code was macOS-only; it has not been true for some time, and the assumption it invited - that a Windows user necessarily arrives through Copilot or Codex - produces wrong conclusions about which paths need to be portable.) Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
+All three CLIs are installed from this package, and `package.json` declares
+`os: ["darwin"]` (ADR-0012), so every command executes on macOS. That is not a
+licence to stop being careful about shell: the runtime is **BSD userland and
+bash 3.2**, which is a narrower target than "portable", and three constructs
+below exist because the BSD form silently differs rather than failing.
 
-For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on those installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`**
+(or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on
+those installs). Call sites never invoke `security` themselves - the wrapper is
+what keeps a secret off argv and what writes the audit entry.
 
-| Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
+| Purpose | Canonical | Underlying backend (for debugging only) |
 |---|---|---|
-| Keychain read | `~/.claude/lib/credential-store.sh get <key>` | macOS: `security find-generic-password -a "$USER" -s <key> -w` · Linux: `secret-tool lookup account "$USER" service <key>` · Windows: PowerShell `Get-StoredCredential` |
-| Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin) | macOS: `security add-generic-password -a "$USER" -s <key> -w "$VAL"` · Linux: `secret-tool store --label=<key> account "$USER" service <key>` · Windows: `New-StoredCredential` |
-| Clipboard read |  -  (still needs a per-platform branch  -  there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
-| Clipboard clear |  -  | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
-
-For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in skill bash blocks.
+| Keychain read | `~/.claude/lib/credential-store.sh get <key>` | `security find-generic-password -a "$USER" -s <key> -w` |
+| Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin, keeping it off argv) | `security add-generic-password -a "$USER" -s <key> -w` |
+| Clipboard read | `pbpaste` | -  |
+| Clipboard clear | `pbcopy < /dev/null` | -  |
+
+**The three that bite on BSD**, and why each is a rule rather than a preference:
+
+- PCRE mode is absent from BSD grep, and is banned here. It exits 2, which under
+  `2>/dev/null` reads as "found nothing" - two gates shipped green for exactly
+  that reason. Use `-E`.
+- `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.
+- `sed -E`, never `-r`; `sed -i ''` when editing in place.
+
+Clipboard callers may use `pbpaste` / `pbcopy` directly; the three-way
+`command -v` guard they used to carry was for hosts this package no longer
+installs on.
 
 ---
 

package/pipeline/multi-agent-refs/features/doctor.md

@@ -25,9 +25,9 @@ resolver as a clean bill.
 
 **A state in which a run will fail or leak. Not a state in which it will merely
 be worse.** Without a closed definition "blocked" grows until nobody respects
-exit 2, so only five checks can produce it: `install-present`, `script-surface`,
-`state-writable`, `prefs-valid` and `embedded-credentials`. Every other check
-tops out at WARN however bad it looks.
+exit 2, so only six checks can produce it: `host-platform`, `install-present`,
+`script-surface`, `state-writable`, `prefs-valid` and `embedded-credentials`.
+Every other check tops out at WARN however bad it looks.
 
 ## Who calls it, and what they do with the code
 
@@ -91,6 +91,18 @@ its host; everything after that is behind `--explain`.
 
 ## Checks
 
+### host-platform
+
+The host is macOS. BLOCK otherwise: every credential read shells `security`,
+every iOS build shells `xcodebuild`, every piece of visual evidence shells
+`simctl`, so a run on another platform does not degrade, it fails partway
+through with a worktree and a branch already created (ADR-0012).
+
+It runs **first**, before `install-present`, so an unsupported host reads one
+line naming the cause instead of a cascade of consequences. The step names the
+`MULTI_AGENT_ALLOW_NON_DARWIN=1` escape, which the entry points honour and
+nothing tests.
+
 ### install-present
 
 The installed tree exists and carries the subtrees a run reads: `commands/`,

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -33,6 +33,54 @@ model's reading of the task. A file counts as UI by stack:
 Nothing about this section is optional-by-omission: when it is required and an
 artefact is absent, the absence is written down with its reason (section 5).
 
+### 1a. Who writes the verdict, and when
+
+**Phase 0 Step 7.7 writes `required`, `requiredBy` and `platform`**, before it
+probes. Naming the writer is not a formality: five phases read these three fields
+and nothing set them, so `required` was never true, Step 7.7 never ran, Phase 3
+never captured, and Phase 6's blocker never blocked. A contract with readers and
+no writer reads exactly like a contract that is satisfied.
+
+Phase 0 has no diff, so it decides on what it actually knows - `taskType` and
+whether the intake carried a Figma reference - and that is enough for the whole
+design-work row. The `bugfix` row needs a changed-file list, so Phase 0 records
+it as provisional (`requiredBy: "bugfix (pending diff)"`) and **Phase 3 re-decides
+from the real diff** before capturing. A provisional `false` never suppresses the
+Phase 3 decision.
+
+### 1b. The platform, and when there is not one
+
+`platform` comes from the stack, not from the diff: it selects which device
+tooling is probed, and that is a property of the repo.
+
+```bash
+eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS
+EVIDENCE_PLATFORM=""
+case " $MA_STACKS " in
+  *" ios "*)     EVIDENCE_PLATFORM=ios ;;
+  *" android "*) EVIDENCE_PLATFORM=android ;;
+esac
+```
+
+iOS wins a tie, and the tie is recorded in `stackWhy`: `simctl` discovery is the
+cheaper of the two, and a repo that is honestly both gets the same answer on
+every run rather than one that depends on ordering.
+
+**An empty value is a real outcome, not an error.** A web or backend repo has no
+simulator to probe, and `probe-evidence-capability.sh` rejects anything but
+`ios|android` with exit 2. So when `EVIDENCE_PLATFORM` is empty the probe **does
+not run**, `platform` is written as `web` or `other` from `MA_STACKS`, and the
+reason goes to `state.evidenceCapability.skippedReason` in the probe's own
+`*_REASON` idiom - "no device platform in stacks [web backend]". Passing an empty
+string instead is what the probe's exit 2 exists to refuse, and swallowing that
+exit would turn a missing value into a silent skip.
+
+Every `--platform` argument in this pipeline is `$EVIDENCE_PLATFORM`, read from
+`state.visualEvidence.platform` in later phases. `$PLATFORM` is not a pipeline
+variable: nothing ever assigned it, in any phase document, which is why
+`smoke-evidence-probe.sh` now fails a `--platform` argument whose variable is not
+assigned earlier in the same file.
+
 ## 2. Before  -  the reporter's screenshot, or nothing
 
 **The pipeline does not build the old state to photograph it.** Reproducing a
@@ -61,7 +109,7 @@ never the only source.
 
 ```bash
 bash $HOME/.claude/scripts/capture-evidence.sh after \
-  --task "$TASK_ID" --platform "$PLATFORM" --label "<screen-slug>"
+  --task "$TASK_ID" --platform "$EVIDENCE_PLATFORM" --label "<screen-slug>"
 ```
 
 What the capture is worth checking against - the per-component catalog, the

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

@@ -591,21 +591,30 @@ Log: `Phase 0 Step 7.6: test baseline = {green|red|unknown} ({N} pre-existing fa
 
 #### Step 7.7  -  Evidence capability, then test depth
 
-Probe, then ask, then run. Skipped unless `state.visualEvidence.required` and `visualEvidence.enabled` is not `false`. Reasoning: `features/visual-evidence.md` section 4.
+Decide, then probe, then ask, then run. Skipped only when `visualEvidence.enabled` is `false`. Contract: `features/visual-evidence.md` sections 1a, 1b, 4.
+
+**This step is the only writer of `visualEvidence.required`, `requiredBy` and `platform`** (section 1a). No diff exists yet, so the `bugfix` row is provisional and Phase 3 re-decides.
 
 ```bash
-eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
-  --platform "$PLATFORM" --repo "$WORKTREE" --changed "$CHANGED_CSV" \
-  --json-out "$WORKTREE/.pipeline/evidence-capability.json")"
+eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
+EVIDENCE_PLATFORM=""
+case " $MA_STACKS " in *" ios "*) EVIDENCE_PLATFORM=ios ;; *" android "*) EVIDENCE_PLATFORM=android ;; esac
+if [ -n "$EVIDENCE_PLATFORM" ]; then
+  eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
+    --platform "$EVIDENCE_PLATFORM" --repo "$WORKTREE" \
+    --json-out "$WORKTREE/.pipeline/evidence-capability.json")"
+fi
 ```
 
+Empty is an outcome, not a failure: no simulator on web or backend, so the probe does not run and `evidenceCapability.skippedReason` says so. No `--changed` yet, by the same token.
+
 One run, both forms: stdout is `EVIDENCE_*` (shell-quoted, so the eval is safe), and the same measurement lands as JSON.
 
 Persist that file as `state.evidenceCapability`, then build the menu from it, never from a reading of the repo: `1. Sadece unit test` / `2. Unit + UI test, ekran kaydiyla` (tier 1) / `3. Unit + MCP ile akis kaydi` (tier 2).
 
 A closed option keeps its row and prints the probe's reason verbatim. No `uiTestTargets` closes 2; `mcp` false closes 3; a missing `device` or `recorder` closes both. Targets present with no `matchingTests` leaves 2 open, warning that the whole UI suite will run. **When only option 1 is open, do not ask**: `testDepth = unit`, `testDepthSource = forced`, and the tier 3 gap is written.
 
-Pass the default as the **1-based index**, never the label (`rules.md`: labels render in `outputLanguage`, so a label default matches nothing on a `tr` run and `ask-choice.sh` takes option 1 on a non-TTY):
+Default as a 1-based index, never a label - same rule and same reason as Step 7.5:
 
 ```bash
 DEPTH_DEFAULT_INDEX=1