# Align environment.md integration test command with run-tests.sh

**Task**: AZ-1131_environment_md_integration_command
**Name**: Align environment.md integration command with run-tests.sh
**Description**: Fix stale integration-test orchestration docs that still reference `docker-compose.yml` + `docker-compose.tests.yml` while `scripts/run-tests.sh` uses self-contained `docker-compose.tests.yml` only.
**Complexity**: 1 points
**Dependencies**: None
**Component**: test environment documentation
**Tracker**: AZ-1131 (https://denyspopov.atlassian.net/browse/AZ-1131)
**Epic**: None

## Problem

`_docs/02_document/tests/environment.md` § Test Execution documents:

`docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit`

`scripts/run-tests.sh` (canonical Step 11 gate) runs integration tests with:

`docker compose -f docker-compose.tests.yml up --build --abort-on-container-exit --exit-code-from integration-tests`

`docker-compose.tests.yml` is self-contained (postgres + api + integration-tests). The dual-file command is stale since the test stack was split out. This mismatch has been a carry-over since cycle 12 retro and misleads operators copying docs instead of the script.

## Outcome

- `environment.md` matches the real integration test orchestration path
- Operators can run integration tests by following either `environment.md` or `run-tests.sh` without conflicting instructions
- Stale dual-compose references in agent-facing docs are corrected or cross-linked

## Scope

### Included

- Update `environment.md` § Test Execution to document `docker-compose.tests.yml` only and cite `scripts/run-tests.sh` as the canonical entry point
- Ripple fix: `README.md` and `AGENTS.md` integration-test command lines (same stale dual-compose pattern)
- No compose file or script behavior changes

### Excluded

- Historical task specs in `_docs/02_tasks/done/` (AZ-285 AC-2 records the old command — leave as historical artifact)
- Perf orchestration docs (already correct — uses `docker-compose.yml` + `docker-compose.perf.yml`)
- CI Woodpecker pipeline changes

## Acceptance Criteria

**AC-1: environment.md accuracy**
Given `environment.md` § Test Execution
When an operator reads the documented integration command
Then it matches `scripts/run-tests.sh` Step 2 (`docker compose -f docker-compose.tests.yml …`) and names the script as canonical

**AC-2: Agent-facing doc ripple**
Given `README.md` and `AGENTS.md` integration test sections
When an operator follows those instructions
Then they reference `docker-compose.tests.yml` only (or point to `./scripts/run-tests.sh` exclusively)

**AC-3: No runtime change**
Given the task is complete
When `./scripts/run-tests.sh --smoke` is run
Then behavior is unchanged (docs-only delta)

## Non-Functional Requirements

**Compatibility**
- Documented manual command must remain valid on darwin/arm64 without requiring `docker-compose.yml`

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-3 | N/A (docs only) | Verified by grep + optional smoke run |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|-------------|-------------------|----------------|
| AC-1 | `environment.md` on disk | Ripgrep for `docker-compose.yml -f docker-compose.tests.yml` | Zero matches in `environment.md` | — |
| AC-2 | `README.md`, `AGENTS.md` | Ripgrep for stale dual-compose integration command | Zero matches or explicit redirect to `run-tests.sh` | — |

## Constraints

- Documentation-only — no compose or script edits unless a comment in `run-tests.sh` is needed for cross-link clarity

## Risks & Mitigation

**Risk 1: Operators relied on dual-compose for host port mapping**
- *Mitigation*: `docker-compose.tests.yml` does not publish postgres to host; document that this is intentional (internal network only)
