@mmerterden/multi-agent-pipeline 14.2.1 → 15.0.0

package/pipeline/commands/multi-agent/analysis-resolve/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a Section 23 changelog bump. Companion to /multi-agent:analysis - same Locked decisions apply (citation discipline, humanizer punctuation, no MCP, no auto-commit). Optional sibling propagation for per-platform file sets. Use when an analysis document's open questions and risks need answering row by row before development starts."
+description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time: up to 3 source-labeled answer candidates per row (evidence / repo / AI reasoned), chosen answer merged into the target section, doc updated in place with a changelog bump. Same locked decisions as /multi-agent:analysis. Use when an analysis document's open questions need answering before development starts."
 description-tr: "Analiz v3 dokümanının Bölüm 20 Riskler ve Açık Sorular satırlarını tek tek çözer. Satır başına en fazla 3 kaynak-etiketli cevap adayı önerir (kanıttan / repodan / AI çıkarımı), seçilen cevabı ilgili gövde bölümüne işler ve dokümanı Bölüm 23 changelog artışıyla yerinde günceller. /multi-agent:analysis'in eşlikçisi - aynı Kilitli kararlar geçerli (alıntı disiplini, humanizer noktalama, MCP yok, otomatik commit yok). Platform bazlı dosya setleri için isteğe bağlı kardeş yayılımı."
 argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
 ---
@@ -121,7 +121,7 @@ For each open row in source order:
 | `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, omission re-flow |
 | `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | `convention-fallback` default values per platform |
 | `~/.claude/lib/extract-conventions.sh` | fresh single-field extraction for convention-fallback candidates |
-| `$HOME/.claude/skills/humanizer/SKILL.md` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |
+| `ai-common-toolkit:humanizer` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |
 
 ## Notes
 

package/pipeline/commands/multi-agent/autopilot/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: '"task"  -  issue URL, Jira ID, free-text, or #id (for resume)'
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Run the task end-to-end with no confirmations.
 
@@ -49,6 +49,10 @@ Run the task end-to-end with no confirmations.
 2. **Set the autopilot flag**  -  write `"autopilot": true` to `agent-state.json`
 3. **Launch the multi-agent pipeline**  -  every confirmation is skipped
 4. **On error**  -  after 3 failed retries, pause and ask the user
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -72,7 +76,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)

package/pipeline/commands/multi-agent/build-optimize/SKILL.md

@@ -40,7 +40,7 @@ Before dispatch, fail fast on non-iOS repos. Detect iOS context via the standard
 
 3. **Dispatch** to `xcode-build-orchestrator` via the Skill tool:
    ```
-   Skill(skill="xcode-build-orchestrator", args="")
+   Skill(skill="ai-ios-toolkit:xcode-build-orchestrator", args="")
    ```
    The orchestrator's Phase 1 (Analyze) runs `xcode-build-benchmark`, the three specialist analyzers, and writes `.build-benchmark/optimization-plan.md`. No project files are modified during Phase 1.
 
@@ -48,7 +48,7 @@ Before dispatch, fail fast on non-iOS repos. Detect iOS context via the standard
 
 5. **Phase 2 (apply + verify)** is initiated by the user. The wrapper does not auto-execute Phase 2 because the upstream contract requires explicit approval via the checkboxes in the plan file. When the user signals "implement the approved items", the wrapper dispatches to `xcode-build-fixer`:
    ```
-   Skill(skill="xcode-build-fixer", args="")
+   Skill(skill="ai-ios-toolkit:xcode-build-fixer", args="")
    ```
    The fixer applies only the approved changes and re-benchmarks for wall-clock delta verification.
 
@@ -62,13 +62,13 @@ Before dispatch, fail fast on non-iOS repos. Detect iOS context via the standard
 
 | Path | Reason |
 |------|--------|
-| `$HOME/.claude/skills/xcode-build-orchestrator/SKILL.md` | The orchestrator this wrapper dispatches to |
-| `$HOME/.claude/skills/xcode-build-benchmark/SKILL.md` | Baseline timing |
-| `$HOME/.claude/skills/xcode-compilation-analyzer/SKILL.md` | Swift compile hotspots |
-| `$HOME/.claude/skills/xcode-project-analyzer/SKILL.md` | Build settings / script phases / parallelism |
-| `$HOME/.claude/skills/spm-build-analysis/SKILL.md` | SPM graph + plugins |
-| `$HOME/.claude/skills/xcode-build-fixer/SKILL.md` | Apply approved fixes + re-benchmark |
-| `$HOME/.claude/skills/NOTICE-xcode-build-skills.md` | MIT attribution + upstream pin |
+| `ai-ios-toolkit:xcode-build-orchestrator` | The orchestrator this wrapper dispatches to |
+| `ai-ios-toolkit:xcode-build-benchmark` | Baseline timing |
+| `ai-ios-toolkit:xcode-compilation-analyzer` | Swift compile hotspots |
+| `ai-ios-toolkit:xcode-project-analyzer` | Build settings / script phases / parallelism |
+| `ai-ios-toolkit:spm-build-analysis` | SPM graph + plugins |
+| `ai-ios-toolkit:xcode-build-fixer` | Apply approved fixes + re-benchmark |
+| ai-ios-toolkit plugin NOTICE (xcode build skills) | MIT attribution + upstream pin |
 
 ## Notes
 

