@mmerterden/multi-agent-pipeline 20.15.1 → 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/review-decision.md

@@ -102,6 +102,7 @@ result, before Step 3.8:
 node "$HOME/.claude/scripts/review-decision-gate.mjs" "$TRIAGE_FILE" --state "$STATE_FILE" \
   --integrity "$WORKTREE/.pipeline/test-integrity.json" \
   --integrity "$WORKTREE/.pipeline/owned-path.json" \
+  --integrity "$WORKTREE/.pipeline/valven-gate.json" \
   --source "$WORKTREE/.pipeline/security-audit-$ITERATION.json" \
   --json > "$WORKTREE/.pipeline/review-decision-$ITERATION.json"
 RD_RC=$?
@@ -113,7 +114,7 @@ nothing); `security-audit-$ITERATION.json` is the file Step 2.7 writes when the
 audit runs (`security-audit.md`). Both are files and not process substitutions
 of a shell variable with a `{}` brace default: bash 3.2, the stock macOS
 `/bin/bash`, expands that to `{\}`, and unparseable input is exit 3.
-`owned-path.json` is the file Step 1.761 writes. `--integrity` repeats, one
+`owned-path.json` is the file Step 1.761 writes, `valven-gate.json` the one Step 1.762 writes. `--integrity` repeats, one
 file per deterministic gate. Both gates always write their file, so a declared
 `--integrity` file that does not exist is unreadable (exit 3): the gate failed
 before writing. An empty one means no findings from that gate, and a missing or

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

