@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/commands/multi-agent/search.md

@@ -6,16 +6,16 @@ argument-hint: "\"query\" [--project NAME] [--since 7d] [--phase N] [--semantic]
 
 # multi-agent search
 
-Searches every task log under `~/.claude/logs/multi-agent/**/agent-log.md`. Uses ripgrep when available for speed, falls back to grep otherwise — same output. Results are ranked by `matches × recency` (last 7 days 1.0×, 7-30 days 0.5×, older 0.2×).
+Searches every task log under `~/.claude/logs/multi-agent/**/agent-log.md`. Uses ripgrep when available for speed, falls back to grep otherwise  -  same output. Results are ranked by `matches × recency` (last 7 days 1.0×, 7-30 days 0.5×, older 0.2×).
 
 **`--semantic` flag** routes the query to the per-repo triage corpus (`triage-memory.mjs`) instead of the agent-log grep. Returns past Phase 4 findings ranked by token overlap. Honors `--project` as the repo-slug; `--since` and `--phase` are not applicable (the corpus is finding-grained, not phase-grained).
 
-**Input:** `$ARGUMENTS` — query + optional flags
+**Input:** `$ARGUMENTS`  -  query + optional flags
 
 ## Usage
 
 ```bash
-# Plain search — all projects, all time
+# Plain search  -  all projects, all time
 /multi-agent:search "null deref"
 
 # Project filter
@@ -46,22 +46,22 @@ Searches every task log under `~/.claude/logs/multi-agent/**/agent-log.md`. Uses
 
 ## Output format
 
-Text mode (default) — colourful, human-readable:
+Text mode (default)  -  colourful, human-readable:
 
 ```
 search-logs · 3 tasks · query=null deref
   since=7d
 
 PROJ-1337 · app · bugfix/PROJ-1337-null-deref · 4 matches
-  PROJ-1337 — Guard null in BookingViewModel
+  PROJ-1337  -  Guard null in BookingViewModel
   2026-04-16  ·  BookingViewModel.swift:142 null-deref fixed via guard
 
 PROJ-1234 · app · feature/PROJ-1234-flight-filter · 1 match
