voyage/tests/fixtures/synthesis/exploration/architecture-mapper.md

Architecture Report — output of architecture-mapper

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

Summary

Voyage is a contract-driven Claude Code plugin (Node ESM, zero runtime deps). The pipeline is six commands (commands/*.md) backed by a lib/ of pure, unit-tested validators/parsers and a thin scripts/ layer of measurement and codegen harnesses. trekexecute is the disciplined plan/session-spec executor; its headless path (Phase 2.6) fans out parallel "waves" of claude -p subprocesses driven by a Bash launcher template.

Tech stack

Layer	Choice	Evidence
Language	JavaScript (ESM, .mjs)	lib/**/*.mjs, "type":"module" in package.json
Tests	node:test + node:assert/strict	every tests/**/*.test.mjs
Validation	hand-rolled validators returning {valid,errors,warnings}	lib/util/result.mjs
Orchestration substrate	command prose + Bash + Agent/Task tool	commands/trekexecute.md
Headless launch	Bash here-doc template, backgrounded subprocesses	templates/headless-launch-template.md

Key patterns

• 3-layer module pattern — Content validator → raw-text wrapper → CLI shim (if (import.meta.url === \file://${process.argv[1]}`)), repeated across lib/validators, lib/parsers, lib/review`. Any new lib must follow it.
• Structured Result type — issue(code,message,hint,location) + fail() / ok() from lib/util/result.mjs. Stable error codes are the contract.
• Prose-as-orchestrator — commands carry the control flow in markdown; the harness executes it. Schema-drift defenses are inlined into command prose so they survive even when agent docs are not implicitly loaded.

Anti-patterns / debt near the task

• The headless launcher backgrounds all wave members at once with no upper bound on concurrent claude -p processes; concurrency is implicit in how many steps a wave contains. No central place caps it.
• Wave composition (which steps go in which wave) is computed by session-decomposer, but the launch fan-out is template Bash, so a cap would straddle a JS (decomposer) / Bash (launcher) boundary.

Module map (task-relevant)

commands/trekexecute.md         # Phase 2.6 parallel-wave orchestration prose
templates/headless-launch-template.md  # the Bash fan-out site
lib/util/result.mjs             # error shape any new guard returns
agents/session-decomposer.md    # produces the wave/dependency graph

Boundaries

The cap is a launch-time concern (Bash template + the Phase 2.6 prose that generates it). It does not belong in the pure lib/ validators unless we add a small "max parallelism" resolver that the prose reads. Recommend a lib resolver (testable) + a template wire-in (the actual xargs -P / job-slot mechanism).

How Phase 2.6 assembles a wave (detail)

The executor reads the plan's ## Step N blocks and the dependency edges session-decomposer emitted (depends_on: frontmatter). Steps with no unmet dependency at the current frontier form a wave. For each wave the prose:

1. builds a SHARED_CONTEXT_FILE (brief + plan + relevant exploration digest) passed to every member via --append-system-prompt-file (cache-prefix material — see q3 experiment);
2. emits one claude -p … & invocation per member from the here-doc, each with --max-turns, --max-budget-usd, GIT_OPTIONAL_LOCKS=0, and the GH#36071 push-before-cleanup workaround;
3. collects the backgrounded PIDs and waits for the batch to drain before advancing the frontier.

The cap belongs strictly between (2) and (3): bound how many of the emitted members run concurrently, leaving wave composition (1) untouched.

Layering verdict

Three layers, in increasing blast radius: (a) a pure resolver in lib/ (arithmetic only — trivially testable, follows the 3-layer module pattern); (b) Phase 2.6 prose passing the resolved integer + a --max-parallel flag into the template; (c) the template's fan-out mechanism. Keep (a) the single source of the number; (c) should only consume it. This matches every prior launcher hardening, which added one bounded externality (budget, locks, turns) at a time without reshaping wave composition.

Cross-cutting observations

• The launcher is the most operationally sensitive file in the repo (it spends money and mutates git). Every edit here is co-reviewed with its doc-consistency needle list — treat the needle test as part of the contract, not an afterthought.
• Nothing in lib/ currently imports anything launcher-related; the resolver will be a leaf module. Good — it can be tested and shipped independently of the template wire-in, enabling a TDD-first slice.