Perf Fleet

# Perf Fleet

> Autonomous performance-budget/regression remediation sweep — enumerate the perf-budget-violation and runtime-regression backlog by composing the existing perf detectors (`check_performance`, `harness check-perf`, the benchmark baselines), fold the codebase into independent remediation targets, rank them by severity value, confirm the batch with the human in one up-front round, fan out worktree-isolated subagents that each run the **real** per-target measure → remediate → re-measure pipeline gated by a measured before/after, independently verify every result by a re-measurement that proves the budget is met plus updated baselines plus all-OS CI, and hand back a tiered batch of perf-fix PRs and filed redesign issues for one bulk review. The fleet never auto-merges, never rebaselines a regression away, and never trusts a subagent's self-report.

Working a performance backlog down by hand is a per-target attention slog: every budget violation and runtime regression must be found, its before-state measured, its remediation scoped, driven to a proven improvement, and turned into a reviewable PR — one at a time, with a human present throughout. For a codebase with dozens of hot paths and complexity hotspots the human's attention, not the machinery, is the bottleneck. `perf-fleet` inverts the model: it enumerates the backlog by composing the existing perf detectors, runs the real per-target pipeline autonomously and in isolation for each target, verifies the result against a re-measurement, and returns **perf-fix PRs to review in bulk** plus **filed issues** for the redesigns too large to auto-fix — moving the human from "remediate every regression" to "confirm the batch once, review the batch once." It is a **quality-queue** member of the `-fleet` family: it does not sit on the core intake → decide → build → land spine, but works the performance queue alongside it.

The defining property is its verification bar. A performance "fix" that is not measured is a guess, and the cheapest way to make a red gate green is to move the goalpost — relax the budget or rebaseline the regression away. `perf-fleet` therefore holds a **measured before/after bar**, the perf analog of `bug-fleet`'s reproduction bar: a target is not remediated until a re-measurement against unmodified baselines proves the budget is now met. **No measured before/after, no fix** — and a "remediation" that only edited the baseline or the threshold fails that bar by design.

This skill builds on the shared `-fleet` spine documented in `docs/reference/fleet-family.md` — the five-phase SELECT → CONFIRM → DISPATCH → VERIFY → terminal skeleton, the concurrency governor, the artifact + all-OS-CI verification discipline, the base-freshness clause, the worktree fan-out with its `.claude/`-nested push caveat, the per-leaf context-replay budget, the canonical `FleetHandoffRecord` handoff, and the never-silent-merge invariant. That page states the family contract once; this SKILL.md defines only what is `perf-fleet`'s own: its queue, its triage taxonomy, its per-target pipeline, its tiered terminal act, and its domain-specific rationalizations.

## Boundary — perf-fleet vs cleanup-fleet vs cicd-fleet

The `-fleet` family already has two neighbours that touch performance-adjacent concerns; perf-fleet is scoped so it composes the detectors they share, never overlaps their queues:

| Fleet           | Queue it works                                                         | What it does NOT own                                                                   |
| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `perf-fleet`    | **measured perf-budget violations + runtime regressions** (bench/gate) | maintainability entropy with no measurement; a red CI run (that is the two neighbours) |
| `cleanup-fleet` | code entropy / structural hotspots (dead code, drift, coupling)        | whether a hotspot is a _measured_ perf-budget violation — that needs a benchmark       |
| `cicd-fleet`    | CI/CD-red and flaky-test runs (a failure already manifested in CI)     | a perf regression the gate has not yet caught, or a proactive budget sweep             |

The line is **the measurement bar**. A high-complexity function is `cleanup-fleet`'s when the goal is maintainability entropy; it is `perf-fleet`'s only when it is a **measured** perf-budget violation (a Tier-1/2 structural gate breach or a benchmarked runtime regression). A perf regression that has already turned CI red is `cicd-fleet`'s to heal from the red signal; `perf-fleet` proactively sweeps the budget/regression backlog and gates every fix on a fresh before/after measurement. perf-fleet composes `harness-perf` (which owns `check-perf` and the benchmark baselines) — it reimplements no perf measurement.

## When to Use

