cem_acpt 0.11.0 → 0.11.2

data/docs/ARCHITECTURE.md

@@ -0,0 +1,1042 @@
+# cem_acpt Architecture
+
+This document describes the architecture of `cem_acpt`, a Ruby gem that provides
+two CLI tools for the Puppet SCE (Security Compliance Enforcement, formerly
+CEM) module suite:
+
+- **`cem_acpt`** — runs acceptance tests against ephemeral cloud nodes. For
+  each acceptance test it provisions a node, applies a Puppet manifest, runs
+  Goss-based infrastructure assertions over HTTP, optionally runs Bolt tasks,
+  and tears the node down.
+- **`cem_acpt_image`** — builds the base VM images that `cem_acpt` later uses
+  as the boot disk for its test nodes.
+
+The intended audience is engineers working on `cem_acpt` itself or on the
+consuming Puppet modules (`sce_linux`, `sce_windows`, etc.). It assumes
+familiarity with Ruby, Terraform, Puppet modules, and GCP at a basic level.
+
+> Companion docs: [README.md](../README.md) covers user-facing usage and
+> configuration. [CLAUDE.md](../CLAUDE.md) summarizes commands and
+> conventions. This document describes how the code is organized and how
+> the parts fit together.
+
+## Table of contents
+
+1. [Repository layout](#1-repository-layout)
+2. [Runtime entry points](#2-runtime-entry-points)
+3. [Configuration system](#3-configuration-system)
+4. [`cem_acpt` test-runner lifecycle](#4-cem_acpt-test-runner-lifecycle)
+5. [Test data & image-name builder](#5-test-data--image-name-builder)
+6. [Platform abstraction](#6-platform-abstraction)
+7. [Provisioner: Terraform](#7-provisioner-terraform)
+8. [Action framework](#8-action-framework)
+9. [Goss subsystem](#9-goss-subsystem)
+10. [Bolt subsystem](#10-bolt-subsystem)
+11. [Result aggregation & log formatting](#11-result-aggregation--log-formatting)
+12. [`cem_acpt_image` image-builder lifecycle](#12-cem_acpt_image-image-builder-lifecycle)
+13. [Windows path](#13-windows-path)
+14. [Cross-cutting utilities](#14-cross-cutting-utilities)
+15. [Logging](#15-logging)
+16. [On-disk state](#16-on-disk-state)
+17. [Test suite](#17-test-suite)
+18. [External dependencies](#18-external-dependencies)
+19. [Open questions / observed dead code](#19-open-questions--observed-dead-code)
+
+---
+
+## 1. Repository layout
+
+```
+cem_acpt/
+├── exe/
+│   ├── cem_acpt              # bin entry point for the test runner
+│   └── cem_acpt_image        # bin entry point for the image builder
+├── lib/
+│   ├── cem_acpt.rb           # top-level dispatcher (CemAcpt.run)
+│   ├── cem_acpt/             # all Ruby code
+│   │   ├── cli.rb            # OptionParser definitions for both binaries
+│   │   ├── config.rb         # requires Config::CemAcpt and Config::CemAcptImage
+│   │   ├── config/           # config schema + merge engine
+│   │   ├── core_ext.rb       # Hash#dot_dig, Hash#dot_store, Array#split_into_groups
+│   │   ├── logging.rb        # MultiLogger / GitHub Actions formatting
+│   │   ├── logging/          # log line formatters
+│   │   ├── platform.rb       # dynamic loader for platform implementations
+│   │   ├── platform/         # base + GCP platform module
+│   │   ├── provision.rb      # provisioner factory
+│   │   ├── provision/        # Terraform driver + OS-specific backends
+│   │   ├── test_runner.rb    # main TestRunner::Runner
+│   │   ├── test_runner/      # log_formatter/, test_results.rb
+│   │   ├── actions.rb        # ActionGroup / Action / ActionConfig
+│   │   ├── goss.rb           # requires goss/api
+│   │   ├── goss/             # HTTP client + response wrapping
+│   │   ├── bolt.rb           # Bolt::TestRunner
+│   │   ├── bolt/             # cmd/, cmd.rb, errors, helpers, inventory,
+│   │   │                     # project, summary_results, tasks, tests, yaml_file
+│   │   ├── image_builder.rb  # TerraformBuilder (image-build flow)
+│   │   ├── image_builder/    # Exec wrapper + ProvisionCommands
+│   │   ├── image_name_builder.rb
+│   │   ├── test_data.rb      # acceptance-test discovery + variable expansion
+│   │   ├── utils.rb          # high-level helpers (e.g. Windows password polling)
+│   │   ├── utils/            # shell, ssh, files, puppet, winrm_runner, etc.
+│   │   └── version.rb
+│   └── terraform/            # HCL templates copied to ~/.cem_acpt at runtime
+│       ├── gcp/
+│       │   ├── linux/        # test-node provisioning + systemd + log_service
+│       │   └── windows/      # test-node skeleton (no remote-exec; see §13)
+│       └── image/
+│           └── gcp/
+│               ├── linux/    # image-build node provisioning
+│               └── windows/  # placeholder (.keep only) — no template yet
+├── spec/                     # RSpec tests mirroring lib/
+├── docs/                     # this directory
+├── sample_config.yaml
+├── cem_acpt.gemspec
+├── Rakefile                  # delegates to bundler/gem_tasks + RSpec
+└── .rubocop.yml              # Ruby 3.2 target, line length 200
+```
+
+`lib/terraform/` is shipped inside the gem. At runtime its contents are
+copied into `~/.cem_acpt/terraform/`; a SHA-256 checksum (mixing in
+`CemAcpt::VERSION`) decides whether the on-disk copy is stale and needs
+to be replaced (`Config::Base#create_terraform_dir!`).
+
+## 2. Runtime entry points
+
+Both binaries are thin shells that:
+
+1. `require 'dotenv/load'` so any `.env` in CWD is available before
+   the config layer reads `ENV`.
+2. Parse CLI options through `CemAcpt::Cli.parse_opts_for(:cem_acpt)`
+   or `:cem_acpt_image` (`lib/cem_acpt/cli.rb`), which returns a
+   `[command, options]` tuple. `command` is normally `:cem_acpt` or
+   `:cem_acpt_image`, but can be one of `:version`,
+   `:print_yaml_config`, or `:print_explain_config` if a meta flag was
+   passed.
+3. Hand off to `CemAcpt.run(command, original_command, options)` in
+   `lib/cem_acpt.rb`.
+
+`CemAcpt.run` is the single dispatch point for both binaries. It:
+
+- installs a SIGINT handler that flips the logger into trap-context mode
+  before calling `exit 1` (`set_up_signal_handlers`),
+- optionally wraps the run in a `TracePoint` (filtered to
+  `lib/cem_acpt` paths, excluding `lib/cem_acpt/logging`) when
+  `--trace` is set,
+- delegates to `run_cem_acpt` (which builds a `TestRunner::Runner`
+  and `exit`s with the runner's `exit_code`), or
+- delegates to `run_cem_acpt_image` (which builds a
+  `ImageBuilder::TerraformBuilder` via `ImageBuilder.build_images`).
+
+```text
+exe/cem_acpt ──▶ CemAcpt::Cli.parse_opts_for ──▶ CemAcpt.run ──▶ TestRunner::Runner#run
+exe/cem_acpt_image ──────────────────────────────────────────▶ ImageBuilder::TerraformBuilder#run
+```
+
+Both binaries default `options[:module_dir]` to `Dir.pwd` if the user
+did not pass `-m / --module-dir`.
+
+## 3. Configuration system
+
+Configuration lives under `lib/cem_acpt/config/`:
+
+- `Config::Base` — merge engine, environment-variable handling,
+  Terraform-dir bootstrapping, secret wrapping, validation, freezing.
+- `Config::CemAcpt` — schema (`VALID_KEYS`) and `defaults` for the test
+  runner. Top-level keys include `actions`, `bolt`, `image_name_builder`,
+  `module_dir`, `node_data`, `test_data`, `tests`.
+- `Config::CemAcptImage` — schema and `defaults` for the image builder.
+  Top-level keys include `cem_acpt_image`, `dry_run`, `images`,
+  `image_name_filter`, `no_build_images`, `node_data`. Uses an
+  `env_var_prefix` of `CEM_ACPT_IMAGE` and registers a `load_hook` that
+  filters `images` by `image_name_filter` *after* the merge but before
+  validation.
+
+### Merge order
+
+`Config::Base#load` merges sources from low to high precedence. The
+ordering visible in code (`base.rb:125-155`) is:
+
+1. **Defaults** from the subclass (seeded in `init_config!`).
+2. **Environment variables** matching `CEM_ACPT_*` (or
+   `CEM_ACPT_IMAGE_*` for the image builder), translated by
+   `env_var_to_dot_key` so e.g. `CEM_ACPT_NODE_DATA__DISK_SIZE` becomes
+   `node_data.disk_size`. Only env vars whose top-level key is in
+   `valid_keys` are kept.
+3. **User config** at `~/.cem_acpt/config.yaml` (skippable with
+   `load_user_config: false`).
+4. **`--config FILE`** (the runtime config file). Resolved against
+   `module_dir` first, then `File.expand_path` fallback.
+5. **CLI `@options`** (everything else from `parse_opts_for`).
+6. **`add_static_options!`** runs last as a single phase; internally
+   it does two things:
+   - 6a. Sets the framework-owned keys `user_config.dir`,
+     `user_config.file`, `provisioner = 'terraform'`, and
+     `terraform.dir`. Only these four keys clobber anything earlier;
+     the rest of the merged config is untouched.
+   - 6b. Calls `set_third_party_env_vars!`: `RUNNER_DEBUG=1` forces
+     `log_level=debug` and `verbose=true`; `GITHUB_ACTIONS=true` or
+     `CI=true` forces `ci_mode=true`.
+7. The optional class-level `load_hook` then runs inside `load`
+   (currently used by `Config::CemAcptImage` to filter images).
+
+The merge uses `deep_merge` with `overwrite_arrays: true` and
+`merge_nil_values: true`. Hash keys are then symbolized via the
+`ExtendedHash#format!` refinement, unknown top-level keys are dropped
+with a `warn`, secrets are wrapped, and the final hash is `freeze`d
+for thread safety.
+
+The README documents the precedence order in user-facing terms; this
+section reflects the actual implementation order, which is consistent.
+
+### Lookups
+
+`Config::Base#get('a.b.c')` (alias `dget`, also `[]` when called with a
+String) walks the frozen hash via `Hash#dot_dig`. Results are duplicated
+on read (`@dot_key_cache`), so callers cannot mutate config state.
+
+### Secrets
+
+The `secrets:` top-level key can come from any merge source (env
+variable, user config, runtime config file, or CLI `-O`). After the
+merge and key-symbolization steps, every value under `secrets:` is
+wrapped in `Config::Secret`, whose `#to_s` and `#inspect` redact the
+value (`Secret(key=****)`). Provisioning code unwraps secrets only at
+the moment of running Terraform (`Provision::Terraform#unwrap_secrets`,
+`ImageBuilder::TerraformBuilder#terraform_vars`). The README warns that
+secrets can still leak through Terraform's own logging.
+
+### `-Y` and `-X`
+
+`CemAcpt.print_config` builds a config without running anything:
+`-Y` prints the merged result as YAML; `-X` prints
+`Base#explain` — a trace of every key and the source(s) that
+contributed to it (collected via `add_config_explanation` calls
+sprinkled through the merge steps).
+
+## 4. `cem_acpt` test-runner lifecycle
+
+`TestRunner::Runner#run` (`lib/cem_acpt/test_runner.rb`) is the entire
+test-execution flow. It is wrapped in a `begin/rescue/ensure` so that
+provisioned infrastructure is always cleaned up.
+
+```text
+   ┌─ start_time recorded ─────────────────────────────────────────┐
+   │                                                               │
+   │  1. Dir.chdir(module_dir)                                     │
+   │  2. configure_actions          (registers :goss + :bolt)      │
+   │  3. pre_provision_test_nodes:                                 │
+   │       • build Puppet module tarball                           │
+   │       • build test_data array (one entry per test × for_each) │
+   │       • build platform/node objects (one per test_data entry) │
+   │       • create ephemeral SSH keys (unless disabled)           │
+   │       • setup_bolt (if :bolt action is registered)            │
+   │  4. provision_test_nodes       (terraform init/plan/apply)    │
+   │  5. instance_names_ips = provisioner_output (with retries)    │
+   │  6. partition tests by Provision::OsData.os_family_for:       │
+   │       (the test list — not platform.name — drives this fork)  │
+   │       • mixed Windows + Linux → raise (unsupported today)     │
+   │       • all-Windows: upload module tarball to                 │
+   │         gs://<windows_bucket> and for each instance run       │
+   │         WinRMRunner::WinNode.run                              │
+   │  7. run_tests                                                 │
+   │       • Actions.execute over registered groups                │
+   │         - :goss group runs async via async-http               │
+   │         - :bolt group runs sync; threaded inside Bolt runner  │
+   │                                                               │
+   │  rescue StandardError ──▶ append error to results             │
+   │  ensure ─▶ clean_up ─▶ destroy_test_nodes (or `terraform show`│
+   │           if --no-destroy-nodes), clean ephemeral keys,       │
+   │           cleanup_bucket (Windows), Dir.chdir(@old_dir)       │
+   │  ensure ─▶ process_test_results: pop from queue, set exit_code│
+   └───────────────────────────────────────────────────────────────┘
+```
+
+### Key state on the runner
+
+- `@run_data` — a hash that travels with everything provisioned. Holds
+  `:module_package_path`, `:test_data` (Array of test-data hashes),
+  `:nodes` (Array of platform objects), `:private_key`, `:public_key`,
+  `:known_hosts`, and on Windows `:win_remote_module_name` /
+  `:win_remote_module_path`.
+- `@instance_names_ips` — what Terraform's `instance_name_ip` output
+  emits: `{ <instance_name> => { 'ip' => ..., 'test_name' => ... } }`.
+- `@hosts` — the IPs that Goss and Bolt run against.
+- `@results` — a `TestRunner::TestResults::Results` (queue-backed).
+- `@exit_code` — `0` only if every result has status in
+  `SUCCESS_STATUS = [200, 0]`.
+
+### Pass/fail rules
+
+- `process_test_results` iterates the results queue, calls `.status` on
+  each, and sets `@exit_code = 1` on the first non-success.
+- Empty results → `@exit_code = 1`. (i.e. "no tests ran" is a failure.)
+- `provisioner_output` makes up to 3 attempts (i.e. 2 retries) with a
+  3-second sleep between attempts; nil/empty after the third attempt
+  raises.
+
+### Cleanup contract
+
+`clean_up` runs once unconditionally (in the outer `ensure`). It is
+no-op if `--no-destroy-nodes` is set, in which case it instead logs
+the SSH keys and runs `terraform show` so the user can SSH into the
+provisioned nodes manually.
+
+## 5. Test data & image-name builder
+
+### Test discovery
+
+`TestData::Fetcher` (`lib/cem_acpt/test_data.rb`) reads the
+`tests:` config array. For each entry it expects a directory under
+`<module_dir>/spec/acceptance/<test_name>/` containing at least:
+
+- `goss.yaml` — Goss assertions
+- `manifest.pp` — Puppet manifest applied during provisioning
+
+and optionally:
+
+- `bolt.yaml` — per-task validation hashes (see §10)
+
+If `goss.yaml` or `manifest.pp` is missing, the runner raises before
+provisioning anything.
+
+### Variable expansion
+
+For each acceptance test, the fetcher builds a base test-data hash
+(`{ test_name:, test_dir:, goss_file:, puppet_manifest:, bolt_test? }`)
+and then runs four expansion passes:
+
+1. **`for_each`** — duplicates the hash once per item in each
+   `test_data.for_each.<key>` array, setting that key on the duplicate.
+   The default config seeds `for_each.collection = ['puppet8']`, so a
+   single test produces a single test-data entry by default but can be
+   easily fanned out.
+2. **`vars`** — merges `test_data.vars` static key/values.
+3. **`name_pattern_vars`** — runs the test name against a Regexp with
+   named captures and merges those captures. The default pattern
+   carves a name like `cis_rhel-8_firewalld_server_2` into:
+
+   | Capture          | Value      |
+   |------------------|------------|
+   | `framework`      | `cis`      |
+   | `image_fam`      | `rhel-8`   |
+   | `firewall`       | `firewalld`|
+   | `framework_vars` | `server_2` |
+4. **`vars_post_processing`** — `new_vars` synthesizes new keys from
+   existing ones (only `string_split` is implemented today). The
+   default config splits `framework_vars` into `profile` and `level`.
+   `delete_vars` drops keys after the new ones are computed.
+
+The result is an Array of hashes; each one produces one provisioned
+test node.
+
+### Image name
+
+If the config has an `image_name_builder` key, `Platform::TestBase`
+defers to `ImageNameBuilder` (`lib/cem_acpt/image_name_builder.rb`)
+for each test-data entry. The builder:
+
+1. Resolves each part: `'$image_fam'` → `test_data.dot_dig('image_fam')`.
+2. Joins with `join_with` (default ``''``).
+3. Optionally validates against `validation_pattern`.
+4. Applies pairwise `character_substitutions`.
+
+If `image_name_builder` is not configured, the platform falls back to
+`test_data[:image_name]`, which would have to come from `vars` or
+`name_pattern_vars`.
+
+## 6. Platform abstraction
+
+`CemAcpt::Platform` (`lib/cem_acpt/platform.rb`) is a small dynamic
+loader. The active platform is `config.get('platform.name')` (default
+`'gcp'`). The string is matched case-sensitively against the basenames
+of `lib/cem_acpt/platform/*.rb`, which are all lowercase — so this
+config value must be lowercase (e.g. `gcp`, not `GCP`) or the lookup
+will fail with `Platform <name> is not supported`.
+
+- `Platform::Base` — node identity, defines abstract `platform_data` /
+  `node_data` hooks.
+- `Platform::TestBase < Base` — adds per-test-data context and the
+  `image_name` lookup hook.
+- `Platform.use(platform, config, run_data)` — for each entry in
+  `run_data[:test_data]`, instantiates one platform-specific
+  `TestBase` and returns the array. Used by the test runner.
+- `Platform.get(platform, base_type: :base|:test)` — returns the class
+  without instantiating it. Used by the image builder, which only
+  needs `platform_data` (no per-test context).
+
+### Loading mechanics
+
+`platforms` is computed once and memoized on the module by globbing
+`lib/cem_acpt/platform/*.rb` and excluding `base.rb`. To add a new platform you create
+`lib/cem_acpt/platform/<name>.rb` defining a module
+`CemAcpt::Platform::Mixin::<CamelCaseName>` with `#platform_data` and
+`#node_data`. `platform_class` then dynamically creates a class named
+after the camel-cased platform name (e.g. `gcp` → `Gcp`,
+`aws_govcloud` → `AwsGovcloud`) inheriting from `Platform::Base` or
+`Platform::TestBase`, and `include`s the corresponding mixin from
+`CemAcpt::Platform::Mixin`. The class is cached on `CemAcpt::Platform`
+under that name for subsequent lookups; the cache check uses
+`const_defined?(name, false)` so unrelated same-named constants
+elsewhere in the constant graph cannot win.
+
+### GCP
+
+`CemAcpt::Platform::Mixin::Gcp` (`lib/cem_acpt/platform/gcp.rb`) is
+mixed into the dynamic `CemAcpt::Platform::Gcp` class and populates
+`platform_data` and `node_data` by:
+
+- preferring values from `config.get('platform.*')` and
+  `config.get('node_data.*')`, then
+- shelling out to `gcloud` (`os-login describe-profile`,
+  `config get-value project|compute/region|compute/zone`) for any value
+  the user didn't set.
+
+The platform also supplies the SSH private/public key paths from
+`@run_data` (the ephemeral keys created in pre-provision), falling
+back to `~/.ssh/google_compute_engine{,.pub}`.
+
+`platform_data` returns the cluster-wide vars (project, region, zone,
+subnetwork, credentials, keys, username). `node_data` returns the
+per-instance vars (machine type, disk size, max run duration, image
+name, test name).
+
+## 7. Provisioner: Terraform
+
+There is currently one provisioner. `Provision.new_provisioner`
+(`lib/cem_acpt/provision.rb`) returns
+`Provision::Terraform` for `provisioner == 'terraform'` and raises
+otherwise. `provisioner` is currently force-set to `'terraform'` in
+`Config::Base#add_static_options!`, so this dispatch is effectively
+fixed today.
+
+### `Provision::Terraform`
+
+`lib/cem_acpt/provision/terraform.rb` orchestrates the four-step
+Terraform run:
+
+1. **Pick a backend** based on the first test's name. `OsData.use_for?`
+   matches the `^prefix_osname-version` pattern; `Linux.valid_names`
+   covers `centos rhel oel alma rocky ubuntu` and `valid_versions`
+   covers `7 8 9 2004 2204 2404`. `Windows.valid_names` is
+   `[windows]` and versions are `2016 2019 2022 2025`.
+2. **Build a working dir** at
+   `~/.cem_acpt/terraform/test_<unix_ts>/`, populated by
+   `cp_r`-ing the backend's `provision_directory`
+   (`<terraform_dir>/<platform>/<linux|windows>/`, computed in
+   `new_working_dir` from `base_provision_directory + implementation_name`)
+   plus the Puppet module tarball. The private and public keys are
+   each copied only when they exist on disk; otherwise the
+   corresponding state field stays `nil`.
+3. **Format vars** (`formatted_vars`) — merges
+   `nodes.first.platform_data` with `puppet_module_package`,
+   `private_key`, `public_key`, and the `node_data` map (one entry per
+   provisioned instance). `node_data` includes test-specific paths
+   (`goss_file`, `puppet_manifest`) and the `provision_commands` array
+   that Terraform feeds into a `remote-exec`.
+4. **Run the Terraform CLI** (`init`, `plan`, `apply`, `output`,
+   `destroy`, `show`) via `TerraformCmd`.
+
+### `TerraformCmd`
+
+`lib/cem_acpt/provision/terraform/terraform_cmd.rb` is a thin
+stand-in for the abandoned `ruby-terraform` gem. It builds shell
+commands (e.g. `terraform -chdir=… plan -out=…`), shells out via
+`Utils::Shell.run_cmd`, streams stdout/stderr to the logger in real
+time, and raises `ShellCommandError` on non-zero exit (configurable).
+
+Notable behavior:
+
+- The `vars` opt is rendered as `-var='key=value'` (or
+  `-var='key=<json>'` for hash values).
+- `plan` requires `:plan` and writes it via `-out=...`. `apply`
+  requires `:plan` and supplies it as the trailing positional arg.
+- `output` defaults to `combine_out_err: false` so JSON parsing
+  isn't broken by stderr noise.
+- `chdir` walks `[Dir.pwd, working_dir, opts[:chdir]]` and uses the
+  first directory that contains a `main.tf`.
+
+### OS-specific provision commands
+
+`Provision::Linux#provision_commands` produces the inline list passed
+to the `remote-exec` block of `lib/terraform/gcp/linux/main.tf`. The
+remote module package name comes from `OsData#remote_module_package_name`
+(currently `'puppet-module.tar.gz'`):
+
+```
+sudo /opt/puppetlabs/puppet/bin/puppet module install /opt/cem_acpt/puppet-module.tar.gz
+curl -fsSL https://goss.rocks/install | sudo sh
+sudo /opt/puppetlabs/puppet/bin/gem install webrick
+sudo chmod +x /opt/cem_acpt/log_service/log_service.rb
+sudo /opt/cem_acpt/log_service/log_service.rb              # daemonized HTTP server on :8083
+
+# Only if `<provision_directory>/systemd/*.service` is non-empty
+# (currently: goss-acpt, goss-idempotent, goss-noop):
+sudo cp /opt/cem_acpt/systemd/<file> /etc/systemd/system/<file>
+sudo systemctl daemon-reload
+sudo systemctl start <file> && sudo systemctl enable <file>
+
+# Finally — note that --logdest comes before [--debug]/[--verbose],
+# and the manifest is the trailing positional argument:
+sudo /opt/puppetlabs/puppet/bin/puppet apply \
+  --logdest console,/opt/cem_acpt/provision_apply.log \
+  [--debug] [--verbose] \
+  /opt/cem_acpt/manifest.pp
+```
+
+`provision_commands_wrapper` prepends RPM/dnf or apt warm-up commands
+for EL8-family or Ubuntu base images respectively.
+
+The Windows backend has no analogous `provision_commands` —
+`Provision::Terraform#provision_node_data` dispatches on backend
+class and threads an empty list into the Windows `node_data`. The
+real shell work happens via WinRM after Terraform finishes; see §13.
+Calling `Provision::Windows#provision_commands` directly raises
+`NotImplementedError` to signal that to anyone who tries.
+
+The image-build flow in §12 reuses the same plan/apply/output/destroy
+shape as this provisioner — that section concentrates on the
+differences (image creation, `gcloud` integration, `--filter` and dry
+runs) rather than re-deriving the Terraform CLI choreography.
+
+### Terraform templates
+
+The on-disk templates (`lib/terraform/gcp/linux/main.tf`,
+`lib/terraform/gcp/windows/main.tf`) declare the required
+`google` provider (currently pinned to `7.24.0`), accept the merged
+vars, and create a `google_compute_instance` per `var.node_data`
+entry. The Linux template runs a sequence of `remote-exec` and
+`file` provisioners to upload `provision_dir_source` (the test
+artifacts), the Puppet module tarball, `goss.yaml`, and `manifest.pp`,
+then runs `each.value.provision_commands` over SSH.
+
+Each instance is tagged `cem-acpt-test-node` and tagged in metadata
+with `cem-acpt-test=<test_name>`. The `instance_name_ip` output is the
+`{ instance => { ip:, test_name: } }` map the runner consumes.
+
+The systemd unit files (`goss-acpt.service`, `goss-idempotent.service`,
+`goss-noop.service`) start three `goss serve` instances on
+ports 8080/8081/8082 with endpoints `/acpt`, `/idempotent`, `/noop`.
+`goss-idempotent` and `goss-noop` pin their ports explicitly with
+`-l ":8081"` / `-l ":8082"`; `goss-acpt` has no `-l` flag and relies
+on goss's default of `:8080` — functionally identical, but
+asymmetric across the three units.
+`log_service.rb` (also shipped under `lib/terraform/gcp/linux/`) is a
+WEBrick server on port 8083 serving the contents of the apply logs.
+
+## 8. Action framework
+
+`CemAcpt::Actions` (`lib/cem_acpt/actions.rb`) is a small
+register/execute framework. It has three classes:
+
+- **`Action`** — name, order, callable block.
+- **`ActionGroup`** — ordered, optionally async list of `Action`s.
+- **`ActionConfig`** — global config object: `groups` (Hash), `only`,
+  `except`. Filters happen at `filter_actions` time on each group.
+
+The runner registers two groups in `configure_actions`:
+
+| Group   | Order | Async | Action(s)                                         |
+| ------- | ----- | ----- | ------------------------------------------------- |
+| `:goss` | 0     | yes   | `:acpt`, `:idempotent`, `:noop` (one per Goss endpoint) |
+| `:bolt` | 1     | no    | `:bolt` (delegates to `Bolt::TestRunner`)         |
+
+`Actions.execute` runs each group sequentially in `order`. Async
+groups create an `Async::Barrier` and a single `Async::HTTP::Internet`
+that is shared across all action calls in the group; this is the
+HTTP client the Goss action callbacks use. Sync groups simply iterate
+and call.
+
+CLI flags `-a / --only-actions` and `-A / --except-actions` populate
+`config.actions.only` and `config.actions.except`, which feed
+`ActionConfig#only=` and `#except=`.
+
+The default Goss action keys come from `Goss::Api::ACTIONS`
+(see §9). When the `bolt` binary is missing, `pre_provision_test_nodes`
+suppresses the `:bolt` action by catching `ShellCommandNotFoundError`
+in `Runner#setup_bolt` and appending `:bolt` to
+`CemAcpt::Actions.config.except` (preserving any user-supplied
+`--except-actions` entries). The remaining action groups continue
+normally.
+
+## 9. Goss subsystem
+
+`lib/cem_acpt/goss/api.rb` is a tiny HTTP client.
+
+- `Goss::Api::ACTIONS = { acpt: '8080/acpt', idempotent: '8081/idempotent', noop: '8082/noop' }`.
+- `run_action(host, action, internet=nil)` does an HTTP GET against
+  `http://<host>:<port>/<endpoint>`, parses the JSON body, and wraps
+  the result in `Goss::Api::ActionResponse`.
+- `get_run_logs(host, internet=nil)` GETs `http://<host>:8083/run-logs`
+  for the logs served by the on-node `log_service.rb`.
+
+The goss HTTP server runs as systemd units installed by the
+`provision_commands` (see §7).
+
+`ActionResponse` (`lib/cem_acpt/goss/api/action_response.rb`):
+
+- `#status` returns the integer HTTP status. `#success?` is `status == 200`.
+- `#results` lazily wraps each item in the JSON `'results'` array as
+  `ActionResponseResult` (one per Goss assertion).
+- `#summary` wraps the `'summary'` block as `ActionResponseSummary`
+  (failed_count / passed_count / total_duration / summary_line).
+- `DurationHandler` provides a small `Duration(value, unit, round)`
+  struct so callers can ask for `:nanoseconds | :milliseconds |
+  :seconds`.
+- `metadata` is an open hash the runner stuffs `:run_logs` into, which
+  the log formatter renders on failure (`log_action_test_result`).
+
+The runner registers one Action per `Goss::Api::ACTIONS` key. Each
+Action callback iterates over `@hosts` and makes **two** calls per
+host using the group's shared `Async::HTTP::Internet`: one
+`run_action` to the Goss endpoint, then a second `get_run_logs` to
+`:8083/run-logs` whose body is attached as `metadata[:run_logs]`. The
+combined response is pushed onto the shared `@results` queue. Sharing
+one `Async::HTTP::Internet` across both calls (and across all hosts in
+the group) is what keeps connection setup costs amortized.
+
+## 10. Bolt subsystem
+
+`lib/cem_acpt/bolt.rb` defines the top-level `Bolt::TestRunner`. The
+rest of the subsystem lives under `lib/cem_acpt/bolt/`, including
+`errors.rb` (defines `BoltActionError`), `helpers.rb`, `yaml_file.rb`
+(base class for the inventory/project YAML I/O), and
+`summary_results.rb` in addition to the classes called out below.
+
+### Object model
+
+| Class                         | Role                                                 |
+|-------------------------------|------------------------------------------------------|
+| `Bolt::TestRunner`            | Top-level coordinator. Owns inventory, project, tests. |
+| `Bolt::Inventory < YamlFile`  | Generates and persists `inventory.yaml`.             |
+| `Bolt::Project < YamlFile`    | Generates and persists `bolt-project.yaml`.          |
+| `Bolt::YamlFile`              | Idempotent YAML I/O (`save!`, `delete!`, `latest_saved?`). |
+| `Bolt::TaskList`              | `bolt task show` + filter (`module_pattern`, `name_filter`, `only`, `ignore`). |
+| `Bolt::TaskWrapper`           | Per-task abstraction with `show` / `run` and a `last_cmd_executed` pointer. |
+| `Bolt::Cmd::Base`             | Generic Bolt CLI builder, options DSL (`option`, `supports_params`). |
+| `Bolt::Cmd::TaskShow / TaskRun` | Concrete subcommands.                              |
+| `Bolt::Cmd::Output`           | Wraps the JSON output (`--format json` is hard-coded). Errors get coerced into a synthetic `_error` item so downstream code is uniform. |
+| `Bolt::Cmd::OutputItem / OutputError` | Per-target result item / error item.       |
+| `Bolt::Tests::TestData`       | Per-task validation hash from `bolt.yaml`.           |
+| `Bolt::Tests::Test`           | One Bolt task × matched groups. `#run` calls `task.run` and validates. |
+| `Bolt::Tests::TestList`       | Loads `bolt.yaml`s, builds `Test` instances using `TaskList × test_data`. |
+| `Bolt::Tests::TestResult`     | Per-target validation result.                        |
+| `Bolt::Tests::TestResults`    | Collection of `TestResult`s for one task.            |
+| `Bolt::SummaryResults < Utils::FinalizerQueue` | Aggregate over all tests; the value pushed to the runner's results queue. |
+
+### Setup / teardown
+
+`TestRunner#setup!` (called from
+`pre_provision_test_nodes` before any node is provisioned) writes
+`bolt-project.yaml` and `inventory.yaml` if they don't already match
+the in-memory hashes, and triggers `tests.setup!`, which runs
+`bolt task show` to discover tasks. If `bolt` isn't on the PATH the
+runner downgrades the action to ignored.
+
+After provisioning, the runner sets `bolt_test_runner.hosts =
+filtered_bolt_hosts` (filtering by `bolt.tests.only` / `.ignore`)
+and calls `run`. The private key was already injected into the
+`Inventory` at `Bolt::TestRunner.new` time (from
+`run_data[:private_key]`); there is also a `run_data=` writer that
+updates it, but the runner doesn't call it in this flow. By default
+Bolt tests are split into `bolt.max_threads` (default 5) groups and
+each group runs sequentially in its own Ruby thread. Set
+`threaded: false` (not exposed via CLI) for sync execution.
+
+`teardown!` runs `delete!` on the inventory and project unless
+`bolt.keep_inventory` / `bolt.keep_project` are set.
+
+### Validation
+
+Each `bolt.yaml` entry is a hash keyed by Bolt task name:
+
+```yaml
+'sce_linux::audit_sssd_certmap':
+  status: 'success'
+  value:
+    match: '^(true|false)$'
+```
+
+`TestData#validate_props` walks every key in the hash and:
+
+- compares to a string with `==`,
+- compares to a hash by interpreting `match:` / `not_match:` as
+  regex predicates and flagging unknown keys,
+- compares to anything else with `==`.
+
+Failures are accumulated as `{ prop:, result:, validator:,
+validation_value:, other_value: }` hashes that the
+`bolt_summary_results_formatter` renders.
+
+## 11. Result aggregation & log formatting
+
+### Results
+
+`TestRunner::TestResults::Results` (`test_runner/test_results.rb`)
+wraps a `Queue`. Anything pushed to it is converted on the way in:
+
+- a `StandardError` becomes a `TestErrorActionResult`,
+- everything else becomes a `TestActionResult`,
+
+and in both cases is paired with a log formatter built by
+`LogFormatter.new_formatter(result, config, instance_names_ips)`.
+The formatter implementations live under
+`lib/cem_acpt/test_runner/log_formatter/`:
+
+| Formatter                            | For                                                |
+|--------------------------------------|----------------------------------------------------|
+| `GossActionResponse`                 | Successful Goss responses                          |
+| `GossErrorFormatter`                 | Error Goss responses (`error?` is true)            |
+| `BoltSummaryResultsFormatter`        | Bolt subsystem aggregate                           |
+| `StandardErrorFormatter`             | Anything else that bubbles up                      |
+
+`process_test_results` pops each result, calls `result.status`, sets
+`@exit_code = 1` on the first non-success status, and routes the
+formatted output to `logger.info|verbose|error` based on whether each
+formatted line starts with `Passed:` / `Skipped:` / something else.
+On non-pass it appends the captured run logs (provision/idempotent/noop
+apply logs) — debug-level lines are filtered out unless
+`debug?` is true and `puppet.no_debug` is not set.
+
+### CI groups
+
+`logger.start_ci_group` / `end_ci_group` emit
+`::group:: ... ::endgroup::` directives on stdout when running under
+`GITHUB_ACTIONS`/`CI`/`-I` so the summary collapses neatly per node
+in the GitHub Actions web UI.
+
+## 12. `cem_acpt_image` image-builder lifecycle
+
+`ImageBuilder::TerraformBuilder` (`lib/cem_acpt/image_builder.rb`)
+is similar in shape to `Provision::Terraform` but builds an image
+artifact rather than running tests. The class comment explicitly
+acknowledges the duplication and flags it for future refactor.
+
+```text
+1. new_tfvars(config):
+     • require secrets.puppet_auth_token
+     • generate ephemeral SSH keys (unless disabled)
+     • for each entry in config.images:
+         - new_platform → platform_data
+         - merge in: provision_commands (via ProvisionCommands.provision_commands),
+                     image_family, base_image, windows_image flag
+2. divide_tfvars_by_os → linux_tfvars, windows_tfvars
+3. dry_run? → log and exit
+4. new_working_dir under ~/.cem_acpt/terraform/image/<platform>/image_builder_<ts>/
+5. terraform init for each os subdir
+6. for each os:
+     terraform plan → terraform apply
+     parse `node-data` output → for each instance:
+         gcloud compute instances stop                (unless --no-destroy-nodes)
+         unless --no-build-images:
+           gcloud compute images deprecate <old in family>
+           gcloud compute images create <new>
+     ensure terraform destroy                         (unless --no-destroy-nodes)
+```
+
+### Differences from the test runner
+
+- Each image's `provision_commands` is OS-aware:
+  `ProvisionCommands` (`lib/cem_acpt/image_builder/provision_commands.rb`)
+  generates the right repo-setup + puppet-agent install commands for
+  EL family, Debian/Ubuntu, or Windows.
+  `secrets.puppet_auth_token` is shipped to the node via an inline
+  `export PUPPET_AUTH_TOKEN='...'` prepended to the `provision_commands`
+  in the Terraform template.
+- The image-builder dir layout has `linux/` and `windows/` siblings;
+  the builder `Dir.chdir` between them as it iterates
+  (`in_os_dir(os_str)`). `lib/terraform/image/gcp/windows/` currently
+  ships only a `.keep` file — no `main.tf` exists. To keep this from
+  surfacing as a confusing `terraform init` failure, `TerraformBuilder#run`
+  calls `assert_template_present!(os_str)` for every populated OS bucket
+  before any working-dir or Terraform work, raising
+  `ImageBuilder::MissingTemplateError` with the missing path and a
+  pointer to `--no-#{os_str}`. Authoring the Windows `main.tf` is
+  tracked separately in [RFC 0003](rfcs/0003-windows-image-builder-template.md).
+- Image naming: the new image is created with family
+  `<image_family>` and name `<image_family>-v<unix_ts>`.
+  `TerraformBuilder#image_name_from_image_family` enforces GCE's
+  `GCE_IMAGE_NAME_MAX = 63` cap (RFC 1035 label rules); when the
+  concatenated name would overflow, the family is clipped to fit
+  while the `-v<unix_ts>` suffix is preserved verbatim, so two
+  consecutive builds in the same family cannot collide on the
+  truncated name. Trailing dashes from a clipped family are stripped
+  before the suffix is appended (GCE rejects names ending in `-`).
+  The previous implementation used `"…-v#{ts}"[0..64]`, an inclusive
+  range that allowed up to 65 characters and could land mid-timestamp;
+  see [RFC 0004](rfcs/0004-image-name-truncation-off-by-one.md). Old
+  `READY` images in the same family are deprecated with a 1-day grace
+  period before deletion.
+- `gcloud` execution is encapsulated in
+  `ImageBuilder::Exec::Gcloud`. `Gcloud#run` shells out via
+  `Open3.capture3`, appends `--format=json`, and parses the output.
+  Construction-time validation is a separate `verify_gcloud!` call
+  that just runs `system('gcloud --version')` (not Open3) and raises
+  if it returns non-true.
+
+### CLI flags for the image builder
+
+- `--dry-run` — log the tfvars and exit.
+- `--no-build-images` — apply Terraform but do not create images
+  (helpful for debugging the provisioner step).
+- `--provision-only` — `--no-build-images` + `--no-destroy-nodes`.
+- `--no-linux` / `--no-windows` — skip the corresponding OS bucket.
+- `-F / --filter REGEX` — applied to image keys via the `load_hook`
+  in `Config::CemAcptImage`.
+
+## 13. Windows path
+
+`cem_acpt`'s Windows flow is a hybrid of Terraform (just to provision
+the instance) and Ruby/WinRM (everything else):
+
+- `lib/terraform/gcp/windows/main.tf` creates the instance and pins a
+  hard-coded service account
+  (`cem-windows-acpt-test@team-sse.iam.gserviceaccount.com`, scope
+  `cloud-platform`). The Linux template (`lib/terraform/gcp/linux/main.tf`)
+  has no `service_account` block at all — this is a Windows-only
+  detail, not a symmetric platform feature. The Windows template
+  defines no `remote-exec` or `file` provisioners; the
+  `username`/`private_key`/`public_key` vars exist as stubs only.
+- After Terraform reports back IPs, the runner partitions the
+  configured `tests:` by `Provision::OsData.os_family_for` (which
+  consults `Linux.use_for?` / `Windows.use_for?` rather than substring
+  matching). A mixed Linux + Windows list raises early; an all-Windows
+  list takes the Windows branch and:
+  1. Uploads the Puppet module tarball to `gs://<windows_bucket>/<uuid>`
+     via `gcloud storage cp`. The bucket name comes from
+     `platform.gcp.windows_bucket` (default: `win_cem_acpt`) and can be
+     overridden via the `--windows-bucket` CLI flag, the
+     `CEM_ACPT_PLATFORM__GCP__WINDOWS_BUCKET` env var, or a config file.
+     The same bucket URI is threaded into `WinNode` so the in-instance
+     `gcloud storage cp` step uses the configured bucket as well.
+  2. For each instance, runs
+     `Utils.get_windows_login_info(name, ip_hash)` which polls
+     `gcloud compute reset-windows-password` until the instance is ready
+     (max 60 × 10s = 10 minutes), then parses out the username/password.
+  3. Constructs a `Utils::WinRMRunner::WinNode` per instance and
+     `run`s it, which opens an SSL WinRM session and issues PowerShell
+     commands to: enable long paths, install Puppet, fetch the module
+     tarball, install Goss (alpha Windows build), install NSSM, register
+     three NSSM-managed Goss services on ports 8080/8081/8082, open
+     firewall holes, and finally `puppet apply` the manifest.
+- After the test, `cleanup_bucket` removes the uploaded tarball.
+
+This duplication of Linux-side provisioning logic in PowerShell is
+intentional and called out in [`README.md#Testing-with-sce_windows`](../README.md#testing-with-sce_windows),
+but it does mean the Windows path is sensitive to the specific
+versions hardcoded in `winrm_runner.rb`
+(`puppet-agent-7.25.0-x64.msi`, `goss v0.3.23`, `nssm-2.24-101-g897c7ad`).
+NSSM is required because Goss's executable cannot register as a
+Windows service directly.
+
+## 14. Cross-cutting utilities
+
+`lib/cem_acpt/utils/`:
+
+- **`shell.rb`** — `Utils::Shell.run_cmd` (Open3-based, streams
+  stdout/stderr to a logger via `Output#<<`, optional combine), plus
+  `Utils::Shell.which` (mimics `which(1)` and skips Ruby bin dirs by
+  default to avoid `bundle exec` confusion). Defines
+  `ShellCommandError` / `ShellCommandNotFoundError`.
+- **`ssh.rb`** — `SSH::Keygen` (wraps `ssh-keygen` with defaults
+  `ed25519` / 100 rounds / 4096 bits — note that `-b 4096` is silently
+  ignored by `ssh-keygen` when the key type is `ed25519`, since
+  ed25519 keys are a fixed size; the `-b` flag is effectively a no-op
+  unless the type is overridden) plus `SSH::Ephemeral`, the
+  create/clean entry points used by the runner. Setting
+  `CEM_ACPT_SSH_PRI_KEY` in the environment short-circuits ephemeral
+  generation.
+- **`puppet.rb`** — `Utils::Puppet::ModulePackageBuilder`. Wraps
+  `Puppet::Modulebuilder::Builder` for normal modules; for modules
+  whose metadata `name` includes `windows`, falls back to a manual
+  `tar -czf`. The builder validates module metadata at construction
+  time (so a malformed `metadata.json` fails before any cloud work).
+- **`files.rb`** — `Utils::Files.{read,write,delete}` dispatch on
+  file extension to a `YamlUtil`/`JsonUtil`/`FileUtil` subclass.
+  Reads are mtime-cached in a process-local registry to avoid
+  re-reading unchanged files inside loops.
+- **`finalizer_queue.rb`** — `Queue → frozen Array` once-only
+  conversion used by `Bolt::SummaryResults` to express "all results
+  collected, now interrogate the aggregate".
+- **`terminal.rb`** — a 1Hz "..." spinner thread used in CI mode by
+  the image builder so GitHub Actions doesn't kill the job for
+  inactivity.
+- **`winrm_runner.rb`** — see §13.
+
+`lib/cem_acpt/utils.rb` itself adds a couple of GCP-specific helpers
+(`reset_password_readiness_polling`, `get_windows_login_info`).
+
+`lib/cem_acpt/core_ext.rb` defines two refinements:
+
+- `ExtendedHash` — `format!` (recursively symbolize keys),
+  `dot_dig`/`dget`, `dot_store`/`dset`, `has?`/`dhas?`. These power
+  the entire `Config::Base#get('a.b.c')` API.
+- `ExtendedArray` — `split_into_groups(n)` used by Bolt's threaded
+  test runner.
+
+Refinements must be activated per-file with `using
+CemAcpt::CoreExt::ExtendedHash` / `ExtendedArray`.
+
+## 15. Logging
+
+`lib/cem_acpt/logging.rb` defines:
+
+- **`Logger < ::Logger`** — overrides `info|debug|warn|error|fatal` so
+  that, in CI mode, log lines are emitted as
+  `::notice::…` / `::warning::…` / `::error::…` GitHub Actions
+  annotations via `<<`. In trap context (after SIGINT) it bypasses
+  the standard `Logger` codepath (which uses a Mutex and would
+  deadlock) and writes directly to the raw logdev.
+  `start_ci_group` / `end_ci_group` emit `::group::` / `::endgroup::`.
+- **`MultiLogger`** — fan-out delegator; methods are forwarded to all
+  underlying loggers if every one of them responds. Used by
+  `CemAcpt#initialize_logger!` to log to both `$stdout` and a
+  `--log-file FILE` simultaneously.
+- **module-level `Logging.logger`** — global accessor. Including
+  `CemAcpt::Logging` in any class adds both an instance-level and
+  class-level `logger` method.
+
+`-D / --debug` sets `log_level = 'debug'`. `-v / --verbose` enables
+the custom `verbose` severity (debug-level message gated by a
+`@verbose` flag — quieter than `--debug` but louder than `info`).
+
+`-q / --quiet` drops `$stdout` from the logger's destinations. Reading
+`cem_acpt.rb#initialize_logger!` (per RFC 0007):
+
+- `--quiet` *with* `--log-file FILE`: stdout is dropped, log lines go
+  only to `FILE`.
+- `--quiet` *without* `--log-file` *outside CI*: refused at startup
+  with a `RuntimeError` —
+  `--quiet without --log-file would silence all output; pass --log-file or drop --quiet`.
+  This is deliberate; the previous behavior silently kept stdout and
+  read as a no-op.
+- CI mode (`GITHUB_ACTIONS`, `CI`, or `-I`): `$stdout` is forcibly
+  re-added to `logdevs` if `--quiet` would have dropped it. A single
+  `warn`-level line is emitted noting the override. This is intentional
+  — Actions needs stdout for `::group::` / `::notice::` directives —
+  but it does mean `--quiet` is partially overridden under CI.
+
+## 16. On-disk state
+
+cem_acpt creates and uses a user-config directory at `~/.cem_acpt/`:
+
+```
+~/.cem_acpt/
+├── config.yaml                    # optional user-supplied config
+├── terraform_checksum.txt         # sha256(version + tree of lib/terraform/)
+└── terraform/                     # copy of lib/terraform/ from the gem
+    ├── gcp/
+    │   ├── linux/                 # provisioning template(s) for tests
+    │   └── windows/
+    └── image/
+        └── gcp/
+            ├── linux/             # provisioning template(s) for image-build
+            └── windows/
+```
+
+`Config::Base#create_terraform_dir!` is responsible for keeping
+`~/.cem_acpt/terraform/` in sync with the version of the gem
+currently in use. It computes a SHA-256 over (a) `CemAcpt::VERSION` and
+(b) every file/directory name under `lib/terraform/`. If the recorded
+checksum differs from the current one (or doesn't exist), it
+`rm_rf`s the on-disk copy and re-copies. The version is mixed into the
+hash so a `gem install cem_acpt -v X.Y.Z` of the same source always
+forces a refresh.
+
+Per-run state is created under `~/.cem_acpt/terraform/`:
+
+- Test runs: `~/.cem_acpt/terraform/test_<unix_ts>/`
+- Image builds: `~/.cem_acpt/terraform/image/<platform>/image_builder_<unix_ts>/`
+
+These directories are removed by `Provision::Terraform#destroy` /
+the image builder's `terraform_destroy` step unless
+`--no-destroy-nodes` is set, in which case the user is responsible for
+cleaning them up. Ephemeral SSH keys live in `~/.ssh/acpt_test_key{,.pub}`
+and are deleted on a successful destroy.
+
+## 17. Test suite
+
+The repo's own RSpec suite lives under `spec/` and mirrors `lib/`:
+
+- `spec/cem_acpt_spec.rb` — top-level smoke tests.
+- `spec/cem_acpt/test_runner_spec.rb`
+- `spec/cem_acpt/bolt_spec.rb`,
+  `spec/cem_acpt/bolt/summary_results_spec.rb`,
+  `spec/cem_acpt/bolt/cmd/{task_run_spec,task_show_spec,output_spec}.rb`,
+  `spec/cem_acpt/bolt/tests/{test_spec,testlist_spec}.rb`
+- `spec/cem_acpt/config/cem_acpt_spec.rb`
+- `spec/cem_acpt/platform/gcp_spec.rb`
+- `spec/cem_acpt/provision/terraform/terraform_cmd_spec.rb`
+- `spec/cem_acpt/test_runner/log_formatter/goss_action_response_spec.rb`
+- `spec/fixtures/` — sample Goss/Bolt JSON output, sample config
+  YAMLs, and a `config_testing/` tree that mimics a `~/.cem_acpt/`
+  directory for the config-merge tests.
+
+Conventions per `CLAUDE.md` and `cem_acpt.gemspec`:
+
+- Ruby 3.0+ runtime; RuboCop targets Ruby 3.2.
+- Document Ruby with YARD comments.
+- All changes ship with tests.
+
+These are *self-tests*. The acceptance tests under
+`spec/acceptance/` referenced throughout this doc live in the
+**consuming module's** repo (e.g. `sce_linux`), not here.
+
+## 18. External dependencies
+
+### Runtime gems
+
+| Gem                  | Version     | Used by                                    |
+|----------------------|-------------|--------------------------------------------|
+| `async-http`         | `~> 0.6x`   | Goss action group (parallel HTTP GETs)     |
+| `bcrypt_pbkdf`       | `~> 1.x`    | (transitive — for `winrm`/`ed25519`)       |
+| `deep_merge`         | `~> 1.x`    | `Config::Base#load`                        |
+| `dotenv`             | `~> 3.x`    | `exe/cem_acpt*` boot                       |
+| `ed25519`            | `~> 1.x`    | (transitive)                               |
+| `puppet-modulebuilder` | `>= 0.0.1`| `Utils::Puppet::ModulePackageBuilder`      |
+| `winrm`              | `~> 2.x`    | `Utils::WinRMRunner`                       |
+
+### External binaries
+
+| Binary       | Required for                | Discovered via             |
+|--------------|-----------------------------|----------------------------|
+| `terraform`  | All provisioning            | `Utils::Shell.which`       |
+| `gcloud`     | GCP platform / image builder| `verify_gcloud!`, shell-out|
+| `ssh-keygen` | Ephemeral SSH keys          | `Utils::Shell.which`       |
+| `bolt`       | Bolt action (optional)      | `Utils::Shell.which` (intended-graceful, currently broken — see §19) |
+
+### Stdlib / Ruby version
+
+- Requires Ruby `>= 3.0.0` (gemspec) and is developed against 3.2.
+- Uses `Async`/`Async::Barrier`/`Async::HTTP::Internet`,
+  `Open3.popen3`, `IO.select`, `Queue`, `Mutex`, `Thread`, `TracePoint`,
+  `WEBrick` (only on the test node, in `log_service.rb`).
+
+## 19. Open questions / observed dead code
+
+These are things the exploration surfaced that don't seem load-bearing
+in the current code but would warrant a quick decision before
+spec-driven refactors.
+
+1. **`provisioner` is statically forced to `'terraform'`** in
+   `Config::Base#add_static_options!`, even though the `Provision`
+   factory branches on it. If we want a non-Terraform path in the
+   future the static set would need to become a default.
+2. **Platform constant cache.** `Platform.platform_class` caches the
+   created class under `CemAcpt::Platform` (e.g.
+   `CemAcpt::Platform::Gcp`) and uses `const_defined?(name, false)`,
+   so unrelated same-named constants elsewhere in the graph cannot
+   collide. Mixins live alongside under `CemAcpt::Platform::Mixin`.
+   Resolved by [CEM-6717](rfcs/0008-namespace-platform-classes.md).
+3. **`lib/terraform/image/gcp/windows/` is an empty directory.** It
+   contains only `.keep` — no `main.tf`. As of the fix for
+   [CEM-6712](rfcs/0003-windows-image-builder-template.md),
+   `TerraformBuilder#assert_template_present!` raises
+   `ImageBuilder::MissingTemplateError` early with a clear, actionable
+   message naming the missing path and pointing at `--no-windows`,
+   instead of letting `terraform init` fail with "no configuration
+   files". Shipping an actual Windows `main.tf` is the long-term half
+   of RFC 0003 and remains open.
+
+If any of these are intentional ("yes, that's load-bearing because
+…") we should annotate them in the code comments rather than rely on
+oral history.