@mmerterden/multi-agent-pipeline 20.16.0 → 20.17.0

package/pipeline/skills/shared/core/multi-agent-bug-bash/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: multi-agent-bug-bash
+description: "Bug bash: parallel exploratory sessions by charter and persona, each with a budget; a finding is reported only when a repro test fails for its reason. Use when an app or branch needs broad bug hunting."
+user-invocable: true
+argument-hint: "[scope] [--platform ios|android|web] [--charters <file>]  -  scope: an area, a branch to diff against its base, or empty for the whole app"
+metadata:
+  language: en
+  not-for: test, review, scenario-audit
+---
+
+# multi-agent-bug-bash
+
+**Input**: $ARGUMENTS
+
+Several exploratory sessions run at once, each on one area with one posture.
+What they report are claims. A claim becomes a bug in the report only when a
+reproducing test fails with `ASSERTION_FAILED` on the assertion that encodes it;
+everything else is listed as rejected, with the reason.
+
+Scripts: `$HOME/.claude/scripts/bug-bash.mjs` (charters, merge, proof rule),
+`$HOME/.claude/scripts/explore-findings.mjs` (per-session budget, stop rules,
+judge). Contracts, read before Step 1:
+
+```
+$HOME/.claude/multi-agent-refs/features/exploratory-testing.md
+$HOME/.claude/multi-agent-refs/features/assertion-judge.md
+```
+
+Log dir: `$HOME/.claude/logs/bug-bash/{repo}/{timestamp}/` (`LOG` below).
+
+## Gotchas
+
+- "The explorer reported it" is not "confirmed". No passing proof, no bug.
+- One charter, one area. A charter that spans the app ends at its budget having skimmed everything.
+- Explorers that share an account report each other's edits as bugs: one test account per charter, typed by `secret_ref`.
+- Against a deployed environment other people use, the bash is read-only: no sign-ups, purchases, submissions or injection-shaped input. A firewall block is the firewall working, not a finding.
+- Mobile explorers need one booted device each; web explorers one browser `session` each.
+
+## Step 1 - Prepare
+
+1. Platform: `--platform`, else detect as `multi-agent-test` does. Mobile: list
+   booted devices; the parallel width is `min(4, devices)`. Web: the app URL,
+   width 4.
+2. Toolkit: locators, expect steps, verdict codes, `secret_ref`, `trace.md`,
+   web `session` and `save_as` / `replay` need
+   `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.19.0. On an older server, say so
+   once and run with UI-tree taps; the proof rule does not change.
+3. Ask (one question to the user) for what the local app cannot do: integrations
+   without keys, seed data, what must never be tapped (payments, real
+   accounts), and the test accounts by credential name. This becomes the
+   charter context and the triage reference for Step 5.
+
+## Step 2 - Charters
+
+With `--charters <file>`, use it. Otherwise read the screens, navigation and
+forms (for a branch, `git diff --stat` against its base) and write 5-10
+charters to `$LOG/charters.json`:
+
+```json
+[{"slug": "cart", "persona": "skeptic", "area": "Cart", "start": "Cart tab",
+  "goal": "Starting at the Cart tab, change quantities and check every total against its rows",
+  "budget": {"steps": 6, "minutes": 10, "tokens": 120000}, "account": "bb-cart"}]
+```
+
+Personas: `first-time-user`, `skeptic` (numbers and copy), `fuzzer` (edge
+input; name the exact matrix in the goal), `state-keeper` (relaunch, back,
+reload), `error-paths`, or `custom` with `stance`. Validate:
+
+```bash
+node "$HOME/.claude/scripts/bug-bash.mjs" charters --file "$LOG/charters.json"
+```
+
+Exit 1 lists what to fix. Show the charters in one table and confirm once
+(autopilot: proceed).
+
+## Step 3 - Fan out
+
+One explorer subagent per charter, at most the Step 1 width at a time (one task
+each where the host can start them, otherwise sequentially). Each gets
+its charter, the persona's stance, the Step 1 context, its device or session,
+and these orders:
+
+- Write `$LOG/sessions/<slug>.json` in the explore-run shape as you go: goal,
+  persona, platform, budget, usage, steps, findings.
+- Run `explore-findings.mjs check --run <file>` before every step; stop when
+  it says so.
+- Report every finding with expected, observed, repro, severity 1-5, kind and
+  evidence on disk. Credentials by `secret_ref` only.
+- A visual or semantic claim is decided by a fresh judge (assertion-judge.md),
+  not by you.
+- Never fix anything, never commit.
+
+A session that ends `blocked` is kept: its causes go in the report.
+
+## Step 4 - Merge
+
+```bash
+node "$HOME/.claude/scripts/bug-bash.mjs" merge --sessions "$LOG/sessions" > "$LOG/merged.json"
+```
+
+Candidates `BB-1..n` merge one defect seen by several charters. Warnings and
+findings that failed the contract are kept apart.
+
+## Step 5 - Triage, then verify
+
+Sort every candidate before writing any test; read the source to do it.
+
+| Bucket | Sign | Outcome |
+|---|---|---|
+| artifact | the explorer misread: lazy content not loaded, text split in the tree but whole on screen, a sheet it never scrolled | `rejected` with the check that settled it |
+| environment | fails on a key, service or limit only the local stack lacks | `rejected`; `productionRisk: true` when production users would see the bad handling |
+| design | code, tests or copy say it is intended | `rejected`, citing where |
+| fixture | seed data lacks what real records have | `rejected`, naming the field |
+| candidate | none of the above | verify |
+
+Verify with one subagent per area (up to the Step 1 width), each with its
+candidates and these orders:
+
+1. Read `observed` against the evidence; a contradiction rejects it here.
+2. Write a repro test in the project's own UI test framework (XCUITest,
+   Compose / Espresso, Playwright), or as a toolkit step sequence saved with
+   `save_as` whose last step is an `expect_*` assertion. It follows the repro
+   and asserts `expected`, so it fails today and passes once fixed. Put it under
+   a `BugBash` / `bugbash` directory and keep it out of the gating suite.
+3. Run it alone. Confirmed only when it fails with `ASSERTION_FAILED` on the
+   assertion that encodes the finding (`failedAt` equals `assertion`). A
+   failing XCTest / JUnit / Playwright `expect` on that line counts as
+   `ASSERTION_FAILED`; a build error, timeout, missing element or a different
+   assertion means the test is wrong: fix it and rerun. A passing test means
+   the finding did not reproduce.
+4. Record `$LOG/verifications.json` entries:
+   `{id, status, repro: {path, command, code, assertion, failedAt, trace?}, rootCause?, reason?, note?, productionRisk?}`.
+
+## Step 6 - Report
+
+```bash
+node "$HOME/.claude/scripts/bug-bash.mjs" report --merged "$LOG/merged.json" \
+  --verifications "$LOG/verifications.json" > "$LOG/report.md"
+```
+
+The script demotes any confirmed entry without a passing proof to `unproven`
+and any candidate without an entry to `unverified`. Print the report: confirmed
+bugs first (repro test, root cause, evidence, charters), then unverified
+production risks, rejected by reason, warnings, and the charter table. Close
+with the areas no charter reached and which parts are mechanical (the proof
+rule, the stop rules) versus judgement (triage, the charters themselves).
+
+Then offer, one question: fix the confirmed bugs through `multi-agent` with
+each repro test as the acceptance check (green test = fixed, kept as the
+regression test), or stop. **No commit, no push, no issue from this command.**

package/pipeline/skills/shared/core/multi-agent-review/SKILL.md

@@ -37,7 +37,7 @@ Skip Phase 0-3 and review a diff only. Input shapes: a PR (`#N`, `repo#N`, GitHu
    # bitbucket PR: curl -u "$BB_USER:$BB_TOKEN" .../pull-requests/$N/diff?contextLines=10
    ```
 
-2c. **Valven delivery rules**  -  required on every input. Run `node "$HOME/.claude/scripts/valven-gate.mjs" --mode review --out "$VG_FILE"` plus the input's sources: a branch adds `--repo . --base origin/develop --head <ref>`; a PR adds `--branch <headRef> --pr-body-file <body> --commits-file <one subject per line>` (GitHub `gh pr view --json headRefName,body,commits`, Bitbucket `fromRef.displayId`, `description`, `/commits`) and either `--repo . --base origin/<baseRef> --head FETCH_HEAD` after `git fetch origin <headRef>` when the cwd is that repo, or `--diff-file <patch>` (rework then reports `not-measured`). Exit 0 clean, 1 findings, 2 could not run: print `Valven: not measured (<reason>)`, never "passed". `findings[]` (`tag: valven`) join the reviewer findings at step 5 and are accepted unless the task is exempt, so an `important` one makes step 7 NEEDS WORK. Old-work findings (`VLV-AGE-01`, `VLV-BEHIND-01`, `VLV-TRACE-03`; commit lines are `<ISO author date>\t<subject>`) get the `valven-port.mjs` plan in their fix: new branch, dropped commits, then "open the new PR, close this one". When `splitRequired`, run `valven-split.mjs` with the same base and head (no `--apply`) and add its slice table to the `VLV-SIZE-01` fix. The registry's judgement rules (`VLV-SCOPE-02`, `VLV-PRDESC-02`, from `$HOME/.claude/skills/valven-rules/references/rules.yml`) go into every reviewer prompt in step 3. Contract: `$HOME/.claude/skills/valven-rules/SKILL.md`.
+2c. **Valven delivery rules**  -  required on every input. Run `node "$HOME/.claude/scripts/valven-gate.mjs" --mode review --out "$VG_FILE"` plus the input's sources: a branch adds `--repo . --base origin/develop --head <ref>`; a PR adds `--branch <headRef> --pr-body-file <body> --commits-file <one subject per line> --pr-meta-file <timeline>` (GitHub: `node "$HOME/.claude/scripts/pr-timeline.mjs" --repo <owner/repo> --pr <N> --out <file>` writes the PR with its ready-for-review time and bot-typed reviews; read the head ref, body and commits from it and pass it as the timeline. Bitbucket `fromRef.displayId`, `description`, `/commits`, and a timeline written as `{createdAt, readyAt, isDraft, reviewerCount, firstReviewAt, approvedAt, mergedAt, closedAt}` from the PR and `/activities`, reviews by the author left out) and either `--repo . --base origin/<baseRef> --head FETCH_HEAD` after `git fetch origin <headRef>` when the cwd is that repo, or `--diff-file <patch>` (rework then reports `not-measured`). Exit 0 clean, 1 findings, 2 could not run: print `Valven: not measured (<reason>)`, never "passed". `findings[]` (`tag: valven`) join the reviewer findings at step 5 and are accepted unless the task is exempt, so an `important` one makes step 7 NEEDS WORK. Old-work findings (`VLV-AGE-01`, `VLV-BEHIND-01`, `VLV-TRACE-03`; commit lines are `<ISO author date>\t<subject>`) get the `valven-port.mjs` plan in their fix: new branch, dropped commits, then "open the new PR, close this one". When `splitRequired`, run `valven-split.mjs` with the same base and head (no `--apply`) and add its slice table to the `VLV-SIZE-01` fix. The duration rules (`VLV-CYCLE-01..03`) are `suggestion` findings with a Valven score and never set NEEDS WORK on their own; `VLV-PICKUP-01` is `important` for no reviewer and a `suggestion` for a draft older than 3 hours. Step 6 adds `Valven scores: churn · coding · pickup · review` from the report's `scores`, `-` where one is missing. The registry's judgement rules (`VLV-SCOPE-02`, `VLV-PRDESC-02`, from the `valven-rules` skill's `references/rules.yml`) go into every reviewer prompt in step 3. Contract: the `valven-rules` skill.
 
 3. **Start parallel reviewers**  -  three on every host; only the second slot differs, because GPT-5.4 exists on Copilot and Codex but not on Claude Code, where Opus fills it:
 

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -133,9 +133,13 @@ pbcopy < /dev/null
 Then, **whether they pasted or skipped**, run:
 
 ```bash