@@ -0,0 +1,110 @@
+# Valven delivery rules across the phases
+
+<!-- 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
+
+Work is built on one branch and shipped as small pull requests. Each task also gets an estimated line count (added + removed, tests included, generated output excluded), and the plan groups tasks into **PR slices** that each stay under the `VLV-SIZE-01` budget (`prefs.global.valven.thresholds`, default 250 lines and 25 files). Order the slices the way `valven-split.mjs` will cut them: renames and moves first, then data (models, services, repositories), then domain (view models, use cases), then UI, each slice carrying its own tests. Show the slice table in the plan (`slice`, `tasks`, `est. lines`) so the user approves the stack together with the plan. A plan whose total estimate exceeds the budget and shows no slices is incomplete. The estimate is advisory; Phase 4 Step 2.95 measures the real diff and splits by it.
+
+## Phase 2
+
+Gate 6 of the exit gate, after the secret scan:
+
+```bash
+node $HOME/.claude/scripts/valven-gate.mjs --mode dev --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --worktree \
+  --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: the `valven-rules` skill.
+
+## Phase 3
+
+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"
+node $HOME/.claude/scripts/valven-gate.mjs --mode review --repo "$WORKTREE" --base "origin/$BASE_BRANCH" \
+  --out "$VG_FILE" >/dev/null
+VG_RC=$?
+[ "$VG_RC" = "2" ] && HALT "valven gate could not run  -  see stderr"
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.valven \
+  findings="$(jq -r '.findings | length' "$VG_FILE")" split="$(jq -r '.splitRequired // false' "$VG_FILE")"
+```
+
+Exit 1 is findings, not an error: they merge at Step 3.0 with `tag: valven`, and `review-decision-gate.mjs` counts them as gate-backed, so a single-source one is not downgraded. Triage accepts a `criteriaSource: "valven-rules"` finding unless the task is exempt, never rejects it as style, and keeps its `line: 0`, which `post-pr-review.sh` posts as a top-level comment. When `splitRequired` is true the fix is never "edit the code"; Phase 4 Step 2.95 splits the branch. With `prefs.global.valven.enabled = false` the file still lands with `enabled: false` and no findings.
+
+## Phase 4
+
+```bash
+VG_COMMIT="$WORKTREE/.pipeline/valven-commit.json"
+node $HOME/.claude/scripts/valven-gate.mjs --mode commit --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --out "$VG_COMMIT" >/dev/null
+VG_RC=$?
+```
+
+- Exit 2 halts: the gate could not measure, and pushing on an unmeasured branch is the silent pass this step exists to prevent.
+- Exit 1 without `splitRequired`: fix in place. `VLV-COMMIT-01` and `VLV-TRACE-02` are squash and reword of this branch's own commits (`git rebase -i` is not available; use `git reset --soft "$(git merge-base HEAD origin/$BASE_BRANCH)"` and re-commit with the step 6 convention). `VLV-TEST-01` and `VLV-TRACE-01` return to Phase 2. Re-run the gate.
+- `splitRequired: true`: plan the stack and show it.
+
+  ```bash
+  node $HOME/.claude/scripts/valven-split.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --out "$WORKTREE/.pipeline/valven-split.json"
+  ```
+
+  Render one row per slice (branch, lines, layers, files, `oversized`) and ask (`question` / labels in `outputLanguage`, `header` English `"Split PR"`): option 1 "Split into N stacked PRs" (Recommended), option 2 "Ship as one PR" (the review will mark it NEEDS WORK), option 3 "Pause". Autopilot takes option 1. On option 1 re-run with `--apply`; exit 1 (the stack's top differs from the branch) halts with `drift[]` shown. Then build every slice branch with the Phase 2 Gate 1 command, in order; a slice that fails is folded into the next one: delete the `<branch>-p*` branches (`--apply` refuses to overwrite them), re-run with `--budget` raised to the two slices' combined lines, and build again. The original branch is never modified, so every re-run starts from the same tree. An `oversized` slice is one file larger than the budget: report it, it cannot be split by file.
+
+  After a split, steps 7 and 8 run once per slice in order: push `<branch>-pK`, open its PR with base `$BASE_BRANCH` for p1 and `<branch>-p(K-1)` for the rest, title suffix `(K/N)`, and a `## Stack` section in each body listing every slice PR with the current one marked. The original branch stays local. Record `state.valven.split = {sliceCount, branches[], prs[]}`.
+
+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:
+
+```bash
+node $HOME/.claude/scripts/valven-gate.mjs --mode review --repo "$WORKTREE" --base "origin/$BASE_BRANCH" \
+  --pr-body-file "/tmp/pr-body-$TASK_ID.md" --out "$WORKTREE/.pipeline/valven-body.json" >/dev/null
+jq -r '.findings[] | select(.ruleId == "VLV-PRDESC-01") | .issue' "$WORKTREE/.pipeline/valven-body.json"
+```
+
+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.
+
+```bash
+node $HOME/.claude/scripts/valven-port.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH"            # plan
+node $HOME/.claude/scripts/valven-port.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --apply    # move
+```
+
+`--apply` cuts `<branch>-v2` (next free `-vN`) from the current base tip, applies the net diff with `git apply --3way` as one commit, and returns to the original branch, which it never modifies. Exit 1 is a conflict: the new branch is deleted, `conflicts[]` names the paths, and they are resolved by hand on a fresh branch. `sharedWithBase[]` lists the paths the base also changed; those are the ones to re-test.
+
+- **Phase 0.** A task that resolves to an existing branch runs `valven-gate.mjs --mode dev` against it first. An old-work finding means work starts on the ported branch, not on the old one.
+- **Phase 4 Step 2.95.** Old-work findings are handled before the size check: port, re-run the gate on the new branch, then split if a size rule still fails. A `VLV-TRACE-03` commit is removed from the port (`--head` at the commit before it, or a cherry-pick of the rest) and gets its own branch.
+- **Review.** The finding's `fix` is concrete: the `valven-port.mjs` plan (new branch name, commits dropped, `sharedWithBase[]`), then "open the new PR from `<to>`, close this one with a link to it". For `VLV-TRACE-03` it lists the foreign commits. Accepted findings make the review NEEDS WORK.

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

@@ -419,6 +419,7 @@ Branch name is deterministic  -  no user confirmation needed.
   # 0 = ref exists (collision) · 2 = no matching ref (authoritative "free")
   # anything else = the probe itself failed; REMOTE_ERR holds why
   ```
+- Old work is not reused (`features/valven.md`).
 - `REMOTE_RC` is 0 or 2 → treat as authoritative
 - `REMOTE_RC` is anything else → the remote answer is **unknown**, not "free". Log
   `Remote collision probe failed: <REMOTE_ERR>`, fall back to the local check only,
@@ -680,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-1-plan.md

@@ -326,6 +326,8 @@ For each identified change area:
 
 Create tasks using TaskCreate with imperative subject, description (what/which files/expected behavior), and `addBlockedBy` for dependencies.
 
+**PR slices (required):** `features/valven.md`.
+
 ##### Analysis citation requirement (every UI task)
 
 Every UI-touching task in the plan MUST cite:

package/pipeline/multi-agent-refs/phases/phase-2-dev.md

@@ -349,7 +349,6 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <input_count> <output_count
 
 Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
-
 #### Generated trees are not yours to edit
 
 Many repos generate part of their source: a service client from an OpenAPI spec, mock
@@ -399,8 +398,6 @@ reach Review at all.
 
 #### Step 1  -  Deterministic Gates (run BEFORE AI review)
 
-If any gate fails → fix first, don't waste AI tokens reviewing broken code.
-
 ```bash
 # Gate 0: Owned paths (repo profile), before the build
 node $HOME/.claude/scripts/owned-path-gate.mjs --repo "$WORKTREE" --base "origin/$BASE_BRANCH" --state "$STATE_FILE"
@@ -411,6 +408,7 @@ node $HOME/.claude/scripts/owned-path-gate.mjs --repo "$WORKTREE" --base "origin
 <test-command> 2>&1 | tee "{worktreePath}/.test.log"
 # Gate 4: Secrets  -  run the scanner against the staged diff
 bash $HOME/.claude/scripts/pre-commit-check.sh
+# Gate 6: features/valven.md
 ```
 
 **Gate 0** exit 1 blocks the phase: move each change where its `fix` points, revert the owned path, re-run. Exit 2 is a call error, never a pass: an unknown `--base` ref means fetch the base branch. Exit 0 with `skipped: true` gives its reason in `note`; log it. Contract: `features/repo-profile.md`, "Owned-path gate".
@@ -442,7 +440,7 @@ The subtraction never widens: match on identifier only, and when identifiers can
 **Gate results:**
 
 - All pass (including the evidence gate) -> proceed to AI review
-- Any fail -> fix immediately, re-run gates (no AI review until clean)
+- Any fail -> fix, re-run gates (no AI review until clean)
   Log: "Phase 3: Gates  -  owned:{ok/fail} build:{pass/fail} lint:{pass/fail} test:{pass/fail/inherited-red} secrets:{clean/found} evidence:{ok/unverified}"
 
 ##### Gate 5  -  Fortify SSC findings (runs when `state.contextLinks[]` contains a `fortify` entry, or when `prefs.global.fortify.alwaysCheck === true`)

package/pipeline/multi-agent-refs/phases/phase-3-review.md

@@ -145,7 +145,7 @@ node $HOME/.claude/scripts/owned-path-gate.mjs --repo "$WORKTREE" --base "origin
   --state "$STATE_FILE" --out "$OP_FILE"
 ```
 
-`--out` drops the old file; exit 2 writes none. A missing `$OP_FILE` is a gate error, never "no findings" (`review-decision-gate.mjs` exit 3 under the gates). Findings merge at Step 3.0. Contract: `features/repo-profile.md`.
+`--out` drops the old file; exit 2 writes none. A missing `$OP_FILE` is a gate error, never "no findings" (`review-decision-gate.mjs` exit 3 under the gates). Findings merge at Step 3.0. Contract: `features/repo-profile.md`. Step 1.762: `features/valven.md`.
 
 #### Step 1.77  -  Reviewer scope (cost gate)
 
@@ -377,15 +377,15 @@ ANON=$(jq -n --argjson r "$REVIEWERS_JSON" --arg t "$TASK_ID" --argjson i "$ITER
 
 `$REVIEWERS_JSON` is `state.reviewIterations[i].reviewers`. Findings come back with `foundBy: "Source A|B|C"` and every identity key removed. Persist the map to `state.reviewIterations[i].anonymizationMap` for Phase 5 per-reviewer telemetry, and **never put the map in a prompt**.
 
-Then append the Step 1.76 test-integrity, 1.761 owned-path and 2.7 security-audit findings, so they are adjudicated:
+Then append the deterministic findings (Steps 1.76, 1.761, 1.762, 2.7):
 
 ```bash
 SA_FILE="$WORKTREE/.pipeline/security-audit-$ITERATION.json"
-MERGED=$(printf '%s' "$ANON" | cat - "$TI_FILE" "$OP_FILE" "$SA_FILE" 2>/dev/null \
+MERGED=$(printf '%s' "$ANON" | cat - "$TI_FILE" "$OP_FILE" "$VG_FILE" "$SA_FILE" 2>/dev/null \
   | jq -s '.[0] + ([.[1:][] | .findings // []] | add // [])')
 ```
 
-Deterministic findings keep their `tag` (`test_integrity`, `owned_path`) and no `foundBy`: a reviewer finding may hallucinate, a gate finding is a fact. Security-audit findings carry their `security` envelope and `foundBy: "security-auditor"`; no audit file contributes nothing.
+Deterministic findings keep their `tag` (`test_integrity`, `owned_path`, `valven`) and no `foundBy`: a reviewer finding may hallucinate, a gate finding is a fact. Security-audit findings carry their `security` envelope and `foundBy: "security-auditor"`; no audit file contributes nothing.
 
 ##### 3.1 Short-circuit: no findings
 
@@ -550,7 +550,7 @@ A triage verdict is judgment; a failing repro test is proof. Runs only when `pre
 
 Compressed flow: dispatch ONE verifier agent (model `verifyByTest.model`, default `sonnet`) for up to `maxFindings` (default 3) accepted blocking findings. Per finding it writes ONE minimal repro test and runs ONLY that test (Phase 2 single-test invocation, build lock, log tee'd to `$WORKTREE/.pipeline/verify-<i>.test.log`). Outcomes: test FAILS as predicted -> `confirmed`, finding stays blocking and the test is KEPT in `redTests[]` as the Phase 2 rework RED test; test PASSES on every one of `verifyByTest.repeatCount` runs (default 3) -> `not-reproduced` ONLY if `evidence-gate.mjs --claim test --status passed` exits 0 on each log; a run that disagrees with the others -> `inconclusive` with `flaky: passed k/N`, finding moves to `deferred[]`, test deleted; compile error / timeout / not unit-testable -> `inconclusive`, judgment verdict stands. Stamp findings with `verification` (schema v3.2.0), persist `state.reviewIterations[-1].verifyByTest = {attempted, confirmed, downgraded, inconclusive, redTests[]}`, recompute `approved`, re-run `validate-triage.mjs` under the 3.2.1 gate. Whole step bounded by `stepTimeoutSec` (default 600); on breach or crash remaining findings keep judgment verdicts  -  never blocks. Telemetry per 3.4: `review.verify_by_test attempted= confirmed= downgraded= inconclusive= duration_ms=`.
 
-**Autopilot decision rule (every round, after 3.7):** run the call in `$HOME/.claude/multi-agent-refs/features/review-decision.md` (Wiring: `--integrity "$TI_FILE" --integrity "$OP_FILE" --source "$SA_FILE"`), merge its JSON into `state.reviewIterations[-1].reviewDecision`, repeat the `cp`. A blocker backed by neither two reviewers nor a failing test becomes important; on exit 1 or 3 run `gate-ledger.mjs park --outcome verification-failed --gate review-decision`.
+**Autopilot decision rule (every round, after 3.7):** run the call in `$HOME/.claude/multi-agent-refs/features/review-decision.md` (Wiring: one `--integrity` per gate file, `--source "$SA_FILE"`), merge its JSON into `state.reviewIterations[-1].reviewDecision`, repeat the `cp`. A blocker backed by neither two reviewers nor a failing test becomes important; on exit 1 or 3 run `gate-ledger.mjs park --outcome verification-failed --gate review-decision`.
 
 ##### 3.8 Cross-round delta + circuit-breaker trigger 2 (iteration >= 2)
 

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
@@ -110,6 +110,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
    - For EACH submodule with changes: stage, commit, push separately
    - Commit message uses same convention but scope reflects submodule: `{type}({submodule-scope}): {description} [{jiraId}]`
 6. Commit with convention: `{type}({scope}): {description} [{jiraId}]` or `[#{shortId}]`. When `node $HOME/.claude/scripts/repo-profile.mjs resolve commit.format --repo "$PROJECT_ROOT"` returns `use: true`, its `ticketPosition` places the ticket (`prefix` first, `suffix` last; `none` keeps this default unless confirmed or manual), `ticketStyle` its form and `scopeRequired` the scope. A profile hook with `amends-commit` or `writes-files` rewrites the commit: re-read the SHA after committing ([`features/repo-profile.md`]($HOME/.claude/multi-agent-refs/features/repo-profile.md)). **Local-only repos** (`projects[i].provider == "local"`) have no ticket, and that wins over any profile placement: the subject keeps the conventional prefix with no ticket, and the taskId (`LOCAL-...`) goes in the body footer: `Local-Task: {taskId}`.
+6a. **Valven (required):** `features/valven.md`.
 7. Push to remote  -  **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 4: local-only commit {sha} (no push)` for that repo.
 8. Ask: "Want to open a Pull Request?"
    - **Skip the prompt entirely when `state.offlineOnly == true`** (all repos local  -  no PR target exists). Proceed to Phase 5 with `pr.status = "skipped-offline"` for each project.
@@ -238,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/agent-state.schema.json

@@ -1476,6 +1476,22 @@
         }
       }
     },
+    "valven": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "valven-rules delivery gate. Phase 2 Gate 6 sets splitRequired when a size or scope rule fails; Phase 4 Step 2.95 records the stacked PRs it opened.",
+      "properties": {
+        "splitRequired": { "type": "boolean" },
+        "split": {
+          "type": "object",
+          "properties": {
+            "sliceCount": { "type": "integer", "minimum": 1 },
+            "branches": { "type": "array", "items": { "type": "string" } },
+            "prs": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "diffRisk": {
       "type": "object",
       "additionalProperties": true,

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