@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/commands/multi-agent/refs/picker-contract.md

@@ -0,0 +1,65 @@
+# Picker Contract (cross-platform single-choice abstraction)
+
+> Foundation for porting pipeline orchestration beyond Claude Code. Native
+> `AskUserQuestion` is a Claude-Code primitive; the other target runtimes
+> (Cursor, Antigravity, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat)
+> do not all expose an agent-invokable choice picker. This contract defines ONE
+> abstract "ask the user to choose" primitive that every adapter renders to the
+> best mechanism its platform offers.
+
+## The abstract primitive
+
+`ask_choice(question, options[], { header?, default?, allowFreeText? })`
+
+- `question` - rendered in `outputLanguage`.
+- `options[]` - each `{ label (English), description (outputLanguage) }`.
+- `default` - recommended option (label or 1-based index); used by autopilot / non-interactive runs.
+- `allowFreeText` - when true, a free-text answer is accepted as an extra channel (e.g. the plan-gate's edit request).
+
+Returns the selected option label (or the free-text string when `allowFreeText` and the user typed instead of choosing).
+
+## Step narration (breadcrumb)
+
+A picker chain (account → repo → maturity → dev-context, or the analysis Phase 0 chain) must tell the user where they are. Before each `ask_choice` / `AskUserQuestion` in a multi-step chain, emit ONE narrator line:
+
+`<localized: "Step <i>/<n>: <what this step decides>">`
+
+- `<i>` is the 1-based position, `<n>` the total steps the active flow will run (known up front: e.g. an analysis run with one platform is 5 steps; a Jira-ID input is 3). When the count is genuinely unknown, omit `/<n>` and print `Step <i>: ...`.
+- The line renders in `outputLanguage` (it is conversational copy, like `question`). Turkish: `Adim 2/5: hesap secimi`. English: `Step 2/5: account selection`.
+- Auto-selected / skipped steps (single account, local-only flow) still print their breadcrumb with the resolution noted (`Step 1/5: account selection (auto: <label>)`), so the chain reads continuously instead of jumping numbers.
+- It is a narrator line above the picker, never part of the `question`, `label`, or `header`.
+
+This is the surface that makes the native picker show, step by step, what it is doing. Every picker file (`_account-picker.md`, `_repo-picker.md`, `_dev-context.md`) and the analysis Phase 0 chain reference this contract.
+
+## Per-platform rendering (degradation ladder)
+
+| Platform | Render |
+|---|---|
+| **Claude Code** | native `AskUserQuestion` (question/description in `outputLanguage`, label English); free-text via the built-in **Other** field |
+| **VS Code Copilot Chat** | native tool-approval / confirmation dialogs for yes/no gates; multi-option choices via a `.prompt.md` that lists options + reads the reply |
+| **Cursor** | Plan-mode question UI where available; otherwise `pipeline/lib/ask-choice.sh` (numbered menu) |
+| **Gemini CLI / Antigravity / Copilot CLI** | `pipeline/lib/ask-choice.sh` (numbered menu); a future MCP elicitation tool can replace this once host support is broad |
+
+## Universal fallback: `pipeline/lib/ask-choice.sh`
+
+A zero-dependency numbered-menu picker for any shell-capable runtime:
+
+```bash
+choice=$(pipeline/lib/ask-choice.sh "Do you approve this plan?" "Approve" "Cancel" "Edit")
+```
+
+- Prints the menu + prompt on **stderr**; echoes ONLY the chosen label on **stdout**.
+- `ASK_CHOICE_DEFAULT=<label|index>` selects without prompting (autopilot / CI).
+- No TTY + no default -> picks the first option and never blocks an automated run.
+
+Enforced by `smoke-ask-choice.sh`.
+
+## Autopilot / non-interactive contract
+
+In autopilot, `ask_choice` resolves to `default` (or the safe first option) without prompting - identical to how the native gates auto-proceed today. A picker is only surfaced for genuinely ambiguous or destructive decisions, matching the maturity-check model.
+
+## Deterministic gates note
+
+Claude Code's `PreToolUse` exit-2 hook is the one HARD blocking gate: the secret scan runs on every `git commit` and a non-zero exit blocks it. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. Only the secret scan is naturally a PreToolUse hook (it needs no run-specific arguments) - the other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+
+On the adapter platforms (Cursor, Antigravity, VS Code Copilot Chat) there is no `PreToolUse` equivalent, so even the secret scan is workflow-enforced there (the gate scripts are installed to `~/.multi-agent/` and invoked as workflow steps) plus a CI smoke-gate step. Enforced by `smoke-gate-hooks.sh`.

package/pipeline/commands/multi-agent/refs/progress-contract.md

@@ -1,14 +1,14 @@
 # Progress Line Contract
 
-> **TLDR** — Every non-trivial pipeline action emits an inline "I'm doing X right now" line so the user always knows what's happening. Immediate flush, no batching. One line per action, standard shape. Autopilot prefers verbose. Low overhead. Mirrored in telemetry as `progress.step` events.
+> **TLDR**  -  Every non-trivial pipeline action emits an inline "I'm doing X right now" line so the user always knows what's happening. Immediate flush, no batching. One line per action, standard shape. Autopilot prefers verbose. Low overhead. Mirrored in telemetry as `progress.step` events.
 
-This contract is consumed by every phase (0–7) and every imported skill (figma-ios, figma-android). It is enforced by `smoke-progress-contract.sh` — any phase doc that drops the contract marker or diverges from the line shape fails CI.
+This contract is consumed by every phase (0-7) and every imported skill (figma-ios, figma-android). It is enforced by `smoke-progress-contract.sh`  -  any phase doc that drops the contract marker or diverges from the line shape fails CI.
 
 ---
 
 ## Why
 
-Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence for 30 s–3 min while subagents churn. Users lose trust, hit ⌃C, or retry identical work. A single-line "current action" fixes it without adding noise: you see exactly what is happening, where, and for how long.
+Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence for 30 s-3 min while subagents churn. Users lose trust, hit ⌃C, or retry identical work. A single-line "current action" fixes it without adding noise: you see exactly what is happening, where, and for how long.
 
 ## Line shape
 
@@ -18,9 +18,9 @@ Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence fo
 
 - **4-space indent**, same as subphase indent elsewhere.
 - `→` arrow, single space.
-- **verb** — lowercase present participle or imperative, one word: `fetching`, `reading`, `running`, `writing`, `posting`, `waiting`, `dispatching`, `retrying`, `building`, `committing`, `checking`.
-- **object** — what is being acted on: file basename, API endpoint last segment, subagent name, command, smoke name.
-- **target** — optional, human-readable scope: repo name, ticket ID, URL host.
+- **verb**  -  lowercase present participle or imperative, one word: `fetching`, `reading`, `running`, `writing`, `posting`, `waiting`, `dispatching`, `retrying`, `building`, `committing`, `checking`.
+- **object**  -  what is being acted on: file basename, API endpoint last segment, subagent name, command, smoke name.
+- **target**  -  optional, human-readable scope: repo name, ticket ID, URL host.
 
 ### Examples
 
@@ -40,8 +40,8 @@ Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence fo
 
 - **No** ANSI color inside the line (runtimes may not render it).
 - **No** emoji in the verb slot (they collide with the phase banner glyphs).
-- **No** payload ≥ 120 chars — truncate target with an ellipsis before shipping.
-- **No** hostnames, tokens, PATs, stderr blobs — emit as `…` and attach detail via telemetry, not the line.
+- **No** payload ≥ 120 chars  -  truncate target with an ellipsis before shipping.
+- **No** hostnames, tokens, PATs, stderr blobs  -  emit as `...` and attach detail via telemetry, not the line.
 - **No** buffered flushes. `stdout` is flushed inside the same call that produces the line.
 
 ---
@@ -58,17 +58,17 @@ Emit a progress line **at least** at every one of these moments:
 
 ### Phase 2 (Planning)
 - plan draft start, plan render, user-approval prompt.
-- **v5.3.0 Plan Approval Gate (normal mode only — skipped for `--dev`, `autopilot`, `--dev autopilot`):**
-  - `clarification-ask` per round — orchestrator writes structured questions when Phase 1 flagged ambiguity (missing acceptance criteria, no Figma/endpoint link, vague language, parent-story scope drift)
-  - `clarification-answer` per round — user reply captured into `state.phases["2"].clarificationAnswers`
-  - `plan-edit-request` per free-text edit — user-supplied revision instruction captured into `state.phases["2"].planEditRequests`
-  - `plan-approved` — terminal success, writes `state.phases["2"].planApprovedAt`
-  - `plan-aborted` — terminal failure (user typed `iptal`/`no`), sets `state.status = "paused"`
-
-### Phase 3 (Dev — non-component)
+- **v5.3.0 Plan Approval Gate (normal mode only  -  skipped for `--dev`, `autopilot`, `--dev autopilot`):**
+  - `clarification-ask` per round  -  orchestrator writes structured questions when Phase 1 flagged ambiguity (missing acceptance criteria, no Figma/endpoint link, vague language, parent-story scope drift)
+  - `clarification-answer` per round  -  user reply captured into `state.phases["2"].clarificationAnswers`
+  - `plan-edit-request` per free-text edit  -  user-supplied revision instruction captured into `state.phases["2"].planEditRequests`
+  - `plan-approved`  -  terminal success, writes `state.phases["2"].planApprovedAt`
+  - `plan-aborted`  -  terminal failure (user typed `iptal`/`no`), sets `state.status = "paused"`
+
+### Phase 3 (Dev  -  non-component)
 - every TDD cycle step: read-target, write-test, run-test RED, write-code, run-test GREEN, run-build, wip-commit.
 
-### Phase 3 (Component — figma-to-component subphases)
+### Phase 3 (Component  -  figma-to-component subphases)
 - subphase dispatch, Figma API call, token mapping, file write per artifact, build step, REVIEW.md gate.
 
 ### Phase 4 (Review)
@@ -98,7 +98,7 @@ Controlled by `prefs.global.settings.progressVerbosity`. Enum:
 | `normal` | Banners + the "when to emit" list above | interactive users (default) |
 | `verbose` | Banners + everything in `normal` + sub-agent internal actions, file-level reads, schema validations, retry internals | autopilot (forced), debugging |
 
-**Autopilot rule:** When `mode: "autopilot"` is set in agent state, progressVerbosity is forced to `verbose` regardless of the preference — rationale: user isn't watching live, so the log must be audit-grade.
+**Autopilot rule:** When `mode: "autopilot"` is set in agent state, progressVerbosity is forced to `verbose` regardless of the preference  -  rationale: user isn't watching live, so the log must be audit-grade.
 
 ---
 
@@ -132,10 +132,26 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase
   tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors the same `tokens_in` / `tokens_out` / `model` into `phase-tracker.sh` so the JSONL metrics line and the tracker's per-phase accumulator stay in sync from one call site. The forward path is best-effort — if the tracker is missing or its file is unwritable, the JSONL write still succeeds. Without the flag the line is purely analytic and the cost block stays empty for that phase.
+`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors the same `tokens_in` / `tokens_out` / `model` into `phase-tracker.sh` so the JSONL metrics line and the tracker's per-phase accumulator stay in sync from one call site. The forward path is best-effort  -  if the tracker is missing or its file is unwritable, the JSONL write still succeeds. Without the flag the line is purely analytic and the cost block stays empty for that phase.
 
 This contract is enforced by `smoke-agent-log-cost.sh` (forwarder unit test) and `smoke-tracker-contract.sh` (Phase 4 reviewer/triage emission).
 
+### Cost budget gate (v9.2+)
+
+When `prefs.global.costBudget.enabled` is true, run the budget check once at the END of every phase, right after that phase's token totals have been forwarded to the tracker:
+
+```bash
+pipeline/scripts/cost-budget-check.mjs --task-id "$TASK_ID" \
+  --prefs "$HOME/.claude/multi-agent-preferences.json"
+```
+
+Act on the exit code:
+- `0` (OK) - say nothing; the live per-phase tile already shows running cost.
+- `10` (WARN) - surface the printed `WARN: ...` line to the user (and into `agent-log.md`). Continue.
+- `11` (EXCEEDED) - surface the `EXCEEDED: ...` line. If `costBudget.onExceed = "halt"`, pause the run and require `multi-agent:resume` (autopilot included) so the user explicitly accepts the overage; if `"warn"`, continue.
+
+The check is a silent no-op (exit 0) when the budget is disabled or no tracker data exists yet, so unconditional invocation is safe. It prices accumulated tokens conservatively (default `opus` rate) so the ceiling trips early. Enforced by `smoke-cost-budget.sh`.
+
 ---
 
 ## Phase adoption marker
@@ -146,10 +162,10 @@ Every phase doc under `refs/phases/` must contain the marker line exactly once:
 <!-- progress-contract: applied -->
 ```
 
-The smoke scans all phase docs for this marker. A missing marker means the phase hasn't adopted the contract yet and fails CI. Adding the marker commits the phase to the contract — any PR that removes it must also remove the phase's progress emissions (no silent regression).
+The smoke scans all phase docs for this marker. A missing marker means the phase hasn't adopted the contract yet and fails CI. Adding the marker commits the phase to the contract  -  any PR that removes it must also remove the phase's progress emissions (no silent regression).
 
 ---
 
 ## Cross-CLI parity
 
-The progress line shape and the `progress.step` event schema are part of the cross-CLI contract. Both Claude Code and Copilot CLI implementations emit identical bytes on the same action — the shape is **not** wrapped in CLI-specific prelude or color codes. `smoke-cross-cli-behavior.sh` includes a progress-line parity check.
+The progress line shape and the `progress.step` event schema are part of the cross-CLI contract. Both Claude Code and Copilot CLI implementations emit identical bytes on the same action  -  the shape is **not** wrapped in CLI-specific prelude or color codes. `smoke-cross-cli-behavior.sh` includes a progress-line parity check.

package/pipeline/commands/multi-agent/refs/rules.md

@@ -1,6 +1,6 @@
-# Multi-Agent Pipeline — Global Rules
+# Multi-Agent Pipeline  -  Global Rules
 
-> **TLDR** — Non-negotiable rules that apply to every phase, every mode, every action. Read once, enforce everywhere. If code / a commit / a PR body violates any rule below, stop and fix before proceeding.
+> **TLDR**  -  Non-negotiable rules that apply to every phase, every mode, every action. Read once, enforce everywhere. If code / a commit / a PR body violates any rule below, stop and fix before proceeding.
 
 ## Language Application (read this FIRST in every run)
 
@@ -30,8 +30,8 @@ This is the single source of truth. When a contributor or model is unsure where
 | Jira comment body (cross-link + summary)     | `outputLanguage`                  |
 | PR description body                          | `outputLanguage`                  |
 | Commit subject + body                        | English (git convention)          |
-| Branch name                                  | English (`feature/…`)             |
-| PR title prefix (`feat:`, `fix:`, …)         | English (Conventional Commits)    |
+| Branch name                                  | English (`feature/...`)             |
+| PR title prefix (`feat:`, `fix:`, ...)         | English (Conventional Commits)    |
 | Code identifiers, file paths, log lines      | English (interop)                 |
 | `agent-state.json` values                    | English (machine-readable)        |
 | `agent-log.md` entries                       | English (audit trail consistency) |
@@ -41,19 +41,20 @@ This is the single source of truth. When a contributor or model is unsure where
 
 1. At the very start of every run (Phase 0 Step 0, before any status output), call `jq -r '.global.outputLanguage // "en"'` on `$HOME/.claude/multi-agent-preferences.json`. Cache as `OUTPUT_LANG` for the session.
 2. Render every assistant-authored line in `OUTPUT_LANG`. If the user types Turkish but `outputLanguage="en"` is set, follow the pref but suggest `/multi-agent:language tr` once.
-3. `AskUserQuestion` `label` and `header` stay English regardless of `OUTPUT_LANG` (UI contract). `question` and `description` follow `OUTPUT_LANG` — the user reads them as conversational copy, not as button affordances.
+3. `AskUserQuestion` `label` and `header` stay English regardless of `OUTPUT_LANG` (UI contract). `question` and `description` follow `OUTPUT_LANG`  -  the user reads them as conversational copy, not as button affordances.
 4. Always English regardless of either axis: commit messages, PR titles, branch names, code identifiers, agent-state.json values, agent-log.md, reviewer/triage system prompts.
 
 **Failure mode this prevents.** Entering `/multi-agent:dev`, `/multi-agent:autopilot`, `/multi-agent:local`, etc. and switching the assistant's conversational text or picker question copy to English while `outputLanguage="tr"` is set. The user sees a half-English half-Turkish dialogue, flagged as a pipeline bug, not a stylistic choice.
 
 ## Code & Commit Rules
 
-- **NEVER** put "Copilot", "AI", "generated by", or similar attribution in code, comments, commit messages, PR descriptions, or issue comments. The pipeline is a tool — it writes on behalf of the configured Git identity, not as itself.
+- **NEVER** put "Copilot", "AI", "generated by", or similar attribution in code, comments, commit messages, PR descriptions, or issue comments. The pipeline is a tool  -  it writes on behalf of the configured Git identity, not as itself.
 - **NEVER** commit without passing build (all gates in Phase 4 Step 1 must be green).
 - **NEVER** commit without passing review (at least one AI reviewer must return `approved: true` with no blocking findings).
 - **NEVER** skip tests. Every public method, every error path, every edge case.
-- **Follow existing code style and conventions.** Read neighbor files before writing new ones — match naming, structure, import order.
+- **Follow existing code style and conventions.** Read neighbor files before writing new ones  -  match naming, structure, import order.
 - **Use design tokens, no magic numbers.** `16` → `.Spacing.spacing16`. `#E31837` → `Color.Primary.primary`. `.font(.system(size: 14))` → `.typographyStyle(.body1)`.
+- **Design system primitives before custom views.** Before writing a new SwiftUI / Compose / React / View / Configuration triplet inside a domain or feature module, grep the shared component library (project-specific path, e.g. `Common/UIComponents/`, `core-ui/`, `packages/ui/`) for an existing primitive that solves the same problem. New domain-level wrappers, custom modals, custom buttons, or hand-rolled toasts are forbidden when the design system already has an equivalent. If the primitive exists but lacks a modifier (placeholder, size, error binding), **add the modifier to the primitive** in its `+Modifiers` extension  -  do not fork the primitive into the consumer domain. The Figma `CodeConnectSnippet` is the authoritative pointer to which primitive to use.
 
 ## Swift-Specific Rules
 
@@ -66,8 +67,8 @@ This is the single source of truth. When a contributor or model is unsure where
   //  Created by {identity.name} on {DD.MM.YYYY}.
   //
   ```
-- No force unwraps (`!`) except IBOutlets. No force casts (`as!`) — use `as?` with `guard`.
-- No `print()` — use `os_log` or `Logger`.
+- No force unwraps (`!`) except IBOutlets. No force casts (`as!`)  -  use `as?` with `guard`.
+- No `print()`  -  use `os_log` or `Logger`.
 
 ## Commit Format
 
@@ -91,9 +92,9 @@ This is the single source of truth. When a contributor or model is unsure where
 
 ## External System Outputs (PR descriptions, Jira comments, GitHub issue bodies)
 
-**formatting contract (required)** — violating these produces unreadable output and is the single most common regression:
+**formatting contract (required)**  -  violating these produces unreadable output and is the single most common regression:
 
-1. **Real newlines, never literal `\n`.** Shell strings like `"line1\nline2"` get saved verbatim by Bitbucket / Jira REST APIs — they render as literal `\n`, not line breaks.
+1. **Real newlines, never literal `\n`.** Shell strings like `"line1\nline2"` get saved verbatim by Bitbucket / Jira REST APIs  -  they render as literal `\n`, not line breaks.
 
    ✅ **Correct pattern** (heredoc → rawfile → data-binary):
 
@@ -118,46 +119,46 @@ This is the single source of truth. When a contributor or model is unsure where
 
 3. **Never hand-concatenate JSON** for bodies with special characters. Use `jq` (which escapes correctly) or `jq --rawfile` (which preserves bytes exactly).
 
-4. **Terminal output, log lines, and `echo`/`printf` calls** also use real newlines — never `\n` literals. For multi-line messages, prefer heredoc.
+4. **Terminal output, log lines, and `echo`/`printf` calls** also use real newlines  -  never `\n` literals. For multi-line messages, prefer heredoc.
 
 ## Issue Management
 
 - **NEVER auto-close** GitHub issues or Jira tickets. Closure requires team review (configurable, typically 4 approvals).
-- PR body: use `Ref: #N`, `Related: #N`, or `See: {jiraId}` — NEVER `Closes #N`, `Fixes #N`, `Resolves #N` (GitHub auto-closes on merge).
+- PR body: use `Ref: #N`, `Related: #N`, or `See: {jiraId}`  -  NEVER `Closes #N`, `Fixes #N`, `Resolves #N` (GitHub auto-closes on merge).
 - Jira auto-close keywords forbidden for the same reason.
 
 ## Reviewers (Every PR)
 
 - **Default reviewers are required** on every PR.
-  - **Bitbucket**: fetch from default-reviewers REST endpoint, filter out PR author, include in payload (empty `reviewers: []` means "no reviewers" — a regression, not a default).
+  - **Bitbucket**: fetch from default-reviewers REST endpoint, filter out PR author, include in payload (empty `reviewers: []` means "no reviewers"  -  a regression, not a default).
   - **GitHub**: rely on CODEOWNERS + branch protection required reviewers; fall back to `prefs.projects[{p}].githubDefaultReviewers` if none configured.
-- **Every Bitbucket PUT must include** `reviewers`, `fromRef`, `toRef`, `draft` — missing fields wipe the existing values (Bitbucket treats omission as empty).
+- **Every Bitbucket PUT must include** `reviewers`, `fromRef`, `toRef`, `draft`  -  missing fields wipe the existing values (Bitbucket treats omission as empty).
 
 ## Build Queue
 
 - All `xcodebuild` / `xcodebuild test` calls acquire `/tmp/claude-xcodebuild.lock` before running. Parallel Xcode builds corrupt DerivedData and simulator state.
 - Each worktree uses its own `-derivedDataPath "{worktreePath}/.DerivedData"` to prevent cross-contamination.
 - Lock auto-releases; stale locks (>15min) get force-cleaned.
-- Non-Xcode builds (Gradle, npm, Python) don't need the lock — they handle their own concurrency.
+- Non-Xcode builds (Gradle, npm, Python) don't need the lock  -  they handle their own concurrency.
 
 ## Retry Discipline
 
 - **3-iteration hard kill** on any retry loop (build fix, review fix, mutation verify). On the 4th failure, pause and ask the user. No exceptions.
 - **Reflection prompt before retry**: "What failed? What specific change fixes it? Am I repeating the same approach?"
-- **Never blindly retry** the identical action — diagnose the root cause first.
+- **Never blindly retry** the identical action  -  diagnose the root cause first.
 
 ## Secrets & Sensitive Files
 
 - **NEVER commit** secrets, tokens, keys, certificates, `.env` files, `Pods/`, `.build/`, `DerivedData/`, `.worktrees/`, or `agent-log.md` / `agent-state.json`.
-- Stage files by name (`git add path/to/file.swift`) — never `git add -A` or `git add .` (accidentally includes sensitive files and agent artifacts).
-- Secret scan runs as Phase 4 Gate 4 — if any hit, fix immediately before proceeding.
+- Stage files by name (`git add path/to/file.swift`)  -  never `git add -A` or `git add .` (accidentally includes sensitive files and agent artifacts).
+- Secret scan runs as Phase 4 Gate 4  -  if any hit, fix immediately before proceeding.
 
 ## Provider CLI Invocations
 
 Provider tools that print failed argv on retry leak credentials into the conversation transcript. Every Vercel call from the pipeline (Phase 6 deploy hooks, Phase 7 site updates, manual `vercel deploy` shells) MUST go through the wrapper:
 
 ```bash
-# CORRECT — token via env var, output redacted automatically. Token resolution
+# CORRECT  -  token via env var, output redacted automatically. Token resolution
 # goes through the cross-platform credential helper so the same snippet works
 # on macOS / Linux / Windows installs:
 VERCEL_TOKEN="$(~/.claude/lib/credential-store.sh get mmerterden_Vercel_Access_Token)" \
@@ -171,13 +172,70 @@ bash $HOME/.claude/scripts/vercel-deploy.sh doctor
 
 ```bash
 # Vercel CLI prints argv on retry → token leaks to transcript.
-vercel deploy --token=vcp_…
+vercel deploy --token=vcp_...
 vercel deploy --token "$VERCEL_TOKEN"
 ```
 
-The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/scripts/vercel-deploy.sh` and `~/.copilot/scripts/vercel-deploy.sh`) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_…`, `Bearer …`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
+The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/scripts/vercel-deploy.sh` and `~/.copilot/scripts/vercel-deploy.sh`) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_...`, `Bearer ...`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
 
-Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `npm-publish.sh`) — never pass tokens via argv when the underlying CLI may echo argv on failure.
+Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `npm-publish.sh`)  -  never pass tokens via argv when the underlying CLI may echo argv on failure.
+
+## User Interaction Discipline
+
+These rules govern when and how the pipeline asks the user, and when it must NOT ask.
+
+- **No auto-commit.** Never run `git commit` without explicit user approval, even when build + review pass. The Phase 4 commit step pauses and asks ("commit message X, OK?"); only on `yes` does the commit run. Applies to checkpoint / WIP commits during Dev (Phase 3) and to the orchestrator's own state-save commits.
+- **No micro-confirmations for reversible local work.** Local edits, lint fixes, test additions, scaffold files, in-worktree rewrites  -  just do them. Ask only for irreversible or shared-state actions: `git push`, `git push --force`, tag, third-party POST (Confluence, Jira, Slack), publish, deletes spanning many files, branch deletion. The threshold is "can the user undo this in 30 seconds via Cmd+Z or `git restore`?"  -  if yes, do not ask.
+- **Empty `AskUserQuestion` answer is not consent.** When the user submits without picking any option (empty answers map), do NOT silently apply the "Recommended" default. Re-ask the question, or proceed treating each item as unselected. Future-behavior preference questions are not preemptive  -  only ask when the answer changes what happens NOW.
+- **Question phrasing in Plan Mode.** Don't reference "the plan" in `AskUserQuestion` text while in plan mode  -  the user cannot see the plan until `ExitPlanMode`. Use `ExitPlanMode` for approval; `AskUserQuestion` only for choosing between concrete options.
+
+## Figma Access Tier (pipeline-wide, BLOCKING)
+
+When any task references a Figma frame (URL, node ID, or free-text "from the design"), the pipeline MUST establish a Figma ground-truth artefact via a 3-tier fallback chain before any UI line is written. The tier in use is persisted as `state.figmaAccess.tier` and read by every phase that consumes or verifies the reference (Phase 0 intake, Phase 1 analysis, Phase 2 planning, Phase 3 dev, Phase 4 review, Phase 5 manual test, Phase 7 channels).
+
+| Tier | Source | When chosen | Code Connect available |
+|---|---|---|---|
+| 1 | Figma MCP server (`mcp__claude_ai_Figma__get_design_context`, `get_screenshot`, `get_metadata`); MCP token resolves through `prefs.global.keychainMapping.figma_mcp` (for MCP server config bootstrap) | MCP auth succeeds (after one re-auth retry; on continued failure the user is asked: recreate the MCP token or continue with the PAT  -  never a silent fallthrough) | yes (`CodeConnectSnippet` blocks) |
+| 2 | Figma REST API (`GET /v1/files/{fileKey}/nodes`, `GET /v1/images/{fileKey}`) with Personal Access Token resolved via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma_pat` | Tier 1 unreachable AND PAT is mapped; on a 401/403 the user is asked the Expired-token decision (regenerate / different token / skip) before moving to Tier 3 | no, fall back to repo `*.figma.swift` / `*.figma.kt` mappings keyed by `fileKey` + `nodeId` |
+| 3 | User-attached screenshot in chat or task attachment | Tiers 1 + 2 both unreachable AND user has provided a screenshot | no  -  record an Open Question, pick the closest existing primitive WITH user confirmation, set Phase 4 reviewer flag to `review_blocking` |
+
+**Halt condition.** If all three tiers fail, halt the run and ask the user how to proceed. Never substitute primitives, never guess from Confluence prose, never derive layout from a text description.
+
+**Synced-file rule.** The literal Keychain service name for the Figma PAT is NEVER embedded in any synced file under `~/.claude/commands/` or `~/.copilot/skills/`. The mapping resolves at runtime through `prefs.global.keychainMapping.figma_pat`. See the Synced Command Hygiene rule below.
+
+Full chain definition, REST endpoints, URL parsing, Code Connect snippet rules, and the pre-UI checklist live in `rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate that text here; the canonical copy is the rule file.
+
+### Figma Access by Phase (pipeline-wide BLOCKING, v9.0.0)
+
+Per Locked decision 30 of `/multi-agent:analysis` and the parallel rule in `pipeline/rules/figma-pipeline.md`, Figma MCP / REST is allowed only in the analysis phase. Phase 2 through Phase 7 in every orchestrator mode (including `--dev`, `--local`, `--autopilot` combinations) consume the analysis document + repo Code Connect mappings.
+
+| Phase | MCP | REST | Sole design source |
+|---|---|---|---|
+| Analysis Phase 1 | allowed | allowed (Tier 2) | Figma ground truth |
+| Phase 2 Planning | forbidden | forbidden | analysis/<feature>-<platform>.md Section 6, 14 |
+| Phase 3 Dev | forbidden | forbidden | analysis doc Section 5, 6, 7, 13 + Code Connect *.figma.swift |
+| Phase 4 Review | forbidden | forbidden | analysis doc Section 21 References citations |
+| Phase 5 Test | forbidden | forbidden | analysis doc Section 13.6 + 15.2 variant subset |
+| Phase 6 Commit | forbidden | forbidden | analysis doc URL in PR body |
+| Phase 7 Report | forbidden | forbidden | analysis doc embedded in channel artefacts |
+
+Violation: smoke gate `smoke-no-mcp-in-dev-phases.sh` fails the run.
+
+Memory: [[mcp-only-in-analysis]]
+
+## Naming & Hygiene
+
+- **No task-sequence shortcuts in code.** "F1", "F2", "F3", "Feature1", "Step2" etc. are task-numbering UX labels in pickers / Confluence; they do not belong in identifiers, comments, log categories, commit messages, branch names, or file names. Use the full feature name (`FlightStatus`, `CheckoutFlow`, `PasswordReset`). Existing legacy references stay until a touch-up touches the same line; do not mass-rename without scope.
+- **No section sign `section` character.** Use the plain word `section` / `bölüm` / `böl.` or omit. This rule is part of the humanizer punctuation policy (no em-dash, en-dash, ellipsis, curly quotes, section sign) and applies to chat, docs, code comments, commit messages, analysis artifacts.
+- **Humanizer always on.** Every user-facing artifact  -  Confluence page, Jira description, commit message, PR body, code comments, status updates, chat replies  -  runs through the humanizer punctuation policy. No opt-in flag is needed; assume it is wanted. Per-channel tone differs (Local file = technical-explanatory, Confluence = formal-stakeholder, Jira = informal-technical) but the punctuation policy is fixed.
+
+## Synced Command Hygiene
+
+The `~/.claude/commands/` and `~/.copilot/skills/` trees are synced to a shared / semi-public pipeline repo. Anything that contains a per-user identifier leaks across users.
+
+- **Never embed personal Keychain service names** (e.g. literals containing your username or full-name initials) in files under `~/.claude/commands/` or `~/.copilot/skills/`. Route every token lookup through `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` is read from `prefs.global.keychainMapping.<provider>` so the mapping lives in the per-user preferences file, not the command file.
+- **Never embed personal repo paths, email addresses, machine names** in synced commands. Use config placeholders (`{REPO_OWNER}`, `{IDENTITY_NAME}`, etc.) resolved at run-time.
+- The CI sync filter strips these patterns; embedding them is a regression caught after the fact, after the leaked value is already in the public repo's history.
 
 ## Subagent Contract
 
@@ -185,5 +243,5 @@ Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `
   ```json
   {"status": "complete", "findings": [...], "files_changed": [...], "blocking": false}
   ```