package/pipeline/commands/multi-agent/channels/SKILL.md

@@ -138,7 +138,7 @@ Then 3b renders:
 - "Teknik analiz" unselectable if no Phase 2 planning log AND no PR diff available. Reason: `"(no technical source  -  need Phase 2 plan or PR diff)"`.
 - "Auto-diff" unselectable if no PR found. Reason: `"(no PR linked to this target)"`.
 - "Manuel not" always available.
-- "Cost özeti" unselectable if `phase-tracker.sh status <id>` returns no token tallies AND no `otel-spans.jsonl` exists for the task. Reason: `"(no tracker data  -  set MULTI_AGENT_OTEL_SPANS=1 or enable token tracking)"`.
+- "Cost özeti" unselectable if `phase-tracker.sh cost total` prints `-` (no priced token tallies; there is no `status` action) AND no `otel-spans.jsonl` exists for the task. Reason: `"(no tracker data  -  set MULTI_AGENT_OTEL_SPANS=1 or enable token tracking)"`.
 - "Yapılan iş özeti" unselectable if no `agent-state.json` exists for the task (post-hoc call with `--branch` + `--base-branch` flags restores partial availability). Reason: `"(no agent-state.json for {taskId})"`. **Auto-ticked** when Step 3a preview was shown  -  user can still uncheck before confirming the menu.
 
 **Defaults (first run):** PR + Jira ticked, Confluence + Wiki unticked. Content: auto-diff if pipeline log missing; otherwise normal-analiz + test-senaryoları.
