HYPERFLEET-1762 - feat: validate the PR title only in --pr mode

AGENTS.md

@@ -13,7 +13,7 @@ Go 1.26.0 · Cobra CLI · go-git · go-github · stretchr/testify · golangci-li
 | `make lint` | golangci-lint (pinned in tools/go.mod, config: `.golangci.yml`) |
 | `make test` | Unit tests with race detection + coverage profile |
 | `make test-coverage` | `make test` + opens HTML coverage report |
-| `make validate-commits` | Build + `hyperfleet-hooks commitlint --pr` (CI mode) |
+| `make validate-commits` | Build + `hyperfleet-hooks commitlint --pr --commits` (needs the Prow PR env) |
 | `make image` | Build container image (podman/docker auto-detected) |
 
 Pre-push order: `make lint` → `make test` → `make build`.
@@ -23,7 +23,8 @@ Pre-push order: `make lint` → `make test` → `make build`.
 ```bash
 hyperfleet-hooks commitlint <file>              # Validate single commit message from file
 echo "feat: ..." | hyperfleet-hooks commitlint  # Validate from stdin
-hyperfleet-hooks commitlint --pr                # CI mode: validate all PR commits + PR title
+hyperfleet-hooks commitlint --pr                # CI mode: validate the PR title (becomes the squashed commit)
+hyperfleet-hooks commitlint --pr --commits      # CI mode: also validate every commit in the PR range
 hyperfleet-hooks version                        # Print version info
 ```
 
@@ -36,6 +37,7 @@ hyperfleet-hooks version                        # Print version info
 | Pre-commit hook definitions | `.pre-commit-hooks.yaml` |
 | Validation logic | `pkg/commitlint/validator.go` |
 | GitHub API client | `pkg/github/client.go` |
+| Prow JOB_SPEC parsing | `pkg/prow/jobspec.go` |
 | CLI command wiring | `cmd/hyperfleet-hooks/commitlint/commitlint.go` |
 | Linter config | `.golangci.yml` |
 | Container image | `Dockerfile` |
@@ -47,7 +49,12 @@ Four pre-commit hooks defined in `.pre-commit-hooks.yaml`:
 - `hyperfleet-commitlint` — validates commit messages (Go binary, `language: golang`)
 - `hyperfleet-golangci-lint`, `hyperfleet-gofmt`, `hyperfleet-go-vet` — delegate to consuming repo's Make targets (`language: system`)
 
-CI mode (`--pr`) commit range detection priority:
+CI mode (`--pr`) validates the PR title only: PRs are squashed on merge, so the title is the commit that lands on `main`. Commits inside a PR need only the `<type>: <subject>` shape, enforced locally. PR title source priority:
+1. `JOB_SPEC` env var (`refs.pulls[0].title`, parsed by `pkg/prow/jobspec.go`)
+2. GitHub API via `REPO_OWNER` + `REPO_NAME` + `PULL_NUMBER`
+3. Neither: fail (never warn and pass)
+
+Per-commit validation (`--pr --commits`) commit range detection priority:
 1. `PULL_REFS` env var (Prow standard, most accurate)
 2. `PULL_BASE_SHA` + `PULL_PULL_SHA`
 3. `PULL_BASE_REF` + `HEAD` (local fallback)

Makefile

@@ -153,6 +153,6 @@ image-push: check-container-tool image ## Build and push container image
 # CI
 # ------------------------------------------------------------------------------
 
-validate-commits: build ## Validate commits in current branch (CI mode)
+validate-commits: build ## Validate PR title and commits in current branch (needs JOB_SPEC or REPO_OWNER/REPO_NAME/PULL_NUMBER)
 	@echo "Validating commits..."
-	@./bin/hyperfleet-hooks commitlint --pr
+	@./bin/hyperfleet-hooks commitlint --pr --commits

README.md

@@ -34,7 +34,7 @@ From this point on, every `git commit` in that repository will validate the comm
 
 ### For CI (Prow)
 
-In Prow, a pre-built container image (`quay.io/openshift-hyperfleet/hyperfleet-git-hooks`) is used to validate all commits and the PR title. See the [commitlint documentation](docs/commitlint.md) for Prow configuration details.
+In Prow, a pre-built container image (`quay.io/openshift-hyperfleet/hyperfleet-git-hooks`) runs `hyperfleet-hooks commitlint --pr`, which validates the PR title. PRs are squashed on merge, so the PR title is the commit message that lands on `main` and it must carry the JIRA ticket. Commits inside a PR are not checked by CI: they only need the `<type>: <subject>` shape, which the local `commit-msg` hook enforces, so push review fixes as new commits rather than amending. See the [commitlint documentation](docs/commitlint.md) for Prow configuration details.
 
 ## Available Hooks
 
@@ -47,7 +47,7 @@ In Prow, a pre-built container image (`quay.io/openshift-hyperfleet/hyperfleet-g
 
 ### Commitlint
 
-Validates commit messages and PR titles against the [HyperFleet Commit Standard](https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/standards/commit-standard.md).
+Validates commit messages locally and PR titles in CI against the [HyperFleet Commit Standard](https://github.com/openshift-hyperfleet/architecture/blob/main/hyperfleet/standards/commit-standard.md). In CI the PR title becomes the squashed commit, so that is what `--pr` validates; add `--commits` to also check every commit in the PR.
 
 **[→ Full Documentation](docs/commitlint.md)**