fix(gcp): complete the Recommender permission setup contract #2124

Summary

Complete the GCP setup contract for recommendation access. The wizard's Compute roles do not supply Recommender permissions, and the setup guide currently provides only a caveat.

Current behaviour

cmd/configure_gcp.go:gcpStepGrantRole provisions Compute Viewer and a custom role containing only compute.commitments.create. The prior Compute Admin grant did not supply the missing recommendation permissions either, so this is a pre-existing gap, not a regression from #2122.

The pinned cloud-commitments-go/providers/gcp module calls the Recommender API from services/computeengine/client.go:394-400. docs/cli/cloud-setup.md:150 now states that additional permissions are required, but does not identify the exact supported recommendation resource and least-privilege grant.

Steps to verify the gap

Trace each supported GCP recommendation API caller and its project or billing-account scope against official permission documentation. In an explicitly authorized test project, verify the recommendation path for an identity having only the wizard-created grants. Record the result without making any commitment purchase.

Expected behaviour

The setup documentation identifies the exact least-privilege Recommender permissions and resource scope. Setup either provisions the supported permissions after a clear prompt or gives an actionable prerequisite before reporting configuration complete.

Proposed fix

• Update docs/cli/cloud-setup.md with the verified permission contract and separately identify project-scoped and billing-scoped grants.
• If wizard provisioning is appropriate, update cmd/configure_gcp.go:gcpStepGrantRole and its SDK fixtures; do not replace the narrow Compute grants with broad roles.
• Coordinate any incorrect or unsupported recommendation resource IDs with cloud-commitments-go; do not infer the correct role from the current ID alone.

References

• Parent: sec(cli): the GCP setup wizard grants roles/compute.admin at project scope #1946
• Fix and documented scope: fix(gcp): restrict setup wizard compute permissions #2122, merge 76d1d4e72f13731ba071c7932f8e7e233cb4f6c6
• https://docs.cloud.google.com/iam/docs/roles-permissions/recommender

Severity

Medium: a newly configured identity can lack access to the recommendation path. Existing external grants may satisfy it; live authorization has not been tested in this session.