-- Subagents receive **minimum viable context** — diff + relevant files, never the whole repo.
-- Subagents never write state, never post to external systems — the orchestrator owns side effects.
+- Subagents receive **minimum viable context**  -  diff + relevant files, never the whole repo.
+- Subagents never write state, never post to external systems  -  the orchestrator owns side effects.

package/pipeline/commands/multi-agent/refs/swiftui-guide.md

@@ -1,7 +1,9 @@
 ## SwiftUI Component Generation Guide (Generic)
 
+> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single UI line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `pipeline/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
+
 When the task involves creating a SwiftUI component (any project), follow this architecture.
-These practices come from the battle-tested Figma-to-SwiftUI pipeline — apply them in every iOS project.
+These practices come from the battle-tested Figma-to-SwiftUI pipeline  -  apply them in every iOS project.
 
 ### Component Architecture: Configuration / View / Modifiers
 
@@ -21,7 +23,7 @@ These practices come from the battle-tested Figma-to-SwiftUI pipeline — apply
 
 ### Configuration Purity Rules
 
-Configuration is a **pure value type** — zero side effects, zero view logic:
+Configuration is a **pure value type**  -  zero side effects, zero view logic:
 
 ```swift
 // Configuration: VALUES ONLY
@@ -36,10 +38,10 @@ struct ButtonConfiguration {
 
 **What should NOT be in Configuration:**
 
-- `@Binding`, `@State`, `@ObservedObject` — these belong in View
-- Closures (`onTap: () -> Void`) — these belong in View
-- `@ViewBuilder` content — View
-- Computed properties — logic stays in View
+- `@Binding`, `@State`, `@ObservedObject`  -  these belong in View
+- Closures (`onTap: () -> Void`)  -  these belong in View
+- `@ViewBuilder` content  -  View
+- Computed properties  -  logic stays in View
 - Any protocol conformance except `Equatable`, `Hashable`, `Sendable`
 
 ### Fluent Modifier Pattern
@@ -100,13 +102,13 @@ enum ButtonStyle {
 }
 ```
 
-**Never use `if/else` chains in the View body for variant styling** — push it into the enum or configuration.
+**Never use `if/else` chains in the View body for variant styling**  -  push it into the enum or configuration.
 
 ### Nested Component Handling
 
 If the design contains sub-components (e.g. a Card with an inner Badge):
 
-1. Check if the sub-component already exists in the project — **reuse it**
+1. Check if the sub-component already exists in the project  -  **reuse it**
 2. If not, decide: inline (simple, <3 props) or extract (reusable, complex)
 3. Pass sub-component configuration through parent: `CardConfiguration.badgeConfig: BadgeConfiguration?`
 
@@ -114,9 +116,9 @@ If the design contains sub-components (e.g. a Card with an inner Badge):
 
 Every interactive element MUST have:
 
-- `accessibilityLabel` — what it is (e.g. "Submit button")
-- `accessibilityHint` — what it does (e.g. "Submits the form") — only if not obvious from label
-- `accessibilityIdentifier` — for UI testing (e.g. `"button_submit"`)
+- `accessibilityLabel`  -  what it is (e.g. "Submit button")
+- `accessibilityHint`  -  what it does (e.g. "Submits the form")  -  only if not obvious from label
+- `accessibilityIdentifier`  -  for UI testing (e.g. `"button_submit"`)
 - Correct traits: `.isButton`, `.isHeader`, `.isSelected`, `.isToggle`
 - Minimum tap target: **44x44pt** (Apple HIG)
 
@@ -144,27 +146,27 @@ Previews must show **all meaningful variants**, not just the default:
 
 | Layer      | Tool           | Validates                                             | Priority                |
 | ---------- | -------------- | ----------------------------------------------------- | ----------------------- |
-| Structural | ViewInspector  | Hierarchy, subview existence, applied modifiers       | P0 — always             |
-| Visual     | Snapshot Tests | Pixel render: light/dark, RTL/LTR, Dynamic Type       | P1 — complex components |
-| Behavioral | Unit Tests     | State changes, closure calls, configuration mutations | P0 — always             |
+| Structural | ViewInspector  | Hierarchy, subview existence, applied modifiers       | P0  -  always             |
+| Visual     | Snapshot Tests | Pixel render: light/dark, RTL/LTR, Dynamic Type       | P1  -  complex components |
+| Behavioral | Unit Tests     | State changes, closure calls, configuration mutations | P0  -  always             |
 
 **Test naming:** `test_{scenario}_{expected}` or `test_{whatItDoes}`
 
 ```swift
-// ViewInspector — structure
+// ViewInspector  -  structure
 func test_hasTitle() throws {
     let sut = ButtonView(configuration: .init(title: "OK"))
     let text = try sut.inspect().find(text: "OK")
     XCTAssertNotNil(text)
 }
 
-// Unit — configuration mutation via modifier
+// Unit  -  configuration mutation via modifier
 func test_titleModifier_updatesConfiguration() {
     let sut = ButtonView().title("Submit")
     XCTAssertEqual(sut.configuration.title, "Submit")
 }
 
-// Snapshot — visual regression
+// Snapshot  -  visual regression
 func test_snapshot_light_primary() {
     assertSnapshot(of: ButtonView(configuration: .init(title: "OK")),
                    as: .image(layout: .device(config: .iPhone13)))
@@ -183,22 +185,22 @@ After implementation, **always run build before considering complete**:
 
 Before marking a component as done:
 
-1. No magic numbers — all values are tokens or named constants
-2. Configuration purity — no side-effects, closures, or view logic in Config
-3. Modifier chain works — each modifier returns a new View with updated config
-4. Accessibility — labels, hints, identifiers, traits, 44pt tap targets
-5. Preview coverage — all meaningful variants, dark mode, RTL, Dynamic Type
-6. Tests — structural (ViewInspector) + behavioral (Unit), snapshot if complex
-7. Dark mode — correct in both color schemes
-8. Dynamic Type — text scales without layout breaking
-9. RTL — leading/trailing used, layout mirrors correctly
-10. Variant exhaustiveness — all enum cases handled, no default catch-all
-11. Build passes — zero errors, zero warnings on component files
-12. Self-documenting — code is clear without comments, MARK sections organized
+1. No magic numbers  -  all values are tokens or named constants
+2. Configuration purity  -  no side-effects, closures, or view logic in Config
+3. Modifier chain works  -  each modifier returns a new View with updated config
+4. Accessibility  -  labels, hints, identifiers, traits, 44pt tap targets
+5. Preview coverage  -  all meaningful variants, dark mode, RTL, Dynamic Type
+6. Tests  -  structural (ViewInspector) + behavioral (Unit), snapshot if complex
+7. Dark mode  -  correct in both color schemes
+8. Dynamic Type  -  text scales without layout breaking
+9. RTL  -  leading/trailing used, layout mirrors correctly
+10. Variant exhaustiveness  -  all enum cases handled, no default catch-all
+11. Build passes  -  zero errors, zero warnings on component files
+12. Self-documenting  -  code is clear without comments, MARK sections organized
 
 ### Compliance Rules (maps to dev-toolkit MCP audit tools)
 
-These rules ensure your code passes `ios_accessibility_audit` and `ios_app_store_audit` without issues. Follow them during development — don't wait for audit to catch problems.
+These rules ensure your code passes `ios_accessibility_audit` and `ios_app_store_audit` without issues. Follow them during development  -  don't wait for audit to catch problems.
 
 #### Accessibility (validated by `ios_accessibility_audit`)