@mmerterden/multi-agent-pipeline 20.15.1 → 20.17.0

package/pipeline/commands/multi-agent/review/SKILL.md

@@ -182,6 +182,51 @@ Persist `agent-state.review.moduleGuides = [<repo-relative paths>]` and inject i
 
 Scope note: a guide governs only files under its own directory  -  a guide found under one module must not be applied to a sibling module's changes in the same PR.
 
+### 2c. Valven delivery rules  -  required on every input
+
+The `valven-rules` registry (`ai-common-toolkit`) is applied to every review, in `review` mode. Collect what the gate needs, then run it:
+
+```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`.
+
+Step 6 adds one line under the table: `Valven: <n> finding(s)  ·  <changedLines> lines / <fileCount> files  ·  split: <yes N slices|no>`, plus for a PR `Valven scores: churn · coding · pickup · review` from `scores` (`-` when absent).
+
 ### 3. Launch parallel reviewers  -  host-CLI dependent
 
 Every host runs three reviewers; only the second slot differs, because GPT-5.4 exists on Copilot and Codex but not on Claude Code, where Opus fills it.
@@ -218,7 +263,7 @@ Never dispatch a Fable reviewer or a Fable triage on the model list below alone.
 
 The rung switch and its resolution: `$HOME/.claude/multi-agent-refs/features/model-fallback.md`.
 
