[jayleaton]

Problem

make test and make db-up used one fixed compose project (ai-patterns-go) and fixed host ports (test Postgres 54329, Postgres 5432, pgweb 5050). Parallel worktrees, the normal way agents work on this template, either shared each other's containers or failed with "port is already allocated". The mobile branch hit this on 54339.

How

make (any checkout)
  CHECKOUT_ID  = cksum(path of the checkout)
  project      = <dir>-<hash>               e.g. feat-foundation-6e0df7, wt2-409717
  postgres     = 25000 + id % 1000          stable per checkout, so DATABASE_URL is stable
  pgweb        = 26000 + id % 1000
  test pg      = 127.0.0.1::5432            Docker picks a free port; make test reads it back

• Overrides: every value can be set in the environment or .env (COMPOSE_PROJECT_NAME, POSTGRES_PORT, PGWEB_PORT, TEST_POSTGRES_PORT, DATABASE_URL). make test uses TEST_DATABASE_URL as is when set.
• make env prints the values, and db-up and test print them too.
• .env.example no longer hardcodes DATABASE_URL; make derives it.
• Docs: AGENTS.md and README.md now describe this.
• CI is unaffected. It runs go test with its own TEST_DATABASE_URL and never calls make.

Evidence

Run in two worktrees started concurrently: this one and a second worktree at the same commit (later removed). Both ran GOFLAGS=-count=1 make test at the same time:

	worktree A	worktree B
compose project	feat-foundation-6e0df7	wt2-409717
test Postgres	127.0.0.1:32770	127.0.0.1:32771
result	all 7 packages ok	all 7 packages ok

Both finished in 14 s. Concurrent make db-up + make migrate also worked: Postgres 25980/25709, pgweb 26980/26709, and migrations applied in both. make ci passes locally in 18.5 s; gofmt and golangci-lint report 0 issues.

Merge Danger

Door: two-way. This only changes local tooling.

Blast Radius: local-dev. Existing checkouts get new default ports for the dev database. A .env that pins POSTGRES_PORT/DATABASE_URL keeps working. A dev database created under the old shared project is not reused; run make db-up && make migrate once, or set COMPOSE_PROJECT_NAME=ai-patterns-go in .env to keep it.

🤖 Generated with Claude Code