fix: upgrade workflows, example modules, and test harnesses

.agent/agent-memory/README.md

@@ -0,0 +1,5 @@
+# AI Agent Memory
+
+This directory contains persistent context and learnings to retain across AI sessions.
+
+Agents can read from and write to this directory to remember past decisions, project-specific quirks, and user preferences, improving future interactions.

.agent/agents/README.md

@@ -0,0 +1,5 @@
+# Specialized AI Agents
+
+This directory contains specialized agent definitions and prompts. 
+
+These files can be used to set the context, persona, and specific capabilities for different AI agents operating within the repository.

.agent/output-styles/README.md

@@ -0,0 +1,5 @@
+# AI Output Styles
+
+This directory contains guidelines on how AI agents should format their responses.
+
+Rules here ensure that code suggestions, pull request reviews, and conversational assistance maintain a consistent and readable structure.

.agent/output-styles/claude-strict.md

@@ -0,0 +1,15 @@
+# Claude Strict Output Style
+
+As an agentic programming assistant, your output must be strictly utilitarian:
+
+## 1. No Conversational Filler
+- Skip all greetings, pleasantries, and conversational transitions.
+- Output only the requested code, diffs, or execution results.
+
+## 2. Format Requirements
+- Provide file modifications as standard unified diffs or complete code blocks.
+- Use absolute file paths for any file references.
+
+## 3. Explanations
+- Provide explanations ONLY if explicitly requested by the user.
+- If an error occurs, output the error message in a bold blockquote at the very top.

.agent/output-styles/gemini-conversational.md

@@ -0,0 +1,15 @@
+# Gemini Conversational Style
+
+As a coding partner, your output should be collaborative, educational, and conversational:
+
+## 1. Conversational Tone
+- Be polite, conversational, and act as an active pairing partner.
+- Use natural transitions and acknowledge the user's goals before diving into code.
+
+## 2. Skepticism & Teaching
+- If the user asks for something that violates Terraform or Go best practices, politely push back and explain why.
+- Suggest better alternatives, workflows, or commands that might suit their goals better.
+
+## 3. Clarity
+- When providing code or diffs, clearly explain the "why" behind the implementation.
+- Break down complex logic into easy-to-understand bullet points.

.agent/rules/README.md

@@ -0,0 +1,5 @@
+# AI Agent Rules
+
+This directory contains strict coding standards, anti-patterns, and requirements based on file types. 
+
+AI agents MUST consult the corresponding instruction file in this directory (e.g., `go.instructions.md`, `terraform.instructions.md`) whenever asked to generate, edit, or review code.

.agent/rules/github-copilot-review.instructions.md

@@ -0,0 +1,20 @@
+# GitHub Copilot Review Instructions
+
+When performing a code review or suggesting changes, adhere to the following guidelines to avoid "bikeshedding" and ensure feedback remains high-impact:
+
+## Focus on Critical and Highly Important Issues
+- **Security:** Highlight potential vulnerabilities, exposed secrets, or unsafe data handling.
+- **Bugs & Logic Errors:** Point out broken logic, unhandled edge cases, nil pointer dereferences, or potential race conditions.
+- **Performance:** Identify significant bottlenecks, severe memory leaks, or highly inefficient resource usage.
+- **Architecture:** Flag major architectural flaws or severe violations of core design principles that will drastically harm maintainability.
+
+## Avoid Bikeshedding (Trivial Suggestions)
+- Do **not** suggest changes that minimally affect the functionality of the code.
+- Ignore subjective styling, variable naming (unless dangerously misleading), and minor formatting adjustments.
+- Do not recommend alternative language syntax or minor refactors if the current implementation is functional and readable.
+- If a suggestion does not prevent a bug, fix a vulnerability, or drastically improve performance, omit it.
+
+## Review Format
+- Provide actionable, concrete feedback for the critical issues identified.
+- If the pull request has no critical or highly important issues, explicitly state that the code looks good and approve the review. 
+- Resist the urge to leave comments just for the sake of leaving comments.

.github/instructions/workflows.instructions.md → .agent/rules/workflows.instructions.md

