HYPERFLEET-1024 - fix: address code review findings

- Guard empty version extraction in CI and release workflows
- Add semver-aware version comparison to reject downgrades
- Use env vars for step outputs in release workflow (script injection)
- Pin spectral-cli version in CI
- Fix CHANGELOG: correct Node.js runtime reference, RFC 9457
- Add language specifier to fenced code block in README
- Add linting docs to CONTRIBUTING.md and CLAUDE.md
- Add pipeline overview diagram for sprint presentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mliptak0

.github/workflows/ci.yml

@@ -51,13 +51,21 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           CURRENT=$(grep -oP '(?<=version: ")[^"]+' main.tsp)
+          if [ -z "$CURRENT" ]; then
+            echo "::error::Failed to extract version from main.tsp — check the @info decorator format" >&2
+            exit 1
+          fi
           LATEST=$(gh release list --limit 1 --json tagName --jq '.[0].tagName' 2>/dev/null | sed 's/^v//' || echo "")
           if [ -z "$LATEST" ]; then
             echo "No previous releases found — version check skipped"
             exit 0
           fi
+          HIGHEST=$(printf '%s\n%s\n' "$CURRENT" "$LATEST" | sort -V | tail -1)
           if [ "$CURRENT" = "$LATEST" ]; then
-            echo "Version '$CURRENT' matches latest release tag 'v$LATEST' — bump the version in main.tsp before merging."
+            echo "::error::Version '$CURRENT' matches latest release tag 'v$LATEST' — bump the version in main.tsp before merging."
+            exit 1
+          elif [ "$HIGHEST" != "$CURRENT" ]; then
+            echo "::error::Version '$CURRENT' is lower than latest release 'v$LATEST' — version in main.tsp must be strictly greater."
             exit 1
           fi
           echo "Version bump OK: $LATEST → $CURRENT"

.github/workflows/release.yml

@@ -29,6 +29,10 @@ jobs:
         id: version
         run: |
           VERSION=$(grep -oP '(?<=version: ")[^"]+' main.tsp)
+          if [ -z "$VERSION" ]; then
+            echo "::error::Failed to extract version from main.tsp — check the @info decorator format" >&2
+            exit 1
+          fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
 

CHANGELOG.md

@@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Release workflow now triggers automatically on push to main instead of requiring a manual tag push; auto-creates annotated tag from version in `main.tsp` and attaches all four schema artifacts (`core-openapi.yaml`, `core-swagger.yaml`, `gcp-openapi.yaml`, `gcp-swagger.yaml`)
-- Bumped `actions/checkout` and `actions/setup-node` to v6 (Node.js 24 runtime)
+- Bumped `actions/checkout` and `actions/setup-node` to v6
 
 ### Fixed
 

CLAUDE.md

@@ -199,6 +199,7 @@ Before submitting changes:
 - [ ] Core Swagger builds: `./build-schema.sh core --swagger`
 - [ ] Schema files generated: `ls schemas/*/openapi.yaml`
 - [ ] No TypeSpec compilation errors (check output)
+- [ ] Schemas pass linting: `spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml`
 - [ ] Changes committed including schema updates
 - [ ] PR description references related issue
 

CONTRIBUTING.md

@@ -79,6 +79,22 @@ npm run build:gcp:swagger
 npm run build:all
 ```
 
+### Linting Schemas
+
+CI automatically lints OpenAPI schemas using a pinned version of [Spectral](https://github.com/stoplightio/spectral) installed locally in the workflow. For local linting during development, install Spectral globally:
+
+```bash
+npm install -g @stoplight/spectral-cli
+```
+
+Then lint the generated schemas:
+
+```bash
+spectral lint schemas/core/openapi.yaml schemas/gcp/openapi.yaml
+```
+
+The `.spectral.yaml` config at the repo root applies the `spectral:oas` ruleset.
+
 ### Validating Output
 
 After building, verify the generated schemas:

README.md

@@ -362,7 +362,7 @@ go get github.com/openshift-hyperfleet/hyperfleet-api-spec@v1.0.12
 
 To test locally against an unreleased branch, use a `replace` directive in your `go.mod`:
 
-```
+```go
 replace github.com/openshift-hyperfleet/hyperfleet-api-spec => /path/to/local/hyperfleet-api-spec
 ```
 

docs/pipeline-overview.md

@@ -0,0 +1,79 @@
+# HYPERFLEET-1024 — Automated OpenAPI Pipeline
+
+## Before: Manual Process
+
+```mermaid
+graph LR
+    Dev[Developer] -->|1. Edit TypeSpec| TSP[main.tsp]
+    TSP -->|2. Run build manually| Schemas[schemas/]
+    Schemas -->|3. Create tag manually| Tag[git tag vX.Y.Z]
+    Tag -->|4. Push tag| Remote[GitHub]
+    Remote -->|5. Upload assets manually| Release[GitHub Release]
+    Release -->|6. Copy files manually| Consumer[hyperfleet-api]
+
+    style Dev fill:#f9f,stroke:#333
+    style Release fill:#fbb,stroke:#900
+    style Consumer fill:#fbb,stroke:#900
+```
+
+**Pain points:** no version enforcement, no linting, manual release steps, consumers vendor stale copies.
+
+---
+
+## After: Fully Automated
+
+```mermaid
+graph LR
+    Dev[Developer] -->|1. Edit TypeSpec + bump version| PR[Pull Request]
+
+    subgraph CI ["CI (on every PR)"]
+        Build[Rebuild schemas]
+        Lint[Spectral lint]
+        Version[Version bump check]
+        Consistency[Schema consistency]
+    end
+
+    PR --> CI
+    CI -->|All green| Merge[Merge to main]
+
+    subgraph Release ["Release (on push to main)"]
+        Extract[Extract version from main.tsp]
+        TagCreate[Create git tag]
+        Publish[Publish GitHub Release + 4 artifacts]
+    end
+
+    Merge --> Release
+
+    Release -->|Go module import| Consumer[hyperfleet-api]
+
+    style Dev fill:#f9f,stroke:#333
+    style CI fill:#e6f3ff,stroke:#369
+    style Release fill:#e6ffe6,stroke:#393
+    style Consumer fill:#e6ffe6,stroke:#393
+```
+
+---
+
+## Key Benefits
+
+```mermaid
+graph TB
+    A["Version discipline enforced"] --- B["Schemas always match TypeSpec sources"]
+    B --- C["OpenAPI linting on every PR"]
+    C --- D["Zero-touch releases on merge"]
+    D --- E["Go module: single source of truth"]
+
+    style A fill:#dcedc8,stroke:#558b2f
+    style B fill:#dcedc8,stroke:#558b2f
+    style C fill:#dcedc8,stroke:#558b2f
+    style D fill:#dcedc8,stroke:#558b2f
+    style E fill:#dcedc8,stroke:#558b2f
+```
+
+| Before | After |
+|--------|-------|
+| Manual `git tag` + `gh release create` | Automatic on merge to main |
+| No linting gate | Spectral OAS lint on every PR |
+| Version bumps easily forgotten | CI blocks merge if version unchanged |
+| Consumers copy `openapi.yaml` by hand | `go get` pulls versioned schemas |
+| Schema drift between source and committed files | CI rebuilds and diffs against committed schemas |