Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
fix(ci): give the breaking-change gate the escape hatch it documents (#799)
Beenu Arorac4a4e0bc522a
diff --git a/.github/workflows/openapi-breaking.yml b/.github/workflows/openapi-breaking.ymlindex 8f56980c1..aeff3f99b 100644--- a/.github/workflows/openapi-breaking.yml+++ b/.github/workflows/openapi-breaking.yml@@ -5,11 +5,25 @@ name: OpenAPI breaking-change gate# touches docs/openapi.yaml, diff the PR's spec against the base branch's spec# and fail on any change that would break an existing generated SDK client# (removed endpoint/schema/field, type change, tightened request, dropped enum-# value). Ship a breaking change deliberately by bumping the version and adding-# a CHANGELOG BREAKING note (then a maintainer re-runs with --allow-breaking).+# value).+#+# Shipping a break deliberately: write a `### BREAKING` note under+# `## [Unreleased]` in CHANGELOG.md saying what moved and why it could not be+# preserved, then a maintainer applies the `breaking-change-approved` label to+# the PR. The label is the authorisation, and GitHub records who applied it and+# when on the PR timeline — which a workflow_dispatch boolean would not. The job+# re-runs on `labeled`/`unlabeled` so the label is a live control rather than+# something that only takes effect on the next push; it still runs the detector,+# names every break it is permitting in the job summary, and refuses the approval+# if the CHANGELOG note is missing or was inherited from an earlier PR.+#+# The version bump is not checked here: this repository accumulates under+# `[Unreleased]` and bumps VERSION when a release is cut, so a per-PR version+# check would demand something no PR can correctly do.on:pull_request:+ types: [opened, synchronize, reopened, labeled, unlabeled]paths:- "docs/openapi.yaml"- "scripts/openapi_diff.py"@@ -22,6 +36,7 @@ concurrency:permissions:contents: read+ pull-requests: readjobs:breaking-change:@@ -43,7 +58,7 @@ jobs:- name: Unit-test the detectorrun: python -m pytest tests/test_openapi_diff.py -v --tb=short- - name: Extract base-branch spec+ - name: Extract base-branch spec and CHANGELOGrun: |set -euo pipefailBASE="${{ github.event.pull_request.base.sha }}"@@ -54,6 +69,47 @@ jobs:echo "no base spec (new file) — nothing to compare"cp docs/openapi.yaml /tmp/base-openapi.yamlfi+ if git cat-file -e "${BASE}:CHANGELOG.md" 2>/dev/null; then+ git show "${BASE}:CHANGELOG.md" > /tmp/base-CHANGELOG.md+ else+ : > /tmp/base-CHANGELOG.md+ fi+ # Not approved: the ordinary path. The detector fails the PR on any break.- name: Diff for breaking changes+ if: ${{ !contains(github.event.pull_request.labels.*.name, 'breaking-change-approved') }}run: python scripts/openapi_diff.py --old /tmp/base-openapi.yaml --new docs/openapi.yaml++ # Approved: name the maintainer who applied the label, from the PR's own+ # event history, so the audit line does not depend on who pushed last.+ - name: Resolve the approval record+ id: approval+ if: contains(github.event.pull_request.labels.*.name, 'breaking-change-approved')+ env:+ GH_TOKEN: ${{ github.token }}+ REPO: ${{ github.repository }}+ PR_NUMBER: ${{ github.event.pull_request.number }}+ run: |+ set -uo pipefail+ record=$(gh api --paginate "repos/${REPO}/issues/${PR_NUMBER}/events" \+ --jq '.[] | select(.event == "labeled" and .label.name == "breaking-change-approved") | "@\(.actor.login) at \(.created_at)"' \+ 2>/dev/null | tail -n 1 || true)+ if [ -z "${record}" ]; then+ record="the 'breaking-change-approved' label on PR #${PR_NUMBER} (actor not resolved — see the PR timeline)"+ else+ record="${record}, via the 'breaking-change-approved' label on PR #${PR_NUMBER}"+ fi+ echo "record=${record}" >> "$GITHUB_OUTPUT"+ echo "approval: ${record}"++ - name: Diff for breaking changes (break approved by label)+ if: contains(github.event.pull_request.labels.*.name, 'breaking-change-approved')+ env:+ APPROVED_BY: ${{ steps.approval.outputs.record }}+ run: |+ python scripts/openapi_diff.py \+ --old /tmp/base-openapi.yaml --new docs/openapi.yaml \+ --allow-breaking \+ --changelog CHANGELOG.md \+ --changelog-base /tmp/base-CHANGELOG.md \+ --approved-by "${APPROVED_BY}"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 70e5df64e..f19a75f46 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -95,6 +95,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed+- **The OpenAPI gate's documented escape hatch did not exist.** The workflow+ header told a maintainer to "re-run with `--allow-breaking`" and+ `scripts/openapi_diff.py` claimed the flag was what "the release flow uses" —+ but the workflow triggered on `pull_request` only, with no dispatch, no input+ and no label check, and the diff step never passed the flag. `--allow-breaking`+ had **no caller anywhere in the tree**. A maintainer facing a correct,+ deliberate break had no action that worked, and the two statements describing+ the procedure were both false.++ The hatch is now a PR label, `breaking-change-approved`, chosen over a+ `workflow_dispatch` boolean because applying a label leaves an attributable+ record of who authorised the break and when on the PR timeline. The job reads+ that timeline and names the approver in its output. It re-runs on `labeled`+ and `unlabeled`, so the label is a live control rather than one that waits for+ the next push.++ Approval is not a skip, and the flag is no longer usable as a silent bypass:+ `--allow-breaking` now *requires* `--changelog` and `--changelog-base`, so it+ cannot be wired up without also wiring up the thing that records what was+ approved. The detector still runs, and the job summary lists every breaking+ change being permitted next to the CHANGELOG note that justified it. The+ approval is refused if there is no `### BREAKING` section under+ `## [Unreleased]`, or if that section is byte-identical to the base branch's —+ checked in both directions, because "a BREAKING section exists" alone would+ let the first note in a release cycle excuse every later break in that cycle.++ The version-bump half of the old promise was dropped rather than implemented:+ this repository accumulates under `[Unreleased]` and bumps `VERSION` at+ release-cut, so a per-PR version check would demand something no PR can+ correctly do. The comment now says what the control does.++ Thirteen new tests, all of which fail against the pre-change tree. Four are+ wiring assertions over the workflow YAML itself — that some step passes+ `--allow-breaking`, that the step passing it is guarded by the label and+ presents its evidence, that the unapproved path still blocks, and that+ `labeled` is in the trigger types. A unit-tested function with no caller is+ indistinguishable from a working feature until something asserts the call.+- **A dry run called the customer's production SIEM.** The live-action dry-runpath works by stripping credentials so the executor falls through tosimulation, and the strip list did not match what the client factory reads:diff --git a/apps/docs/docs/contributing/guidelines.md b/apps/docs/docs/contributing/guidelines.mdindex c462f3f0f..d25ce5d03 100644--- a/apps/docs/docs/contributing/guidelines.md+++ b/apps/docs/docs/contributing/guidelines.md@@ -152,6 +152,52 @@ must include:> [eval harness page](../benchmark) explains exactly which is which. Update> that page in the same commit if your PR changes a suite's metric category.+### 4. OpenAPI breaking-change gate {#openapi-breaking-change-gate}++A PR that touches `docs/openapi.yaml` is diffed against the base branch by+`scripts/openapi_diff.py`. It fails on any change that would break an existing+generated SDK client: a removed path, operation, schema or property, a changed+property type, an optional field becoming required, a new required field on a+request-shaped schema, a dropped enum value, or a new required parameter.++Run it yourself before pushing:++```bash+git show origin/main:docs/openapi.yaml > /tmp/base-openapi.yaml+python scripts/openapi_diff.py --old /tmp/base-openapi.yaml --new docs/openapi.yaml+```++Additive changes — a new path, a new optional field, a new enum value — are not+flagged. Most spec changes need nothing further.++#### Shipping a break deliberately++Sometimes the break is the point: a schema described data the platform never+measured, or a field promised a number with no formula behind it. Removing it is+correct, and preserving it would keep the lie. Two steps:++1. **Write the record.** Add a `### BREAKING` section under `## [Unreleased]` in+ `CHANGELOG.md` saying what moved, what replaced it, and why it could not be+ preserved. Name each field. This is the half that outlives CI logs.+2. **Get it authorised.** Ask a maintainer to apply the+ `breaking-change-approved` label to the PR.++The label is the authorisation, and it is deliberately a label rather than a+workflow input: GitHub records who applied it and when on the PR timeline, so+the approval is attributable after the fact. The gate re-runs on `labeled` and+`unlabeled`, so applying or removing it takes effect immediately.++Approval is not a skip. The detector still runs, and the job summary lists+**every** breaking change being permitted alongside the CHANGELOG note that+justified it — the record says what was approved, not merely that something was.+The gate refuses the approval outright if the CHANGELOG note is missing, or if+the `### BREAKING` section is unchanged from the base branch (a note written for+an earlier PR does not describe yours).++There is no version-bump requirement here. This repository accumulates under+`[Unreleased]` and bumps `VERSION` when a release is cut, so no single PR can+correctly satisfy one.+## Commit MessagesFollow [Conventional Commits](https://www.conventionalcommits.org/). Thediff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.mdindex 46514b4ab..9b098d014 100644--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md@@ -37,7 +37,7 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`| Container image / IaC / secret scanning (Trivy/checkov/tfsec/gitleaks/Semgrep) | (implied by security) | `security.yml` (claim-matrix ratchet HARD; gitleaks/Semgrep/Trivy/checkov/tfsec observe) | PARTIAL (matrix ratchet enforced; secret + code/IaC/container scanners report-and-ratchet, allowlist at `.security/allowlist.yml` / `.gitleaksignore`; GitHub push-protection is the always-on hard secret gate) | Phase 2 || Signed / attested release artifacts | (implied by "run next to crown jewels") | `release.yml` + `publish-images.yml` (cosign keyless signatures, CycloneDX SBOM attestation, BuildKit SLSA provenance + SPDX SBOM per image; SHA-pinned actions), `build-extensions.yml` (extension cosign) | GATED | - || Insecure defaults hard-fail in production | (implied by self-host) | `ci.yml` api tests (`test_security_defaults.py::test_enforce_*`; `enforce_secure_defaults` raises at boot in production) | GATED | - |-| OpenAPI stability for 3 SDKs + MCP | (implied by SDKs) | `check-openapi.yml` (drift) + `openapi-breaking.yml` (`scripts/openapi_diff.py` — PR spec vs base fails on removed endpoint/schema/field, type change, tightened request, or dropped enum value) | GATED | - |+| OpenAPI stability for 3 SDKs + MCP | (implied by SDKs) | `check-openapi.yml` (drift) + `openapi-breaking.yml` (`scripts/openapi_diff.py` — PR spec vs base fails on removed endpoint/schema/field, type change, tightened request, or dropped enum value). A deliberate break goes through the `breaking-change-approved` PR label, which still runs the detector and records every break it permits plus the CHANGELOG `### BREAKING` note that justified it; `--allow-breaking` requires that note as an argument, so the bypass cannot be wired up without the record. Four of the tests assert the *workflow* reaches the flag — it previously had no caller at all | GATED | - || Ingested events land in the queryable ClickHouse lake | README (SIEM / lake) | `integration.yml :: spine` (Phase A1 — after the spine ingests, asserts `SELECT count() FROM aisoc.raw_events > 0` against the live ClickHouse container; `services/fusion` `LakeWriter` archives every normalized event) | GATED | - || Detection rules fire on the live event stream (not just CI fixtures) | README L170 (detection engine) | `integration.yml :: spine` (Phase A2 — posts an event matching the native `aws-root-account-login` rule, asserts the fusion `DetectionEngine` produces the alert) + `validate-detections.yml` (exported-ruleset drift `--check`) + fusion `test_detection_engine.py` / `test_detection_matcher_parity.py` | GATED | - || Three-model AI: behavioral (UEBA) model feeds alert scoring in production | README (multi-model) | `ci.yml` fusion job (`test_ueba_signal.py` — the `ueba.anomalies` stream warms a per-entity cache that boosts fuse-time confidence + anomaly score; wired in `fusion_engine.process`) | GATED | - |diff --git a/scripts/openapi_diff.py b/scripts/openapi_diff.pyindex 92b2eba66..db5f87d12 100644--- a/scripts/openapi_diff.py+++ b/scripts/openapi_diff.py@@ -20,15 +20,23 @@ of an existing generated client. Breaking classes:* an enum value was removed (a client with exhaustive handling breaks),* a new required parameter was added to an existing operation.-`--old`/`--new` take spec files; exit 1 if any breaking change is found (unless-`--allow-breaking`, which the release flow uses when it deliberately ships a-major bump). The CI job (`openapi-breaking.yml`) diffs the PR spec against the-base branch's spec, so a breaking change blocks the PR until it's intentional.+`--old`/`--new` take spec files; exit 1 if any breaking change is found. The CI+job (`openapi-breaking.yml`) diffs the PR spec against the base branch's spec,+so a breaking change blocks the PR until it is deliberate.++Shipping one deliberately goes through `--allow-breaking`, which the gate passes+only when a maintainer has applied the `breaking-change-approved` label to the+pull request. The flag is not a silent bypass: it *requires* `--changelog` and+`--changelog-base`, refuses the approval unless this change added a `### BREAKING`+note under `## [Unreleased]`, and prints every break it is permitting — so the+record says what was approved rather than merely that something was."""from __future__ import annotationsimport argparse+import os+import reimport sysfrom dataclasses import dataclassfrom pathlib import Path@@ -156,12 +164,104 @@ def load_spec(path: Path) -> dict[str, Any]:return yaml.safe_load(path.read_text(encoding="utf-8")) or {}-def main() -> int:+# ── CHANGELOG evidence for an approved break ────────────────────────────────+#+# The approval label says a maintainer authorised the break. The CHANGELOG note+# is what says *what* was broken, and it is the half that outlives CI logs.++_H2 = re.compile(r"^##\s+")+_H3 = re.compile(r"^###\s+")+_UNRELEASED = re.compile(r"^##\s+\[Unreleased\]", re.IGNORECASE)+_BREAKING_HEADING = re.compile(r"^###\s+BREAKING\b", re.IGNORECASE)+++def changelog_breaking_notes(text: str) -> list[str]:+ """Non-blank lines under `### BREAKING` inside the `## [Unreleased]` section.++ Scoped to Unreleased on purpose: a BREAKING heading in an already-shipped+ release section describes a past break and must not stand in for this one.+ """+ lines = text.splitlines()+ start = next((n for n, line in enumerate(lines) if _UNRELEASED.match(line)), None)+ if start is None:+ return []+ notes: list[str] = []+ in_breaking = False+ for line in lines[start + 1 :]:+ if _H2.match(line): # the next release section — Unreleased has ended+ break+ if _H3.match(line):+ in_breaking = bool(_BREAKING_HEADING.match(line))+ continue+ if in_breaking and line.strip():+ notes.append(line.strip())+ return notes+++def changelog_evidence(old_text: str, new_text: str) -> tuple[list[str], str | None]:+ """Notes this change added, or a reason the approval cannot be honoured.++ Checked in both directions. "A BREAKING section exists" alone would let the+ first such note in a release cycle excuse every later break in that cycle,+ so the note must also differ from the base branch's.+ """+ new_notes = changelog_breaking_notes(new_text)+ if not new_notes:+ return [], "the CHANGELOG has no '### BREAKING' section with content under '## [Unreleased]'"+ old_notes = set(changelog_breaking_notes(old_text))+ added = [note for note in new_notes if note not in old_notes]+ if not added:+ return [], (+ "the '### BREAKING' section under '## [Unreleased]' is byte-identical to the "+ "base branch's, so it documents an earlier break and not this one"+ )+ return added, None+++def approval_record(breaking: list[Change], notes: list[str], approved_by: str) -> str:+ """The audit line: who permitted it, and exactly what they permitted."""+ lines = [+ "## Breaking OpenAPI changes PERMITTED",+ "",+ f"Authorised by: {approved_by or 'not resolved — see the pull request timeline'}",+ "",+ f"The detector ran and found {len(breaking)} breaking change(s). All are permitted:",+ "",+ ]+ lines += [f"- `{c.kind}` — {c.detail}" for c in breaking]+ lines += ["", "CHANGELOG `### BREAKING` note added by this change:", ""]+ lines += [f"> {note}" for note in notes]+ return "\n".join(lines)+++def _write_step_summary(record: str) -> None:+ """Mirror the record onto the check-run page, not just into the job log."""+ path = os.environ.get("GITHUB_STEP_SUMMARY")+ if not path:+ return+ with open(path, "a", encoding="utf-8") as handle:+ handle.write(record + "\n")+++def main(argv: list[str] | None = None) -> int:parser = argparse.ArgumentParser(description=__doc__)parser.add_argument("--old", required=True, type=Path, help="baseline spec (e.g. base branch / last release)")parser.add_argument("--new", required=True, type=Path, help="candidate spec (e.g. this PR)")- parser.add_argument("--allow-breaking", action="store_true", help="permit breaking changes (deliberate major bump)")- args = parser.parse_args()+ parser.add_argument(+ "--allow-breaking",+ action="store_true",+ help="permit breaking changes; requires --changelog/--changelog-base as evidence",+ )+ parser.add_argument("--changelog", type=Path, help="candidate CHANGELOG.md (required with --allow-breaking)")+ parser.add_argument("--changelog-base", type=Path, help="baseline CHANGELOG.md (required with --allow-breaking)")+ parser.add_argument("--approved-by", default="", help="who authorised the break; recorded in the audit line")+ args = parser.parse_args(argv)++ # A bypass that can be taken on trust is not auditable. Requiring the+ # evidence as arguments means --allow-breaking cannot be wired up later+ # without also wiring up the thing that records what was approved.+ if args.allow_breaking and not (args.changelog and args.changelog_base):+ parser.error("--allow-breaking requires --changelog and --changelog-base (the CHANGELOG BREAKING note is the evidence)")old = load_spec(args.old)new = load_spec(args.new)@@ -172,20 +272,38 @@ def main() -> int:print(f"OK: no breaking OpenAPI changes ({len(changes)} total change(s))")return 0+ # The detector runs and names every break whether or not it is approved.print(f"Found {len(breaking)} BREAKING OpenAPI change(s):", file=sys.stderr)for c in breaking:print(f" - [{c.kind}] {c.detail}", file=sys.stderr)- if args.allow_breaking:- print("--allow-breaking set: not failing (deliberate breaking release).", file=sys.stderr)- return 0- print(- "\nBreaking API changes break every generated SDK client. Either avoid the "- "break, or ship it deliberately with a version bump + CHANGELOG BREAKING note "- "and re-run with --allow-breaking.",- file=sys.stderr,+ if not args.allow_breaking:+ print(+ "\nBreaking API changes break every generated SDK client. Either avoid the "+ "break, or ship it deliberately: add a '### BREAKING' note under "+ "'## [Unreleased]' in CHANGELOG.md saying what moved and why it could not "+ "be preserved, then have a maintainer apply the 'breaking-change-approved' "+ "label to the pull request.",+ file=sys.stderr,+ )+ return 1++ notes, problem = changelog_evidence(+ args.changelog_base.read_text(encoding="utf-8"),+ args.changelog.read_text(encoding="utf-8"),)- return 1+ if problem:+ print(+ f"\nApproval REFUSED: {problem}. The label authorises a break; the CHANGELOG "+ "note is what records which break, and it has to outlive this job log.",+ file=sys.stderr,+ )+ return 1++ record = approval_record(breaking, notes, args.approved_by)+ print(record)+ _write_step_summary(record)+ return 0if __name__ == "__main__":diff --git a/tests/test_openapi_diff.py b/tests/test_openapi_diff.pyindex db274c236..12f8c7d21 100644--- a/tests/test_openapi_diff.py+++ b/tests/test_openapi_diff.py@@ -10,10 +10,17 @@ from __future__ import annotationsimport sysfrom pathlib import Path+import pytest+import yaml+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))import openapi_diff as od # noqa: E402+_REPO = Path(__file__).resolve().parents[1]+_WORKFLOW = _REPO / ".github" / "workflows" / "openapi-breaking.yml"+_LABEL = "breaking-change-approved"+def _spec(paths=None, schemas=None):return {@@ -126,3 +133,220 @@ def test_ref_type_signature_change_is_breaking():def test_identical_specs_have_no_changes():s = _spec(paths={"/a": {"get": {}}}, schemas={"User": {"properties": {"id": {"type": "string"}}}})assert od.diff(s, s) == []+++# ── The deliberate-break escape hatch ────────────────────────────────────────+#+# `--allow-breaking` shipped with no caller: the workflow triggered on+# pull_request only and never passed the flag, so the documented way to ship a+# deliberate break did not exist. These cover both halves — that the flag does+# what it claims, and that the workflow actually reaches it.++_CHANGELOG_BASE = """# Changelog++## [Unreleased]++### Security++- something unrelated++## [1.0.0]++### BREAKING++- an old break, already shipped+"""++_CHANGELOG_WITH_NOTE = """# Changelog++## [Unreleased]++### BREAKING++- `Thing.health_score` is removed; it was an undefined composite.++### Security++- something unrelated++## [1.0.0]++### BREAKING++- an old break, already shipped+"""+++def _write_pair(tmp_path, old_spec, new_spec):+ old = tmp_path / "old.yaml"+ new = tmp_path / "new.yaml"+ old.write_text(yaml.safe_dump(old_spec), encoding="utf-8")+ new.write_text(yaml.safe_dump(new_spec), encoding="utf-8")+ return old, new+++def _breaking_pair(tmp_path):+ return _write_pair(+ tmp_path,+ _spec(schemas={"Thing": {"properties": {"id": {"type": "string"}, "health_score": {"type": "number"}}}}),+ _spec(schemas={"Thing": {"properties": {"id": {"type": "string"}}}}),+ )+++def _changelogs(tmp_path, new_text):+ base = tmp_path / "base-CHANGELOG.md"+ head = tmp_path / "CHANGELOG.md"+ base.write_text(_CHANGELOG_BASE, encoding="utf-8")+ head.write_text(new_text, encoding="utf-8")+ return base, head+++def test_a_break_without_approval_still_fails(tmp_path):+ old, new = _breaking_pair(tmp_path)+ assert od.main(["--old", str(old), "--new", str(new)]) == 1+++def test_allow_breaking_without_changelog_evidence_is_an_argument_error(tmp_path):+ """The bypass cannot be taken on trust: the evidence is mandatory.++ Before this change `--allow-breaking` alone silently returned 0, which is+ what made it usable as an invisible bypass had anything ever called it.+ """+ old, new = _breaking_pair(tmp_path)+ with pytest.raises(SystemExit) as excinfo:+ od.main(["--old", str(old), "--new", str(new), "--allow-breaking"])+ assert excinfo.value.code == 2+++def test_approved_break_passes_when_the_changelog_records_it(tmp_path):+ old, new = _breaking_pair(tmp_path)+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)+ rc = od.main(+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]+ )+ assert rc == 0+++def test_approved_break_is_refused_when_the_changelog_says_nothing(tmp_path):+ old, new = _breaking_pair(tmp_path)+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_BASE)+ rc = od.main(+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]+ )+ assert rc == 1+++def test_an_inherited_note_does_not_excuse_a_later_break(tmp_path):+ """Both directions. "A BREAKING section exists" would let the first note in+ a release cycle excuse every later break in that cycle."""+ old, new = _breaking_pair(tmp_path)+ base_cl = tmp_path / "base-CHANGELOG.md"+ head_cl = tmp_path / "CHANGELOG.md"+ base_cl.write_text(_CHANGELOG_WITH_NOTE, encoding="utf-8")+ head_cl.write_text(_CHANGELOG_WITH_NOTE, encoding="utf-8")+ rc = od.main(+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]+ )+ assert rc == 1+++def test_a_note_in_a_shipped_release_section_is_not_evidence():+ notes = od.changelog_breaking_notes(_CHANGELOG_BASE)+ assert notes == [], "a BREAKING heading under [1.0.0] describes a past break"+++def test_the_approval_names_every_break_it_permits(tmp_path, capsys):+ """"Approved" must record *what* was approved, not merely that something was."""+ old, new = _write_pair(+ tmp_path,+ _spec(paths={"/gone": {"get": {}}}, schemas={"Thing": {"properties": {"id": {"type": "string"}, "score": {"type": "number"}}}}),+ _spec(paths={}, schemas={"Thing": {"properties": {"id": {"type": "string"}}}}),+ )+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)+ rc = od.main(+ [+ "--old", str(old), "--new", str(new), "--allow-breaking",+ "--changelog", str(head_cl), "--changelog-base", str(base_cl),+ "--approved-by", "@maintainer at 2026-01-01T00:00:00Z",+ ]+ )+ out = capsys.readouterr().out+ assert rc == 0+ assert "@maintainer at 2026-01-01T00:00:00Z" in out+ assert "path '/gone' was removed" in out+ assert "Thing.score was removed" in out+ assert "health_score" in out, "the CHANGELOG note that justified it is part of the record"+++def test_the_approval_record_reaches_the_check_run_page(tmp_path, monkeypatch):+ """A record only in the job log is one click further from a reviewer than+ the summary, and job logs age out."""+ summary = tmp_path / "summary.md"+ monkeypatch.setenv("GITHUB_STEP_SUMMARY", str(summary))+ old, new = _breaking_pair(tmp_path)+ base_cl, head_cl = _changelogs(tmp_path, _CHANGELOG_WITH_NOTE)+ od.main(+ ["--old", str(old), "--new", str(new), "--allow-breaking", "--changelog", str(head_cl), "--changelog-base", str(base_cl)]+ )+ assert "Thing.health_score was removed" in summary.read_text(encoding="utf-8")+++# ── The workflow must actually reach the flag ────────────────────────────────+++def _workflow():+ doc = yaml.safe_load(_WORKFLOW.read_text(encoding="utf-8"))+ # PyYAML resolves a bare `on:` key to the boolean True (YAML 1.1).+ triggers = doc.get("on", doc.get(True))+ steps = doc["jobs"]["breaking-change"]["steps"]+ return triggers, steps+++def _diff_steps():+ _, steps = _workflow()+ return [s for s in steps if "openapi_diff.py" in (s.get("run") or "")]+++def test_the_workflow_passes_allow_breaking_somewhere():+ """The defect this closes: the flag existed, was tested, and had no caller."""+ assert any("--allow-breaking" in s["run"] for s in _diff_steps()), (+ "no step invokes --allow-breaking, so the documented escape hatch does not exist"+ )+++def test_the_approved_path_is_guarded_by_the_label_and_presents_its_evidence():+ approved = [s for s in _diff_steps() if "--allow-breaking" in s["run"]]+ assert len(approved) == 1, "exactly one step may permit breaks"+ step = approved[0]+ assert _LABEL in str(step.get("if", "")), "the bypass must be guarded by the approval label"+ assert "--changelog " in step["run"] and "--changelog-base" in step["run"]+++def test_the_unapproved_path_never_permits_a_break():+ unapproved = [s for s in _diff_steps() if "--allow-breaking" not in s["run"]]+ assert unapproved, "the ordinary blocking path must still exist"+ for step in unapproved:+ assert "--allow-breaking" not in step["run"]+++def test_the_approved_path_still_runs_the_detector():+ """Approval must not short-circuit detection — otherwise the record cannot+ say what was permitted."""+ approved = [s for s in _diff_steps() if "--allow-breaking" in s["run"]][0]+ assert "--old" in approved["run"] and "--new" in approved["run"]+++def test_applying_the_label_re_runs_the_gate():+ """Without `labeled`, the label would only take effect on the next push —+ a control that appears to do something and does not."""+ triggers, _ = _workflow()+ types = triggers["pull_request"]["types"]+ assert "labeled" in types and "unlabeled" in types+++def test_the_label_name_the_script_tells_contributors_matches_the_workflow():+ """One-directional drift: renaming the label in CI while the instructions+ still name the old one leaves contributors following a dead procedure."""+ script = (_REPO / "scripts" / "openapi_diff.py").read_text(encoding="utf-8")+ assert _LABEL in script+ assert _LABEL in _WORKFLOW.read_text(encoding="utf-8")