From b74d18309e2e71cefb18165c36198d409d58f468 Mon Sep 17 00:00:00 2001 From: Tri Lam Date: Tue, 19 May 2026 00:58:04 -0700 Subject: [PATCH] [docs] AGENTS.md: aggregator bypass + perf-regex flake lessons Two universal rules learned at real cost this session: 1. GitHub Actions aggregator jobs under default `needs:` semantics silently bypass branch protection. PR #73 merged past a failed `verify-test` because the aggregator was SKIPPED and GitHub treats SKIPPED required checks as satisfied. Fix shape lives already in main (PR #74); the lesson now lives where the next contributor splitting CI jobs will see it before repeating. 2. `require.Regexp` with implicit upper bounds (e.g. `0\.0[0-9]+`) is a flake class. Two assertions of identical shape hit in one session (`TestReceiver_SLIBudget`, `TestReceiver_SetDegraded`). Fix shape: assert only the actual invariant. File at 148 lines (cap is 150). `make doc-check` clean. Signed-off-by: Tri Lam --- AGENTS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ab527a7a..7c7da5aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,6 +84,26 @@ Universal rules every change should respect. The file is capped at § "M3 release-pipeline hardening" for the chart-appversion drift entry. +- **Aggregate CI gates with `if: always()` and explicit + `needs.*.result` checks; default semantics silently bypass branch + protection.** GitHub short-circuits an aggregator job's `needs:` to + SKIPPED on any sub-job failure, and treats SKIPPED required checks + as satisfied. PR #73 silently merged past a failed `verify-test` + for this reason. Fix shape: aggregator runs `if: always()`, + evaluates each `needs..result`, and exits non-zero when any is + not `"success"`. Anchor: `.github/workflows/ci.yml` `verify:` job; + PR #74 commit `c1aa82a` body. + +- **Match perf-budget assertions by the invariant only — regex + patterns with implicit upper bounds flake on slow CI runners.** + `require.Regexp` with a pattern like `0\.0[0-9]+` enforces an upper + bound (<0.1s) on a counter whose only invariant is `>0`. Two such + assertions flaked in one session on slow GH Actions runners (0.126s + and 539ms observed). Fix shape: relax to "any non-zero value" + (e.g., `\d+\.[0-9]*[1-9]`) or use baseline-relative comparisons. + Anchor: `bench_test.go` PR #76 commit `869450b`; `impl_test.go` PR + #78 commit `06b9ddf`. + ## Topic index — repo-wide Per-topic notes that apply to anyone working in this codebase. Read