@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

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

@@ -0,0 +1,87 @@
+# 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.
+
+## Step 1a  -  No-input PR picker
+
+**List open PRs across both providers** (a provider contributes nothing if its token/CLI is absent - never hard-fail on one provider):
+
+```bash
+# GitHub: current repo's open PRs + the user's own/requested open PRs across repos.
+gh pr list --state open --json number,title,url,headRefName,author,updatedAt 2>/dev/null   # current repo
+gh search prs --state open --review-requested=@me --json number,title,url,repository,updatedAt 2>/dev/null
+gh search prs --state open --author=@me           --json number,title,url,repository,updatedAt 2>/dev/null
+
+# Bitbucket Server: for each configured bitbucket repo (prefs recentRepos / dev-context),
+# resolve creds via credential-store (see Step 2 bitbucket block) then:
+#   GET https://$host/rest/api/1.0/projects/$KEY/repos/$slug/pull-requests?state=OPEN&role=REVIEWER
+```
+
+Merge into one deduped list, each row labeled with its provider and PR URL; sort by `updatedAt` desc. If the merged list is EMPTY -> tell the user "no open PRs found", fall back to branch mode, and continue.
+
+**Select** - follow `$HOME/.claude/multi-agent-refs/picker-contract.md` (breadcrumb narrator line before the prompt), then `AskUserQuestion` `multiSelect: true`:
+
+```
+question (outputLanguage): "Hangi PR('lar)ı review edeyim?"
+header   (English):        "Review PRs"
+options: one per open PR -> label "#<N> <short title>", description (outputLanguage): "<repo> · <provider> · <headRef>"
+```
+
+Each selected option maps back to a full `agent-state.review.input` descriptor (provider + orgRepo / bb coordinates + prNumber + raw URL), exactly as Step 1 would have parsed an explicit URL. Then **loop Steps 2-7 once per selected PR** (independent review + post each). If the user selects none, fall back to branch mode.
+
+## Step 2  -  Fetch the diff
+
+**branch mode:**
+
+```bash
+git diff origin/develop...{ref}
+```
+
+**pr mode  -  github:**
+
+```bash
+gh pr diff "$pr_number" --repo "$org_repo" > /tmp/multi-agent-review-${TASK_ID}-diff.patch
+# Also capture the head commit SHA for GitHub inline-comment anchors
+# (POST .../pulls/{n}/comments requires commit_id):
+HEAD_SHA=$(gh api "/repos/$org_repo/pulls/$pr_number" --jq .head.sha)
+printf '%s\n' "$HEAD_SHA" > /tmp/multi-agent-review-${TASK_ID}-head.sha
+# Persist into agent-state  -  post-pr-review.sh reads it from there.
+tmp_state=$(mktemp)
+jq --arg sha "$HEAD_SHA" '.review.headCommitSha = $sha' "$AGENT_STATE" > "$tmp_state" \
+  && mv "$tmp_state" "$AGENT_STATE"
+```
+
+**pr mode  -  bitbucket-server:**
+
+```bash
+# Resolve credentials via prefs.global.keychainMapping (never hardcode key names).
+. "$HOME/.claude/lib/credential-store-resolver.sh" \
+  || . "$HOME/.copilot/lib/credential-store-resolver.sh"
+resolve_credential_store
+USER_KEY=$(jq -r '.global.keychainMapping.bitbucket_user' "$HOME/.claude/multi-agent-preferences.json")
+TOKEN_KEY=$(jq -r '.global.keychainMapping.bitbucket_token' "$HOME/.claude/multi-agent-preferences.json")
+BB_USER=$("$CRED_STORE" get "$USER_KEY")
+BB_TOKEN=$("$CRED_STORE" get "$TOKEN_KEY")
+
+DIFF_FILE="/tmp/multi-agent-review-${TASK_ID}-diff.patch"
+http=$(curl -sS -m 60 --config <(printf 'user = "%s:%s"\n' "$BB_USER" "$BB_TOKEN") -H "Accept: text/plain" \
+  "https://$bb_server_host/rest/api/1.0/projects/$bb_project_key/repos/$bb_repo_slug/pull-requests/$pr_number/diff?contextLines=10" \
+  -o "$DIFF_FILE" -w '%{http_code}')
+if [ "$http" != "200" ]; then
+  echo "review: Bitbucket diff fetch failed (HTTP $http)  -  error body in $DIFF_FILE" >&2
+  rm -f "$DIFF_FILE"
+  exit 1
+fi
+```
+
+The `credential-store.sh` wrapper reads the macOS Keychain (`security`).
+
+## Input matrix
+
+| Input | Mode | PR action |
+|---|---|---|
+| no args (interactive) | PR picker (open GitHub + Bitbucket PRs, multi-select) | inline comments + approve/needs-work, per selected PR |
+| no args (autopilot / no PRs) | branch (current) | none  -  chat only |
+| `feature/foo` | branch (named) | none  -  chat only |
+| `#N`, `repo#N`, GitHub PR URL | pr (github) | inline comments + approve/needs-work |
+| Bitbucket Server PR URL | pr (bitbucket-server) | inline comments + approve/needs-work |

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

