member-console/openspec/changes/archive/2026-04-29-worktree-test-stack-isolation/proposal.md

Why

We want to evaluate multiple LLM coding agents on the same repository in parallel by giving each its own git worktree. The current test/ stack assumes a single set of host ports (5432, 6379, 8080, 7233, 8233, 80) and bind-mounts ./testdata/ from the working directory, so two worktrees running docker compose up -d simultaneously collide on ports and would otherwise share a Postgres data directory if testdata/ were tracked. The Keycloak seed script and mc-config.yaml also hardcode localhost:8081 / localhost:8233 and the keycloak.localhost hostname, so even with COMPOSE_PROJECT_NAME isolation, the seeded OIDC realm would not match per-stack URLs. Without isolation, parallel agents waste time fighting port conflicts and corrupting each other's database state.

What Changes

• Parameterize host ports and Keycloak hostname in test/compose.yaml via ${VAR:-default} so a per-worktree .env controls the stack.
• Env-template hardcoded URLs and clientIds in test/seed/keycloak/seed-keycloak.sh (member-console redirect URI, temporal-ui redirect URI, web origins) so the seed matches the running stack.
• Add test/bootstrap-stack.sh: idempotent script that derives a slug from the worktree directory name, hashes it to a port-offset slot (range 200, step 50), probes for free ports and recovers from collisions, writes test/.env, copies test/secrets/ from the main worktree, and prints the resulting URL/port table.
• Add test/teardown-stack.sh: brings the compose stack down with volumes, removes test/.env, removes test/secrets/ and per-stack testdata/.
• Add test/AGENTS.md: short, agent-targeted instructions explaining the parallel-stack contract (run bootstrap before compose; idempotent; per-worktree).
• Extend test/README.md with a parallel-stack section linking to AGENTS.md.
• Add a 3-line note to top-level CLAUDE.md directing agents to run ./test/bootstrap-stack.sh before docker compose up.
• Add test/.env to .gitignore.
• No application code changes: Viper's existing AutomaticEnv + MC_ prefix + dash→underscore replacer already lets per-worktree MC_* env vars override mc-config.yaml keys.

Capabilities

New Capabilities

• worktree-test-stacks: Per-worktree isolation of the test/ Docker Compose stack so multiple worktrees can run independent member-console + Keycloak + Temporal + FedWiki environments concurrently. Covers port allocation, env templating, secret propagation across worktrees, and the agent-facing bootstrap contract.

Modified Capabilities

None. No existing spec covers the test harness or local development environment.

Impact

• Affected files: test/compose.yaml, test/seed/keycloak/seed-keycloak.sh, test/README.md, .gitignore, CLAUDE.md. New: test/bootstrap-stack.sh, test/teardown-stack.sh, test/AGENTS.md.
• No code changes: cmd/root.go already configures Viper for env-var overrides via MC_ prefix.
• Risk surface: Keycloak occasionally ignores fields supplied in the realm/client seed payloads; the seed script audit must verify each templated URL actually takes effect. A spike against a non-default port set is required before declaring the change complete.
• Shared external state: All stacks still hit the same Stripe test account via test/secrets/stripe-*. Webhook traffic for parallel runs may land in any stack; agents should not run Stripe webhook tests in parallel. Documented in AGENTS.md.
• No production impact: changes are confined to test/ and developer-facing tooling.