- A performance backlog has accumulated (structural complexity/coupling budget breaches, benchmarked runtime regressions on hot paths, size-budget violations) and needs autonomous remediation plus one bulk review
- Clearing performance debt across many independent hot paths where per-target interactive remediation does not scale
- Turning the output of `check_performance` / `harness check-perf` / the benchmark baselines into a set of verified, scoped, merge-ready perf-fix PRs (and filed issues for the redesigns) in a single session
- After a batch of merges that plausibly regressed performance across many modules at once
- When the targets are genuinely independent — each is a distinct hot path or hotspot producing its own PR, and remediating one does not depend on another's merge
- NOT for a single regression — invoke `harness-perf` (and `harness-debugging` for the fix) directly; a fleet's overhead only pays off across a batch
- NOT for landing / merging PRs — that is `pr-fleet`; `perf-fleet` stops at merge-ready and never merges
- NOT for enforcing the perf gate on one PR's diff — that is `harness-perf` inline; a fleet fans out across many standing targets, it is not a per-PR gate
- NOT for maintainability entropy with no measurement — that is `cleanup-fleet`; perf-fleet works only the **measured** perf-budget/regression queue

## Flags

| Flag            | Effect                                                                                                               |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--concurrency` | Cap concurrent remediation subagents (default 2, max recommended 3 — the machine-storm limit)                        |
| `--report-only` | Enumerate, score, and present the ranked target batch; do not dispatch, verify, or open PRs                          |
| `--dry-run`     | Run SELECT and CONFIRM only; stop before fan-out                                                                     |
| `--safe-only`   | Restrict remediation to the safe fix class (file the risky redesigns as issues) even if a risky fix looks mechanical |

## Process

### Iron Law

**A perf-fix PR is "merge-ready" only after an independent re-measurement proves the budget is met against unmodified baselines, plus all-OS-CI verification. The fleet never auto-merges, never applies a risky redesign autonomously, never rebaselines or relaxes a threshold to clear a violation, and never accepts a subagent's self-report as proof its pipeline ran.**

A subagent that reports "optimized it — regression gone, CI green" has told you what it believes, not what is true. The only evidence that the real per-target pipeline ran and worked is the measured before/after it necessarily produces — the violation the target opened with (from SELECT) is re-measured **gone** against the same baselines — plus the CI signal on the pushed branch. If the re-measurement still shows the budget breached, the remediation did not land, regardless of how confident the report reads. And the cheapest fake green is the goalpost move: a "fix" that edited `.harness/perf/baselines.json` to match the new slower numbers, or relaxed a Tier threshold, is not a remediation — it is a suppression, and it fails the against-unmodified-baselines re-measurement by design. Landing the batch is the human's call: the fleet stops at a set of verified, reviewable PRs plus filed issues.

```
Phase 1: SELECT --> Phase 2: CONFIRM --> Phase 3: DISPATCH
                                                    |
                                                    v
                     Phase 5: REPORT <-- Phase 4: VERIFY
