docs(bugbot): add .cursor/BUGBOT.md project context

[LukasWodka]

Summary

Adds .cursor/BUGBOT.md — project context for the Cursor Bugbot reviewer. Zero repos in the org have one today, so Bugbot reviews every repo blind. This is item 4 of tracebloc/backend#930 and RFC 0001's own highest-value change.

This repo draws the most Bugbot findings of any (232), and they cluster on classes generic security advice does not cover: dishonest outcome reporting and mishandled interrupts. Writing the house rules down means Bugbot stops re-deriving them and spends its one pass on genuinely hard findings.

What's in it

Every rule carries the reason and a real reference in this repo:

• Honest outcome reporting. classifyPushOutcome is named as the reference pattern: a Job that exits 0 but reports row failures returns completed_with_failures + a non-zero code, not succeeded. Plus doctor.StatusUnknown — a check that cannot back a green prints neutral rather than a false tick.
• The exit-code contract is frozen — customers branch on it, so every path names a constant from exitcodes.go.
• Cancellation must be visible. Names the correct Cancelled — … sites, and flags that mapClientErr (internal/cli/client.go:858) maps errInteractiveCancelled straight to nil with no output — so a Ctrl-C at client.go:334 / delete.go:196 currently exits 0 in total silence, right beside a declined-answer branch that does print.
• HTTP 426 is a hard stop, never a warning — lists all six existing hard-fail sites so a new API consumer is measured against them.
• Verification is fail-closed — the SHA256 and cosign paths in install.sh, and validate_version_tag before URL interpolation.
• Timeouts, empty/nil boundary guards, cross-repo pins and generated artifacts (.data-ingestors-ref, .client-ref, .backend-ref, the goldens, chart-invariants).
• The STYLE.md output contract — Printer-only colour, colour never load-bearing, the terminology table, and regenerating the copy catalog golden.

Plus a verified known-non-issues section: .golangci.yml does not gate CI (pinned standalone binaries do, and staticcheck/unused are disabled there for runner OOM reasons); staticcheck runs -checks all,-ST1005 deliberately, so error-string capitalisation is not a finding; the single documented nolint and its reasoning; and the deadcode allowlist entries.

Type

Docs / DevEx. No code changes.

Test plan

• No runtime impact — a single markdown file read by Cursor. make ci is unaffected.
• Every path, line reference and non-issue was verified against this checkout before writing. Two claims were dropped rather than guessed: a SLSA/provenance reference (the term appears nowhere here — signing is cosign keyless), and a shared empty-input validation helper (none exists; the file describes the actual colocated validate* convention instead).

Checklist

• Targets develop
• Public repo — no customer names, internal hostnames, or internal-only ticket detail
• Only .cursor/BUGBOT.md in this PR
• Assigned

🤖 Generated with Claude Code

---

Note

Low Risk
Single markdown file for Cursor Bugbot; no runtime, build, or customer-facing CLI behavior changes.

Overview
Introduces .cursor/BUGBOT.md, a Cursor Bugbot guide for tracebloc/cli. It frames the product (signed releases, customer-run Kubernetes, scripting on exit codes, make ci parity) and lists what to always flag: dishonest success / JSON vs exit-code mismatch, unnamed exit codes, silent interactive cancel (including mapClientErr), HTTP 426 as hard stop, fail-closed install.sh verification, bounded external calls, boundary validation, cross-repo pins and generated artifacts, STYLE.md / Printer output rules, and typed errors with %w.

It also documents known non-issues (CI uses pinned linters, not golangci-lint; deliberate staticcheck -ST1005; documented nolint; integration timeouts; advisory workflows) and review tone for a public repo.

No application code changes — documentation only for automated review.

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

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 60517e0. Configure here.}