@mmerterden/multi-agent-pipeline 20.33.0 → 20.34.0

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