```

| Phase       | Purpose                                                                                   | Exit Condition                                                                |
| ----------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 1. SELECT   | Compose perf detectors into targets, cross-check, score by severity value                 | Ranked `Target[]` with fix class, measured before-state, cross-check verdicts |
| 2. CONFIRM  | One up-front human round: approve/trim, confirm safe/risky calls, set cap                 | Human-approved batch with confirmed classes and agreed concurrency            |
| 3. DISPATCH | Worktree-isolated subagents run the real measure → remediate → re-measure per target      | Every confirmed target returned a branch, filed, parked, or failed (recorded) |
| 4. VERIFY   | Independent before/after re-measurement + baseline-honesty + all-OS-CI, never self-report | Each returned target marked verified / rejected / retry                       |
| 5. REPORT   | One-row-per-target tiered summary (fix PRs + filed issues); never merge                   | Report delivered; risky redesigns filed with evidence for the human           |

### Phase 1: SELECT — Compose Perf Detectors, Measure, Cross-Check, Score

1. **Enumerate the perf-budget/regression backlog by composing the existing detectors — reimplement no perf measurement.** Run and fold together:
   - `check_performance` — the current performance posture against defined budgets.
   - `harness check-perf --structural` and `--coupling` — complexity, nesting, size, and fan-in/fan-out budget breaches (Tier 1/2/3), and `get_critical_paths` for the hot-path set that carries the stricter thresholds.
   - the benchmark regression detector — `harness perf bench` compared against `get_perf_baselines` (`.harness/perf/baselines.json`), with the noise margin applied before flagging.
   - a git-churn pass over the perf-critical source (`git log --format=format: --name-only --since=...`) to surface hot paths whose code moved recently.

   Missing any one source degrades to whichever detectors are available; record which source was unavailable rather than aborting. If the project has no `.bench.ts` files, the benchmark tier is simply empty — the structural/coupling budget queue still stands. **Verify the toolchain first** (spine § _Runtime preconditions_): record the resolved `harness --version` and treat a stale scanner's findings as untrusted.

2. **Fold findings into remediation targets.** A **target** is one coherent hot path or hotspot cluster — the unit that becomes one PR (or one filed issue). Group co-located findings on the same function/module into a single target; never split a coherent optimization across PRs, and never bundle unrelated hot paths into one.

3. **Capture the measured before-state for every target.** A target enters the queue only with a **measured violation** recorded — the benchmark number vs its baseline (and the delta%), or the structural metric vs its threshold and tier. This before-state is the anchor VERIFY re-measures against; a target with no measurement is not a perf target, it is a maintainability finding (which is `cleanup-fleet`'s).

4. **Classify each target's fix class** by the remediation it needs:
   - **safe** (auto-remediated → fix PR): a bounded local optimization that provably meets the budget without changing public API or observable behaviour — an algorithmic fix in one function, removing an N+1 query, memoizing a hot computation, or an extract-method that lowers cyclomatic complexity below the threshold.
   - **risky** (filed as an issue for the human): a large or architectural redesign, a change on a correctness-sensitive hot path, or any optimization that alters a public API or observable behaviour. It is **filed with its measurement evidence attached**, never auto-applied — the perf analog of `bug-fleet` filing a risky-fix bug rather than patching it.

5. **Cross-check each target against merged and open PRs.** For every target, search merged/open PRs for one that already optimized that path. A target whose hot path was already remediated is **already-optimized** — flag it for drop/annotate, not re-remediation. (An open perf PR is a live claim; drop the target — see spine § _Cross-run claim lease_ for the ID-based-member mechanism, of which perf-fleet uses only the open-PR cross-check degradation, since a hot path has no GitHub-native id at SELECT.)

6. **Score and order by composite severity value.** Do not rank ad-hoc. Reuse `roadmap-pilot`-style impact scoring over a composite of **tier severity (Tier 1 > Tier 2 > Tier 3) × critical-path weight (a hot path outranks a cold one) × churn**, so the most severe regressions on the busiest hot paths come first and selection is principled and reproducible.

7. **Build the `Target` record** for each survivor:

   ```
   Target {
     sources,           // which detectors surfaced it (may be several)
     id,                // target slug
     area,              // function / module / hot path the target covers
     violation,         // the measured before-state: metric vs threshold/baseline + tier + delta%
     fixClass,          // "safe" | "risky"
     score,             // composite severity-value score
     crossCheck,        // "novel" | "already-optimized"
     resolvingPr,       // set when crossCheck = already-optimized
     forks,             // detected risky-redesign forks (may be empty)
   }
   ```

### Phase 2: CONFIRM — The Single Up-Front Human Gate `[checkpoint:human-verify]`

1. **Present the ranked target batch in one round.** This is the **only guaranteed human touchpoint before review** — everything downstream runs autonomously. Present, together, in a single surface:
   - The ranked targets (highest-severity first) with scores and the **measured violation** each opens with (metric vs threshold/baseline, tier, delta%).
   - Each target's **safe / risky** fix classification — with risky targets flagged as they will **file an issue** (never auto-remediate).
   - Already-optimized targets **flagged for drop** with the resolving PR.
   - The **proposed concurrency** (default 2, capped at ~3).

2. **The human approves or trims once, and confirms the classifications.** Batch approval, safe/risky confirmation, and already-optimized triage all happen in this same gate — front-loading the genuinely-ambiguous calls is what keeps wrong-remediation rework low. A target the human downgrades to risky is filed rather than remediated.

3. **From here it is autonomous.** After this gate the fleet does not pause per-target. The only thing that re-surfaces to the human before REPORT is a target that turns out mid-flight to need a **risky** redesign (see DISPATCH) — and even that files only that one target without blocking the batch. Under `--dry-run` the skill stops at the end of this phase.

### Phase 3: DISPATCH — Worktree Fan-Out With a Concurrency Governor

1. **One worktree-isolated subagent per confirmed target, running the real measure → remediate → re-measure pipeline.** Each subagent is briefed to run the **real** per-target pipeline for its one target — it does not hand-optimize blind and it does not short-cut the pipeline; the measured before/after the pipeline produces is what VERIFY checks for:
   - **MEASURE** — establish the before-state on unmodified code with `harness-perf` (`harness perf bench` for a runtime regression, or `harness check-perf` for a structural budget breach). This must reproduce the violation SELECT recorded; a violation that does not reproduce is reported and the target dropped (a stale finding, never a fabricated fix).
   - **REMEDIATE** — drive the fix with the real fix skill for the target's cause: `harness-debugging` to diagnose and fix a runtime regression (the same diagnosis-and-fix pipeline `bug-fleet` uses), or `harness-refactoring` to bring a structural complexity/coupling breach under budget. The fix must be the safe class — bounded, and not altering public API or observable behaviour.
   - **RE-MEASURE** — re-run the same `harness-perf` measurement and confirm the budget is now met. Persist the new numbers with `update_perf_baselines` (`harness perf baselines update`) **only to record a genuine improvement** — never to move a red budget to match slower numbers.

2. **A target that needs a risky redesign files an issue; it never auto-remediates.** A subagent runs autonomously on the safe class for its target. But if meeting the budget turns out to require a **risky** change — a large/architectural redesign, a correctness-sensitive hot-path change, or a public-API/behaviour change — that target **files an issue with its measured before-state and a recommendation** instead of applying the fix. Filing is per-target: the other targets in the batch continue uninterrupted. The filed redesign appears in REPORT for the human.

3. **Cap concurrency at the governor (default 2, max ~3).** This is the machine-storm limit: beyond roughly three concurrent remediation agents the compound load produces flaky failures indistinguishable from real ones — **and it poisons the benchmark signal**, since a stormed machine's timings are noise, not measurement. Never exceed the confirmed concurrency to "go faster"; a benchmark run under load is worthless. Run each target's benchmark on a quiet machine with a clean working tree (`harness-perf`'s dirty-tree guard).

4. **Consult the per-leaf context-replay budget before fan-out.** A hot-path remediation can pull wide source context (a regression that spans several call sites). Estimate each leaf's context load and call `assertLeafWithinBudget` before dispatching it; an over-budget leaf is rejected loudly at dispatch, never silently spent. Assemble each leaf's working context **graph-scoped by default** (retrieve via `code_outline`/`get_critical_paths`/`find_context_for`, read raw source only for the region under optimization). See spine § _The per-leaf context-replay budget_.

5. **Record an "assumptions made" note per target.** Each subagent records the ranking basis, the remediation scope it took, the safe-vs-risky call it made, and the **before/after numbers with the noise margin applied**, so the eventual PR carries an assumptions note — batch review is only trustworthy when the reviewer can see the measurement, what was assumed, and what was deliberately left un-remediated.

6. **Push-path caveat.** A worktree created under a `.claude/`-nested path breaks the local pre-push gates (it self-excludes and scans zero files). Subagents push via the GitHub API or from a non-`.claude` throwaway worktree. **Never `--no-verify`** — bypassing the gate defeats the verification the fleet depends on.

**Worker handoff — return the canonical `FleetHandoffRecord`.** When a worker finishes its target it hands the orchestrator exactly one `FleetHandoffRecord` (from `@harness-engineering/types`) — the ONE bounded envelope every `-fleet` member emits, so `fleet-command` parses any fleet's worker output uniformly instead of special-casing an ad hoc per-worker report shape. The record carries `status` (`done | parked | blocked | failed`), `fleet`, `item`, a one-line `summary`, an `evidence[]` of verifiable pointers (branch, PR, filed-issue number, baseline path, CI check — exactly the references VERIFY re-checks), `next_steps[]`, and, for any non-`done` status, a `blocker`. The measured before/after and the fix-class live inside the record's `summary`/`evidence`. The orchestrator validates it with `validateFleetHandoffRecord`; a malformed or unknown-keyed record is rejected, never silently misread. See the canonical handoff record in `docs/reference/fleet-family.md`.

### Phase 4: VERIFY — Independent Confirmation, Never Self-Report

1. **Never accept a subagent's self-report as verification.** "The regression is gone and CI is green" is a claim to be checked, not a result. For each returned branch, the orchestrator independently confirms the evidence itself.

2. **Require the measured before/after artifact against unmodified baselines.** Confirm the target actually improved:
   - The violation the target opened with (from SELECT) is **re-measured gone** — re-run the same `harness-perf` measurement on the branch and confirm the budget is now met.
   - The improvement is measured **against the baselines the target opened against**, not against a baseline the branch edited. Diff `.harness/perf/baselines.json`: a baseline update is legitimate only when it **records a faster number** for the target; a baseline moved to match a slower number, or a Tier threshold relaxed, is a **goalpost move** — reject it.

   A branch whose re-measurement **still shows the budget breached did not remediate** — regardless of what the subagent reported. Reject it (or retry once); it is never marked merge-ready.

3. **Require all-OS CI green.** Confirm the pushed branch's CI is green on **all target operating systems** plus the project's required checks (`gh pr checks` / `gh run list`), including the repo's own perf gate. Green on one OS is not green. A subset-red branch is not merge-ready — it is reported as failed, and the batch continues. **Base freshness (spine clause):** all-OS green is trusted as `verified` only when it ran against **current `main`** — the branch is up to date with `main`, or branch protection enforces strict / up-to-date-before-merge. Green gathered against a base `main` has since moved past is **stale** (and a perf baseline drifts as `main` churns): downgrade the item to **`degraded`**, not verified, and report the stale tested base SHA vs current `main`. See `docs/reference/fleet-family.md` § _Base freshness_ (`classifyBaseFreshness`).

4. **Classify each returned target** as `verified` (re-measured budget-met against unmodified baselines + all-OS CI green against a fresh base), `filed` (risky redesign, issue opened with evidence — not a PR), `rejected` (did not improve, or gamed the baseline, or definitively red), or `retry` (transient, retried at most once). No target reaches REPORT as merge-ready without passing both the re-measurement and the CI check.

### Phase 5: REPORT — Tiered Batch Summary, Never Merge

1. **Emit a one-row-per-target tiered batch summary** for bulk human review:

   | Target | Verdict | PR / Issue | Before → After | Findings resolved | Assumptions made | Filed redesign |
   | ------ | ------- | ---------- | -------------- | ----------------- | ---------------- | -------------- |

   Every verified target's row carries its PR link, the **before → after numbers** (with noise margin), the assumptions-made note from DISPATCH, and the tier it cleared. Filed targets carry their issue link and the recommendation. Rejected/failed targets are listed with the reason.

2. **The terminal act is tiered — fix PRs plus filed issues.** Verified safe-class targets are delivered as **merge-ready perf-fix PRs**; risky redesigns are delivered as **filed issues carrying the measurement evidence** (before-state, tier, recommendation) — the same tiered output `bug-fleet` produces (fix PRs for the bounded, filed issues for the risky). A filed issue is a first-class outcome, not a failure.

3. **Annotate already-optimized targets accurately.** For each target flagged already-optimized in SELECT and confirmed in CONFIRM, record it as dropped with a note **citing the resolving PR** — never a re-remediation.

4. **Never merge.** The fleet delivers verified, reviewable perf-fix PRs; the human (optionally via `pr-fleet`) lands the batch. Auto-merging a perf PR is out of scope by design — a subtly wrong optimization on a hot path is exactly where the one review the model is built around must happen.

5. **Degrade gracefully.** A missing detector source, an already-optimized target, or a single target's non-improving remediation results in that target (or source) being **reported** while the rest of the batch proceeds. One bad target never sinks the batch.

## Harness Integration

- **`harness skill run perf-fleet`** — Run the full five-phase batch pipeline.
- **`check_performance`** — Composed in SELECT to assess the current performance posture against budgets.
- **`harness check-perf` (`--structural` / `--coupling`)** — Composed in SELECT for the structural/coupling budget queue; re-run in VERIFY as the independent structural re-measurement.
- **`get_perf_baselines`** — Read in SELECT to compare benchmark results against the recorded baselines, and in VERIFY to diff the branch's baseline changes for goalpost moves.
- **`update_perf_baselines`** — The only sanctioned way to persist new numbers; DISPATCH calls it to record a genuine improvement, never to mask a regression. Baselines are never hand-edited.
- **`get_critical_paths`** — Composed in SELECT to weight hot paths (stricter thresholds) above cold ones in scoring.
- **`harness-perf`** — The real measurement/benchmark pipeline each DISPATCH subagent runs for its before/after; the fleet composes it and never reimplements perf measurement.
- **`harness-debugging`** — The real fix pipeline for a runtime regression with an investigable cause (the diagnosis-and-fix pipeline `bug-fleet` also uses).
- **`harness-refactoring`** — The real fix pipeline for a structural complexity/coupling budget breach.
- **`harness-roadmap-pilot`** — Its impact-scoring approach is reused in SELECT to order targets by composite severity value.
- **`gh`** — Cross-check merged/open PRs (SELECT), read `gh pr checks` (VERIFY), open the perf-fix PRs and file the redesign issues (REPORT).
- **`harness skill validate perf-fleet`** — The authoring-time gate for this skill's own structure and schema.
- **`docs/reference/fleet-family.md`** — The shared `-fleet` spine this skill builds on (the five-phase skeleton, the concurrency governor, the per-leaf context budget, the artifact/CI verification discipline, the base-freshness clause, the worktree fan-out, the canonical handoff record, and the never-silent-merge invariant), stated once for the family.

## Success Criteria

- Given a confirmed batch of N targets, the fleet produces **up to N** outcomes — perf-fix PRs for the safe class, filed issues for the risky class — each safe-class PR carrying a verified before/after re-measurement (budget met against unmodified baselines) and green CI across all target operating systems plus the project's required checks.
- There is **exactly one** up-front human decision round; no per-target interactive pauses except a genuinely-risky redesign filed to its own target.
- **Every emitted PR carries an "assumptions made" note** with the before/after numbers, the noise margin, and the ranking basis.
- Risky redesigns are **filed with their measurement evidence, never auto-applied**.
- Already-optimized targets are **dropped/annotated with a resolving-PR citation, not re-remediated**.
- No target is marked merge-ready on a baseline edit or threshold relaxation — every verdict is a re-measurement against **unmodified** baselines.
- The skill **never auto-merges** a perf-fix PR.
- It **degrades gracefully**: a missing detector source or a single target's non-improving remediation is reported while the batch continues.
- Concurrency never exceeds the confirmed governor (default 2, max ~3), and benchmarks run on a quiet machine with a clean tree.

## Gates

- **No "merge-ready" without a verified before/after re-measurement.** A target whose re-measurement still shows the budget breached did not remediate. It is rejected or retried — never reported as merge-ready, no matter what the subagent claimed.
- **No "merge-ready" without all-OS CI green against a fresh base.** Green on a subset of operating systems (or with the perf gate red), or green gathered against a base `main` has moved past, is not verified. Report subset-red as failed; downgrade stale-base green to `degraded` and refresh before it can authorize anything.
- **Never move the goalpost.** Editing `.harness/perf/baselines.json` to match slower numbers, or relaxing a Tier threshold, is suppression, not remediation — it fails the against-unmodified-baselines re-measurement by design. Baselines are updated via `update_perf_baselines` only to record a genuine improvement.
- **Never auto-apply a risky redesign.** Large/architectural redesigns, correctness-sensitive hot-path changes, and public-API/behaviour changes are **filed as issues** with the measurement evidence; the fleet applies only the safe class autonomously.
- **Never auto-merge.** The fleet stops at reviewable PRs. Merging a perf PR from inside the fleet = gate violation; the human lands the batch.
- **Never exceed the concurrency governor.** More than ~3 concurrent remediation agents is the machine-storm zone — and it poisons the benchmark signal. Do not raise the cap to "go faster."
- **A self-report is never verification.** Accepting "regression gone, CI green" without independently re-measuring against unmodified baselines and checking CI = gate violation. Re-verify independently.
- **Never fabricate a fix for an unreproducible violation.** If MEASURE cannot reproduce the SELECT violation on unmodified code, the finding is stale — drop the target and report it; never author a "fix" for a violation that does not exist.
- **Never `--no-verify`.** No subagent bypasses the pre-push gates; a `.claude/`-nested worktree pushes via the GitHub API or a non-nested worktree instead.

## Escalation

- **A detector source is unavailable (`check_performance` errors, no `.bench.ts` files, no baselines, no git history):** proceed with whichever detectors are available; record the missing source in REPORT rather than aborting. If no detector is available, stop and report — there is nothing to enumerate.
- **MEASURE cannot reproduce the SELECT violation:** the finding is stale (the code already changed, or the scanner was out of step). Drop the target and report it as "did not reproduce" — never fabricate a fix. The batch continues.
- **A subagent returns a branch whose re-measurement still shows the budget breached:** do not accept its self-report. Reject or retry once; if it still does not meet the budget, report the target as "did not improve" and move on — the batch continues.
- **A target needs a risky redesign to meet the budget:** file an issue with the measured before-state and a recommendation; do not apply the redesign, and continue. The filed target is the only one affected.
- **CI red on a subset of OS:** report the target failed with the failing OS/check named; never mark it merge-ready. Do not average a mixed CI result into "mostly green".
- **The batch appears coupled (one target's optimization depends on another's merge):** stop fanning out those targets; the coupling means they are one convergence pipeline, not a fleet. Escalate to the human to sequence them.

## Rationalizations to Reject

| Rationalization                                                                          | Reality                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The subagent reported the regression is gone and CI is green, so the target is fixed"   | A self-report is a claim, not evidence. Independently re-measure with `harness-perf` against the unmodified baselines and confirm CI — or the remediation did not land.       |
| "The benchmark baseline is stale anyway — just update it to the new numbers and move on" | Updating the baseline to match slower numbers is a goalpost move, not a fix. It fails the against-unmodified-baselines re-measurement by design; fix the regression.          |
| "The complexity threshold is a bit conservative — relax it for this one function"        | Relaxing a Tier threshold to clear a violation is suppression. Bring the function under the budget (extract-method), or file the redesign — never move the line.              |
| "This regression is only 6% — it's probably just noise, ship it"                         | The noise margin (default 3%) is applied before flagging; a 6% regression on a critical path exceeds the Tier-1 bar even after noise. Measure, do not hand-wave.              |
| "This hot path needs a big architectural rewrite — I'll just do it while I'm in here"    | A large/architectural redesign is the risky class. It is filed with its measurement evidence for the human, never auto-applied on a hot path.                                 |
| "I'll bundle every target's optimization into one big perf PR"                           | Scope one coherent target per PR. A mega-perf-PR is un-reviewable and un-revertible; the whole model depends on the reviewer holding one target's before/after in their head. |
| "I'll hand-optimize this one target — it's faster than driving the whole pipeline"       | Dogfood the real per-target skill. A hand-optimized target leaves no measured before/after, fails VERIFY, and breaks the guarantee that every PR ran the audited pipeline.    |
| "The SELECT finding is clear enough — I'll fix it without re-measuring the before-state" | No measured before/after, no fix. A violation that does not reproduce on unmodified code is stale; a fix with no before-state anchor cannot be verified.                      |
| "The batch is verified — I'll merge these perf PRs to save the human a step"             | Never auto-merge. A subtly wrong optimization on a hot path is exactly where the one review the whole model is built around must happen.                                      |
| "One target didn't improve, so the sweep is a bust — abort the batch"                    | Degrade gracefully. Report the non-improving target and keep the verified ones; one bad target never sinks the batch.                                                         |
| "I'll reimplement the benchmark harness here so the fleet is self-contained"             | Compose, don't reimplement. `harness-perf` owns `check-perf` and the baselines; a second measurement engine is drift waiting to happen. The fleet's value is orchestration.   |

## Red Flags

| Flag                                                                           | Corrective Action                                                                                                                |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| "I'll mark it verified based on the subagent's summary"                        | STOP. Independently re-measure the target against the unmodified baselines and check CI. A summary is not a verification.        |
| "The baseline is stale — I'll just bump it to green the gate"                  | STOP. That is a goalpost move. Re-measure against unmodified baselines; a baseline may only record a faster number.              |
| "This architectural rewrite looks safe enough — I'll apply it on the hot path" | STOP. Risky redesigns are filed with evidence, not applied. Record the before-state and a recommendation; do not auto-remediate. |
| "Let me raise concurrency to get the benchmarks done faster"                   | STOP. A stormed machine poisons the benchmark signal. Cap at the governor and run benchmarks on a quiet, clean tree.             |
| "The pre-push gate is failing in this worktree — I'll `--no-verify`"           | STOP. Never bypass. Push via the GitHub API or a non-`.claude` worktree; the gate is part of the verification.                   |
| "All verified — let me merge and close the loop"                               | STOP. The fleet never merges. Deliver the PRs and filed issues for review; landing is the human's step.                          |

## Examples

### Example: A five-target perf-budget/regression sweep

```
$ harness skill run perf-fleet --concurrency 2