@@ -0,0 +1,25 @@
+# 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.
+
+```bash
+# Changed file paths from the patch:
+grep -E '^\+\+\+ b/' "$DIFF_FILE" | sed 's|^+++ b/||' | sort -u > /tmp/multi-agent-review-${TASK_ID}-paths.txt
+
+# For each changed path, walk its directory chain up to the repo root and
+# collect guide files matching: CLAUDE.md, *-CLAUDE.md, AGENTS.md.
+# Root-level CLAUDE.md/AGENTS.md are excluded  -  the host CLI already loads those.
+guides=()
+while IFS= read -r p; do
+  d=$(dirname "$p")
+  while [ "$d" != "." ] && [ "$d" != "/" ]; do
+    for g in "$d"/CLAUDE.md "$d"/*-CLAUDE.md "$d"/AGENTS.md; do
+      [ -e "$g" ] && guides+=("$g")
+    done
+    d=$(dirname "$d")
+  done
+done < /tmp/multi-agent-review-${TASK_ID}-paths.txt
+# dedupe, cap at 5 (log any dropped so truncation is never silent)
+```
+
+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.

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

@@ -0,0 +1,42 @@
+# 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`.
+
+```bash
+VG_FILE="/tmp/multi-agent-review-${TASK_ID}-valven.json"
+VG_ARGS=(--mode review --out "$VG_FILE")
+case "$kind/$provider" in
+  branch/local)
+    VG_ARGS+=(--repo . --base origin/develop --head "$ref") ;;
+  pr/github)
+    node "$HOME/.claude/scripts/pr-timeline.mjs" --repo "$org_repo" --pr "$pr_number" \
+      --out "/tmp/multi-agent-review-${TASK_ID}-pr.json"   # gh pr view + ready time + bot-typed reviews
+    jq -r '.body // ""' "/tmp/multi-agent-review-${TASK_ID}-pr.json" > "/tmp/multi-agent-review-${TASK_ID}-body.md"
+    jq -r '.commits[] | "\(.authoredDate)\t\(.messageHeadline)"' "/tmp/multi-agent-review-${TASK_ID}-pr.json" > "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
+    VG_ARGS+=(--branch "$(jq -r .headRefName "/tmp/multi-agent-review-${TASK_ID}-pr.json")"
+              --pr-body-file "/tmp/multi-agent-review-${TASK_ID}-body.md"
+              --commits-file "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
+              --pr-meta-file "/tmp/multi-agent-review-${TASK_ID}-pr.json") ;;
+  pr/bitbucket-server)
+    # Same credentials as Step 2. PR: fromRef.displayId + description; commits: values[].message.
+    # Write the description to ...-body.md, one "<ISO authorTimestamp>\t<first message line>" per commit to ...-commits.txt,
+    # and the timeline to ...-meta.json (features/valven.md, "Development Behaviors"). Then:
+    VG_ARGS+=(--branch "$BB_FROM_REF" --pr-body-file "/tmp/multi-agent-review-${TASK_ID}-body.md"
+              --commits-file "/tmp/multi-agent-review-${TASK_ID}-commits.txt"
+              --pr-meta-file "/tmp/multi-agent-review-${TASK_ID}-meta.json") ;;
+esac
+```
+
+For PR input: when the cwd is a checkout of the same repo, `git fetch origin "<headRef>"` (this moves no HEAD) and add `--repo . --base "origin/<baseRef>" --head FETCH_HEAD`, so sizes and the rework ratio come from history. Otherwise add `--diff-file "$DIFF_FILE"`; the rework rule then reports `not-measured`, which is stated in the summary rather than read as a pass.
+
+```bash
+node "$HOME/.claude/scripts/valven-gate.mjs" "${VG_ARGS[@]}" >/dev/null
+VG_RC=$?   # 0 clean, 1 findings, 2 could not run
+```
+
+- Exit 2: print the stderr line and continue the review with `Valven: not measured (<reason>)` in the Step 6 summary. Never print it as passed.
+- The gate's `findings[]` join the reviewer findings at Step 5 with `tag: valven`. They are measurements, so triage accepts them unless the task is exempt; an accepted `important` or `blocking` one makes the Step 7 decision NEEDS WORK.
+- When `splitRequired` is true, run `node "$HOME/.claude/scripts/valven-split.mjs" --repo . --base "origin/<baseRef>" --head <head>` (plan only, no `--apply`) where a checkout exists, and append the slice table (branch, lines, files) to the `VLV-SIZE-01` finding's `fix`.
+- 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`.

package/pipeline/multi-agent-refs/review-standalone-tracker.md

@@ -0,0 +1,37 @@
+# Standalone review: its own tracker record
+
+A standalone review (the command seeded a `review-` id, so no pipeline run
+owns this session) registers itself, so its progress shows wherever runs
+are read (the office panel, `/multi-agent:status`). Inside a pipeline run the
+run's own tracker already covers it; skip this block.
+
+```bash
+case "$TASK_ID" in review-*)
+  S="${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/$TASK_ID"; mkdir -p "$S"
+  printf '{"taskId":"%s","mode":"review","status":"in_progress","currentPhase":0}' "$TASK_ID" \
+    | node "$HOME/.claude/scripts/write-state.mjs" "$S/agent-state.json" >/dev/null
+  export MULTI_AGENT_TASK_ID="$TASK_ID"
+  bash "$HOME/.claude/scripts/phase-tracker.sh" init "$TASK_ID"
+  for p in "0:Input" "1:Diff" "2:Reviewers" "3:Triage" "4:Report"; do
+    bash "$HOME/.claude/scripts/phase-tracker.sh" add "${p%%:*}" "${p#*:}"
+  done
+  bash "$HOME/.claude/scripts/phase-tracker.sh" update 0 in_progress ;;
+esac
+```
+
+Step 1 (1, 1a) is tracker step 0, step 2 (2-2c) step 1, steps 3-4b step 2,
+step 5 step 3 and steps 6-7 step 4: `update <N> in_progress` on entry and `completed` on exit. Each later
+call runs in a new shell where `$TASK_ID` is no longer set, so it carries the
+review's id written out literally (the `review-...` value the registration
+used) and refuses the global pointer, which another run's `init` can move:
+
+```bash
+MULTI_AGENT_TASK_ID=review-1 MULTI_AGENT_STRICT_TASK_ID=1 \
+  bash "$HOME/.claude/scripts/phase-tracker.sh" update 2 completed
+```
+
+After step 7 a standalone review closes its record with the same `write-state.mjs` call and
+`"status":"complete","currentPhase":4`.
+
+Reviewer token counts (`phase-tracker.sh tokens <N> ...`) go under step 2
+(Reviewers); inside a pipeline run they go under the run's Review phase.

package/pipeline/multi-agent-refs/setup/accounts.md

@@ -0,0 +1,27 @@
+# Setup  -  Per-account hosts and auto-learned fields
+
+> Loaded by `setup/SKILL.md` Step 3.6 and its auto-learned-fields note. The SKILL keeps when Step 3.6 runs and the autopilot skip; this file carries the prompt, the saved shape and the resolver precedence, plus the fields the pipeline learns from use instead of asking.
+
+## Per-account host overrides (Step 3.6)
+
+Use case: a single user with two corporate identities (e.g. agency + client). Each account points at its own Jira host  -  `prefs.global.hosts.jira` can hold only one default, so per-account overrides win for the rest.
+
+For each non-default account, ask once:
+
+```
+Account {label} has Jira/Bitbucket tokens but no host override yet.
+Use the global default ({hosts.jira}) or set a per-account host?
+
+  1) Use global default
+  2) Set per-account host
+```
+
+If `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optional). Save to `prefs.global.accounts[]` as `{ \"id\": \"client-x\", \"jiraHost\": \"client-x.atlassian.net\", \"bitbucketHost\": \"bitbucket.client-x.com\" }`.
+
+`account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent:setup accounts`.
+
+## Auto-learned fields
+
+**Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time  -  most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.
+
+**Git Identity**: auto-learned from token onboarding. Each token saved in Step 3 triggers an identity prompt (see Token Save Flow Step C). No separate identity setup step.

