voyage/tests/fixtures/synthesis/exploration/dependency-tracer.md

Dependency & Data-Flow Report — output of dependency-tracer

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

Import / call chain relevant to the task

commands/trekexecute.md  (Phase 2.6 prose)
  └─ generates → templates/headless-launch-template.md  (Bash here-doc)
        ├─ reads  SHARED_CONTEXT_FILE  (append-system-prompt-file)
        ├─ spawns claude -p  ×N  (one per wave member, backgrounded with &)
        └─ waits  via `wait` on collected PIDs
  └─ consumes → .session-state.local.json  (Handover 7; session graph)

Data flow

1. session-decomposer emits a plan with wave groupings + a dependency graph.
2. trekexecute Phase 2.6 turns each independent wave into a launch batch.
3. The template loops over batch members and backgrounds each claude -p, collecting PIDs into a Bash array, then waits for the whole batch.
4. There is no slot-limiting between "background member" and "wait" — the degree of parallelism equals the batch size.

Side effects

• Each subprocess does git work under GIT_OPTIONAL_LOCKS=0; high concurrency raises the chance of index-lock contention (mitigated, not eliminated).
• --max-budget-usd is per-subprocess; total spend scales with batch size, so a concurrency cap also indirectly bounds burst spend.

What a cap touches

• Pure-addable: a maxParallel resolver in lib/ (reads plan/profile/flag, returns an integer ≥ 1). No existing module imports would change.
• Wire-in: the template's loop must consume slots (e.g. a counting semaphore in Bash, or xargs -P <n>). This is the only behavioral edit.

No hidden dependents

Grepped for other call sites of the launch template — only trekexecute Phase 2.6 and the headless-launch-template test reference it. A cap is local in blast radius.

Resolver input provenance (what the cap reads)

The resolved integer must be derived from, in lookup order:

1. CLI flag --max-parallel <n> — parsed by lib/parsers/arg-parser.mjs; highest precedence (operator override).
2. Brief signal — phase_signals already carries per-phase orchestration shape; a max_parallel hint here is honoured if no flag.
3. Profile — lib/profiles/ resolves --profile economy|balanced|premium; each profile can carry a max_parallel default. This is the same lookup order phase_models uses, so the resolver should reuse profile-resolver, not re-implement precedence.
4. Hard default — batchSize (i.e. no cap / current behavior), so the change is a strict no-op until someone opts in.

Downstream of the cap

• Budget: total burst spend = min(cap, batchSize) × per-member --max-budget-usd. A cap therefore tightens the worst-case spend envelope — worth noting in the plan's risk/observability section.
• Git contention: fewer concurrent git-touching subprocesses → fewer index.lock races. GIT_OPTIONAL_LOCKS=0 reduces lock acquisition but does not serialize ref updates; the cap is the structural mitigation.
• Classifier exposure: a smaller concurrent fan-out under auto/bypass lowers the surface the proliferation classifier (S7 F4) scrutinises.

Data-flow invariant to preserve

SHARED_CONTEXT_FILE is built once per wave and read by every member; the cap must not cause it to be rebuilt per-slot (would defeat the cache prefix). Slot limiting happens at spawn time only; the context file is wave-scoped, not slot-scoped.