Phase 1: SELECT
  Composed detectors:
    check_performance         -> posture: 2 budgets breached
    check-perf --structural   -> serializeRoadmap() cyclomatic 18 (Tier 1, > 15)
    check-perf --coupling     -> router.ts fan-out 13 (Tier 2)
    bench vs baselines        -> parseDocument 4.2ms -> 4.9ms (+16.7%, critical path, Tier 1)
    churn pass                -> both hot paths changed in the last 20 commits
  Folded into 6 targets; measured before-state captured for each; cross-check vs PRs:
    - "date-utils fast-path" -> already-optimized (merged PR: link) -> flag for drop
  Classified: 4 safe, 1 risky ("re-architect the document streaming pipeline")
  Scored 5 survivors by tier x critical-path x churn; ordered highest-first.

Phase 2: CONFIRM  [checkpoint:human-verify]
  Ranked batch (5) presented with each target's measured violation.
  Risky target "re-architect streaming" flagged as will-file (not auto-remediated).
  Human trims 1 low-severity Tier-3 target -> batch = 4 (3 safe + 1 risky). Concurrency: 2.

Phase 3: DISPATCH (governor = 2)
  3 safe targets: worktree-isolated subagents, 2 at a time, each running the real
  MEASURE (harness-perf) -> REMEDIATE (harness-debugging / harness-refactoring) -> RE-MEASURE.
  Risky target "re-architect streaming" -> files an issue with its before-state (+16.7%
  on parseDocument) and a recommendation; the other 3 continue.