@@ -246,7 +246,7 @@ Emitted only when `reportContent.workSummary === true` and at least one of (`age
 2. **Scope delivered**  -  Phase 2 `planTodos[]` / `tasks[]` rendered as `✅` (status=done) or `⏳` (anything else) rows. Task id + title shown; `(deferred  -  rationale)` appended if the task's `status` is `"deferred"`.
 3. **Changed files**  -  `git -C $WORKTREE diff --numstat $baseBranch...HEAD`. Shows `` `path` (+add / -del) `` per row, capped at 20 with a `_... +N more files not shown_` footer when exceeded. Total adds/dels + file count in section header.
 4. **Review outcome**  -  from `reviewConsensus` (pre-v6.1) or `phases["4"].triage`: `{accepted} accepted · {deferred} deferred · {rejected} rejected · approved={bool}`. Hidden entirely when all three buckets are empty (normal for `--dev` / `dev-autopilot` runs that skip Phase 4).
-5. **Phase tick strip**  -  single line from `phase-tracker.json`: `0 Init ✅ · 1 Analysis ✅ · 2 Planning ✅ · 3 Dev ✅ · 4 Review ✅ · 5 Test ⏭ · 6 Commit ✅ · 7 Report ▶`. Marks: `✅` completed · `▶` in_progress · `❌` failed · `⏭` skipped · `·` pending.
+5. **Phase tick strip**  -  single line from the tracker state (`render-work-summary.sh` resolves worktree/artifacts copies, then `$HOME/.claude/logs/multi-agent/{taskId}/tracker-state.json`): `0 Init ✅ · 1 Analysis ✅ · 2 Planning ✅ · 3 Dev ✅ · 4 Review ✅ · 5 Test ⏭ · 6 Commit ✅ · 7 Report ▶`. Marks: `✅` completed · `▶` in_progress · `❌` failed · `⏭` skipped · `·` pending.
 
 **Output template:**
 
@@ -276,7 +276,7 @@ Emitted only when `reportContent.workSummary === true` and at least one of (`age
 
 Emitted only when `reportContent.costSummary === true` and tracker data is available. Source of truth is `phase-tracker.sh`:
 
-1. **Token tallies per phase**  -  read `.worktrees/{taskPath}/phase-tracker.json` (written by `phase-tracker.sh update` / `tokens` actions). If present, each phase row has `{tokens_in, tokens_out}`.
+1. **Token tallies per phase**  -  `render-cost-summary.sh <taskId>` resolves the tracker JSON itself: worktree candidates (`.worktrees/{taskPath}/phase-tracker.json`) first, then the standard location `$HOME/.claude/logs/multi-agent/{taskId}/tracker-state.json` that `phase-tracker.sh` actually writes. Each phase row carries `{tokens_in, tokens_out}`.
 2. **Fallback to OTel spans**  -  if tracker JSON has no token columns but `otel-spans.jsonl` exists (set `MULTI_AGENT_OTEL_SPANS=1` beforehand), aggregate `phase.tokens` spans by phase ID.
 3. **USD estimate**  -  uses a static price table in `$HOME/.claude/scripts/cost-table.json` (model → $/Mtok_in, $/Mtok_out). Missing model → show ` - ` for USD, never block.
 
@@ -310,7 +310,18 @@ Skipped in exactly two cases:
 | Autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`) | Explicit consent for side-effect creation  -  posts directly with prefs/flag selections, zero interaction |
 | `--dry-run` | Already prints without posting; a question would be redundant |
 
-**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval):
+**Preview render** (one block per selected channel, final body after humanizer  -  shown in readable Markdown, channel-specific markup conversion happens after approval).
+
+Conversion is per-channel and two of the four channels have none. Do not reach for "the" conversion table  -  there is no single one:
+
+| Channel | Conversion after approval | Table |
+|---|---|---|
+| PR description | **none**  -  posted as Markdown, verbatim | GitHub / Bitbucket / GitLab all render Markdown; see `channels/pr.md` "Markup dialect" |
+| GitHub issue comment | **none**  -  posted as Markdown, verbatim |  -  |
+| Jira comment | markdown → Jira wiki markup | `channels/jira.md` "Wiki markup conversion" |
+| Confluence page | markdown → storage format | `channels/confluence.md` "Body conversion" |
+
+Applying the Jira table to the PR body is the recurring failure of this step: it is the only *text* markup table in the doc set, so it reads as the default. It is not. A PR body containing `h2.`, `{{code}}`, or `#`-numbered lists shipped raw wiki markup to a Markdown surface.
 
 ```
 ── PR description  ({repoName} #{prNumber}, replace) ─────────
@@ -390,7 +401,7 @@ Full contract: [`$HOME/.claude/multi-agent-refs/channels/confluence.md`]($HOME/.
 
 **Wiki → Jira comment auto-link** (triad contract, preserved from v5.6): when the Wiki adapter writes pages AND `state.jiraId` is set AND `prefs.global.wikiToJiraComment === true`, also post a humanizer-passed summary of the wiki pages (component name + variant count + wiki URL) as an additional Jira comment on the same issue. Independent of the main Jira channel's comment  -  both can coexist. Full contract in `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`.
 
-**If preconditions met (Case A):** scope multi-select prompt (Main page / iOS sub-page / Screenshots / Index updates / Other); adapter dispatched to the plugin skill `ai-ios-engineering-toolkit:figma-component-wiki` (or `ai-android-engineering-toolkit:figma-component-wiki`).
+**If preconditions met (Case A):** scope multi-select prompt (Main page / iOS sub-page / Screenshots / Index updates / Other); adapter dispatched to the plugin skill `ai-ios-toolkit:figma-component-wiki` (or `ai-android-toolkit:figma-component-wiki`).
 
 Full contract: [`$HOME/.claude/multi-agent-refs/channels/wiki.md`]($HOME/.claude/multi-agent-refs/channels/wiki.md)  -  all four `figma-config.wiki.mode` adapters (submodule / in-repo / github-wiki / separate-repo), full Case A scope menu, screenshot quadrant gate.
 

package/pipeline/commands/multi-agent/complaint-analysis/SKILL.md

@@ -0,0 +1,186 @@
+---
+description: "Customer-complaint triage. Ingests complaints (paste, csv/xlsx/txt/json file, Jira issue, Confluence URL), fetches Graylog evidence per trx/conversation id, correlates read-only against the selected client + BFF repos; per complaint: client/bff root cause + fix plan + dev prompt, or core routing recommendation, or insufficient-evidence. Report only, no dev chaining. Use when customer-reported errors need layer triage."
+description-tr: "Müşteri şikayeti / müşteri kaynaklı hata triyajı. Şikayetleri alır (serbest metin, csv/xlsx/txt/json dosya, Jira issue, Confluence URL), trxId/conversationId ile Graylog kanıtı çeker, seçilen client + BFF repolarıyla salt-okunur eşleştirir ve her şikayeti sınıflandırır: client / bff (bizim sorumluluğumuz, kök neden analizi) veya core (core ekibine yönlendirme önerisi) veya insufficient-evidence. Rapor üretip durur - branch, worktree, commit, PR veya dev zinciri yok."
+argument-hint: "[\"<run-name>\"] [--file <path>] [<jira-id | jira-url | confluence-url> ...]"
+---
+
+# multi-agent complaint-analysis - Customer Complaint Triage
+
+**Input**: $ARGUMENTS (optional run name, optional `--file <path>`, optional Jira ids / Jira URLs / Confluence URLs; remaining free text is treated as pasted complaints)
+
+Triage of customer-reported errors across the layers the team owns (client apps + BFFs). Per complaint: Graylog log evidence by trx/conversation id, read-only repo correlation, and a verdict. **Core failures get a routing recommendation, never a fix analysis.**
+
+**Side-effect contract**: may write a local markdown report, post a Confluence page, or add a Jira comment/description - but **never** creates branches, worktrees, commits, or PRs. Stops at the report.
+
+> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English. `AskUserQuestion.label` and `header` stay English. `question` and `description` follow `outputLanguage`. The report body follows `outputLanguage`; Graylog excerpts, verdict tokens, and external payload metadata stay English.
+
+## Locked decisions (do not re-ask)
+
+1. **Graylog is primary evidence (deliberate departure).** `features/external-context-injection.md` declares Graylog advisory-only for the dev pipeline; in THIS command Graylog IS the evidence backbone. A per-complaint fetch failure still never halts the run, but that complaint's verdict is capped at `insufficient-evidence` - never fabricated.
+2. **Ids are never guessed.** A complaint with no trxId and no convId enters the Phase 0 Step 5 confirmation loop: the user supplies the id(s) or explicitly marks the complaint `skip-graylog`. Empty submit is not consent (`feedback_no-inferred-defaults-from-empty-answer`); re-ask.
+3. **Read-only ops command.** No worktree, branch, commit, PR, or dev chaining. Report + Stop.
+4. **Redaction before any output.** Complaint text is redacted at intake (`parse-complaints.sh`, default on). Jira / Confluence-sourced complaint text passes through the same redaction (`--stdin` mode) after fetch. Raw PII never enters state, drafts, or any dispatch target.
+5. **Core is a residual classification, not a repo.** Verdict `core` produces a routing recommendation only - no fix analysis, no core-repo grepping, no core code speculation.
+6. **Layer mapping is user-confirmed.** Name-based layer inference (Step 3b) is a proposal; the confirmation table must be approved before Phase 1.
+7. **Output default = Local file.** The Phase 4.5 picker keeps `Local file` pre-selected; Confluence and Jira are never default-selected.
+8. **Humanizer punctuation policy is non-negotiable.** No em-dash, en-dash, ellipsis, curly quotes, or section sign in any emitted text. Turkish diacritics are preserved verbatim - never ASCII-fold the prose.
+9. **Language split.** Report body follows `outputLanguage`; verdict tokens (`client:ios`, `bff:mobile-bff`, `core`, `insufficient-evidence`), Graylog evidence excerpts, and Confluence/Jira payload metadata stay English.
+10. **Verdict citation discipline.** Every `client`/`bff` verdict cites at least one Graylog message (timestamp + source) AND one repo evidence row (`file:line`). Anything less is `insufficient-evidence`. Every `core` verdict cites the Graylog message that names the upstream service.
+11. **One complaint batch per run.** Mixed batches spanning unrelated products are user error: surface it and ask to split.
+12. **No auto-commit.** The local report is written to the working tree; the user commits it themselves if they want.
+13. **Client/bff verdicts carry a development handoff.** Every `client`/`bff` verdict renders a fix plan grounded in the EXISTING architecture (the `repoEvidence[]` files are the reference: name the concrete files/components to touch, reuse-first, no invented structures) plus a ready-to-run dev prompt (English, one fenced block, `/multi-agent:dev`-compatible). The handoff is part of the report - this command still never runs dev itself (Locked 3). Core and insufficient-evidence verdicts never get a fix plan (Locked 5).
+
+## Steps
+
+### Phase 0 - Intake
+
+Sequential `AskUserQuestion` chain, answers land under `state.complaintSpec.*` (schema: `$HOME/.claude/schemas/complaint-analysis-spec.schema.json`). Step narration per `$HOME/.claude/multi-agent-refs/picker-contract.md`: print `<localized: "Step <i>/<n>: <what this step decides>">` before each picker; auto-resolved steps still print their breadcrumb.
+
+#### Step 0 - Language resolution (BLOCKING)
+
+Read `prefs.global.outputLanguage` (`tr` or `en`, default `tr`) before the first picker. Every `<localized: "...">` marker in this file is rendered in that language, never emitted literally.
+
+#### Step 1 - Run name
+
+From `$ARGUMENTS` quoted string if present, else default `complaints-<YYYYMMDD>` (announce, do not ask). Result: `state.complaintSpec.runName`.
+
+#### Step 2 - Account picker
+
+Reuse `$HOME/.claude/multi-agent-refs/_account-picker.md`. Needed for Graylog-adjacent Jira/Confluence fetches and dispatch; skipped only when the run is fully local (no Jira/Confluence input, local output only) - then `account: null`.
+
+#### Step 3 - Repo multi-select
+
+Reuse `$HOME/.claude/multi-agent-refs/_repo-picker.md` (multi-select via `~/.claude/lib/repo-cache.sh`). Guidance line in the question: <localized: "Select the client and BFF repos your team owns (e.g. ios / android / web / mobile-bff / web-bff). Core services are NOT selected - core is a triage outcome, not a repo.">
+
+#### Step 3b - Layer tagging (single confirmation table)
+
+Infer a layer per selected repo from its name (`ios|iphone` -> ios, `android` -> android, `web(?!.*bff)` -> web, `mobile.?bff|bff.?mobile` -> mobile-bff, `web.?bff|bff.?web` -> web-bff, else other). Present ONE AskUserQuestion with the full `repo -> layer` table in the question body: options `Approve mapping` / `Override rows`. On override, one follow-up per rejected row with the 6 layer options. Result: `state.complaintSpec.repos[] = {name, layer, localPath?, provider?}` (Locked 6).
+
+#### Step 4 - Complaint input (multi-source)
+
+Classify every `$ARGUMENTS` remainder and any pasted input via `~/.claude/lib/context-link-extractor.sh`, then collect per source type. If nothing was supplied, ask: <localized: "Paste the complaints, or give a file path (csv / xlsx / txt / json), a Jira issue, or a Confluence URL. Mixed input is fine.">
+
+| Source | Ingestion |
+|---|---|
+| File path (`--file` or detected) | `~/.claude/lib/parse-complaints.sh --file <path>` (format auto-detected; exit 5 = xlsx degrade -> surface `degradeReason`, ask for a CSV export path, re-run) |
+| Pasted free text | `parse-complaints.sh --stdin` (splits blocks, pre-fills ids via the shared label set) |
+| Jira id / URL | Fetch issue summary + description + comments via Jira REST (account token); concatenate as text blocks, pipe through `parse-complaints.sh --stdin` (Locked 4) |
+| Confluence URL | `~/.claude/lib/fetch-confluence.sh <url>`; page body paragraphs/table rows become text blocks, piped through `parse-complaints.sh --stdin` |
+
+Merge all outputs into one list, re-numbering ids `C-01..C-NN`. Result: `state.complaintSpec.input` + `state.complaintSpec.complaints[]`.
+
+#### Step 5 - Id confirmation loop (Locked 2)
+
+Render the parsed table (id, redacted excerpt <= 80 chars, trxId, convId, platformHint) to the user. For every complaint missing BOTH ids, one AskUserQuestion: <localized: "Complaint <id> has no trx/conversation id. Supply one, or skip Graylog for it?"> with options `Skip Graylog for this complaint` (-> `skipGraylog: true`) and Other for the id (`trx:<value>` / `conv:<value>`). Empty submit re-asks. Set `phase: "fetching_graylog"`.
+
+### Phase 1 - Graylog evidence fan-out
+
+For each complaint with at least one id and `skipGraylog: false`:
+
+```bash
+~/.claude/lib/fetch-graylog.sh --trx <trxId> --conv <convId>   # pass whichever exist
+```
+
+Record per complaint: `graylog: {status: ok|degraded|skipped, totalResults, degradeReason}` plus the top messages (timestamp, source, level, message excerpt) kept in working context for Phase 2/3. Failure handling:
+
+- Exit 0 with `degraded: true` -> `status: degraded`, keep the reason, continue.
+- Exit 2 / 3 / 6 (credential / auth / host) -> per `$HOME/.claude/multi-agent-refs/keychain.md` non-critical rule: warn ONCE (`WARN: Graylog unavailable (<reason>); remaining complaints proceed without log evidence.`), mark this and all remaining fetches `status: degraded`, continue. Never halt (Locked 1).
+- `skipGraylog: true` -> `status: skipped`.
+
+Set `phase: "correlating_repos"`.
+
+### Phase 2 - Repo evidence correlation (read-only)
+
+From each complaint's Graylog messages extract candidate signals: endpoint paths, error codes, exception class names, distinctive message templates, and the `source` service name. Then grep the selected repos (skip dirs: `.build`, `DerivedData`, `Pods`, `node_modules`, `.next`, `build/`, `.gradle`, `vendor/`):
+
+```bash
+grep -rn --include='*.swift' --include='*.kt' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.java' -E "<signal>" "$REPO_PATH"
+```
+
+Bucket hits per complaint as `repoEvidence[] = {repo, layer, file, line, signal, matchKind: direct|partial}` (`direct` = exact endpoint/error-code/template match; `partial` = fuzzy/name-only). Grep only - no convention extraction, no Figma, no Swagger. Complaints with `status: degraded|skipped` still get a text-similarity pass (grep the complaint's distinctive nouns/error phrases), tagged `partial`. Set `phase: "triaging"`.
+
+### Phase 3 - Triage classification
+
+Per complaint, in order:
+
+| Condition | Verdict |
+|---|---|
+| Graylog error originates in an owned layer: signal matched `direct` in a selected repo, OR the failing `source` maps to an owned BFF | `client:<ios|android|web>` or `bff:<mobile-bff|web-bff>` + root-cause rationale + citations (Locked 10) |
+| Graylog shows the failure downstream of owned layers: `source` is an unowned core service, 5xx from an upstream nobody selected owns, no repo match | `core` + routing recommendation (below) |
+| No/degraded Graylog AND no direct repo signal | `insufficient-evidence` + open question row |
+
+**Routing recommendation** (core only, Locked 5): `{suspectedService: <Graylog source>, endpoint, errorCode, evidenceExcerpt (EN, redacted), suggestedQueue: prefs.projects[<project>].routing.coreTeamLabel ?? null, confidence}`.
+
+Verdict shape: `verdict: {category, layer, confidence: high|medium|low, rationale}`. Ambiguous client-vs-bff attribution lowers `confidence`, never invents evidence.
+
+**Development handoff (client/bff only, Locked 13)**: for each `client`/`bff` verdict, derive from the `repoEvidence[]` rows:
+
+- **Fix plan**: 2-5 numbered steps referencing the existing architecture by `file:line` - which service/view/handler to change, what to reuse (reuse-first: prefer extending the cited components over adding new ones), which tests to add. No speculative rewrites.
+- **Dev prompt**: one fenced English block the user can paste into `/multi-agent:dev` (or a Jira description): complaint summary, root cause, the cited files, the fix plan steps, and the acceptance check. Include the complaint id (`[C-NN]`) for traceability.
+
+Set `phase: "drafting"`.
+
+### Phase 4 - Draft, humanize, buffer
+
+1. Render the report per `$HOME/.claude/multi-agent-refs/complaint-analysis-template.md` (8 fixed sections; single-language body in `outputLanguage`; verdict tokens English per Locked 9) to `/tmp/complaint-analysis-<run-slug>-<UTC-iso8601>/report.md`. Store `outputs.draftDir`.
+2. **Humanizer pass (MANDATORY: actually invoke the `ai-common-toolkit:humanizer` skill; the punctuation grep alone does NOT satisfy this)** with `language: <tr|en>`, `tone: technical-explanatory`, `stripFancyPunctuation: true`. Diacritics preserved (Locked 8).
+3. Punctuation gate: `grep -P '[\x{2013}\x{2014}\x{2026}\x{201C}\x{201D}\x{2018}\x{2019}\x{00A7}]'` over the draft returns zero matches.
+4. Show the draft path + size to the user. Set `phase: "awaiting_output_decision"`.
+
+### Phase 4.5 - Output destination picker
+
+AskUserQuestion (multiSelect=true), `Local file` pre-selected (Locked 7):
+
+```
+header: "Output"
+question: <localized: "Where should the triage report be written?">
+options:
+  - label: "Local file"        (description: complaints/<run-name>.md in the primary repo's working tree)
+  - label: "Confluence page"
+  - label: "Jira"
+```
+
+Follow-ups: Confluence -> ask parent page (Other, LRU recents from `prefs.projects[<project>].confluenceUrls`); Jira -> pick from Step 4 Jira ids if any, else ask via Other. Result: `outputs.destinations[]`. Set `phase: "dispatching"`.
+
+### Phase 5 - Validate, dispatch, report. Stop.
+
+**Pre-dispatch gate (BLOCKING)**: `node $HOME/.claude/scripts/validate-complaint-doc.mjs <draft>` - front-matter, required sections, verdict tokens per triage row, routing entry per core verdict, punctuation, redaction-leak scan. Any ERROR blocks dispatch: fix the draft, re-validate.
+
+| Target | Action |
+|---|---|
+| Local | `cp` the draft to `complaints/<run-name>.md` in the primary repo's working tree. **No commit** (Locked 12). |
+| Confluence | Re-humanize with `formal-stakeholder` tone; post one page under the chosen parent via `$HOME/.claude/multi-agent-refs/channels/confluence.md` + `~/.claude/lib/md2confluence-v3.py`. |
+| Jira | Re-humanize with `informal-technical` tone; markdown -> wiki markup per `$HOME/.claude/multi-agent-refs/channels/jira.md`; post as a comment on the chosen issue (never close/transition the issue). |
+
+Then print the summary in `outputLanguage`: complaint count, verdict counts (`X client / Y bff / Z core / W insufficient-evidence`), degraded services, output paths/URLs. When any `core` verdict exists, add: <localized: "N complaint(s) route to the core team - see the routing section before forwarding.">
+
+**Stop. Do not chain into `/multi-agent:dev`. Do not open a worktree. Do not create a branch.** Set `phase: "done"`.
+
+### Resume contract
+
+`state.complaintSpec.phase`: `intake | fetching_graylog | correlating_repos | triaging | drafting | awaiting_output_decision | dispatching | reporting | done`.
+
+`/multi-agent:resume` at `awaiting_output_decision`: if `outputs.draftDir` still holds `report.md`, jump to Phase 4.5; if gone, re-render Phase 4 from state (evidence is retained). Earlier phases resume at their own boundary; Graylog results already in state are never re-fetched.
+
+## Reusable refs
+
+| Path | Reason |
+|---|---|
+| `~/.claude/lib/parse-complaints.sh` | Phase 0 Step 4 normalization + redaction (all formats + stdin) |
+| `~/.claude/lib/context-link-extractor.sh` | Phase 0 Step 4 input classifier (jira / confluence / graylog id labels) |
+| `~/.claude/lib/fetch-graylog.sh` | Phase 1 log evidence (`--trx` / `--conv`) |
+| `~/.claude/lib/fetch-confluence.sh` | Phase 0 Step 4 Confluence-sourced complaints |
+| `$HOME/.claude/multi-agent-refs/_account-picker.md`, `_repo-picker.md`, `picker-contract.md` | Phase 0 pickers |
+| `$HOME/.claude/multi-agent-refs/keychain.md` | Phase 1 non-critical credential handling |
+| `$HOME/.claude/multi-agent-refs/complaint-analysis-template.md` | Phase 4 report template (8 sections) |
+| `ai-common-toolkit:humanizer` | Phase 4 tone pass |
+| `$HOME/.claude/scripts/validate-complaint-doc.mjs` | Phase 5 pre-dispatch gate |
+| `$HOME/.claude/multi-agent-refs/channels/confluence.md`, `channels/jira.md`, `~/.claude/lib/md2confluence-v3.py` | Phase 5 dispatch |
+| `$HOME/.claude/schemas/complaint-analysis-spec.schema.json` | State contract |
+
+## Notes
+
+- Fully generic: hosts come from `prefs.global.hosts.*`, tokens from `prefs.global.keychainMapping.*`; no company name, host, or real repo name in this file.
+- `prefs.projects[<project>].routing.coreTeamLabel` is optional; when unset, `suggestedQueue` renders as `-` and the routing entry still stands.
+- If Confluence / Jira dispatch returns 401 / 403, surface the error and offer the Local fallback (the draft stays on disk).
+- The `complaints/` directory is not gitignored; the user commits manually if desired.

package/pipeline/commands/multi-agent/create-jira/SKILL.md

@@ -10,11 +10,11 @@ argument-hint: "[\"<free-text description>\"] [figma-url] [swagger-url]  -  all
 
 Creates exactly one Jira issue, and only after explicit approval. The issue type (Task / Bug / Story) is asked at the start of every run. No branches, no commits, no worktrees, no pipeline chaining. The draft learns the target project's conventions from its recent same-type issues (summary format, labels, components, priority norms, test-scenario style) 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.
+> **Language**: instruction prose here is English. AskUserQuestion `question`/`description` and the issue content (summary + description) follow `prefs.global.outputLanguage`, like every other user-facing payload body (`rules.md` matrix). `label`/`header` stay English.
 
 ## Issue types
 
-Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `$HOME/.claude/multi-agent-refs/generate-issue.md` for the full A/C matrix and inclusion rules).
+Type is chosen at step [3/12] via AskUserQuestion (never inferred silently). Each type has a standard template baseline; sections auto-size (see `$HOME/.claude/multi-agent-refs/generate-issue.md` for the full A/C matrix and inclusion rules).
 
 | Type | Always-present sections | Conditional sections (included only when their trigger is present) |
 |---|---|---|
@@ -24,11 +24,11 @@ Type is chosen at step [3/11] via AskUserQuestion (never inferred silently). Eac
 
 ## Flow
 
-Read `$HOME/.claude/multi-agent-refs/generate-issue.md` and execute the 11-step shared flow. Non-negotiables restated:
+Read `$HOME/.claude/multi-agent-refs/generate-issue.md` and execute the 12-step shared flow. Non-negotiables restated:
 
 - Ask the user (AskUserQuestion) for the issue type first, then about every genuinely unknown field  -  component, epic, priority, labels, assignee, sprint vs backlog, required custom fields.
 - A conditional section renders only when its trigger is present (Figma URL, pasted screenshot/log, Swagger URL/contract, real Notes content). No empty placeholder headings; content the user did not supply and mining could not derive is never invented.
-- Step [8/11] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
+- Step [9/12] full preview + approval gate always runs. `Approve` / `Edit` (loop) / `Cancel`. No bypass exists.
 
 ## Error paths
 

package/pipeline/commands/multi-agent/dev/SKILL.md

@@ -13,7 +13,7 @@ description-tr: "Hızlı geliştirme modu: Init → Dev (Opus) → Review → Te
 > 2. **`prefs.global.outputLanguage` is user-selectable**  -  applies to (a) every conversational line the agent writes back, and (b) every user-facing external payload: PR description body, Jira comment, Confluence body, Wiki body.
 >
 > Regardless of `outputLanguage`, these stay English (interop / convention):
->   - `AskUserQuestion` labels and descriptions (UI contract)
+>   - `AskUserQuestion` `label` + `header` only (UI contract)  -  the `question` and each option's `description` follow `outputLanguage`; a picker whose question is English on a Turkish run is a bug, not the contract
 >   - Commit message subject/body (git convention)
 >   - Branch names (`feature/`, `bugfix/`, ...)
 >   - Code identifiers, file paths, log lines
@@ -215,6 +215,14 @@ That is the whole list. Phase 0 (Init full picker), Phase 4 (Review), Phase 5 (U
 | Phase 5 User Test | ✅ | ✅ (same) |
 | Phase 7 channels (Jira / Confluence / PR / Wiki) | ✅ | ✅ (same) |
 | Duration | ~10-15 min | ~7-10 min |
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:resume-local`, not a second Dev pass). Read that section rather than reasoning about it from scratch.
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -236,7 +244,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
@@ -279,24 +287,3 @@ bash $HOME/.claude/scripts/phase-tracker.sh render
 ```
 
 Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fails.
-
-## Analysis doc supplied to a fast mode (warn before starting)
-
-The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
-the input references an analysis document  -  a Confluence URL, a local analysis file,
-or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
-plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
-whatever the model read first: the bottom of the dependency chain lands, the screen
-wiring does not.
-
-Say so before starting, once, and offer the choice:
-
-```
-This mode skips Analysis and Planning, so the analysis document will not be turned
-into a task breakdown. For analysis-driven screen work, /multi-agent or
-/multi-agent:local run both phases.
-  1. Continue with --dev (doc as context only)
-  2. Switch to the full pipeline
-```
-
-Autopilot picks 1 and logs the warning rather than asking.

package/pipeline/commands/multi-agent/dev-autopilot/SKILL.md

@@ -7,7 +7,7 @@ description-tr: "En hızlı mod: Dev (Opus) + Autopilot. Init → Dev → Review
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Dev mode + Autopilot combined: a 4-phase pipeline with no confirmations, end-to-end autonomous.
 
@@ -59,6 +59,14 @@ Phase 7: Report     → short terminal summary
 | Review | Parallel + triage (CLI-aware) | Parallel + triage (CLI-aware) | Parallel + triage (CLI-aware) | **Parallel + triage, auto-fix** |
 | Blocking finding | Fix loop, then ask | Fix loop, then ask | Auto-fix, breaker at 3 | **Auto-fix, breaker at 3** |
 | Estimated duration | ~12 min | ~7 min | ~10 min | **~5 min** |
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:resume-local`, not a second Dev pass). Read that section rather than reasoning about it from scratch.
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -82,7 +90,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)

