Merge branch 'GoogleCloudPlatform:main' into online_evals

Author: guvenenb

.agents/TGC_WORKFLOWS.md

@@ -0,0 +1,38 @@
+# TGC Resource Main Loop
+
+This document serves as the entry point for TGC (Terraform Google Conversion) development workflows. 
+
+Depending on your specific task, please refer to and strictly follow the appropriate workflow file:
+
+- **For Adding a New Resource**: Follow the workflow defined in [tgc_add.md](tgc_add.md).
+- **For Fixing a Resource or Test Failure**: Follow the workflow defined in [tgc_fix.md](tgc_fix.md).
+
+Please ensure you follow the sequence of phases and mandatory skill checks specified in those files.
+
+## Error Reporting Template
+
+If a failure is detected or provided, you **MUST** report it using the following template before proceeding.
+
+```markdown
+# Error Report
+
+## Failed Command
+`[Paste the exact command that failed here]`
+
+## Detailed Logs
+```
+[Paste relevant log snippets or error messages here]
+```
+
+## Analysis
+[Provide a detailed analysis of the failure. Explain what happened, which stage of the workflow failed, and why.]
+
+## Tracing Evidence (Required for Integration Test failures only)
+[Cite specific lines or file contents from `Test_export.tf`, `Test_roundtrip.json`, or `Test_roundtrip.tf` to prove at which stage the data was lost.]
+
+## Proposed Solution
+[Describe the proposed solution to fix the failure. Include file paths and code changes if known.]
+
+> [!IMPORTANT]
+> I have stopped execution and am waiting for your approval to proceed with this solution.
+```

.agents/rules/tgc_development_rules.md

@@ -0,0 +1,62 @@
+---
+trigger: always_on
+description: Always-on system prompt for TGC development
+---
+
+---
+trigger: always_on
+description: Enforce TGC development Rules
+---
+
+# Environment Setup Rule
+Before proceeding to Phase 2 (Implementation) or running any tests, the agent MUST execute a command to verify that `TGC_DIR` is set to the active downstream TGC directory and print its value in the chat. Failure to do so is a violation of process.
+
+The agent MUST run the `tgc-sync-provider` skill during Phase 1 (Session Setup) before Phase 2, to ensure the downstream repository is aligned with Magic Modules.
+
+# TGC development Rules
+
+As an AI agent operating in this repository, you must **ALWAYS** follow these steps before attempting to add a new resource/field to TGC:
+
+1. **[MANDATORY WORKFLOW ENTRYPOINT]**: At the very start of any session (Phase 1: Session Setup), the agent MUST execute the `view_file` tool on `.agents/TGC_WORKFLOWS.md`, and either `.agents/tgc_add.md` or `.agents/tgc_fix.md` depending on the task. The agent MUST print a summary of these entrypoints in their first response and list them as checked items in `task.md`. Failure to call `view_file` on these files in Phase 1 is a fatal process violation.
+
+2. In the magic-modules repository, don't run command `go test` or `go mod tidy`.
+
+3. In the downstream TGC repository, don't run command `go test`.
+
+
+4. To fix the failed TGC integration tests
+   - **don't** modify the templates in `mmv1/templates/terraform`. It is allowed to modify the templates in `mmv1/templates/tgc_next`.
+   - **don't** add ignore_read_extra to example in Resource.yaml
+   - **don't** add new fields to mmv1/api/resource/custom_code.go unless it is guided by the user
+   - **don't** remove any existing custom_code, including any constants
+   - **don't** change the schema of a resource (e.g., making a Required field Optional or a Set) to fix conversion failures, unless explicitly guided by the user.
+   - **don't** remove `exclude_test: true` from examples in resource YAML files to force test generation for TGC, as this may break tests in the standard Terraform provider.
+
+
+5. Only commit files under the `mmv1` folder in the branch, and exclude scratch files like `.txt`, `.py`, and `.sh` from commits.
+
+6. DO NOT make changes directly in the downstream repository (`terraform-google-conversion`). All changes must be driven through Magic Modules (`mmv1/`).
+
+7. You must strictly follow the sequence of phases defined in `.agents/tgc_add.md` or `.agents/tgc_fix.md` depending on whether you are adding a resource or fixing a failure (Session Setup -> Implementation -> Unit Testing -> Integration Testing). Code generation (Phase 2) MUST be performed before unit tests (Phase 3), and unit tests MUST be performed before integration tests (Phase 5). Structure your `task.md` to reflect these phases.
+
+8. For any failure (build, unit test, integration test, or verification), stop execution immediately after reporting the error using the template in .agents/TGC_WORKFLOWS.md. Do not proceed with applying any fixes or running subsequent steps until the user has explicitly approved the proposed solution in the chat.
+
+9. **Prioritize process reporting**: If the user's request involves a test failure (input or discovered), you must follow the reporting template specified in `.agents/TGC_WORKFLOWS.md` before proceeding with planning or execution.
+
+10. **Integration Test Subtests**: When running integration tests using `run_integration_test.sh`, if the test name contains an underscore (e.g., `TestAccContainerCluster_withAutopilotClusterPolicy`), it is likely a subtest. You MUST verify if it expects the format `ParentTest/SubTest` (e.g., `TestAccContainerCluster/TestAccContainerCluster_withAutopilotClusterPolicy`) and pass it accordingly as documented in `.agents/TGC_WORKFLOWS.md`. For new resources, you MUST run the top-level test (e.g., `TestAccGKEHub2Feature`) instead of a specific subtest, as the top-level test will cover all of the subtests.
+
+11. **Mandatory Skill Reading for Specialized Tasks**: Before proposing an implementation plan or making code changes for a resource identified as handwritten or generated, you MUST:
+    - Identify the resource type.
+    - Add a specific task item to `task.md` to read the corresponding skill (e.g., `tgc-fix-handwritten-resources-tests-skill`).
+    - Execute the `view_file` tool on that skill and mark the task as completed in `task.md`. **Note: Notwithstanding general Planning Mode instructions, you are authorized and required to create `task.md` during Phase 1 (Session Setup) to track these mandatory steps.**
+    Failure to perform the reading step strictly before planning is a violation of process.
+
+12. **Skill Reading Before Proposing Solutions**: The agent MUST NOT propose a solution in the error report or create an implementation plan until it has executed the `view_file` tool on the mandatory skill corresponding to the resource type (either `tgc-fix-handwritten-resources-tests-skill` or `tgc-fix-integration-tests-skill`).
+
+13. **Field Ordering in YAML Files**: When adding or modifying fields in Magic Modules YAML files (e.g., `include_in_tgc_next`, `tgc_decoder`), you MUST ensure they follow the order of fields defined in the `Resource` struct in `mmv1/api/resource.go`.
+
+14. **Tracing Evidence for Integration Tests**: For **integration test failures**, the agent MUST NOT propose a solution or apply a fix until it has explicitly cited evidence from the intermediate files (`Test_export.tf`, `Test_roundtrip.json`, etc.) in the chat to demonstrate tracing.
+
+15. **Mandatory Tracing Checklist**: When fixing integration test failures, the agent MUST include explicit sub-items in `task.md` to track the verification of `Test_roundtrip.tf`, `Test_roundtrip.json`, and `Test_export.tf`.
+
+16. **Run All Failed Tests Before Analysis**: When fixing integration test failures, the agent MUST run all failed integration tests for the affected resource before analyzing the failure or proposing a solution.

