Simplify state management: default terraform.tfstate per stage directory

Removed centralized .terraform-state/ directory, stage-N-slug.tfstate
convention, TFM-TF-003 transform, and STAN-TF-011 standard. Each stage
uses the default terraform.tfstate in its own directory. Cross-stage
references use relative paths (../stage-1-managed-identity/terraform.tfstate).

This eliminates the #1 recurring QA failure — the AI naturally generates
backend "local" {} which now just works.

Author: a11smiles

HISTORY.rst

@@ -8,10 +8,13 @@ Release History
 
 Generation quality improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* **TFM-TF-003** — structured transform that fixes backend state file
-  paths: replaces ``terraform.tfstate`` or empty ``backend "local" {}``
-  with the correct ``stage-N-slug.tfstate`` path derived from stage
-  context.  The #1 recurring QA failure across all builds.
+* **Simplified state management** — removed centralized
+  ``.terraform-state/`` directory and ``stage-N-slug.tfstate`` naming
+  convention.  Each stage uses the default ``terraform.tfstate`` in its
+  own directory.  Cross-stage references use simple relative paths
+  (``../stage-1-managed-identity/terraform.tfstate``).  Removed
+  TFM-TF-003, STAN-TF-011, and the CRITICAL STATE FILE NAMING section
+  from TERRAFORM_PROMPT.  Eliminates the #1 recurring QA failure.
 * **Stage context in transforms** — ``apply()`` now accepts ``stage``
   dict and ``stage_content`` (all files concatenated), enabling
   structured handlers to use stage metadata and cross-file reference
@@ -20,11 +23,10 @@ Generation quality improvements
   checks references across ALL stage files (via ``stage_content``),
   not just the file containing the declaration.  Prevents false removal
   of remote state blocks referenced in ``locals.tf`` or ``outputs.tf``.
-* **35 transform unit tests** — comprehensive tests for all 7 handlers:
+* **29 transform unit tests** — comprehensive tests for all 6 handlers:
   load, apply filtering, capacityMode replacement, unused remote state
   (single-file and cross-file), response_export_values injection,
-  resource group parent_id, PE removal, state path fix, and stage
-  context integration.
+  resource group parent_id, PE removal, and stage context integration.
 * **``response_export_values`` prompt strengthening** — TERRAFORM_PROMPT
   changed from "add when outputs reference it" to "add to EVERY
   azapi_resource, no exceptions."  Violations section with rejected

azext_prototype/agents/builtin/iac_shared_rules.py

@@ -75,10 +75,6 @@
   role must be applied _after_ the identity stage deploys.
 
 ## CRITICAL: deploy.sh STATE DIRECTORY