-node "$HOME/.copilot/scripts/usage-register.mjs"
+node "$HOME/.copilot/scripts/usage-register.mjs" --json
 ```
 
+If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
+the person's own GitHub account once (the "Personal account" step in
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
+
 It maps whatever token exists and switches reporting on, and requests a
 per-machine write-only one when none resolves. Setup is a registration entry point
 in its own right, so a machine that runs setup and never runs update still reports.

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -33,7 +33,7 @@ Run all steps automatically:
 ```
 Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 63 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 64 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
@@ -96,6 +96,7 @@ If nothing is stale -> report "All targets up to date" and stop.
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh` and `build-stack-plugins.mjs` (generic, synced)
    - Step 3c (PLUGINS): rebuild the `{owner}/multi-agent-plugins` marketplace from `shared/external` via `build-stack-plugins.mjs` (bumps changed plugins' patch version), then commit + push the plugins repo. On any change also verify help + README freshness: every plugin registers `./skills/tools/help` in plugin.json, `tools/bump.py --check` shows no DRIFT, `tools/validate.py` clean (CHANGELOG entry per bumped version), and pipeline help/READMEs reflect any command-surface change from Step 3
    - `~/.claude/settings.json`
+   - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
 
 
 ## Codex Sync (Step 2b)
@@ -228,11 +229,11 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**63 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**64 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
-autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
+autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
 language, log, manual-test, model, prune-logs,

package/pipeline/skills/shared/core/multi-agent-update/SKILL.md

@@ -38,12 +38,15 @@ Update the pipeline with a single command. Preferences are preserved; only skill
 4b. Refresh the stack-plugin marketplace so the latest plugin versions are picked up:
    `bash "$HOME/.claude/scripts/plugin-refresh.sh" {owner}` (adds the marketplace if needed, refreshes it, then runs `claude plugin update` for every installed plugin)
 5. `node migrate-prefs.mjs` (if there is a schema upgrade)
-5b. `node "$HOME/.claude/scripts/usage-register.mjs"` - operational reporting.
+5b. `node "$HOME/.claude/scripts/usage-register.mjs" --json` - operational reporting.
    It requests a per-machine **write-only** token when none resolves, stores it in
    the credential store only, and switches reporting on. A no-op when a token is
    already onboarded, and permanently blocked by `usageLog.optOut: true`. Offline
    or endpoint down leaves reporting off with one line, never an error. Contract:
    `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
