@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.0

package/pipeline/multi-agent-refs/features/exploratory-testing.md

@@ -0,0 +1,140 @@
+# Exploratory testing - findings, budgets, stop rules
+
+<!-- toc -->
+- [1. The run file](#1-the-run-file)
+- [2. A finding](#2-a-finding)
+- [3. Budget and stop rules](#3-budget-and-stop-rules)
+- [4. Product failure or blocked](#4-product-failure-or-blocked)
+- [5. Driving the app: locators and expect steps](#5-driving-the-app-locators-and-expect-steps)
+- [6. Report](#6-report)
+<!-- /toc -->
+
+An exploratory run drives a live app toward a goal and reports what looks
+wrong. What it produces is a set of claims, and this contract keeps them
+checkable: every finding carries what was expected, what was seen and how to
+get there again; every run has a budget and stops on its own; a step that could
+not run is reported apart from a product that ran and was wrong.
+
+Consumers: `/multi-agent:test` (the UI Bug Hunter, `commands/sim-test.md`),
+`/multi-agent:bug-bash` (one run per charter). Script:
+`$HOME/.claude/scripts/explore-findings.mjs`. Run file:
+`$HOME/.claude/schemas/explore-run.schema.json`. Assertions that need judgement go
+to a fresh judge: `features/assertion-judge.md`.
+
+## 1. The run file
+
+Write the run as it goes to `<log dir>/run.json`: `goal`, `platform`, `budget`,
+`usage`, `steps[]`, `findings[]`. One step is one charter-sized move ("change
+the quantity on the first cart row and read the total"), not one tap.
+
+```json
+{"index": 3, "title": "Change quantity", "status": "failed", "code": "ASSERTION_FAILED",
+ "detail": "total stayed 12.00", "trace": "<path of the toolkit's trace.md, if any>"}
+```
+
+`status` is `passed | failed | blocked | exhausted`. `code` is the toolkit's
+code when the step did not pass; it decides how the step counts (section 4).
+
+## 2. A finding
+
+| Field | Rule |
+|---|---|
+| `kind` | `issue` (functional defect, fails the run) or `warning` (cosmetic, does not) |
+| `severity` | integer 1-5: 1 trivial, 2 low, 3 medium, 4 high, 5 critical |
+| `title`, `screen` | short, and where it was seen |
+| `expected` | what should have happened, from the spec when there is one (`spec` quotes it) |
+| `observed` | what happened instead |
+| `repro` | the steps that reach it from launch, at least one |
+| `evidence` | at least one `{kind, path}`: `screenshot`, `ui-tree`, `video`, `trace`, `log`, `text` |
+| `step` | the step that reported it |
+
+Report a finding the moment its evidence is on disk, not at the end. A finding
+that misses a field is listed under "failed the contract" and cannot fail the
+run: `explore-findings.mjs report` holds it out of the verdict.
+
+Secrets never appear in a finding. A credential is named, not written:
+`secret_ref:<name>`. The script refuses `password: <value>`, `token=<value>`
+and the like in any finding text.
+
+## 3. Budget and stop rules
+
+| Budget | Default | Range |
+|---|---|---|
+| steps | 8 | 1-12 |
+| minutes (wall clock) | 10 | 3-15 |
+| tokens | 150000 | 20000-400000 |
+
+Values outside the range are clamped and named in `clamped`. Before each new
+step run:
+
+```bash
+node "$HOME/.claude/scripts/explore-findings.mjs" check --run "<run.json>"
+```
+
+`{"stop": true}` ends the run with that `reason`:
+
+- `step-limit`, `time`, `tokens`: the budget is spent.
+- `stuck`: the last three steps were blocked and none of them reported a
+  finding. Three blocked steps in a row means the environment, not the app, is
+  in the way, and more steps would spend the budget learning nothing.
+
+A failed step does not stop the run; only the rules above do.
+
+## 4. Product failure or blocked
+
+| Step | Counts as |
+|---|---|
+| `failed` + `ASSERTION_FAILED` / `ASSERTION_INCONCLUSIVE` | product failure |
+| `CREDENTIAL_MISSING` | blocked: credentials |
+| `ENVIRONMENT_UNAVAILABLE` | blocked: environment |
+| `SEED_DATA_MISSING` | blocked: seed data |
+| `LOCATOR_NOT_FOUND`, `LOCATOR_AMBIGUOUS`, `REPLAY_DIVERGED` | blocked: automation |
+| `BUDGET_EXCEEDED` | exhausted (neither) |
+| `failed` with no code | blocked: unknown (never silently a product failure) |
+
+A blocked step is a fact about the test setup. It goes in its own report
+section, grouped by cause, so "the login screen is broken" and "the run had no
+test account" are never the same line.
+
+Verdict, from `explore-findings.mjs report`:
+
+- **failed**: at least one valid `issue`.
+- **blocked**: no step ran, or every step was blocked, and no `issue`.
+- **passed**: steps ran, no `issue`, not every step blocked. Warnings allowed.
+
+## 5. Driving the app: locators and expect steps
+
+With `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.19.0, prefer these over
+coordinates; on an older toolkit, fall back to the UI tree plus frame-centre
+taps as before and say so in the report:
+
+- **Locate, then act.** `ui_locate` resolves an element by accessibility
+  identifier, by role plus label, or by visible text; `ios_tap_element` /
+  `android_tap_element` tap what it resolves. Identifier first, role plus label
+  second, text last (text changes with locale). `LOCATOR_NOT_FOUND` and
+  `LOCATOR_AMBIGUOUS` are automation blocks, not product findings: narrow the
+  locator and retry once before recording the step as blocked.
+- **Assert with expect steps.** In `agent_run_steps`, `expect_text`,
+  `expect_element` and `expect_url` decide a deterministic check and return
+  `verdict: passed | failed | blocked` with a code. Use them for anything
+  exact: a total, a label, a route. Only a visual or semantic claim ("the
+  layout is not clipped", "the error explains what to do") goes to the judge.
+- **Secrets by reference.** The type tools take `secret_ref` instead of the
+  value; the value never enters the transcript, the run file or a finding.
+- **Traces.** A failed `agent_run_steps` writes a `trace.md`; put its path in
+  the step's `trace` and in the finding's `evidence` as `kind: "trace"`.
+- **Replay.** `save_as` stores a step sequence that reached a finding, and
+  `replay` runs it again. `REPLAY_DIVERGED` means the app no longer follows the
+  recorded path: an automation block, and a hint that the screen changed.
+- **Web sessions.** Pass `session` to keep parallel browser sessions apart
+  (one per bug-bash charter).
+
+Tool inputs are the tool's own schema; the names above are the contract, the
+argument shapes are read from the server.
+
+## 6. Report
+
+`explore-findings.mjs report --run <run.json>` prints the verdict, why the run
+ended, the budget used, issues before warnings with the most severe first,
+blocked steps by cause, and the findings that failed the contract. The UI Bug
+Hunter keeps its own screen table and summary around this block.

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -44,7 +44,7 @@ The key sits under `metadata:` because the host skill frontmatter schema has no
 
 `skill-conformance.mjs` reads frontmatter across the installed skills trees and loads what declared itself. Nothing in the pipeline names `ios-coding-standard`, `apple-archive-compliance` or any other skill, so a future UIKit, Objective-C, Kotlin or backend registry drops in with zero pipeline change  -  and a registry that is absent produces a declared coverage gap rather than a silent pass.
 
-**The skills root differs per host**, so discovery is a bounded walk over candidate roots (`<install>/skills`, `<install>/multi-agent-refs/skills` for Codex, `<repo>/pipeline/skills`), installed layouts first. `install/copilot.mjs` copies `scripts/` byte-for-byte with no path rewrite, so a hardcoded `~/.claude/skills` is inert on two of the three hosts. That bug has already shipped here once: dynamic skill loading exited 1 on every real install while passing a smoke that ran from the repo. `skillsRootsSearched` is recorded in the manifest so an empty result is attributable to a root rather than to an absence of registries.
+**The skills root differs per host**, so discovery is a bounded walk over candidate roots and the first registry found under a name wins. On Claude Code the order is each marketplace stack plugin's `skills/` (the checkout, then every cached version, from `lib/plugin-skill-roots.mjs`), `~/.claude/multi-agent-refs/registries` (registries the installer lays down for the pipeline's gates, `valven-rules` among them), `~/.claude/skills`, then `<repo>/pipeline/skills`: a registry that ships in a plugin (`ios-coding-standard`, `valven-rules`) is what Claude Code loads, and a same-named copy an older install left behind must not shadow it. Copilot CLI and Codex load no plugin, so their installed skills dir (`<install>/skills`, `<install>/multi-agent-refs/skills`) comes first and the plugin roots follow. `install/copilot.mjs` copies `scripts/` byte-for-byte with no path rewrite, so a hardcoded `~/.claude/skills` is inert on two of the three hosts. `skillsRootsSearched` is recorded in the manifest so an empty result is attributable to a root rather than to an absence of registries.
 
 ## Scope is required, and it is what makes this stack-generic
 

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -57,6 +57,21 @@ progress.
 | `completed` | Phase 5, after it writes `status: complete` and `finishedAt` to the state; the analysis render step |
 | `halted` | the halt-visibility step in `phases/operations.md` |
 | `parked` | the park-visibility step in `phases/operations.md`, after a run writes `awaiting_input` or `waitingFor` |
+| `install`, `update` | registration, setup and update, and every accepted run event, when the installed version was not reported yet (see below) |
+
+**Install and update records.** Derived, never written by the installer (see
+section 8): the version stamp `install.js` writes (`.pipeline-version`, Claude
+Code's first) says which version is installed and, by its modification time,
+since when; prefs keep the last version reported (`usageLog.reportedVersion`).
+When they differ, `usage-report.mjs --lifecycle` sends one record: `ev`
+(`update` from the reported version; without one, `install` on a machine that
+registered after the stamp and `update` from an unknown version on one that
+registered before it), `v`, `vf`, `hs` (the host trees at that version) and `t`
+(the stamp time), and moves `reportedVersion` forward once the server accepted
+it. The id is derived from the version and the stamp time, so a resend replaces
+the record. It runs after a successful registration, after setup or update finds
+a token already onboarded, and after every accepted run event. The panel lists
+the records under "Kurulumlar" and keeps them out of the run counts.
 
 The panel derives a run's status from the last event it received. A run still
 `in_progress` with no event for **6 hours** is shown as abandoned; a parked run
@@ -79,16 +94,55 @@ corporate title, and never simply the active `gh` account, which on a machine
 with a work account and a personal account is often the one without access.
 
 The answer is cached in prefs (`usageLog.login`, `loginRepo`, `loginCheckedAt`)
-for 7 days, or 1 day when no account had access, so a phase boundary costs no
-network call. Refresh it after changing accounts or being granted access:
+for 7 days, or 1 day for a fallback or when no account was found, so a phase
+boundary costs no network call. Refresh it after changing accounts or being granted access:
 
 ```bash
 node "$HOME/.claude/scripts/usage-identity.mjs" --refresh
 ```
 
-**No account with access, no report.** The emitter sends nothing and writes one
-line to stderr (`usage-report: not sent - none of the logged-in GitHub accounts
-(...) can read ...`); registration is skipped with the same reason.
+**No account with access: the active account, and the server decides.** A work
+machine often has only an enterprise-managed account logged in to gh, and such an
+account can never be a collaborator of a personal repository. Then the active
+account (else the first) is used as a fallback, marked `usageLog.loginFallback`
+and cached for 1 day so an account with access added later takes over. The
+server accepts it when its suffix is one the operator listed
+(`USAGE_ENTERPRISE_SUFFIXES`) and refuses it with a 403 otherwise.
+
+**No gh account at all, no report.** The emitter sends nothing and writes one
+line to stderr (`usage-report: not sent - no GitHub account is logged in ...`);
+registration is skipped with the same reason.
+
+**`--quiet` still speaks once.** The Phase 0 backstop discards stdout, so a
+registration that leaves reporting off for a reason the user can fix (a refused
+login, no gh account, an unreachable endpoint) prints one stderr line,
+`multi-agent: usage reporting is off - <reason>`, on every run until it is fixed.
+
+### Personal account
+
+A registration is pinned: the server binds the token to the login it verified,
+and the machine keeps that login in `usageLog.registeredAs`. Every later record
+is named after it, with no gh call, and a fallback account never replaces it
+(`decideRegistration`). So the personal account has to be logged in to gh only
+once, at the moment of registration; it can be logged out afterwards.
+
+`usage-register.mjs --json` reports `needsPersonalAccount: true` while the
+machine is not pinned to an account that can read the pipeline repository: no
+registration yet, or one made with a fallback account. Setup and update then ask
+once (AskUserQuestion per `$HOME/.claude/multi-agent-refs/picker-contract.md`; label
+`Add personal account (Recommended)` / `Skip`):
+
+1. Note the active account: `gh api user --jq .login`.
+2. The person runs the browser login for the account that holds access, in their
+   own terminal (in Claude Code: `! gh auth login --hostname github.com --web`).
+   gh keeps both accounts.
+3. Switch the work account back, so pull requests keep their author:
+   `gh auth switch --hostname github.com --user <the noted account>`.
+4. `node "$HOME/.claude/scripts/usage-register.mjs" --refresh --json`. It finds
+   the account with access, replaces the fallback registration and pins the new
+   one.
+
+Skip leaves the fallback in place; the next update asks again.
 
 ## 4. The server side
 

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

@@ -1,6 +1,17 @@
 # Valven delivery rules across the phases
 
-The `valven-rules` registry (`$HOME/.claude/skills/valven-rules/`) holds the rules; `valven-gate.mjs` measures them and `valven-split.mjs` turns an oversized branch into stacked pull requests. This file is the per-phase contract the phase docs point at.
+<!-- toc -->
+- [Phase 1](#phase-1)
+- [Phase 2](#phase-2)
+- [Phase 3](#phase-3)
+- [Phase 4](#phase-4)
+- [Development Behaviors](#development-behaviors)
+- [Old work](#old-work)
+<!-- /toc -->
+
+The `valven-rules` skill holds the rules in `references/rules.yml`; `valven-gate.mjs` measures them and `valven-split.mjs` turns an oversized branch into stacked pull requests. This file is the per-phase contract the phase docs point at.
+
+The skill ships in `ai-common-toolkit`, the always-on plugin, so the rules reach everyone who installs the marketplace, with or without the pipeline. Claude Code loads it from the plugin (`ai-common-toolkit:valven-rules`); the installer copies it into the skills tree on Copilot CLI and Codex. The gate reads the registry installed with it, so its evaluators and its rules come from one release: `multi-agent-refs/registries/valven-rules/` on Claude Code (laid down by the installer outside the skills dir, so the host does not load the skill twice), the skills tree on Copilot CLI and Codex, the source in a checkout, and the plugin copies only when none of those exists. `skill-conformance.mjs` finds the judgement rules in the plugin on Claude Code and falls back to the same registries dir. The gate prints the path it used as `rulesPath`; when none is found it exits 2, which every step below treats as "could not measure", never as a pass.
 
 ## Phase 1
 
@@ -15,11 +26,11 @@ node $HOME/.claude/scripts/valven-gate.mjs --mode dev --repo "$WORKTREE" --base
   --out "$WORKTREE/.pipeline/valven-dev.json" >/dev/null
 ```
 
-**Gate 6** (valven-rules, dev mode). Exit 2 blocks the phase: the rules could not be read or git failed. Exit 1: `VLV-TEST-01` (source changed, no test changed) and `VLV-TRACE-01` (no issue key in the branch) are fixed here before Review. `VLV-SIZE-01`, `VLV-SIZE-02` and `VLV-SCOPE-01` are not fixed by editing: keep building on this branch, set `state.valven.splitRequired = true`, and Phase 4 Step 2.95 splits it into stacked PRs. `VLV-REWORK-01` is reported to the user with the ratio and continues. Contract: `$HOME/.claude/skills/valven-rules/SKILL.md`.
+**Gate 6** (valven-rules, dev mode). Exit 2 blocks the phase: the rules could not be read or git failed. Exit 1: `VLV-TEST-01` (source changed, no test changed) and `VLV-TRACE-01` (no issue key in the branch) are fixed here before Review. `VLV-SIZE-01`, `VLV-SIZE-02` and `VLV-SCOPE-01` are not fixed by editing: keep building on this branch, set `state.valven.splitRequired = true`, and Phase 4 Step 2.95 splits it into stacked PRs. `VLV-REWORK-01` is reported to the user with the ratio and continues. Contract: the `valven-rules` skill.
 
 ## Phase 3
 
-Step 1.762, after the owned-path gate. The PR body does not exist yet, so `VLV-PRDESC-01` reports `not-measured`; Phase 4 checks it.
+Step 1.762, after the owned-path gate. The PR body and the pull request do not exist yet, so `VLV-PRDESC-01`, `VLV-CYCLE-01`, `VLV-CYCLE-02`, `VLV-CYCLE-03` and `VLV-PICKUP-01` report `not-measured`; Phase 4 and `/multi-agent:review` measure them.
 
 ```bash
 VG_FILE="$WORKTREE/.pipeline/valven-gate.json"
@@ -55,6 +66,12 @@ VG_RC=$?
 
 Log: `Phase 4 Step 2.95: valven {pass|fixed|split N|shipped-whole}`
 
+The commit-mode report also scores `VLV-CYCLE-01`, from the oldest author date among the commits about to be pushed to now. Phase 4 commits right before the push, so this is what Valven will read from the pushed history, and it is a `suggestion` that never blocks the push. The rule carries information on a pull request whose commits were pushed as they were made, which `/multi-agent:review` measures.
+
+### Opening the pull request
+
+Every gate has passed before the push, so the pull request opens ready for review with the default reviewers attached, and the draft/ready prompt recommends READY. A draft delays the reviewers' notification, and `VLV-PICKUP-01` flags a draft older than 3 hours on the next review.
+
 ### PR body
 
 **Valven body check (required, every PR).** After the body is written to `/tmp/pr-body-$TASK_ID.md` and before the PR is created or updated:
@@ -67,6 +84,16 @@ jq -r '.findings[] | select(.ruleId == "VLV-PRDESC-01") | .issue' "$WORKTREE/.pi
 
 Any `VLV-PRDESC-01` line blocks creation: add the missing why / how-to-verify text and re-run. Other findings here were already handled at Step 2.95.
 
+## Development Behaviors
+
+`VLV-CYCLE-01` (coding: first commit to the pull request opening), `VLV-CYCLE-02` (pickup: ready for review to the first review) and `VLV-CYCLE-03` (review: first review to approval or merge) are scored into Valven's bands, reported as `results[].score` and collected in `scores`; `VLV-REWORK-01` adds the churn score, `100 - churn %`. A duration in the 50 or 0 band is a `suggestion`, because the time has passed and the pull request cannot change it. `VLV-PICKUP-01` is `important` when the pull request has no reviewer, which the author fixes now; a draft older than 3 hours is a `suggestion` (`draft_severity`), because an unattended run opens a draft on purpose and a person decides when it is ready.
+
+The durations need the pull request's timeline, passed with `--pr-meta-file`. On GitHub, `pr-timeline.mjs --repo <owner/repo> --pr <N> --out <file>` writes it: `gh pr view --json` (head and base branch, body, commits, author, open, close and merge times, draft state, review requests, reviews) plus two things only GitHub's GraphQL timeline carries, the time a draft was marked ready (`readyAt`) and each review author's type, so a bot such as Copilot's reviewer is not counted as a person. When that query fails the script keeps the `gh pr view` output and says on stderr that pickup then counts from the opening and bots are not recognised; the summary repeats it.
+
+A Bitbucket caller writes `{createdAt, readyAt, isDraft, reviewerCount, firstReviewAt, approvedAt, mergedAt, closedAt}` in ISO 8601: `createdDate`, `draft` and the close time of a declined pull request from the pull request, `reviewerCount` the length of `reviewers[]`, `firstReviewAt` the earliest `COMMENTED`, `REVIEWED` or `APPROVED` activity by someone other than the author, `approvedAt` the earliest `APPROVED`; a field it cannot read is null. Bitbucket records no ready-for-review time, so its `readyAt` is null.
+
+The gate leaves out reviews by the author, by bots and pending reviews, and a review left before the pull request was ready: pickup and review time start at ready. An unknown reviewer count stays unknown (`VLV-PICKUP-01` reports it `not-measured`, never "no reviewer"), a draft is not asked for a reviewer, and on a merged or closed pull request the clocks stop there and `VLV-PICKUP-01` does not apply. A file that does not parse, or has no valid `createdAt`, is reported on stderr and the timeline rules report `not-measured`; every other rule is still measured.
+
 ## Old work
 
 `VLV-AGE-01` (a commit older than 14 days, by author date so a rebase does not hide it), `VLV-BEHIND-01` (more than 50 commits behind the base, or a merge-base older than 14 days) and `VLV-TRACE-03` (commits carrying another issue's key) mean the branch carries old or foreign work. The answer is never a rebase of the old history: the change moves.

package/pipeline/multi-agent-refs/help/en.md

@@ -186,6 +186,8 @@ UI Testing (standalone  -  not part of pipeline phases):
   through three gates per platform, and lives at /multi-agent:store-ready. The old
   /multi-agent:test "store-ready" [path] tag still works and hands off there.
 
+  /multi-agent:bug-bash [scope]      Parallel exploratory sessions by charter and persona, each with a budget; a finding is reported only when a repro test fails for its reason
+
   Uses xcrun simctl / adb (native, no external app needed).
   Booted simulator/emulator required. Auto-detects bundle ID from project.
 

package/pipeline/multi-agent-refs/help/tr.md

@@ -185,6 +185,8 @@ UI Testing (standalone  -  pipeline fazlarından bağımsız):
   geçirerek doğrular, iOS + Android, ve /multi-agent:store-ready altında. Eski
   /multi-agent:test "store-ready" [path] etiketi çalışır ve oraya devreder.
 
+  /multi-agent:bug-bash [kapsam]     Charter ve persona başına bütçeli paralel keşif oturumları; bulgu, sebebiyle fail olan bir repro testi varsa raporlanır
+
   xcrun simctl / adb kullanır (harici app gerekmez).
   Booted simulator/emulator şart. Bundle ID proje'den otomatik algılanır.
 

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -681,7 +681,7 @@ Phase 0 owns `agent-state.json`. Do not call
 
 ```bash
 node "$HOME/.claude/scripts/phase0-exit-gate.mjs" "$TASK_ID" --input "$ORIGINAL_INPUT"
-node "$HOME/.claude/scripts/usage-register.mjs" --quiet >/dev/null 2>&1 || true
+node "$HOME/.claude/scripts/usage-register.mjs" --quiet >/dev/null || true
 node "$HOME/.claude/scripts/usage-report.mjs" --task-id "$TASK_ID" --phase 0 --event phase >/dev/null 2>&1 || true
 ```
 

package/pipeline/multi-agent-refs/phases/phase-4-commit.md

@@ -20,7 +20,7 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 >                                                        │
 >   ┌──────────────── PR payload ─────────────────────────┘
 >   │  title + description (rawfile) + reviewers + fromRef + toRef + draft
->   └──► POST (Bitbucket) or gh pr create --draft (GitHub) ──► PR open
+>   └──► POST (Bitbucket) or gh pr create (GitHub) ──► PR open
 > ```
 
 #### Input contract
@@ -239,7 +239,7 @@ PR author cannot appear in `--reviewer`  -  strip from list.
 
 ##### Draft vs ready-for-review
 
-Before creating PR, ask: "DRAFT or READY? [1/2], default 1"  -  DRAFT blocks merge/delays notifications, READY notifies reviewers + CI. Skip in `autopilot` → default READY.
+Before creating PR, ask: "READY or DRAFT? [1/2], default `defaultPrMode` or 1"  -  READY notifies reviewers + CI, DRAFT blocks merge and notifies later. Skip in `autopilot` → READY.
 
 - **Bitbucket**: `"draft": true` in payload (DC 8.x+). Promote: `draft: false` PUT. Older: prefix title `[DRAFT]`.
 - **GitHub**: `--draft`. Promote: `gh pr ready {N}`.

package/pipeline/schemas/bug-bash-verification.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/bug-bash-verification.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline  -  bug bash verifications",
+  "description": "One entry per merged candidate, written by the verifying subagents of /multi-agent:bug-bash. bug-bash.mjs report confirms a candidate only when its repro test failed with ASSERTION_FAILED on the assertion that encodes it (failedAt equals assertion); any other outcome is listed as rejected with the reason.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["id", "status"],
+    "properties": {
+      "id": { "type": "string", "pattern": "^BB-[0-9]+$" },
+      "status": { "enum": ["confirmed", "rejected"] },
+      "reason": {
+        "enum": ["artifact", "environment", "design", "fixture", "did-not-reproduce", "duplicate"],
+        "description": "Required when rejected. artifact: the explorer misread the screen; environment: a key, service or limit only the local stack lacks; design: the code, tests or copy say it is intended; fixture: the seed data lacks what real records have."
+      },
+      "note": { "type": "string" },
+      "productionRisk": {
+        "type": "boolean",
+        "description": "An environment rejection whose failure handling production users would also see."
+      },
+      "rootCause": { "type": "string", "description": "file:line, when the source was read." },
+      "repro": {
+        "type": "object",
+        "required": ["path", "command", "code", "assertion"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 },
+          "code": {
+            "type": ["string", "null"],
+            "description": "ASSERTION_FAILED, PASSED, or the failure code the run produced."
+          },
+          "assertion": { "type": "string", "minLength": 1 },
+          "failedAt": { "type": ["string", "null"] },
+          "trace": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/explore-run.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/explore-run.schema.json",
+  "version": "1.0.0",
+  "title": "Multi-Agent Pipeline  -  exploratory test run",
+  "description": "One exploratory session of /multi-agent:test or one /multi-agent:bug-bash charter, written as the run goes so explore-findings.mjs can decide when it must stop (check) and what its verdict is (report). Findings are claims with evidence; a bug bash proves them with a reproducing test before reporting them.",
+  "type": "object",
+  "required": ["goal", "budget", "steps", "findings"],
+  "properties": {
+    "goal": { "type": "string", "minLength": 1 },
+    "platform": { "enum": ["ios", "android", "web"] },
+    "persona": { "type": "string" },
+    "budget": {
+      "type": "object",
+      "description": "Per-run budget; explore-findings.mjs fills defaults (8 steps, 10 minutes, 150000 tokens) and clamps to steps 1-12, minutes 3-15, tokens 20000-400000.",
+      "properties": {
+        "steps": { "type": "integer", "minimum": 1 },
+        "minutes": { "type": "number", "minimum": 0 },
+        "tokens": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "usage": {
+      "type": "object",
+      "properties": {
+        "steps": { "type": "integer", "minimum": 0 },
+        "minutes": { "type": "number", "minimum": 0 },
+        "tokens": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ended": { "enum": ["finished", "step-limit", "time", "tokens", "stuck", "aborted"] },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["index", "status"],
+        "properties": {
+          "index": { "type": "integer", "minimum": 1 },
+          "title": { "type": "string" },
+          "status": { "enum": ["passed", "failed", "blocked", "exhausted"] },
+          "code": {
+            "type": "string",
+            "description": "The toolkit's verdict or locator code when the step did not pass: ASSERTION_FAILED and ASSERTION_INCONCLUSIVE are product failures; CREDENTIAL_MISSING, ENVIRONMENT_UNAVAILABLE and SEED_DATA_MISSING block by cause; LOCATOR_NOT_FOUND, LOCATOR_AMBIGUOUS and REPLAY_DIVERGED block as automation; BUDGET_EXCEEDED is exhausted."
+          },
+          "detail": { "type": "string" },
+          "trace": {
+            "type": "string",
+            "description": "Path of the toolkit's failure trace.md, when it wrote one."
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "severity", "title", "expected", "observed", "repro", "evidence"],
+        "properties": {
+          "id": { "type": "string" },
+          "step": { "type": "integer", "minimum": 1 },
+          "kind": {
+            "enum": ["issue", "warning"],
+            "description": "issue: a functional defect, fails the run. warning: cosmetic, does not."
+          },
+          "severity": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 5,
+            "description": "1 trivial, 2 low, 3 medium, 4 high, 5 critical."
+          },
+          "title": { "type": "string", "minLength": 1 },
+          "screen": { "type": "string" },
+          "expected": { "type": "string", "minLength": 1 },
+          "observed": { "type": "string", "minLength": 1 },
+          "repro": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "evidence": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["kind", "path"],
+              "properties": {
+                "kind": { "enum": ["screenshot", "ui-tree", "video", "trace", "log", "text"] },
+                "path": { "type": "string", "minLength": 1 }
+              }
+            }
+          },
+          "spec": {
+            "type": "string",
+            "description": "The acceptance criterion the expectation comes from, quoted, or 'no spec, model expectation'."
+          },
+          "judge": {
+            "type": "object",
+            "description": "Present when a visual or semantic assertion decided the finding: the fresh judge's checked verdict.",
+            "properties": {
+              "verdict": { "enum": ["passed", "failed"] },
+              "code": { "type": ["string", "null"] },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/prefs.schema.json

@@ -1503,7 +1503,7 @@
         "valven": {
           "type": "object",
           "additionalProperties": false,
-          "description": "valven-rules delivery gate (skills/valven-rules). Runs at Phase 2 exit (Gate 6), Phase 4 Step 2.95 before push, Phase 3 Step 1.762 and every /multi-agent:review. Findings carry tag `valven`; an accepted important or blocking one sets NEEDS WORK, and an oversized branch is split into stacked PRs by valven-split.mjs.",
+          "description": "valven-rules delivery gate (the valven-rules skill, shipped in ai-common-toolkit). Runs at Phase 2 exit (Gate 6), Phase 4 Step 2.95 before push, Phase 3 Step 1.762 and every /multi-agent:review. Findings carry tag `valven`; an accepted important or blocking one sets NEEDS WORK, and an oversized branch is split into stacked PRs by valven-split.mjs.",
           "properties": {
             "enabled": {
               "type": "boolean",

package/pipeline/scripts/_stack-routing.mjs

@@ -29,6 +29,8 @@ export const COMMON_SKILLS = [
   "backlog",
   "localization-reuse-map",
   "security-review",
+  "valven-rules",
+  "e2e-testing",
 ];
 
 // The analyst plugin is the second always-enabled toolkit. It carries outside