# Task-Relevant Code — output of task-finder

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

## Direct hits

| File | Lines | Why relevant |
|------|-------|--------------|
| `templates/headless-launch-template.md` | ~10–60 | The Bash fan-out: backgrounds each wave member, `wait`s on PIDs. Edit site for slot-limiting. |
| `commands/trekexecute.md` | Phase 2.6 | Prose that generates the launch batches; where a `--max-parallel` flag + profile lookup would be documented. |
| `lib/profiles/` | resolver dir | Profiles already carry per-phase knobs; a `max_parallel` default fits the existing `phase_signals`/profile lookup order. |
| `lib/util/result.mjs` | 33 | `issue()` — the error shape a `maxParallel` resolver returns on bad input. |

## Reuse candidates

- **arg-parser** (`lib/parsers/arg-parser.mjs`, per tests/lib/arg-parser.test.mjs)
  already parses `--flag value` pairs for the commands. A `--max-parallel <n>`
  flag plugs into the existing parser; do not hand-roll parsing.
- **profile-resolver** (`lib/profiles/`, profile-resolver.test.mjs) is the lookup
  order CLI-flag → brief signal → profile → default. A concurrency default
  belongs as a profile field consumed through this same resolver.
- **autonomy-gate** (`lib/` autonomy-gate.test.mjs) shows the established pattern
  for "bounded integer with a safe default" — mirror its clamp/validate.

## Existing similar solutions

`scripts/q3-cache-prefix-experiment.mjs` spawns children **sequentially** to
avoid spawn-burst rate-limits — confirms the project already knows unbounded
fan-out is a risk and chose a manual bound there. A cap generalises that
instinct to the headless wave path.

## Models / config

No DB. Config lives in `settings.json` (`trekplan`/`trekresearch` scopes only —
doc-consistency pins this) and per-run profiles. A `max_parallel` knob should
ride the profile system, not add a new settings.json scope.