+   If its JSON line says `"needsPersonalAccount":true`, offer to tie this machine to
+   the person's own GitHub account once (the "Personal account" step in
+   `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`).
 6. Show the new version + changelog
 7. Smoke test (schema + cross-cli)
 

package/pipeline/skills/shared/external/e2e-testing/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: e2e-testing
+description: |
+  End-to-end testing of a running web or mobile app through the
+  multi-agent-toolkit MCP server: element locators instead of coordinates,
+  expect steps that return passed / failed / blocked verdicts with codes,
+  secrets by secret_ref, failure traces, saved and replayed step sequences,
+  parallel web sessions, and synthetic passport / residence permit / visa
+  fixtures for MRZ and document-scan tests. Use when driving an app on a
+  simulator, emulator or browser to check a flow, writing a repro for a UI
+  bug, or testing an MRZ or document-scan feature.
+metadata:
+  source: multi-agent-pipeline
+  version: 1.0.0
+---
+
+# E2E testing with the toolkit
+
+Drive the app, assert exact outcomes deterministically, leave judgement only
+to what cannot be compared, and keep a step that could not run apart from a
+product that ran and was wrong.
+
+Requires `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.19.0 for everything below
+except the base `ios_*` / `android_*` / `web_*` tools. On an older server, read
+the UI tree, tap frame centres, and say in the result that the run used the
+fallback. Tool inputs come from the server's own schema; the names here are
+the contract.
+
+## 1. Locate, then act
+
+| Platform | Locate | Act |
+|---|---|---|
+| iOS | `ui_locate` | `ios_tap_element`, `ios_type_text` |
+| Android | `ui_locate` | `android_tap_element`, `android_type_text` |
+| Web | `web_snapshot` / `ui_locate` | `web_click`, `web_type`, `web_select_option` |
+
+Locator order: accessibility identifier, then role plus label, then visible
+text. Text is last because it changes with locale and copy edits.
+
+- `LOCATOR_NOT_FOUND`: nothing matched. Read the tree; the element may be
+  off-screen (scroll), not loaded yet (wait), or renamed.
+- `LOCATOR_AMBIGUOUS`: several matched. Narrow by role or container; never pick
+  the first one.
+
+Both are automation failures, not product bugs. Fix the locator and retry once;
+still failing, record the step as blocked (automation).
+
+Coordinates (`ios_tap`, `android_tap`) are for what has no element: a canvas, a
+map, a chart point.
+
+## 2. Assert with expect steps
+
+Inside `agent_run_steps`, an `expect_text`, `expect_element` or `expect_url`
+step checks one exact claim and the run returns a verdict:
+
+| Verdict | Code | Meaning |
+|---|---|---|
+| `passed` | - | every expect step held |
+| `failed` | `ASSERTION_FAILED` | an expect step did not hold: a product failure |
+| `blocked` | `CREDENTIAL_MISSING` | a secret_ref named an unknown credential |
+| `blocked` | `ENVIRONMENT_UNAVAILABLE` | device, browser or backend not reachable |
+| `blocked` | `SEED_DATA_MISSING` | the data the flow needs is not there |
+| `blocked` | `BUDGET_EXCEEDED` | the step or time budget ran out |
+| `blocked` | `REPLAY_DIVERGED` | a replayed sequence no longer matches the screen |
+
+Report blocked apart from failed. "Checkout is broken" and "the run had no test
+account" must never be the same line.
+
+Use an expect step for anything exact: a total, a label, a route, an element
+present or absent. A visual or semantic claim (clipping, contrast, "the error
+explains what to do") is not an expect step: hand it to a fresh judge that sees
+only the claim and the current screenshot or UI tree, never the run that led
+there. Inconclusive is a failure, not a pass.
+
+## 3. Secrets
+
+Type credentials with `secret_ref: "<name>"`, never the value. The value never
+reaches the transcript, a log, a screenshot caption, a finding or a test file.
+A finding names the account (`secret_ref:checkout-user`), not its password.
+
+## 4. Traces, save and replay
+
+- A failed `agent_run_steps` writes a `trace.md`: the steps, the failing step,
+  the screen at failure. Attach its path to the bug, not a paraphrase of it.
+- `save_as: "<name>"` stores a sequence that reached a state; `replay` runs it
+  again. A replay ending in an expect step is a repro: it fails with
+  `ASSERTION_FAILED` while the bug exists and passes once it is fixed.
+- `REPLAY_DIVERGED` means the app no longer follows the recorded path. Look at
+  what changed before re-recording.
+
+## 5. Parallel web sessions
+
+Pass `session: "<name>"` to the web tools to keep sessions apart: one per
+explorer, one per test account. Two explorers on one session or one account
+report each other's edits as bugs.
+
+## 6. A repro that proves a bug
+
+1. Follow the bug's repro steps with locators.
+2. End with the assertion that encodes the expected behaviour.
+3. Run it alone. It proves the bug only when it fails with `ASSERTION_FAILED`
+   on that assertion. Any other failure (a locator, a timeout, a build error, a
+   different assertion) means the test is wrong. A pass means the bug did not
+   reproduce.
+4. Keep it out of the gating suite until the fix lands; then it is the
+   regression test.
+
+In a project test framework the same rule holds: a failing `XCTAssert`,
+JUnit / Compose assertion or Playwright `expect` on the encoding line is
+`ASSERTION_FAILED`.
+
+## 7. MRZ and document-scan features
+
+`document_mrz_build` and `document_generate` produce synthetic passport (TD3),
+residence permit (TD1) and visa (MRV-A / MRV-B) fixtures labelled TEST
+SPECIMEN, with every ICAO 9303 check digit computed. Recipes, edge cases and
+how to get the image into a simulator: `references/document-fixtures.md`.
+
+## Related
+
+- `/multi-agent:test` and `/multi-agent:bug-bash` run this contract with
+  budgets, stop rules and a findings schema.
+- `accessibility-compliance-accessibility-audit` for the accessibility half of
+  a screen check.

package/pipeline/skills/shared/external/e2e-testing/references/document-fixtures.md

@@ -0,0 +1,65 @@
+# Document fixtures for MRZ and document-scan tests
+
+Synthetic travel documents for testing a feature that reads a machine readable
+zone (MRZ): a passport scanner, a residence permit upload, a visa check.
+Requires `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.19.0.
+
+## The two tools
+
+| Tool | Returns | Writes |
+|---|---|---|
+| `document_mrz_build` | `{format, lines, checkDigits, documentNumber, truncated, fields}` | nothing |
+| `document_generate` | the same plus `{path, width, height, label, layout}` | a PNG |
+
+Formats: `passport` is TD3 (2 lines of 44), `residence_permit` is TD1 (3 lines
+of 30), `visa` is MRV-A (2x44, default) or MRV-B (2x36) via `visa_format`.
+
+Main inputs: `type`, `surname`, `given_names`, `nationality`, `issuing_state`
+(defaults to nationality), `birth_date` and `expiry_date` as `YYYY-MM-DD`,
+`sex` (`M`, `F`, `X`), `document_number` (omit it for a deterministic synthetic
+number from `seed`), `optional_data`. `document_generate` adds `output`,
+`include_data_block` and `scale`.
+
+Every PNG carries a fixed "TEST SPECIMEN - NOT A TRAVEL DOCUMENT" label and a
+plain layout. It is a test input for a parser and an OCR pipeline, not a
+document likeness.
+
+## Rules
+
+- Synthetic identities only. Use made-up names and the ICAO test codes (`UTO`
+  for nationality and issuing state) unless the test is about a specific
+  country's rules. Never a real person's data, never a real document number.
+- Fix `seed` in a test so the fixture is the same on every run.
+- Assert on what the app extracted against `fields`, not against a re-read of
+  the image: the tool's `fields` and `checkDigits` are the expected values.
+
+## Getting the fixture to the app
+
+| Path into the app | How |
+|---|---|
+| Photo library import | iOS: `ios_add_media` with the PNG `path`. Android: copy it to the device's pictures folder with adb and trigger a media scan |
+| Debug deep link or test hook | pass `lines` straight in, when the app has a debug entry for MRZ text |
+| Live camera | a simulator or emulator has no camera stream to aim at the image; this path needs a device and stays a manual check. Say so in the result |
+
+## Cases worth a test each
+
+| Case | Input |
+|---|---|
+| Happy path, each format | one `passport`, one `residence_permit`, one `visa` |
+| Long names | a surname or given names longer than the line allows; check `truncated` and that the app does not reject a valid truncated zone |
+| Transliteration | names with diacritics or non-Latin letters; the zone carries the ICAO transliteration, the data block the original |
+| Sex `X` | written `<` in the zone; the app must not require `M` or `F` |
+| Expired document | `expiry_date` in the past; the app's own rule decides, the zone stays valid |
+| TD1 number overflow | a document number longer than 9 characters spills into the optional field |
+| Broken check digit | build a valid zone, then change one digit in `lines` before passing it in; the app must reject it |
+
+## A repro with a fixture
+
+1. `document_generate` with a fixed `seed` and the case's input.
+2. Put the PNG into the app's import path (table above).
+3. Drive the scan with locators.
+4. `expect_text` for each extracted field against `fields`: document number,
+   birth date, expiry date, names.
+
+The last step failing with `ASSERTION_FAILED` on one field is the bug, and the
+same sequence saved with `save_as` is its regression test.

