@mmerterden/multi-agent-pipeline 15.16.0 → 16.0.0

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

@@ -7,7 +7,7 @@ allowed-tools: Bash, Read, Edit, Write, AskUserQuestion
 
 # multi-agent stack  -  Select Stack(s) via Plugin Enablement
 
-Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. The `ai-common-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin(s).
+Stack skills ship as plugins in the `{owner}/multi-agent-plugins` marketplace. Selecting a stack = **enabling the matching plugin(s)** in the current repo's `.claude/settings.json` `enabledPlugins`. Two toolkits are stack-independent and always enabled alongside the stack plugin(s): `ai-common-toolkit` (accessibility audit, humanizer, Firebase) and `ai-analyst-toolkit` (GitHub and package-registry evidence, community signal for analysis work).
 
 On Claude Code the marketplace plugins are the ONLY source of stack skills - nothing is copied into `~/.claude/skills` anymore. A stack that is not enabled here is simply absent from the session. Copilot CLI and Codex CLI have no plugin loader; they receive a local copy filtered to the enabled stacks at install time, which is why step 5 below offers to refresh those copies after a change.
 
@@ -31,10 +31,10 @@ This replaces the old `stack-swap.sh` mechanic that physically moved skill direc
 
 | Stack | Plugins enabled (all `@multi-agent-plugins`) |
 |---|---|
-| `ios` | `ai-common-toolkit`, `ai-ios-toolkit` |
-| `android` | `ai-common-toolkit`, `ai-android-toolkit` |
-| `frontend` / `web` | `ai-common-toolkit`, `ai-frontend-toolkit` |
-| `backend` | `ai-common-toolkit`, `ai-backend-toolkit` |
+| `ios` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-ios-toolkit` |
+| `android` | `ai-common-toolkit`, `ai-analyst-toolkit`, `ai-android-toolkit` |
+| `frontend` / `web` | `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 |
@@ -53,7 +53,7 @@ Multiple args union their plugin sets: `ios backend` → common + iOS + backend.
 3. **Write rules:**
    - every plugin in the union is set to `true`
    - every stack toolkit **not** in the union is set to `false` (leave non-`@multi-agent-plugins` entries untouched)
-   - `ai-common-toolkit@multi-agent-plugins` is always `true`
+   - `ai-common-toolkit@multi-agent-plugins` and `ai-analyst-toolkit@multi-agent-plugins` are always `true`
    - **legacy-key cleanup**: delete any `ai-*-engineering-toolkit@multi-agent-plugins` keys - those plugin names were retired by the `ai-<stack>-toolkit` rename and a stale `true` there enables a plugin that no longer exists in the marketplace
 4. **Unknown arg** → show the table above; do not guess.
 5. **Copilot/Codex refresh offer.** Their local skill copies are filtered to the enabled stacks at install time, so after a change ask (single `AskUserQuestion`, not silent): "Refresh Copilot/Codex local copies now?" - Yes runs `node <pipelineRepo>/install.js --copilot --codex`, No leaves them stale with a one-line warning naming the command to run later. Skip this question entirely when neither `~/.copilot` nor `~/.codex` exists.
@@ -71,13 +71,14 @@ if ! claude marketplace list 2>/dev/null | grep -q "$MP"; then
 fi
 
 COMMON="ai-common-toolkit@${MP}"
+ANALYST="ai-analyst-toolkit@${MP}"
 IOS="ai-ios-toolkit@${MP}"
 ANDROID="ai-android-toolkit@${MP}"
 FRONTEND="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 $COMMON is in $ON), silently wiping the repo's
+# 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).
 if [ "$#" -eq 0 ]; then
   echo "No stack given - nothing changed. Pass stacks (ios backend ...) or use the picker."
@@ -85,7 +86,7 @@ if [ "$#" -eq 0 ]; then
 fi
 
 # resolve every arg through the alias table, union the ON set
-ON="$COMMON"
+ON="$COMMON $ANALYST"
 for ARG in "$@"; do
   case "$ARG" in
     ios)              ON="$ON $IOS" ;;
@@ -104,7 +105,7 @@ done
 After resolving `$ON`, edit `.claude/settings.json` (create `{ "enabledPlugins": {} }` if absent) so that:
 - every plugin in `$ON` is set to `true`,
 - every stack toolkit **not** in `$ON` is set to `false` (leave non-`@multi-agent-plugins` entries untouched),
-- `ai-common-toolkit@multi-agent-plugins` is always `true`,
+- `ai-common-toolkit@multi-agent-plugins` and `ai-analyst-toolkit@multi-agent-plugins` are always `true`,
 - every `ai-*-engineering-toolkit@multi-agent-plugins` key is **deleted** (retired names).
 
 Use the Read + Edit/Write tools (JSON must stay valid). Then print the resulting `enabledPlugins` block and run step 5 (Copilot/Codex refresh offer).

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

@@ -85,7 +85,7 @@ English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
 2. **Branch**  -  the branch to validate. Resolution order:
    - `git fetch --prune` first, capturing **stderr**. **If the fetch fails, do not
      silently fall back to a cached ref**, and **classify before naming a cause**  -
-     the same rule as the `/multi-agent:dev` remote gate:
+     the same rule as the pipeline's own remote gate:
 
      | stderr contains | Cause | Remedy |
      |---|---|---|

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

@@ -82,11 +82,11 @@ If nothing is stale → report "All targets up to date" and stop.
    - `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 modes table (normal / autopilot / --dev / --dev autopilot)