package/pipeline/multi-agent-refs/setup/app-store-connect.md

@@ -5,6 +5,7 @@
 - [Apple ID + app-specific password](#apple-id-app-specific-password)
 - [Multi-provider accounts](#multi-provider-accounts)
 - [Verify + expiry](#verify-expiry)
+- [Step 3b in one paragraph](#step-3b-in-one-paragraph)
 <!-- /toc -->
 
 Loaded on demand by `/multi-agent:setup` Step 3b (iOS only, optional). The SKILL.md carries the step intro; this file is the full flow.
@@ -149,3 +150,7 @@ the resolved tier. A credential that resolves but is rejected (401/403) follows
 Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
 different token / Skip and continue  -  never a silent drop. Regenerating the API
 key repeats steps 2 to 5 with the new file.
+
+## Step 3b in one paragraph
+
+Runs inside Step 3. Every part of the API key lives in the Keychain, the `.p8` included: ask for the `.p8` as a path, validate it BEFORE saving with `node "$HOME/.claude/scripts/probe-store-key.mjs" --asc ...` (exit 0 only), map `appstore_connect_private_key`, store it from the file with `credential-store.sh set appstore_connect_private_key - < <AuthKey_<keyId>.p8>`, run `node "$HOME/.claude/scripts/write-store-config.mjs"`, then offer (picker, default keep) to delete the file. `store_asc_*` and `ios_testflight_validate` then read the key from the Keychain. The five entries, the tier picker and the probes: `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. On Skip, nothing is written.

package/pipeline/multi-agent-refs/setup/firebase.md

@@ -7,6 +7,7 @@
 - [4. appId discovery](#4-appid-discovery)
 - [5. v1alpha, and what to do when it breaks](#5-v1alpha-and-what-to-do-when-it-breaks)
 - [6. Skipping](#6-skipping)
+- [Step 3c in one paragraph](#step-3c-in-one-paragraph)
 <!-- /toc -->
 
 Loaded on demand by `/multi-agent:setup` Step 3c (optional, any platform). The SKILL.md carries the step intro; this file is the full flow.
@@ -158,3 +159,7 @@ are simply not enriched, and the run says so rather than pretending it looked.
 Never lead with "paste the stack trace yourself" - that is tier 3, and offering
 the last resort first trains the user to skip the durable fix (`refs/keychain.md`
 Rule 2).
+
+## Step 3c in one paragraph
+
+Runs inside Step 3. Measure first  -  `bash "$HOME/.claude/lib/fetch-crashlytics.sh" --probe` answers `tier-1-ready` / `tier-1-no-grant` / `malformed` / `unreachable`  -  then ask by that answer, never blind. Store the JSON as issued; never base64 it. Skip writes nothing. Then offer appId discovery: `bash "$HOME/.claude/scripts/firebase-app-discovery.sh" <repo> --json` reads the pairs the repo already carries, for `firebase.accounts[].apps[]`  -  it saves a round trip per run; skipping costs nothing. The picker, both tiers, the role-request wording and the v1alpha caveat: `$HOME/.claude/multi-agent-refs/setup/firebase.md`.

package/pipeline/multi-agent-refs/setup/google-play.md

@@ -68,3 +68,7 @@ toolkit then reports Google Play as configured from the Keychain, and
 
 The JSON stays on disk unless the user asks otherwise: Google issues a new key on
 request, so the file is not the only copy the way a `.p8` is.
+
+## Step 3d in one paragraph
+
+Runs inside Step 3, only when the target repo is Android. One entry, `google_play`: the service-account JSON the toolkit's `store_play_*` tools use, which lets `/multi-agent:store-ready` run Android Gate 2. Ask for the JSON's path, validate BEFORE saving with `node "$HOME/.claude/scripts/probe-store-key.mjs" --play --service-account <path>`, map `google_play`, then `credential-store.sh set google_play - < <path>` and `write-store-config.mjs`. Account prerequisites, the picker and the probe hints: `$HOME/.claude/multi-agent-refs/setup/google-play.md`. Skip writes nothing.

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

@@ -0,0 +1,21 @@
+# Setup  -  Enforcement hooks (Step 8) and stack plugins (Step 9)
+
+> Loaded by `setup/SKILL.md` Steps 8 and 9. The SKILL keeps what is offered and the commands; this file carries the merge rules for the hooks template and how the stack answer is read. Read it before Step 8.
+
+## Step 8  -  Hook merge rules
+
+- 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.
+- Say the read-size gate stays inert until `prefs.global.bulkRead.mode` is set; recommend `observe` first (why, and the Phase 3 exemption: `picker-contract.md`).
+
+## Step 9  -  Reading the stack answer
+
+Ask the detector, then derive. No marker list here: a second list is a second
+answer, and it drifts from the detector.
+
+Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
+`ai-analyst-toolkit` are in every answer, the empty one included: neither is
+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.

package/pipeline/multi-agent-refs/setup/language.md

@@ -0,0 +1,46 @@
+# Setup Step 0  -  Language Selection (full contract)
+
+> Loaded by `setup/SKILL.md` Step 0. The SKILL keeps the order (this question comes first) and the fixed-English rules; this file carries the two language axes, the exact prompt, validation, the confirmation lines and the unknown-input rule. Read it before Step 0. Pickers follow `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+
+Ask BEFORE anything else, so every subsequent setup prompt and the rest of the pipeline honour the choice. The pipeline has two language axes:
+
+| Axis | What it controls | Configurable? |
+|---|---|---|
+| `promptLanguage` | Picker chrome only: the `AskUserQuestion` `header` chip, host error UI, internal contract identifiers | **No  -  fixed to `en`.** The chip is capped at 12 chars, which most Turkish equivalents overflow. |
+| `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports rendered to the user | Yes  -  set here and changeable later via `/multi-agent:language <en\|tr>` |
+
+`promptLanguage` is seeded as `"en"` and never offered to the user. Commits, branch names, PR title prefixes, reviewer and triage prompts and agent-log.md stay English; PR, Jira, issue and wiki bodies follow `outputLanguage` (`multi-agent-refs/rules.md`, Language Application).
+
+#### Step 0 prompt  -  `outputLanguage`
+
+The setup wizard asks one question (English UI per skill-prompt rules):
+
+```
+Which language should the assistant use for ITS OWN explanations,
+status updates, and pipeline-generated reports?
+
+  1) English
+  2) Türkçe
+
+Select (1-2):
+```
+
+**Rules:**
+
+- **Already set in prefs** → skip silently. User can change later with `/multi-agent:language <en|tr>` or `/multi-agent:language output <en|tr>`.
+- **New value** → validate against the schema enum (`en`, `tr`), write `prefs.global.outputLanguage` via atomic rename, force `prefs.global.promptLanguage = "en"`, then echo a confirmation in the just-chosen `outputLanguage`:
+  - `en`: `outputLanguage=<Y>. promptLanguage stays "en". Commits, branch names and reviewer prompts stay English; PR, Jira and wiki bodies follow outputLanguage.`
+  - `tr`: `outputLanguage=<Y>. promptLanguage "en" sabit. Commit'ler, branch adları ve review istemleri İngilizce kalır; PR, Jira ve wiki metinleri outputLanguage'i izler.`
+- **Unknown input** → re-ask once, then abort setup with a hint pointing to `/multi-agent:language`.
+
+From this point forward, every prompt in Steps 1-6 below follows the canonical
+per-field matrix in `$HOME/.claude/multi-agent-refs/rules.md` ("Language Application"):
+`question`, `label` and `description` render in `outputLanguage`; `header` stays
+English. Wizard status and the post-setup summary follow `outputLanguage`. Commits,
+branch names and agent prompts stay English; PR, Jira, issue and wiki bodies
+follow `outputLanguage`.
+
+> `promptLanguage` governs only the button and chip chrome, never the question a
+> user reads. Rendering a whole prompt in English "per the fixed
+> `promptLanguage`" contradicts the matrix above and produces half-English
+> pickers on Turkish runs.

package/pipeline/multi-agent-refs/setup/multi-repo-group.md

@@ -0,0 +1,51 @@
+# Setup Step 6  -  Remember as Multi-Repo Group (full contract)
+
+> Loaded by `setup/SKILL.md` Step 6. The SKILL keeps the trigger and the skip condition; this file carries the prompt, the auto-name heuristic, the saved shape, the LRU + dedup rules and the skip rules. Read it before Step 6.
+
+After Step 5, if the user picked **2 or more** repos, offer to remember the combination as a named group. Phase 0's project picker surfaces saved groups at the top, so a multi-repo task ("update token resolver in `common` + `uicomponents`") becomes a single keypress next time.
+
+Auto-skipped if Step 5 was skipped or fewer than 2 repos were selected.
+
+**Prompt:**
+```
+Step 6  -  Remember as a multi-repo group (optional)
+You picked 2 repos: Checkout, UIComponents.
+
+Save this combo for one-tap selection in Phase 0?
+  Group name (Enter for auto): [Checkout + UIComponents]
+  Skip with 'n'.
+```
+
+**Auto-name heuristic** (suggested but editable):
+- 2 repos    → `"<repoA> + <repoB>"`
+- 3-4 repos  → `"<repoA>, <repoB>, <repoC>(+1)"`
+- 5+ repos   → `"<repoA> + <count-1> more"`
+
+Repo identifiers in the label are the human label from `recentProjects` (basename of the path, not the full path), so groups stay readable.
+
+**Save** (matches schema `global.recentGroups[]` shape  -  `repos` required, `label` / `count` / `lastUsed` optional):
+
+```json
+{
+  "global": {
+    "recentGroups": [
+      {
+        "label": "Checkout + UIComponents",
+        "repos": ["~/dev/Checkout", "~/dev/UIComponents"],
+        "count": 1,
+        "lastUsed": "2026-04-15T21:08:00Z"
+      }
+    ]
+  }
+}
+```
+
+**LRU + dedup rules:**
+- New group → unshift to front of `recentGroups`.
+- Same set of `repos` already exists (order-independent compare) → bump existing entry to front, increment its `count`, update `lastUsed`. Do NOT create a duplicate.
+- Schema cap is 10 entries; oldest LRU entries past the cap are dropped.
+
+**Skip rules:**
+- Single-repo selection → step is a no-op (no group needed for one repo).
+- User answers `n` → not saved; the picker still works for one-time use, and a future Phase 0 selection of the same combo will re-prompt.
+- Step 5 skipped → Step 6 is also skipped (no selection to remember).

package/pipeline/multi-agent-refs/setup/summaries.md

@@ -0,0 +1,63 @@
+# Setup  -  Summary layouts
+
+> Loaded by `setup/SKILL.md` Steps 2 and 4 and its setup-from-scratch note. Each section is the layout the wizard prints at that point.
+
+## Step 2 discovery summary
+
+```
+Keychain Token Discovery (${USER}):
+
+  Jira               -> ${USER}_Jira_Access_Token
+  GitHub             -> ${USER}_Github
+  Figma              -> ${USER}_Figma_Access_Token
+  Firebase           -> ${USER}_Firebase_Access_Json
+  Confluence         -> MISSING
+  Jenkins            -> MISSING
+  ---
+  Git identities: check preferences file (see Step 3)
+
+  Mapped: 8 | Missing: 4
+```
+
+## Step 4 final status
+
+```
+All tokens present. Pipeline ready to use.
+
+Optional per-project features (configured on first use, nothing to do now):
+  • Phase 5 Report Step 2 Wiki  -  auto-generates component wiki pages + Figma
+    screenshots. Activates when (a) task is a component AND (b) a Figma token
+    is in Keychain. Four adapters supported: submodule / in-repo / github-wiki
+    / separate-repo. First run asks: use auto-detected path, use a custom
+    path, skip once, or disable for this project (persisted).
+  • channels  -  post-hoc multi-channel reporter (Jira/Confluence/Wiki/PR), works on any branch with an open PR.
+  • Default reviewers  -  auto-fetched from Bitbucket default-reviewers endpoint
+    or GitHub CODEOWNERS on first PR.
+
+Next step:
+  /multi-agent "PROJ-12345"              -> start your first task
+  /multi-agent help                      -> full usage guide
+```
+
+## Setup from scratch
+
+To set up multi-agent on a new machine:
+
+```
+1. Install the toolkit:
+   npx @{npm-scope}/multi-agent-pipeline install
+
+2. Start setup:
+   /multi-agent setup
+
+3. Interactive flow:
+   -> Token scan (shows what is missing)
+   -> Git Identity creation (name + email)
+   -> Inline commands for missing tokens
+   -> Final verification
+
+4. Ready:
+   /multi-agent "PROJ-12345"
+   /multi-agent "https://github.com/.../issues/42"
+   /multi-agent "bug description"
+```

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

@@ -4,6 +4,8 @@
 - [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)
+- [Identity learning (Step 3)](#identity-learning-step-3)
+- [Inline Token Save Pattern](#inline-token-save-pattern)
 <!-- /toc -->
 
 This flow is used in TWO contexts:
@@ -223,3 +225,52 @@ Repository hosts this token may be sent to for read-only clone and fetch
 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.
+
+## Identity learning (Step 3)
+
+Each token save triggers an identity prompt:
+
+```
+Token saved. Which git identity uses this token?
+
+  Existing identities:
+    1. Ada Lovelace <ada@example.com>
+    2. Ada Lovelace <ada@personal.com>
+    n. Create new identity
+
+  Select:
+```
+
+- First token ever → no existing identities → asks name + email → creates identity → maps token
+- Subsequent tokens → pick existing or create new → maps token to that identity's `servicePatMap`
+- Multiple accounts per platform supported (e.g. two GitHub tokens, each mapped to a different identity)
+- Identity is stored in `prefs.global.identities[]`, token-to-identity binding in `identity.servicePatMap`
+
+**Legacy compatibility**: If `prefs.global.gitIdentities` (deprecated) is present, `migrate-prefs.mjs` renames it to `identities` automatically.
+
+## Inline Token Save Pattern
+
+All tokens go through `~/.claude/lib/credential-store.sh` (Python helper and label/service attributes: `setup/SKILL.md` "Setup").
+
+```bash
+# PAT / API Key / JSON contents (from clipboard)
+pbpaste | ~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" -
+pbcopy < /dev/null  # clear clipboard
+
+# Non-secret value typed inline (a secret on argv is visible to ps and lands in shell history)
+~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
+
+# Key file from disk (the .p8, the Google Play JSON; or when the clipboard is unavailable)
+~/.claude/lib/credential-store.sh set "<SERVICE_NAME>" - < /path/to/file.json
+
+# Read  -  a JSON value comes back exactly as it was stored, newlines included
+~/.claude/lib/credential-store.sh get "<SERVICE_NAME>"
+```
+
+For maximum stdin hygiene (the secret never lands on argv / shell history), use the Python helper directly with the `-` sentinel:
+
+```bash
+pbpaste | ~/.claude/scripts/keychain.py set "<SERVICE_NAME>" -
+```
+
+The shell driver auto-delegates `get`/`set`/`delete` to the deterministic Python helper at `$HOME/.claude/scripts/keychain.py` (Python 3 stdlib only, no external deps). The Python path writes both `-l` (label) and `-s` (service) attributes so items are findable regardless of how callers look them up. Set `KEYCHAIN_DELEGATE=0` to force the raw shell path.

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -93,7 +93,7 @@ Phases by mode:
 | `/multi-agent` | 0,1,2,3,4,5 |
 | answered local at Step 5b | 0,1,2,3,4,5 (the user test needs a worktree checkout and local has none, so that STEP inside Review is skipped - the phase is not) |
 | `/multi-agent:autopilot` | 0,1,2,3,4,5 (autopilot drops the interactive user test inside Review) |
-| `/multi-agent:analysis` | 0,1,3,4,5 (no code is written, so Dev is not in the set) |
+| `/multi-agent:analysis` | 0,1,2,3,4,5 under its own names (`schemas/phases.json` `modes.analysis.names`: Intake, Evidence, Synthesis, Review, Publish, Report) |
 
 Every entry registers its whole set in one batch: the set is a property of the command, known before the tracker boots.
 
@@ -404,7 +404,7 @@ call for call, so a reader that is not the host (`runs-index.mjs`, and every
 client behind the contract server) sees the same list under the same phase:
 
 ```bash
-bash $HOME/.claude/scripts/phase-tracker.sh task <N> <task_id> pending|in_progress|completed \
+bash $HOME/.claude/scripts/phase-tracker.sh task <N> <task_id> pending|in_progress|completed|deleted \
   [--subject "<subject>"] [--active-form "<activeForm>"]
 ```
 
@@ -416,10 +416,15 @@ bash $HOME/.claude/scripts/phase-tracker.sh task <N> <task_id> pending|in_progre
 
 `<N>` is the phase the task belongs to: the phase in progress when it was
 created. A new task needs `--subject`; an update may pass the status alone and
-keeps the subject and active form it had. Phase tiles themselves are not
+keeps the subject and active form it had. `deleted` takes the task off the list, as a native `TaskUpdate` with status `deleted` does. Phase tiles themselves are not
 mirrored: the phase list already is the state file. The call is quiet (it
 renders nothing), so it never replaces the host's own update; it records it.
 
+On Claude Code the `task-mirror.sh` PostToolUse hook makes this call itself
+for every `TaskCreate` and `TaskUpdate` of the session bound to the run, under
+the phase in progress, and leaves phase tiles out. A manual `task` call on top
+of it is harmless: the second write sets the same values.
+
 ## Resume behaviour
 
 When `/multi-agent:resume <task_id>` is called:

package/pipeline/office/NOTICE.md

@@ -4,7 +4,10 @@ The office page (`index.html`, built from `pipeline/office-src` by
 `pipeline/scripts/office-build.mjs`) draws sprites from pixel-agents
 (https://github.com/pixel-agents-hq/pixel-agents, commit b1bafd0): the six
 character sheets, the floor and wall tiles and the furniture, kept unchanged
-in `assets/`. pixel-agents'
+in `assets/`. The company furniture (kitchen, restroom, server room, archive,
+reception, lab and mail room pieces) is this project's own drawing: its
+sources are the pixel grids in `pipeline/office-art`, which the build renders
+into `assets/` with the pixel-agents palette. pixel-agents'
 characters are based on JIK-A-4's MetroCity free top-down character pack
 (https://jik-a-4.itch.io/metrocity-free-topdown-character-pack), released
 under CC0 1.0.