package/pipeline/skills/shared/external/valven-rules/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: valven-rules
+description: "Delivery-flow rules from metrics Valven reports: PR size, one concern per PR, tests with source, issue keys, no WIP commits, churn, PR body, and coding, pickup and review time on Valven's bands. Use when developing, opening or reviewing a pull request held to these rules, or splitting a branch into stacked PRs."
+user-invocable: false
+metadata:
+  source: multi-agent-pipeline
+  language: en
+  standards-registry: references/rules.yml
+---
+
+# valven-rules
+
+The registry is `references/rules.yml`. It holds two blocks:
+
+| Block | Who checks it | Read by |
+|---|---|---|
+| `gate_rules` | the multi-agent pipeline's `valven-gate.mjs`, from the diff, the commits, the branch name, the PR body and the PR timeline | the gate only |
+| `rules` | the reviewers, as judgement | `skill-conformance.mjs`, which puts them in `${CRITERIA}` |
+
+Measured rules stay out of `rules` on purpose: a reviewer asked for a verdict on a line count
+either recounts it or guesses, and both are worse than the number the script already has.
+
+## Development Behaviors
+
+Valven scores four durations and a churn rate per developer. The bands are Valven's table; each
+bound is exclusive.
+
+| Rule | Measures | 100 | 75 | 50 | 0 |
+|---|---|---|---|---|---|
+| `VLV-REWORK-01` | removed lines written in the last 21 days | 0% churn | linear | linear | 100% churn |
+| `VLV-CYCLE-01` | first commit to the pull request opening | < 30 min | < 2.5 h | < 24 h | later |
+| `VLV-CYCLE-02` | ready for review to the first review | < 1 h | < 3 h | < 14 h | later |
+| `VLV-CYCLE-03` | first review to approval or merge | < 30 min | < 3 h | < 18 h | later |
+
+A duration in the 50 or 0 band is a `suggestion`: the time has passed, so the pull request cannot
+fix it, and the finding names the habit that does. `VLV-PICKUP-01` is the part the author can fix
+now: a pull request without a reviewer is `important`; a draft older than 3 hours is a
+`suggestion`, because an unattended run opens a draft on purpose. A pull request still waiting is
+measured up to now, a merged or closed one up to then, and a draft never marked ready has no pickup
+time yet and is not asked for a reviewer. Reviews by the author, by bots, pending ones and ones left
+before the pull request was ready do not count.
+
+The habits behind good scores:
+
+- Open the pull request as soon as the first slice works; ship the next slice as its own PR.
+- Open it ready for review once its gates pass, with the default reviewers assigned.
+- Reviewers check their queue at fixed times every day.
+- Answer every review comment the same day, in one round, and push the fixes together.
+- Settle the requirement before rewriting code written in the last three weeks.
+
+Deploy time is not a rule: a release train or a store review sets it, not the pull request.
+Activity and balance are team distributions, not properties of one pull request.
+
+## Where it runs in the pipeline
+
+| Point | Command | A violation |
+|---|---|---|
+| Phase 1 Step 6 | plan estimates lines per task against `VLV-SIZE-01` | the plan proposes stacked slices before any code exists |
+| Phase 2 exit, Gate 6 | `valven-gate.mjs --mode dev` | blocks the handoff to Review; size findings set `state.valven.splitRequired` |
+| Phase 4, before push | `valven-gate.mjs --mode commit`, then `valven-split.mjs` when a split is required | the branch ships as stacked pull requests, one per slice |
+| Phase 3 Step 1.762 and `/multi-agent:review` | `valven-gate.mjs --mode review`, with `--pr-meta-file` for a pull request | findings merge into triage with `tag: valven`; an accepted important one sets NEEDS WORK |
+
+Thresholds: `prefs.global.valven.thresholds` overrides any rule's numeric keys per rule ID, for
+example `{"VLV-SIZE-01": {"important_over": 300}}`. `prefs.global.valven.enabled: false` turns
+the gate off and logs `valven: disabled by prefs`, so a skipped check never reads as a pass. A
+rule the gate cannot measure is reported `not-measured` with the reason.
+
+## Without the pipeline
+
+Apply the registry by hand before opening or approving a pull request, with the base branch as
+`BASE`. Read each threshold from `gate_rules`, never from memory:
+
+| Rules | Measure with |
+|---|---|
+| `VLV-SIZE-01`, `VLV-SIZE-02`, `VLV-SCOPE-01`, `VLV-HOTFIX-01` | `git diff --numstat -M "$(git merge-base BASE HEAD)"`, generated files, lockfiles and snapshots left out |
+| `VLV-TEST-01` | the same diff: a changed source file without a changed test file |
+| `VLV-TRACE-01..03`, `VLV-COMMIT-01`, `VLV-AGE-01` | `git log --format='%aI %s' BASE..HEAD` and the branch name |
+| `VLV-BEHIND-01` | `git rev-list --count HEAD..BASE` and the merge-base's commit date |
+| `VLV-CYCLE-*`, `VLV-PICKUP-01` | `gh pr view --json author,closedAt,createdAt,isDraft,mergedAt,reviewRequests,reviews`, the ready-for-review time from the pull request's `READY_FOR_REVIEW_EVENT` timeline item and each review author's type (GraphQL), and the oldest commit's author date |
+
+State which rules were measured and which were not; an unmeasured rule is not a pass.
+
+## Splitting and old work
+
+When `VLV-SIZE-01`, `VLV-SIZE-02` or `VLV-SCOPE-01` fails, the branch ships as stacked pull
+requests of at most the size budget: pure renames and moves first, each test file with the source
+it pairs with, then models and services, view models and use cases, views, and the rest. A single
+file larger than the budget is its own slice and is reported, never cut. The pipeline's
+`valven-split.mjs` plans and applies the stack.
+
+`VLV-AGE-01`, `VLV-BEHIND-01` and `VLV-TRACE-03` mean the branch carries old or foreign work. The
+change moves to a fresh branch from the current base as one commit (the pipeline's
+`valven-port.mjs`); the old history is not rebased. Port first, then split.

