@mmerterden/multi-agent-pipeline 10.9.0 → 10.12.0

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

@@ -107,6 +107,35 @@ Run `bash pipeline/scripts/update-check.sh` (cached per `updateCheck.ttlHours`,
 
 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.
@@ -526,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

@@ -296,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

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
 

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

@@ -58,8 +58,9 @@ Phases by mode:
 | Mode | Phases |
 |---|---|
 | Full pipeline | 0,1,2,3,4,5,6,7 |
-| `--dev` | 0,3,6,7 |
-| `--autopilot`, `--dev autopilot` | same as dev, with confirmations skipped |
+| `--dev` | 0,3,5,6,7 |
+| `--dev autopilot`, `--dev local`, `--dev local autopilot` | 0,3,6,7 (Phase 5 interactive test gate dropped) |
+| `--autopilot` | same as full pipeline, with confirmations skipped |
 
 Register each phase:
 
@@ -118,9 +119,10 @@ Mode-specific phase sets:
 | Mode | TaskCreate set (in order) |
 |---|---|
 | Full pipeline (`/multi-agent`, `:autopilot`, `:local`, `:local-autopilot`) | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 (all 8) |
-| `:dev`, `:dev-autopilot`, `:dev-local`, `:dev-local-autopilot` | 0 → 3 → 5 → 6 → 7 (5 phases  -  1/2/4 omitted entirely) |
+| `:dev` | 0 → 3 → 5 → 6 → 7 (5 phases  -  1/2/4 omitted entirely) |
+| `:dev-autopilot`, `:dev-local`, `:dev-local-autopilot` | 0 → 3 → 6 → 7 (4 phases  -  1/2/4/5 omitted entirely; the autopilot/local variants drop the interactive Phase 5 test gate) |
 
-Note: in `--dev` modes the omitted phases (1, 2, 4) **do not get TaskCreate calls at all**  -  they're not part of the mode's phase set. The "[SKIPPED]" pattern above only applies if a normally-included phase is conditionally skipped at runtime.
+Note: in `--dev` modes the omitted phases (1, 2, 4  -  plus 5 in the autopilot/local variants) **do not get TaskCreate calls at all**  -  they're not part of the mode's phase set. The "[SKIPPED]" pattern above only applies if a normally-included phase is conditionally skipped at runtime. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc; this table mirrors those blocks.
 
 **Enforcement**: `smoke-tasklist-ordering.sh` scans every mode entry point doc (`commands/multi-agent.md`, `commands/multi-agent/{autopilot,local,local-autopilot,dev,dev-autopilot,dev-local,dev-local-autopilot}.md` + Copilot mirrors) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 
@@ -172,23 +174,40 @@ TaskUpdate({taskId: <dev_task>, activeForm: "Editing TopBarView.swift"})
 TaskUpdate({taskId: <dev_task>, activeForm: "Running xcodebuild test"})
 ```
 
-**Other CLIs**  -  `meta Now` key plus a render call:
+**Other CLIs**  -  the dedicated `now` action (quiet: writes `meta.Now`, never renders; the card picks it up at the next boundary render/update):
 ```bash
-bash $HOME/.claude/scripts/phase-tracker.sh meta 3 Now "→ editing TopBarView.swift"
-bash $HOME/.claude/scripts/phase-tracker.sh render
+bash $HOME/.claude/scripts/phase-tracker.sh now 3 "editing TopBarView.swift"
 ```
 
-The `Now` meta key shows up in the bordered card as `Now: → editing TopBarView.swift`.
+The `Now` value shows up in the bordered card as `Now: editing TopBarView.swift` (truncated to 60 chars by the script).
+
+**Progress-line mirror (required).** Every `normal`-tier progress line from the progress contract's canonical "When to emit" set is ALSO mirrored to the active phase, so the tracker always answers "what is it doing right now":
+
+- Claude Code: `TaskUpdate({activeForm: "<line text, arrow prefix stripped>"})`
+- Other CLIs: `phase-tracker.sh now <N> "<line text, arrow prefix stripped>"`
+
+Throttling rules: mirror only canonical-set lines (`verbose`-tier internals are not mirrored); at most one mirror per emitted line; skip the mirror when the text is identical to the last mirrored value; the mirror itself never triggers a render. Text is truncated to 60 chars.
+
+### Delegated phases  -  mirror limitation + chunked dispatch (required)
+
+When a phase's work is delegated to a subagent (Phase 3 Dev on Opus in `--dev` modes, `figma-to-component` dispatch, Phase 1 explorers, Phase 4 reviewers), the visual channel freezes for the duration of the Agent call: the orchestrator is blocked while the call is in flight, so it cannot fire `TaskUpdate` / `now` / `tokens`, and a subagent cannot drive the parent session's TaskList (its own TaskCreate/TaskUpdate calls land on an invisible child list). The progress-line mirror above can therefore only fire while the orchestrator holds control. Rules:
+
+1. **Pre-dispatch marker.** Immediately before every Agent call, set the active-phase line to the delegation itself, so the frozen interval at least states what is running and on which model:
+   - Claude Code: `TaskUpdate({activeForm: "Dev subagent (opus): <task subject>"})`
+   - Other CLIs: `phase-tracker.sh now <N> "dev subagent (opus): <task subject>"`
+2. **Chunk long delegations.** A phase whose delegated work spans multiple tasks MUST NOT go out as one monolithic Agent call. Dispatch per task (the Phase 2 task graph, or in `--dev` mode the self-generated task list, is the natural chunk boundary) so the orchestrator regains control at each boundary and refreshes `activeForm`, `tokens`, and `now` between chunks. Single-task phases and inherently atomic dispatches (one reviewer, one explorer) are exempt.
+3. **Post-chunk accounting.** When each chunk returns, record its token estimate (`phase-tracker.sh tokens <N> <in> <out>`) before dispatching the next chunk  -  not accumulated once at phase end.
 
 ### 5. Token accounting  -  automatic (manual top-up optional)
 
 The native TaskList header automatically prints `↑Nk tokens · thought for Ns`  -  Claude Code uses session-level metrics. For per-phase token attribution:
 
 ```bash
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <input_count> <output_count>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <input_count> <output_count> [cached_count]
+bash $HOME/.claude/scripts/phase-tracker.sh model  <N> <model_name>
 ```
 
-Token counts are additive  -  multiple calls accumulate. Stored per phase in the state file; surfaced in `:log` reports.
+Token counts are additive  -  multiple calls accumulate. `input_count` is FRESH input (cache-exclusive); the optional 4th arg is the prompt-cache-read count, priced at the discounted rate. `model` tags the phase so the card and the cost helper can price it. Stored per phase in the state file; surfaced in `:log` reports, on the bash card tile (`<elapsed> · <tok> tok · ~$<usd>`), and in the card footer (total USD + cached tokens).
 
 **MANDATORY: per-phase token narration on completion (v9.10.2).** The native
 TaskList widget cannot display per-phase tokens  -  it shows name, status, and
@@ -203,9 +222,22 @@ Phase <N> <name> tamamlandi - ~<in> giris / ~<out> cikis token (<model>, ~$<usd>
 Phase <N> <name> done - ~<in> in / ~<out> out tokens (<model>, ~$<usd>)
 ```
 
-USD comes from `cost-table.json` rates for the phase's model (same math as
-`render-agent-log-cost.sh`: floor to cents). Phases with zero recorded tokens
-print `(no LLM calls)` instead of fabricating numbers.
+USD comes from `phase-tracker.sh cost <N>` - the single pricing implementation
+(cost-table.json rates, cached tokens at the discounted rate, floored to
+cents; prints `-` when the model is unknown). Do not re-implement the math
+inline. Phases with zero recorded tokens print `(no LLM calls)` instead of
+fabricating numbers.
+
+**Completion tile suffix (Claude Code).** The native widget cannot show
+per-phase tokens, but subject edits after creation are safe (tile order is
+fixed at TaskCreate time). So on phase completion, in addition to the
+narration line, append the spend to the tile subject:
+
+```text
+TaskUpdate({taskId: <phase_task>, subject: "Phase 3: Dev · ~35k tok · ~$0.26"})
+```
+
+Skip the suffix when the phase recorded zero tokens (subject stays clean).
 
 **Honesty note:** on Claude Code the orchestrator does not receive its own
 usage metering, so per-phase counts are content-size estimates (chars/4 for
@@ -259,11 +291,22 @@ When `/multi-agent:resume <task_id>` is called:
 
 The `tasklist_id` meta from the previous session is replaced with the new IDs during resume.
 
+## Continuation runs (finish / manual-test)
+
+A pre-existing `tracker-state.json` for the task is never re-initialized. Rules for any command that continues an earlier run (`/multi-agent:finish`, `/multi-agent:manual-test`, resume):
+
+1. `init` runs ONLY when no state file exists for the task. Otherwise the existing file is kept - phase history (elapsed, tokens, model, meta) survives.
+2. The continuing command re-declares its phase set with `add` - `add` is idempotent, so existing phases keep their name, status, and token history; only genuinely new phases are appended. The card renders phases sorted by numeric id, so mixed sets stay in order.
+3. If Phase 5 was left `in_progress` with `Now: awaiting local test (user)`, the continuing command marks it `update 5 completed` + `meta 5 Result "local test done (user)"` before its own work starts (finish may re-open it with `update 5 in_progress` when its build+test gate runs; elapsed keeps the original `started_at`, which is acceptable).
+4. On Claude Code, rebuild the FULL TaskList from the state file (completed tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta - exactly the Resume behaviour above.
+5. Print ONE line in `outputLanguage` summarizing the inherited history, e.g. `Continuing PROJ-12345: phases 0-3 finished earlier (12m, 38.4k tok, ~$0.74)` (USD via `cost total`), then `render`.
+
 ## Anti-patterns
 
 ❌ **TaskList only** → `:resume` will not work; no run history is preserved.
 ❌ **`phase-tracker.sh` only** in Claude Code → the user sees no widget, only bash stdout snapshots  -  the #1 source of "I see no phases" complaints.
 ❌ **Wiring `phase-tracker.sh render` to `statusLine` config** → it drops below the screen as a placeholder; the user complained, removed in v7.9.0.
+❌ **One monolithic subagent call for a whole multi-task phase** → the tile freezes for the entire phase (no `activeForm`, no `tokens`, no `now`)  -  the user sees a dead widget for 20+ minutes. Chunk per task; see "Delegated phases" above.
 
 ## Verification
 

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

@@ -31,6 +31,10 @@ Resume a paused or failed task from the last successful phase.
      - Phase 3 code → already in the worktree
    - Recent `git log --oneline -10` in the worktree grounds what was actually committed vs. claimed.
 
-4. **Continue the pipeline**  -  start from the next phase (same pipeline as the main multi-agent command).
+4. **Rebuild the phase tiles**  -  load `tracker-state.json` for the task (never re-init it; `refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
+   - Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
+   - Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
 
-5. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`
+5. **Continue the pipeline**  -  start from the next phase (same pipeline as the main multi-agent command).
+
+6. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`

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

@@ -58,7 +58,7 @@ Run every step automatically:
 Step 0: FIGMA_SYNC  SKIP (deprecated  -  feedback_figma_source_deprecated)
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 35 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 37 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -277,14 +277,14 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**35 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**37 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 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
 ```
 
 **NOT synced**: `refs/*`  -  lazy-load references, Claude Code specific

package/pipeline/commands/multi-agent.md

@@ -77,6 +77,8 @@ Lib scripts (`~/.claude/lib/`):
 | `analysis ["<feature>"]` | Standalone feature-spec analizi: Figma / Swagger / Confluence / Jira / repo girdileri sabit 7-bölümlük şablona dökülür, humanizer'dan geçer, Local/Confluence/Jira hedef(ler)ine post edilir. Worktree veya commit yok. Dev'e zincirleme yok. |
 | `build-optimize` | iOS-only Xcode build performance wrapper. Vendored `xcode-build-orchestrator`'a dispatch eder; benchmark + compilation / project / SPM analyzer'lar + recommend-first plan `.build-benchmark/optimization-plan.md`. Non-iOS stack'lerde fail-fast. |
 | `channels [PR-url\|#N\|Jira-url\|Jira-id] [--channels pr,jira,confluence,wiki] [--content normal,test,auto-diff,note] [--message "..."]` | Post task report to multi-select channels (PR description, Jira comment, Confluence page, Wiki pages) with multi-select content sources. Humanizer pass per-channel. Bitbucket PR updates use reviewer-preserving PUT. Phase 7 delegates to this command; also invocable post-hoc for fixes made outside the pipeline. No worktree. |
+| `generate-task ["desc"] [figma-url]` | Create a standards-compliant Jira **Task**: mines the project's recent Tasks for conventions (summary format, template, labels, priority), detects the active sprint, asks about unknown fields, then full draft preview + explicit approval before create. No worktree, no commits. |
+| `generate-bug ["desc"] [figma-url]` | Create a standards-compliant Jira **Bug**: same convention mining + active-sprint detection; free-text logs/devices map to Steps to Reproduce / Environment; full draft preview + explicit approval before create. No worktree, no commits. |
 | `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test.md` delegate. |
 | `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
 | `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
@@ -116,6 +118,8 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | `local-autopilot` | `$HOME/.claude/commands/multi-agent/local-autopilot.md` |
 | `dev-local` | `$HOME/.claude/commands/multi-agent/dev-local.md` |
 | `dev-local-autopilot` | `$HOME/.claude/commands/multi-agent/dev-local-autopilot.md` |
+| `generate-task` | `$HOME/.claude/commands/multi-agent/generate-task.md` (loads `refs/generate-issue.md`) |
+| `generate-bug` | `$HOME/.claude/commands/multi-agent/generate-bug.md` (loads `refs/generate-issue.md`) |
 | `stack` | `$HOME/.claude/commands/multi-agent/stack.md` |
 | `language` | Handled inline  -  set/show prompt language in preferences |
 | SwiftUI component task (iOS) | `$HOME/.claude/commands/multi-agent/refs/swiftui-guide.md` |

package/pipeline/lib/figma-mcp-refresh.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# figma-mcp-refresh.sh  -  silent Figma MCP (figu_) token renewal via OAuth refresh grant.
+#
+# Used by the Phase 0 token pre-flight (refs/phases/phase-0-init.md Step 0.7) and the
+# expired-token decision (refs/keychain.md). Never prints token values  -  status lines only.
+#
+# Flow:
+#   1. Resolve the access-token Keychain name from prefs.global.keychainMapping.figma_mcp.
+#   2. Read the refresh token from "<name>_Refresh" (written by the user's generation script).
+#   3. Read client credentials from .figma-oauth.json next to prefs.global.tokenScripts.figma_mcp.
+#   4. POST grant_type=refresh_token to the Figma token endpoint.
+#   5. On success save the new access token (and rotated refresh token) back to the Keychain.
+#
+# Exit codes:
+#   0  renewed (access token replaced in Keychain)
+#   1  refresh grant rejected by Figma (refresh token dead  -  run the generation script)
+#   2  prerequisites missing (no mapping / no refresh entry / no oauth config)
+
+set -euo pipefail
+
+PREFS_FILE="${PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
+TOKEN_ENDPOINT="https://api.figma.com/v1/oauth/token"
+ACCOUNT="${USER:-$(whoami)}"
+
+say() { printf '%s\n' "$*"; }
+
+[ -f "$PREFS_FILE" ] || { say "figma-mcp-refresh: prefs file missing ($PREFS_FILE)"; exit 2; }
+
+KEY_NAME=$(jq -r '.global.keychainMapping.figma_mcp // empty' "$PREFS_FILE")
+[ -n "$KEY_NAME" ] || { say "figma-mcp-refresh: keychainMapping.figma_mcp not set"; exit 2; }
+
+REFRESH_KEY="${KEY_NAME}_Refresh"
+REFRESH_TOKEN=$(security find-generic-password -s "$REFRESH_KEY" -w 2>/dev/null || true)
+[ -n "$REFRESH_TOKEN" ] || { say "figma-mcp-refresh: no refresh token at '$REFRESH_KEY'"; exit 2; }
+
+SCRIPT_PATH=$(jq -r '.global.tokenScripts.figma_mcp // empty' "$PREFS_FILE")
+OAUTH_CONFIG=""
+if [ -n "$SCRIPT_PATH" ]; then
+  OAUTH_CONFIG="$(dirname "$SCRIPT_PATH")/.figma-oauth.json"
+fi
+[ -n "$OAUTH_CONFIG" ] && [ -f "$OAUTH_CONFIG" ] || { say "figma-mcp-refresh: .figma-oauth.json not found (tokenScripts.figma_mcp unset or sibling config missing)"; exit 2; }
+
+CLIENT_ID=$(jq -r '.client_id // empty' "$OAUTH_CONFIG")
+CLIENT_SECRET=$(jq -r '.client_secret // empty' "$OAUTH_CONFIG")
+[ -n "$CLIENT_ID" ] || { say "figma-mcp-refresh: client_id missing in .figma-oauth.json"; exit 2; }
+
+CURL_ARGS=(
+  --data-urlencode "grant_type=refresh_token"
+  --data-urlencode "refresh_token=${REFRESH_TOKEN}"
+  --data-urlencode "client_id=${CLIENT_ID}"
+)
+[ -n "$CLIENT_SECRET" ] && CURL_ARGS+=( --data-urlencode "client_secret=${CLIENT_SECRET}" )
+
+RESPONSE=$(curl -s --max-time 20 -X POST "$TOKEN_ENDPOINT" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  "${CURL_ARGS[@]}")
+
+NEW_ACCESS=$(printf '%s' "$RESPONSE" | jq -r '.access_token // empty' 2>/dev/null || true)
+NEW_REFRESH=$(printf '%s' "$RESPONSE" | jq -r '.refresh_token // empty' 2>/dev/null || true)
+EXPIRES_IN=$(printf '%s' "$RESPONSE" | jq -r '.expires_in // "?"' 2>/dev/null || true)
+
+if [ -z "$NEW_ACCESS" ]; then
+  ERR=$(printf '%s' "$RESPONSE" | jq -r '.error // .message // "unknown"' 2>/dev/null || echo "unknown")
+  say "figma-mcp-refresh: refresh grant rejected ($ERR)  -  regenerate via tokenScripts.figma_mcp"
+  exit 1
+fi
+
+# Save new access token first, then the rotated refresh token  -  order matters so a
+# mid-write failure never leaves us with a lost refresh token AND a stale access token.
+security delete-generic-password -s "$KEY_NAME" -a "$ACCOUNT" >/dev/null 2>&1 || true
+security add-generic-password -s "$KEY_NAME" -a "$ACCOUNT" -w "$NEW_ACCESS" -T "" -U
+
+if [ -n "$NEW_REFRESH" ]; then
+  security delete-generic-password -s "$REFRESH_KEY" -a "$ACCOUNT" >/dev/null 2>&1 || true
+  security add-generic-password -s "$REFRESH_KEY" -a "$ACCOUNT" -w "$NEW_REFRESH" -T "" -U
+fi
+
+say "figma-mcp-refresh: renewed '$KEY_NAME' (expires_in=${EXPIRES_IN}s, refresh $( [ -n "$NEW_REFRESH" ] && echo rotated || echo unchanged ))"
+exit 0

package/pipeline/preferences-template.json

@@ -14,6 +14,7 @@
       "firebase": null,
       "jenkins": null
     },
+    "tokenScripts": {},
     "platformIdentityRouting": {},
     "recentProjects": [],
     "recentBranches": {},
@@ -153,4 +154,4 @@
       "overrides": {}
     }
   }
-}
+}