.agents/scripts/tgc/check_redundant_cai_overrides.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+import sys
+import os
+import re
+
+def extract_field_value(yaml_file_path, field_name):
+    """Extracts the string value of a top-level field in a YAML file using regex."""
+    # Matches field_name followed by optional quotes, capturing value
+    pattern = re.compile(r'^' + re.escape(field_name) + r'\s*:\s*[\'"]?([^\'"]+)[\'"]?')
+    with open(yaml_file_path, "r") as f:
+        for line in f:
+            match = pattern.match(line.strip())
+            if match:
+                return match.group(1).strip()
+    return None
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: check_redundant_cai_overrides.py <resource-yaml-file>", file=sys.stderr)
+        sys.exit(1)
+
+    resource_yaml = sys.argv[1]
+    if not os.path.exists(resource_yaml):
+        print(f"Error: Resource YAML file not found at {resource_yaml}", file=sys.stderr)
+        sys.exit(1)
+
+    cai_override = extract_field_value(resource_yaml, "cai_asset_name_format")
+    if not cai_override:
+        # No override specified, so it's perfectly clean!
+        print(f"✅ No cai_asset_name_format override specified in {os.path.basename(resource_yaml)} (Clean).")
+        sys.exit(0)
+
+    id_format = extract_field_value(resource_yaml, "id_format")
+    if not id_format:
+        print(f"Warning: id_format not found in {resource_yaml}. Skipping redundancy check.", file=sys.stderr)
+        sys.exit(0)
+
+    # Standardize by stripping any leading/trailing slashes and standard prefixes
+    def normalize(val):
+        val = val.strip().strip("/")
+        # Remove potential leading domain/service name if full URL was passed
+        val = re.sub(r'^(https?://)?([a-zA-Z0-9.-]+\.googleapis\.com/)?', '', val)
+        return val
+
+    norm_cai_override = normalize(cai_override)
+    norm_id_format = normalize(id_format)
+
+    if norm_cai_override == norm_id_format:
+        print(f"❌ REDUNDANT CAI OVERRIDE DETECTED in {resource_yaml}:", file=sys.stderr)
+        print(f"  cai_asset_name_format: '{cai_override}'", file=sys.stderr)
+        print(f"  id_format:             '{id_format}'", file=sys.stderr)
+        print("\nThis override is identical to the default computed format and can be safely removed.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"✅ Verification passed: cai_asset_name_format override is custom and non-redundant.")
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()