package/pipeline/skills/shared/{core → external}/valven-rules/references/rules.yml

@@ -1,12 +1,13 @@
-version: 1.0.0
-updated: 2026-10-02
+version: 1.1.0
+updated: 2026-10-07
 owner: delivery flow
 description: >
   Delivery-flow rules derived from the metrics Valven reports per team and per
   developer: cycle time, rework rate, review responsiveness, PR complexity,
-  commit risk, lead time for changes and change failure rate. Valven publishes no
-  formulas or thresholds, so every threshold below is a stated default that
-  prefs.global.valven.thresholds overrides.
+  commit risk, lead time for changes and change failure rate. The Development
+  Behaviors bands (churn, coding, pickup and review time) are Valven's own scoring
+  table; every other threshold is a stated default, because Valven publishes no
+  formula for it. prefs.global.valven.thresholds overrides any of them.
 
 # The whole change set is in scope: these rules judge the shape of a pull
 # request, not the language inside it. Generated output, lockfiles and recorded
@@ -79,7 +80,7 @@ gate_rules:
     fix: squash them into the commit they amend before pushing
   - id: VLV-REWORK-01
     title: At most 30% of the removed lines were written in the last 21 days
-    metric: Rework Rate
+    metric: Rework Rate, Churn rate (Development Behaviors, scored 100 - churn %)
     severity: important
     ratio_over: 0.30
     window_days: 21
