@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

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

@@ -12,184 +12,77 @@ confirm: none
 
 **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.**
+Triage of customer-reported errors across the layers the team owns (client apps + BFFs): Graylog evidence by trx/conversation id, read-only repo correlation, a verdict per complaint. **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.
+**Side-effect contract**: may write a local markdown report, post a Confluence page, or add a Jira comment - 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.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The report body follows `outputLanguage`; Graylog excerpts, verdict tokens, and external payload metadata stay English.
+> **Language**: instruction prose stays English (`$HOME/.claude/multi-agent-refs/rules.md` Language Application). `AskUserQuestion` `question` / `label` / `description` and the report body follow `outputLanguage`; `header` (<=12 chars), verdict tokens, Graylog excerpts and payload metadata stay English.
+
+Procedures, tables, the full locked decisions and the reusable refs: `$HOME/.claude/multi-agent-refs/complaint-analysis/phases.md`. Read the section each phase names before running it.
 
 ## 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`-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).
+1. **Graylog is primary evidence.** A fetch failure never halts the run; it caps that complaint at `insufficient-evidence`.
+2. **Ids are never guessed.** No trxId and no convId: the user supplies one or marks `skip-graylog`. Empty submit is not consent; re-ask.
+3. **Read-only ops command.** No worktree, branch, commit, PR, or dev chaining.
+4. **Redaction before any output** (`parse-complaints.sh`, Jira / Confluence text via `--stdin`). Raw PII never enters state, drafts or any target.
+5. **Core is a residual classification, not a repo**: routing only, no fix analysis, no core-repo grepping.
+6. **Layer mapping is user-confirmed** before Phase 1.
+7. **Output default = Local file**; 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; Turkish diacritics preserved, never ASCII-folded.
+9. **Language split** as above.
+10. **Citations.** `client`/`bff` cites a Graylog message (timestamp + source) AND a `file:line`, else `insufficient-evidence`; `core` cites the message naming the upstream service.
+11. **One batch per run**; unrelated products: ask to split.
+12. **No auto-commit.**
+13. **Client/bff verdicts carry a dev handoff** (fix plan + dev prompt), never run here; other verdicts get none.
 
 ## 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)
+`AskUserQuestion` chain into `state.complaintSpec.*`, breadcrumbs per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Read `phases.md` "Phase 0" first.
 