Phase 4: VERIFY (independent — no self-report)
  target A (parseDocument regression): re-measure 4.9ms -> 4.1ms (budget met), baseline
    diff records the FASTER number, CI green all 3 OS + perf gate -> verified
  target B (serializeRoadmap complexity 18): re-measure extract-method -> 11 (< 15),
    CI green all 3 OS -> verified
  target C (router.ts fan-out): re-measure STILL Tier 2 (fan-out 12) -> REJECTED (did not
    meet budget)
  target D (re-architect streaming): filed in DISPATCH -> issue link (risky, awaits human)

Phase 5: REPORT
  | Target                 | Verdict  | PR / Issue | Before → After     | Findings | Assumptions made        | Filed redesign |
  | ---------------------- | -------- | ---------- | ------------------ | -------- | ----------------------- | -------------- |
  | parseDocument regr.    | verified | PR link    | 4.9ms → 4.1ms      | 1        | noise margin 3%; algo   | —              |
  | serializeRoadmap cx    | verified | PR link    | cx 18 → 11         | 1        | extract-method, no API  | —              |
  | router.ts fan-out      | rejected | —          | fan-out 13 → 12    | —        | —                       | — (over budget) |
  | streaming re-architect | filed    | Issue link | +16.7% (evidence)  | —        | —                       | streaming redesign |
  Dropped 1 already-optimized target with a note citing the resolving PR.
  Never merged. 2 fix PRs + 1 filed issue handed to the human for bulk review.