@@ -125,6 +126,51 @@ gate_rules:
     modes: [commit, review]
     fix: move the commits of the other issue to their own branch and PR
 
+  # Development Behaviors: cycle time breakdown. Each duration is scored into
+  # Valven's bands (100 / 75 / 50 / 0; every bound exclusive). A score of 50 or
+  # 0 is reported as a suggestion: the time has already passed, so the pull
+  # request cannot fix it, and the finding names the habit that does. Deploy
+  # time is not a rule: a release train or a store review sets it, not the
+  # pull request.
+  - id: VLV-CYCLE-01
+    title: Coding time, from the first commit to opening the pull request, stays under 2.5 hours
+    metric: Cycle Time (coding)
+    severity: suggestion
+    full_under_minutes: 30
+    three_quarter_under_minutes: 150
+    half_under_minutes: 1440
+    modes: [commit, review]
+    fix: open the pull request as soon as the first slice works; ship the next slice as its own pull request
+  - id: VLV-CYCLE-02
+    title: Pickup time, from ready-for-review to the first review, stays under 3 hours
+    metric: Cycle Time (pickup), Review Responsiveness
+    severity: suggestion
+    full_under_minutes: 60
+    three_quarter_under_minutes: 180
+    half_under_minutes: 840
+    modes: [review]
+    fix: assign the reviewers when the pull request opens; reviewers check their queue at fixed times every day
+  - id: VLV-CYCLE-03
+    title: Review time, from the first review to approval, stays under 3 hours
+    metric: Cycle Time (review), Review Responsiveness
+    severity: suggestion
+    full_under_minutes: 30
+    three_quarter_under_minutes: 180
+    half_under_minutes: 1080
+    modes: [review]
+    fix: answer every comment the same day in one round and push the fixes together
+  # A missing reviewer is important: the author fixes it now. A long-lived
+  # draft is a suggestion, because an unattended run opens a draft on purpose
+  # and a person decides when it is ready.
+  - id: VLV-PICKUP-01
+    title: A pull request has a reviewer and does not sit as a draft for more than 3 hours
+    metric: Cycle Time (pickup), Review Responsiveness
+    severity: important
+    draft_minutes_over: 180
+    draft_severity: suggestion
+    modes: [review]
+    fix: assign the default reviewers; mark the pull request ready for review once its gates pass, or close it
+
 # Judgement rules. skill-conformance.mjs selects these for every diff, so each
 # reviewer returns a verdict per ID.
 rules:

