@mmerterden/multi-agent-pipeline 10.8.0 → 10.12.0

package/pipeline/commands/multi-agent/generate-bug.md

@@ -0,0 +1,33 @@
+---
+description: "Create a standards-compliant Jira Bug: mines project conventions, drafts in outputLanguage, full preview + explicit approval before create."
+argument-hint: "[\"<free-text description>\"] [figma-url]  -  both optional; pasted logs/screens in the text land in Steps to Reproduce / Environment"
+---
+
+# multi-agent generate-bug  -  Standards-Compliant Jira Bug Creator
+
+**Input**: $ARGUMENTS
+
+Creates exactly one Jira **Bug**, and only after explicit approval. No branches, no commits, no worktrees, no pipeline chaining. The draft learns the target project's conventions from its recent Bugs (summary format, description template, labels, components, priority norms) and offers active-sprint placement when a sprint is running.
+
+> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`  -  an intentional exception to the "external payloads stay English" default, because the issue is authored for the user's team. `label`/`header` stay English.
+
+## Profile
+
+| Key | Value |
+|---|---|
+| `ISSUE_TYPE` | `Bug` |
+| Default description sections | Steps to Reproduce, Expected Result, Actual Result, Environment, Design Reference (only when a Figma URL is given), Notes |
+| JQL sample filter | `issuetype = Bug` |
+| Priority default | mined norm from sampled Bugs (bug priorities often skew higher  -  respect the project's own norm) |
+
+## Flow
+
+Read `$HOME/.claude/commands/multi-agent/refs/generate-issue.md` and execute the 11-step shared flow with the profile above. Non-negotiables restated:
+
+- Free-text parsing maps logs, stack traces, and device/OS mentions into Steps to Reproduce and Environment; anything underivable is asked in step [7/11], never invented.
+- Ask the user (AskUserQuestion) about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields, missing Steps to Reproduce / Environment.
+- Step [8/11] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
+
+## Error paths
+
+See `refs/generate-issue.md` Error paths. No command-specific additions.

package/pipeline/commands/multi-agent/generate-task.md

@@ -0,0 +1,33 @@
+---
+description: "Create a standards-compliant Jira Task: mines project conventions, drafts in outputLanguage, full preview + explicit approval before create."
+argument-hint: "[\"<free-text description>\"] [figma-url]  -  both optional, asked interactively when missing"
+---
+
+# multi-agent generate-task  -  Standards-Compliant Jira Task Creator
+
+**Input**: $ARGUMENTS
+
+Creates exactly one Jira **Task**, and only after explicit approval. No branches, no commits, no worktrees, no pipeline chaining. The draft learns the target project's conventions from its recent Tasks (summary format, description template, labels, components, priority norms) and offers active-sprint placement when a sprint is running.
+
+> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`  -  an intentional exception to the "external payloads stay English" default, because the issue is authored for the user's team. `label`/`header` stay English.
+
+## Profile
+
+| Key | Value |
+|---|---|
+| `ISSUE_TYPE` | `Task` |
+| Default description sections | Goal, Scope, Acceptance Criteria, Design Reference (only when a Figma URL is given), Notes |
+| JQL sample filter | `issuetype = Task` |
+| Priority default | mined norm from sampled Tasks |
+
+## Flow
+
+Read `$HOME/.claude/commands/multi-agent/refs/generate-issue.md` and execute the 11-step shared flow with the profile above. Non-negotiables restated:
+
+- Ask the user (AskUserQuestion) about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields.
+- Step [8/11] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
+- Never invent Goal, Scope, or Acceptance Criteria content the user did not supply.
+
+## Error paths
+
+See `refs/generate-issue.md` Error paths. No command-specific additions.

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

@@ -111,6 +111,8 @@ Post-Hoc & Side-Channel:
   /multi-agent:analysis ["analysis-name"]  Feature-spec analysis (Figma + Swagger + Confluence + repos) → per-platform v3 doc (23-section Full / 7-section Lite)
   /multi-agent:analysis-resolve [doc]      Resolve Section 20 open questions of an analysis doc, one at a time with source-labeled candidates
   /multi-agent:build-optimize iOS-only Xcode build perf wrapper → benchmark + analyze + recommend-first .build-benchmark/optimization-plan.md
+  /multi-agent:generate-task ["desc"] [figma-url]  Create a Jira Task matching team conventions (mining + active sprint + preview & approval)
+  /multi-agent:generate-bug ["desc"] [figma-url]   Create a Jira Bug matching team conventions (mining + active sprint + preview & approval)
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
@@ -220,6 +222,10 @@ Examples:
   # Review current diff only
   /multi-agent:review
 
+  # Create a Jira issue that matches team conventions (preview + approval before create)
+  /multi-agent:generate-task "Profile screen empty state" https://figma.com/design/abc?node-id=1-2
+  /multi-agent:generate-bug "Login crash on iOS 17, see attached log"
+
 ------------------------------------------------------------
 
 Logs: $HOME/.claude/logs/multi-agent/{project}/{task-id}/
