# turniere-backend Agent Notes

This repository should be operated through `invoke` tasks by default.

For routine development, verification, Docker, and E2E work, agents should use
`inv ...` rather than ad-hoc shell commands unless there is a strong reason not to.

## Default Workflow

Use `tasks.py` and run commands through `inv ...` instead of ad-hoc shell commands for routine work.

Examples:

- `inv db-migrate`
- `inv test`
- `inv test-shard --node-index=1 --node-total=8`
- `inv lint`
- `inv verify-http`
- `inv blackbox-production`
- `inv scenario-main-usecase`
- `inv docker-build-all`
- `inv docker-test-shard --node-index=3 --node-total=8`
- `inv docker-test-http-e2e`

The GitLab CI pipeline is expected to use these tasks as well.
In CI, blackbox E2E should prefer the documented GitLab service-to-service model with `FF_NETWORK_PER_BUILD: "true"` when the production image needs to talk to a Postgres sidecar.
The normal Rails spec suite is sharded through `inv test-shard ...` and should stay aligned with the CI matrix configuration.

Useful GitLab push-option variables for saving CI minutes on public repos:

- skip all spec jobs: `git push -o ci.variable="SKIP_ALL_SPECS=1"`
- skip only normal Rails specs: `git push -o ci.variable="SKIP_RAILS_SPEC=1"`
- skip only blackbox E2E: `git push -o ci.variable="SKIP_E2E_SPEC=1"`

Do not use these by default. Only use them when the change truly does not affect the skipped area.

This is not just a convenience preference. The task layer is the operational
contract for this repo and should stay aligned across local use, CI, and
cross-repo consumers.

## Why

The point of the task layer is:

- one stable entrypoint for local development
- one stable entrypoint for CI
- one stable entrypoint for frontend and cross-repo test setup
- fewer undocumented command variants

If a workflow matters often enough that a human or CI needs to remember it, it
should usually become an `invoke` task.

## Maintenance Rule

When new functionality or recurring maintenance work is added, extend `tasks.py`
so the new workflow stays easy to discover and easy to run.

Do not leave important multi-step flows only in:

- CI YAML
- MR descriptions
- shell history
- team memory

Instead, add or update an `inv` task and then have CI or docs call that task.

If a new backend capability introduces a meaningful setup, verification, fixture,
or scenario workflow, add or extend a task for it as part of the same change.

## HTTP E2E

The backend HTTP E2E flow is intended to be reusable outside this repo, especially by frontend tests that need realistic backend state.

That means:

- scenario creation should stay HTTP-driven
- reusable scenario setup should be exposed through `inv` tasks and `script/e2e_scenarios.rb`
- new commonly needed backend states should be added to the scenario/task layer, not recreated ad hoc in each consuming test suite
- the released production image should be exercised through the blackbox task layer, not only Rails-internal test entrypoints

## Practical Expectation

If you touch test, verification, boot, Docker, or scenario setup workflows,
check whether `tasks.py` also needs to change.