From aca3cf46047a2d8cb7508c4edf11d1452f6bd4fa Mon Sep 17 00:00:00 2001 From: subencheng Date: Tue, 15 Sep 2026 13:58:01 -0700 Subject: [PATCH 1/2] Add B10 API spec drift rule to connector review mixin The connector mixin covered newly added endpoints (B7, B8) but had no criterion for an existing endpoint being changed, so version/path swaps and response shape changes could pass review unflagged. B10 triggers only on endpoint change or addition. A changed endpoint is diffed against the checked-in api.yaml and reported as a blocking correctness break when the schema differs; an added endpoint is a suggestion to regenerate the spec. Both point the author at the build-openapi-spec.md skill. Co-Authored-By: Claude Opus 5 (1M context) --- .github/actions/pr-review/prompts/mixins/connector.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.github/actions/pr-review/prompts/mixins/connector.md b/.github/actions/pr-review/prompts/mixins/connector.md index 830de35..abbfc57 100644 --- a/.github/actions/pr-review/prompts/mixins/connector.md +++ b/.github/actions/pr-review/prompts/mixins/connector.md @@ -107,6 +107,17 @@ Criteria: - B7: New required OAuth scopes - B8: New endpoints added to existing sync paths can be breaking when they require new scopes or permissions - B9: Safe changes: display name changes, adding new resource types, adding trait options, adding pagination +- B10: API spec drift. Trigger this rule only when the diff changes or adds an API endpoint + (endpoint constants, request paths, base URL, or the request/response structs bound to a call). + Do not raise it for unrelated changes. + - Endpoint changed: compare the new request and response shape against the checked-in + `api.yaml` if one is present. If the schema differs — path or version changed, fields + added, removed, renamed, or retyped, ID field changed, or pagination style changed — report + it as `blocking-correctness` breaking change, and tell the author to regenerate the spec + by running the `build-openapi-spec.md` skill. If no `api.yaml` is present, treat it as the + added-endpoint case below. + - Endpoint added: not a breaking change. Report a `suggestion` asking the author to run the + `build-openapi-spec.md` skill so `api.yaml` covers the new endpoint. Breaking connector changes should be gated behind opt-in config where possible, called out in the PR description, and paired with documentation updates. From 794706547ce58a8cedd6c174aee097dd773e8b8a Mon Sep 17 00:00:00 2001 From: subencheng Date: Tue, 15 Sep 2026 14:01:01 -0700 Subject: [PATCH 2/2] Point B10 at spec/openapi.json and flag stale specs Rename the spec reference from api.yaml to the real path, spec/openapi.json. Also require the regeneration prompt whenever an endpoint changes without a corresponding spec update, not only when the schema visibly differs. Co-Authored-By: Claude Opus 5 (1M context) --- .../actions/pr-review/prompts/mixins/connector.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/actions/pr-review/prompts/mixins/connector.md b/.github/actions/pr-review/prompts/mixins/connector.md index abbfc57..2b7e804 100644 --- a/.github/actions/pr-review/prompts/mixins/connector.md +++ b/.github/actions/pr-review/prompts/mixins/connector.md @@ -111,13 +111,15 @@ Criteria: (endpoint constants, request paths, base URL, or the request/response structs bound to a call). Do not raise it for unrelated changes. - Endpoint changed: compare the new request and response shape against the checked-in - `api.yaml` if one is present. If the schema differs — path or version changed, fields - added, removed, renamed, or retyped, ID field changed, or pagination style changed — report - it as `blocking-correctness` breaking change, and tell the author to regenerate the spec - by running the `build-openapi-spec.md` skill. If no `api.yaml` is present, treat it as the - added-endpoint case below. + `spec/openapi.json`. If the schema differs — path or version changed, fields added, + removed, renamed, or retyped, ID field changed, or pagination style changed — report it as + a `blocking-correctness` breaking change. If `spec/openapi.json` was not updated in this + PR, it is now stale: report that as well, at `suggestion` severity when the schema looks + unchanged. In every changed-endpoint case, tell the author to regenerate + `spec/openapi.json` by running the `build-openapi-spec.md` skill. If no + `spec/openapi.json` exists, treat it as the added-endpoint case below. - Endpoint added: not a breaking change. Report a `suggestion` asking the author to run the - `build-openapi-spec.md` skill so `api.yaml` covers the new endpoint. + `build-openapi-spec.md` skill so `spec/openapi.json` covers the new endpoint. Breaking connector changes should be gated behind opt-in config where possible, called out in the PR description, and paired with documentation updates.