+   - Pipeline entries table (base / :local / :autopilot / :local-autopilot) + the Full-or-Short depth question
    - Project detection (URL-based + cwd-based)
    - Figma pipeline flow
    - Git conventions (author, branch, commit format)
-   - --dev mode model info (Opus)
+   - Short-run model info (Opus)
    - 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

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

@@ -165,7 +165,7 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
 ```
 Current: v15.6.0   Latest: v15.6.1
   -> npm pack @{npm-scope}/multi-agent-pipeline@15.6.1
-  -> node install.js --all (51 commands, 228 scripts, 205 skills)
+  -> node install.js --all (51 commands, 245 scripts, 208 skills)
   -> migrate-prefs.mjs (0 changes  -  already v2.6.0)
 
 ✓ Updated: v15.6.0 → v15.6.1

package/pipeline/lib/context-link-extractor.sh

@@ -19,6 +19,9 @@
 #                   its entries carry "url": null. Advisory diagnostic context;
 #                   pattern-based + tolerant, a project may refine the labels.
 #   - figma       : Figma design / make / FigJam / slides URLs
+#   - document    : a local document path or a document URL - .docx, .pdf, .md,
+#                   .txt. Distinct from generic-doc, which is an HTML page: this
+#                   one is a file that must be converted before it can be read.
 #   - generic-doc : http(s) URLs that didn't match a more specific type but
 #                   look like documentation (Notion, Google Docs, GitHub
 #                   markdown blob/wiki, gist)  -  passed through as advisory
@@ -33,6 +36,7 @@
 #     { "type": "swagger",    "url": "...", "metadata": { "format": "json|yaml|unknown" } },
 #     { "type": "crashlytics","url": "...", "metadata": { "projectId": "...", "platform": "ios|android", "issueId": "...", "sessionId": "...|null" } },
 #     { "type": "fortify",    "url": "...|null", "metadata": { "host": "...|null", "versionId": "...|null", "instanceId": "...|null", "source": "url|label" } },
+#     { "type": "document",   "url": "...|null", "metadata": { "path": "...", "format": "docx|pdf|md|txt", "source": "path|url" } },
 #     { "type": "graylog",    "url": null,  "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
 #     { "type": "figma",      "url": "...", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "...|null" } },
 #     ...
@@ -169,6 +173,13 @@ def classify(url: str):
             "source": "url",
         })
 
+    # --- Document files (a URL that points at a file, not a page) -----------
+    m_doc = re.search(r"\.(docx|pdf|md|markdown|txt)$", path, re.IGNORECASE)
+    if m_doc:
+        fmt = m_doc.group(1).lower()
+        return ("document", {"path": url, "format": "md" if fmt == "markdown" else fmt,
+                             "source": "url"})
+
     # --- Generic doc fallbacks ---------------------------------------------
     # Notion, Google Docs, GitHub markdown blob/wiki, gists. Useful as
     # advisory context  -  extractor flags them so the orchestrator can decide
@@ -276,5 +287,32 @@ for m in FORTIFY_ID_RE.finditer(text):
         },
     })
 
+# --- Local document paths (not URLs, so the URL pass above never sees them) -
+# A spec arrives as often as a path as it does as a link: "/Users/x/Spec.docx",
+# "~/notes/api.md". Quotes and surrounding prose are stripped; the extension is
+# what makes it a document, so a bare directory or a code path cannot match.
+DOCUMENT_PATH_RE = re.compile(
+    r"(?<![\w/])(~?/[^\s\"'<>|]+\.(?:docx|pdf|md|markdown|txt))",
+    re.IGNORECASE,
+)
+# A URL contains a slash-path too, so skip any match that falls inside one -
+# otherwise "https://x/api.pdf" also yields the bogus local path "//x/api.pdf".
+url_spans = [m.span() for m in URL_RE.finditer(text)]
+for m in DOCUMENT_PATH_RE.finditer(text):
+    if any(a <= m.start() < b for a, b in url_spans):
+        continue
+    raw = m.group(1).rstrip(".,;:!?)")
+    key = ("document", raw)
+    if key in seen:
+        continue
+    seen.add(key)
+    fmt = raw.rsplit(".", 1)[1].lower()
+    out.append({
+        "type": "document",
+        "url": None,
+        "metadata": {"path": raw, "format": "md" if fmt == "markdown" else fmt,
+                     "source": "path"},
+    })
+
 print(json.dumps(out))
 PY

package/pipeline/lib/fetch-document.sh

@@ -0,0 +1,190 @@
+#!/bin/bash
+#
+# fetch-document.sh
+# Extract readable text from a local document or a document URL so an analysis
+# run can cite a Word file, a PDF or a plain-text spec the way it cites a
+# Confluence page. Before this existed nothing in the pipeline could read a
+# .docx, which is the format most feature specs actually arrive in.
+#
+# Input forms:
+#   ./fetch-document.sh /path/to/spec.docx
+#   ./fetch-document.sh ~/notes/spec.md
+#   ./fetch-document.sh https://example.com/spec.docx
+#
+# Optional env:
+#   DOCUMENT_TIMEOUT_SECONDS   download bound, default 25
+#   DOCUMENT_MAX_CHARS         truncate the extracted body, default 200000
+#   DOCUMENT_PDFTOTEXT         pdf converter binary, default `pdftotext`. Some
+#                              distributions ship it under another name or path,
+#                              and the offline smoke points it at a binary that
+#                              does not exist to exercise the degrade path.
+#
+# Output (stdout, single JSON object):
+#   {
+#     "fetchedAt": "<ISO8601>",
+#     "source": { "url": "<url|null>", "path": "<local path>",
+#                 "format": "docx|pdf|md|txt", "bytes": <n> },
+#     "title": "<first heading or filename>",
+#     "text": "<extracted plain text>",
+#     "truncated": <bool>,
+#     "degraded": <bool>, "degradeReason": "<reason|null>"
+#   }
+#
+# Exit codes:
+#   0  success (may be degraded-empty for a pdf with no converter)
+#   3  download or read failure
+#   4  bad usage / unsupported extension
+#   6  converter not available (pdf only; the orchestrator treats this as
+#      "referenced but not fetched" and continues)
+#
+# .docx needs no external tool: the file is a zip and `word/document.xml` is
+# read with the python3 standard library, which the lib layer already depends
+# on. Requiring pandoc or libreoffice would be the wrong dependency for a tool
+# that must work on macOS, Linux and Windows alike. PDF has no stdlib path, so
+# `pdftotext` is used when present and its absence is a soft skip rather than
+# an error - on Windows that absence is the normal case.
+
+set -uo pipefail
+
+TIMEOUT="${DOCUMENT_TIMEOUT_SECONDS:-25}"
+MAX_CHARS="${DOCUMENT_MAX_CHARS:-200000}"
+SRC="${1:-}"
+
+if [ -z "$SRC" ] || [ "$SRC" = "-h" ] || [ "$SRC" = "--help" ]; then
+  echo "usage: $0 <path-or-url>   # .docx | .pdf | .md | .txt" >&2
+  exit 4
+fi
+
+URL=""
+LOCAL="$SRC"
+TMPDL=""
+cleanup() { [ -n "$TMPDL" ] && rm -f "$TMPDL"; }
+trap cleanup EXIT
+
+case "$SRC" in
+  http://*|https://*)
+    URL="$SRC"
+    TMPDL=$(mktemp "${TMPDIR:-/tmp}/fetch-document.XXXXXX")
+    if ! curl -sS -L --fail --max-time "$TIMEOUT" --connect-timeout 5 -o "$TMPDL" "$URL" 2>/dev/null; then
+      printf '%s\n' '{"status":"failed","reason":"download-failed","service":"document"}' >&2
+      exit 3
+    fi
+    # Keep the URL's extension so the format probe below still works.
+    LOCAL="$TMPDL"
+    EXT=$(printf '%s' "${URL%%\?*}" | tr 'A-Z' 'a-z' | sed -n 's/.*\.\([a-z0-9]\{1,5\}\)$/\1/p')
+    ;;
+  *)
+    case "$LOCAL" in "~"/*) LOCAL="$HOME/${LOCAL#\~/}" ;; esac
+    if [ ! -f "$LOCAL" ]; then
+      printf '%s\n' '{"status":"failed","reason":"file-not-found","service":"document"}' >&2
+      exit 3
+    fi
+    EXT=$(printf '%s' "$LOCAL" | tr 'A-Z' 'a-z' | sed -n 's/.*\.\([a-z0-9]\{1,5\}\)$/\1/p')
+    ;;
+esac
+
+case "$EXT" in
+  docx|pdf|md|markdown|txt) ;;
+  *)
+    printf '%s\n' '{"status":"failed","reason":"unsupported-format","service":"document"}' >&2
+    exit 4 ;;
+esac
+
+DEGRADED=false
+DEGRADE_REASON=""
+PDFTOTEXT="${DOCUMENT_PDFTOTEXT:-pdftotext}"
+if [ "$EXT" = "pdf" ] && ! command -v "$PDFTOTEXT" >/dev/null 2>&1; then
+  DEGRADED=true
+  DEGRADE_REASON="converter-not-available"
+fi
+
+SRC_URL="$URL" SRC_PATH="$SRC" LOCAL_IN="$LOCAL" EXT_IN="$EXT" \
+MAX_IN="$MAX_CHARS" DEGRADED_IN="$DEGRADED" REASON_IN="$DEGRADE_REASON" \
+PDFTOTEXT_IN="$PDFTOTEXT" \
+python3 - <<'PY'
+import datetime, json, os, re, subprocess, zipfile
+import xml.etree.ElementTree as ET
+
+path = os.environ["LOCAL_IN"]
+ext = os.environ["EXT_IN"]
+degraded = os.environ["DEGRADED_IN"] == "true"
+reason = os.environ["REASON_IN"] or None
+try:
+    limit = int(os.environ["MAX_IN"])
+except ValueError:
+    limit = 200000
+
+W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
+
+def from_docx(p):
+    # A .docx is a zip; the body is word/document.xml. <w:t> holds the runs,
+    # <w:p> is the paragraph boundary. Standard library only, so the same code
+    # path runs on every platform.
+    with zipfile.ZipFile(p) as z:
+        xml = z.read("word/document.xml")
+    root = ET.fromstring(xml)
+    out = []
+    for para in root.iter(W + "p"):
+        runs = [t.text or "" for t in para.iter(W + "t")]
+        line = "".join(runs).strip()
+        if line:
+            out.append(line)
+    return "\n\n".join(out)
+
+def from_pdf(p):
+    if degraded:
+        return ""
+    r = subprocess.run([os.environ.get("PDFTOTEXT_IN", "pdftotext"), "-layout", p, "-"],
+                       capture_output=True, text=True)
+    return r.stdout if r.returncode == 0 else ""
+
+text = ""
+err = None
+try:
+    if ext == "docx":
+        text = from_docx(path)
+    elif ext == "pdf":
+        text = from_pdf(path)
+    else:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+except Exception as exc:                      # unreadable archive, bad xml, ...
+    err = type(exc).__name__
+    text = ""
+
+if err and not degraded:
+    degraded, reason = True, f"extract-failed:{err}"
+
+truncated = len(text) > limit
+if truncated:
+    text = text[:limit]
+
+title = ""
+for line in text.split("\n"):
+    s = line.strip().lstrip("#").strip()
+    if s:
+        title = s[:120]
+        break
+if not title:
+    title = os.path.basename(os.environ["SRC_PATH"])
+
+print(json.dumps({
+    "fetchedAt": datetime.datetime.now(datetime.timezone.utc)
+                 .isoformat().replace("+00:00", "Z"),
+    "source": {
+        "url": os.environ["SRC_URL"] or None,
+        "path": os.environ["SRC_PATH"],
+        "format": "md" if ext == "markdown" else ext,
+        "bytes": os.path.getsize(path) if os.path.exists(path) else 0,
+    },
+    "title": title,
+    "text": text,
+    "truncated": truncated,
+    "degraded": degraded,
+    "degradeReason": reason,
+}, ensure_ascii=False))
+PY
+
+if [ "$DEGRADED" = "true" ]; then
+  exit 6
+fi

package/pipeline/multi-agent-refs/_dev-context.md

@@ -48,6 +48,10 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
 
 4. **Empty submit**  -  user picks nothing → `extras=[]`, primary repo(s) only.
 
+## Frontend repos  -  `frontendRepos`
+
+Frontend repos are rarely submodules of the app repo, so submodule detection never finds them. `prefs.projects[<key>].frontendRepos[]` is the primary source for them and is merged into the candidate list alongside the detected submodules. Only `/multi-agent:analysis` used to read this key, which meant the pipeline's own dev-context picker could not offer a frontend repo at all.
+
 ## Pref override  -  `editableRelatedRepos`
 
 For repos that aren't on a remote provider (local-only checkout) or to explicitly grant edit rights regardless of provider state, add to `~/.claude/multi-agent-preferences.json`:

package/pipeline/multi-agent-refs/analysis/evidence.md

@@ -0,0 +1,213 @@
+# Evidence gathering (Phases 1, 1b, 1b.1, 1b.2, 1c, 1d)
+
+> Evidence gathering for the analysis engine. Loaded on demand by `/multi-agent:analysis` and by pipeline Phase 1. Produces `state.analysisSpec.evidence.*`; nothing here writes a document.
+
+### Phase 1 - Fetch & extract (parallel)
+
+For each entry in `state.analysisSpec.contextLinks[]`, fan out by `type`. Entries tagged `binding: true` (Q5 inputs) land in `evidence.standards[]` regardless of underlying source type so Section 7 can iterate them as one set.
+
+| type | Command | Output bucket |
+|------|---------|---------------|
+| swagger | `~/.claude/lib/fetch-swagger.sh <url>` | `state.analysisSpec.evidence.swagger[]` |
+| confluence | `~/.claude/lib/fetch-confluence.sh <url>` | `state.analysisSpec.evidence.confluence[]` |
+| figma | **MUST** establish the Figma access tier per Locked decision #12. Tier 1 (preferred): call `mcp__claude_ai_Figma__get_design_context` (primary), `mcp__claude_ai_Figma__get_screenshot`, `mcp__claude_ai_Figma__get_metadata` for every node ID; auth failure runs `authenticate` + `complete_authentication` then retries. Tier 2 (fallback): `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` for design context and `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2` for screenshots, with PAT from `~/.claude/lib/credential-store.sh get <logical-key>` (logical key = `prefs.global.keychainMapping.figma`); canonical component resolves via repo `*.figma.swift` / `*.figma.kt` mapping. Tier 3 (last resort): user-attached screenshot, `codeConnectSnippets: []`, forced Open Question. Capture each `CodeConnectSnippet` block verbatim when on Tier 1 (component name + modifier chain). **Annotation capture (when the project `figma-config` has `annotations.enabled`):** on Tier 1, walk the `annotations[]` the `get_design_context` payload returns for each node (read `label` / `labelMarkdown`); on Tier 2, run `~/.claude/lib/fetch-figma-annotations.sh --file-key <fileKey> --node-id <ids> --lang-prefixes <config.annotations.langPrefixes>`. Parse each annotation by the configured language prefixes (prefixed `TR:/EN:` wins, else line1/line2, else single) and persist to `annotations[]`. The annotation is the authoritative copy for its node (Locked 3); the visible text layer is a placeholder. Persist `state.figmaAccess.tier`. See Locked decision #12 and `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain". | `state.analysisSpec.evidence.figma[]` (records: `nodeId`, `screenshotUrl`, `codeConnectSnippets[]`, `tokens[]`, `textLayers[]`, `annotations[]`, `tier`; see `analysis-spec.schema.json`) |
+| jira | `gh api` or Jira REST API for issue summary | `state.analysisSpec.evidence.jira[]` |
+| document | `~/.claude/lib/fetch-document.sh <path-or-url>` (`.docx` via python3 stdlib, `.md` / `.txt` read directly, `.pdf` only when `pdftotext` exists). Exit `6` is a soft skip, not a failure: record the file with `fetched: false` so Section 21 still cites it as referenced-but-not-fetched. | `state.analysisSpec.evidence.documents[]`, or `evidence.standards[]` when `binding: true` |
+| generic-doc | WebFetch on demand | `state.analysisSpec.evidence.confluence[]` (generic bucket) unless `binding: true` -> `evidence.standards[]` |
+| `local-file` | `Read` (no fetch) on tilde-expanded absolute path | `state.analysisSpec.evidence.standards[]` |
+| `wiki` | `git clone --depth 1 https://github.com/<owner>/<repo>.wiki.git /tmp/<repo>-wiki`, then `Read /tmp/<repo>-wiki/<PageName>.md` (`-` decoded back to space in PageName). Fallback chain: `gh api repos/<owner>/<repo>/contents/<file>.md` for repo-hosted docs if wiki repo is 404. | `state.analysisSpec.evidence.standards[]` |
+| `standards-confluence` | `~/.claude/lib/fetch-confluence.sh <url>` (same fetcher as `confluence`) | `state.analysisSpec.evidence.standards[]` |
+| `firebase-events:names` | Scaffold rows directly from `metadata.names[]`; one row per name with empty params (filled later by repo grep cross-check) | `state.analysisSpec.evidence.firebase[]` |
+| `firebase-events:schema` | `Read` the JSON path; parse `events[]` with `python3 -c json.load`; each entry yields `{name, params: [{name, type, required}]}` | `state.analysisSpec.evidence.firebase[]` |
+| `firebase-events:console` | Reference-only; print INFO warning `INFO: Firebase Console URL captured for reference; provide JSON schema or event-name list for structured ingestion.`; no fetch attempt | `state.analysisSpec.evidence.firebase[]` (URL stored as reference link only) |
+
+**Auth / access failure handling** (applies to `confluence`, `standards-confluence`, `generic-doc` when WebFetch returns a login page, 401, 403, or HTML containing `<form action="/login.action"`):
+
+1. Do **not** silently drop the entry. Record `state.analysisSpec.evidence.fetchErrors[]` with `{url, type, reason: "auth_required"}`.
+2. Surface a one-line warning to the user during Phase 1 progress output: `WARN: Confluence requires browser auth for <url>. Falling back to repo evidence; add the page text manually to /tmp/analysis-paste.md and re-run if needed.`
+3. Continue Phase 1 with remaining evidence sources rather than aborting.
+
+For each repo in `state.analysisSpec.repos[]`, run parallel greps (lightweight surface scan; the deeper 13-bucket extraction happens in Phase 1b):
+
+```bash
+# Localization
+grep -rEl '(Localizable\.strings|strings\.xml|i18n|locale)' "$REPO_PATH"
+
+# Deeplink handlers
+grep -rEl '(UniversalLink|DeeplinkRouter|getDeeplink|onNewIntent|intent-filter)' "$REPO_PATH"
+
+# Push handlers
+grep -rEl '(UNUserNotificationCenter|didReceiveRemoteNotification|FirebaseMessaging|FCM)' "$REPO_PATH"
+
+# Firebase Analytics call sites (Phase 1 auto-detect + Phase 1b cross-check)
+grep -rEln '(Analytics\.logEvent|firebaseAnalytics\.logEvent|logEvent\(analytics,)' "$REPO_PATH"
+
+# Code Connect
+find "$REPO_PATH" -name '*.figma.swift' -o -name '*.figma.kt'
+```
+
+Results go to `state.analysisSpec.evidence.repo[]` (presence flags only).
+
+**Confluence-embedded API table detection**: if a Confluence page body contains `Request Path` / `Service Name` / `Response Body` table columns, set `embeddedApiTable=true` and parse the endpoints from those columns (a project may supply its own parser for this). Do not also trigger a separate Swagger fetch.
+
+### Phase 1b - Repo-evidence collector (parallel, per repo)
+
+After Phase 1 finishes, run a deeper scan per repo to enable Section 7's reuse-first rule (Locked decision 11). Output: `state.analysisSpec.evidence.repoEvidence[<repo>]`.
+
+**Whitelist roots per platform** (subset of repo paths scanned to keep the catalogue bounded):
+
+| Platform | Roots |
+|---|---|
+| iOS | `Domains/`, `Common/`, `Core/`, `App/` |
+| Android | `app/src/`, `feature/`, `core/`, `common/` |
+| Backend | `src/`, `api/`, `services/` |
+| Frontend | `src/`, `app/`, `components/`, `features/`, `lib/` (override with `prefs.projects[<key>].frontendRoots[]`) |
+
+Skip dirs (always): `.build`, `DerivedData`, `Pods`, `node_modules`, `.next`, `build/`, `.gradle`, `vendor/`.
+
+**Candidate set**: build a feature-name slug bundle:
+
+```bash
+slugs=$(echo "$featureName" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+# e.g. UserProfile -> "user profile userprofile"
+grep -rilE "$slugs" $WHITELIST --include="*.swift" --include="*.kt" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" | head -200 > $CANDIDATES
+```
+
+If `wc -l < $CANDIDATES` exceeds 200, record `fetchWarnings += "feature-name too generic; candidate cap hit"` in `repoEvidence[<repo>]`.
+
+**13 buckets** (each scanned in parallel with a 30 s timeout per bucket; timeout marks the bucket as `partial`, never blocks the others):
+
+| Bucket | Detection (iOS Swift sketch) | Cross-platform variant |
+|---|---|---|
+| services | `class .*Service\b`, `protocol .*Service\b`, generated `InfoEndpoint<...>` | `class *Service` / `interface *Service` / `def *_service` |
+| dtos | `struct .*(Request|Response|DTO)\b` | `data class *Dto` / `interface *DTO` / Pydantic `BaseModel` |
+| useCases | `protocol .*UseCase\b`, `class .*UseCase\b` | `class *UseCase` / `def *_use_case` |
+| validationRules | `*Rule.swift`, `*Validator.swift`, Validation/ dir | `*Validator.kt` / `*.ts` zod schemas / pydantic validators |
+| domainEntities | `Domain/Entities/*.swift` | `domain/entities/*.kt` / `entities/*.py` |
+| routes | Public `enum *Route` matching `DomainRoute` | `*Route` sealed / NavRoute / `routes.*` modules |
+| coordinators | `*Coordinator.swift` + `CoordinatorProtocol`/`DomainRouter` | Navigator / NavController helpers |
+| diConfigurators | `*DependencyConfigurator.swift`, `Module.kt` (Hilt) | DI container registrations |
+| uiComponents | `Common/UIComponents/.../Components/**/*.swift` triplet (Configuration + View + +Modifiers) | Compose @Composable functions / React components |
+| tokens | `*Token` enums under `UIAssetTokens/Generated/` | `Theme.kt` / `tokens.ts` / `tailwind.config.*` |
+| localizationKeys | `LocalizationStringKeys.swift` public enum + cases | `strings.xml` keys / `i18n/*.json` keys |
+| testingIdentifiers | `ui-testing-identifiers.json` | `testTag` strings / `data-testid` constants |
+| analyticsEvents | Generated `AnalyticsEvents/*.swift` + `Analytics.logEvent\(` call sites | Equivalent Android / Frontend / Backend telemetry |
+
+**Tagging rule** for each row:
+
+| Tag | Match condition |
+|---|---|
+| `direct-match` | The item name contains a feature-name slug fragment |
+| `same-domain` | Item lives under `Domains/<feature>/` or `feature/<feature>/` |
+| `cross-cutting` | Item lives under `Common/` / `core/` / shared roots (not under any single feature) |
+
+**Output JSON shape** (per repo):
+
+```json
+{
+  "buckets": {
+    "services": [
+      {"name": "UserProfileService", "file": "Domains/UserProfile/Services/UserProfileService.swift", "line": 12, "tag": "direct-match"},
+      {"name": "LoggingService", "file": "Common/Logging/LoggingService.swift", "line": 8, "tag": "cross-cutting"}
+    ]
+  },
+  "fetchWarnings": []
+}
+```
+
+### Phase 1b.1 - Code Connect index (after Phase 1b)
+
+figma-to-swiftui (and the Android equivalent) already produced the feature's components and bound them to Figma via Code Connect. The analysis treats those bindings as the ground truth for "what already exists"  -  it does not re-derive components from the design. Build an index from the `*.figma.swift` / `*.figma.kt` files found in Phase 1:
+
+```bash
+# Code Connect figma(...) calls carry the Figma URL (fileKey + node-id)
+grep -rEn 'figma\("https://www\.figma\.com/[^"]+"' "$REPO_PATH" \
+  --include='*.figma.swift' --include='*.figma.kt'
+```
+
+For each binding, parse `{ fileKey, nodeId, component, path }` where `component` is the registered component type and `path` is the binding file. Decode the URL `node-id` form (`-` to `:`). Output: `state.analysisSpec.evidence.codeConnect[]`.
+
+Phase 2 fills the design->code link deterministically from this index:
+- Section 5.1 `Code Connect` column: the matched component name for that frame's `nodeId` (blank when the frame has no existing binding).
+- Section 6 `Mevcut / Existing`: `yes` + `reuse <component> at <path>` when the design `nodeId` (or its `fileKey`) matches an index entry; `no` + `new component` (added to Section 14) when it does not.
+
+When no Code Connect file exists in any selected repo, the index is empty and Section 6 falls back to the Phase 1b `uiComponents` heuristic (the prior behavior).
+
+### Phase 1b.2 - Main component variant matrix (after the Code Connect index)
+
+The index answers "does this component exist and is it bound". It does not answer "what can it do". For every bound component, walk from the instance to its definition and read the whole axis:
+
+1. Resolve the instance's `componentId` to its main component / component set.
+2. Read the full variant axis. Tier 1: `mcp__claude_ai_Figma__get_metadata` on the component set. Tier 2: `GET /v1/files/{fileKey}/nodes?ids=<componentSetId>` and read `componentPropertyDefinitions` (each axis plus every one of its values); `GET /v1/files/{fileKey}/components` when the set id is not known.
+3. Diff the full axis against the values this screen actually uses.
+
+Output: `state.analysisSpec.evidence.variantMatrix[<component>] = { axis, allValues[], usedValues[] }`, which fills Section 6.X.
+
+Why it lives here and nowhere later: Locked 30 forbids Figma access from Phase 2 onward, so an axis not captured now cannot be recovered - Section 13.6 Preview and Section 15.2 Snapshot would then be validated against a subset nobody could check.
+
+A component with no variant axis (a plain component, not a set) records `axis: null` and is not a finding.
+
+### Phase 1c - Convention extraction (parallel, per repo)
+
+Per Locked decision 23. After Phase 1b finishes, run `~/.claude/lib/extract-conventions.sh <repo-path> <platform>` for each selected repo. The script returns a JSON document with seven pattern groups:
+
+| Group | Keys |
+|---|---|
+| C1 folder structure | `folderStructure` |
+| C2 class naming | `stateHolderNaming`, `viewNaming`, `navigatorNaming`, `useCaseNaming`, `repositoryNaming`, `dtoNaming` |
+| C3 UI state model | `uiStateModel` |
+| C4 test method naming | `testMethodNaming` |
+| C5 accessibility identifier | `accessibilityIdentifier` |
+| C6 localization key | `localizationKey` |
+| C7 DI registration | `diRegistration` |
+
+Each field has shape `{ pattern, example, confidence, evidenceFiles, alternativeCandidates }` where `confidence` is one of `high` (5+ examples, dominant), `medium` (3-4 examples, majority), `low` (2 examples or mixed), `none` (no evidence).
+
+**Output**: `state.analysisSpec.evidence.conventions[<repo>]`.
+
+**Risk auto-population (Locked 23)**: when any field returns `confidence: "low"` or `"none"`, push a row onto `state.analysisSpec.evidence.conventionRisks[]`:
+
+```json
+{
+  "repo": "<repo>",
+  "field": "<pattern key>",
+  "confidence": "<low | none>",
+  "fallback": "conventions-defaults.md:C<n>-<platform>",
+  "question": "<convention-key> evidence is insufficient. Apply default <pattern> or override?"
+}
+```
+
+Phase 2 Section 20 Risks reads this list and emits one open question per entry.
+
+**Fallback source**: when `confidence == "none"` AND `evidence.standards[]` does not contain an explicit rule for that field, the renderer reads `$HOME/.claude/multi-agent-refs/conventions-defaults.md` and applies the platform default.
+
+**Caching (Locked 27)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || hash(evidence.repoEvidence) || hash(evidence.conventions))`. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
+
+Phase 1d is deliberately absent from the digest inputs. Community signal changes by the hour, so folding it in would produce a new digest on every run, invalidate the cache every time, and re-run the two expensive repo phases the cache exists to skip. The consequence is worth stating plainly: a cache hit reuses yesterday's signal rows. That is the correct trade for an advisory tier, and `--no-cache` is the way to refresh them.
+
+### Phase 1d - Outside facts (optional, analyst toolkit)
+
+Runs after Phase 1c, only when `ai-analyst-toolkit` is enabled. Not enabled is a recorded no-op, never a halt: this phase adds context the repo cannot supply, and a run without it is smaller, not wrong.
+
+Two tiers, and the difference decides where a fact is allowed to appear.
+
+| Tier | Sources | Bucket | May appear in |
+|---|---|---|---|
+| Evidence | `evidence-github`, `evidence-registry` | `state.analysisSpec.evidence.outside[]` | any section, cited `GitHub:<owner>/<repo>#<n>` or `Release:<pkg>@<ver>` (Locked 3) |
+| Signal | `signal-community` | `state.analysisSpec.evidence.signals[]` | Section 20 Risks only, as a "reported in the wild" row with its link and date |
+
+What to ask for: whether a dependency the feature touches has an open upstream bug, what a pinned version actually changed, whether prior art exists for the pattern being introduced, and whether anyone outside this team has reported the same symptom.
+
+The tier boundary is not advisory. A signal row that reaches Section 4 (business rules), Section 9 (API contracts) or Section 13 (architecture) is a Locked 3 violation: those sections carry claims a reviewer can check, and a forum post is one person's experience, not a fact about the system being specified.
+
+Per source: reachable and answered, reachable and empty, or unreachable. All three are recorded; only the third produces a `fetchErrors[]` entry, and none of them halts.
+
+**Lite mode auto-detection (Locked 25, v9.1.0 scoring)**: at the end of Phase 1c, evaluate three signals and score each:
+
+| Signal | True condition | Score |
+|---|---|---|
+| Confluence spec body lines | < 100 | 1 |
+| Figma frames count | <= 1 | 1 |
+| Repo evidence direct-match count | >= 8 | 1 |
+
+`liteModeAuto = (totalScore >= 2)`. Two of three signals true is enough; the v8.12.0..v9.0.x AND-threshold (all three) forced too many small features into Full mode when one signal was marginal (e.g. a tiny spec with 2 Figma frames). User overrides via `--full` or `--lite` always win over scoring.