feat: add policy operations commands for Sentinel policy evaluation

[CloudbrokerAz]

Description

This PR adds two new commands to tfci for automating Sentinel policy evaluation and override operations in CI/CD pipelines.

Why this change?

Currently, tfci lacks commands for handling Sentinel policy evaluations, forcing users to manually check policy results in the TFC UI or build custom API integrations. This creates friction in automated deployment workflows, particularly when:

• CI/CD pipelines need to programmatically check if policies passed/failed
• Teams need to apply policy overrides with proper audit trails during approved change windows

This change adds native support for policy operations, enabling fully automated policy workflows while maintaining proper governance and audit trails.

Commands Added:

1. policy show - Retrieves and displays Sentinel policy evaluation results for a run

   • Automatically waits for policy evaluation to complete (with --no-wait option to disable)
   • Displays actual policy names (e.g., "require-all-resources-from-pmr.sentinel") instead of generic summaries
   • Supports both modern (task-stages) and legacy (policy-checks) TFC APIs
   • Pipeline-agnostic JSON output for consumption by any CI/CD system

2. policy override - Applies policy overrides with justification for audit compliance

   • Requires justification comment (added to run for audit trail)
   • Validates run is in correct state before applying override
   • Returns detailed override status for workflow automation

Testing plan

Unit Tests

All tests pass successfully:

go test ./internal/cloud/...
# PASS: 37.029s
# ✅ policy_evaluation_test.go - All 8 tests passing
# ✅ policy_override_test.go - All 6 tests passing

End-to-End Testing

Tested against real TFC organization (cloudbrokeraz/it-ops-api-automation):

1. Policy Show Command - Retrieve policy evaluation results:

tfci -organization cloudbrokeraz policy show \
  --run run-abc123def456\
  --json

Expected output:

• JSON with policy counts (total, passed, mandatory_failed, advisory_failed)
• List of failed policy names with enforcement levels
• requires_override boolean flag
• Full structured output for CI/CD consumption

2. Policy Override Command - Apply override with justification:

tfci -organization cloudbrokeraz policy override \
  --run run-abc123def456 \
  --justification "Emergency hotfix approved by CTO - INC-12345" \
  --json

Expected output:

• Confirmation of override application
• Initial and final run statuses
• Justification recorded in run comment for audit trail

3. GitHub Actions Integration - Production workflow testing:

• Successfully integrated in GitHub Actions workflows
• Parses JSON output and displays in CI/CD UI

Code Quality

go vet ./internal/...  # No issues
go build              # Compiles successfully

External links

• TFC Runs API - Policy Checks
• TFC Policy Set Outcomes API
• TFC Task Stages API
• TFC Runs API - Override Policy
• go-tfe SDK v1.95.0

Audit Trail Enhancement:

• All policy overrides require --justification parameter
• Justifications are added as comments to the TFC run (immutable audit log)
• Override actions are visible in TFC UI with timestamp and actor information
• Enables compliance teams to track all policy override decisions

[hashicorp-cla-app]

Thank you for your submission! We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. Read and sign the agreement

Learn more about why HashiCorp requires a CLA and what the CLA includes

_{Have you signed the CLA already but the status is still pending? Recheck it.}

[CloudbrokerAz]

Example of the Policy Show
https://github.com/hashi-demo-lab/it-ops-api-automation/blob/a55fbaabcc0e70c42242a4e725a1241b931c9ff6/.github/workflows/2-policy-check.yml#L47C7-L54C95
GitHub Action example
https://github.com/hashi-demo-lab/it-ops-api-automation/actions/runs/19987312680

Example of Policy Override
https://github.com/hashi-demo-lab/it-ops-api-automation/actions/runs/19987360991
GitHub Action example
https://github.com/hashi-demo-lab/it-ops-api-automation/blob/a55fbaabcc0e70c42242a4e725a1241b931c9ff6/.github/workflows/2-policy-override.yml#L29-L36