@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.1

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

@@ -13,7 +13,7 @@
 <!-- /toc -->
 
 Reporting needs three things: `usageLog.enabled` true, a token that resolves,
-and a logged-in GitHub account that can read the pipeline repository. The token
+and a GitHub account on this machine that can read the pipeline repository. The token
 is arranged by one call (`$HOME/.claude/scripts/usage-register.mjs`) made from
 the three places a machine can first become real: **setup**, **update**, and
 **the Phase 0 exit gate** of a run on a machine that reached neither. Asserted by
@@ -24,7 +24,8 @@ the three places a machine can first become real: **setup**, **update**, and
 `usage-report.mjs` emits coarse run metadata, one record per run, upserted by
 run id. Never prompts, never code, never diffs, never token values, never
 absolute paths, never the repository name (a digest stands in for it). The
-registration call sends two fields: the reporting login and the short hostname.
+registration call sends the reporting login and the short hostname, plus the
+signed challenge when the account was found by an SSH key (section 4).
 
 Each record carries:
 
@@ -57,6 +58,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
@@ -65,57 +81,133 @@ is waiting on a person and is never shown as abandoned. The threshold is
 
 ## 3. The reporting identity
 
-The login is the GitHub login of the **logged-in account that can read the pipeline
-repository** (`usageLog.accessRepo`, default `mmerterden/multi-agent-pipeline`):
+The login is the GitHub login of **the account on this machine that can read the
+pipeline repository** (`usageLog.accessRepo`, default `mmerterden/multi-agent-pipeline`):
 access to that repository is what grants use of the pipeline, so it also decides
