# qa-fanout-contract.md — peaks-qa 3-way fan-out + business sub-division

> **Slice**: 2026-06-07-sub-agent-dispatch-decouple (G3 + G5 + G6)
> **Audience**: peaks-qa main loop and any future sub-role of peaks-qa
> **Status**: stable

This reference is the peaks-qa-specific contract for the 3-way fan-out
(business / perf / security) and the optional business sub-division
(`qa-business-api` / `qa-business-frontend` / `qa-business-regression` /
...). peaks-qa is **itself a Dispatcher** (slice 2026-06-07 G1): when it
is the main loop, it fans out 3 sub-agents in one message via the
`peaks sub-agent dispatch <role>` primitive.

## Why peaks-qa is a Dispatcher (not a Worker)

The user has been explicit: "peaks-qa 是需要的,因为可以同时进行
业务测试,性能测试,安全测试。而且业务测试还是可以再分的". Three concerns
(business / perf / security) are **information-independent**:
- business validation exercises the user's expected behavior,
- perf baseline measures throughput / latency / memory,
- security review audits the trust boundary.

They have independent inputs (PRD / RD planning / codegraph for
business; perf-signals for perf; trust model for security), independent
outputs (different artifact paths), and can run concurrently without
sharing mutable state. peaks-qa fans them out so QA wall-clock drops
from "sum of all three" to "max of the three". Sub-dividing business
(`qa-business-api` etc.) further drops wall-clock when the business
slice is large.

The 2-level cap (RL-4) is empirical: past 2 levels, the reducer cannot
audit the boundaries between sub-agents and prompts start overlapping.

## The 3-way fan-out

When peaks-qa is the main loop and the QA phase is about to run, it
issues 3 dispatch calls in a **single message**:

```
peaks sub-agent dispatch qa-business \
  --prompt "<qa-business contract below, plus runtime args: project=<repo>,
             session-id=<sid>, request-id=<rid>.
             Write your evidence at .peaks/_runtime/<sid>/qa/test-reports/<rid>.md
             and return ONLY the path. While running, call
             peaks sub-agent heartbeat --record <dispatchRecordPath>
             --status running --progress <pct> --note '<text>' at least every 30s;
             on completion call --status done --progress 100 --note 'completed'." \
  --request-id <rid> --session-id <sid> --project <repo> --json

peaks sub-agent dispatch qa-perf \
  --prompt "<qa-perf contract below, plus runtime args; output .peaks/_runtime/<sid>/qa/performance-findings.md>" \
  --request-id <rid> --session-id <sid> --project <repo> --json

peaks sub-agent dispatch qa-security \
  --prompt "<qa-security contract below, plus runtime args; output .peaks/_runtime/<sid>/qa/security-findings.md>" \
  --request-id <rid> --session-id <sid> --project <repo> --json
```

The LLM reads the 3 `data.toolCall` descriptors from the envelopes and
fires all 3 in the same message (real concurrency). peaks-qa then
waits for all 3 to return, runs Gate B (`ls` checks on the 3 artifact
paths), and merges their findings into the QA verdict.

## Business sub-division (optional)

If the project warrants it, `qa-business` can be split into:

- `qa-business-api` — REST / RPC / message-bus contracts
- `qa-business-frontend` — UI flows, component behavior, state machines
- `qa-business-regression` — re-run a curated test plan against the slice diff

Each gets its own `peaks sub-agent dispatch` call. The names are
**convention not contract** — the dispatcher accepts any non-empty
string. The recommended names above are hints, not a hard list.

**Cap (RL-4)**: ≤ 2 levels deep. `qa-business-api` is fine;
`qa-business-api-user` is not.

## Independent inputs + independent artifacts

| Sub-agent | Reads | Writes | Must not depend on |
|---|---|---|---|
| `qa-business` (or subdivisions) | PRD body, RD planning, codegraph, project scan, existing system | `.peaks/_runtime/<sid>/qa/test-reports/<rid>.md` | perf / security output (run in parallel) |
| `qa-perf` | RD planning, codegraph, perf baselines from prior slices | `.peaks/_runtime/<sid>/qa/performance-findings.md` | business / security output |
| `qa-security` | PRD body (trust model), codegraph, RD planning, existing security notes | `.peaks/_runtime/<sid>/qa/security-findings.md` | business / perf output |

