@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/multi-agent-refs/audit-guide.md

@@ -1,6 +1,7 @@
 ## Audit & Quality Tools Guide
 
 <!-- toc -->
+- [Audit & Quality Tools Guide](#audit-quality-tools-guide)
 - [Trigger Model](#trigger-model)
 - [iOS Accessibility Audit](#ios-accessibility-audit)
 - [Android Accessibility Audit](#android-accessibility-audit)
@@ -10,6 +11,9 @@
 - [Android APK Audit (Play Store Compliance)](#android-apk-audit-play-store-compliance)
 - [Integration with Pipeline Phases](#integration-with-pipeline-phases)
 - [Graceful Degradation](#graceful-degradation)
+- [Phase 3 evidence flows](#phase-3-evidence-flows)
+- [UI flow video, when Phase 2 produced none](#ui-flow-video-when-phase-2-produced-none)
+- [Snapshot regression flow (optional)](#snapshot-regression-flow-optional)
 <!-- /toc -->
 
 Standalone audit commands  -  runs directly via Bash, **no MCP server dependency**. These are the same checks that multi-agent-toolkit-mcp provides as MCP tools, but embedded here as pipeline skills.
@@ -250,3 +254,19 @@ unzip -l "$APK" 2>/dev/null | grep "classes.*\.dex" | wc -l
 - No Android SDK → skip Android audits, log "Android SDK not available"
 - No booted simulator → skip accessibility audit, log "No running simulator"
 - Audits are **enhancements**, never blockers for the pipeline flow
+
+## Phase 3 evidence flows
+
+Read from `phases/phase-3-review.md` "Automated Device Checks".
+
+### UI flow video, when Phase 2 produced none
+
+Phase 2 Step 3.55 is the primary host and runs in every mode. Phase 3 is the richer one where it exists: the device is up and a person is watching, so the flow is one somebody confirmed. It adds, never replaces.
+
+Run only when `visualEvidence.required` and `visualEvidence.video.file` is empty: re-check the device with `$HOME/.claude/scripts/probe-evidence-capability.sh --only device`, then `$HOME/.claude/scripts/capture-evidence.sh video start` -> drive the flow (`run-ui-tests.sh run`, or the Phase 3 scenarios by hand) -> `video stop` -> `fit`. The cap is `visualEvidence.maxVideoSeconds`, read through `capture-evidence.sh limits` so one value serves both. Update `videoTier` and `videoTierReason` with what ran.
+
+When the intake answer was `unit` there is no recording here either: overriding it in a phase the user may not be watching makes the question decorative.
+
+### Snapshot regression flow (optional)
+
+When the task changes a stable component, capture a screenshot before the change (baseline) and after (current), then call `ios_visual_diff({baseline, current, max_diff_pct: 1.0})`. Threshold can be relaxed for animated / non-deterministic regions  -  keep `max_diff_pct ≤ 1.0` for static layouts.

package/pipeline/multi-agent-refs/autopilot-on/details.md

@@ -0,0 +1,148 @@
+# autopilot-on: reasoning and detail
+
+<!-- toc -->
+- [Why doctor gates arming (step 1)](#why-doctor-gates-arming-step-1)
+- [Why a picker rather than a label alone](#why-a-picker-rather-than-a-label-alone)
+- [Source queries (step 4)](#source-queries-step-4)
+- [Why the JQL is run before saving](#why-the-jql-is-run-before-saving)
+- [Keeping the Mac awake (step 5)](#keeping-the-mac-awake-step-5)
+- [Config keys not written (step 6)](#config-keys-not-written-step-6)
+- [The menu bar indicator (step 7)](#the-menu-bar-indicator-step-7)
+- [Probe warnings (step 8)](#probe-warnings-step-8)
+- [Rendering the plist (step 8)](#rendering-the-plist-step-8)
+- [What `autopilot-control.mjs on` does](#what-autopilot-controlmjs-on-does)
+- [Why the report says what it says (step 9)](#why-the-report-says-what-it-says-step-9)
+<!-- /toc -->
+
+Read by `/multi-agent:autopilot-on` when a step needs its reasoning explained,
+when Jira is selected as a source (step 4), or when the probe or launchd reports
+a problem (step 8).
+
+## Why doctor gates arming (step 1)
+
+Arming unattended work on an install that `doctor` calls broken produces a queue
+of failures, one per item.
+
+## Why a picker rather than a label alone
+
+Push rights usually reach far more repos than you own, many of them other
+people's. A label is a filter; anyone who can open an issue in a repo you happen
+to have push on could add one. The gate is the repo selection, and it is per
+machine.
+
+Both halves of the repo list are shown because silently dropping the
+`unavailable` rows looks exactly like a permissions problem, and the user goes
+hunting for a token fault that does not exist.
+
+There is no `add-repo` / `remove-repo` command because two entry points to one
+list is two lists; re-running the picker is how repos are added and removed.
+
+## Source queries (step 4)
+
+| Source | Query | Extra condition |
+|---|---|---|
+| GitHub | `gh issue list --repo <r> --label <label> --assignee @me --state open` | **assigned to you** (`githubAssignee`, `"*"` for any), so a label an issue form applies is not enough |
+| Jira | `assignee = currentUser() AND labels = "<label>" AND resolution = EMPTY AND status not in (Done, Closed, Cancelled)` | **assigned to you**, so a label somebody else adds is not enough |
+
+Two Jira caveats to say out loud when Jira is selected: labels are one global
+namespace across the whole instance and anyone can write them, so on a shared
+instance prefer a qualified name (`agent-queue-<team>`); and the Labels field has
+to be on the edit screen for the issue types in play. An instance where neither
+holds is a `jiraJql` config change - a saved filter, a component - not a
+redesign.
+
+## Why the JQL is run before saving
+
+A JQL that returns nothing is not an error and is usually correct on day one
+(nothing is labelled yet), but a JQL that errors is a config that will be silent
+forever - the Labels field missing from an edit screen looks exactly like an
+empty queue from the outside. "0 items, query valid" and "query rejected" are
+reported differently for that reason.
+
+## Keeping the Mac awake (step 5)
+
+While the mode is on, a second launchd agent, `com.multi-agent.autopilot-awake`,
+runs `/usr/bin/caffeinate -s -i` from **Start** until `autopilot-off`. Without it
+the machine can sleep between ticks, and launchd does not wake it for the next
+one: the queue stops with nothing to say so. `-s` holds system sleep off on AC
+power; `-i` holds idle sleep off on battery too. Display sleep does not lock the
+keychain; system sleep can, which is the part `-s -i` prevents regardless of the
+display answer.
+
+## Config keys not written (step 6)
+
+Keys the schema reserves and nothing reads (`askOnLowMaturity`, `reportStatus`,
+`sendItemKeys`) are not written. A config written by an older version may carry
+`depthRouter` or one of those; the schema still accepts them and nothing reads
+them, so drop them when rewriting the file.
+
+## The menu bar indicator (step 7)
+
+Built from source on demand, never shipped as a binary: the package contains only
+text, and a compiled artifact in it would need signing and notarization to be
+distributable. The compiled binary is the one thing an update does not replace,
+so the runner rebuilds it on the first tick after `autopilot-menubar.swift`
+becomes newer than `bin/menubar`. A machine that is already on picks up a new
+indicator without running this command again.
+
+## Probe warnings (step 8)
+
+`PROBE_WARNING=` lines do not block: a login keychain that locks on sleep or
+after a timeout is readable now and locked for the tick after the Mac slept,
+which every tick checks again and refuses with the same message.
+`features/autopilot-operations.md` has the probe's rules.
+
+## Rendering the plist (step 8)
+
+Run before the Start / Configure only question:
+
+```bash
+. "$HOME/.claude/lib/autopilot-state.sh"
+TPL=$(ma_ap_asset templates/multi-agent-autopilot.plist.template) || {
+  echo "BLOCKED: the plist template is not installed on this host - re-run the installer"; exit 1; }
+DEST="$HOME/Library/LaunchAgents/com.multi-agent.autopilot.plist"
+INTERVAL=$(bash "$HOME/.claude/scripts/autopilot-status.sh" --json | jq -r '.scanIntervalSeconds // 120')
+sed -e "s|{{NODE}}|$(command -v node)|g" \
+    -e "s|{{TICK}}|$HOME/.claude/scripts/autopilot-runner.mjs|g" \
+    -e "s|{{LABEL}}|com.multi-agent.autopilot|g" \
+    -e "s|{{ROOT}}|$HOME/.claude/autopilot|g" \
+    -e "s|{{INTERVAL}}|$INTERVAL|g" \
+    -e "s|{{HOME}}|$HOME|g" \
+    -e "s|{{CLAUDE}}|$(command -v claude || true)|g" \
+    "$TPL" > "$DEST"
+```
+
+`ma_ap_asset` resolves the template rather than a literal
+`$HOME/.claude/templates/...`, because on a Copilot-only or Codex-only machine
+that tree may not exist. The state root stays shared on purpose - two CLIs on one
+machine must see one queue, not two.
+
+`command -v node` rather than the bare word: launchd does not read a login
+shell, so its `PATH` is the short one in the plist's own `EnvironmentVariables`,
+and a Homebrew or nvm node that is not on that path would make every tick fail
+with a message nobody is watching for. `claude` is captured the same way, and
+the plist's `PATH` carries `~/.local/bin` as well, which is where the native
+installer puts it; the runner tries the captured path first, then that `PATH`.
+
+## What `autopilot-control.mjs on` does
+
+The same script the office panel's `POST /v1/autopilot/on` calls. It keeps
+exactly the named repos in `config.json`, probes their credentials again
+(`autopilot-arming.mjs probeCredentials`), renders
+`templates/multi-agent-autopilot.plist.template` with its seven placeholders
+(NODE, TICK, LABEL, ROOT, INTERVAL, HOME, CLAUDE), loads it with `launchctl
+bootstrap` (falling back to `load`) and installs the awake agent with the saved
+`awake.display` answer. `--configure-only` saves the selection and installs
+neither.
+
+## Why the report says what it says (step 9)
+
+"Configure only" lets the queue be watched with `autopilot-status` for a while
+before anything runs. Both runs are worktrees and per-repo concurrency is 1, so
+the queue skips a repo you are working in rather than competing for
+`.git/index.lock`.
+
+Each of the five items is something a user has asked about after the fact.
+launchd loads at **login**, not boot, and that is correct: the login keychain is
+what unlocks the tokens, so a run before login could not reach Jira or GitHub
+anyway.

package/pipeline/multi-agent-refs/channels/generator.md

@@ -1,7 +1,21 @@
 # Channels - Generator (Step 5 section bodies)
 
+<!-- toc -->
+- [Jira body versus PR body](#jira-body-versus-pr-body)
+- [Content options](#content-options)
+- [Output template](#output-template)
+<!-- /toc -->
+
 > Loaded by `channels/SKILL.md` Step 5. The SKILL keeps the Jira-vs-PR body rule, the section-order rule and the target length rule; this file carries the content-option table, the aggregated output template, the store-compliance augmentation, and the work-summary and cost-summary generators. Read it before generating any section body.
 
+## Jira body versus PR body
+
+Jira is read by the person who filed the ticket and by whoever tests it, so its comment carries the four sections `channels/jira.md` fixes - `summary` (`Geliştirme Özeti`), `test_scenarios` (`Test Senaryoları`), `impact` (`Etki Analizi`) and `context_refs` (`Bağlantılar`), plus `test_run` when selected - and nothing else. Technical sections go to the PR and to Confluence, where the reader is a code reviewer. When `jira` is a selected channel, drop the technical sections from its body rather than converting them: the PR link on line 1 is how a Jira reader reaches the detail. No framework-theory paragraphs and no numbered "why this approach" lists in either body.
+
+`impact` is not a technical section in disguise. It answers four questions - what was wrong, what was changed, which areas must be tested, what else is affected - in the same plain register as the summary, and it is the part a test lead reads before deciding how wide to test.
+
+The content options are sources, not the body's shape. Which sections a PR body carries and in what order is fixed by `channels/pr.md` (`summary` -> `technical` -> `architecture` -> `impact` -> `test_scenarios` -> `test_run` -> `visuals` -> `risk` -> `dependencies` -> `build` -> `related`); the content options choose what gets gathered to fill them. A content option left unselected means a section has no source, not that the section may be reordered or renamed.
+
 ## Content options
 
 | Content option | Generated section |

package/pipeline/multi-agent-refs/channels/preview.md

@@ -23,3 +23,16 @@ The Jira table is the only *text* markup table in the doc set and never applies
 ```
 
 Secondary artifacts ride along as one-line intents at the bottom of the preview: Wiki page list, wiki → Jira triad comment (when Wiki is selected and the triad is active per `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`), Board status move (`{from} → {to}`), GitHub issue comment + Progress-flag sync (Phase 5 Step 1.5  -  same gate, see `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md`), test-run candidates to untick (`channels/test-run.md`), the Jira body's `--measure` (`render-jira-evidence.mjs`).
+
+## Approval options and skip cases
+
+The gate runs after the generator + humanizer and before Step 7 dispatch, in every interactive invocation: menu mode and `--channels` / `--content` flag mode alike (flags pick the targets, they do not waive the content approval). It is skipped only for autopilot (`state.autopilot === true` or `MULTI_AGENT_AUTOPILOT=1`, attended: explicit consent for side-effect creation, posts directly with prefs or flag selections) and `--dry-run` (prints without posting).
+
+| Option | Behavior |
+|---|---|
+| `Approve & post` | Step 7 dispatches every previewed body verbatim |
+| `Edit` | Free-text "which channel, what should change", apply, re-render the FULL preview, re-ask (loop, no cap) |
+| `Skip channels` | multiSelect which channels to drop this run, re-render the rest, re-ask |
+| `Cancel` | Abort dispatch entirely; nothing is posted anywhere. Internal capture (agent-log, knowledge) is unaffected |
+
+Persisting channel prefs (Step 8) still happens on `Cancel`: selection memory and content approval are independent.

package/pipeline/multi-agent-refs/channels/reference.md

@@ -1,5 +1,17 @@
 # Channels - Input forms, flags, summary format, error handling, cross-CLI parity, examples
 
+<!-- toc -->
+- [Input forms](#input-forms)
+- [Flags](#flags)
+- [Step 1 target resolution](#step-1-target-resolution)
+- [Step 4 mode short-circuit](#step-4-mode-short-circuit)
+- [Step 8 summary format](#step-8-summary-format)
+- [Error handling](#error-handling)
+- [Cross-CLI parity](#cross-cli-parity)
+- [Examples](#examples)
+- [Phase 5 delegation contract](#phase-5-delegation-contract)
+<!-- /toc -->
+
 > Loaded by `channels/SKILL.md`. Read the flag table and the error-handling table before Step 1 and whenever a target, a token or a precondition fails; the parity notes and examples are for orientation.
 
 ## Input forms
@@ -33,6 +45,27 @@
 | `--lang=tr\|en\|both` | Output language override (default: `en`; `promptLanguage` is locked to `en`). |
 | `--ready` | If PR draft, promote to READY after channels dispatch. |
 
+## Step 1 target resolution
+
+1. Parse the argument and classify it: Jira-id, Jira-url, PR-url (GitHub or Bitbucket), GitHub-issue-number, or empty (cwd + branch).
+2. Resolve linked entities:
+   - Jira ID: linked PR via the dev-status API (`/rest/dev-status/latest/issue/detail`).
+   - PR URL: Jira ID extracted from branch name / title / body using the `{JIRA_KEY}-XXXXX` pattern.
+   - GitHub `#N`: resolved against the repo in cwd.
+   - Empty: read the git branch, extract the Jira ID, find the linked PR.
+3. Detect the remote type: `github` (gh CLI) or `bitbucket` (REST).
+4. Store in runtime state: `{jiraId, targets: [{prUrl, prNumber, remoteType, repoPath, baseBranch, headBranch, repoName, isPrimary}]}`.
+
+## Step 4 mode short-circuit
+
+Non-interactive in three cases; the menu is skipped and flag values or prefs are used directly:
+
+| Mode | Behavior |
+|---|---|
+| `--channels X,Y` + `--content A,B` flags | Exact flag values, no menu. |
+| `autopilot` (Phase 5 delegate) | Reads `prefs.global.reportChannels` + `prefs.global.reportContent`. Per the Phase 5 autopilot-pause contract, Phase 5 still pauses before calling channels but pre-fills the menu from prefs. A post-hoc call in autopilot mode uses prefs directly. |
+| `--dry-run` | Runs the menu, generates output, prints to stdout, does not post. |
+
 ## Step 8 summary format
 
 ```
@@ -96,3 +129,16 @@ Progress emission on Copilot (no native TaskCreate UI): `bash ~/.copilot/scripts
   → auto-diff from cwd+branch PR + user note combined
   → posts to default channels (PR + Jira)
 ```
+
+## Phase 5 delegation contract
+
+Phase 5 invokes channels internally instead of running its own Jira / Confluence / Wiki logic:
+
+| Who | What |
+|---|---|
+| Phase 5 | Progress tracker (sub-steps 1-3), agent-log finalization (step 4), knowledge + memory capture (step 5), telemetry emission |
+| `channels` | All external delivery: PR description update, Jira comment, Confluence page, Wiki pages |
+
+Phase 5 passes a runtime state bundle: `{jiraId, prUrl, remoteType, taskType, figmaConfig, agentState, pipelineLogPath, flowRuns}`. Channels reads these directly and skips Step 1 target resolution.
+
+Autopilot: Phase 5 always pauses at the channels menu, the one exception to the autopilot zero-interaction contract. A 30-min timeout ends the session cleanly and the task stays resumable via `/multi-agent:resume`; full contract in `$HOME/.claude/multi-agent-refs/phases/modes.md`. The Step 6 approval gate follows the same split: interactive runs approve the composed bodies before dispatch, autopilot posts directly after the menu resolves.

package/pipeline/multi-agent-refs/complaint-analysis/phases.md

@@ -0,0 +1,159 @@
+# Complaint analysis - locked decisions, phase procedures and reusable refs
+
+<!-- toc -->
+- [Locked decisions](#locked-decisions)
+- [Phase 0](#phase-0)
+- [Phase 1](#phase-1)
+- [Phase 2](#phase-2)
+- [Phase 3](#phase-3)
+- [Phase 4.5](#phase-45)
+- [Phase 5](#phase-5)
+- [Reusable refs](#reusable-refs)
+- [Notes](#notes)
+<!-- /toc -->
+
+Reference for `/multi-agent:complaint-analysis`. The command file carries the step order, the hard rules and the stop conditions; this file carries the full locked decisions, the per-phase tables and commands, and the reusable-refs list.
+
+## Locked decisions
+
+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`-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).
+
+## Phase 0
+
+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. State schema: `$HOME/.claude/schemas/complaint-analysis-spec.schema.json`.
+
+### 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
+
+Environment defaults to `auto`: production first, the test instance (`hosts.graylogTest`) when production returns nothing or is unreachable. A customer complaint is normally a production event, but a tester-minted id only exists on test, and prod-only search reports "no logs" for both cases identically. When the intake itself says which environment a complaint came from, pin it with `--env prod` / `--env test` rather than letting the fallback decide.
+
+Record per complaint: `graylog: {status: ok|degraded|skipped, environment, 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`.
+
+**Always name the environment when citing log evidence.** `source.environment` in the fetcher payload says which instance answered; the same lines mean different things depending on whether a production complaint was corroborated by production logs or only by test ones. A complaint whose only evidence came from test is `insufficient-evidence` for a production claim, not `bff`.
+
+## Phase 2
+
+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`.
+
+## Phase 3
+
+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` (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.
+
+## Phase 4.5
+
+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[]`.
+
+## Phase 5
+
+`validate-complaint-doc.mjs` checks front-matter, required sections, verdict tokens per triage row, routing entry per core verdict, punctuation, and a redaction-leak scan.
+
+| 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.">
+
+## 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 |
+| `ai-analyst-toolkit:signal-community` | Phase 1 corroboration, optional. Advisory only: a matching report outside the company shows the complaint is not one user's device, and lands in the risks section with its link, never as a root cause. |
+| `$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
+
+- `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/multi-agent-refs/design-check/export.md

@@ -17,6 +17,7 @@
                         notVerified: [ { item, tag, reason } ] } } ] }
 ```
 
+- Persist the tool result's `coverage` to `state.designCheck.coverage`. On `gate: "pass"`, report per-variant PASS/FAIL, the findings count and the report paths.
 - `walk` separates a checked screen from a viewed one. Field definitions live in `features/design-conformance.md`.
 - Pass ids, not counts: the engine then names each unaccounted target in the report instead of printing an anonymous tally.
 - `compareSize` and `liveSize` come straight from the `design_visual_compare` result.

package/pipeline/multi-agent-refs/design-check/init-inventory.md

@@ -43,7 +43,7 @@ Intersect `$ARGUMENTS` (grammar in SKILL.md) with `inventory.targets`. Persist `
 
 ## Step 7 - `--resume`
 
-Read the most recent `~/DesignChecks/{repo}__{module}/*/run-state.json`; the scope becomes that run's targets minus its `covered` and minus its `skipped` entries. Skips carry a reason and are honoured, so a resume covers the genuinely unaudited remainder.
+Read the most recent `~/DesignChecks/{repo}__{module}/*/run-state.json`; the scope becomes that run's targets minus its `covered` and minus its `skipped` entries. Skips carry a reason and are honoured, so a resume covers the genuinely unaudited remainder. No previous run: tell the user and fall back to whole-module scope after confirmation.
 
 ## Step 8 - report dir
 

package/pipeline/multi-agent-refs/design-check/scope-and-ledger.md

@@ -0,0 +1,64 @@
+# design-check - scope grammar, requirements, the target ledger and notes
+
+Detail behind the command's scope argument, its requirements, the Phase 3 ledger and the Phase 4 gate. The binding rules (halts, confirmation, the coverage gate) stay in the command's SKILL.md; this file carries the grammar and the reasoning.
+
+## Scope grammar (`$ARGUMENTS`)
+
+The scope decides which inventory targets (Phase 0 step 5) the run must audit. It never changes how thoroughly each target is audited.
+
+| Form | Example | Scope |
+|------|---------|-------|
+| empty / `module` | (no argument) | Every target in the module's inventory |
+| screen name | `order-status` | Every target whose `screen` matches (case/separator-insensitive) |
+| `screen@variant` | `order-status@expired` | One target |
+| target id | `scenario-case:orderstatusoutcome-expired` | One target, exactly |
+| Figma URL(s) | `https://figma.com/design/...?node-id=1-2` | Only the frames those URLs name |
+| `--resume` | `--resume` | The unaudited remainder of the most recent run for this repo + module |
+| combinations | `seat-map summary@semi-success` | Union of the above, space- or newline-separated |
+
+A scope that matches no inventory target is an error, not an empty run: print the closest inventory ids and halt.
+
+**Whole-module is the default, and it is meant to finish.** The inventory prices each target (`cost: relaunch | in-app`) and batches them into a run `plan`, so a 50-target module is typically about a dozen relaunches rather than fifty: a full audit is one sitting, not a project. Scope exists for resuming an interrupted run and for re-checking one screen after a fix, not for trimming an audit down to what feels affordable. The coverage gate applies to the scoped target set, so a deliberate scoped run is never penalised for out-of-scope targets, and `--resume` closes the remainder.
+
+## Requirements
+
+- **iOS**: Xcode + an available Simulator. **Android**: Android SDK + a running emulator / device.
+- **MCP**: the `multi-agent-toolkit` MCP server (>= 2.8.0, for `design_scenario_inventory`, the `design_report` coverage gate, and `design_visual_compare` region alignment). The Figma MCP (`mcp__claude_ai_Figma__*`) must be authenticated; the user supplies the Figma URL.
+- The selected module must be auditable: a **mock mode** (preferred, it can toggle variants) or a **snapshot capture** of the screen's view model. Phase 0 decides which. Neither means the command halts.
+
+## Phase tracker detail
+
+Register the five tiles (`0:Init & Gate`, `1:Build & Launch`, `2:Figma`, `3:Drive & Compare`, `4:Report`) with `phase-tracker.sh init` + `add` in strict order before any update. On Claude Code also drive the native TaskList widget: fire all `TaskCreate` calls in phase order (0 to 4) first, persist each `taskId` via `phase-tracker.sh meta <N> tasklist_id`, then flip status with `TaskUpdate` + `phase-tracker.sh update` at every boundary. On Copilot CLI or a plain shell there is no TaskList widget: call `phase-tracker.sh render` after every state change and never call TaskCreate. Full spec: `tracker-contract.md`.
+
+## Why Phase 3 iterates the inventory
+
+Phase 3 iterates `state.designCheck.scope.targetIds`, a finite list decided in Phase 0, and ends when every id is resolved, not when the UI stops offering new taps. Tap-walking alone cannot reach a state that needs a different launch argument, scenario case, or typed scenario code, which is how a module's error and edge states go missing.
+
+Driving `inventory.plan` batch by batch is what makes full coverage affordable: each batch is one launch, the relaunch target opens a screen, and every in-app target for that screen is flipped while the app sits there, with no relaunch between them.
+
+`features/design-conformance.md` owns the per-component catalog, the scope tags, and the three rules that decide whether Phase 3 produced a result or an impression: enumerate first (a blank cell is a fail-to-verify), measure never the token, and converge per component (two consecutive clean attempts, cap 8). The screen is done when every component converged, not when the walk reached the bottom. Every skipped `[DYNAMIC]` / `[CAPTURE+]` item is listed in the report rather than omitted.
+
+## The ledger (Phase 3.5)
+
+Every scoped target id ends in exactly one bucket:
+
+- **covered**: captured AND compared.
+- **skipped**: with a concrete reason recorded in 3.1 or 3.3. A screen the user declined to map in the 3.3 batch-ask is a skip with reason "no Figma frame supplied". "Requires a scenario / prefix / launch-arg" is not a reason: it describes the work, which is Phase 3's job.
+
+`run-state.json` in the Phase 0 report dir holds `{ targetIds, covered, skipped }` so `--resume` can pick up the remainder. An id in neither bucket is a bug in Phase 3, and Phase 4's gate fails the run for it.
+
+The `covered.length + skipped.length` versus `scope.targetIds.length` check exists because reaching Phase 4 with a mismatch is the worst of both outcomes: the work is undone AND the run is marked incomplete.
+
+## The report's `walk` block and the gate
+
+`walk` (`components`, `converged`, `didNotConverge`, `notVerified`) separates a checked screen from a viewed one: an empty `notVerified` on a run that never captured a dark or mirrored pass is a false clean, so list the skip. Pass ids, not counts.
+
+The coverage gate is a last line of defence, not the plan. If it fires, Phase 3 left work undone: drive the missing targets, and only then report. Do not present an incomplete audit as a finished one, and do not bury the miss in a footnote.
+
+## Notes
+
+- **Feasibility is real**: a project with no launchable app or no runtime switch cannot be audited. Report that honestly and stop; never substitute a fabricated or partial comparison.
+- **The inventory is the contract**: Phase 0 step 5 decides what "done" means. An audit that visits the linear happy path and lists the rest as "not visited" is the failure mode this command exists to prevent; the gate makes it visible instead of polite.
+- **Chunk with scope, not with silence**: a 50-target module is a legitimate multi-run job. Scope it, finish each run's gate cleanly, and let `--resume` carry the remainder.
+- **"Pixel perfect" is perceptual + geometric**: scale normalized, chrome cropped; findings carry px / pt / hex deltas and a tolerance.
+- The `design_*` engine is project-agnostic; project specifics (mock keys, launch args / targets, node overrides, status-bar crop, coverage floor, Confluence toggle) come from `design-check-config.json` / prefs, never hardcoded.

package/pipeline/multi-agent-refs/features/analysis-command-notes.md

@@ -0,0 +1,53 @@
+# Analysis command notes: scope, profiles, template, outputs and tracker detail
+
+Read by `/multi-agent:analysis` before Phase 0. The command file keeps the step skeleton, the side-effect contract, the gates and the hard rules; this file holds the scope, the profile table, the template rules, output naming and source-handling notes. Every question asked follows `$HOME/.claude/multi-agent-refs/picker-contract.md`. The engine contracts themselves live in the `analysis/` refs the command names.
+
+## Scope
+
+This command is **independent** from the orchestrator's Phase 1 analysis (which is a stack/findings detector inside `/multi-agent`). It produces a stakeholder-ready, platform-agnostic feature-spec document - up to 23 sections, trimmed to whatever the evidence supports - before any implementation starts. Each per-platform file is rendered by projecting concept-layer content onto repo-extracted conventions (Pass B).
+
+this command produces a *development* analysis  -  what to build, the architecture plan, files to add, the test plan, and which existing components to reuse. It is NOT a design / screen-anatomy specification. The design itself is already produced elsewhere (figma-to-swiftui builds the components and binds them via Code Connect), so the analysis consumes those existing bindings as the source of truth for "what already exists" (see Phase 1b.1) instead of re-deriving the design. Do not grow this command toward exhaustive per-screen layout / gesture / state documentation; keep it development-focused.
+
+## Profiles
+
+Phase 0 Step 1b asks which analysis standard the document follows (Locked 31), and the answer selects the template. Both profiles read the same evidence: intake, fetching, repo evidence and convention extraction are shared, so the two cannot drift into two products.
+
+| Profile | Template | Shape |
+|---|---|---|
+| `global` (default) | `analysis-template.md` | Development handoff, 23 sections. Business rules with Gherkin acceptance criteria, architecture plan, files to add, test plan. Zero-evidence sections drop (Locked 2). |
+| `corporate` | `analysis-template-corporate.md` | Requirements document. `IG -> UC -> FG` spine with three traceability matrices, current and target state with impact analysis, then Technical Analysis and Development Analysis. The Part A backbone always renders, carrying `N/A` or `EKLENECEK` (Locked 32). |
+
+One run emits one profile. A missing input never blocks either profile: the gap is written as `EKLENECEK` and raised as a Section 20 open question rather than halting the run.
+
+**Stack is optional** (Locked 34). When no platform is selected the run still completes: everything that does not need a target repository renders in full, and only the development layer plus the Pass B projection are skipped, with a Section 20 row recording why. The output is a single file at `~/Desktop/multiAgentAnalysis/<feature-name>/<feature>.md` instead of one per repo: without a repo there is no working tree for the usual `analysis/` path to be relative to, and the current working directory is never written to. The Phase 3.5 picker shows the resolved path and accepts an override.
+
+## Template
+
+v3 template at `$HOME/.claude/multi-agent-refs/analysis-template.md`. The document renders up to 23 main sections + footer, minus any dropped by the omission table. The analysis doc is a development handoff, so low-signal sections are default-drop: **19 Alternatives** (render only for a real 2+-option architectural decision), **22 Glossary** (render only on request or >5 unfamiliar domain terms), and **18 Rollout** (compact checklist only, dropped when the pipeline's own commit/PR/rollout phase covers it). Sections are chosen from evidence; there is no second mode (ADR-0015, `docs/adr/0015-one-pipeline-no-depth-answer.md` in the pipeline repo). Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; a rendered section keeps its canonical template number, so the rendered set has gaps.
+
+Numbering is plain Arabic numerals: `## 1. Geliştirme Özeti` / `## 1. Summary`, `## 2. Hedefler ve Karşı Hedefler` / `## 2. Goals and Non-Goals`. No special section characters; the section sign codepoint (U+00A7) is banned by `feedback_no-section-sign`.
+
+The template is platform-agnostic (Locked 22). It speaks in concepts (state holder, view, navigator, use case, repository, DTO, state model, DI register, localization key, accessibility identifier, test method). Pass B (Phase 2b) projects each concept onto the selected platform using `state.analysisSpec.evidence.conventions[<repo>]` extracted at Phase 1c. Every projected cell carries a footnote pointing to its evidence source (Locked 24).
+
+## Phase summaries
+
+- **Phase 0**: sequential `AskUserQuestion` steps filling `state.analysisSpec.*`: analysis name, analysis profile, account, platform multi-select, repos per platform, the six-question source batch (Figma / Swagger / Confluence / Jira / Standards / Firebase) and the two coverage opt-ins. Every step prints its breadcrumb.
+- **Phases 1 to 1c**: fetch every declared source in parallel, collect the 13-bucket repo evidence, build the Code Connect index, and extract the seven convention groups.
+- **Phases 3 to 5**: render one markdown file per platform, run the humanizer pass, gate on the validator and the references coverage gate, ask for the output destination, dispatch to Local / Confluence / Jira, report and stop.
+- **Resume**: `analysis/resume.md` holds the `state.analysisSpec.phase` enumeration and the re-entry rule per paused phase.
+
+## Notes
+
+- The minimum possible output (per per-platform file) is `1. Scope` + `7. Development Plan` (both always-present).
+- If Confluence or Jira POST returns 401 / 403 during Phase 4, surface the error and offer Local fallback (the local drafts in `/tmp/` are still on disk; copying them into the repo working tree is always available).
+- The `analysis/` directory is not in `.gitignore`; the user can `git add analysis/` manually. No auto-commit.
+- **Per-platform file naming**: `analysis/<feature>-<platform>.md`. The `<platform>` slug is lowercase, one of `ios | android | web | backend` for a repo-backed run, or `mobile | web` for the channels a repo-less run derives from its evidence (Locked 34). `web` is the pre-`web` spelling and is still read back for older state and documents. The `<feature>` slug preserves the user's feature name with whitespace replaced by `-` (e.g. `User Profile` -> `UserProfile` or `Item-Status` depending on input shape; the renderer trims and de-duplicates dashes).
+- **Standards binding (the Standards question)**: When `evidence.standards[]` is non-empty, every decision in Section 13 (Architecture Plan, corporate Section 17) must cite the binding source in its 13.7 Standards-binding table. The renderer enforces this by failing render if any architectural decision has no `cite:` reference; the user is prompted to either tighten the source or add a Risk row acknowledging the missing citation.
+- **Firebase ingestion (the Firebase question)**: Console URLs are never fetched (auth-gated). Only `:names` and `:schema` inputs feed `evidence.firebase[]`. Section 11 Analytics (corporate Section 13) emits per-platform snippets but the events table itself is shared across all per-platform files (the rules / event vocabulary is one product invariant).
+- **Wiki access fallback chain**: Phase 1 `wiki` fetcher tries (a) `git clone .wiki.git`, (b) `gh api repos/.../contents/<file>.md`, (c) raw `WebFetch` of the page URL. Only after all three fail does the entry land in `fetchErrors[]`.
+- **Local-file safety**: `local-file` reads are scoped to `~/`, `/Users/`, and the repo's working tree. Paths outside these prefixes are rejected with `WARN: refusing to read <path>; outside allowed roots` to avoid accidental ingestion of unrelated files.
+- **Standards vs Confluence vs Document split**: the Confluence question collects feature-specific spec pages and the Document question the same spec delivered as a `.docx` / `.pdf` / `.md` / `.txt` file  -  both describe what the feature IS and both land in `evidence.documents[]`. The Standards question collects cross-cutting documentation that constrains the development plan (architecture, coding conventions, navigation pattern). A source pasted in more than one of the three is de-duplicated (by URL, or by `realpath` for a local file) and the Standards entry wins, because it retains the binding flag.
+- **Workspace coding documentation default**: when the Standards question's option 2 (Auto-detect) is selected, the probe also reads `prefs.projects[<project>].confluenceStandardsParent` (if set) and looks for child pages whose title starts with `Coding`, `Standards`, `Architecture`, or `Navigation`. If that fetch fails with auth, log a hint that the user should host an offline mirror at `prefs.projects[<project>].standardsFile` (canonical local fallback).
+- **Mixed paste handling**: the Standards and Firebase Other inputs accept comma-separated mixed entries. Whitespace is trimmed; entries are de-duplicated by canonicalised string (lowercase scheme + host + path for URLs; `realpath` for local files; lowercase exact match for event names).
+- **Repo-evidence reuse policy**: Phase 1b's catalogue is consulted by Pass B Section 7 rendering. The `direct-match` tag is the strongest signal; a `same-domain` row becomes an advisory note ("consider adapting existing X in the same feature directory"); `cross-cutting` items become a sentence in the section preamble ("reuse the cross-feature X from Common/"). See Locked decision 11.
+