{"id":"4fe93168-64e5-4eff-b71f-8a593e523d1c","task":"Use the HCP Terraform API to programmatically trigger a speculative plan, poll for its completion, and parse the structured plan output to enforce a cost policy gate in CI","domain":"Terraform / HCP Terraform","steps":["Compress the Terraform configuration directory into a tar.gz file and upload it to HCP Terraform as a configuration version using the POST /configuration-versions API endpoint with the auto-queue-runs: false flag","Trigger a speculative plan run by creating a run via POST /runs with plan-only: true referencing the workspace ID and configuration version ID; capture the returned run ID","Poll GET /runs/:id at intervals inspecting the status field until it reaches planned, errored, or discarded; implement exponential backoff and a maximum poll timeout to avoid infinite loops","Retrieve the structured plan JSON by following the run's relationships.plan.links.json-output URL; parse the resource_changes array to extract planned cost-relevant attributes such as instance types or storage sizes","Apply a cost policy rule in the CI script: if the planned changes include instance types not on an approved list or exceed a resource count threshold, post a policy violation comment to the pull request and exit non-zero to block merge","On policy pass, optionally trigger the actual apply run using the same run ID if the workspace is configured for API-driven runs, or leave the speculative plan result as an advisory artifact in the PR"],"gotchas":["Speculative plans in HCP Terraform consume a plan credit and count toward the organization's concurrent run limit; triggering speculative plans on every commit in a busy repository can exhaust the concurrent plan slots and cause queuing","The plan JSON output is not available immediately when the run reaches planned status; there may be a short delay before the JSON artifact is generated, and the download URL may return 404 until it is ready","Configuration version uploads require the tar.gz to contain the Terraform files at the root of the archive, not nested in a subdirectory; an incorrectly packaged archive causes the plan to fail with a module not found error"],"contributor":"waymark-seed","created":"2026-06-13T05:09:50Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/4fe93168-64e5-4eff-b71f-8a593e523d1c"}