```

### Example: Rejecting a goalpost move

A subagent returns a branch and reports "done — regression fixed, CI green." VERIFY diffs `.harness/perf/baselines.json` and finds the branch **raised the parseDocument baseline from 4.2ms to 4.9ms** rather than making the code faster: the re-measurement against the _unmodified_ baseline still shows a +16.7% regression. Per the Iron Law this is a **goalpost move, not a remediation** — it is **rejected**, never marked merge-ready. The batch's other verified targets proceed to REPORT unaffected.

## Test Scenarios

### Scenario 1: Gate — a self-report accepted as verification

VERIFY receives a subagent claiming "regression gone, CI green" but a fresh re-measurement against the unmodified baselines still shows the budget breached. Expected: the "no merge-ready without a verified before/after re-measurement" Gate halts marking it merge-ready; the target is rejected/retried, not reported as a PR. Accepting the self-report is the failure this scenario guards against.

### Scenario 2: Gate — a goalpost move disguised as a fix

A subagent edits `.harness/perf/baselines.json` to match the new slower numbers (or relaxes a Tier threshold) and reports the gate green. Expected: the "never move the goalpost" Gate rejects it — the re-measurement is taken against the unmodified baselines, so the regression is still present. Baselines may only record a faster number via `update_perf_baselines`.

### Scenario 3: Gate — auto-applying a risky redesign

A target's budget can only be met by re-architecting a streaming pipeline on a correctness-sensitive hot path. Expected: the "never auto-apply a risky redesign" Gate files an issue with the measured before-state and a recommendation; the redesign is never applied autonomously. The other in-flight targets continue uninterrupted.

### Scenario 4: Rationalization — reimplementing the benchmark harness

An operator reasons "I'll reimplement the benchmark harness inside the fleet so it's self-contained." Expected: rejected by the "compose, don't reimplement" rationalization — the fleet composes `harness-perf` (which owns `check-perf` and the baselines) for its queue and measurement, and runs `harness-debugging` / `harness-refactoring` per target. A second measurement engine is drift waiting to happen.