Implement severity-based drift classification and tiered documentation

.github/workflows/drift-guard.yml

@@ -49,8 +49,21 @@ jobs:
           python -m drift_guard.guard check
           EXIT_CODE=$?
           echo "drift_exit_code=$EXIT_CODE" >> "$GITHUB_OUTPUT"
-          if [ "$EXIT_CODE" -eq 2 ]; then
-            echo "::warning::API drift detected — docs are out of sync with the code"
+
+          # Exit codes: 10=GREEN, 11=YELLOW, 2=RED
+          if [ "$EXIT_CODE" -eq 10 ]; then
+            echo "drift_severity=green" >> "$GITHUB_OUTPUT"
+            echo "::notice::Non-breaking API drift detected — Tier 1 docs regenerated"
+            # Auto-update baseline for GREEN
+            python -m drift_guard.guard baseline
+          elif [ "$EXIT_CODE" -eq 11 ]; then
+            echo "drift_severity=yellow" >> "$GITHUB_OUTPUT"
+            echo "::warning::Potentially breaking API drift — PR review required"
+          elif [ "$EXIT_CODE" -eq 2 ]; then
+            echo "drift_severity=red" >> "$GITHUB_OUTPUT"
+            echo "::error::BREAKING API drift detected — escalating"
+          else
+            echo "drift_severity=none" >> "$GITHUB_OUTPUT"
           fi
           # Don't fail yet — collect all results first
           exit 0
@@ -98,23 +111,37 @@ jobs:
       - name: Final result
         run: |
           DRIFT=${{ steps.drift.outputs.drift_exit_code }}
+          SEVERITY=${{ steps.drift.outputs.drift_severity }}
           TESTS=${{ steps.contracts.outputs.test_exit_code }}
           AUDIT=${{ steps.audit.outputs.audit_exit_code }}
           echo "Drift check exit code:    $DRIFT"
+          echo "Drift severity:           $SEVERITY"
           echo "Contract tests exit code: $TESTS"
           echo "Audit check exit code:    $AUDIT"
+
           FAILED=0
-          if [ "$DRIFT" -eq 2 ]; then
-            echo "::error::API drift detected — the OpenAPI spec changed but docs/baseline were not updated"
+
+          # GREEN drift: pass (baseline already auto-updated above)
+          # YELLOW drift: fail — require PR review
+          if [ "$SEVERITY" = "yellow" ]; then
+            echo "::error::Potentially breaking API drift — PR review required before merge"
             FAILED=1
           fi
+
+          # RED drift: fail — breaking change, escalate
+          if [ "$SEVERITY" = "red" ]; then
+            echo "::error::BREAKING API drift — this change will break existing clients"
+            FAILED=1
+          fi
+
           if [ "$TESTS" -ne 0 ]; then
             echo "::error::Contract tests failed — some API calls don't match the current spec"
             FAILED=1
           fi
+
           if [ "$FAILED" -eq 1 ]; then
             echo ""
-            echo "To fix: run 'python -m drift_guard.guard baseline' to update the baseline,"
+            echo "To fix: review the drift summary, run 'python -m drift_guard.guard baseline',"
             echo "then commit the updated artifacts/openapi_baseline.json and docs/api_reference.md"
             exit 1
           fi