@@ -7,8 +7,8 @@ applyTo: ".github/workflows/**/*.{yml,yaml}"
 As a strict DevSecOps CI/CD reviewer, enforce these standards on all workflow changes. Flag violations with a concise explanation and provide the refactored YAML.
 
 ## 1. Security (Critical)
-* **Least Privilege:** All workflows and jobs must define explicit `permissions:`. Default to `read-all` or `permissions: {}` at the top level. Set scopes to `none` as needed.
-* **Pin Actions by SHA:** Pin all actions (including `actions/*`, `github/*`, `rancher/*`) to a full 40-character commit SHA, not a tag. The `uses:` line MUST include the version and a repository link in a comment (e.g., `# v6.0.2 https://github.com/actions/checkout`). Exception: `rancher-eio/read-vault-secrets`.
+* **Least Privilege:** All jobs must define explicit `permissions:`. All workflows should have `permissions: {}` at the top level. Set scopes to `none` as needed. Permissions should implement least privilege necessary access.
+* **Pin Actions by SHA:** Pin all actions (including `actions/*`, `github/*`, `rancher/*`) to a full 40-character commit SHA, not a tag. The `uses:` line MUST include the version (e.g., `# v6.0.2`). On the line before the `uses:` there should be a comment with a link to the releases page for the action (e.g. `# https://github.com/actions/github-script/releases`).
 * **Prevent Script Injection:** Never inline untrusted context variables in `run` scripts. Use environment variables (e.g., `env: VAR: ${{...}}`).
 * **No `pull_request_target`:** This trigger is banned.
 

.agent/skills/README.md

@@ -0,0 +1,5 @@
+# AI Agent Skills
+
+This directory contains reusable tools or scripts that AI agents can recommend or utilize to execute tasks in this repository.
+
+Examples include scripts for running acceptance tests (`run-acc-test.sh`), linting code, or automating repetitive tasks.

.agent/skills/run-acc-test.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# Skill: run-acc-test.sh
+# Description: Safely runs a specific Terraform provider acceptance test within the Nix environment.
+#              It explicitly keeps necessary AWS and Terraform environment variables so tests don't fail.
+# Usage: ./run-acc-test.sh <TestName>
+
+set -euo pipefail
+
+if [ -z "${1:-}" ]; then
+  echo "Error: Must provide a test name."
+  echo "Usage: $0 <TestName>"
+  exit 1
+fi
+
+TEST_NAME="$1"
+
+echo "Executing acceptance test: ${TEST_NAME} inside Nix environment..."
+
+nix develop --ignore-environment \
+  --extra-experimental-features nix-command \
+  --extra-experimental-features flakes \
+  --keep HOME --keep SSH_AUTH_SOCK --keep GPG_SIGNING_KEY --keep NIX_SSL_CERT_FILE --keep NIX_ENV_LOADED --keep TERM \
+  --keep AWS_ROLE --keep AWS_REGION --keep AWS_DEFAULT_REGION \
+  --keep AWS_ACCESS_KEY_ID --keep AWS_SECRET_ACCESS_KEY --keep AWS_SESSION_TOKEN \
+  --keep TF_VAR_aws_access_key_id --keep TF_VAR_aws_secret_access_key --keep TF_VAR_aws_session_token --keep TF_VAR_aws_region \
+  --command bash -c "./run_tests.sh -t ${TEST_NAME}"