package/pipeline/skills/skills-index.md

@@ -3,7 +3,7 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**221 skills** across 2 groups.
+**223 skills** across 2 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
@@ -54,6 +54,7 @@
 | external | `debugging-strategies` |  -  | Language-neutral debugging method: reproduce, minimise, falsifiable hypotheses, git bisect, instrumentation, production traces, concurrency  |
 | external | `device-integrity` |  -  | DeviceCheck and App Attest: DCDevice tokens and per-device bits, DCAppAttestService key generation, attestation and assertions. Use when add |
 | external | `docker-expert` |  -  | Dockerfiles and images: multi-stage builds, BuildKit cache and secret mounts, slim or distroless bases, non-root, healthchecks, scanning, mu |
+| external | `e2e-testing` |  -  | End-to-end testing of a running web or mobile app through the multi-agent-toolkit MCP server: element locators instead of coordinates, expec |
 | external | `energykit` |  -  | EnergyKit on iOS 26: grid electricity forecasts via ElectricityGuidance, EnergyVenue, EV and HVAC load events, ElectricityInsightService his |
 | external | `eventkit-calendar` |  -  | EventKit and EventKitUI: adding events to the user's calendar, creating reminders, recurrence rules, calendar or reminders access, event edi |
 | external | `evidence-github` |  -  | Search GitHub for facts an analysis can cite - a known issue in a dependency, the PR that fixed it, what a release actually changed, prior a |
