V13-FE-006: consolidate approved UI and contract hardening

.gitea/workflows/openapi-gate.yml

@@ -36,23 +36,23 @@ jobs:
           mkdir -p /tmp/openapi
           dotnet run --project src/KArtSell.Host -c Release -- \
             --generate-openapi-spec-only \
-            --output /tmp/openapi/current.json || true
+            --output /tmp/openapi/current.json
+          test -s /tmp/openapi/current.json
 
       - name: Checkout main branch
         run: |
           git fetch origin main:main
           git checkout main
 
-      - name: Build main branch
+      - name: Load approved baseline OpenAPI spec
         run: |
-          dotnet restore
-          dotnet build -c Release --no-restore
-
-      - name: Generate baseline OpenAPI spec
-        run: |
-          dotnet run --project src/KArtSell.Host -c Release -- \
-            --generate-openapi-spec-only \
-            --output /tmp/openapi/baseline.json || true
+          test -s docs/api/openapi.json || {
+            echo "Approved baseline missing: docs/api/openapi.json"
+            echo "Create and approve the baseline before enabling OpenAPI diff comparisons."
+            exit 1
+          }
+          cp docs/api/openapi.json /tmp/openapi/baseline.json
+          test -s /tmp/openapi/baseline.json
 
       - name: Checkout PR branch again
         run: git checkout -
@@ -148,21 +148,7 @@ jobs:
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: `⛔ **OpenAPI Gate Failed: Breaking Changes Detected**
-
-This PR introduces breaking changes to the API contract:
-- Required parameters removed
-- Response fields removed
-- Status codes removed
-
-**Action Required:**
-1. Modify your changes to be backward-compatible, OR
-2. Request approval from @api-architects with justification
-
-Breaking change approval requires:
-- [x] Documented rationale (why breaking is necessary)
-- [x] Migration plan for existing clients
-- [x] Version bump (major version for breaking changes)`
+              body: '⛔ **OpenAPI Gate Failed: Breaking Changes Detected**\n\nThis PR introduces breaking changes to the API contract. Required parameters, response fields, or status codes were removed. Modify the changes for backward compatibility or request API Architect approval with rationale, migration plan, and version bump.'
             })
 
       - name: Comment on PR (All Clear)
@@ -174,9 +160,7 @@ Breaking change approval requires:
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: `✅ **OpenAPI Gate Passed: No Breaking Changes**
-
-Your API changes are backward-compatible. Safe to merge.`
+              body: '✅ **OpenAPI Gate Passed: No Breaking Changes**\n\nYour API changes are backward-compatible. Safe to merge.'
             })
 
   openapi-approval:
@@ -193,7 +177,7 @@ Your API changes are backward-compatible. Safe to merge.`
           exit 1
 
   openapi-specs-update:
-    name: Update Committed OpenAPI Specs (if merged)
+    name: Publish OpenAPI Candidate Artifact (manual approval required)
     if: success()
     needs: openapi-diff
     runs-on: ubuntu-latest
@@ -207,20 +191,17 @@ Your API changes are backward-compatible. Safe to merge.`
         with:
           dotnet-version: '10.x'
 
-      - name: Generate OpenAPI spec
+      - name: Generate candidate OpenAPI spec
         run: |
-          mkdir -p docs/api
+          mkdir -p /tmp/openapi
           dotnet run --project src/KArtSell.Host -c Release -- \
             --generate-openapi-spec-only \
-            --output docs/api/openapi.json
+            --output /tmp/openapi/candidate.json
+          test -s /tmp/openapi/candidate.json
 
-      - name: Commit updated spec
-        run: |
-          git config user.email "ci@example.com"
-          git config user.name "CI Bot"
-
-          if ! git diff --quiet docs/api/openapi.json; then
-            git add docs/api/openapi.json
-            git commit -m "ci: Update OpenAPI specification (auto-generated)"
-            git push
-          fi
+      - name: Upload candidate for API Architect review
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-candidate
+          path: /tmp/openapi/candidate.json
+          if-no-files-found: error