@@ -318,6 +324,8 @@ Post-Hoc & Side-Channel:
   /multi-agent:analysis ["analysis-name"]  Feature-spec analizi (Figma + Swagger + Confluence + repolar) → platform başına v3 doküman (23 bölüm Full / 7 bölüm Lite)
   /multi-agent:analysis-resolve [doc]      Analiz dokümanının Bölüm 20 açık sorularını kaynak etiketli adaylarla teker teker çözer
   /multi-agent:build-optimize iOS-only Xcode build performance wrapper → benchmark + analiz + recommend-first .build-benchmark/optimization-plan.md
+  /multi-agent:generate-task ["açıklama"] [figma-url]  Takım standartlarına uygun Jira Task oluştur (convention mining + aktif sprint + önizleme & onay)
+  /multi-agent:generate-bug ["açıklama"] [figma-url]   Takım standartlarına uygun Jira Bug oluştur (convention mining + aktif sprint + önizleme & onay)
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
@@ -427,6 +435,10 @@ Quality & Telemetry (advisory, default açık  -  prefs.global.* ile kapatılabi
   # Sadece mevcut diff'i review et
   /multi-agent:review
 
+  # Takım standartlarına uygun Jira issue oluştur (oluşturmadan önce önizleme + onay)
+  /multi-agent:generate-task "Profil ekranı empty state" https://figma.com/design/abc?node-id=1-2
+  /multi-agent:generate-bug "iOS 17'de login crash, log ekte"
+
 ------------------------------------------------------------
 
 Log'lar: $HOME/.claude/logs/multi-agent/{project}/{task-id}/

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

@@ -22,6 +22,13 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
    git checkout {branch-name}
    ```
 
+   Then mark the tracker as waiting (this CONTINUES the task's existing `tracker-state.json`; never `init` here - see `refs/tracker-contract.md` "Continuation runs"). On Claude Code in a fresh session, first rebuild the TaskList from state per the same contract:
+   ```bash
+   bash $HOME/.claude/scripts/phase-tracker.sh update 5 in_progress
+   bash $HOME/.claude/scripts/phase-tracker.sh now 5 "awaiting local test (user)"
+   bash $HOME/.claude/scripts/phase-tracker.sh render
+   ```
+
 4. **Tell the user how to test**:
    ```
    🧪 Switched to branch: {branch-name}
@@ -39,5 +46,5 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
 5. **Wait for the user's reply**
 
 6. **Branch on the answer**:
-   - **OK** → recreate the worktree, continue to Phase 6
-   - **Fix needed** → recreate the worktree, apply the fix
+   - **OK** → `phase-tracker.sh update 5 completed` + `phase-tracker.sh meta 5 Result "local test passed (user)"`, recreate the worktree, continue to Phase 6
+   - **Fix needed** → `phase-tracker.sh now 5 "applying fix: <summary>"`, recreate the worktree, apply the fix

package/pipeline/commands/multi-agent/refs/channels/pr.md

@@ -120,7 +120,7 @@ Single-repo tasks return one entry from `channels-multi-repo.sh targets ...` wit
 The Bitbucket REST API returns `409 Conflict` if `version` is stale. Adapter behaviour:
 
 1. Refetch PR JSON, retry the PUT once with the new `version`.
-2. Second mismatch → fail this adapter, log reason, return `{status: "failed", reason: "version conflict"}`. Other adapters keep running  -  non-blocking by Step 6 contract.
+2. Second mismatch → fail this adapter, log reason, return `{status: "failed", reason: "version conflict"}`. Other adapters keep running  -  non-blocking by Step 7 contract.
 
 ## Flags that affect this adapter
 

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

@@ -6,19 +6,20 @@
 
 ---
 
-## 1. Command Inventory (35 commands)
+## 1. Command Inventory (37 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, delete, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
-help, issue, jira, kill, language, local, local-autopilot, log, manual-test,
-prune-logs, purge, refactor, resume, review, scan, search, setup, stack, status,
-sync, test, update
+generate-bug, generate-task, help, issue, jira, kill, language, local,
+local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review,
+scan, search, setup, stack, status, sync, test, update
 ```
 
 Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
+- **Issue generators** (one-shot, no worktree, hard approval gate before create): `generate-task`, `generate-bug`
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
@@ -29,7 +30,7 @@ Categories:
 
 ### 1.1 Figma component subphase skills
 
-In addition to the 35 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
+In addition to the 37 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
 
 | Location | Skill count | Purpose |
 |---|---|---|
@@ -311,7 +312,7 @@ For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; th
 
 This contract is validated by:
 
-- `smoke-cross-cli-behavior.sh`  -  asserts all 35 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
+- `smoke-cross-cli-behavior.sh`  -  asserts all 37 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
 - `smoke-commands-skills-parity.sh` (50 assertions)  -  enforces colon-form command ↔ dash-form skill directory parity
 - `smoke-compliance-skills.sh` (45 assertions)  -  enforces store-compliance skill catalog + 4 consumer wiring
 - `smoke-personal-data.sh`  -  extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs

package/pipeline/commands/multi-agent/refs/generate-issue.md

@@ -0,0 +1,197 @@
+# Generate Issue  -  Shared Flow (generate-task / generate-bug)
+
+> **TLDR**  -  Shared 11-step flow for `/multi-agent:generate-task` and `/multi-agent:generate-bug`. Mines the target project's existing issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
+
+Consumed by `generate-task.md` and `generate-bug.md` via their profile blocks (`ISSUE_TYPE`, default description sections, JQL sample filter). This ref is never invoked directly.
+
+## Hard rules (must not regress)
+
+- **Approval gate is absolute.** Step [8/11] (full preview + explicit approval) runs on every invocation. There is no autopilot variant of these commands and no preference that skips the gate. `Cancel` means nothing was created.
+- **Never invent content.** Anything the user did not supply and mining could not derive stays an open question (step [7/11]) or an explicitly empty section  -  never fabricated repro steps, environments, or acceptance criteria.
+- **Issue content language follows `prefs.global.outputLanguage`.** Summary and description are written in the user's output language (intentional exception to the "external payloads stay English" default  -  the issue is authored FOR the user's team). Code identifiers, file paths, and URLs stay verbatim. AskUserQuestion `question`/`description` also follow `outputLanguage`; `label`/`header` stay English.
+- **UTF-8 verbatim POST path** (same as `refs/channels/jira.md`): description body goes to a file, `jq -n --rawfile` builds the payload, `curl --data-binary @file` ships it. Never round-trip through `unicode_escape`/`latin-1`, never hand-roll a re-encoding helper. Jira wiki markup (`h3.` headings, `[text|url]` links), real newlines, no HTML entities.
+- **Humanizer pass** on the description body after composition, before the preview render.
+- **Read-only until approval.** Steps 1-8 perform only GET requests. The first write of any kind is the `POST /rest/api/2/issue` in step [9/11].
+
+## Flow
+
+### [1/11] Pick account (`_account-picker`)
+
+```bash
+ACCOUNTS=$(~/.claude/lib/account-resolver.sh --providers jira)
+TOKEN=$(~/.claude/lib/credential-store.sh get "$ACCOUNT_JIRA_TOKEN_KEY")
+```
+- Single account → auto-select silently (picker-contract behavior); multiple → AskUserQuestion.
+- Output: `ACCOUNT_JIRA_TOKEN_KEY`, `ACCOUNT_JIRA_HOST`.
+- Token missing/expired → Token Save Flow from `setup.md` inline; user skips → abort, nothing created.
+
+### [2/11] Resolve project key
+
+Fallback chain (same as `refs/issue-jira-triad.md` Create path):
+1. `figmaConfig.jira.projectKey` (per-project config, when running inside a configured repo)
+2. `prefs.global.defaultJiraKey`
+3. Fetch and ask:
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/project" \
+  | python3 -c 'import json,sys; [print(p["key"]+"\t"+p["name"]) for p in json.load(sys.stdin)]'
+```
+   AskUserQuestion (single-select) → cache the choice to `prefs.global.defaultJiraKey`.
+- Output: `PROJECT_KEY`.
+
+### [3/11] Parse input
+
+- Any `figma.com` URL in `$ARGUMENTS` → `FIGMA_URL`. Node-id normalization: `-` → `:`. Branch URLs use `branchKey` as effective `fileKey` (see `rules/figma-pipeline.md` URL parsing).
+- Everything else → `FREE_TEXT`.
+- Both empty → AskUserQuestion (free-text, in `outputLanguage`): "Describe the {task|bug} you want to open."
+- `FIGMA_URL` is always optional. Never ask for one; only use it when given.
+
+### [4/11] Convention mining + field discovery + sprint detection (read-only)
+
+Three GET groups. Run them before drafting anything.
+
+**4a. Sample recent same-type issues:**
+```bash
+JQL="project = ${PROJECT_KEY} AND issuetype = ${ISSUE_TYPE} ORDER BY created DESC"
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/search?jql=$(printf '%s' "$JQL" | python3 -c 'import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))')&fields=summary,description,labels,components,priority,fixVersions&maxResults=30"
+```
+Extract from the sample (thresholds are guidance, not hard gates):
+- **Summary prefix pattern**: leading `[...]` or `AREA:` token frequency. Appears in >= 40% of samples → adopt as suggested prefix; top 2-3 prefixes become AskUserQuestion options in step 7 when ambiguous.
+- **Description heading set**: lines matching `h[1-4]\.` or `*bold*` header style, frequency-ranked. A heading set shared by >= 50% of samples overrides the profile's default sections  -  the team template wins.
+- **Top labels / components**: top 5 each by frequency → option lists for step 7.
+- **Priority norm**: modal priority for this issuetype → pre-filled default, editable in preview.
+- **Epic usage rate**: share of sampled issues carrying an epic link → decides whether step 7 asks for an epic.
+
+**4b. Field discovery (createmeta):**
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/createmeta?projectKeys=${PROJECT_KEY}&issuetypeNames=${ISSUE_TYPE}&expand=projects.issuetypes.fields"
+```
+- 404 or empty `projects[]` (newer Jira DC deprecates the classic form) → fall back to the paged endpoint: `GET /rest/api/2/issue/createmeta/{PROJECT_KEY}/issuetypes` then `GET /rest/api/2/issue/createmeta/{PROJECT_KEY}/issuetypes/{issuetypeId}`.
+- Every field with `required: true` beyond project/issuetype/summary/description/reporter → step 7 question (options from `allowedValues` when present, free-text fallback).
+- Generic custom-field detection by `schema.custom` id  -  never assume field ids:
+  - Sprint: `com.pyxis.greenhopper.jira:gh-sprint`
+  - Epic Link: `com.pyxis.greenhopper.jira:gh-epic-link`
+  - Team-like fields: case-insensitive name match on `Team`
+- 403 → warn "cannot read project field metadata", continue with profile defaults; required fields surface reactively via the 400 path in step 9.
+
+**4c. Board + active sprint (Agile REST):**
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://$ACCOUNT_JIRA_HOST/rest/agile/1.0/board?projectKeyOrId=${PROJECT_KEY}"
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://$ACCOUNT_JIRA_HOST/rest/agile/1.0/board/${BOARD_ID}/sprint?state=active"
+```
+- Multiple boards → AskUserQuestion (board name + type). One board → silent. Zero boards or Agile API 404 → the sprint option is silently omitted; the preview notes "backlog only (no board found)".
+- Active sprint found → remember `SPRINT_ID` + name for the step 7 placement choice. None → backlog only; if a `state=future` sprint exists, mention it in the preview as information.
+
+### [5/11] Figma context (only when `FIGMA_URL` is set)
+
+Follow the 3-tier chain from `rules/figma-pipeline.md`: Tier 1 MCP (`get_design_context` / `get_screenshot`, one re-auth retry) → Tier 2 REST (`keychainMapping.figma_pat`) → Tier 3 ask the user for a screenshot or proceed link-only.
+
+> This command is standalone (same class as `/multi-agent:analysis`), so Figma MCP use here is allowed  -  it is not a dev-phase violation under the "No MCP outside analysis phase" rule.
+
+- Output: frame name, node id, optional screenshot PNG in `/tmp/generate-issue-$$-figma.png` for the step 10 attachment opt-in.
+- Any tier failure degrades gracefully; Figma never blocks issue creation. Link-only is always acceptable.
+
+### [6/11] Compose draft
+
+Write summary + description in `outputLanguage`:
+- **Summary**: `{minedPrefix} {concise title}`, truncated to 255 chars.
+- **Description**: mined heading set from 4a (or the profile's default sections when mining found no dominant template), in Jira wiki markup (`h3.` headings).
+  - Task profile fills: Goal, Scope, Acceptance Criteria, Notes from `FREE_TEXT`.
+  - Bug profile fills: Steps to Reproduce, Expected Result, Actual Result, Environment, Notes from `FREE_TEXT`.
+  - Missing information stays an open question for step 7  -  never invented.
+  - `FIGMA_URL` set → add `h3. Design Reference` with `[Figma|{FIGMA_URL}]` + frame name + node id.
+- Run the humanizer skill on the description body.
+- Write the final body to `/tmp/generate-issue-$$.txt` (UTF-8, real newlines) for the `--rawfile` POST.
+
+### [7/11] Clarifying questions (only genuinely unknown fields)
+
+Batched AskUserQuestion(s), each with a "Skip / leave unset" option where Jira allows it:
+- **Component**: mined top components + "none"  -  only when the project uses components.
+- **Epic link**: only when 4a epic usage rate is high. Options from `project = {KEY} AND issuetype = Epic AND statusCategory != Done`.
+- **Priority**: only when the mined norm is ambiguous; otherwise pre-fill the norm and let the preview edit change it.
+- **Labels**: mined top labels, multiSelect.
+- **Assignee**: "me / unassigned / someone else".
+- **Sprint placement**: "Active sprint: {name}" vs "Backlog"  -  only when an active sprint exists.
+- **Required custom fields** from 4b not yet resolved (allowedValues as options).
+- **Bug profile**: Steps to Reproduce or Environment underivable from `FREE_TEXT` → ask here.
+
+Rule: never ask about anything already answerable from mining or the input. Regardless of how complete the draft looks, step 8 always runs.
+
+### [8/11] Full preview + approval gate (never skipped)
+
+Render the complete issue in chat: project, issuetype, summary, the full description body, priority, labels, components, epic, assignee, sprint/backlog placement, attachment plan (Figma screenshot upload  -  default off, opt-in).
+
+Then AskUserQuestion (`question` in `outputLanguage`, e.g. tr: "Bu sekilde olusturuyorum, onayliyor musun?"):
+
+| Option | Behavior |
+|---|---|
+| `Approve` | Proceed to step 9 |
+| `Edit` | Free-text "what should change?" → apply → re-render the FULL preview → re-ask. Loop, no iteration cap |
+| `Cancel` | Stop. Nothing was created; say so explicitly |
+
+This gate has no bypass. No flag, mode, or preference suppresses it.
+
+### [9/11] Create
+
+```bash
+jq -n --rawfile desc /tmp/generate-issue-$$.txt \
+  --arg key "$PROJECT_KEY" --arg type "$ISSUE_TYPE" --arg summary "$SUMMARY" \
+  '{fields: {project: {key: $key}, issuetype: {name: $type}, summary: $summary, description: $desc}}' \
+  > /tmp/generate-issue-$$-payload.json
+# merge approved optional fields (priority / labels / components / epic / assignee / required customs) into .fields with jq before POST
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data-binary @/tmp/generate-issue-$$-payload.json \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue"
+```
+- Parse `key` from the response → `NEW_KEY`.
+- 400 with field errors → show Jira's per-field error verbatim, return to step 7 for exactly those fields, then re-run step 8 (full preview again).
+
+### [10/11] Post-create steps
+
+Each step is failure-isolated: on error, warn + continue  -  the issue already exists.
+
+1. **Sprint** (when chosen in step 7/8):
+```bash
+jq -n --arg key "$NEW_KEY" '{issues: [$key]}' > /tmp/generate-issue-$$-sprint.json
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  --data-binary @/tmp/generate-issue-$$-sprint.json \
+  "https://$ACCOUNT_JIRA_HOST/rest/agile/1.0/sprint/${SPRINT_ID}/issue"
+```
+   Post-create move instead of a Sprint custom field in the create payload: field-id-agnostic, works on every Jira Software instance.
+2. **Figma remote link** (when `FIGMA_URL` set):
+```bash
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"object":{"url":"'"$FIGMA_URL"'","title":"Figma design"}}' \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/remotelink"
+```
+3. **Screenshot attachment** (only when opted in during preview):
+```bash
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "X-Atlassian-Token: no-check" \
+  -F "file=@/tmp/generate-issue-$$-figma.png" \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/attachments"
+```
+
+### [11/11] Report
+
+```
+Created {NEW_KEY}: https://{ACCOUNT_JIRA_HOST}/browse/{NEW_KEY}
+```
+Plus one line per post-create step that ran (sprint placement, remote link, attachment) and any that were skipped with reason.
+
+## Error paths
+
+| Condition | Behavior |
+|---|---|
+| Token missing/expired (401) | Token Save Flow from `setup.md` inline; user skips → abort with message, nothing created |
+| Search 403 / createmeta denied | Warn "cannot read project conventions/fields"; continue with profile-default template; required fields asked reactively on 400 |
+| Zero sampled issues (new project) | Skip mining, use profile defaults, note in preview "no prior issues to learn from" |
+| Agile API 404 / no boards | Omit sprint choice, backlog implied, say so in preview |
+| No active sprint | Offer backlog only; mention the next `state=future` sprint when one exists |
+| Figma Tier 1 fails | Tier 2; Tier 2 fails → Tier 3 (ask screenshot or link-only). Never block issue creation on Figma |
+| Create 400 (field errors) | Show per-field errors, loop back to step 7 for those fields, re-preview |
+| Create 5xx / network | Show the error, offer one retry, then abort  -  keep `/tmp/generate-issue-$$.txt` and print its path so the draft survives |
+| Post-create step failure | Warn + continue (issue exists); print a manual-fix hint |

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

@@ -21,6 +21,18 @@ When a token resolves but the service rejects it (401 / 403), do not silently sk
 
 The question asks a *choice*; the replacement value still flows through the clipboard, never chat. `smoke-no-token-prompt.sh` greps for value-prompts (`enter token`, `paste token`, `API key:`) - decision labels like `Regenerate` / `Skip and continue` do not trip it.
 
+Expiry is also checked **proactively at init**: Phase 0 Step 0.7 (`refs/phases/phase-0-init.md`) probes every token the run will need with one cheap call each (cached via `global.serviceStatus`, TTL 300s) and runs this same decision at init instead of waiting for the first mid-run 401. The mid-run 401 path stays as the safety net.
+
+#### Figma MCP token lifecycle (critical)
+
+`figma_mcp` is the only OAuth token in the registry (`figu_` prefix, ~90-day expiry); everything else is a long-lived PAT. A dead MCP token silently degrades every Figma consumer to Tier 2/3, so its expiry is handled specially:
+
+1. **Refresh token**: the generation flow stores a refresh token under `<keychainMapping.figma_mcp>_Refresh`. `~/.claude/lib/figma-mcp-refresh.sh` performs a silent renewal (OAuth refresh grant; client credentials read from the `.figma-oauth.json` next to `prefs.global.tokenScripts.figma_mcp`). Exit 0 = renewed in place, no user interaction. This ALWAYS runs before any question is asked.
+2. **Generation script**: `prefs.global.tokenScripts.figma_mcp` may point to a user-owned script that produces a fresh MCP token via Dynamic Client Registration + browser OAuth and saves it to the Keychain. When silent renewal fails, the expired-token question offers **Regenerate now (script)** which runs it (interactive runs only  -  it opens a browser).
+3. **Fallbacks**: Token Save Flow (clipboard) or continue degraded on Tier 2 (REST PAT), per the Phase 0 Step 0.7 decision table.
+
+`prefs.global.tokenScripts` maps service ids to user-owned generation scripts (`{"figma_mcp": "/path/to/start_mcp.sh"}`); paths are personal and live only in the local preferences file  -  never in synced command files. Script output is status lines only  -  token values never enter chat or logs.
+
 Reasons:
 - Asking for a token in chat leaks it into the conversation transcript and any audit log.
 - The user has already configured the keychain; missing/expired is a setup issue, not a per-run issue.

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

@@ -98,6 +98,44 @@ Log the resolved tier in the agent log:
 
 Full chain definition, REST endpoints, URL parsing, canonical-component contract: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate it here.
 
+#### Step 0.6 - Update check (advisory, opt-out via `prefs.global.updateCheck.enabled`)
+
+Run `bash pipeline/scripts/update-check.sh` (cached per `updateCheck.ttlHours`, default 24h; 3s-bounded; every failure path silent). Empty output → continue. Output `<local>|<latest>` means a newer version exists:
+
+- **Interactive**: log `→ update available: v<local> -> v<latest>`, ask ONE AskUserQuestion  -  **Update now** (recommended) / **Continue without updating**. On *Update now* (or `updateCheck.autoUpdate: true`, which skips the question): run the `/multi-agent:update` flow, log `→ updated to v<latest>`, continue the run (note in the log: already-loaded phase docs finish this run on the old version; full effect next session). On *Continue*: no re-ask until the TTL expires.
+- **Autopilot**: never ask (zero-interaction contract). Log `→ update available: ... (log-only; run /multi-agent:update)` and continue  -  unless `autoUpdate: true`, then update silently first.
+
+Advisory  -  NEVER blocks. Must run BEFORE Step 6 (worktree creation) so an accepted update cannot mutate `~/.claude` under a mid-phase run.
+
+#### Step 0.7 - Token expiry pre-flight (runs before Step 1 fetch)
+
+Validate the tokens THIS run will need before any of them is used mid-phase. Scope is derived, not exhaustive:
+
+| Run signal | Tokens to probe | Cheap probe (1 call each) |
+|---|---|---|
+| Input is Jira-id / Jira-url | `jira` | `GET /rest/api/2/myself` |
+| Input is GitHub issue / repo#N | `github` | `gh auth status` (or `GET /user`) |
+| Remote is Bitbucket | `bitbucket_token` | `GET /rest/api/1.0/application-properties` |
+| `reportChannels.confluence` true | `confluence` | `GET /rest/api/user/current` |
+| Task carries a Figma reference | `figma_mcp` (Tier 1), `figma` (Tier 2) | MCP `initialize` POST to `mcp.figma.com/mcp`; `GET api.figma.com/v1/me` |
+
+Results are cached in `global.serviceStatus` (existing TTL contract, default 300s)  -  a probe that ran in the last 5 minutes is not repeated.
+
+**Valid** → continue silently (one log line: `→ token pre-flight: N ok`).
+
+**Figma MCP expired / rejected  -  CRITICAL path.** The `figma_mcp` OAuth token (`figu_`) expires on a schedule (90 days), unlike the PATs. Because a dead MCP token silently degrades every Figma consumer to Tier 2/3 and has cost rebuild rounds, an expired `figma_mcp` is never deferred to mid-run:
+
+1. **Silent renewal first**: run `~/.claude/lib/figma-mcp-refresh.sh` (refresh grant via `<key>_Refresh` + the `.figma-oauth.json` client credentials next to `prefs.global.tokenScripts.figma_mcp`). Exit 0 → re-probe, log `→ figma mcp token renewed silently`, continue. No question asked.
+2. **Renewal impossible/rejected** (exit 1/2) → AskUserQuestion at init (`question`/`description` in `outputLanguage`): "Figma MCP token expired  -  update it now?"
+   - **Regenerate now (script)**  -  shown only when `prefs.global.tokenScripts.figma_mcp` is set: run that script (browser OAuth flow), then re-probe and continue.
+   - **Save a new token**  -  Token Save Flow from `setup.md` (clipboard path).
+   - **Continue degraded**  -  proceed on Tier 2 (REST PAT) for this run; log the downgrade.
+3. **Autopilot**: silent renewal only; if it fails, log `→ figma mcp token expired (autopilot: continuing on tier 2)` and continue degraded  -  never prompt.
+
+**Other tokens expired / rejected** → run the Expired-token decision from `refs/keychain.md` Rule 1 HERE at init (Regenerate / Use a different token / Skip and continue) instead of waiting for the first mid-run 401. A token that is structurally required for the input (e.g. the Jira PAT for a Jira-ID input) halts on skip, since Step 1 cannot fetch without it. Autopilot: skip-and-degrade semantics per Rule 1, halt only on structurally required tokens.
+
+Probe failures caused by network (timeout, DNS) are NOT treated as expiry  -  log and continue; the mid-run 401 path still exists as the safety net.
+
 #### Step 1  -  Parse Input
 
 **Branch from input**: If the user provided a branch name after the issue reference (space-separated), store as `baseBranch` and skip Step 3. Otherwise Step 3 asks interactively.
@@ -517,8 +555,8 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 After each clarifier call:
 
 ```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
-  score=$SCORE questions=$Q stop_and_ask=$STOP autopilot_mode=$AP \
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
+  model=haiku score=$SCORE questions=$Q stop_and_ask=$STOP autopilot_mode=$AP \
   duration_ms=$D tokens_in=$TI tokens_out=$TO
 ```
 

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

@@ -49,6 +49,16 @@ When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the en
 
 For non-component taskTypes (`bugfix`, `feature`, `refactor`, `chore`), continue with the standard TDD section below.
 
+#### Design fidelity contract (BLOCKING when the task carries a Figma reference)
+
+Applies to EVERY task whose analysis doc carries design ground truth (Section 6 rows, node IDs, screenshots)  -  component-dispatch AND TDD-path UI work alike. MCP stays forbidden here (analysis-only rule); the analysis doc IS the design:
+
+1. **1:1, not interpretation.** The captured frames are the reference for every UI line. Layout, variant states, copy, and colours come from the analysis doc's measured values  -  never eyeballed, never "close enough".
+2. **Code Connect decides the component.** A mapped component (`CodeConnectSnippet` / repo `*.figma.swift` / `*.figma.kt` row) MUST be used verbatim  -  sound-alike substitutes are forbidden; a missing modifier is added to the component's `+Modifiers` extension, never forked. No mapping exists -> write a NEW component per the Configuration/View/Modifiers architecture; never inline ad-hoc UI into the consumer screen.
+3. **Inter-component spacing is part of the design.** Gaps, paddings, and alignment BETWEEN components must match the frame's measured values, mapped to spacing tokens (`Spacing*`)  -  never invented numbers. A spacing/layout deviation is a `review_blocking` finding in Phase 4 Step 1.8, not a nitpick.
+
+Missing design data (variant, padding, copy) → HALT and instruct the user to re-run `/multi-agent:analysis`; never guess and never call Figma MCP from this phase.
+
 #### Re-entry from Phase 4 triage
 
 Phase 3 runs twice in the pipeline lifetime: first for initial development, then optionally for rework after Phase 4 review. **Phase 3 never acts on raw reviewer output.** It only consumes `triage.accepted` findings  -  Fable triage in Phase 4 already filtered false-positives, deferred out-of-scope items, and rejected noise.
@@ -286,6 +296,8 @@ When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with *
 
 **Combinable with autopilot**: `--dev autopilot` = zero interaction. Init → Dev → auto-commit → auto-PR → Report.
 
+**Tracker visibility during Opus dispatch**: on Claude Code the model switch to Opus happens via subagent dispatch, and the parent widget cannot move while an Agent call is in flight. Dispatch per task from the self-generated task list (never one monolithic call for the whole phase), set the pre-dispatch `activeForm` marker, and record tokens between chunks  -  full rules in `refs/tracker-contract.md` section "Delegated phases".
+
 ---
 
 #### v2.1.0+ Multi-Repo Mode

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

@@ -157,6 +157,8 @@ When `state.evidence.figma[]` is non-empty, the reviewer subagents MUST receive
 
 Visual-fidelity mismatches against the captured screenshot are BLOCKING findings, not nits:
 
+- Canonical component usage: the Code Connect-mapped component is used verbatim  -  a sound-alike substitute, a forked copy, or ad-hoc inline UI where a mapping exists is blocking (Phase 3 "Design fidelity contract")
+- Inter-component spacing: gaps, paddings, and alignment BETWEEN components match the design's measured values mapped to spacing tokens  -  invented numeric values are blocking
 - Avatar icon (presence, glyph, shape, position)
 - Field grouping (one rounded box vs two; separator vs gap)
 - Character counter visibility
@@ -390,30 +392,9 @@ After the triage verdict is computed, populate `triage.consensus`:
 
 ##### 3.7 Verify-by-test (opt-in, empirical validation of blocking findings)
 
-**Rationale:** a triage verdict is still a judgment call; a failing repro test is proof. Debating a finding costs tokens, running it costs one test invocation and kills false positives that survive adversarial framing.
+A triage verdict is judgment; a failing repro test is proof. Runs only when `prefs.global.verifyByTest.enabled` is `true` AND `accepted` contains a `blocking` finding; otherwise skip silently. **Full contract (verdict table, cleanup invariant, prompts): `refs/features/verify-by-test.md`  -  read it before executing this step.**
 
-**Gate:** runs only when `prefs.global.verifyByTest.enabled` is `true` AND the validated triage output contains at least one `accepted` finding with `severity: "blocking"`. Otherwise skip silently (no log noise). Full behavior spec: `refs/features/verify-by-test.md`.
-
-1. **Dispatch ONE verifier agent** (subagent_type: `general-purpose`, model: `prefs.global.verifyByTest.model`, default `sonnet`) for the iteration  -  not one per finding. Input: up to `verifyByTest.maxFindings` (default 3) accepted blocking findings (ordered as triage returned them), the diff hunks for their files, and the project's test conventions from Phase 1. Findings beyond the cap keep their judgment-only verdict; log `verify_by_test=cap-exceeded count=<n>`.
-2. **Per finding, the verifier writes ONE minimal repro test** asserting the CORRECT behavior the finding claims is broken, following the platform test conventions (framework, naming, location per phase-3-dev.md), then runs ONLY that test using the platform single-test invocation from Phase 3 (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, `npm test -- --testPathPattern=`, `./gradlew test --tests`), wrapped in `acquire_build_lock`/`release_build_lock`, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`.
-3. **Verdict mapping (fails toward keeping blockers):**
-
-| Repro test outcome | `verification.result` | Action on finding |
-| --- | --- | --- |
-| Test FAILS as the finding predicts | `confirmed` | Stays `accepted` blocking. Repro test is KEPT in the worktree and recorded in `redTests[]` as the RED test for the Phase 3 rework loop. |
-| Test PASSES (defect not reproducible) | `not-reproduced` | Downgrade is evidence-gated: `node pipeline/scripts/evidence-gate.mjs --claim test --status passed --evidence "$WORKTREE/.pipeline/verify-<i>.test.log"` must exit 0. On exit 0: move finding from `accepted[]` to `deferred[]` with reason `verify-by-test: not reproduced - repro test <testRef> passed`, delete the repro test file. On exit non-zero: treat as `inconclusive`. |
-| Compile error, timeout, or defect not expressible as a unit test | `inconclusive` | Stays `accepted` blocking (judgment-only verdict stands). Partial test file deleted, cause noted in `verification.note`. |
-
-4. **Cleanup invariant:** after Step 3.7 the only verifier artifacts left in the worktree are the confirmed repro tests listed in `redTests[]` (they get committed with the fix, satisfying the TDD contract) and logs under `$WORKTREE/.pipeline/` (already outside Phase 6 commit scope).
-5. **Persist + re-validate:** stamp each verified finding with a `verification` object (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = { attempted, confirmed, downgraded, inconclusive, redTests: [{file, testRef, issue}] }`, recompute `approved`, then re-run `validate-triage.mjs` on the mutated `$TRIAGE_FILE` under the same 3.2.1 gate protocol.
-6. **Timeout/fallback (mirrors 3.3):** the whole step is bounded by `verifyByTest.stepTimeoutSec` (default 600). On verifier crash or budget breach: no retry; remaining findings keep judgment-only verdicts, log `triage=verify-by-test-timeout`, proceed to Step 4. Never blocks the pipeline.
-
-Telemetry (per 3.4 conventions, best-effort):
-
-```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.verify_by_test \
-  attempted=$A confirmed=$C downgraded=$D inconclusive=$I duration_ms=$MS
-```
+Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 3 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 3 rework RED test; test PASSES -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on the log, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
 
 #### Step 4  -  Consensus + Action (triage-driven)
 

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

@@ -95,7 +95,12 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    "ok" -> proceeds to Phase 6 (WIP commit will be replaced via git reset HEAD~1 + proper commit)
    "fix: ..." -> worktree is recreated, returns to Phase 3
    ```
-5. Wait for user response
+5. Mark the tracker as waiting, then wait for the user response:
+   ```bash
+   bash $HOME/.claude/scripts/phase-tracker.sh now 5 "awaiting local test (user)"
+   bash $HOME/.claude/scripts/phase-tracker.sh render
+   ```
+   The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:finish` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`refs/tracker-contract.md` "Continuation runs").
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`

package/pipeline/commands/multi-agent/refs/phases/phase-7-report.md

@@ -101,6 +101,8 @@ Tracker: `phase-tracker.sh sub 7 1 "Channels dispatch" completed` (or `failed` i
 
 Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue  -  no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `refs/channels/issue-comment.md`.
 
+**Approval gate:** interactive runs show the composed comment body (and the Progress-flag diff intent) through the same preview + approval gate as channels Step 6 (`channels.md`) before posting  -  Approve & post / Edit / Cancel. Autopilot posts directly.
+
 Two paired actions, in order:
 
 ```bash
@@ -182,9 +184,11 @@ Skipped sections: when `planTodos.enabled` is false or no `plan.todos[]` was emi
 (embed `aggregate-metrics.mjs --since=<30 days ago> --json` output as collapsed JSON)
 ```
 
-**Telemetry emission** (mandatory): emit final event:
+**Telemetry emission** (mandatory): forward the phase's own LLM spend (humanizer + report compose calls) to the tracker, then emit the final event:
 
 ```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 7 report.compose \
+  model=$REPORT_MODEL tokens_in=$R_IN tokens_out=$R_OUT duration_ms=$R_DUR
 pipeline/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
   phases=$PHASE_COUNT review_cycles=$CYCLES lang=$PROMPT_LANG \
   channels_pr=$PR_STATUS channels_jira=$JIRA_STATUS \

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

@@ -21,6 +21,7 @@ Today pipeline users see a phase banner (`→ Phase 3: Dev`) and then silence fo
 - **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.
+- **Live mirror to the phase tracker**: each `normal`-tier emitted line is also mirrored to the active phase per `refs/tracker-contract.md` "Active phase" (Claude Code `TaskUpdate activeForm`, other CLIs `phase-tracker.sh now`) - the authoritative throttling rules live there.
 
 ### Examples