The reducer merges all 3 outputs into the final QA verdict. None of
the 3 sub-agents reads another sub-agent's output (no peer-to-peer
messages — peaks is a pseudo-swarm, not a true bee colony).

## Heartbeat instructions (G6)

Each sub-agent prompt must include the heartbeat instruction so the
parent peaks-qa can render a live status line during the wait. The
recommended paragraph (also auto-generated by peaks CLI):

```
While running, call `peaks sub-agent heartbeat --record <dispatchRecordPath>
--status running --progress <pct> --note '<text>'` at least every 30 seconds.
On completion call `--status done --progress 100 --note 'completed'`. On
failure call `--status failed --note '<reason>'`. Do not skip heartbeats;
the parent peaks-qa uses them to render the live status line.
```

The `heartbeatIntervalSec` value can be overridden in the peaks-qa
SKILL.md frontmatter (e.g. `heartbeatIntervalSec: 15` for fast QA
sub-agents that finish in <2 min).

## Batch counter (RL-1)

peaks-qa is allowed up to 3 sub-agents in this fan-out by default. If
business is sub-divided, the total batch size is `1 (business) + 1 (perf)
+ 1 (security) + N (business subdivisions) = 3 + N`. The peaks CLI
emits a `BATCH_OVER_LIMIT` warning if the dispatch count exceeds the
RL-1 empirical upper bound of 6, but does NOT block the dispatch (the
user has been explicit: "RL-1 is empirical; if you have a real reason
to go to 7, that's your call"). The warning goes into the dispatch
envelope and into the slice's `reducerReport`.

## Resource lifecycle (G5)

- Each sub-agent dispatch writes a record to
  `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json` (RL-5).
- After the 3 sub-agents return, peaks-qa reducer marks each record
  `disposed: true` + `disposedAt: <now>` (RL-7).
- A reducer-report is emitted with
  `{ batchId, total: 3 + N, disposed, leaked: 0 }`. `leaked > 0` is a
  user-visible warning (RL-11).
- Slice close archives the records to
  `.peaks/_runtime/<sid>/_archive/_sub_agents/<slice-id>/` (RL-8).

## Acceptance criteria covered

- AC-17 (peaks-qa 3-way fan-out + 业务可再分)
- AC-17b (peaks-ui说明行)
- AC-26 / AC-34 (dispatch record schema)
- AC-27 (RL-1 batch counter)
- AC-28 (reducer dispose)
- AC-29 (fan-out 原则)
- AC-33..AC-36 (G6 heartbeat + SKILL.md)
- AC-37 (E2E dogfood)

## Cross-reference

- `skills/peaks-code/references/sub-agent-dispatch.md` — orchestrator
  contract for all Dispatchers
- `skills/peaks-code/SKILL.md` "Peaks-Loop Swarm parallel phase" — sibling
  fan-out pattern
- `.peaks/memory/sub-agent-resource-lifecycle-red-line.md` — G5 red line
- `.peaks/memory/sub-agent-heartbeat-progress-red-line.md` — G6 red line

---

## 业务测试细分 (optional)

> Body of `## 业务测试细分 (optional)`. If the PRD or project warrants it, subdivide `qa-business` further into roles like `qa-business-api` / `qa-business-frontend` / `qa-business-regression`; each gets its own `peaks sub-agent dispatch` call. Names are convention not contract — the dispatcher accepts any non-empty string. **Subdivision must stay ≤ 2 levels deep** (RL-4): `qa-business-api` is fine, `qa-business-api-user` is not. Two levels of depth is the empirical sweet spot — past that, the reducer cannot audit the boundaries between sub-agents, and prompts start overlapping.

For the full contract (heartbeat instructions for each sub-agent, batch-id discipline, 30s cadence, 100-truncation, 5min stale) see `skills/bee/peaks-qa/references/qa-fanout-contract.md` and `skills/peaks-code/references/sub-agent-dispatch.md` §G6.