-Each reviewer receives the diff, the module review guides from Step 2b (when any were found), plus the standard reviewer system prompt (see `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
+Each reviewer receives the diff, the module review guides from Step 2b (when any were found), the Valven judgement rules from Step 2c, plus the standard reviewer system prompt (see `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` for the prompt contract). Output: structured `findings[]` per reviewer.
 
 ### 4. Store-compliance cross-reference
 

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -150,15 +150,17 @@ pbcopy < /dev/null
 Then, **whether they pasted or skipped**, run:
 
 ```bash
-node "$HOME/.claude/scripts/usage-register.mjs"
+node "$HOME/.claude/scripts/usage-register.mjs" --json
 ```
 
+If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
+the person's own GitHub account once (the "Personal account" step in
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
+
 It maps whatever token exists and switches reporting on, and requests a
-per-machine write-only one when none resolves. This call is why the step exists:
-registration used to happen only inside `/multi-agent:update`, so a user who
-installed, ran setup and never ran update never registered and never reported -
-which reads in the panel exactly like nobody using the pipeline. What is sent,
-what never is, and `usageLog.optOut`:
+per-machine write-only one when none resolves, so a machine that runs setup and
+never runs update still reports. What is sent, what never is, and
+`usageLog.optOut`:
 `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
 ### Auto-learned fields (no setup step needed)

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -73,7 +73,7 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 63 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 64 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -131,6 +131,7 @@ Step 0 gate rules and why: `features/doctor.md`.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
+   - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
    - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`.
      ```bash
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
@@ -240,11 +241,11 @@ same specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**63 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**64 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
-autopilot-status, build-optimize, channels, complaint-analysis, create-jira,
+autopilot-status, bug-bash, build-optimize, channels, complaint-analysis, create-jira,
 design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help,
 ios-coding-standard, issue, jira, kill, language, log,
 manual-test, model, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -126,7 +126,7 @@ and every later block that needs them starts by sourcing it.
    whichever of the three runs first.
 
    ```bash
-   node "$HOME/.claude/scripts/usage-register.mjs"
+   node "$HOME/.claude/scripts/usage-register.mjs" --json
    ```
 
    It requests a per-machine **write-only** token when none resolves, stores it
@@ -135,6 +135,10 @@ and every later block that needs them starts by sourcing it.
    reporting off with one status line - never an error. Contract and the data it
    sends: `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
+   If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
+   the person's own GitHub account once (the "Personal account" step in
+   `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
+
 6. **Show the new version and its changes** (from the packaged CHANGELOG - there is no git history on this channel):
    ```bash
    . "${TMPDIR:-/tmp}/multi-agent-update.env" || { echo "Run step 1 first."; exit 1; }

package/pipeline/commands/sim-test.md

@@ -67,6 +67,29 @@ is the iOS-pinned alias of that same command.
 
 ## Flow
 
+Every run follows the exploratory-testing contract: findings shape, budget,
+stop rules, and blocked steps kept apart from product failures. Read it once
+before Step 1:
+
+```
+$HOME/.claude/multi-agent-refs/features/exploratory-testing.md
+```
+
+### Step 0  -  Budget and run file
+
+Open the run file at `$HOME/.claude/logs/sim-test/{bundle_id}/{timestamp}/run.json`
+with the goal (the scenario, or "full sweep"), the platform and the budget
+(defaults 8 steps, 10 minutes, 150000 tokens; the user may name others). Append
+each step and each finding as it happens. Before every new step:
+
+```bash
+node "$HOME/.claude/scripts/explore-findings.mjs" check --run "<run.json>"
+```
+
+`stop: true` ends exploration with that reason (`step-limit`, `time`, `tokens`,
+or `stuck` after three consecutive blocked steps that reported nothing) and
+goes straight to the crash sweep and Step 6. A failed step does not stop the run.
+
 ### Step 1  -  Device & App Discovery
 
 ```
@@ -90,7 +113,16 @@ Call: ios_status_bar (time: "09:41", battery_level: 100)
 
 ### Step 3  -  Systematic Screen Exploration
 
-For each screen in the app, read before you look, and batch what you can:
+For each screen in the app, read before you look, and batch what you can.
+
+**Locators before coordinates.** With `@mmerterden/multi-agent-toolkit-mcp` ≥
+v3.19.0, resolve elements with `ui_locate` (accessibility id, then role plus
+label, then visible text) and tap with `ios_tap_element` / `android_tap_element`;
+assert exact outcomes with `expect_text` / `expect_element` / `expect_url` steps
+inside `agent_run_steps`; type credentials with `secret_ref`, never the value.
+`LOCATOR_NOT_FOUND` / `LOCATOR_AMBIGUOUS` block the step as automation, not
+product. On an older toolkit, the frame-centre taps below are the fallback; say
+which one ran in the report.
 
 ```
 Call: ios_get_ui_tree            (text: labels, frames, traits; ~0.1 s, no image)
@@ -213,6 +245,17 @@ Call: ios_list_crashes (app: <process name>, since_min: <minutes since Step 1 la
 
 ### Step 5  -  Bug Detection (on EVERY screenshot)
 
+Exact claims (a total, a label, a route, an element present) are checked with an
+expect step or the UI tree. A visual or semantic claim that becomes a finding,
+or decides a step, goes to a fresh judge subagent that sees only the assertion
+and the current screenshot / UI tree, never this run's history:
+
+```
+$HOME/.claude/multi-agent-refs/features/assertion-judge.md
+```
+
+`inconclusive` never passes. The checked verdict goes on the finding as `judge`.
+
 When analyzing each screenshot, check for:
 
 | Category         | What to Look For                                                                     |
@@ -228,6 +271,18 @@ When analyzing each screenshot, check for:
 
 ### Step 6  -  Report
 
+Render the findings block from the run file first; its verdict, issues,
+warnings and blocked section are the source for everything below:
+
+```bash
+node "$HOME/.claude/scripts/explore-findings.mjs" report --run "<run.json>"
+```
+
+Every bug below is a finding from the run file: `expected`, `observed`, `repro`,
+`severity` 1-5 (5 critical, 4 high, 3 medium, 2 low, 1 trivial), `kind`
+`issue` or `warning`, and `evidence`. A finding the script listed under
+"failed the contract" is fixed or dropped, never reported as a bug.
+
 Create tasks for each bug found:
 
 ```
@@ -246,18 +301,25 @@ Then output full report:
 
 ## Bugs Found ({N} total)
 
-### BUG-1: [{Critical/Major/Minor}] {title}
+### BUG-1: [{severity word} {issue|warning}] {title}
 
 - **Screen**: {which screen}
 - **Category**: Layout / Dark Mode / Typography / Navigation
-- **Steps**: 1. Open app -> 2. Tap {X} -> 3. Observe {issue}
+- **Repro**: 1. Open app -> 2. Tap {X} -> 3. Observe {issue}
 - **Expected**: {correct behavior}
-- **Actual**: {what's wrong}
+- **Observed**: {what's wrong}
+- **Judge**: {passed / failed ASSERTION_FAILED / failed ASSERTION_INCONCLUSIVE, when a judge decided it}
 - **Spec**: "<quoted acceptance criterion from the analysis doc Section 15 / 20, or: no spec, model expectation>" (<source>)
 - **Evidence**: before=<png path> after=<png path>
 
 ### BUG-2: ...
 
+## Blocked ({N})  -  not product failures
+
+| Step | Cause | Code | Detail |
+| ---- | ----- | ---- | ------ |
+| 4    | credentials | CREDENTIAL_MISSING | no test account for checkout |
+
 ## Screens Visited ({N})
 
 | #   | Screen   | Light | Dark  | Large Text | Bugs | Evidence |
@@ -271,13 +333,16 @@ Then output full report:
 - Screens tested: {N}
 - Clean: {N}
 - With bugs: {N}
-- Critical: {N} | Major: {N} | Minor: {N}
+- Verdict: {passed / failed / blocked} · ended: {finished / step-limit / time / tokens / stuck}
+- Budget used: {steps}/{max} steps · {min}/{max} min · {tokens}/{max} tokens
+- Critical: {N} | High: {N} | Medium: {N} | Low: {N} | Trivial: {N}
+- Blocked steps: {N} (environment {N} · credentials {N} · seed data {N} · automation {N})
 - Accessibility audit (accessibility scenario): {N} audited, {N} not audited (reason per screen), deep pass: {ran / skipped: reason}
 - Crashes (full scenario): {N} during this run
 - Production readiness: FAILED | NEEDS WORK | READY
 ```
 
-`Evidence` in a bug block is the captures already written to files in Step 4: a tap-driven finding needs both `before` and `after`, a static finding (layout, contrast, dark mode, large text) needs `after` only. The `Evidence` column in Screens Visited is the count of screenshot files written for that screen. Production readiness defaults to FAILED; it is NEEDS WORK when only Minor bugs remain, and READY only when there are zero Critical / Major bugs and every planned screen was visited.
+`Evidence` in a bug block is the captures already written to files in Step 4: a tap-driven finding needs both `before` and `after`, a static finding (layout, contrast, dark mode, large text) needs `after` only. The `Evidence` column in Screens Visited is the count of screenshot files written for that screen. Production readiness defaults to FAILED; it is NEEDS WORK when only low / trivial findings remain, and READY only when there are no findings of severity 3 or above and every planned screen was visited. A blocked run is never READY: the screens it could not reach were not tested.
 
 Save to: `$HOME/.claude/logs/sim-test/{bundle_id}/{timestamp}.md`
 

package/pipeline/lib/plugin-skill-roots.mjs

@@ -0,0 +1,80 @@
+/**
+ * @file plugin-skill-roots.mjs  -  the `skills/` roots of the marketplace stack
+ * plugins on this machine.
+ *
+ * On Claude Code the stack skills do not land in ~/.claude/skills - they are
+ * loaded from the multi-agent-plugins marketplace. Registries a gate depends on
+ * (`ios-coding-standard`, `ios-module-structure`, `valven-rules`) live in a
+ * plugin's knowledge/ tree, so without these roots a gate reads green over
+ * criteria that were never loaded. Local checkout is preferred over the plugin
+ * cache for the same reason install/_plugin-skills.mjs prefers it: the checkout
+ * is what /multi-agent:sync rebuilds, the cache only advances on marketplace
+ * refresh. Cache dirs are version-named; newest wins.
+ *
+ * @module pipeline/lib/plugin-skill-roots
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const PLUGIN_MARKETPLACE = "multi-agent-plugins";
+
+export const STACK_PLUGIN_NAMES = Object.freeze([
+  "ai-ios-toolkit",
+  "ai-android-toolkit",
+  "ai-frontend-toolkit",
+  "ai-backend-toolkit",
+  "ai-common-toolkit",
+]);
+
+/** Numeric semver order, falling back to string order for non-numeric parts. */
+export function semverCompare(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return a.localeCompare(b);
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDirs(p) {
+  try {
+    return readdirSync(p).filter((n) => isDir(join(p, n)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Every `skills/` root a plugin may be loaded from, best first: the marketplace
+ * checkout, then each cached version, newest first. A caller looking for one
+ * file walks this list, so a checkout or a cache that predates the file does not
+ * hide a version that has it.
+ *
+ * @param {string} [home]
+ * @param {readonly string[]} [names]
+ * @returns {string[]}
+ */
+export function pluginSkillRootCandidates(home = homedir(), names = STACK_PLUGIN_NAMES) {
+  const roots = [];
+  for (const name of names) {
+    const checkout = join(home, PLUGIN_MARKETPLACE, "plugins", name, "skills");
+    if (existsSync(checkout)) roots.push(checkout);
+    const cacheRoot = join(home, ".claude", "plugins", "cache", PLUGIN_MARKETPLACE, name);
+    for (const v of listDirs(cacheRoot).sort(semverCompare).reverse()) {
+      const p = join(cacheRoot, v, "skills");
+      if (existsSync(p)) roots.push(p);
+    }
+  }
+  return roots;
+}

package/pipeline/lib/usage-lifecycle.mjs

@@ -0,0 +1,83 @@
+/**
+ * usage-lifecycle.mjs  -  install and update records for operational reporting.
+ *
+ * Derived, never stored by the installer: install.js lays down files and
+ * nothing else. The version stamp it writes (`.pipeline-version`) says which
+ * version is installed and, by its modification time, since when; prefs keep the
+ * last version reported (`usageLog.reportedVersion`). When the two differ,
+ * `usage-report.mjs` sends one record and moves `reportedVersion` forward once
+ * the server accepted it.
+ *
+ * A record carries `ev` (`install` or `update`), `v`, `vf` (the version it
+ * replaced, null when unknown), `hs` (the host trees at that version) and `t`
+ * (the stamp time). Its id is derived from the version and the stamp time, so a
+ * resend replaces the record rather than adding one.
+ *
+ * @module pipeline/lib/usage-lifecycle
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const HOSTS = ["claude", "copilot", "codex"];
+
+function version(v) {
+  const s = typeof v === "string" ? v.trim() : "";
+  return VERSION_RE.test(s) ? s : null;
+}
+
+function readStamp(home, host) {
+  const path = join(home, `.${host}`, ".pipeline-version");
+  try {
+    const v = version(readFileSync(path, "utf8"));
+    return v ? { host, v, mtimeMs: statSync(path).mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The installed version, the time its stamp was written and every host tree at
+ * that version; Claude Code's stamp first. Null when no stamp is readable.
+ */
+export function installedVersion(home) {
+  const stamps = HOSTS.map((h) => readStamp(home, h)).filter(Boolean);
+  if (!stamps.length) return null;
+  const first = stamps[0];
+  return {
+    v: first.v,
+    at: new Date(Math.floor(first.mtimeMs)).toISOString(),
+    hosts: stamps.filter((s) => s.v === first.v).map((s) => s.host),
+  };
+}
+
+/**
+ * The record for an installed version not reported yet, or null.
+ *
+ * Without a reported version the machine's registration decides: registered
+ * after the stamp means this version was its first install; registered before
+ * it (or by a version that did not record when) means an update from a version
+ * nobody reported.
+ */
+export function lifecycleEvent({ installed, usageLog = {} }) {
+  if (!installed?.v) return null;
+  const reported = version(usageLog.reportedVersion);
+  if (reported === installed.v) return null;
+  let ev = "update";
+  if (!reported) {
+    const registeredAt = Date.parse(usageLog.registeredAt || "");
+    const registeredEarlier =
+      Boolean(usageLog.registeredAs) &&
+      (Number.isNaN(registeredAt) || registeredAt < Date.parse(installed.at));
+    if (!registeredEarlier) ev = "install";
+  }
+  return {
+    id: `lc-${installed.v}-${Date.parse(installed.at)}`,
+    ev,
+    v: installed.v,
+    vf: reported,
+    hs: installed.hosts,
+    t: installed.at,
+  };
+}

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (63 commands)](#1-command-inventory-63-commands)
+- [1. Command Inventory (64 commands)](#1-command-inventory-64-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,11 +20,11 @@
 
 ---
 
-## 1. Command Inventory (63 commands)
+## 1. Command Inventory (64 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
-autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
+autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
 language, log, manual-test, model, prune-logs,
@@ -42,7 +42,7 @@ Categories:
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
 - **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
 - **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `prune-logs`, `prune-prompts`, `serve`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `prune-logs`, `prune-prompts`, `serve`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
@@ -96,6 +96,22 @@ Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary
 
 Superseded by section 1.1: Claude Code resolves component dispatch to the marketplace plugin (dual-name `create-component`/`create-ui-component`; full contract in `$HOME/.claude/multi-agent-refs/component-dispatch.md`); Copilot CLI receives the enabled plugin's authored skills through `install/copilot.mjs` (section 1.1), not a standalone `figma-*` tree  -  the installer prunes those. No shared filesystem-path routing table or figma-skill frontmatter/inventory parity remains under enforcement.
 
+### 1.4 End-to-end testing tools
+
+`/multi-agent:test` (`commands/sim-test.md`), `/multi-agent:bug-bash` and the
+`e2e-testing` knowledge skill (ai-common-toolkit) call these toolkit tools when
+the server has them, and fall back to UI-tree reads and frame-centre taps when
+it does not. Contracts: `features/exploratory-testing.md`,
+`features/assertion-judge.md`.
+
+| Capability | Tools / fields | Minimum |
+|---|---|---|
+| Element locators | `ui_locate`, `ios_tap_element`, `android_tap_element`; codes `LOCATOR_NOT_FOUND`, `LOCATOR_AMBIGUOUS` | `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.19.0 |
+| Assertion steps and verdicts | `agent_run_steps` steps `expect_text`, `expect_element`, `expect_url`; `verdict: passed / failed / blocked` with `ASSERTION_FAILED`, `CREDENTIAL_MISSING`, `ENVIRONMENT_UNAVAILABLE`, `SEED_DATA_MISSING`, `BUDGET_EXCEEDED`, `REPLAY_DIVERGED`; failure `trace.md` | ≥ v3.19.0 |
+| Secrets by reference | `secret_ref` on the type tools | ≥ v3.19.0 |
+| Parallel web sessions, replay | `session` on the web tools; `save_as` / `replay` | ≥ v3.19.0 |
+| Travel document fixtures | `document_generate`, `document_mrz_build` | ≥ v3.19.0 |
+
 ---
 
 ## 2. Canonical Placeholder Vocabulary

package/pipeline/multi-agent-refs/features/assertion-judge.md

@@ -0,0 +1,76 @@
+# Assertion judge - a fresh reader decides what the screen shows
+
+A visual or semantic assertion ("the error message tells the user what to do",
+"no text is clipped", "the selected plan is highlighted") cannot be decided by
+an exact comparison. It is decided by a judge: a fresh subagent that sees the
+assertion and the current evidence, and nothing about how the run got there.
+
+Consumers: `/multi-agent:test` (`commands/sim-test.md` Step 5),
+`/multi-agent:bug-bash` (charters and verification). Script:
+`$HOME/.claude/scripts/explore-findings.mjs judge-packet` / `judge-verdict`.
+
+## 1. Why the judge is separate
+
+The agent that drove the app knows what it meant to do, what it already
+believes, and what it was told about when a step counts as done. Every one of
+those lowers the bar for "the screen shows it". A judge that reads only the
+statement and the evidence answers the question that was asked. The actor's
+transcript, its step summaries, earlier findings and its instructions never
+reach the judge.
+
+What does reach it is the app's own vocabulary, when the assertion depends on
+it ("plans are called tiers"): a sentence that would still be true for a
+different tester on the same app.
+
+## 2. When to use it
+
+| Assertion | Decided by |
+|---|---|
+| exact text, count, total, route, element present | an expect step (`expect_text`, `expect_element`, `expect_url`) or a UI-tree read; no judge |
+| layout, contrast, clipping, overlap, an image's content | judge, with a screenshot |
+| copy meaning ("explains the error"), state ("the right tab is selected") | judge, with the screenshot and the UI tree |
+
+If an exact check can decide it, it is not a judge question.
+
+## 3. Flow
+
+1. Capture the evidence now, for this assertion: a screenshot file and, when
+   useful, the UI tree saved to a file. Evidence from an earlier step is not
+   current.
+2. Build the packet:
+
+   ```bash
+   node "$HOME/.claude/scripts/explore-findings.mjs" judge-packet \
+     --assertion "<one sentence>" \
+     --evidence screenshot=<png> --evidence ui-tree=<json> \
+     [--vocabulary "<app terms>"] > <dir>/judge-packet.json
+   ```
+
+   The script refuses any field that describes the run.
+3. Dispatch one fresh subagent (Agent tool, no conversation context carried
+   over; Copilot CLI: a new task). Its whole prompt is the packet: the
+   `instructions` field, the assertion, the evidence paths to open, and the
+   vocabulary when present.
+4. Save its JSON answer to `<dir>/judge-verdict.json` and check it:
+
+   ```bash
+   node "$HOME/.claude/scripts/explore-findings.mjs" judge-verdict \
+     --packet <dir>/judge-packet.json --verdict <dir>/judge-verdict.json
+   ```
+
+## 4. Verdicts
+
+| Judge answer | Result |
+|---|---|
+| `passed`, citing evidence from the packet | passed |
+| `failed`, citing evidence from the packet | failed, `ASSERTION_FAILED` |
+| `inconclusive` | failed, `ASSERTION_INCONCLUSIVE` |
+| a verdict citing a path not in the packet, no reason, or no citation | failed, `ASSERTION_INCONCLUSIVE` |
+
+Inconclusive is never a pass. It means the evidence did not show enough:
+capture a better screenshot (scroll, wait for the content) and judge again once,
+or record the step as failed with that code. The checked result goes on the
+finding as `judge: {verdict, code, reason}`.
+
+The actor never overrides a judge verdict. When it disagrees, it captures new
+evidence and asks a new judge; it does not argue with the old one.