feat(notifier): buildkite_annotate notifier (Wave 1 Tier-2 #2)

[zuchka]

Summary

Adds a built-in `type: buildkite_annotate` notifier that publishes DING alerts as Buildkite build annotations via `buildkite-agent annotate --style <style> --context ding --append`. All alerts for a build land in a single rolling annotation visible at the top of the Buildkite job UI, closing the "annotation surface unused" gap flagged in the Wave 1 Buildkite recipe — second row of the Wave 1 Tier-2 candidates table marked shipped.

This continues the Tier-2 cadence: T2-A (`${VAR}`), T2-B (`kubernetes_event` shipped in v0.9.0), Wave 1 #1 (`gitlab_artifact` shipped in v0.10.0), now Wave 1 #2 (`buildkite_annotate`).

Design (locked in brainstorm)

• Style: configurable `style:` field; default `error`; validated against `success`/`info`/`warning`/`error`.
• Context: hardcoded `--context ding --append` — single rolling annotation per build.
• Pattern: sync, mutex-guarded, append-only. Mirrors `gitlab_artifact.go` exactly with `exec.Command("buildkite-agent", ...)` substituting for `os.OpenFile`.
• Outside Buildkite: `buildkite-agent` not on PATH → log once at construction, Send becomes a no-op. Mirrors GHA's graceful-degrade philosophy.
• No async / retry / metrics: sync local exec; nothing to instrument.
• Body via stdin: avoids shell-escape pitfalls with multi-line markdown.

Commits

1. `feat(notifier): buildkite_annotate notifier (shells out to buildkite-agent)` — impl + 8 tests + 1 new field on `NotifierConfig` + config + server registry wiring (no new deps)
2. `docs(recipes): document buildkite_annotate notifier` — recipe positive section, configuration.md entry, ding.yaml.example block

Test plan

• `go test -race ./...` — full suite green
• `go test -race ./internal/notifier/... -run TestBuildkiteAnnotate -v` — all 8 new tests pass
• `go build -o /tmp/ding ./cmd/ding` — binary builds
• Local stub smoke (light, no real Buildkite required):
  ```bash
  mkdir /tmp/buildkite-annotate-smoke && cd /tmp/buildkite-annotate-smoke
  cat > buildkite-agent <<'AGENT'
  #!/bin/sh
  { echo "=== invocation: $(date -u +%FT%TZ) ==="; echo "args: $@"; echo "stdin:"; cat; echo "=== end ==="; } >> /tmp/buildkite-agent-calls.log
  exit 0
  AGENT
  chmod +x buildkite-agent
  export PATH="$PWD:$PATH"
  rm -f /tmp/buildkite-agent-calls.log
  cat > ding.yaml <<'YAML'
  notifiers:
  alerts:
  type: buildkite_annotate
  rules:
  • name: job_failed
    match: { metric: run.exit }
    condition: value > 0
    message: "Job failed (exit {{ .exit_code }})"
    alert:
    • notifier: alerts
      YAML
      /tmp/ding run --config ding.yaml -- false
      cat /tmp/buildkite-agent-calls.log
      ```
• mkdocs build --strict (CI runs it; not run locally if mkdocs isn't installed)

Out of scope (deferred)

• Per-rule style override — notifier-level only
• Alternative annotation strategies (per-rule replace, every-fire-new) — single rolling is canonical Buildkite UX
• Custom `--context` name — hardcoded `ding`
• Real-Buildkite smoke gate — local stub smoke + unit tests sufficient

Post-merge

By the established convention (gitlab_artifact → v0.10.0), this could tag as v0.11.0 if you want the new notifier in a release rather than just on main.

🤖 Generated with Claude Code