package/pipeline/commands/multi-agent/dev-local/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent dev-local  -  Fast + Local
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 Dedicated form of the `--dev` + `--local` combination. A 4-phase fast pipeline (no worktree).
 
@@ -22,7 +22,6 @@ Phase 7: Report     → Jira / Wiki + log + knowledge/memory
 
 `--dev local` skips Phase 1 (Analysis), Phase 2 (Planning + Approval Gate), and Phase 5 (User Test  -  local/autopilot variants skip the interactive test gate). It differs from `--dev` on two axes: no git worktree is created (development happens directly on the current branch in `$PROJECT_ROOT`), and the interactive User Test phase is skipped. **Review is not skipped**  -  Phase 4 runs its gates, resolves the criteria the dev phase was supposed to honour, reviews in parallel and triages, and accepted blocking findings return to Phase 3 (3-iteration cap).
 
-> **Already have work on the branch?** For changes developed outside the pipeline, or by hand, run [`/multi-agent:ship`](../ship/SKILL.md) on that branch: it puts the existing diff through the same review, adds a build+test success gate, opens the PR and posts the Jira technical-analysis + test-scenario comment  -  without re-developing.
 
 ## When to use it
 
@@ -52,7 +51,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
@@ -105,30 +104,17 @@ Routes to the orchestrator with `--dev --local` flags. Apply the `$HOME/.claude/
 - Phase 6: commit + push + PR (the local checkout prompt is natural in local mode  -  you're already there; no worktree removal needed, code is already in `$PROJECT_ROOT`)
 - Phase 7: report + channels (same as `--dev`)
 
-## Examples
+## Intake warnings (`--dev` family)
 
-```bash
-/multi-agent:dev-local "PROJ-12345"                            # Jira
-/multi-agent:dev-local "Bug: LoginView dark mode"              # Free-text
-```
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:resume-local`, not a second Dev pass). Read that section rather than reasoning about it from scratch.
 
