@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

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

@@ -0,0 +1,35 @@
+# Resume  -  Single-candidate escape, answer contract, tail phases, tracker continuation
+
+> 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`.
+
+## Single-candidate escape
+
+| Only row | Second option |
+|---|---|
+| one stopped run | **Show every run** - re-opens with the `status != "done"` filter dropped, so a run that recorded itself finished but left work behind is still reachable |
+| only the branch diff | **Pick a stopped run instead** - re-opens listing Source A unfiltered, and says so when it is empty |
+
+## Answering a parked question
+
+**`--answer <optionId>`** answers `state.pendingQuestion` ({id, stepId, text, kind, options[]}) without a picker, which is how a client or a second terminal replies to a run parked on a question:
+
+```bash
+node "$HOME/.claude/scripts/answer-question.mjs" "$STATE_FILE" --answer "$OPTION_ID"
+```
+
+It accepts only one of `options[].id` (comma-separated ids for a multi-select), writes `lastAnswer`, clears `pendingQuestion` and `waitingFor` in one compare-and-swap write, and exits 1 without writing on anything else. The answer is data: the re-entered step reads `lastAnswer.optionIds` as the option it offered, never as text to follow. Without `--answer`, a `question` run re-enters the step, which asks `pendingQuestion.text` through the native picker. Exit 5 means the run moved since it asked; re-read the state and stop.
+
+## Tail phases
+
+**Why Review runs the build gate here.** Verify is Phase 2 Dev's exit gate, and this path has no Dev: the work arrived already written. The gate still has to run, so Review runs it before dispatching reviewers. Reviewing a branch whose build was never checked is the failure this ordering prevents.
+
+- **Phase 3 Review** - per `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Opus + Sonnet on Claude Code, Opus + Sonnet while the fable rung is off; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
+  - interactive: present them and ask (`AskUserQuestion`) whether to fix now (loop back through a minimal Phase-2-style TDD fix) or proceed;
+  - `autopilot` (or `prefs.global.resume.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
+- **Phase 3 Verify gate** - the **automated success gate** (the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/web build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" - never fabricate test results.**
+- **Phase 4 Commit/PR** - per `$HOME/.claude/multi-agent-refs/phases/phase-4-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/multi-agent-refs/rules.md` "External System Outputs" and `$HOME/.claude/rules/git-conventions.md` - `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- **Phase 5 Report** - per `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content: a Jira **comment** carrying the technical analysis + the test scenarios (and, when the PR was opened, the PR description). Every body runs through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
+
+## 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`.

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/rules.md

@@ -84,6 +84,7 @@ This is the single source of truth. When a contributor or model is unsure where
 - **Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `style`, `perf`
 - **Max first-line length**: 72 chars
 - **Body** for "why", not "what"
+- **Enforced** on Claude Code inside the run the session drives: agent-guard refuses a subject with no conventional type (after a repo profile's ticket prefix) or over 72 characters, and a PR, issue or Jira body with a literal `\n` or an HTML entity outside code.
 - **Git author**: identity selected in Phase 0, from preferences file (not Keychain, not git global config)
 
 ## Branch Naming
@@ -188,9 +189,9 @@ Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `
 
 These rules govern when and how the pipeline asks the user, and when it must NOT ask.
 
-- **No auto-commit.** Never run `git commit` without explicit user approval, even when build + review pass. The Phase 4 commit step pauses and asks ("commit message X, OK?"); only on `yes` does the commit run. Applies to checkpoint / WIP commits during Dev (Phase 3) and to the orchestrator's own state-save commits.
+- **No auto-commit.** Never run `git commit` without explicit user approval, even when build + review pass. The Phase 4 commit step pauses and asks ("commit message X, OK?"); only on `yes` does the commit run. Applies to checkpoint / WIP commits during Dev (Phase 3) and to the orchestrator's own state-save commits. Enforced on Claude Code: agent-guard asks on a `git commit` from the session driving an attended run, and pre-commit-check refuses it without the run's build, test and (from Phase 4) review evidence.
 - **No micro-confirmations for reversible local work.** Local edits, lint fixes, test additions, scaffold files, in-worktree rewrites  -  just do them. Ask only for irreversible or shared-state actions: `git push`, `git push --force`, tag, third-party POST (Confluence, Jira, Slack), publish, deletes spanning many files, branch deletion. The threshold is "can the user undo this in 30 seconds via Cmd+Z or `git restore`?"  -  if yes, do not ask.
-- **Empty `AskUserQuestion` answer is not consent.** When the user submits without picking any option (empty answers map), do NOT silently apply the "Recommended" default. Re-ask the question, or proceed treating each item as unselected. Future-behavior preference questions are not preemptive  -  only ask when the answer changes what happens NOW.
+- **Empty `AskUserQuestion` answer is not consent.** When the user submits without picking any option (empty answers map), do NOT silently apply the "Recommended" default. Re-ask the question, or proceed treating each item as unselected. On Claude Code the `answer-check.sh` PostToolUse hook names each unanswered question back to the model. Future-behavior preference questions are not preemptive  -  only ask when the answer changes what happens NOW.
 - **Question phrasing in Plan Mode.** Don't reference "the plan" in `AskUserQuestion` text while in plan mode  -  the user cannot see the plan until `ExitPlanMode`. Use `ExitPlanMode` for approval; `AskUserQuestion` only for choosing between concrete options.
 
 ## Figma Access Tier (pipeline-wide, BLOCKING)

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

@@ -120,7 +120,7 @@ For each `TaskCreate` line `phase-tracker.sh tiles` prints, IN THAT ORDER:
 
 **The subject is the tracker's line, verbatim.** `phase-tracker.sh tiles` prints each subject from the phase names the command registered (`0:Init 1:Plan 2:Dev 3:Review 4:Commit 5:Report` for a full run). Copy it as printed: no task-id prefix, no renamed, merged or annotated phase (`Analysis + Plan`, `Review + Verify`). What a phase does inside goes in `activeForm` or a sub-step tile, never in the phase name. A tile that disagrees with the tracker is a second, wrong progress record.
 
-The `tasklist_id` meta field is persisted so that `:resume` can rebuild the TaskList from the state file in a fresh session.
+The `tasklist_id` meta field is persisted so that `:resume` can rebuild the TaskList from the state file in a fresh session. On Claude Code the `task-mirror.sh` PostToolUse hook records it from every phase tile's TaskCreate result, replacing an id an earlier session left (so a resume's new ids land too), and tells the model when a tile is created after a higher-numbered phase's tile in the same session. The explicit `meta` call stays in the pattern: it is what the other hosts have, and on Claude Code it writes the same value.
 
 #### The card is not the widget
 

package/pipeline/office/NOTICE.md

@@ -7,7 +7,10 @@ character sheets, the floor and wall tiles and the furniture, kept unchanged
 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'
+into `assets/` with the pixel-agents palette. The employees' sheets
+(`assets/char_12.png` and up) are those six character sheets recoloured
+by the build, one person per sheet, from the colours in
+`pipeline/office-art/employees.json`; no pixel is drawn anew. 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.