-whose name a run carries. `usage-identity.mjs` checks every github.com account
-`gh auth status` lists, in the order `usageLog.reportAs` (when logged in), the
-active account, then the rest. Each check is `gh api repos/<accessRepo>` with that
-account's token in the child's environment as `GH_TOKEN`: never on argv, never
-logged, never stored. The first account that can read the repository wins.
+whose name a run carries. `usage-identity.mjs` finds it with no question asked,
+stopping at the first account that can read the repository:
+
+| Order | Method (`usageLog.loginMethod`) | Candidates | Access check |
+|-------|------|------------|--------------|
+| 1 | `gh` | every github.com account `gh auth status` lists: `usageLog.reportAs` (when logged in), the active account, then the rest | `gh api repos/<accessRepo>` with that account's token in the child's environment as `GH_TOKEN` |
+| 2 | `credential` | the token git's credential helper holds for https://github.com: `git credential fill` with `protocol=https`, `host=github.com` on stdin, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, askpass disabled, a timeout | `GET /user` names the login, `GET /repos/<accessRepo>` proves access; through `gh api` with `GH_TOKEN`, or straight to the GitHub API from a child process when gh is not installed |
+| 3 | `ssh` | the private keys `ssh -G github.com` lists (`identityfile`, `~` expanded) and `~/.ssh/id_ed25519`, `id_ecdsa`, `id_rsa`, each only when its `.pub` exists; a `.pub` listed on its own stands for a key held by an agent | `ssh -T git@github.com` names the login (`Hi <login>!`; a deploy key's `owner/repo` is skipped), `git ls-remote git@github.com:<accessRepo>.git HEAD` proves access. Both with `-i <key> -o IdentitiesOnly=yes -o BatchMode=yes -o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new` |
+
+No token is ever put on an argv, logged or stored: gh and git print it on their
+own stdout, and it travels on only in a child's environment. Batch mode means a
+key that needs a passphrase and is not in ssh-agent is skipped, never prompted
+for. A missing gh, git or ssh binary, a timeout or a failed check only means
+"no candidate"; nothing here fails a caller.
 
 Never `identity.name`, which carries a person's real name and sometimes a
 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:
+The answer is cached in prefs (`usageLog.login`, `loginMethod`, `loginKey` for
+the SSH key path, `loginRepo`, `loginCheckedAt`, `loginReason`) for 7 days, or
+1 day when no account was found, so a phase boundary costs no network call. A
+cached SSH login whose key file is gone is re-checked. Refresh it after changing
+accounts or keys, 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, no report.** Nothing is reported under an account
+that cannot read the repository: the server accepts only the repository owner
+and its collaborators. The emitter sends nothing and writes one line to stderr
+(`usage-report: not sent - no GitHub account on this machine can read ...`,
+naming what was tried); registration is skipped with the same reason. A cache
+entry or registration written by 20.17.0 with `loginFallback` /
+`registeredFallback` set is treated as no account: it is re-checked at once and
+replaced as soon as an account with access is found.
+
+**`--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 account with access, a key that cannot sign, 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 identity check, and finding no account later does not
+undo it (`decideRegistration`). So the personal account has to be reachable only
+once, at the moment of registration.
+
+`usage-register.mjs --json` reports `needsPersonalAccount: true` only when the
+machine is not pinned and no account was found at all: no gh account, no
+credential-helper token and no SSH key with access. That is the last resort.
+Setup and update then ask once (AskUserQuestion per
+`$HOME/.claude/multi-agent-refs/picker-contract.md`; label
+`Add personal account (Recommended)` / `Skip`) and offer either fix:
+
+- **gh**: note the active account (`gh api user --jq .login`), have the person
+  run 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), then switch the work account back so pull requests keep their
+  author: `gh auth switch --hostname github.com --user <the noted account>`.
+- **SSH key**: add this machine's public key (for example `~/.ssh/id_ed25519.pub`)
+  under the personal account's GitHub Settings > SSH and GPG keys. Nothing else
+  changes on the machine.
+
+Then `node "$HOME/.claude/scripts/usage-register.mjs" --refresh --json` finds
+the account and pins it. Skip leaves reporting off; the next update asks again.
 
 ## 4. The server side
 
 `/api/usage/register` requires proof that the caller owns the login it names.
-`usage-register.mjs` reads the verified account's token with
-`gh auth token --user <login>` (gh prints it on its own stdout; it is never on
-another process's argv, never logged, never stored) and sends it as
-`Authorization: Bearer <token>`. The body's `u` stays as a hint. The server
-resolves the token to a GitHub login, refuses a mismatch, then checks that login
-with a server-side token (the repository owner, or a collaborator of the
-repository) before it issues a token, and pins the login to that token.
+The proof depends on how the account was found:
+
+- **gh**: `gh auth token --user <login>` (gh prints it on its own stdout), sent
+  as `Authorization: Bearer <token>`.
+- **credential**: the credential helper's token, fetched again at registration
+  (never kept from the identity check), sent the same way.
+- **ssh**: no token at all. (a) `POST <register url>/challenge` with
+  `{ "u": <login> }` returns `{ challenge, namespace, expiresAt }`. (b) The exact
+  challenge bytes (UTF-8, no trailing newline) are written to a `0600` file in a
+  fresh temp dir and signed with `ssh-keygen -Y sign -f <key> -n <namespace>`,
+  stdin closed and askpass disabled, so a key that needs a passphrase fails at
+  once; then with `-f <key>.pub`, which signs through ssh-agent when the key is
+  loaded there. The temp dir is removed afterwards. (c) `POST <register url>`
+  with `{ "u", "c", "ssh": { "challenge", "signature" } }` and no
+  Authorization header.
+
+For a bearer, the server resolves the token to a GitHub login and refuses a
+mismatch. For an SSH proof, the challenge is stateless and HMAC-bound to the
+login, valid for five minutes; the server checks it, then accepts the signature
+only from one of the login's public keys on GitHub
+(`https://github.com/<login>.keys`; ed25519, rsa-sha2-256/512, ecdsa nistp256). Either way it then checks that login with a
+server-side token (the repository owner, or a collaborator of the repository)
+before it issues a token, and pins the login to that token. The body's `u` is a
+hint for a bearer and the claim being proven for a signature.
 
 The proof is sent only over https to the default reporting host or a host listed
 in `usageLog.trustedHosts`, or plain http to loopback (`127.0.0.1`, `localhost`,
-`[::1]`) for local development; any other endpoint is refused before the gh
-token is read. Redirects are not followed by either call, so neither the gh
-token nor the ingest token can be carried to another host. A `401`, or a `403`
-for a login mismatch, leaves reporting off with a status line naming the login
-that could not be confirmed (`gh auth status` must list that account); a `403`
-for a login without access says it needs collaborator access; a decline is
-reported as `declined`; gh having no
-token for the login sends nothing. `/api/usage/ingest` reports every record
-under the pinned login and ignores the name the client sent; a pinned login that
-is no longer the owner or a collaborator is dropped. Records from any other
-account are hidden from the panel. `usage-register.mjs` replaces a stored token
-whose `registeredAs` differs from the verified login, or that predates
-verification, because a token reports under the login it was issued for.
+`[::1]`) for local development; any other endpoint is refused before any token
+is read or any key is used. Redirects are not followed by any of the calls, so
+neither a GitHub token, a signature nor the ingest token can be carried to
+another host.
+
+| Answer | Status line |
+|--------|-------------|
+| `401` / `403` `login_mismatch` | the login that could not be confirmed (for gh: `gh auth status` must list it) |
+| `401` `ssh_signature_invalid` | the signature did not verify |
+| `401` `ssh_key_not_on_account` | the key is not on that account; add its `.pub` to it |
+| `401` `ssh_key_unsupported` | the key type is not accepted; use an ed25519, rsa or ecdsa-p256 key |
+| `403` (no access) | the login needs collaborator access |
+| challenge `404` / `405` | the endpoint does not accept an SSH key as proof yet |
+| signing failed | the key needs a passphrase and is not in ssh-agent: `ssh-add <key>` |
+| `accepted: false` | `declined` |
+
+gh or the credential helper having no token for the login sends nothing.
+`/api/usage/ingest` reports every record under the pinned login and ignores the
+name the client sent; a pinned login that is no longer the owner or a
+collaborator is dropped. Records from any other account are hidden from the
+panel. `usage-register.mjs` replaces a stored token whose `registeredAs` differs
+from the verified login, that predates verification, or that a 20.17.0 fallback
+registration left, because a token reports under the login it was issued for.
 
 ## 5. The token
 
@@ -135,7 +227,8 @@ switch) holds the prefs file's lock and replaces the file atomically at mode
 
 `usageLog.optOut: true` blocks registration permanently and is checked before
 anything else - before the identity check, the network call and any credential
-read (the credential store and `gh auth token`).
+read (the credential store, `gh auth token`, `git credential fill` and any SSH
+key).
 
 The other silence is not a choice: offline, endpoint down, ingest disabled by the
 admin, no account with access, or a credential store that refuses the write. That

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" }
+        }
+      }
+    }
+  }
+}