# Test Strategy — output of test-strategist

Task: Add a per-wave concurrency cap to trekexecute headless launches.

## Existing patterns

- Framework: `node:test` + `node:assert/strict`. One file per module under
  `tests/lib/` (mirrors `lib/`) and `tests/scripts/` for harness cores.
- Validators are tested as **pure functions**: feed a payload, assert
  `{valid,errors}` + stable error codes (see findings-schema.test.mjs,
  autonomy-gate.test.mjs).
- Template/prose invariants are pinned by **doc-consistency.test.mjs** (string
  `assert.ok(text.includes(...))` against templates/commands).

## Coverage gaps for this task

1. No test asserts an upper bound on launch parallelism today (there is none).
2. headless-launch-template.md is pinned for a list of required needles
   (`GIT_OPTIONAL_LOCKS`, `--max-turns`, `--max-budget-usd`, …) but NOT for any
   concurrency mechanism.

## Recommended tests (TDD order)

1. **`lib/.../max-parallel-resolver.test.mjs`** (new) — pure resolver:
   - flag `--max-parallel 3` wins over profile/default;
   - missing flag → profile default → hard default;
   - `0` / negative / non-integer → `{valid:false}` with a stable code;
   - cap ≥ batchSize → returns batchSize (no-op clamp).
2. **doc-consistency extension** — assert headless-launch-template.md consumes
   the resolved integer (e.g. includes `$MAX_PARALLEL` or `xargs -P`).
3. **arg-parser** — assert `--max-parallel` is recognised (extend
   arg-parser.test.mjs / gates-flag-coverage pattern).

## Notes

The Bash fan-out itself is not unit-testable in `node:test`; rely on the
template-needle pin (#2) + keeping arithmetic in the JS resolver (#1). This
matches how the project already tests prose-driven behavior.