diff --git a/changelog.d/maintenance/quality-policies-ws5.md b/changelog.d/maintenance/quality-policies-ws5.md new file mode 100644 index 0000000000..990c7e7c20 --- /dev/null +++ b/changelog.d/maintenance/quality-policies-ws5.md @@ -0,0 +1 @@ +- **Docs**: `QUALITY_GATES.md` now codifies the per-runner test retry policy (Playwright 1 CI retry with trace; Vitest per-test explicit quarantine only; node:test never) with target flake SLOs, and the release-level ratchet-drift rule (combination drift on the pure tip is the release captain's to fix once on the branch — never pushed onto contributor PRs, never rebaselined per-PR) diff --git a/docs/architecture/QUALITY_GATES.md b/docs/architecture/QUALITY_GATES.md index 3686b9eef4..c2970af8f9 100644 --- a/docs/architecture/QUALITY_GATES.md +++ b/docs/architecture/QUALITY_GATES.md @@ -173,6 +173,31 @@ pending implementation). --- +## Test Retry Policy (WS5.4, v3.8.49) + +Retry is per-runner, never a global blanket — a blanket retry converts real regressions +into invisible flakes: + +| Runner | Policy | Why | +| --- | --- | --- | +| Playwright (e2e) | `retries: 1` in CI only, with `trace: on-first-retry` | Browser/network timing is genuinely nondeterministic; one retry with a trace turns a flake into a diagnosable artifact | +| Vitest | NO global retry. A proven-flaky test gets an explicit per-test retry (visible in the diff, reviewed in PR) | Keeps the quarantine list in the repo, never opaque | +| node:test (unit) | NO retry, ever | A flaky unit test is a bug in the test — fix it, don't re-roll it | + +Target SLOs once flake telemetry lands (WS5.2/5.3): <1% flake rate per test +("fix now" threshold), ≥95% pass rate per pipeline. Industry reference values — +recalibrate against our own measurements. + +## Release-Level Ratchet Drift (WS5.5, v3.8.49) + +When a ratchet (file-size, complexity, eslint warnings) regresses on the PURE release +tip — i.e. the COMBINATION of merges regressed it, and no single PR reproduces the +regression on its own branch — the fix belongs to the **release captain, once, on the +release branch**: prefer extraction/refactor; rebaseline only with the documented +justification entry. Never push combination drift onto a contributor PR, and never +rebaseline per-PR (that hides real regressions). Discriminate first: reproduce the +red against the pure tip in a probe worktree before assuming your PR caused it. + ## Allowlist Policy Every gate that cannot fail on pre-existing violations uses a frozen allowlist