@@ -100,6 +101,7 @@
 | core | `multi-agent-autopilot-off` |  -  | Turn off continuous mode on this machine: the schedule is removed, work already running finishes, the repo selection is kept. Use when the m |
 | core | `multi-agent-autopilot-on` |  -  | Turn on continuous mode on THIS machine: pick the repos it watches; labelled GitHub issues and assigned+labelled Jira items then run in a wo |
 | core | `multi-agent-autopilot-status` |  -  | Show what continuous mode is doing here: what runs at which phase, what is queued, what waits for an answer, what PRs it opened today. Use w |
+| core | `multi-agent-bug-bash` |  -  | Bug bash: parallel exploratory sessions by charter and persona, each with a budget; a finding is reported only when a repro test fails for i |
 | core | `multi-agent-build-optimize` |  -  | Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analy |
 | core | `multi-agent-channels` |  -  | Multi-channel reporter  -  Jira/Confluence/Wiki/PR description. Multi-select channels + content, humanizer pass, reviewer-preserving Bitbuck |
 | core | `multi-agent-complaint-analysis` |  -  | Customer-complaint triage. Ingests complaints (paste, csv/xlsx/txt/json file, Jira issue, Confluence URL), fetches Graylog evidence per trx/ |
@@ -215,7 +217,7 @@
 | external | `testing-backend` |  -  | Backend testing: pytest patterns (Python), Jest patterns (Node.js), integration testing, database fixtures/factories, API contract testing.  |
 | external | `tipkit` |  -  | TipKit in-app tips (iOS 17+): Tip protocol, TipView, popoverTip, rules, events, TipGroup, styles, CloudKit sync. Use when building or review |
 | external | `typescript-patterns` |  -  | Modern TypeScript patterns: strict mode, utility types, generics, conditional types, type guards, discriminated unions, Zod validation. Use  |
-| core | `valven-rules` |  -  | Delivery-flow rules from the metrics Valven reports: PR size, one concern per PR, tests with source, issue keys, no WIP commits, rework, PR  |
+| external | `valven-rules` |  -  | Delivery-flow rules from metrics Valven reports: PR size, one concern per PR, tests with source, issue keys, no WIP commits, churn, PR body, |
 | external | `vision-framework` |  -  | On-device computer vision with Vision and VisionKit: OCR, face detection and landmarks, barcode and QR scanning, person and instance segment |
 | external | `vue-composition` |  -  | Vue 3 Composition API: ref, reactive, computed, watch, composables, Pinia state management, Vue Router 4, script setup. Use when building or |
 | external | `weatherkit` |  -  | WeatherKit on iOS: current, hourly, daily and minute forecasts, alerts, historical statistics, dataset selection, caching. Use when integrat |