docs(bugbot): project context for the repo that decides whether checks passed (backend#1680)

[LukasWodka]

Why

.github had no .cursor/BUGBOT.md — one of the five repos without one (with e2e-test-agent, release-train, rfcs, claude-skills) — despite being public and holding the reusables ~120 callers consume at @main, plus the conformance contract itself.

Written from this repo's actual defect history

Nearly every real finding here is one shape: a guard that reports success it did not verify. The guide names the variants that have actually occurred in this repo rather than describing the idea abstractly:

• an empty API response read as "nothing found"
• || echo 0 turning a failed call into a clean count
• grep -q in a pipefail pipeline where a real hit returns rc=141
• a required check that is path- or branch-filtered, so PRs outside the filter wait forever at "Expected — waiting for status to be reported"
• a soft-fail default making a required check exit 0 on findings

Plus the two traps specific to this repo:

• Only one of GitHub's two protection systems is read. A ruleset-only branch 404s on the classic endpoint; bypass_actors exists only on /rulesets/{id}, so an allowlist asserted from the per-branch endpoint asserts nothing.
• Caller/callee ordering at @main. A caller passing an input the @main callee does not yet declare dies with startup_failure — a job that never starts, not a red one.

It also records the non-issues

Half of review churn is rediscovering a settled decision. Written down: retired pii-gate contexts lingering red, the deliberate fleet-wide strict: false (backend#1276), and the long incident comments — which are load-bearing, each one the reason a guard is written the awkward way it is, and should not be trimmed for brevity.

Parent epic: backend#1680 (repo-hygiene scan, section A).

---

Note

Low Risk
Documentation-only addition with no runtime, CI, or security behavior changes.

Overview
Adds a new .cursor/BUGBOT.md so Bugbot has repo-specific review guidance for this public reusable-workflows repo.

The guide focuses Bugbot on fail-open guards (success reported without a real check), required checks that cannot fail or report, reading only one of GitHub's two branch-protection systems, and caller/callee input ordering at @main. It also lists known non-issues (retired pii-gate, deliberate strict: false, load-bearing incident comments) to cut review churn.

^{Reviewed by Cursor Bugbot for commit d571455. Bugbot is set up for automated code reviews on this repo. Configure here.}