-## Analysis doc supplied to a fast mode (warn before starting)
+## Required: outward-facing payload contracts
 
-The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
-the input references an analysis document  -  a Confluence URL, a local analysis file,
-or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
-plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
-whatever the model read first: the bottom of the dependency chain lands, the screen
-wiring does not.
+Skipping Analysis and Planning does not shorten the payload contracts. Before writing anything outward-facing, load `$HOME/.claude/multi-agent-refs/payload-contracts.md`  -  the canonical list of what to read for the PR body, the Jira comment, and the closing report, plus the markup dialect per surface. Improvising a payload shape from memory is the single most common failure of the fast modes.
 
-Say so before starting, once, and offer the choice:
+## Examples
 
+```bash
+/multi-agent:dev-local "PROJ-12345"                            # Jira
+/multi-agent:dev-local "Bug: LoginView dark mode"              # Free-text
 ```
-This mode skips Analysis and Planning, so the analysis document will not be turned
-into a task breakdown. For analysis-driven screen work, /multi-agent or
-/multi-agent:local run both phases.
-  1. Continue with --dev (doc as context only)
-  2. Switch to the full pipeline
-```
-
-Autopilot picks 1 and logs the warning rather than asking.

package/pipeline/commands/multi-agent/dev-local-autopilot/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # multi-agent dev-local-autopilot  -  Fastest + Local
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` and external payloads stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` `label`/`header` stay English, but its `question` and option `description`s render in `outputLanguage`; external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 The triple `--dev` + `--local` + `autopilot`  -  the fastest form available. Zero confirmations, NO worktree.
 
@@ -38,7 +38,6 @@ Phase 1 (Analysis), Phase 2 (Planning + Approval Gate) and Phase 5 (User Test) a
 
 Routes to the orchestrator with `--dev --local autopilot` flags. The pipeline contract matches [`dev-autopilot/SKILL.md`](../dev-autopilot/SKILL.md) exactly, with Phase 0 Step 8 (worktree creation) skipped.
 
-> **Already have work on the branch?** For a diff that exists without a pipeline run behind it, [`/multi-agent:ship`](../ship/SKILL.md) applies the same review plus a build+test gate before the PR.
 
 ## Examples
 
@@ -46,6 +45,14 @@ Routes to the orchestrator with `--dev --local autopilot` flags. The pipeline co
 /multi-agent:dev-local-autopilot "PROJ-12345"                  # Jira
 /multi-agent:dev-local-autopilot "Add retry to HomeNetworking" # Free-text
 ```
+## Intake warnings (`--dev` family)
+
+Two checks belong at the top of every `--dev` run and are specified once in `$HOME/.claude/multi-agent-refs/phases/modes.md` "Intake warnings shared by the whole `--dev` family": an analysis document supplied to a mode that skips Analysis and Planning, and a branch that already carries the work (which wants `/multi-agent:resume-local`, not a second Dev pass). Read that section rather than reasoning about it from scratch.
+
+## Required: outward-facing payload contracts
+
+Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.
+
 ## Required: Phase Tracker Contract
 
 **The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
@@ -71,7 +78,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 ```
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -62,7 +62,7 @@ deletes nothing until you confirm.
    residue in the index (`.worktrees/{id}` recorded as a "Subproject commit"
    entry by a pre-guard `git add -A`), and a missing `.worktrees/` line in
    `.git/info/exclude`. Registered, healthy worktrees are NEVER touched  -
-   those belong to `/multi-agent:ship` / `/multi-agent:kill`.
+   those belong to `/multi-agent:resume-local` / `/multi-agent:kill`.
 
    - Output says `nothing to do` -> skip silently, no question.
    - Otherwise surface a second `AskUserQuestion` (in `outputLanguage`):