docs: how Backend CI gates a merge, and why it isn't the pytest job

[JSv4]

Documents backend-ci-gate (added in #2267) in docs/development/test-suite.md:

• why requiring the pytest job reads green when a red linter skips it (GitHub reports a conditionally-skipped job as Success);
• why the mirror-image trap — workflow-level path filtering — hangs a required check at Pending forever instead;
• the gate's decision table, and that it --self-tests before every evaluation;
• the six sibling workflows (frontend*, production-stack, redis-integration) that cannot be required until they get the same always-runs gate job;
• that enforce_admins is false, so the gate is a strong default rather than an absolute one.

This PR doubles as the skip-path verification for #2267

#2267's own diff touched backend.yml, so it only ever exercised backend=true. This PR is docs-only, so it should exercise the other branch:

• changes → backend=false
• linter → skipped
• pytest → skipped
• backend-ci-gate → success

If that is what the checks below show, the gate is safe to make a required status check. If backend-ci-gate is missing or red here, it is not — do not enable branch protection until this PR is green.

🤖 Generated with Claude Code

[claude]

Reviewed — this is a docs-only change (docs/development/test-suite.md, +79/-0), so the main bar is factual accuracy against the actual workflow/script code, and it clears that bar well.

Verified against source:

• .github/workflows/backend.yml: pytest is indeed gated on needs.linter.result == 'success', and the gate job (named backend-ci-gate) runs with if: always() and depends on [changes, linter, pytest] — matches the doc's description exactly.
• paths-ignore is only on the push trigger of backend.yml, not pull_request — matches the "mirror-image trap" explanation.
• .github/scripts/backend_ci_gate.sh's evaluate() logic matches the decision table row-for-row, including the skipped-counts-as-failure branch for the "tests skipped for any other reason" row.
• The gate job does run backend_ci_gate.sh --self-test before evaluation, as stated.
• The six sibling workflows (frontend.yml, frontend-e2e*.yml, production-stack.yml, redis-integration.yml) all carry workflow-level paths: filters on pull_request (confirmed for frontend.yml, production-stack.yml, redis-integration.yml; the frontend-e2e-* variants weren't individually re-checked but follow the same pattern), so the "not safely requirable as-is" claim holds.
• require_backend_ci_gate.sh's rationale (PUT replaces the whole protection object; PATCH .../required_status_checks 404s if none exists) matches the script's actual behavior and comments.

Minor notes, non-blocking:

• The doc states "PR feat(agents): system_instructions_mode — let an agent config EXTEND the corpus persona instead of replacing it #2262 ended up on main... for about 30 hours" and the gate script comment cites "Bump djangorestframework-stubs from 3.17.1 to 3.18.0 #2260, Bump mypy from 2.3.0 to 2.3.1 #2264 and Bump django-stubs from 6.0.7 to 6.1.0 #2265" as the observed linter=failure / pytest=skipped cases — these are point-in-time operational claims I can't independently verify from the diff alone, but they're consistent with the stated purpose and read as genuine incident data rather than speculation.
• The doc appropriately hedges the "Other workflows are not safely requirable" section and the enforce_admins note with present-tense framing rather than asserting these as permanent facts, which is the right call for something that can change out from under the docs.
• No markdown-heading collisions and no markdown linter is configured in .pre-commit-config.yaml, so no lint-format concerns.

On the stated purpose of this PR (skip-path verification for #2267 — confirming changes→backend=false, linter/pytest skipped, backend-ci-gate→success on this docs-only diff): that's an operational check to make on the PR's own CI run rather than something reviewable from the diff, but the doc's own "Practical notes" section correctly predicts what should happen here, so it's a nice self-verifying artifact.

Nothing to change — this is accurate, well-scoped, and directly useful for anyone confused about why pytest isn't the required check. Approving.