From 5e5104bb3649cace92bcf5d181d06496c75539a7 Mon Sep 17 00:00:00 2001
From: Bharat Kunwar <brtkwr@gmail.com>
Date: Thu, 29 Oct 2026 15:54:40 +0545
Subject: [PATCH] PLAT-1314/ci: reject stale embedded OpenAPI specs

---
 .github/workflows/ci.yml   |  2 ++
 Makefile                   |  5 ++++-
 README.md                  |  8 ++++++++
 scripts/check-generated.sh | 20 ++++++++++++++++++++
 4 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100755 scripts/check-generated.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b5b641b..7c508a2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,6 +19,8 @@ jobs:
           go-version: '1.26'
           cache: true
       - run: go build ./...
+      - name: Check embedded spec drift
+        run: make check-generated
       - run: make test-cover
 
   lint:
diff --git a/Makefile b/Makefile
index 95e2701..bcae7f7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: build install regen test test-cover lint tidy clean release-dry help
+.PHONY: build install regen check-generated test test-cover lint tidy clean release-dry help
 
 BINARY  := twoctl
 PKG     := github.com/two-inc/twoctl-cli
@@ -17,6 +17,9 @@ install: ## Install twoctl into $$GOBIN (or $$GOPATH/bin).
 regen: ## Refresh embedded OpenAPI specs from openapi/<api>-api.yaml.
 	./scripts/codegen.sh
 
+check-generated: ## Regenerate embedded specs and fail if committed output is stale.
+	./scripts/check-generated.sh
+
 test: ## Run all unit tests.
 	go test ./...
 
diff --git a/README.md b/README.md
index 5e260f7..c30e81b 100644
--- a/README.md
+++ b/README.md
@@ -261,6 +261,14 @@ To regenerate locally:
 go build ./...
 ```
 
+CI runs `make check-generated` on every pull request and main-branch push.
+It regenerates the embedded specs from the committed `openapi/` inputs and
+fails if any embedded file changes or is newly generated but untracked.
+When changing source specs or the preprocessor, run `make regen` and commit
+the updated `cmd/twoctl/cli/specs/` files with the change. This check uses
+vendored inputs and does not fetch upstream specs or require API credentials;
+the nightly `regenerate` workflow continues to handle upstream refreshes.
+
 ## Contributing
 
 This repository is generated from the OpenAPI specs in [`two-inc/docs`](https://github.com/two-inc/docs).
diff --git a/scripts/check-generated.sh b/scripts/check-generated.sh
new file mode 100755
index 0000000..c2d4a2e
--- /dev/null
+++ b/scripts/check-generated.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Check that the embedded OpenAPI specs match their committed source inputs.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${ROOT}"
+
+./scripts/codegen.sh
+
+# Include untracked files: adding a generator output must fail until that new
+# file is committed, even though git diff alone would not show it.
+changes="$(git status --porcelain --untracked-files=all -- cmd/twoctl/cli/specs/)"
+if [[ -n "${changes}" ]]; then
+  echo "::error::Embedded OpenAPI specs are stale. Run make regen and commit cmd/twoctl/cli/specs/."
+  printf '%s\n' "${changes}"
+  git --no-pager diff -- cmd/twoctl/cli/specs/
+  exit 1
+fi
+
+echo "embedded OpenAPI specs are up to date"