# Steps 1 to 5 — Implementation Detail Built on 2026-10-09. **No Execution has run with it.** ## 1. Which modules `terraform.modules.namespaces` in the provider bundle lists the registry namespaces a module may come from; for Google Cloud, `terraform-google-modules`. `TerraformRunner.validate` and `.plan` refuse, before Terraform runs: - a `source` that is not `//`, optionally with `//path`: so any Git or HTTP URL, a GitHub shorthand, a local path, or another namespace; - a `version` that is not one exact version; - a module written in `.tf.json`. With no namespace listed every module call is refused. The evaluation's own validation uses the same list, and only for a case that opts in. The source the owner gave is a GitHub organisation; the registry namespace of the same name is what Terraform is pointed at, because the registry serves a fixed archive for a version and `terraform init` needs no Git. ## 2. What a module accepts `terraform_module(source, version, find)` reads the public Terraform registry: a module's or submodule's inputs (required first, with type and description), its outputs and its submodules. It compares the module's provider requirements with the versions the bundle pins and says "NOT USABLE" when they exclude it. Only allowed namespaces can be looked up. Answers are cached for the life of the process. It makes one new outbound call, to `registry.terraform.io`, which `terraform init` already reaches. ## 3. The Skill `skills/google-cloud-iac-modules/`: when to use a module (it is in the table, it replaces three or more dependent resources, and every Check on the Elements it covers can be met through an input), and four references with a validated example each. | For | Module | Version | |---|---|---| | VPC, subnets, firewall rules, Cloud NAT | `network`, `cloud-nat` | 18.3.1, 7.1.0 | | Cloud SQL for PostgreSQL on a private address | `sql-db//modules/postgresql`, `//modules/private_service_access` | 28.3.0 | | A Cloud Storage bucket with retention, lifecycle, encryption, grants | `cloud-storage//modules/simple_bucket` | 12.4.1 | | A key ring, keys and grants | `kms` | 4.2.1 | `tests/test_iac_modules.py` runs each example through `terraform validate` with the patterns Skill's versions file, and checks that every module call is from an allowed namespace at the version the table gives. It needs the network and is skipped without it. The Skill is named in the bundle under `terraform.modules.skill`, not among any role's Skills. See step 5 for who is given it. ## 4. Checks through a module A Check stays worded about the resource. `implementation.json` gives the module and the input that meets it, such as `module.database.ip_configuration.ipv4_enabled`. When no input sets what a Check needs, the module does not fit and the resources are written directly. The validator reads the input's value and confirms with the lookup what it sets, or what its default is. This is instruction, in the Skills and the two role files. Nothing in code verifies that a module input does what a Check says: that would need a plan against a real project. ## 5. Opt-in per Execution Infrastructure code is plain resources unless the Execution opts in. - `ExecutionEngine.start(terraform_modules=...)`: true, false, or unset. Unset, a Change request does as its Baseline did, and any other Execution takes `TERRAFORM_MODULES` (off). Opting in is refused when the provider's bundle lists no sources. - Callers: `terraform_modules` in the `/generate` body, in A2A message metadata, and on an evaluation case. - **Opted in:** the roles that carry the `terraform_module` tool (the IaC author and the validator) are given the modules Skill, and their context says `terraform_modules: true`. - **Not opted in:** those roles get neither the Skill nor the tool, and any `module` block is refused by `terraform_validate` and `terraform_plan` with a message saying to write the resources directly. The refusal is in code (`MODULES_OPTED_IN` in `app/tools/modules.py`, set when a Specialist starts), not only in instructions. - `execution.json` records `terraform_modules`. Reference routing (iteration 5 step 8) does not choose within the modules Skill, because it is not among a role's Skills at start-up. ## Known limits - Modules also bring providers the bundle does not pin (`google-beta`, `random`, `null`), at whatever version their constraints allow. - The schema review and the target architect's lookups still describe resources. A Check's wording is unaffected by whether a module later creates the resource. - A module version in the catalogue goes stale; `scripts/check-terraform-modules.py` reports it when run, and nothing runs it on a schedule. Tests: `tests/tools/test_modules.py` (24), `tests/test_iac_modules.py` (6), `tests/execution/test_terraform_modules.py` (7). ## Run on 2026-10-09 Case 03's request, once each way, side by side (`20261009T210931Z` plain, `20261009T210935Z` opted in as `case-07-approved-modules`). Both completed at 100%. | | Plain resources | Modules opted in | |---|---|---| | Minutes | 35 | 22 | | Tokens | 5.66 million | 3.08 million | | Cost, about | $5.50 | $3.17 | | Revisions of the Target architecture | 3 | 1 | | Checks, all passed | 77 | 54 | | Module calls / resources / lines of Terraform | 0 / 35 / 555 | 2 / 25 / 448 | | Design quality score | 0.82 | 0.62 | **The difference in time and cost is the Revisions, not the modules.** The two runs produced different designs before any code was written: 77 Checks against 54, three Revisions against one. One run each way cannot say modules are cheaper. What the opted-in run does show: - The IaC author used a module for one thing, private Cloud SQL (`sql-db//modules/postgresql` with `//modules/private_service_access`, 28.3.0), and wrote the network, load balancer, Cloud Run, storage, secrets, IAM and monitoring as plain resources. A VPC with one subnet did not get the network module. - 14 of 54 Checks are met through module inputs, each recorded as `module.cloud_sql.`; the validator passed all 14 citing the input's value. - `terraform_module` was called four times by the author and once by the validator. No module was refused, and the code validated. - For a Check met by leaving an input unset, the validator's evidence is that the module falls back to its default. That rests on the module's documentation. The plain run was given neither the Skill nor the tool, and wrote no module. The design quality score of 0.62 is below the bar of 0.67. It is scored on the design recommendations, written before any code. ## Two follow-ups (2026-10-10) - **A Check is met by a value in the code.** The first run showed the validator arguing from a module's default where an input was left unset. The Skill now tells the author to set every input a Check depends on, even when the default already gives the value; where one is still left unset the verdict says so. - **Stale and newly usable modules are reported.** `scripts/check-terraform-modules.py` reads the registry and prints, for each module the Skill's examples call, the pinned version against the latest and whether the latest still works with the pinned provider; and for each module in `terraform.modules.watch`, whether it can now be used. Today all five are up to date and none of the eight watched modules can be used: each still requires a `google` provider below 8. It changes nothing; it needs running by hand.