.agent/skills/run-in-nix.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# Skill: run-in-nix.sh
+# Description: Executes a given command inside the standardized Nix development environment.
+# Usage: ./run-in-nix.sh "<command>"
+
+set -euo pipefail
+
+if [ $# -eq 0 ]; then
+  echo "Error: Command required."
+  echo "Usage: $0 \"<command>\""
+  exit 1
+fi
+
+COMMAND="$1"
+
+echo "Running command in Nix environment: ${COMMAND}"
+
+nix develop --ignore-environment \
+  --extra-experimental-features nix-command \
+  --extra-experimental-features flakes \
+  --keep HOME --keep SSH_AUTH_SOCK --keep GPG_SIGNING_KEY --keep NIX_SSL_CERT_FILE --keep NIX_ENV_LOADED --keep TERM \
+  --command bash -c "${COMMAND}"

.agent/workflows/README.md

@@ -0,0 +1,5 @@
+# AI Agent Workflows
+
+This directory contains defined processes for executing multi-step tasks.
+
+These workflows provide step-by-step procedures for AI agents to follow when tackling complex tasks such as releasing the provider, running full test suites, or scaffolding new Terraform resources.

.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# GitHub Copilot Instructions
+
+Before analyzing this repository, providing code suggestions, or reviewing pull requests, you MUST read the authoritative root prompt for all agents located in `AGENTS.md` at the root of this repository.
+
+It contains essential coding standards, the `.agent` directory structure you need to use, and strict rules specific to your role in this project.

.github/pull_request_template.md

@@ -1,17 +1,17 @@
 <!--- If there is no user issue related to this then you should remove the next line --->
-Addresses #
-
-<!--- Add labels (eg. release/v14) for each release branch to target --->
+- Addresses #
+<!--- Add labels (eg. release/v15) for each release branch to target --->
 <!--- Please don't manually add "internal" labels, those are for automation only --->
 
 ## Description
-
 <!--- Describe your change and how it addresses the issue linked above or a problem with the product. --->
 
-## Testing
 
+## Testing
 <!--- Please describe how you verified this change or why testing isn't relevant. --->
 
+
 <!--- Does this change alter an interface that users of the provider will need to adjust to? --->
-<!--- Will there be any existing configurations broken by this change? If so, change the following line with an explanation. --->
+<!--- Will there be any existing configurations broken by this change? -->
+<!--- If so, change the following line with an explanation. --->
 Not a breaking change.

.github/workflows/backport-issues.yml

@@ -7,17 +7,29 @@ on:
 env :
   TERRAFORM_MAINTAINERS: ${{ vars.TERRAFORM_MAINTAINERS }} # eg. ["matttrach"]
 
+permissions: {}
+
 jobs:
   create-issue:
+    name: 'Create Backport Issue'
     runs-on: ubuntu-latest
-    if: ${{ startsWith(github.event.label.name, 'release/v') }}
+    if: startsWith(github.event.label.name, 'release/v')
+    timeout-minutes: 10
+    permissions:
+      issues: write
+      contents: read
     steps:
       - name: Find and Verify PR Number
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         id: extract_pr
         with:
           script: |
             const body = context.payload.issue.body;
+            if (!body) {
+              core.setFailed('Issue body is empty.');
+              return;
+            }
             const regex = /#(\d+)/g;
             const matches = body.matchAll(regex);
             const potentialNumbers = Array.from(matches, m => m[1]);
@@ -38,7 +50,8 @@ jobs:
             }
             core.setFailed('No valid PR found.');
       - name: Create GitHub Issue
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env :
           TERRAFORM_MAINTAINERS: ${{env.TERRAFORM_MAINTAINERS}}
           PR: ${{ steps.extract_pr.outputs.result }}
@@ -55,6 +68,11 @@ jobs:
             });
             const scriptContent = Buffer.from(response.data.content, "base64").toString();
 
-            // The script will be executed in an async context
-            const script = eval(scriptContent);
+            // Write the script to a temporary file and require it to avoid eval()
+            const fs = require('fs');
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+            const tempPath = path.join(process.env.RUNNER_TEMP, 'backport-issues.mjs');
+            fs.writeFileSync(tempPath, scriptContent, 'utf8');
+            const { default: script } = await import(pathToFileURL(tempPath).href);
             await script({github, context, core, process});

.github/workflows/backport-merge-label.yml

@@ -6,21 +6,27 @@ on:
     branches: 
       - 'release/*'
 
+permissions: {}
+
 jobs:
   label:
-    if: ${{ github.event.pull_request.merged == true }}
+    name: 'Label Related Issue'
+    if: github.event.pull_request.merged == true
     permissions:
       contents: read
       issues: write
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - name: 'Checkout Repository'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 https://github.com/actions/checkout
+        # https://github.com/actions/checkout/releases
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           ref: 'main'
       - name: 'Find and Label Related Issue'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const scriptPath = `${process.env.GITHUB_WORKSPACE}/.github/workflows/scripts/merge-label.js`;

.github/workflows/backport-pr-manual.yml