-  PROJ-1234 — Add flight price filter
+  PROJ-1234  -  Add flight price filter
   2026-04-15  ·  price-filter state leaked across navigation
 ```
 
-JSON mode — for embedded automation:
+JSON mode  -  for embedded automation:
 
 ```json
 {
@@ -94,4 +94,4 @@ JSON mode — for embedded automation:
 
 ## Security note
 
-The search is scoped to **local** files — `~/.claude/logs/multi-agent/` (per-user, not in the repo). No network I/O, no uploads. Raw log content never leaves the terminal.
+The search is scoped to **local** files  -  `~/.claude/logs/multi-agent/` (per-user, not in the repo). No network I/O, no uploads. Raw log content never leaves the terminal.

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

@@ -5,7 +5,7 @@ allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 
 ## Setup (Credential Store + Git Identity Onboarding)
 
-Cross-platform setup — uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the platform-native credential store:
+Cross-platform setup  -  uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the platform-native credential store:
 
 | Platform | Backend | Built-in? |
 |----------|---------|-----------|
@@ -13,22 +13,22 @@ Cross-platform setup — uses `$HOME/.claude/lib/credential-store.sh` to read/wr
 | Windows  | Credential Manager (PowerShell `CredentialManager` module) | Module install required |
 | Linux    | libsecret (`secret-tool`) | Distro package required |
 
-Run `~/.claude/lib/credential-store.sh doctor` first — it prints platform + missing dependencies with the exact install command.
+Run `~/.claude/lib/credential-store.sh doctor` first  -  it prints platform + missing dependencies with the exact install command.
 
 On macOS and Linux the shell driver auto-delegates `get`/`set`/`delete` to the deterministic Python helper at `$HOME/.claude/scripts/keychain.py` (Python 3 stdlib only, no external deps). The Python path writes both `-l` (label) and `-s` (service) attributes so items are findable regardless of how callers look them up. Set `KEYCHAIN_DELEGATE=0` to force the raw shell path.
 
-### Step 0 — Language Selection
+### Step 0  -  Language Selection
 
 Ask BEFORE anything else, so every subsequent setup prompt and the rest of the pipeline honour the choice. The pipeline has two language axes:
 
 | Axis | What it controls | Configurable? |
 |---|---|---|
-| `promptLanguage` | Interactive pickers and prompts during a pipeline run (account, project, dev-context, branch, channels, Phase 5 test, Phase 6 confirmations) | **No — fixed to `en`.** Picker UI is always English to keep tooling consistent across CLIs. |
-| `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports rendered to the user | Yes — set here and changeable later via `/multi-agent:language <en\|tr>` |
+| `promptLanguage` | Interactive pickers and prompts during a pipeline run (account, project, dev-context, branch, channels, Phase 5 test, Phase 6 confirmations) | **No  -  fixed to `en`.** Picker UI is always English to keep tooling consistent across CLIs. |
+| `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports rendered to the user | Yes  -  set here and changeable later via `/multi-agent:language <en\|tr>` |
 
 `promptLanguage` is seeded as `"en"` and never offered to the user. **External payloads always stay English** (commits, PR titles/bodies, Jira comments, wiki content, reviewer/triage prompts, agent-log.md).
 
-#### Step 0 prompt — `outputLanguage`
+#### Step 0 prompt  -  `outputLanguage`
 
 The setup wizard asks one question (English UI per skill-prompt rules):
 
@@ -50,9 +50,9 @@ Select (1-2):
   - `tr`: `outputLanguage=<Y>. promptLanguage "en" sabit. Dış çıktılar (PR açıklamaları, Jira yorumları, review istemleri) her durumda İngilizce kalır.`
 - **Unknown input** → re-ask once, then abort setup with a hint pointing to `/multi-agent:language`.
 
-From this point forward, every prompt in Steps 1–6 below (discovery summaries, Token Save Flow Steps A–D, identity binding, repo picker) renders in English (per the fixed `promptLanguage`). The setup wizard's own status text and the post-setup summary render in `outputLanguage`. External payloads remain English.
+From this point forward, every prompt in Steps 1-6 below (discovery summaries, Token Save Flow Steps A-D, identity binding, repo picker) renders in English (per the fixed `promptLanguage`). The setup wizard's own status text and the post-setup summary render in `outputLanguage`. External payloads remain English.
 
-### Step 0.5 — Credential Backend Check
+### Step 0.5  -  Credential Backend Check
 
 Before discovery, verify the platform's credential backend is available:
 
@@ -65,14 +65,14 @@ Before discovery, verify the platform's credential backend is available:
 | `Backend: ✓` | Continue to Step 1 |
 | Linux: `secret-tool ✗ MISSING` | Prompt: `sudo apt install libsecret-tools` (Debian/Ubuntu) or `sudo dnf install libsecret` (Fedora). Re-run setup after install. |
 | Windows: `CredentialManager ✗ MISSING` | Prompt: `Install-Module CredentialManager -Scope CurrentUser -Force` in an elevated PowerShell. Re-run setup. |
-| Platform `unknown` | Halt — credential storage cannot proceed. |
+| Platform `unknown` | Halt  -  credential storage cannot proceed. |
 
 ### Credential Key Naming Rule
 
 - **New token** (first-time creation in Step 3): ALWAYS use the standard key name (`${USER}_Jira_Access_Token`, etc.). This ensures cross-machine consistency.
-- **Existing token** (discovered in Step 1): NEVER rename or migrate. Map the discovered key name as-is into `keychainMapping`. The mapping layer abstracts the actual key name — the pipeline never reads the credential store directly by standard name.
+- **Existing token** (discovered in Step 1): NEVER rename or migrate. Map the discovered key name as-is into `keychainMapping`. The mapping layer abstracts the actual key name  -  the pipeline never reads the credential store directly by standard name.
 
-### Step 1 — Dynamic Credential Discovery
+### Step 1  -  Dynamic Credential Discovery
 
 Instead of checking only hardcoded key names, discover ALL user keys and intelligently map them to services. Uses cross-platform `credential-store.sh list`:
 
@@ -84,7 +84,7 @@ echo "$DISCOVERED"
 
 **1b. Standard key names (convention):**
 
-These are the RECOMMENDED key names. When creating NEW keys, use these. But existing keys under different names are perfectly valid — the discovery step will find them.
+These are the RECOMMENDED key names. When creating NEW keys, use these. But existing keys under different names are perfectly valid  -  the discovery step will find them.
 
 | Service ID | Standard Key Name | Search Keywords |
 |------------|------------------|-----------------|
@@ -93,8 +93,10 @@ These are the RECOMMENDED key names. When creating NEW keys, use these. But exis
 | `bitbucket_user` | `${USER}_Bitbucket_Username` | `bitbucket` + (`user` or `name`) |
 | `github` | `${USER}_Github_Access_Token` | `github` or `gh` (exclude `ssh`) |
 | `confluence` | `${USER}_Confluence_Access_Token` | `confluence` |
-| `figma` | `${USER}_Figma_Access_Token` | `figma` + NOT `mcp` |
+| `figma_pat` | `${USER}_Figma_Access_Token` | `figma` + (`token` or `pat` or `access`) + NOT `mcp` |
 | `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | `figma` + `mcp` |
+
+> Multi-agent setup onboards **both** Figma tokens because the pipeline's 3-tier Figma access chain (see `pipeline/rules/figma-pipeline.md`) uses them in priority order: Tier 1 = MCP (`figma_mcp`), Tier 2 = REST PAT (`figma_pat`), Tier 3 = user screenshot fallback. Missing either token forces a downshift; missing both leaves Tier 3 as the only path.
 | `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
 | `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
@@ -106,7 +108,7 @@ For each service in the table above, follow this order:
 1. **Check standard key** -> `~/.claude/lib/credential-store.sh get "<standard_key>" 2>/dev/null`
    - Found (non-empty stdout, exit 0) -> auto-map, done
 3. **Search discovered keys** -> filter `$DISCOVERED` by the service's search keywords (case-insensitive)
-   - Exactly 1 match -> show: `"Found '${matched_key}' for ${service} — use this? (enter=yes / n=skip)"` -> if yes, map it
+   - Exactly 1 match -> show: `"Found '${matched_key}' for ${service}  -  use this? (enter=yes / n=skip)"` -> if yes, map it
    - Multiple matches -> show numbered list, user picks:
      ```
      Multiple keys found for GitHub:
@@ -120,7 +122,7 @@ For each service in the table above, follow this order:
    ```
    No exact match found for Jira in your keychain.
    
-   These entries might be your Jira token — do any look right?
+   These entries might be your Jira token  -  do any look right?
      1. MyPersonalJiraToken
      2. work_jira_pat
      3. JiraPAT_2024
@@ -143,7 +145,7 @@ Before running discovery, check `prefs.global.keychainMapping`. If a mapping alr
 
 If a previously mapped key NO LONGER exists in Keychain -> clear the stale mapping, re-run discovery for that service.
 
-### Step 2 — Show Discovery Summary + Save Mapping
+### Step 2  -  Show Discovery Summary + Save Mapping
 
 Show results grouped by status:
 
@@ -162,7 +164,7 @@ Keychain Token Discovery (${USER}):
   Mapped: 8 | Missing: 4
 ```
 
-Non-standard key names are perfectly valid — the mapping handles resolution. No rename or migration is offered.
+Non-standard key names are perfectly valid  -  the mapping handles resolution. No rename or migration is offered.
 
 Save the resolved mapping to preferences:
 ```json
@@ -174,7 +176,7 @@ Save the resolved mapping to preferences:
       "bitbucket_user": "${USER}_Bitbucket_Username",
       "github": "${USER}_Github",
       "confluence": null,
-      "figma": "${USER}_Figma_Access_Token",
+      "figma_pat": "${USER}_Figma_Access_Token",
       "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
       "fortify": null,
       "firebase": "${USER}_Firebase_Access_Json",
@@ -184,15 +186,15 @@ Save the resolved mapping to preferences:
 }
 ```
 
-`null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically — never hardcoded key names.
+`null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
 ### Auto-learned fields (no setup step needed)
 
-**Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time — most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.
+**Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time  -  most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.
 
 **Git Identity**: auto-learned from token onboarding. Each token saved in Step 3 triggers an identity prompt (see Token Save Flow Step C). No separate identity setup step.
 
-### Step 3 — Interactive token onboarding (for missing tokens)
+### Step 3  -  Interactive token onboarding (for missing tokens)
 
 Git identities are NOT asked as a separate step. They are learned when tokens are added in Step 4 (Token Save Flow). Each token save triggers an identity prompt:
 
@@ -221,27 +223,43 @@ For each MISSING service, run the **Token Save Flow** below. When creating new t
 ### Token Save Flow (reusable)
 
 This flow is used in TWO contexts:
-- **Setup Step 4** — for missing tokens during first-time onboarding
-- **Phase 0 token pre-check** — when a token is missing or expired (401/403) at runtime
+- **Setup Step 4**  -  for missing tokens during first-time onboarding
+- **Phase 0 token pre-check**  -  when a token is missing or expired (401/403) at runtime
 
 **Trigger**: token missing (`keychainMapping` is `null`) OR token expired (API returned 401/403).
 
-**Step A — Ask**:
+**Step A  -  Ask** (options depend on whether the token is missing or expired):
 
+Missing token (first-time / unmapped):
 ```
-{Service} token {missing|expired}.
+{Service} token missing.
   Where to get it: {source URL/instructions}
 
-  [1] Add now — I'll generate the token and copy it
-  [2] Skip — I'll set it up later
+  [1] Add now  -  I'll generate the token and copy it
+  [2] Skip  -  I'll set it up later
 
   Select:
 ```
 
-- `[2]` → skip. During setup: `keychainMapping` stays `null`. During Phase 0: abort that service's pre-check, warn and continue if non-critical, halt if critical (e.g. Jira token for Jira input).
-- `[1]` → proceed to Step B.
+Expired / rejected token (401 / 403 mid-run)  -  the Expired-token decision from `refs/keychain.md` Rule 1:
+```
+{Service} token expired (the service returned 401/403).
+  Where to get a fresh one: {source URL/instructions}
+
+  [1] Regenerate  -  replace {KEY_NAME} in place, then retry
+  [2] Use a different token  -  map another Keychain entry, then retry
+  [3] Skip and continue  -  drop this source (halts only if the token is required for the input)
+
+  Select:
+```
 
-**Step B — Clipboard save** (token NEVER appears in terminal):
+Render `question` + `description` in `outputLanguage`; `label` + `header` English. The picked label is a choice, never the secret  -  the value still enters via Step B clipboard.
+
+- **Skip** (missing `[2]` / expired `[3]`) → skip semantics. During setup: `keychainMapping` stays `null`. During Phase 0 / mid-run: abort that service's contribution, warn and continue if non-critical, halt if critical (e.g. Jira token for Jira input).
+- **Add now** / **Regenerate** → proceed to Step B (clipboard save). Regenerate reuses the same `{KEY_NAME}`.
+- **Use a different token** → proceed to Step B, then re-run Step C identity binding for the new entry.
+
+**Step B  -  Clipboard save** (token NEVER appears in terminal):
 
 For PAT / API key / username:
 ```
@@ -251,7 +269,7 @@ For PAT / API key / username:
   Press Enter when ready...
 ```
 
-Pipeline runs silently — value is piped via stdin (`-` sentinel) so it never lands on argv / shell history:
+Pipeline runs silently  -  value is piped via stdin (`-` sentinel) so it never lands on argv / shell history:
 ```bash
 pbpaste | ~/.claude/lib/credential-store.sh set "<KEY_NAME>" "$(cat)"
 pbcopy < /dev/null
@@ -259,7 +277,7 @@ pbcopy < /dev/null
 
 (The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Linux, which writes both `-l` (label) and `-s` (service) attributes so callers using either convention find the same entry.)
 
-For JSON file (Firebase) — same clipboard flow, JSON content never lands in argv or shell history:
+For JSON file (Firebase)  -  same clipboard flow, JSON content never lands in argv or shell history:
 ```
   Open the Service Account JSON, copy its FULL contents to your clipboard,
   then press Enter.
@@ -281,7 +299,7 @@ For GitHub (special case):
   ! gh auth login
 ```
 
-**Step C — Identity binding** (after token saved):
+**Step C  -  Identity binding** (after token saved):
 
 ```
   ✓ Saved to Keychain as <KEY_NAME>
@@ -302,7 +320,7 @@ For GitHub (special case):
 - First token ever (no identities exist) → skip picker, go straight to name + email
 - `bitbucket_user` is excluded from identity binding (it's a username, not a PAT)
 
-**Step D — Confirm + update**:
+**Step D  -  Confirm + update**:
 
 ```
   ✓ Token mapped to identity: Ada Lovelace <ada@example.com>
@@ -314,7 +332,7 @@ Update `serviceStatus.{service} = { ok: true, checkedAt: <now> }`.
 
 **→ Next: if `{service}` is `jira` / `confluence` / `bitbucket` / `fortify` AND the corresponding
 `prefs.global.hosts.{service}` is unset, run Step 3.5 (Host Prompt) inline before
-the Auto-routing rule below. required — the pipeline cannot build API URLs without
+the Auto-routing rule below. required  -  the pipeline cannot build API URLs without
 the host. Firebase is skipped here (host is always `console.firebase.google.com` /
 `firebasecrashlytics.googleapis.com`); the SA JSON itself carries `project_id`.**
 
@@ -327,18 +345,18 @@ If `platformIdentityRouting` has no rule for this platform yet, auto-suggest one
     [enter=yes / n=skip]
 ```
 
-This builds `platformIdentityRouting` incrementally — no separate Step 7 needed for most users.
+This builds `platformIdentityRouting` incrementally  -  no separate Step 7 needed for most users.
 
 ---
 
-### Step 3.5 — Host Prompt (embedded in Token Save Flow)
+### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
-**Not a standalone step** — runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step — Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.
+**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.
 
 Right after Step D (identity mapping confirmed), ask:
 
 ```
-Service host — needed to build API URLs for this token.
+Service host  -  needed to build API URLs for this token.
 
   {Service} host (e.g. jira.example.com): ___
 ```
@@ -372,15 +390,15 @@ Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_H
 
 **Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
 
-Team-sharing note: Hosts are the only corporate metadata the pipeline needs. Tokens live in macOS Keychain (encrypted, never on disk inside the repo). Preferences file lives in `~/.claude/` — fully outside the repo clone. A teammate cloning the repo runs `/multi-agent:setup` once; host + token prompts run naturally together.
+Team-sharing note: Hosts are the only corporate metadata the pipeline needs. Tokens live in macOS Keychain (encrypted, never on disk inside the repo). Preferences file lives in `~/.claude/`  -  fully outside the repo clone. A teammate cloning the repo runs `/multi-agent:setup` once; host + token prompts run naturally together.
 
 ---
 
-### Step 3.6 — Per-account host overrides (optional)
+### Step 3.6  -  Per-account host overrides (optional)
 
 **Runs only when** `~/.claude/lib/account-resolver.sh` returns **more than one** account AND at least one account has Jira or Bitbucket tokens.
 
-Use case: a single user with two corporate identities (e.g. agency + client). Each account points at its own Jira host — `prefs.global.hosts.jira` can hold only one default, so per-account overrides win for the rest.
+Use case: a single user with two corporate identities (e.g. agency + client). Each account points at its own Jira host  -  `prefs.global.hosts.jira` can hold only one default, so per-account overrides win for the rest.
 
 For each non-default account, ask once:
 
@@ -405,26 +423,26 @@ If `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optiona
 }
 ```
 
-`account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot — `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
+`account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
 
 **Re-run / update**: `/multi-agent:setup accounts` opens the editor for this block without re-running token discovery.
 
 ---
 
-### Step 4 — Verify all
+### Step 4  -  Verify all
 
 Re-run scan from Step 1. Show final status:
 ```
 All tokens present. Pipeline ready to use.
 
 Optional per-project features (configured on first use, nothing to do now):
-  • Phase 7 Report Step 2 Wiki — auto-generates component wiki pages + Figma
+  • Phase 7 Report Step 2 Wiki  -  auto-generates component wiki pages + Figma
     screenshots. Activates when (a) task is a component AND (b) a Figma token
     is in Keychain. Four adapters supported: submodule / in-repo / github-wiki
     / separate-repo. First run asks: use auto-detected path, use a custom
     path, skip once, or disable for this project (persisted).
-  • channels — post-hoc multi-channel reporter (Jira/Confluence/Wiki/PR), works on any branch with an open PR.
-  • Default reviewers — auto-fetched from Bitbucket default-reviewers endpoint
+  • channels  -  post-hoc multi-channel reporter (Jira/Confluence/Wiki/PR), works on any branch with an open PR.
+  • Default reviewers  -  auto-fetched from Bitbucket default-reviewers endpoint
     or GitHub CODEOWNERS on first PR.
 
 Next step:
@@ -434,23 +452,23 @@ Next step:
 
 If still missing, show which ones and let user skip (pipeline will re-ask for any needed token at Phase 0).
 
-### Step 5 — Repo Discovery (optional)
+### Step 5  -  Repo Discovery (optional)
 
 Pre-populates the Phase 0 project picker. Without this, every task types the repo path by hand; with this, the picker shows a curated list of repos the user has been active in.
 
-Three sources merge into one flat list. Each source is independent — any one failing does NOT block the others.
+Three sources merge into one flat list. Each source is independent  -  any one failing does NOT block the others.
 
 **Prompt:**
 ```
-Step 5 — Repo Discovery (optional)
+Step 5  -  Repo Discovery (optional)
 Scan for recent repos now to pre-populate the Phase 0 picker?
 
-  y — all three (local + Bitbucket + GitHub, ~10-30s)
-  l — local scan only (fastest, no network)
-  n — skip (Phase 0 will prompt for repo path manually)
+  y  -  all three (local + Bitbucket + GitHub, ~10-30s)
+  l  -  local scan only (fastest, no network)
+  n  -  skip (Phase 0 will prompt for repo path manually)
 ```
 
-**7a. Local scan** — `$HOME` depth-3, repo markers
+**7a. Local scan**  -  `$HOME` depth-3, repo markers
 
 ```bash
 find "$HOME" -maxdepth 3 -type d -name ".git" 2>/dev/null | while read gitdir; do
@@ -463,11 +481,11 @@ done
 
 Auxiliary markers (recorded but not required): `*.xcworkspace`, `*.xcodeproj`, `Podfile`, `Package.swift`, `package.json`, `pom.xml`, `build.gradle`. Their presence tags the repo as iOS/macOS, Cocoapods, SPM, Node, Maven, Gradle in the picker.
 
-**7b. Bitbucket scan** — last 90 days active
+**7b. Bitbucket scan**  -  last 90 days active
 
 Runs only if `keychainMapping.bitbucket_token` is non-null AND `serviceStatus.bitbucket.ok === true` (or cache older than `settings.serviceStatusCacheSeconds`, re-ping first).
 
-Bitbucket Data Center (self-hosted) — the host comes from `prefs.global.bitbucketHost` (or prompts once if unset; NEVER hardcoded):
+Bitbucket Data Center (self-hosted)  -  the host comes from `prefs.global.bitbucketHost` (or prompts once if unset; NEVER hardcoded):
 ```bash
 BB_HOST="$(jq -r '.global.bitbucketHost // empty' "$PREFS_FILE")"
 BB_USER="$(~/.claude/lib/credential-store.sh get "$(jq -r '.global.keychainMapping.bitbucket_user' "$PREFS_FILE")" 2>/dev/null)"
@@ -480,9 +498,9 @@ curl -sfS -u "$BB_USER:$BB_TOK" \
       { slug: "\(.project.key)/\(.slug)", clone: (.links.clone[] | select(.name=="http") | .href) }'
 ```
 
-Bitbucket Cloud — swap to `https://api.bitbucket.org/2.0/repositories/{workspace}?role=member&sort=-updated_on`.
+Bitbucket Cloud  -  swap to `https://api.bitbucket.org/2.0/repositories/{workspace}?role=member&sort=-updated_on`.
 
-**7c. GitHub scan** — owner + collaborator, push in last 90 days
+**7c. GitHub scan**  -  owner + collaborator, push in last 90 days
 
 Runs only if `keychainMapping.github` is non-null AND `serviceStatus.github.ok === true`.
 
@@ -512,7 +530,7 @@ Discovered 24 active repos (local + remote ≤ 90 days):
   [ ]  1. Booking               ~/dev/Booking              bitbucket   iOS · SPM
   [ ]  2. UIComponents          ~/dev/UIComponents         bitbucket   iOS · SPM
   [ ]  3. multi-agent-pipeline  ~/multi-agent-pipeline     github      Node
-  [ ]  4. dotfiles              (not cloned)               github      —
+  [ ]  4. dotfiles              (not cloned)               github       - 
   [ ]  5. backend-services      ~/work/backend-services    bitbucket   Maven
   ...
 
@@ -538,16 +556,16 @@ Discovered 24 active repos (local + remote ≤ 90 days):
 }
 ```
 
-Entries are objects (not bare strings). The schema `recentProjects.items` is a `oneOf` — both shapes validate, but v2.1.0 writes objects so `lastUsed` + `label` are first-class.
+Entries are objects (not bare strings). The schema `recentProjects.items` is a `oneOf`  -  both shapes validate, but v2.1.0 writes objects so `lastUsed` + `label` are first-class.
 
 **7g. Skip / degrade rules**
 
 - Source failure (network, VPN, 401, rate-limit) skips that source silently; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
-- If all three sources yield zero hits, Step 5 is a no-op — the picker in Phase 0 falls back to manual path entry.
+- If all three sources yield zero hits, Step 5 is a no-op  -  the picker in Phase 0 falls back to manual path entry.
 - Discovery is **never destructive**: it never modifies git state, never writes outside `PREFS_FILE`.
 - Step 5 is idempotent. Re-running it refreshes `recentProjects` and `serviceStatus` but preserves user-curated entries unless explicitly deselected.
 
-### Step 6 — Remember as Multi-Repo Group (optional)
+### Step 6  -  Remember as Multi-Repo Group (optional)
 
 After Step 5, if the user picked **2 or more** repos, offer to remember the combination as a named group. Phase 0's project picker surfaces saved groups at the top, so a multi-repo task ("update token resolver in `common` + `uicomponents`") becomes a single keypress next time.
 
@@ -555,7 +573,7 @@ Auto-skipped if Step 5 was skipped or fewer than 2 repos were selected.
 
 **Prompt:**
 ```
-Step 6 — Remember as a multi-repo group (optional)
+Step 6  -  Remember as a multi-repo group (optional)
 You picked 2 repos: Booking, UIComponents.
 
 Save this combo for one-tap selection in Phase 0?
@@ -570,7 +588,7 @@ Save this combo for one-tap selection in Phase 0?
 
 Repo identifiers in the label are the human label from `recentProjects` (basename of the path, not the full path), so groups stay readable.
 
-**Save** (matches schema `global.recentGroups[]` shape — `repos` required, `label` / `count` / `lastUsed` optional):
+**Save** (matches schema `global.recentGroups[]` shape  -  `repos` required, `label` / `count` / `lastUsed` optional):
 
 ```json
 {
@@ -597,9 +615,9 @@ Repo identifiers in the label are the human label from `recentProjects` (basenam
 - User answers `n` → not saved; the picker still works for one-time use, and a future Phase 0 selection of the same combo will re-prompt.
 - Step 5 skipped → Step 6 is also skipped (no selection to remember).
 
-### Step 7 — Platform Identity Routing (optional)
+### Step 7  -  Platform Identity Routing (optional)
 
-Map repo URL **glob patterns** to a named identity from `prefs.global.identities`. Phase 0 consults this map in Step 5 to auto-pick the git author and the right `servicePatMap` for the target repo — preventing corporate identity leakage into personal repos and vice versa.
+Map repo URL **glob patterns** to a named identity from `prefs.global.identities`. Phase 0 consults this map in Step 5 to auto-pick the git author and the right `servicePatMap` for the target repo  -  preventing corporate identity leakage into personal repos and vice versa.
 
 Auto-skipped if `identities` has fewer than 2 entries (single-identity case has nothing to route).
 
@@ -608,21 +626,21 @@ Auto-skipped if `identities` has fewer than 2 entries (single-identity case has
 For each identity, derive a default routing rule from where its PATs work:
 - Identity owns `bitbucket` PAT → propose `<bitbucket-host>/*` glob, mapped to that identity.
 - Identity owns `github` PAT → propose `github.com/<gh-username>/*` if known (from `identities[].username`), else `github.com/*`.
-- Identity owns `confluence` / `jira` only → no URL routing applies (those aren't repo origins) — skip.
+- Identity owns `confluence` / `jira` only → no URL routing applies (those aren't repo origins)  -  skip.
 
 Auto-suggestions are **proposals**, not forced. User confirms or edits each one.
 
 **9b. Confirm or edit each suggested rule**
 
 ```
-Step 7 — Platform Identity Routing (optional)
+Step 7  -  Platform Identity Routing (optional)
 Auto-suggested rules:
 
   1. bitbucket.{corp-domain}/*                  -> corporate    [confirm/edit/skip]
   2. github.com/{personal-username}/*           -> personal     [confirm/edit/skip]
   3. github.com/{org-name}/*                    -> corporate    [confirm/edit/skip]
 
-Add another rule? [y/N]
+Add another rule? [Add another / Done]
 ```
 
 Each rule answer:
@@ -653,29 +671,29 @@ Glob matching semantics (Phase 0 implementation):
 
 **9d. Skip / degrade rules**
 
-- Zero rules saved is valid — Phase 0 always falls back to the identity picker.
+- Zero rules saved is valid  -  Phase 0 always falls back to the identity picker.
 - A rule may point to an identity name that doesn't (yet) exist in `identities`; on Phase 0 lookup, an unknown identity name surfaces as a warning and the picker is shown.
-- Step 7 is idempotent — re-running merges new rules; existing rules are preserved unless the user explicitly edits them.
+- Step 7 is idempotent  -  re-running merges new rules; existing rules are preserved unless the user explicitly edits them.
 - Routing is **advisory**: the user can always override the auto-picked identity in Phase 0.
 
 ### Cross-Platform Notes (Step 1-9)
 
-The credential store is platform-agnostic — every read/write goes through `~/.claude/lib/credential-store.sh`, which dispatches to the right backend (`security` on macOS, `secret-tool` on Linux, PowerShell `CredentialManager` on Windows). On macOS / Linux the shell driver delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. You almost never need the platform-native commands directly.
+The credential store is platform-agnostic  -  every read/write goes through `~/.claude/lib/credential-store.sh`, which dispatches to the right backend (`security` on macOS, `secret-tool` on Linux, PowerShell `CredentialManager` on Windows). On macOS / Linux the shell driver delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. You almost never need the platform-native commands directly.
 
-Clipboard helpers (`pbpaste`, `pbcopy`) are macOS-specific — for Copilot CLI on Linux substitute:
+Clipboard helpers (`pbpaste`, `pbcopy`) are macOS-specific  -  for Copilot CLI on Linux substitute:
 
 | macOS command | Linux equivalent | Notes |
 |---|---|---|
 | `pbpaste` | `xclip -selection clipboard -o` (X11) or `wl-paste` (Wayland) | Install with `apt install xclip` or `apt install wl-clipboard` |
 | `pbcopy < /dev/null` | `xclip -selection clipboard < /dev/null` or `wl-copy --clear` | Same intent: clear clipboard after token paste |
 
-If you need to bypass the helper (debugging, raw inspection), the underlying platform commands are documented at the top of `pipeline/lib/credential-store.sh`. Otherwise stay on the helper — it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes on macOS.
+If you need to bypass the helper (debugging, raw inspection), the underlying platform commands are documented at the top of `pipeline/lib/credential-store.sh`. Otherwise stay on the helper  -  it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes on macOS.
 
-If no backend is available, setup falls back to a plain-text prompt + a warning that the token is **not persisted** — pipeline phases will re-ask each session.
+If no backend is available, setup falls back to a plain-text prompt + a warning that the token is **not persisted**  -  pipeline phases will re-ask each session.
 
 ### Token -> Source Mapping
 
-Standard key names (used when creating NEW tokens). Discovery may find existing keys under different names — that's fine, the mapping in preferences handles it.
+Standard key names (used when creating NEW tokens). Discovery may find existing keys under different names  -  that's fine, the mapping in preferences handles it.
 
 | Service ID | Standard Key Name | Type | Where to Get |
 |------------|------------------|------|---------------|
@@ -684,12 +702,12 @@ Standard key names (used when creating NEW tokens). Discovery may find existing
 | `bitbucket_user` | `${USER}_Bitbucket_Username` | Plain text | Bitbucket profile username |
 | `github` | `${USER}_Github_Access_Token` | PAT | GitHub Settings -> Tokens (scopes: repo, read:org, project) |
 | `confluence` | `${USER}_Confluence_Access_Token` | PAT | Confluence -> Profile -> Personal Access Tokens (VPN required) |
-| `figma` | `${USER}_Figma_Access_Token` | PAT | Figma Developer Settings (max 90 days) |
-| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth | Automatic via Claude Code Figma MCP remote auth |
+| `figma_pat` | `${USER}_Figma_Access_Token` | PAT (Tier 2, REST API) | Figma Developer Settings (max 90 days). Token Save Flow prompt copy: "Figma Personal Access Token (for Tier 2)". |
+| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth (Tier 1, MCP) | Automatic via Claude Code Figma MCP remote auth. Token Save Flow prompt copy: "Figma MCP token (for Tier 1)". |
 | `fortify` | `${USER}_Fortify_Access_Token` | API Token | Fortify SSC -> Token Management (VPN required) |
-| `firebase` | `${USER}_Firebase_Access_Json` | Firebase JSON (base64) | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Project id is parsed from the decoded JSON — no separate entry. |
+| `firebase` | `${USER}_Firebase_Access_Json` | Firebase JSON (base64) | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Project id is parsed from the decoded JSON  -  no separate entry. |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | API Token | Jenkins -> User -> Configure -> API Token |
-| — | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json` — not Keychain |
+|  -  | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json`  -  not Keychain |
 
 ### Inline Token Save Pattern
 
@@ -703,7 +721,7 @@ pbcopy < /dev/null  # clear clipboard
 # Plain text (direct value)
 ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
 
-# JSON file from clipboard (preferred — no file path leaks into history)
+# JSON file from clipboard (preferred  -  no file path leaks into history)
 pbpaste | base64 | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "$(cat)"
 pbcopy < /dev/null
 
@@ -728,7 +746,7 @@ pbpaste | ~/.claude/scripts/keychain.py set "<SERVICE_NAME>" -
 Figma MCP works in two modes:
 
 **Remote MCP** (Claude Code built-in):
-- Automatic — comes as `claude_ai_Figma` in Claude Code settings.json
+- Automatic  -  comes as `claude_ai_Figma` in Claude Code settings.json
 - If token renewal needed: re-auth from within Claude Code
 
 **Local MCP** (@anthropic-ai/figma-mcp package, with PAT):
@@ -743,7 +761,7 @@ pbcopy < /dev/null
 
 ### Security Rules
 
-- Never paste tokens into terminal or chat — use `pbpaste` for input
+- Never paste tokens into terminal or chat  -  use `pbpaste` for input
 - Never hardcode tokens in source code
 - Never commit tokens to git history
 - Clear clipboard immediately: `pbcopy < /dev/null`
@@ -772,4 +790,13 @@ To set up multi-agent on a new machine:
    /multi-agent "bug description"
 ```
 
-All tokens are optional — pipeline will ask for any needed token at Phase 0. Setup only does pre-preparation.
+All tokens are optional  -  pipeline will ask for any needed token at Phase 0. Setup only does pre-preparation.
+
+### Step 8  -  Enforcement hook (optional, Claude Code)
+
+Offer to make the secret scan a HARD pre-commit gate (a non-zero exit blocks the commit) instead of an advisory step. The recommended block ships at `install/templates/claude-hooks.json`.
+
+- Ask (picker): "Install the pre-commit secret-scan hook into `~/.claude/settings.json`?" Default Yes.
+- On Yes, deep-merge the template's `hooks.PreToolUse` into the user's `settings.json` (preserve any existing hooks; do not duplicate a matcher that already calls `pre-commit-check.sh`).
+- Honest note to show: this is the only deterministic gate that is OS-enforceable as a hook (it needs no run-specific arguments). The evidence / consensus / intent / learnings gates are invoked by the pipeline phases with per-run arguments, so they are enforced by the phase contract + the installed gate scripts, not by a hook.
+- On the adapter platforms (Cursor / Antigravity / VS Code Copilot Chat) there is no PreToolUse equivalent; the gate scripts live in `~/.multi-agent/` and are run as workflow steps. See `refs/picker-contract.md`.