-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"`.
+0. **Language (BLOCKING)**: read `prefs.global.outputLanguage` (default `tr`) before the first picker; every `<localized: "...">` marker renders in it, never literally.
+1. **Run name**: quoted argument, else `complaints-<YYYYMMDD>` (announce, do not ask).
+2. **Account**: `$HOME/.claude/multi-agent-refs/_account-picker.md`; `null` only for a fully local run.
+3. **Repos**: `$HOME/.claude/multi-agent-refs/_repo-picker.md`, owned client + BFF repos only.
+3b. **Layer tagging**: infer a layer per repo, ONE confirmation question with the whole table (`Approve mapping` / `Override rows`) (Locked 6).
+4. **Complaint input**: every source through `parse-complaints.sh` (Locked 4), merged as `C-01..C-NN`.
+5. **Id confirmation loop** for every complaint missing both ids (Locked 2). Then `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
-```
-
-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`.
-
-Set `phase: "correlating_repos"`.
+`~/.claude/lib/fetch-graylog.sh --trx <trxId> --conv <convId>` per complaint with an id and no `skipGraylog`; environment `auto` unless the intake pins it (`--env prod|test`). Exit 2 / 3 / 6: warn ONCE per `$HOME/.claude/multi-agent-refs/keychain.md`, mark the rest `degraded`, continue; never halt (Locked 1). **Always name the environment when citing log evidence**; test-only evidence is `insufficient-evidence` for a production claim. Statuses and recorded fields: `phases.md` "Phase 1". Then `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"`.
+Grep the selected repos for Graylog-derived signals only; degraded or skipped complaints get a `partial` text-similarity pass. Details: `phases.md` "Phase 2". Then `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` (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"`.
+Owned-layer origin -> `client:<ios|android|web>` / `bff:<mobile-bff|web-bff>`; downstream unowned failure -> `core` + routing recommendation; no evidence -> `insufficient-evidence`. Ambiguity lowers `confidence`, never invents evidence. Condition table, routing shape and the client/bff fix plan + dev prompt (Locked 13): `phases.md` "Phase 3". Then `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 (required: 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: `node $HOME/.claude/scripts/validate-complaint-doc.mjs <draft>` reports no banned-punctuation error. It checks the policy in Node; `grep -P` is absent from BSD grep and would never run.
-4. Show the draft path + size to the user. Set `phase: "awaiting_output_decision"`.
+1. Render per `$HOME/.claude/multi-agent-refs/complaint-analysis-template.md` to `/tmp/complaint-analysis-<run-slug>-<UTC-iso8601>/report.md` (`outputs.draftDir`).
+2. **Humanizer pass (required: actually invoke the `ai-common-toolkit:humanizer` skill; the punctuation grep alone does NOT satisfy this)**: `language: <tr|en>`, `tone: technical-explanatory`, `stripFancyPunctuation: true` (Locked 8).
+3. `node $HOME/.claude/scripts/validate-complaint-doc.mjs <draft>` reports no banned punctuation (never `grep -P`).
+4. Show path + size; `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"`.
+`AskUserQuestion` multiSelect, `header` `Output`, options `Local file` (pre-selected, Locked 7) / `Confluence page` / `Jira`; follow-ups in `phases.md` "Phase 4.5". Then `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.">
+**Pre-dispatch gate (BLOCKING)**: `validate-complaint-doc.mjs <draft>`; any ERROR blocks dispatch until fixed and re-validated. Local copies to `complaints/<run-name>.md` with **no commit** (Locked 12); Confluence and Jira re-humanize and post per `phases.md` "Phase 5" (a Jira issue gets a comment, never a close or transition). 401 / 403: surface it and offer Local. Print the `outputLanguage` summary (`phases.md` "Phase 5").
 
 **Stop. Do not chain into a dev run. 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 |
-| `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 |
+`state.complaintSpec.phase`: `intake | fetching_graylog | correlating_repos | triaging | drafting | awaiting_output_decision | dispatching | reporting | done`. At `awaiting_output_decision`, jump to Phase 4.5 when `report.md` is still in `outputs.draftDir`, else re-render Phase 4 from state. Earlier phases resume at their own boundary. Graylog results in state are never re-fetched.
 
 ## 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.
+- Fully generic: hosts from `prefs.global.hosts.*`, tokens from `prefs.global.keychainMapping.*`; no company name, host, or real repo name in this file.

package/pipeline/commands/multi-agent/design-check/SKILL.md

@@ -9,13 +9,11 @@ confirm: none
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__claude_ai_Figma__get_metadata, mcp__claude_ai_Figma__get_design_context, mcp__claude_ai_Figma__get_screenshot, mcp__multi-agent-toolkit__design_mock_detect, mcp__multi-agent-toolkit__design_scenario_inventory, mcp__multi-agent-toolkit__design_mock_launch, mcp__multi-agent-toolkit__design_ui_geometry, mcp__multi-agent-toolkit__design_visual_compare, mcp__multi-agent-toolkit__design_report, mcp__multi-agent-toolkit__ios_list_devices, mcp__multi-agent-toolkit__ios_boot_device, mcp__multi-agent-toolkit__ios_launch_app, mcp__multi-agent-toolkit__ios_terminate_app, mcp__multi-agent-toolkit__ios_screenshot, mcp__multi-agent-toolkit__ios_tap, mcp__multi-agent-toolkit__ios_swipe, mcp__multi-agent-toolkit__ios_type_text, mcp__multi-agent-toolkit__ios_open_url, mcp__multi-agent-toolkit__ios_get_ui_tree, mcp__multi-agent-toolkit__ios_status_bar, mcp__multi-agent-toolkit__ios_set_appearance, mcp__multi-agent-toolkit__ios_set_locale, mcp__multi-agent-toolkit__ios_xcodebuild, mcp__multi-agent-toolkit__ios_xcresult, mcp__multi-agent-toolkit__android_list_devices, mcp__multi-agent-toolkit__android_screenshot, mcp__multi-agent-toolkit__android_tap, mcp__multi-agent-toolkit__android_swipe, mcp__multi-agent-toolkit__android_type_text, mcp__multi-agent-toolkit__android_open_url, mcp__multi-agent-toolkit__android_launch_app, mcp__multi-agent-toolkit__android_stop_app
 ---
 
-# /multi-agent:design-check  -  Mock-mode vs Figma design audit
+# /multi-agent:design-check - Mock-mode vs Figma design audit
 
-Local, on-device design-conformance auditor. Runs the app in a **mock mode** on a simulator / emulator and compares each screen (and every mock variant the build exposes) against its Figma design at the **pixel + geometry + typography + color** level, then produces a detailed report.
+Runs the app in **mock mode** on a simulator / emulator and compares each screen and mock variant against Figma at the **pixel + geometry + typography + color** level. **Local-only**: no CI, no commits, no PR; the report goes to `~/DesignChecks/`, the worktree only isolates the Debug build.
 
-**Local-only**: no CI/CD, no cron, no commits, no PR. Read-only audit; writes a report to `~/DesignChecks/`. The worktree only isolates the Debug build from the user's working tree.
-
-> **Language (read FIRST)**: `prefs.global.promptLanguage` is always `en` - this spec and every instruction to the LLM stay English. `prefs.global.outputLanguage` applies to conversational lines and the human-readable parts of the report; pass it to `design_report` as `report.lang` (engine defaults to English, ships `en` + `tr` label packs, per-key `report.labels` overrides). `AskUserQuestion` `header` chips, branch names, file paths, code identifiers and log lines stay English; option `label`s follow `outputLanguage`. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language**: this spec stays English. `outputLanguage` covers conversational lines and the report (`design_report` `report.lang`); `header` chips, paths, identifiers and logs stay English. Contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
 
 ## Gotchas
 
@@ -23,145 +21,43 @@ Local, on-device design-conformance auditor. Runs the app in a **mock mode** on
 - The coverage gate fails the run when a target was neither audited nor skipped with a reason. "Not reached" is not "passed".
 - A Figma variant with no matching mock state is a finding about the mock, not a pass for the screen.
 
-## Scope  -  `$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` | `/multi-agent:design-check` | 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. 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.
-
-## Pipeline
-
-```
-Phase 0: Init & Gate  → repo + module picker, platform detect, MOCK FEASIBILITY GATE, SCENARIO INVENTORY, scope resolve, report dir, worktree
-Phase 1: Build & Launch → Debug build in worktree, boot device, install, launch in mock mode
-Phase 2: Figma          → fetch module frame tree, enumerate + map variants (ask when ambiguous)
-Phase 3: Drive & Compare → per plan batch: one launch → capture + flip in-app states → match → batch-ask → compare
-Phase 4: Report         → coverage gate + assemble + export HTML + PDF (+ Confluence) to ~/DesignChecks/
-```
-
-## 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 → the command halts.
-
-## Phase Tracker Contract (mandatory)
-
-Register one tile per phase in strict order BEFORE any update, on both channels. Full spec: `$HOME/.claude/multi-agent-refs/tracker-contract.md`.
-
-```bash
-bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in "0:Init & Gate" "1:Build & Launch" "2:Figma" "3:Drive & Compare" "4:Report"; do
-  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
-done
-```
-
-In Claude Code also drive the native TaskList widget: fire all `TaskCreate` calls in phase order (0→1→2→3→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 / plain shell call `phase-tracker.sh render` instead (no TaskCreate).
-
-## STOP-AND-CONFIRM format
-
-Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker per `picker-contract.md` (numbered text menus are forbidden). Print a `Step <i>/<n>: <what it decides>` breadcrumb before each picker. Confirmation is required even with a single option; state inheritance from a previous run is FORBIDDEN.
-
----
-
-## Phase 0 - Init, Feasibility Gate & Inventory
-
-0. **MCP CURRENCY GATE (first, before anything expensive)** - a session started before the last update serves the OLD tool list while reporting "connected". Check both halves before the Debug build: (a) **session** - `design_scenario_inventory` is available and `design_visual_compare` accepts `live_region`; (b) **disk** - probe what a fresh connection would serve. Disk OK but session stale → **HALT**, tell the user to reconnect (`/mcp` → `multi-agent-toolkit` → Reconnect). Disk stale → **HALT**, the checkout needs updating. Both current → continue. Never substitute a local `node` call for a missing tool: the run would silently lose the coverage gate and region alignment. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/mcp-currency-gate.md`. Read it for Phase 0 step 0.
-1. **Repo picker** - `$HOME/.claude/multi-agent-refs/_repo-picker.md`. Account picker skipped unless Confluence export is enabled.
-2. **Module / dev-context picker** - `$HOME/.claude/multi-agent-refs/_dev-context.md`; multi-module allowed, each audited independently.
-3. **Platform detect** - persist `state.designCheck.platform`.
-4. **MOCK FEASIBILITY GATE** - `mcp__multi-agent-toolkit__design_mock_detect` on the selected module path. Branch on `supported`:
-   - **`false`** → try the **snapshot lane** before halting: a screen renderable from its own view model is auditable without a runtime mock switch. Ask via `AskUserQuestion`, persist `state.designCheck.captureLane = "snapshot"`, and state the trade (no in-app variant flips). Declined or not renderable → **HALT** with `reason`. Never fabricate a comparison.
-   - **`"debug-only"`** → `AskUserQuestion` warning: variants cannot be toggled at launch, only the default Debug state is comparable. Continue / Cancel.
-   - **`true`** → continue; persist `state.designCheck.mock`.
-5. **SCENARIO INVENTORY (this is the audit's target set)** - `mcp__multi-agent-toolkit__design_scenario_inventory` with the config's inventory overrides. This list, not the agent's reading of the code or what the UI exposes to tapping, is what the run is measured against. Persist verbatim to `state.designCheck.inventory`.
-   - `targetCount: 0` → warn that no state driver was found and only the default launch state can be audited; a `debug-only` project lands here.
-   - `truncated: true` → the target set is INCOMPLETE. Say so now, and pass `coverage.truncatedInventory: true` in Phase 4 so the gate fails rather than reporting a clean percentage of a partial denominator. Narrow the scope to a screen and work through the module in `--resume` steps.
-   - `ignored[]` non-empty → list what the config dropped, so a stale `ignoreTargets` cannot quietly shrink the audit.
-6. **Scope resolve** - intersect `$ARGUMENTS` with `inventory.targets`; persist `state.designCheck.scope = { argument, targetIds[] }`. Print the set grouped by screen as `<n> targets · <relaunchCount> relaunches` (cost from `plan`, not the target count). Ask for confirmation only when `relaunchCount` exceeds `config coverage.confirmAbove` (default 25), as a cost estimate; never propose a smaller scope as the easy path.
-7. **`--resume`** - scope = the latest `run-state.json` targets minus `covered` minus `skipped`. No previous run → tell the user and fall back to whole-module scope after confirmation.
-8. **Report dir** - create `~/DesignChecks/{repo}__{module}/{UTC-timestamp}/` (+ `assets/`) now, persist `state.designCheck.reportDir`; it exists before driving starts.
-9. **Worktree** - `{projectRoot}/.worktrees/{taskId}`, `taskId` = `DC-<shortId>`, **never under $HOME**; prune stale locks and add the residue guard first. Local mode is not offered.
-
-Then persist `agent-state.json`. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/init-inventory.md`. Read it for Phase 0 steps 1-9.
-
-## Phase 1 - Build & Launch (mock)
-
-Debug build in the worktree (mocks need Debug), boot, install once, fix status bar / appearance / locale, launch via `design_mock_launch` with the Phase 0 activation (`debug-only`: plain launch). Phase 3 relaunches, never rebuilds. Full procedure: `$HOME/.claude/multi-agent-refs/design-check/build-launch.md`. Read it for Phase 1.
-
-## Phase 2 - Figma fetch & variant mapping (module-scoped)
-
-Figma **discovery** happens only here: the frame tree is fetched once and no later phase browses Figma looking for candidates. Phase 3 may still fetch a specific node the user hands over in the 3.3 batch-ask - that is a targeted fetch of an already-identified frame, not discovery, and it is the only Figma call allowed after this phase.
-
-Fetch the frame tree, map each scoped target to a frame, fetch screenshot + design context per variant, persist `state.designCheck.variants[]`. **Ambiguous or unmatched → defer to the Phase 3.3 batch-ask. Never guess silently.** Full procedure: `$HOME/.claude/multi-agent-refs/design-check/figma-mapping.md`. Read it for Phase 2.
-
-## Phase 3 - Drive every scoped target → capture → match → batch-ask → compare
-
-**This phase iterates `state.designCheck.scope.targetIds`  -  a finite list decided in Phase 0. It 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 / edge states go missing.
-
-### 3.0 What every capture is compared against
-
-**Read `$HOME/.claude/multi-agent-refs/features/design-conformance.md` before the first compare.** It owns the per-component catalog (30 groups), the scope tags, and the three rules that decide whether this phase 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.
-
-### 3.1 Drive the inventory's plan, batch by batch
-
-**Follow `inventory.plan`, filtered to the scoped ids.** Each batch is one launch: the relaunch target opens a screen, then every in-app target for that screen is flipped while the app sits there - **no relaunch between them**. Driving the plan is what makes full coverage affordable. Activate each target by its `driver.type`, and capture the tap-reachable sub-states (sheets, modals, inline errors) under `<id>#<sub-label>`. Each capture (screenshot + `design_ui_geometry`) goes to `state.designCheck.captured[]`. **Persist `state` and `run-state.json` after every capture**, so a run that dies mid-way resumes from where it stopped. Full procedure (driver table, capture mechanics): `$HOME/.claude/multi-agent-refs/design-check/drive-capture.md`. Read it for Phase 3.1.
-
-An unreachable target is recorded immediately as `{ id, reason }` in `state.designCheck.skipped[]` with a concrete reason. "Requires a scenario / prefix / launch-arg" is **not** a reason - it describes the work, which is this phase's job.
-
-### 3.2 Match each capture → Figma frame (auto)
+## Scope, requirements, tracker
 
-Accept only a **confident** match against the Phase 2 tree; matched → `pairs[]`.
+Before Phase 0, read `$HOME/.claude/multi-agent-refs/design-check/scope-and-ledger.md`: the scope grammar (empty, screen, `screen@variant`, target id, Figma URL, `--resume`), the requirements, the tracker detail and the ledger rules. Whole-module is the default and is meant to finish; scope is for resuming or re-checking, never for trimming. No mock mode and no snapshot capture: halt.
 
-### 3.3 Batch-ask the user for EVERYTHING unmatched (ONE prompt, WITH the visual)
+Tracker: `phase-tracker.sh init` + `add` for `0:Init & Gate`, `1:Build & Launch`, `2:Figma`, `3:Drive & Compare`, `4:Report`, plus `TaskCreate` in phase order first (`$HOME/.claude/multi-agent-refs/tracker-contract.md`).
 
-Collect ALL captures with no confident Figma match into a single list and ask the user ONCE - never guess, never show a wrong frame. **For each unmatched screen you MUST SHOW its captured live screenshot**, name the screen, and ask for the Figma node-id / URL (in `outputLanguage`). Each answer becomes a confirmed pair. A screen the user declines to map is a skip with reason "no Figma frame supplied".
+Every Phase 0 / Phase 2 decision is a native `AskUserQuestion` per `picker-contract.md` with a `Step <i>/<n>` breadcrumb; confirm even a single option; never inherit state from a previous run.
 
-### 3.4 Compare ALL pairs in one pass
+## Phase 0 - Init, feasibility gate, inventory
 
-`design_visual_compare` per pair (matched + user-supplied) with `tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0`. **Bottom sheets, modals, and any partial overlay need region alignment** (`live_region` from the sheet container in `design_ui_geometry`, never a guess, plus `expected_region` from the Figma placement). Attach Code Connect refs (best-effort); compose a paste-ready fix prompt. Full procedure (match, batch-ask mechanics, compare call, region alignment): `$HOME/.claude/multi-agent-refs/design-check/compare.md`. Read it for Phase 3.2-3.4.
+Read `$HOME/.claude/multi-agent-refs/design-check/mcp-currency-gate.md` for step 0 and `$HOME/.claude/multi-agent-refs/design-check/init-inventory.md` for steps 1-9.
 
-**Edge insets are defects, not tolerances.** Report every `inset` finding as a deviation with its px delta; never absorb a side gap as "close enough", never raise `tolerance_px` to make one disappear.
+0. **MCP currency gate** before anything expensive: session stale or disk stale: **HALT** (reconnect, or update the checkout). Never substitute a local `node` call for a missing tool.
+1-3. Repo picker, module picker, platform detect.
+4. **Mock feasibility** (`design_mock_detect`): `false`: offer the **snapshot lane** (`captureLane = "snapshot"`, no in-app flips), declined or not renderable: **HALT** with `reason`, never fabricate a comparison. `"debug-only"`: warn, Continue / Cancel. `true`: persist `state.designCheck.mock`.
+5. **Scenario inventory** (`design_scenario_inventory`) is the target set; persist verbatim. `truncated: true`: say so and pass `coverage.truncatedInventory: true` in Phase 4. `targetCount: 0`: only the default launch state is auditable. List `ignored[]`.
+6-7. Scope resolve, `--resume`; confirm only above `coverage.confirmAbove` relaunches, as a cost estimate, never offering a smaller scope.
+8-9. Report dir now; worktree `{projectRoot}/.worktrees/DC-<shortId>`, never under $HOME.
 
-### 3.5 Close the ledger
+## Phase 1 - Build & launch
 
-Every scoped target id must end in exactly one bucket:
+Debug build in the worktree, launch via `design_mock_launch`; Phase 3 relaunches, never rebuilds. Read `$HOME/.claude/multi-agent-refs/design-check/build-launch.md` for Phase 1.
 
-- **covered** - captured AND compared (or captured and explicitly awaiting a Figma frame the user declined to supply, which is a skip)
-- **skipped** - with a concrete reason recorded in 3.1 / 3.3
+## Phase 2 - Figma mapping
 
-Write `run-state.json` into the Phase 0 report dir with `{ targetIds, covered, skipped }` so `--resume` can pick up the remainder. An id in neither bucket is a bug in this phase, and Phase 4's gate will fail the run for it.
+The only Figma discovery; later only a node the user hands over in 3.3. **Ambiguous or unmatched: defer to 3.3, never guess.** Read `$HOME/.claude/multi-agent-refs/design-check/figma-mapping.md` for Phase 2.
 
-Before leaving this phase, compare `covered.length + skipped.length` against `scope.targetIds.length`. A mismatch is a set of targets nobody decided about - go back and drive them, or record why they cannot be driven. Reaching Phase 4 with a mismatch is the worst of both worlds: the work is undone AND the run is marked incomplete.
+## Phase 3 - Drive, capture, match, compare
 
-## Phase 4 - Report, coverage gate & export
+Iterate `scope.targetIds`; done when every id is resolved, not when taps run out. Before the first compare, read `$HOME/.claude/multi-agent-refs/features/design-conformance.md`.
 
-1. **Output dir**: `state.designCheck.reportDir` from Phase 0; never a second timestamped dir.
-2. **Assemble** the report object: `coverage` (scoped `targets`, `covered`, `skipped` with reasons, `truncatedInventory`, optional `floor`) and per-variant results with a `walk` block (`components`, `converged`, `didNotConverge`, `notVerified`). `walk` 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 - list the skip. Pass **ids**, not counts.
-3. **Render + export** with `design_report` (`html` + `pdf`, + `confluence` only when enabled; disabled → graceful skip). Full procedure (report object, export formats, cleanup): `$HOME/.claude/multi-agent-refs/design-check/export.md`. Read it for Phase 4.
-4. **COVERAGE GATE (blocking, not advisory)** - read `coverage` from the tool result and persist it to `state.designCheck.coverage`:
-   - `gate: "pass"` → report per-variant PASS/FAIL + findings count + report paths.
-   - `gate: "fail"` → the run is **INCOMPLETE**. Print `coverageError`, the `unaccountedIds`, and the exact command that closes the gap: `/multi-agent:design-check --resume`. Do not present an incomplete audit as a finished one, do not bury the miss in a footnote, and never pad the covered list to make the gate pass.
+- **3.1** Drive `inventory.plan` batch by batch; persist `state` and `run-state.json` after every capture. Unreachable: skip with a concrete reason. Read `$HOME/.claude/multi-agent-refs/design-check/drive-capture.md`.
+- **3.2-3.4** Confident matches only; batch-ask everything unmatched ONCE, showing each live screenshot; compare all pairs (`tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0`), sheets and modals with region alignment. **Edge insets are defects**: never raise `tolerance_px` to hide one. Read `$HOME/.claude/multi-agent-refs/design-check/compare.md`.
+- **3.5** Every id ends covered or skipped; `covered + skipped` must equal `targetIds` before Phase 4.
 
-   The gate is a last line of defence, not the plan. If it fires, Phase 3 left work undone - the correct response is to drive the missing targets, and only then to report.
-5. Remove the worktree unless the user asked to keep the built app. The report dir is never removed.
+## Phase 4 - Report and coverage gate
 
-## Notes
+Use `state.designCheck.reportDir`. Pass ids, not counts; each variant carries `walk` with `didNotConverge` and `notVerified`. Export with `design_report` (Confluence only when enabled). Read `$HOME/.claude/multi-agent-refs/design-check/export.md` for Phase 4.
 
-- **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 pipeline 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.
+**Coverage gate (blocking)**: `pass`: report results and paths. `fail`: the run is **INCOMPLETE**; print `coverageError`, `unaccountedIds` and `/multi-agent:design-check --resume`. Never pad the covered list. Remove the worktree unless asked to keep it; never the report dir.

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

@@ -13,15 +13,14 @@ confirm: required
 
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
-Each run writes ephemeral scratch under `/tmp`: picker state
-(`multi-agent-picker-*`), PR/review diffs (`multi-agent-review-*`), issue
-progress bodies (`issue-progress-*`), channel payloads (`channels-*`),
-external-context bundles (`context-links-*` / `context-by-type-*`), and analysis
-drafts (`analysis-*`). Most are never cleaned up, so a long-lived machine
-accumulates them. This sweeps the known prefixes only.
+Sweeps run scratch under `/tmp` (known prefixes only), worktree residue,
+offloaded payloads and, with `--abandoned`, stopped runs. Backed by
+`$HOME/.claude/scripts/gc-tmp.sh` and its siblings. Safe by default: it previews
+and deletes nothing until you confirm.
 
-Backed by `$HOME/.claude/scripts/gc-tmp.sh`. Safe by default: it previews and
-deletes nothing until you confirm.
+What each phase covers, the abandoned-run line kinds and the scope of each
+phase: `$HOME/.claude/multi-agent-refs/garbage-collect/phases.md`. Read it when
+explaining a phase's output.
 
 ## Steps
 
@@ -63,13 +62,8 @@ deletes nothing until you confirm.
    bash $HOME/.claude/scripts/gc-worktrees.sh ${ARGUMENTS}
    ```
 
-   This covers: stale worktree admin entries (`git worktree prune`, applied
-   immediately  -  it only drops bookkeeping for dirs that are already gone),
-   orphan `.worktrees/*` dirs no longer registered as worktrees, gitlink
-   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:resume` / `/multi-agent:kill`.
+   Registered, healthy worktrees are NEVER touched  -  those belong to
+   `/multi-agent:resume` / `/multi-agent:kill`.
 
    - Output says `nothing to do` -> skip silently, no question.
    - Otherwise surface a second `AskUserQuestion` (in `outputLanguage`):
@@ -86,13 +80,8 @@ deletes nothing until you confirm.
    bash $HOME/.claude/scripts/gc-refs.sh ${ARGUMENTS}
    ```
 
-   `offload-ref.sh` parks build logs, diffs and test output under
-   `.multi-agent/refs/<node_id>.md`. In worktree modes that directory dies with
-   the worktree; when the run chose a local workspace it lands in the real checkout, and
-   because it is gitignored it never shows up in `git status`. Only files
-   matching the node-id shape are touched  -  anything else in that directory is
-   left alone, and files inside the grace window are spared so a sweep cannot
-   pull a ref out from under a running phase.
+   Only node-id-shaped files under `.multi-agent/refs/` are touched, and files
+   inside the grace window are spared.
 
    - Output says `nothing to do` -> skip silently, no question.
    - Otherwise surface a third `AskUserQuestion` (in `outputLanguage`):
@@ -112,25 +101,15 @@ deletes nothing until you confirm.
    bash $HOME/.claude/scripts/gc-abandoned.sh ${ARGUMENTS}
    ```
 
-   Nothing else collects these. `gc-worktrees.sh` skips registered worktrees on
-   purpose, because a registered worktree belongs to a live run - and a run that
-   stopped never stops being "live". Measured on one machine: 20 runs reading
-   `in_progress`, every one over a day old, one of them 157 days.
+   The four line kinds (`would remove`, `would stash`, `would mark abandoned`,
+   `unattributed`) are not interchangeable; their table is in `phases.md`. An
+   `unattributed` worktree is **never removed, whatever the flags**: report the
+   list and its size; the user decides.
 
-   The output has four kinds of line and they are not interchangeable:
-
-   | Line | Meaning |
-   |---|---|
-   | `would remove` / `would remove worktree` | reapable: stopped past its age limit, or finished with its worktree left behind |
-   | `would stash` | uncommitted work found - it goes into a stash entry labelled `autopilot/abandoned/<task-id>` (`git stash list`) and the worktree is **kept** |
-   | `would mark abandoned` | the state is stale but there is no worktree left to remove |
-   | `unattributed` | a worktree with no run state. **Never removed, whatever the flags.** `.worktrees/` is not exclusively ours, and nothing distinguishes a hand-made worktree from a pipeline one whose log was pruned. Report the list and its size; the user decides |
-
-   Three rules hold with or without `--yes`, and they are why this is safe to
-   offer: a run waiting on you (open PR, Phase 4/5, `awaiting_input`) is never
-   touched; a path outside `<repo>/.worktrees/` is never removed, which matters
-   because four state files on the measured machine record the REPO ROOT as
-   their `worktreePath`; and uncommitted work is stashed rather than lost.
+   Three rules hold with or without `--yes`: a run waiting on you (open PR,
+   Phase 4/5, `awaiting_input`) is never touched; a path outside
+   `<repo>/.worktrees/` is never removed; and uncommitted work is stashed rather
+   than lost.
 
    - Output says `nothing to do` -> skip silently, no question.
    - Otherwise surface a fourth `AskUserQuestion` (in `outputLanguage`):
@@ -147,11 +126,6 @@ deletes nothing until you confirm.
   and `/multi-agent:resume` re-uses them. If a run is paused at
   `awaiting_output_decision`, pass `--older-than=<minutes>` so fresh drafts are
   spared, or finish the run first.
-- The /tmp phase only touches `/tmp` scratch; the worktree phase only touches
-  the current repo's `.worktrees/` residue and index; the payload phase only
-  touches node-id files under `.multi-agent/refs/`. Persistent per-task logs
-  live under `~/.claude/logs/multi-agent/` and are cleaned by
-  `/multi-agent:prune-logs`. The per-repo memory stores under
-  `~/.claude/memory/multi-agent/` are durable knowledge, not scratch: they are
-  removed only by `/multi-agent:uninstall --all-data`, or one entry at a time
-  with `learnings-ledger.mjs forget`.
+- Per-task logs (`/multi-agent:prune-logs`) and the per-repo memory stores
+  (`/multi-agent:uninstall --all-data`) are never swept here; see `phases.md`,
+  "Scope of each phase".