Changelog 2026-07-10 -- DOCFIX-179: OpenTofu scaffold, first real validation + apply

Context. First-ever execution of the opentofu/ tree against a real tofu binary (OpenTofu v1.12.3), on the vcloud host, executing runbooks/dc-dc-phase0-vcloud-prep.md Steps 8-11. The tree had carried a SCAFFOLD, UNVALIDATED banner since authoring (no tofu had ever run it). Two real bugs blocked tofu init/plan; both fixed here, then the Stage-1 module slice was validated, planned, and applied clean (13 libvirt objects).

What changed

FIX 1 -- per-module required_providers (the tofu init blocker)

• tofu init failed: child modules use libvirt_*/maas_* resources but did not declare their own required_providers, so OpenTofu inferred the libvirt_ prefix as hashicorp/libvirt (nonexistent) instead of dmacvicar/libvirt. Provider SOURCE mapping is NOT inherited by child modules -- only provider CONFIGURATION is.
• Added versions.tf (source-only; version stays pinned at the root) to every module using a provider resource: 8 libvirt modules (dc-planes, mesh-link, dc-storage-pool, office1-network, node-vm, base-image, cloudinit-vm, opnsense-edge) + 1 maas module (maas-vm-host). netem-link uses only the built-in terraform_data, so it needs none. Fixed comprehensively (all modules, not just Stage 1's four) so Stage 2/3 do not re-hit it.

FIX 2 -- tofu fmt (the whole never-fmt'd scaffold)

• tofu fmt -recursive opentofu/ normalized 11 files (attribute alignment, comment reflow) that had drifted because no tofu had ever formatted them.

CHANGE 3 -- provider "maas" deferred to Stage 3

• The root provider "maas" block forced tofu plan to demand maas_api_url AND the sensitive maas_api_key for a Stage-1 plan that creates ZERO MAAS resources -- which would bake a fake key into phase0.tfplan and terraform.tfstate (the DOCFIX-175 plaintext-secret surface). Operator ruled (2026-07-10) to fix structurally rather than use the runbook's placeholder workaround. Removed the provider "maas" block from main.tf and the maas_api_url/maas_api_key variables from variables.tf, with in-file notes to re-add them at Stage 3 (when maas-vm-host is instantiated). maas stays in the ROOT versions.tf required_providers (version pinned, .terraform.lock.hcl complete for Stage 3).

FIX 4 -- repo-lint must skip OpenTofu's .terraform/ provider cache

• After the first real tofu init, repo-lint FAILED L1 (ASCII) on a downloaded provider plugin's README inside opentofu/.terraform/. DOCFIX-175 gitignored .terraform/ for git, but repo_lint.py's all_text() scans the filesystem, not git. Added ".terraform" in p.parts to all_text()'s skip set (alongside .git/__pycache__) -- third-party, gitignored, not repo content. tests/repo-lint/run-tests.sh -> 34/34 PASS.

Result

• tofu validate -> Success. tofu plan -> 13 to add / 0 / 0, with NO MAAS vars required. tofu apply -> 13 added, 0 changed, 0 destroyed (6 DC1 planes + dc1/office1/dc2 pools + office1-local + 3 mesh legs, all MTU 9000).
• .terraform.lock.hcl is now generated -- commit it (pins provider hashes: dmacvicar/libvirt 0.9.8, canonical/maas 2.7.2).
• opentofu/README.md status banner updated: Stage-1 module slice VALIDATED + APPLIED; the not-yet-instantiated Stage 2/3 modules remain UNVALIDATED.

Verification

• bash scripts/opentofu-validate.sh (== tofu fmt -check + init + validate) -> clean after the fixes.
• bash scripts/repo-lint.sh -> 0 fail.

Revert

• git rm opentofu/modules/*/versions.tf (the 9 added files) -- restores the original tofu init inference failure.
• Re-add the provider "maas" block to main.tf and the two maas_* variables to variables.tf from this changelog / git history.
• tofu fmt reverts are cosmetic; git checkout the 11 files to undo.
• (Live infra: runbooks/dc-dc-teardown-rollback.md / tofu destroy -- not part of a repo revert.)

Follow-up (logged)

• Stage 3's runbook must re-add the provider "maas" block + the two variables when it wires maas-vm-host -- noted in main.tf/variables.tf in-file.