@@ -10,45 +10,39 @@ on:
 env :
   TERRAFORM_MAINTAINERS: ${{ vars.TERRAFORM_MAINTAINERS }} # eg. ["matttrach"]
 
+permissions: {}
+
 jobs:
   create-cherry-pick-prs:
+    name: 'Create Cherry-Pick PRs'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: write
       pull-requests: write
       issues: write
       actions: write
     steps:
+      - name: 'Checkout Repository'
+        # https://github.com/actions/checkout/releases
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          ref: 'main'
       - name: 'Wait for merge to settle'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           MERGE_COMMIT_SHA: ${{ inputs.merge_commit_sha }}
           TERRAFORM_MAINTAINERS: ${{ env.TERRAFORM_MAINTAINERS }}
         with:
           script: |
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            const mergeCommitSha = process.env.MERGE_COMMIT_SHA;
-            // wait 10 seconds to allow GitHub to index the commit and associated PRs
-            await new Promise(resolve => setTimeout(resolve, 10000));
-            // just in case the GitHub API is still having trouble, try to fetch associated PRs
-            let response;
-            try {
-                response = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-                owner,
-                repo,
-                commit_sha: mergeCommitSha
-              });
-            } catch (error) {
-              core.setFailed(`Failed to retrieve PRs associated with commit ${mergeCommitSha}: ${error.message}`);
-            }
-      - name: 'Checkout Repository'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 https://github.com/actions/checkout
-        with:
-          fetch-depth: 0
-          ref: 'main'
+            const scriptPath = `${process.env.GITHUB_WORKSPACE}/.github/workflows/scripts/wait-for-settle.js`;
+            const { default: script } = await import(scriptPath);
+            await script({github, context, core, process});
       - name: 'Find Issues and Create Cherry-Pick PRs'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           MERGE_COMMIT_SHA: ${{ inputs.merge_commit_sha }}
           TERRAFORM_MAINTAINERS: ${{ env.TERRAFORM_MAINTAINERS }}

.github/workflows/backport-prs.yml

@@ -8,47 +8,40 @@ on:
 env :
   TERRAFORM_MAINTAINERS: ${{ vars.TERRAFORM_MAINTAINERS }} # eg. '["matttrach"]'
 
+permissions: {}
+
 jobs:
   create-cherry-pick-prs:
+    name: 'Auto Cherry-Pick PRs'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: write
       pull-requests: write
       issues: write
       actions: write
 
     steps:
+      - name: 'Checkout Repository'
+        # https://github.com/actions/checkout/releases
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          ref: 'main'
       - name: 'Wait for merge to settle'
         id: wait_for_settle
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           TERRAFORM_MAINTAINERS: ${{ env.TERRAFORM_MAINTAINERS }}
         with:
           script: |
-            const owner = context.repo.owner;
-            const repo = context.repo.repo;
-            const mergeCommitSha = context.payload.head_commit.id;
-            // wait 10 seconds to allow GitHub to index the commit and associated PRs
-            await new Promise(resolve => setTimeout(resolve, 10000));
-            // just in case the GitHub API is still having trouble, try to fetch associated PRs
-            try {
-              const { data: associatedPrs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-                owner,
-                repo,
-                commit_sha: mergeCommitSha
-              });
-            } catch (error) {
-              core.setFailed(`Failed to retrieve PRs associated with commit ${mergeCommitSha}: ${error.message}`);
-            }
-            // set output for next steps
-            core.setOutput('merge_commit_sha', mergeCommitSha);
-      - name: 'Checkout Repository'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 https://github.com/actions/checkout
-        with:
-          fetch-depth: 0
-          ref: 'main'
+            const scriptPath = `${process.env.GITHUB_WORKSPACE}/.github/workflows/scripts/wait-for-settle.js`;
+            const { default: script } = await import(scriptPath);
+            await script({github, context, core, process});
       - name: 'Find Issues and Create Cherry-Pick PRs'
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 https://github.com/actions/github-script
+        # https://github.com/actions/github-script/releases
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           TERRAFORM_MAINTAINERS: ${{ env.TERRAFORM_MAINTAINERS }}
           MERGE_COMMIT_SHA: ${{ steps.wait_for_settle.outputs.merge_commit_sha }}