-deploy.sh **MUST** create the Terraform state directory before `terraform init`:
-```bash
-STATE_DIR="$(cd "$(dirname "$0")/../../.." && pwd)/.terraform-state"
-mkdir -p "${STATE_DIR}"
-```
-Without this, `terraform init` fails on first run in a clean environment.
+Each stage stores its state as `terraform.tfstate` in its own directory.
+Cross-stage references use relative paths (e.g., `../stage-1-managed-identity/terraform.tfstate`).
 """.strip()

azext_prototype/agents/builtin/terraform_agent.py

@@ -138,19 +138,14 @@ def get_system_messages(self):
     }
   }
 
-  backend "local" {
-    path = "../../../.terraform-state/stage-N-slug.tfstate"
-    # REPLACE stage-N-slug with the ACTUAL stage number and name.
-    # Example: stage-1-managed-identity.tfstate, stage-4-networking.tfstate
-    # NEVER use the default "terraform.tfstate" — downstream stages WILL break.
-  }
+  backend "local" {}
 }
 
 provider "azapi" {}
 ```
 Do NOT add `subscription_id` or `tenant_id` to the provider block. The az CLI context provides these.
-NEVER use `backend "local" {}` without an explicit `path` — it defaults to
-`terraform.tfstate` which breaks cross-stage references.
+Each stage uses the default `terraform.tfstate` in its own directory.
+Cross-stage references use relative paths: `../stage-1-managed-identity/terraform.tfstate`.
 
 ## CRITICAL: TAGS PLACEMENT
 Tags on `azapi_resource` MUST be a TOP-LEVEL attribute, NEVER inside `body`.
@@ -261,7 +256,7 @@ def get_system_messages(self):
 variable "stage1_state_path" {
   description = "Path to Stage 1 state file"
   type        = string
-  default     = "../../../.terraform-state/stage-1-managed-identity.tfstate"
+  default     = "../stage-1-managed-identity/terraform.tfstate"
 }
 data "terraform_remote_state" "stage1" {
   backend = "local"
@@ -271,25 +266,6 @@ def get_system_messages(self):
 parent_id = data.terraform_remote_state.stage1.outputs.resource_group_id
 ```
 
-## CRITICAL: STATE FILE NAMING CONVENTION
-ALL stages MUST set an explicit `path` in `backend "local"`. The path MUST
-follow this EXACT pattern — NO EXCEPTIONS:
-
-  path = "../../../.terraform-state/stage-{N}-{slug}.tfstate"
-
-Where {N} is the stage number and {slug} is the stage name in lowercase
-with hyphens. You MUST replace {N} and {slug} with the actual values.
-
-Examples:
-  Stage 1 "Managed Identity": path = "../../../.terraform-state/stage-1-managed-identity.tfstate"
-  Stage 4 "Networking":       path = "../../../.terraform-state/stage-4-networking.tfstate"
-  Stage 8 "Cosmos DB":        path = "../../../.terraform-state/stage-8-cosmos-db.tfstate"
-
-VIOLATIONS THAT WILL BE REJECTED:
-  backend "local" {}                              # WRONG — defaults to terraform.tfstate
-  path = "terraform.tfstate"                      # WRONG — breaks cross-stage references
-  path = "../stage-N-name/terraform.tfstate"      # WRONG — must use .terraform-state/ directory
-
 NEVER use variable references in backend config blocks.
 
 ## MANAGED IDENTITY + RBAC (MANDATORY)

azext_prototype/governance/standards/iac/terraform.yaml

@@ -81,8 +81,8 @@ principles:
   applies_to:
   - terraform-agent
   examples:
-  - 'POC: omit backend block entirely (local state by default)'
-  - 'POC multi-stage: backend "local" { path = "../.terraform-state/stage1.tfstate" }'
+  - 'POC: backend "local" {} — default terraform.tfstate in stage directory'
+  - 'Cross-stage ref: ../stage-1-managed-identity/terraform.tfstate'
   - 'Production: backend "azurerm" { resource_group_name = "terraform-state-rg"; storage_account_name = "tfstate12345"; container_name
     = "tfstate"; key = "stage1.tfstate" }'
   rationale: Proper state management prevents cross-stage conflicts and ensures reliable deployments.
@@ -121,14 +121,3 @@ principles:
   - resource "azapi_resource" "cosmosdb_role_assignment" { type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15";
     body = { properties = { principalId = azapi_resource.managed_identity.output.properties.principalId } } }
   rationale: Complete outputs enable downstream stages to reference resources without hardcoding.
-- id: STAN-TF-011
-  description: 'State File Naming: The backend local block must specify an explicit path using the pattern stage-N-slug.tfstate
-    (e.g., stage-1-managed-identity.tfstate). Never use the default terraform.tfstate. Downstream stages reference upstream
-    state via terraform_remote_state with these paths — a mismatch silently reads empty state.'
-  applies_to:
-  - terraform-agent
-  examples:
-  - 'backend "local" { path = "stage-1-managed-identity.tfstate" }'
-  - 'backend "local" { path = "stage-4-networking.tfstate" }'
-  - 'WRONG: backend "local" {} — defaults to terraform.tfstate'
-  rationale: Consistent state file naming enables cross-stage references via terraform_remote_state without path guessing.

azext_prototype/governance/transforms/__init__.py

@@ -449,51 +449,11 @@ def _inject(match: re.Match) -> str:  # type: ignore[type-arg]
     return new_content
 
 
-def _fix_state_path(content: str, stage: dict | None = None) -> str:
-    """Fix backend state file path to follow stage-N-slug.tfstate convention.
-
-    Replaces:
-    - ``backend "local" {}`` (empty, defaults to terraform.tfstate)
-    - ``path = "terraform.tfstate"``
-    - ``path = "...terraform.tfstate"`` (wrong path)
-
-    With the correct ``path = "../../../.terraform-state/stage-N-slug.tfstate"``.
-    Requires ``stage`` context to derive the correct path.
-    """
-    if not stage:
-        return content
-
-    stage_num = stage.get("stage")
-    stage_name = stage.get("name", "")
-    if not stage_num or not stage_name:
-        return content
-
-    slug = stage_name.lower().replace(" ", "-")
-    correct_path = f"../../../.terraform-state/stage-{stage_num}-{slug}.tfstate"
-
-    result = content
-
-    # Fix empty backend "local" {} — inject path
-    empty_backend = re.compile(r'backend\s+"local"\s*\{\s*\}', re.DOTALL)
-    if empty_backend.search(result):
-        result = empty_backend.sub(f'backend "local" {{\n    path = "{correct_path}"\n  }}', result)
-        logger.debug("Fixed empty backend local with path %s", correct_path)
-
-    # Fix wrong path values
-    wrong_path = re.compile(r'path\s*=\s*"[^"]*terraform\.tfstate"')
-    if wrong_path.search(result):
-        result = wrong_path.sub(f'path = "{correct_path}"', result)
-        logger.debug("Fixed terraform.tfstate path to %s", correct_path)
-
-    return result
-
-
 _STRUCTURED_HANDLERS: dict[str, Callable] = {
     "remove_unused_remote_state": _remove_unused_remote_state,
     "remove_private_endpoint_resources": _remove_private_endpoint_resources,
     "add_response_export_values": _add_response_export_values,
     "add_resource_group_parent_id": _add_resource_group_parent_id,
-    "fix_state_path": _fix_state_path,
 }
 
 

azext_prototype/governance/transforms/iac/terraform-state-path.transform.yaml

@@ -5,7 +5,6 @@
 from azext_prototype.governance.transforms import (
     _add_resource_group_parent_id,
     _add_response_export_values,
-    _fix_state_path,
     _remove_private_endpoint_resources,
     _remove_unused_remote_state,
     apply,
@@ -50,7 +49,7 @@ def test_structured_transforms_have_handler(self):
 
     def test_known_transforms_exist(self):
         ids = {t.id for t in load()}
-        expected = {"TFM-LA-001", "TFM-CDB-001", "TFM-TF-001", "TFM-TF-002", "TFM-TF-003", "TFM-RG-001", "TFM-NET-001"}
+        expected = {"TFM-LA-001", "TFM-CDB-001", "TFM-TF-001", "TFM-TF-002", "TFM-RG-001", "TFM-NET-001"}
         for eid in expected:
             assert eid in ids, f"Expected transform {eid} not found"
 
@@ -355,75 +354,12 @@ def test_empty_content_returns_unchanged(self):
         assert result == ""
 
 
-# ------------------------------------------------------------------
-# _fix_state_path (TFM-TF-003)
-# ------------------------------------------------------------------
-
-
-class TestFixStatePath:
-    def test_fixes_empty_backend(self):
-        content = """terraform {
-  required_version = ">= 1.9.0"
-  backend "local" {}
-}
-"""
-        result = _fix_state_path(content, stage={"stage": 4, "name": "Networking"})
-        assert "stage-4-networking.tfstate" in result
-        assert "terraform.tfstate" not in result
-
-    def test_fixes_wrong_path(self):
-        content = """terraform {
-  backend "local" {
-    path = "terraform.tfstate"
-  }
-}
-"""
-        result = _fix_state_path(content, stage={"stage": 7, "name": "Azure SQL"})
-        assert "stage-7-azure-sql.tfstate" in result
-
-    def test_preserves_correct_path(self):
-        content = """terraform {
-  backend "local" {
-    path = "../../../.terraform-state/stage-4-networking.tfstate"
-  }
-}
-"""
-        result = _fix_state_path(content, stage={"stage": 4, "name": "Networking"})
-        assert result == content
-
-    def test_no_stage_returns_unchanged(self):
-        content = 'backend "local" {}'
-        result = _fix_state_path(content, stage=None)
-        assert result == content
-
-    def test_slug_generation(self):
-        content = 'backend "local" {}'
-        result = _fix_state_path(content, stage={"stage": 12, "name": "Container Apps Environment"})
-        assert "stage-12-container-apps-environment.tfstate" in result
-
-
 # ------------------------------------------------------------------
 # apply() — integration with stage context
 # ------------------------------------------------------------------
 
 
 class TestApplyWithStageContext:
-    def test_state_path_fix_uses_stage(self):
-        content = """terraform {
-  backend "local" {
-    path = "terraform.tfstate"
-  }
-}
-"""
-        result, ids = apply(
-            content,
-            services=[],
-            iac_tool="terraform",
-            stage={"stage": 5, "name": "Container Registry"},
-        )
-        assert "TFM-TF-003" in ids
-        assert "stage-5-container-registry.tfstate" in result
-
     def test_cross_file_remote_state_preserved(self):
         main_tf = """data "terraform_remote_state" "stage1" {
   backend = "local"