@mmerterden/multi-agent-pipeline 10.9.0 → 11.0.0

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

@@ -0,0 +1,267 @@
+# Generate Issue  -  Shared Flow (generate)
+
+> **TLDR**  -  Shared 12-step flow for `/multi-agent:generate`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, 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.md`. This ref is never invoked directly.
+
+## Hard rules (must not regress)
+
+- **Approval gate is absolute.** Step [9/12] (full preview + explicit approval) runs on every invocation. There is no autopilot variant of this command 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 [8/12]) or is omitted entirely  -  never fabricated repro steps, environments, acceptance criteria, or test pass/fail results.
+- **Standard template is the baseline.** The description structure comes from the type's standard template (see [7/12]), not from a mined heading set. Mining informs summary prefix, labels, components, priority norm, sprint placement, and test-scenario style  -  never replaces the standard section skeleton.
+- **Auto-sizing.** A conditional section renders only when its trigger is present. No empty placeholder headings  -  if there is nothing to put in a conditional section, it does not appear.
+- **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-9 perform only GET requests. The first write of any kind is the `POST /rest/api/2/issue` in step [10/12].
+
+## Standard templates
+
+Each type has a standard section skeleton. `A` = always present. `C` = conditional (renders only when its trigger fires).
+
+| Type | Section | Presence | Trigger (for `C`) |
+|---|---|---|---|
+| **Task** | Detailed Description | A | |
+| | Scope | A | |
+| | Acceptance Criteria | A | |
+| | Test Scenarios | A | populated from mined test-scenario style; skeleton derived from AC when the project has no prior style |
+| | API Contract / Swagger | C | Swagger URL, OpenAPI/contract snippet, or explicit endpoint mention in input |
+| | Design Reference | C | Figma URL given |
+| | Screenshots | C | user pasted image(s) or a Figma screenshot was fetched |
+| | Notes | C | real content only |
+| **Bug** | Detailed Description | A | |
+| | Steps to Reproduce | A | |
+| | Expected Result | A | |
+| | Actual Result | A | |
+| | Environment | A | |
+| | Screenshots / Logs | C | user pasted image(s) or log/stack-trace text |
+| | Regression / Test Scenario | C | derivable from the repro; else omitted |
+| | API Contract | C | API-related bug + Swagger/contract/endpoint given |
+| | Design Reference | C | Figma URL given |
+| | Notes | C | real content only |
+| **Story** | User Story (`As a ... I want ... so that ...`) | A | |
+| | Detailed Description | A | |
+| | Scope | A | |
+| | Acceptance Criteria | A | |
+| | Test Scenarios | A | same as Task |
+| | API Contract / Swagger | C | Swagger URL / contract / endpoint mention |
+| | Design Reference | C | Figma URL given |
+| | Screenshots | C | user pasted image(s) or Figma screenshot fetched |
+| | Dependencies / Notes | C | real content only |
+
+Section headings render in `outputLanguage` (e.g. tr: "Detaylı Açıklama", "Kapsam", "Kabul Kriterleri", "Test Senaryoları", "Adımlar", "Beklenen Sonuç", "Gerçekleşen Sonuç", "Ortam", "Ekran Görüntüleri", "API Contract", "Design Reference", "Notlar").
+
+## Flow
+
+### [1/12] 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/12] 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/12] Pick issue type
+
+AskUserQuestion (single-select, `question` in `outputLanguage`, e.g. tr: "Ne oluşturmak istiyorsun?"): `Task` / `Bug` / `Story`. Never inferred silently.
+- Output: `ISSUE_TYPE`. Selects the standard template from the table above.
+- The chosen type drives the mining JQL in [5/12], the required-field discovery in [5/12], and the section skeleton in [7/12].
+
+### [4/12] 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).
+- Any OpenAPI/Swagger URL (path or query contains `swagger`, `openapi`, `/v2/api-docs`, `/v3/api-docs`, or a `.json`/`.yaml` spec) → `SWAGGER_URL`.
+- Pasted images (chat attachments) → `USER_SCREENSHOTS[]`. Pasted log/stack-trace text → kept with `FREE_TEXT` and later mapped to the Screenshots / Logs section (Bug) or Notes.
+- Everything else → `FREE_TEXT`.
+- All of `FREE_TEXT`/`FIGMA_URL`/`SWAGGER_URL`/`USER_SCREENSHOTS` empty → AskUserQuestion (free-text, in `outputLanguage`): "Describe the {type} you want to open."
+- `FIGMA_URL`, `SWAGGER_URL`, and screenshots are always optional. Never ask for them; only use them when given.
+
+### [5/12] Convention mining + field discovery + sprint detection (read-only)
+
+Three GET groups. Run them before drafting anything.
+
+**5a. 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,issuelinks&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 8 when ambiguous.
+- **Top labels / components**: top 5 each by frequency → option lists for step 8.
+- **Priority norm**: modal priority for this issuetype → pre-filled default, editable in preview. (Bug priorities often skew higher  -  respect the project's own norm.)
+- **Epic usage rate**: share of sampled issues carrying an epic link → decides whether step 8 asks for an epic.
+- **Test-scenario style** (Task / Story, and Bug regression): detect how the project expresses test scenarios in the sampled descriptions and links, in priority order:
+  1. Linked test issues  -  `issuelinks` pointing at a `Test`-family issuetype (Xray / Zephyr). If present, the standard Test Scenarios section references those linked tests rather than inlining steps.
+  2. A dedicated description heading (`Test Scenarios`, `Test Cases`, `QA`, `Senaryolar`, checklist blocks). If a style is shared by >= 40% of samples, reuse that exact format (heading name + bullet/checklist/table shape).
+  3. No prior style → inline a Test Scenarios skeleton derived from the Acceptance Criteria (one scenario per criterion, Given/When/Then or the project's dominant shape). Skeleton only  -  the user edits it in preview; pass/fail data is never fabricated.
+
+**5b. 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 8 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 template defaults; required fields surface reactively via the 400 path in step 10.
+
+**5c. 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 8 placement choice. None → backlog only; if a `state=future` sprint exists, mention it in the preview as information.
+
+### [6/12] External context (only for the sources actually provided)
+
+Each source is failure-isolated and never blocks issue creation.
+
+**6a. Figma** (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 11 attachment opt-in.
+- Any tier failure degrades gracefully; link-only is always acceptable.
+
+**6b. Swagger / API contract** (only when `SWAGGER_URL` is set or a contract snippet was pasted):
+- `SWAGGER_URL` set → fetch the spec, then extract **only the referenced endpoints**: if `FREE_TEXT` names specific paths / operationIds / tags, extract those; otherwise summarize the single tag or path group the user pointed at. Never crawl or dump the whole spec.
+```bash
+curl -s "$SWAGGER_URL" -o /tmp/generate-issue-$$-swagger.json  # add auth header only if the user supplied one
+```
+  Parse with `python3`/`jq` to pull, per referenced endpoint: HTTP method + path, a one-line summary, and the key request/response fields (names + types, not the full schema).
+- Only a pasted contract snippet → summarize that snippet (endpoints + key fields).
+- Output: an `API Contract` section body: `{METHOD} {path}` + summary + key request/response fields, plus `[Swagger|{SWAGGER_URL}]` when a URL was given.
+- Fetch failure / unreachable / no matching endpoint → degrade to link-only (or omit the section if nothing usable) and note it in the preview. Never block issue creation.
+
+**6c. Screenshots**: `USER_SCREENSHOTS[]` from step 4 are staged for the step 11 attachment opt-in; each attached image is referenced inline in the relevant section with Jira wiki `!filename|thumbnail!` markup.
+
+### [7/12] Compose draft
+
+Write summary + description in `outputLanguage` from the type's **standard template** (baseline, not mined headings):
+- **Summary**: `{minedPrefix} {concise title}`, truncated to 255 chars.
+- **Description**: render the type's standard section skeleton in Jira wiki markup (`h3.` headings), applying auto-sizing:
+  - **Always-present** sections are filled from `FREE_TEXT` (+ mining for Test Scenarios style). If an always-present section has no user content and cannot be derived, it stays an explicit open question for step 8  -  it is not fabricated.
+  - **Conditional** sections render only when their trigger fired (see the Standard templates table): Design Reference when `FIGMA_URL` set (`[Figma|{FIGMA_URL}]` + frame name + node id); API Contract when 6b produced a body; Screenshots when images were staged; Notes/Dependencies only with real content. Otherwise the heading is omitted entirely.
+  - Bug: logs / stack traces / device+OS mentions from `FREE_TEXT` map into Environment and Screenshots / Logs; anything underivable becomes a step-8 question.
+- 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.
+
+### [8/12] 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 5a 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 5b not yet resolved (allowedValues as options).
+- **Always-present sections still empty**: Bug Steps to Reproduce / Environment, or a Task/Story with no derivable Scope / Acceptance Criteria → ask here.
+
+Rule: never ask about anything already answerable from mining or the input. Regardless of how complete the draft looks, step 9 always runs.
+
+### [9/12] 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 + user screenshots upload  -  default off, opt-in).
+
+Then AskUserQuestion (`question` in `outputLanguage`, e.g. tr: "Bu sekilde olusturuyorum, onayliyor musun?"):
+
+| Option | Behavior |
+|---|---|
+| `Approve` | Proceed to step 10 |
+| `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.
+
+### [10/12] 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 8 for exactly those fields, then re-run step 9 (full preview again).
+
+### [11/12] Post-create steps
+
+Each step is failure-isolated: on error, warn + continue  -  the issue already exists.
+
+1. **Sprint** (when chosen in step 8/9):
+```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. **Swagger remote link** (when `SWAGGER_URL` set):
+```bash
+curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"object":{"url":"'"$SWAGGER_URL"'","title":"API contract"}}' \
+  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/remotelink"
+```
+4. **Screenshot / image attachments** (only when opted in during preview  -  Figma render and/or user-pasted images):
+```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"
+```
+
+### [12/12] Report
+
+```
+Created {NEW_KEY}: https://{ACCOUNT_JIRA_HOST}/browse/{NEW_KEY}
+```
+Plus one line per post-create step that ran (sprint placement, remote links, attachments) 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 standard-template defaults; required fields asked reactively on 400 |
+| Zero sampled issues (new project) | Skip mining, use standard template + AC-derived test-scenario skeleton, 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 |
+| Swagger fetch fails / unreachable | Degrade to link-only, or omit the API Contract section if nothing usable; note in preview. Never block issue creation |
+| Create 400 (field errors) | Show per-field errors, loop back to step 8 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 + 36 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)
@@ -169,7 +169,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 ## Stack-Plugin Sync (Step 3c)
 
-Stack skills are distributed as versioned plugins in the `{owner}/multi-agent-plugins` marketplace. The pipeline's `pipeline/skills/shared/external/` is the **single authoring source**; the marketplace is a derived, versioned publish artifact. This step rebuilds it and publishes only when something changed.
+Stack skills are distributed as versioned plugins in the `mmerterden/multi-agent-plugins` marketplace. The pipeline's `pipeline/skills/shared/external/` is the **single authoring source**; the marketplace is a derived, versioned publish artifact. This step rebuilds it and publishes only when something changed.
 
 **Source of truth:** author/vendor knowledge skills in `pipeline/skills/shared/external/` (the pipeline's own phases also consume them). The plugins' authored lifecycle skills (`index` / `reference` / `workflow` / `tools`) live in the plugins repo and are never touched by sync.
 
@@ -177,7 +177,7 @@ Stack skills are distributed as versioned plugins in the `{owner}/multi-agent-pl
 
 ```bash
 PLUGINS_REPO="$HOME/multi-agent-plugins"
-[ ! -d "$PLUGINS_REPO/.git" ] && gh repo clone {owner}/multi-agent-plugins "$PLUGINS_REPO"
+[ ! -d "$PLUGINS_REPO/.git" ] && gh repo clone mmerterden/multi-agent-plugins "$PLUGINS_REPO"
 cd "$PLUGINS_REPO" && git pull origin main
 
 # 1. Preview what would change (routing + version bumps), no writes:
@@ -197,10 +197,10 @@ node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
 ```bash
 cd "$PLUGINS_REPO"
 if ! git diff --quiet; then
-  git config user.name "$(git config user.name)"; git config user.email "$(git config user.email)"
+  git config user.name "Mert Erden"; git config user.email "mmerterden@gmail.com"
   git add -A
   git commit -m "chore: rebuild stack plugins from pipeline shared/external"
-  gh auth switch --user {owner} 2>/dev/null || true
+  gh auth switch --user mmerterden 2>/dev/null || true
   git push origin main
 fi
 ```
@@ -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):
+**36 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, 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