@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

package/pipeline/multi-agent-refs/refactor/sweep.md

@@ -0,0 +1,190 @@
+# Refactor sweep: research, scan, analysis, scoring and plan detail
+
+<!-- toc -->
+- [Plan bands](#plan-bands)
+- [Step 0: best-practices research](#step-0-best-practices-research)
+- [Step 0c: why the toolkit is in scope](#step-0c-why-the-toolkit-is-in-scope)
+- [Step 0e: why a backlog band](#step-0e-why-a-backlog-band)
+- [Step 1: scan checklist](#step-1-scan-checklist)
+- [Step 2a: the 10 categories](#step-2a-the-10-categories)
+- [Step 2b: bug hunt](#step-2b-bug-hunt)
+- [Step 3: score table](#step-3-score-table)
+- [Step 4: plan table](#step-4-plan-table)
+- [Step 6: per-item loop](#step-6-per-item-loop)
+- [Step 7: verify commands](#step-7-verify-commands)
+- [Focus filter](#focus-filter)
+<!-- /toc -->
+
+Reference for `/multi-agent:refactor`. The command file carries the step skeleton and its hard rules; this file carries the procedures, output tables and catalogs each step points at.
+
+## Plan bands
+
+All bands feed the single Step 4 table:
+
+- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
+- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
+- **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
+- **D - Drift**: upstream updates to skills we derived from an external source.
+- **E - Dev-toolkit**: current-practice gaps in the companion multi-agent-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
+- **F - Run-errors**: recurring real failures the pipeline actually hit across past runs, read from the local run-error ledger. These are lived evidence, not speculation - a failure that recurs across users or tasks is a prioritized improvement area.
+- **G - Backlog**: open observations recorded mid-task (Step 0e).
+
+## Step 0: best-practices research
+
+The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
+
+1. **Identify the domain** of the current project (read README + package/build manifests): what kind of project is it (CLI, SDK, app, pipeline, library), what stack, who uses it.
+2. **Research the best-in-class** for that exact domain. When `ai-analyst-toolkit` is enabled, run the first three bullets through its skills (`evidence-github`, `evidence-registry`, `signal-community`) rather than ad-hoc searching: they carry the query forms and the citation format, and they keep the evidence / signal line straight - a GitHub PR is a fact, a forum thread is one person's experience. Not enabled is a recorded no-op and the manual searches below still apply.
+   - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
+   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners and tool authors actually recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
+   - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
+   - **Web**: "<domain> best practices <current-year>", official style guides, and the platform's own guidance.
+3. **For each candidate approach, record**:
+   - what it is, who does it well (source link)
+   - the concrete benefit
+   - **adaptation**: exactly how it would look in OUR repo (which file/dir/script), and what has to change for it to fit - not a generic "add tests" but "add a flow-assertion helper in `test/helpers/`"
+   - effort (Low/Med/High) and impact (Low/Med/High/Critical)
+4. **Discard** approaches that do not fit our stack, our scale, or our constraints - and say WHY (so the user sees the filter working, not just the survivors).
+
+Output (plan band A):
+
+```
+| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
+|--------|----------|------------------------|--------|--------|----------|
+| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
+| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
+```
+
+Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.
+
+## Step 0c: why the toolkit is in scope
+
+The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`multi-agent-toolkit-mcp`): Phase 3 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. The procedure is `refactor/toolkit-research.md`.
+
+## Step 0e: why a backlog band
+
+Every other band derives its findings from scratch, which is right for a sweep and has one consequence: a friction noticed mid-task is gone by the next run unless it was fixed within the hour. Most are not, because stopping mid-task to fix them is the wrong call. So they are written down when noticed and decided here. Sibling surfaces matter because a command is authored in `commands/`, mirrored into `skills/shared/core/`, and installed again into three host trees, so a fix applied to one copy drifts from the rest with every gate still green.
+
+## Step 1: scan checklist
+
+```
+- file count, LOC (cloc or wc -l)
+- package.json / Package.swift / build.gradle analysis
+- dependency count (runtime vs dev)
+- Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
+- Is there test infrastructure? How many tests? Coverage?
+- Is a linter/formatter config in place?
+- Do README, LICENSE, SECURITY.md, CHANGELOG.md exist?
+- Git state: branch count, last commit date, tags
+```
+
+## Step 2a: the 10 categories
+
+| # | Category | What to check |
+|---|----------|---------------|
+| 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
+| 2 | **Code Quality** | Naming, magic numbers, dead code, complexity, DRY |
+| 3 | **Security** | Hardcoded secrets, input validation, Keychain, ATS, ATT |
+| 4 | **Tests** | Coverage, test pyramid, edge cases, mock/stub quality |
+| 5 | **CI/CD** | Build matrix, lint job, release automation, artifact caching |
+| 6 | **Docs** | README quality, JSDoc / Swift docs, API docs, CHANGELOG |
+| 7 | **Performance** | Bundle size, lazy loading, memory leaks, unnecessary re-renders |
+| 8 | **Accessibility** | a11y labels, tap targets, VoiceOver, Dynamic Type |
+| 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
+| 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |
+
+## Step 2b: bug hunt
+
+Dispatch focused review agents (Agent tool, `code-reviewer` persona where available) over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries. For each candidate defect, record **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
+
+Output (plan band B) - every confirmed defect becomes a P0/P1 item:
+
+```
+| # | Severity | File:line | Defect | Failure scenario |
+|---|----------|-----------|--------|------------------|
+| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
+```
+
+## Step 3: score table
+
+```
++---------------------+-------+
+| Category            | Score |
++---------------------+-------+
+| Architecture        | 9/10  |
+| Code Quality        | 8/10  |
+| Security            | 9/10  |
+| Tests               | 7/10  |
+| CI/CD               | 8/10  |
+| Docs                | 7/10  |
+| Performance         | 9/10  |
+| Accessibility       | 6/10  |
+| Dependency Mgmt     | 8/10  |
+| DevEx               | 9/10  |
++---------------------+-------+
+| TOTAL               | 80/100|
++---------------------+-------+
+```
+
+## Step 4: plan table
+
+```
+| # | Priority | Band | Category | Item | Impact |
+|---|----------|------|----------|------|--------|
+| 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
+| 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
+| 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
+| 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
+| 5 | P1 | E | Toolkit | Add read-only annotations to the multi-agent-toolkit device tools | Medium |
+| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
+```
+
+Priority levels:
+
+- **P0**: bugs, security holes, broken functionality - must fix
+- **P1**: clear quality improvement or high-value adopted best-practice / drift port - should be done
+- **P2**: nice-to-have - if time allows
+
+## Step 6: per-item loop
+
+1. For each item:
+   - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
+   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d - do not publish from this step.
+   - run the relevant tests
+   - on success, move to the next
+   - on failure, roll back and notify the user
+2. After all changes are done: run the full lint + test suite; on success, commit.
+
+## Step 7: verify commands
+
+```bash
+# Lint
+npm run lint 2>/dev/null || swift build 2>/dev/null
+
+# Test
+npm test 2>/dev/null || swift test 2>/dev/null || xcodebuild test 2>/dev/null
+
+# Result
+echo "Lint: PASS/FAIL"
+echo "Test: PASS/FAIL (X/Y passed)"
+```
+
+If any band-E item was applied, verify the toolkit repo too - syntax check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts (README header, `package.json` description) match the count the server reports.
+
+## Focus filter
+
+| Input | Focus |
+|-------|-------|
+| `backlog` | Backlog band only (band G, Step 0e) |
+| `bugs` | Bug hunt only (band B) |
+| `best-practices` | Field research + adapted plan only (band A) |
+| `drift` | Upstream derived-skill drift only (band D) |
+| `multi-agent-toolkit` | Companion MCP toolkit research + audit only (band E) |
+| `run-errors` | Run-error ledger only (band F) |
+| `security` | Security analysis only |
+| `tests` | Test coverage and quality only |
+| `performance` | Performance optimisation only |
+| `docs` | Docs only |
+| `ci` | CI/CD pipeline only |
+| `deps` | Dependency updates only |
+| (empty) | Everything (default) |

package/pipeline/multi-agent-refs/resume/details.md

@@ -1,6 +1,20 @@
-# Resume  -  Single-candidate escape, answer contract, tail phases, tracker continuation
+# Resume  -  usage, source rows, re-entry, answer contract, tail phases, tracker detail
 
-> Loaded by `resume/SKILL.md`. Read "Single-candidate escape" before Step 1, "Answering a parked question" before Step 5 when `--answer` is given or `waitingFor` is `question`, "Tail phases" before Step 7, and "Continuation path" when a tracker state already exists. The SKILL keeps the routing, the gates and the hard rules. Every picker here follows `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+<!-- toc -->
+- [Single-candidate escape](#single-candidate-escape)
+- [Answering a parked question](#answering-a-parked-question)
+- [Tail phases](#tail-phases)
+- [Continuation path](#continuation-path)
+- [Usage](#usage)
+- [Source rows](#source-rows)
+- [Tracked-run notes](#tracked-run-notes)
+- [Re-entry by waitingFor](#re-entry-by-waitingfor)
+- [Untracked context](#untracked-context)
+- [Tail phase map](#tail-phase-map)
+- [Tracker block](#tracker-block)
+<!-- /toc -->
+
+> Loaded by `resume/SKILL.md`. "Usage" holds the invocation examples, when not to use the command and the modes. Read "Single-candidate escape" and "Source rows" before Step 1, "Tracked-run notes" with Steps 2-3, "Re-entry by waitingFor" before Step 5, "Answering a parked question" before Step 5 when `--answer` is given or `waitingFor` is `question`, "Untracked context" with Step 6, "Tail phases", "Tail phase map" and "Tracker block" before Step 7, and "Continuation path" when a tracker state already exists. The SKILL keeps the routing, the gates and the hard rules. Every picker here follows `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 ## Single-candidate escape
 
@@ -33,3 +47,102 @@ It accepts only one of `options[].id` (comma-separated ids for a multi-select),
 ## Continuation path
 
 **Continuation path (prior state existed):** (1) if Phase 3 was left `in_progress` with `Now: awaiting local test (user)`, mark it `update 3 completed` + `meta 3 Result "local test done (user)"` before this run's own work (it re-opens Phase 3 with `update 3 in_progress` when the Verify gate runs; elapsed keeps the original `started_at`, which is expected); (2) print ONE line in `outputLanguage` summarizing the inherited history, e.g. `Continuing PROJ-12345: phases 0-3 finished earlier (12m, 38.4k tok, ~$0.74)` (USD via `phase-tracker.sh cost total`); (3) `render`.
+
+## Usage
+
+```bash
+/multi-agent:resume                       # list everything resumable, pick one
+/multi-agent:resume #2                    # a tracked run by task number
+/multi-agent:resume PROJ-12345            # a tracked run by Jira id, or bind the tail to that id
+/multi-agent:resume --base develop        # tail path: override the base branch for the diff
+/multi-agent:resume #2 --answer continue  # answer the question the run stopped on, then re-enter its step
+/multi-agent:resume autopilot             # no gate prompts: auto-fix, auto-PR, auto-comment
+```
+
+A single command covers both directions, so the user does not have to know which case they are in before asking.
+
+When NOT to use it:
+
+- The change is not written yet  -  use `/multi-agent`.
+- Only the review is wanted  -  `/multi-agent:review`. Only the report  -  `/multi-agent:channels`. Only device UI testing  -  `/multi-agent:test` / `/multi-agent:manual-test`.
+- The run is abandoned rather than paused  -  `/multi-agent:kill #N`, or `/multi-agent:garbage-collect --abandoned` for the Phase 0 leftovers.
+
+Modes:
+
+- **interactive** (default): stops at the Phase 4 gate when there are blocking/important findings; asks before committing/PR when appropriate.
+- **`autopilot`**: no prompts  -  auto-fix accepted blocking/important findings, auto-commit/push/PR, auto-post the Jira comment.
+
+Examples:
+
+```bash
+/multi-agent "PROJ-12345"                 # a run that stops at the user-test gate
+/multi-agent:resume                        # ... pick it back up from that gate
+
+# ... or, with no run behind it at all:
+# you write the change by hand on bugfix/PROJ-12345-order-filter
+/multi-agent:resume                        # review + build/test + PR + Jira analysis & test scenarios
+```
+
+## Source rows
+
+Source B is offered only when no Source A run owns the branch, otherwise the same work would be offered twice under two different contracts. Labels carry proper nouns verbatim (task id, branch name). A single row still needs a second option because `AskUserQuestion` refuses a call with fewer than two declared options and discards every question batched with it.
+
+## Tracked-run notes
+
+- A worktree removed on purpose (`state.worktreeRemovedAt`) was removed by Phase 4 once the PR opened; the branch is still local and the artefacts live under `state.artifactsPath`. A Phase 5 pause needs no checkout. Ask before moving HEAD because the user may be mid-work on another branch, which is exactly why the removal did not check the branch out.
+- The handoff block carries done / remaining / decisions / open findings and the exact re-entry point (phase + subStep). State is the machine truth; the handoff is the narrative.
+
+## Re-entry by waitingFor
+
+A run that stopped mid-phase to ask a human has `currentPhase` pointing at the phase it is still inside, so resuming past it skips the question permanently.
+
+| `waitingFor` | Re-entry |
+|---|---|
+| `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`); after a research pass that proceeded, re-scored through `research-gate.mjs --recheck` |
+| `user-channels-choice` | Phase 5, the channels multi-select, with the stored `channelsInput` |
+| `local-test` | Phase 3, the user-test gate, with the checkout the gate was waiting on |
+| `attended-reply` | `currentPhase`, at the step that asked for a typed reply: ask it again |
+| `question` | The step `state.pendingQuestion.stepId` names, after the answer is recorded ("Answering a parked question") |
+| absent or `null` | `currentPhase + 1` (same pipeline as the main multi-agent command) |
+
+A `waitingFor` that outlives the question it asked sends every later resume back to the step the user already answered, which is why it is cleared in the same write that records the answer.
+
+## Untracked context
+
+1. **Project + branch:** detect project (cwd), current branch (`git branch --show-current`). No worktree is created; the work is already in this checkout.
+2. **Base + diff:** as resolved in Step 1. Abort with `ERR: no local work to resume on <branch> vs <base>` if the diff went empty between the question and the answer.
+3. **Task binding:** Jira id from the argument, else parsed from the branch name (`bugfix/PROJ-XXXX` / `feature/PROJ-XXXX`); `taskType` inferred from the diff (bugfix/feature/refactor/chore) for the report wording. GitHub issue `#N` from branch or argument when present.
+4. **Prior state (optional):** if a tracker state exists for this branch from an earlier run, load its analysis summary and Jira/issue binding to enrich the report. Never require a prior pipeline run.
+5. Persist state under `$HOME/.claude/logs/multi-agent/{project}/{taskId}/`, the same location every run uses.
+
+## Tail phase map
+
+```
+Phase 0: Init          → project/branch detect, base + diff, Jira id, state (no worktree),
+                         fable slots resolved: `lib/model-dispatch.sh subagent --persona <reviewer|triage>
+                         --default fable` (opus while modelFallback.fableEnabled is false)
+Phase 3: Review        → the Verify gate first (stack-aware build + existing tests; SUCCESS required), then
+                         parallel review + triage on the resolved rungs (Fable + Opus + Sonnet and Fable
+                         triage while the fable rung is on; Opus + Sonnet and Opus triage while it is off)
+Phase 4: Commit        → commit remaining local changes + push + open PR if none exists
+Phase 5: Report        → technical analysis + Jira comment with test scenarios (channels: Jira / PR / Confluence / Wiki)
+```
+
+The missing Plan Approval Gate is the only case where it is absent for a reason other than `autopilot` having nobody to ask.
+
+With the quality gates active the commit hook asks for every required ledger entry, and this path has neither Phase 1 nor Phase 2 to write them, so it writes them itself:
+
+- Phase 0 runs `node "$HOME/.claude/scripts/open-questions-gate.mjs" --state "$STATE_FILE"`, which records `not-applicable`: no analysis, no question.
+- The Verify gate runs the Phase 2 exit gates of `features/unattended-gates.md` on the build and test logs it captured, with `--base "$(git merge-base "$BASE" HEAD)"` for `test-strength.mjs` and `symbol-existence-gate.mjs` so the branch's commits count as the change.
+- Phase 4's `plan-coverage-gate.mjs` records `not-applicable`: the run has no Plan phase.
+
+## Tracker block
+
+The full tail tracker sequence, with the reason `init` is conditional: a task handed off from the user test inside Phase 3 ("awaiting local test") keeps its full phase 0-2 history (elapsed, tokens, USD), so `init` runs only when no prior state exists, and `add` is idempotent (existing phases keep their history).
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped   # every phase boundary
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]                   # after every LLM call
+```
+
+On Claude Code, capture each `taskId` from `TaskCreate` and persist it via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, then flip status with `TaskUpdate` at each boundary. Out-of-order TaskCreate scrambles the tile stack. On continuation, rebuild the FULL TaskList from the state file (completed tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta. Copilot CLI / plain shell have no TaskList widget: `phase-tracker.sh render` prints the bordered ANSI phase table as the last tool result.

package/pipeline/multi-agent-refs/review/inputs.md

@@ -1,6 +1,38 @@
 # Review  -  PR picker and diff fetch (Steps 1a and 2)
 
-> Loaded by `review/SKILL.md` Steps 1a and 2. The SKILL keeps when each step runs, the autopilot fallback and the per-PR loop; this file carries the list commands, the picker fields and the per-provider fetch commands.
+<!-- toc -->
+- [Step 1  -  Parse the input](#step-1---parse-the-input)
+- [Step 1a  -  No-input PR picker](#step-1a---no-input-pr-picker)
+- [Step 2  -  Fetch the diff](#step-2---fetch-the-diff)
+- [Input matrix](#input-matrix)
+<!-- /toc -->
+
+> Loaded by `review/SKILL.md` Steps 1, 1a and 2. The SKILL keeps when each step runs, the autopilot fallback and the per-PR loop; this file carries the input parser, the list commands, the picker fields and the per-provider fetch commands.
+
+## Step 1  -  Parse the input
+
+```bash
+# Pseudocode  -  orchestrator implements this:
+input="$ARGUMENTS"
+case "$input" in
+  "")                              kind=pick   # interactive: go to Step 1a PR picker; autopilot/no-PRs falls back to branch (see 1a)
+                                   ;;
+  https://github.com/*/pull/*)     kind=pr; provider=github; org_repo=<extracted>; pr_number=<extracted> ;;
+  https://bitbucket.*/projects/*/repos/*/pull-requests/*)
+                                   kind=pr; provider=bitbucket-server
+                                   bb_server_host=<extracted host>
+                                   bb_project_key=<extracted KEY>
+                                   bb_repo_slug=<extracted slug>
+                                   pr_number=<extracted N>
+                                   ;;
+  *#[0-9]*)                        kind=pr; provider=github; org_repo="${input%%#*}"; pr_number="${input##*#}" ;;
+  '#'[0-9]*)                       kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="${input#'#'}" ;;
+  [0-9]*)                          kind=pr; provider=github; org_repo=$(gh repo view --json nameWithOwner -q .nameWithOwner); pr_number="$input" ;;
+  *)                               kind=branch; provider=local; ref="$input" ;;
+esac
+```
+
+Autopilot with no ref goes straight to branch mode (`kind=branch; provider=local; ref=$(git rev-parse --abbrev-ref HEAD)`) so nothing prompts. When `provider=github`, Step 2 also persists `agent-state.review.headCommitSha`  -  GitHub inline-comment posts (`POST /repos/{o}/{r}/pulls/{n}/comments`) require `commit_id`. Bitbucket Server's anchor API does not.
 
 ## Step 1a  -  No-input PR picker
 

package/pipeline/multi-agent-refs/review/module-guides.md

@@ -1,6 +1,6 @@
 # Review  -  Module review guide discovery (Step 2b)
 
-> Loaded by `review/SKILL.md` Step 2b. The SKILL keeps what a guide is, the reviewer-prompt injection and the scope rule; this file carries the discovery walk and the PR-mode probe.
+> Loaded by `review/SKILL.md` Step 2b. The SKILL keeps what a guide is and the scope rule; this file carries the discovery walk, the PR-mode probe and the reviewer-prompt injection block.
 
 ```bash
 # Changed file paths from the patch:
@@ -23,3 +23,11 @@ done < /tmp/multi-agent-review-${TASK_ID}-paths.txt
 ```
 
 Existence checks are resolved against the local checkout when the cwd is the target repo. In PR mode without a local checkout, probe the candidate paths via the provider API instead (`gh api /repos/{o}/{r}/contents/{path}?ref={headSha}` / Bitbucket `GET /projects/{KEY}/repos/{slug}/browse/{path}?at={headSha}`) and fetch the matching files' raw content the same way. No hit → step is a silent no-op.
+
+## Reviewer-prompt injection
+
+Persist `agent-state.review.moduleGuides = [<repo-relative paths>]` and inject this block into every reviewer prompt (Step 3):
+
+> MODULE REVIEW GUIDES: before reviewing, read each of these guide files. Apply a guide's rules/checklist to every changed file under its directory. Guide violations are findings like any other  -  triage them by severity.
+
+Scope: a guide governs only files under its own directory  -  a guide found under one module must not be applied to a sibling module's changes in the same PR.

package/pipeline/multi-agent-refs/review/panel.md

@@ -0,0 +1,75 @@
+# Review  -  reviewer panels, store compliance, summary and posting (Steps 3, 4, 6, 7)
+
+> Loaded by `review/SKILL.md` and the Copilot `multi-agent-review` skill. The SKILL keeps the fable-rung resolution, the decision rule and the posting defaults; this file carries the per-host model panels, the store-compliance triggers, the chat summary template, the post prompt and the provider endpoints.
+
+## Reviewers
+
+Every host runs three reviewers; only the second slot differs, because GPT-5.4 exists on Copilot and Codex but not on Claude Code, where Opus fills it.
+
+**Claude Code (3 in parallel while the fable rung is on, 2 while it is off):**
+- Agent 1: `claude-fable-5-1` → security + architecture (only when `REVIEW_RUNG` is `fable`)
+- Agent 2: `claude-opus-5-5` → edge cases, alternate perspective
+- Agent 3: `claude-sonnet-5-5` → general quality
+
+**Copilot CLI (3 in parallel):**
+- Agent 1: `claude-opus-4.7` → security + architecture (Fable is not offered on Copilot CLI)
+- Agent 2: `gpt-5.4` → edge cases, alternate perspective
+- Agent 3: `claude-sonnet-4.6` → general quality
+
+**Codex CLI (3 in parallel, single vendor):**
+- Agent 1: `gpt-5.6` @ `xhigh` → security + architecture
+- Agent 2: `gpt-5.4` @ `high` → edge cases, alternate perspective
+- Agent 3: `gpt-5.6` @ `medium` → general quality
+
+When `REVIEW_RUNG` is anything but `fable`, Agent 1 is dropped on Claude Code and the panel is Agent 2 + Agent 3.
+
+## Store compliance
+
+| Platform | Trigger files | Catalog |
+|---|---|---|
+| iOS | `**/Info.plist`, `**/PrivacyInfo.xcprivacy`, `**/*.entitlements`, `**/*App.swift`, `**/AppDelegate*.swift`, `**/SceneDelegate*.swift`, `**/project.pbxproj` | `$HOME/.claude/skills/apple-archive-compliance/SKILL.md`  -  18 rules + ITMS refs |
+| Android | `**/AndroidManifest.xml`, `**/build.gradle(.kts)`, `**/proguard-rules.pro`, `**/network_security_config.xml` | `$HOME/.claude/skills/google-play-compliance/SKILL.md`  -  21 rules + Play policy refs |
+
+Each finding gets the `ruleID` from the catalog plus the platform policy ref:
+- iOS: `(apple-archive-compliance / info-plist  -  Guideline 5.1.1)`
+- Android: `(google-play-compliance / dangerous-permissions  -  Policy  -  Permissions)`
+
+## Summary
+
+```
+🔍 Review Complete  ·  PR #1250  ·  3 files +120 -45
+| Model    | Verdict   | Blocking | Important | Suggestion |
+|----------|-----------|----------|-----------|------------|
+| Fable    | approved  | 0        | 1         | 3          |
+| Opus     | approved  | 0        | 2         | 2          |
+| Sonnet   | rejected  | 1        | 2         | 5          |
+
+Consensus: ⚠ DISAGREEMENT  -  see triage
+```
+
+One row per reviewer that ran: Fable + Opus + Sonnet on Claude Code (Opus + Sonnet while the fable rung is off), Opus + GPT-5.4 + Sonnet on Copilot CLI, the three GPT rows on Codex CLI. The chat is the live conversation; on the PR side, the durable artifacts are inline comments + the review state (Step 7).
+
+## Posting
+
+Optional opt-out prompt (interactive mode only; autopilot skips and posts):
+
+```
+question (outputLanguage): "PR #{N} için review action gönderilsin mi?"
+header   (English):        "Post review"
+options (label + description in outputLanguage; semantics, not literals):
+  - option 1  -  "Post review": inline comments + Request changes when there are
+                 findings, Approve when there are none
+  - option 2  -  "Chat only": leave the PR untouched, the chat summary is enough
+default: option 1
+```
+
+`post-pr-review.sh` reads `agent-state.review.{input, findings, iterationNumber, headCommitSha}`, decides APPROVE vs NEEDS_WORK from the decision rule, posts one inline comment per accepted blocking + important finding (in `outputLanguage`), then sets the review state via the provider's API:
+
+| Provider | Inline comment | State |
+|---|---|---|
+| `github` | `gh api -X POST /repos/{o}/{r}/pulls/{n}/comments` (path + line + commit_id) | `gh pr review --approve` / `--request-changes` |
+| `bitbucket-server` | `POST /pull-requests/{n}/comments` with `anchor: { path, line, lineType:"ADDED", fileType:"TO" }` | `PUT /pull-requests/{n}/participants/{user}` body `{"status":"APPROVED"}` or `{"status":"NEEDS_WORK"}` |
+
+If a finding's `line` lies outside the diff or `headCommitSha` is missing, the comment falls back to a top-level PR comment with the same body.
+
+If the post fails (network, token, harness block), `post-pr-review.sh` exits non-zero and surfaces the failing endpoint on stderr  -  the chat summary remains the source of truth. The script reads `agent-state.review` and handles finding render, comment posts and review state end-to-end.

package/pipeline/multi-agent-refs/review/valven.md

@@ -1,6 +1,6 @@
 # Review  -  Valven delivery-rule gate (Step 2c)
 
-> Loaded by `review/SKILL.md` Step 2c. The SKILL keeps the not-measured rule and the NEEDS WORK rule; this file carries the per-input gate arguments, the checkout-vs-diff-file choice, and the handling of every rule family. Rule definitions: `$HOME/.claude/multi-agent-refs/features/valven.md`.
+> Loaded by `review/SKILL.md` Step 2c. The SKILL keeps the not-measured rule and the NEEDS WORK rule; this file carries the Step 6 summary lines, the per-input gate arguments, the checkout-vs-diff-file choice, and the handling of every rule family. Rule definitions: `$HOME/.claude/multi-agent-refs/features/valven.md`.
 
 ```bash
 VG_FILE="/tmp/multi-agent-review-${TASK_ID}-valven.json"
@@ -40,3 +40,7 @@ VG_RC=$?   # 0 clean, 1 findings, 2 could not run
 - When `VLV-AGE-01`, `VLV-BEHIND-01` or `VLV-TRACE-03` fires and a checkout exists, put the `valven-port.mjs` plan (same base and head, no `--apply`) in the finding's `fix` as `$HOME/.claude/multi-agent-refs/features/valven.md`, "Old work", lists it.
 - The registry's judgement rules (`rules:` block: `VLV-SCOPE-02`, `VLV-PRDESC-02`) go into every reviewer prompt in Step 3, with the PR body when one exists. Each reviewer returns a verdict per ID.
 - `VLV-CYCLE-01..03` are `suggestion` findings with a Valven score and never set NEEDS WORK alone; `VLV-PICKUP-01` is `important` for no reviewer, a `suggestion` for an old draft. Branch input reports them `not-measured`.
+
+## Summary lines
+
+Step 6 adds one line under the table: `Valven: <n> finding(s)  ·  <changedLines> lines / <fileCount> files  ·  split: <yes N slices|no>`, plus for a PR `Valven scores: churn · coding · pickup · review` from the report's `scores` (`-` where one is missing).

package/pipeline/multi-agent-refs/setup/hooks-and-plugins.md

@@ -4,6 +4,8 @@
 
 ## Step 8  -  Hook merge rules
 
+The template carries three blocking `PreToolUse` gates (secret scan, agent-guard, read-size), non-blocking hooks on `PreCompact`, `SessionEnd`, `SessionStart` and `PostToolUse`, and a `Stop` hook (`run-stop-guard.sh`) that holds a session from stopping mid-run. What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`. Copilot CLI gets no hook: it discards `postToolUse` output as of 1.0.45.
+
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object (merging `PreToolUse` alone drops the capture hooks); keep existing hooks, never duplicate a matcher calling the same script.
 - Say only the three gates are hookable (no run-specific arguments); the rest are phase-enforced.
@@ -19,3 +21,5 @@ Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
 stack-specific. **No marker matched is an answer** - those two, not a guess.
 A name the marketplace does not carry is dropped with `dropped[]` naming it,
 so a toolkit that was never shipped is caught before it fails to load.
+
+The marketplace repo name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork, and nothing in the pipeline is coupled to a specific account.

package/pipeline/multi-agent-refs/setup/token-save-flow.md

@@ -4,6 +4,7 @@
 - [Token Save Flow (reusable)](#token-save-flow-reusable)
 - [Step 3.5  -  Host Prompt (embedded in Token Save Flow)](#step-35---host-prompt-embedded-in-token-save-flow)
 - [Step 3.7  -  Repository read binding (embedded in Token Save Flow)](#step-37---repository-read-binding-embedded-in-token-save-flow)
+- [Sequential onboarding loop (Step 3)](#sequential-onboarding-loop-step-3)
 - [Identity learning (Step 3)](#identity-learning-step-3)
 - [Inline Token Save Pattern](#inline-token-save-pattern)
 <!-- /toc -->
@@ -226,6 +227,18 @@ Save the answer, lowercased, to `prefs.global.credentialHosts.{logical-key}`
 (an array of hostnames). Empty leaves the key unbound. `/multi-agent:setup hosts`
 re-opens it.
 
+## Sequential onboarding loop (Step 3)
+
+The Step 2 discovery summary is never the end of setup. Immediately after showing it, walk the missing services one by one in the fixed order the setup SKILL lists, and run the Token Save Flow for each.
+
+- **One prompt per service.** Never collapse the list into a single "add missing tokens now?" yes/no, and never offer one multi-select covering all services: each service has its own source URL, key name, identity binding and host prompt, so each gets its own Token Save Flow pass.
+- **Each service pass asks, in order: token, author, host, read binding (GitHub, Bitbucket; Step 3.7).** Step A/B collect the secret, Step C binds the git identity (author) - Bitbucket and GitHub included; every saved token gets an author - and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog), plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
+- **Skip is per-service.** A Skip answer leaves that service's `keychainMapping` at `null` and the loop continues with the next service. Skips never abort the loop.
+- **`figma` and `figma_mcp` are distinct credentials for distinct tiers: ask both.** Skipping the PAT does not imply skipping MCP, and vice versa. The `figma_mcp` pass opens with a Remote / Local mode question instead of a clipboard paste (`setup/figma.md`): Remote generates a `figu_` OAuth token for the current user, Local wires the PAT-based local server.
+- The loop ends only when every missing service has been asked exactly once; then continue to Step 4 (Verify all).
+
+Every token is optional in the sense that every service can be answered with Skip, but the asking is not optional. Phase 0 re-asks at runtime only for tokens the user skipped here.
+
 ## Identity learning (Step 3)
 
 Each token save triggers an identity prompt:

package/pipeline/multi-agent-refs/stack/background.md

@@ -0,0 +1,72 @@
+# stack: background and examples
+
+Read by `/multi-agent:stack` when the user asks how stack selection works, what
+an argument enables, or why the plugin map is derived.
+
+## How hosts receive stack skills
+
+On Claude Code the marketplace plugins are the ONLY source of stack skills -
+nothing is copied into `~/.claude/skills`. A stack that is not enabled is simply
+absent from the session. Copilot CLI and Codex CLI have no plugin loader; they
+receive a local copy filtered to the enabled stacks at install time, which is why
+the command offers to refresh those copies after a change.
+
+Enablement is declarative, per-repo and versioned. There is no SessionStart hook
+and no directory shuffling; the old `stack-swap.sh` mechanic is gone.
+
+## Usage examples
+
+```bash
+/multi-agent:stack                 # no arg -> native multi-select picker (current state pre-noted)
+/multi-agent:stack ios             # SwiftUI toolkit + common
+/multi-agent:stack ios backend     # any combination, space-separated
+/multi-agent:stack android         # Compose toolkit + common
+/multi-agent:stack mobile          # alias: ios + android + common
+/multi-agent:stack backend         # Python / Node spec-driven toolkit + common
+/multi-agent:stack web             # React / TSX toolkit + common (alias: frontend)
+/multi-agent:stack fullstack       # alias: web + backend + common
+/multi-agent:stack all             # all four stack toolkits + common
+```
+
+## Why the map is derived
+
+`pluginsForStacks()` in `scripts/_stack-routing.mjs` owns the stack to plugin
+map, and the command carries no copy: every hand-written copy is a chance to get
+the one asymmetry wrong - the detector says `web`, the marketplace ships
+`ai-frontend-toolkit`. To preview what a set of arguments enables:
+
+```bash
+node -e 'import(process.env.HOME+"/.claude/scripts/_stack-routing.mjs").then(m=>{
+  const st=process.argv.slice(1).flatMap(a=>m.expandStackArg(a));
+  if(!st.length){console.error("Unknown stack. One of: "+m.KNOWN_STACKS.join(" ")+" mobile fullstack all");process.exit(1);}
+  const r=m.pluginsForStacks(st);
+  if(r.dropped.length) console.error("not in the marketplace, dropped: "+r.dropped.join(" "));
+  console.log(r.plugins.join(" "));
+})' "$@"
+```
+
+`ai-common-toolkit` and `ai-analyst-toolkit` are in every answer, including the
+empty one. Multiple args union their sets, and the aliases (`frontend`,
+`mobile`, `fullstack`, `all`) expand in the module so `/multi-agent:stack
+mobile` cannot mean one thing here and another in the installer.
+
+The marketplace suffix is appended inside node, not in the shell: `$ON` is a
+single string, and re-splitting it in zsh to suffix each name suffixes the whole
+string, not each word.
+
+## Apple's Xcode skills
+
+Apple's skills (`xcode-integration@xcode-apple`, linked by the installer from
+this Mac's Xcode 27.1+ plugin into `~/.claude/xcode-apple-marketplace`) are the
+reference for iPhone Duo and window resizing, SwiftUI, App Intents and the
+accessibility audits, and they are the first route for those iOS tasks.
+
+## What stack-toggle.mjs does
+
+`stack-toggle.mjs set` applies the write rules (selection `true`, every other
+stack toolkit `false`, `ai-common-toolkit` and `ai-analyst-toolkit` always
+`true`, retired `ai-*-engineering-toolkit` keys deleted,
+`xcode-integration@xcode-apple` following `ios` when the Apple marketplace is
+linked, every other key kept), writes the file atomically and prints the
+resulting `enabledPlugins`. The office panel's `POST /v1/stack` calls the same
+script.