cem_acpt 0.11.0 → 0.11.2

data/lib/cem_acpt/test_runner.rb

@@ -61,8 +61,13 @@ module CemAcpt
         @provisioned = true
         logger.info('CemAcpt::TestRunner') { 'Provisioned test nodes...' }
         logger.debug('CemAcpt::TestRunner') { "Instance names and IPs: #{@instance_names_ips}" }
-        # Verifying that we're running on windows nodes or not
-        if config.get('tests').first.include? 'windows'
+        # Classify every test in the run by OS family rather than substring-matching the first test name.
+        windows_tests, linux_tests = config.get('tests').partition do |t|
+          CemAcpt::Provision::OsData.os_family_for(t) == :windows
+        end
+        unless windows_tests.empty?
+          raise 'Mixed Windows and Linux tests in one run are not supported' unless linux_tests.empty?
+
           logger.info('CemAcpt') { 'Running on windows nodes...' }
           upload_module_to_bucket
 
@@ -71,7 +76,7 @@ module CemAcpt
             # instance_names_ips. It contains the username, password, and ip of the
             # windows node, as well as the test name that will be run on that node.
             login_info = CemAcpt::Utils.get_windows_login_info(k, v)
-            win_node = CemAcpt::Utils::WinRMRunner::WinNode.new(login_info, @run_data[:win_remote_module_name])
+            win_node = CemAcpt::Utils::WinRMRunner::WinNode.new(login_info, @run_data[:win_remote_module_name], windows_bucket_uri)
             win_node.run
           end
         end
@@ -203,9 +208,9 @@ module CemAcpt
           @bolt_test_runner = CemAcpt::Bolt::TestRunner.new(config, run_data: @run_data)
           @bolt_test_runner.setup!
         rescue CemAcpt::ShellCommandNotFoundError => e
-          logger.warning('CemAcpt::TestRunner') { e.message }
-          logger.warning('CemAcpt::TestRunner') { 'Adding Bolt action to ignore list...' }
-          CemAcpt::Actions.config.ignore << :bolt
+          logger.warn('CemAcpt::TestRunner') { e.message }
+          logger.warn('CemAcpt::TestRunner') { 'Bolt binary not found on PATH; skipping :bolt action.' }
+          CemAcpt::Actions.config.except = (CemAcpt::Actions.config.except + [:bolt]).uniq
           return
         end
         return unless @bolt_test_runner.tests.to_a.empty?
@@ -378,14 +383,22 @@ module CemAcpt
         logger.error { result.log_formatter.results.join("\n") }
       end
 
+      # Returns the configured Windows GCS bucket URI (e.g. "gs://win_cem_acpt").
+      # Raises if the bucket is unset or empty so we fail before invoking gcloud.
+      def windows_bucket_uri
+        bucket = config.get('platform.gcp.windows_bucket')
+        raise 'platform.gcp.windows_bucket is not configured' if bucket.nil? || bucket.to_s.empty?
+        "gs://#{bucket}"
+      end
+
       # Upload the cem_windows module to the bucket if we're testing the cem_windows module
       # This should only be done once per cem_acpt run. It's important to update the module_package_path
       # in the run_data to reflect the new module path if we do end up changing the module name
       def upload_module_to_bucket
         @run_data[:win_remote_module_name] = SecureRandom.uuid << File.split(@run_data[:module_package_path]).last
-        @run_data[:win_remote_module_path] = File.join('gs://win_cem_acpt', @run_data[:win_remote_module_name])
+        @run_data[:win_remote_module_path] = File.join(windows_bucket_uri, @run_data[:win_remote_module_name])
         # Upload the module from the local host to the bucket
-        logger.info('CemAcpt') { "Uploading #{@run_data[:module_pakage_path]} to #{@run_data[:win_remote_module_path]}..." }
+        logger.info('CemAcpt') { "Uploading #{@run_data[:module_package_path]} to #{@run_data[:win_remote_module_path]}..." }
         CemAcpt::Utils::Shell.run_cmd("gcloud storage cp #{@run_data[:module_package_path]} #{@run_data[:win_remote_module_path]}")
         logger.debug('CemAcpt') { 'Successfully uploaded module' }
       end

data/lib/cem_acpt/utils/winrm_runner.rb

@@ -36,11 +36,12 @@ module CemAcpt
       class WinNode
         include CemAcpt::Logging
 
-        attr_reader :mod_name
+        attr_reader :mod_name, :bucket_uri
 
-        def initialize(login_info, mod_name)
+        def initialize(login_info, mod_name, bucket_uri)
           @login_info = login_info
           @mod_name = mod_name
+          @bucket_uri = bucket_uri
         end
 
         def run_winrm
@@ -80,7 +81,7 @@ module CemAcpt
               logger.debug('CemAcpt') { 'Creating cem_acpt directory and downloading necessary files...' }
               winrm_runner.run("mkdir C:\\cem_acpt")
               # Download the cem_windows module from the bucket to cem_acpt directory
-              winrm_runner.run("gcloud storage cp gs://win_cem_acpt/#{@mod_name} C:\\cem_acpt")
+              winrm_runner.run("gcloud storage cp #{@bucket_uri}/#{@mod_name} C:\\cem_acpt")
               # Install the cem_windows module
               logger.info('CemAcpt') { 'Installing cem_windows module...' }
               winrm_runner.run("Start-Process -FilePath 'C:\\Program Files\\Puppet Labs\\Puppet\\bin\\puppet.bat' -ArgumentList 'module install C:\\cem_acpt\\#{@mod_name}' -Wait -NoNewWindow")

data/lib/cem_acpt/utils.rb

@@ -13,18 +13,6 @@ module CemAcpt
     class << self
       include CemAcpt::Logging
 
-      # This is method currently unused, see lib/cem_acpt/utils/puppet.rb for details.
-      def package_win_module(module_dir)
-        # Path to the package file
-        package_file = File.join(module_dir, 'puppetlabs-cem_windows.tar.gz')
-
-        # Remove the old package file if it exists
-        FileUtils.rm_f(package_file)
-        `cd #{module_dir} && touch puppetlabs-cem_windows.tar.gz && tar -czf puppetlabs-cem_windows.tar.gz --exclude=puppetlabs-cem_windows.tar.gz *`
-        logger.info('CemAcpt') { "Windows module packaged at #{package_file}" }
-        package_file
-      end
-
       def reset_password_readiness_polling(instance_name)
         attempts = 0
         last_error = nil

data/lib/cem_acpt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CemAcpt
-  VERSION = '0.11.0'
+  VERSION = '0.11.2'
 end

data/lib/cem_acpt.rb

@@ -56,26 +56,38 @@ module CemAcpt
       CemAcpt::TestRunner::Runner.new(@config)
     end
 
+    # Build the logger destinations from `--quiet`, `--log-file`, and CI mode.
+    # See docs/rfcs/0007-logging-quiet-and-typos.md for the matrix.
     def initialize_logger!
       raise 'Config must be loaded before logger can be initialized' if config.nil? || config.empty?
 
       log_formatter = config.get('log_format')&.to_sym || :text
-      logdevs = [$stdout]
-      # If log_file is set, and quiet is set, only log to the file
-      if config.get('log_file') && config.get('quiet')
-        logdevs = [config.get('log_file')]
-      elsif config.get('log_file') && !config.get('quiet')
-        logdevs << config.get('log_file')
-      end
+      quiet = !!config.get('quiet')
+      log_file = config.get('log_file')
+
+      logdevs = []
+      logdevs << $stdout unless quiet
+      logdevs << log_file if log_file
+
+      ci_override = false
       if config.ci_mode? && !logdevs.include?($stdout)
         logdevs << $stdout
+        ci_override = quiet
       end
+
+      if logdevs.empty?
+        raise '--quiet without --log-file would silence all output; pass --log-file or drop --quiet'
+      end
+
       new_log = new_logger(
         *logdevs,
         level: config.get('log_level'),
         formatter: log_formatter,
       )
       new_log.set_verbose(!!config.get('verbose'))
+      if ci_override
+        new_log.warn('CemAcpt') { '--quiet is overridden in CI mode; logging to stdout for ::group:: support' }
+      end
       new_log
     end
 

data/lib/terraform/gcp/linux/main.tf

@@ -189,7 +189,12 @@ resource "google_compute_instance" "acpt-test-node" {
   }
 
   metadata = {
-    "enable-oslogin" = "TRUE"
+    # Keep OSLogin disabled on test instances. The metadata "ssh-keys" entry
+    # below is what cem_acpt relies on for SSH auth (terraform's remote-exec
+    # provisioner connects with the ephemeral key generated per run). With
+    # enable-oslogin=TRUE, GCP ignores the metadata "ssh-keys" entry, and we
+    # currently have no plumbing for OSLogin key registration.
+    "enable-oslogin" = "FALSE"
     "ssh-keys"       = "${var.username}:${file(var.public_key)}"
     "cem-acpt-test"  = each.value.test_name
   }

data/lib/terraform/image/gcp/linux/main.tf

@@ -116,7 +116,14 @@ resource "google_compute_instance" "acpt-test-node" {
   }
 
   metadata = {
-    "enable-oslogin"   = "TRUE"
+    # Keep OSLogin disabled on the throwaway build instance. The metadata
+    # "ssh-keys" entry below is what terraform's remote-exec provisioner
+    # uses for SSH auth (with the ephemeral key generated per run). With
+    # enable-oslogin=TRUE, GCP ignores the metadata "ssh-keys" entry, and
+    # we have no plumbing for OSLogin key registration. The build instance
+    # is destroyed immediately after the disk is snapshotted, so disabling
+    # OSLogin here only affects the throwaway VM, not the resulting image.
+    "enable-oslogin"   = "FALSE"
     "ssh-keys"         = "${var.username}:${file(var.public_key)}"
     "for-image-family" = each.value.image_family
   }

data/specifications/CEM-6713.md

@@ -0,0 +1,165 @@
+# CEM-6713 — Fix image-name truncation off-by-one
+
+## Background
+
+`ImageBuilder::TerraformBuilder#image_name_from_image_family`
+(`lib/cem_acpt/image_builder.rb:114-116`) currently does:
+
+```ruby
+def image_name_from_image_family(image_family)
+  "#{image_family}-v#{@start_time.to_i}"[0..64]
+end
+```
+
+`String#[0..64]` is **inclusive** on both ends and returns up to 65
+characters. GCE image names are limited to 63 characters per RFC 1035
+label rules, and must match `[a-z]([-a-z0-9]*[a-z0-9])?`. So the
+current code:
+
+1. Allows names of up to 65 chars, which GCE rejects with no clear
+   error path back to the user.
+2. When it does truncate, the cut can land mid-timestamp or on the
+   `-v` separator, allowing two consecutive builds in the same family
+   to collide on the truncated name.
+
+This work is the implementation half of
+[RFC 0004](../docs/rfcs/0004-image-name-truncation-off-by-one.md).
+
+## Functional behavior
+
+`image_name_from_image_family` will produce a string that is
+GCE-name-safe by construction:
+
+- **Length ≤ 63 characters.**
+- **Suffix `-v<unix_timestamp>` is preserved verbatim.** Two
+  consecutive builds in the same family always differ in the
+  timestamp portion, regardless of how long the family is.
+- **No trailing dash.** When the prefix has to be clipped and the
+  clip lands on a `-`, trailing dashes are stripped before the suffix
+  is appended.
+
+### Method signature (unchanged)
+
+```ruby
+# @param image_family [String] the GCE image family
+# @return [String] the GCE-safe image name, ≤ 63 chars,
+#   with the timestamp suffix preserved
+def image_name_from_image_family(image_family)
+```
+
+### Implementation sketch
+
+```ruby
+GCE_IMAGE_NAME_MAX = 63
+
+def image_name_from_image_family(image_family)
+  suffix = "-v#{@start_time.to_i}"
+  full = "#{image_family}#{suffix}"
+  return full if full.length <= GCE_IMAGE_NAME_MAX
+
+  prefix = image_family[0, GCE_IMAGE_NAME_MAX - suffix.length]
+  prefix.sub(/-+\z/, '') + suffix
+end
+```
+
+The constant lives on `TerraformBuilder` next to
+`DEFAULT_PLAN_NAME` / `DEFAULT_VARS_FILE`.
+
+## Input / output contract
+
+| Input `image_family` length | `@start_time.to_i` length | Expected output                           |
+| --------------------------- | ------------------------- | ----------------------------------------- |
+| 5 (`rhel9`)                 | 10                        | `"rhel9-v<ts>"` (17 chars, unchanged)     |
+| Any value ≤ 63 chars total  | —                         | unchanged                                 |
+| 64 chars total              | —                         | family clipped by 1, suffix intact        |
+| Family clip ends in `-`     | —                         | trailing `-` stripped, suffix intact      |
+
+`@start_time` is a `Time` set at the start of `run`. Callers
+(`run` → `create_image_from_disk`) already only invoke this method
+during a build, so `@start_time` is non-nil when this method runs.
+
+## Edge cases
+
+1. **Short family** — `image_family.length + suffix.length <= 63`:
+   return concatenation unchanged.
+2. **Exactly 63 chars** — returned unchanged (no truncation).
+3. **64 chars (one over)** — clip the family to fit; suffix is
+   preserved.
+4. **Family ends in dashes after clipping** — strip *all* trailing
+   dashes from the clipped prefix before appending the suffix. (The
+   suffix begins with `-v…` so the result still has exactly one `-`
+   between the clipped family and the `v`.)
+5. **Family long enough that clipping reduces it to nothing** — not a
+   realistic case (`@start_time.to_i` is 10 digits, suffix is 12
+   chars, leaving 51 chars of family room), but the implementation
+   tolerates it: `String#[0, 0]` returns `""`, `sub` is a no-op, and
+   the result is just the suffix. We are not adding explicit
+   handling for this; if it ever fires, GCE will reject (name must
+   start with a letter) and the failure surfaces normally.
+
+## Constraints / invariants
+
+- The suffix `-v<ts>` must always appear literally at the end of the
+  returned name.
+- The returned name's length is always ≤ 63.
+- The returned name never ends in `-`.
+- No other call sites in the codebase grep for `image_name_from_image_family`,
+  so the contract change is local to this method.
+
+## Error handling
+
+No new exceptions. The method is pure-string, no I/O, no Terraform
+or GCE calls. Existing callers (`create_image_from_disk`) handle
+GCE errors at their own layer.
+
+## Tests
+
+Add to `spec/cem_acpt/image_builder_spec.rb`:
+
+- A `describe '#image_name_from_image_family'` block that builds a
+  `TerraformBuilder` instance, sets `@start_time` via
+  `instance_variable_set`, and exercises:
+  1. Short family: result equals `"<family>-v<ts>"` and is unchanged.
+  2. Exact 63-char total: result unchanged, length 63.
+  3. 64-char total (one over): result is exactly 63 chars, ends in
+     the full `-v<ts>` suffix, family portion is one shorter.
+  4. Prefix-ending-in-dash: family chosen so the clip lands on `-`
+     (or `--`); result has no trailing dash before the suffix and
+     length ≤ 63.
+
+Tests use a fixed `@start_time` (e.g.
+`Time.utc(2026, 5, 4, 12, 0, 0)`) so timestamp digits are
+deterministic.
+
+## Documentation
+
+- Update `docs/ARCHITECTURE.md` §12 — replace the off-by-one note
+  (current lines 757-762) with a description of the new bounded
+  behavior, referencing `GCE_IMAGE_NAME_MAX` and the suffix-preserving
+  rule.
+- Update `docs/rfcs/0004-image-name-truncation-off-by-one.md` to
+  flip status from `Proposed` to `Implemented` and append an
+  "Implementation" note linking to the commit / PR.
+
+## Non-goals
+
+- Refusing to build when the family alone exceeds 63 chars
+  (alternative listed in the RFC) — out of scope.
+- Hashing-based naming — out of scope.
+- Refactoring the `TerraformBuilder` ↔ `Provision::Terraform`
+  duplication — out of scope; that is its own follow-up.
+- Adding validation for the `[a-z]([-a-z0-9]*[a-z0-9])?` regex —
+  the existing code does not validate the family characters, and
+  this ticket is scoped to the length / off-by-one issue.
+
+## Acceptance criteria
+
+- [ ] `image_name_from_image_family` enforces a 63-char cap.
+- [ ] Generated names never end in `-`.
+- [ ] The `-v<ts>` suffix is preserved intact.
+- [ ] RSpec coverage for: short, exact-63, 64-overflow,
+      prefix-ending-in-dash.
+- [ ] `bundle exec rake spec` passes.
+- [ ] `rubocop` is clean on touched files.
+- [ ] `docs/ARCHITECTURE.md` §12 updated.
+- [ ] RFC 0004 status updated to `Implemented`.

data/specifications/CEM-6714.md

@@ -0,0 +1,271 @@
+# CEM-6714 — Replace `tests.first.include?('windows')` with explicit OS dispatch
+
+## Background
+
+`TestRunner::Runner#run` (`lib/cem_acpt/test_runner.rb:65`) currently
+decides whether to take the Windows branch with:
+
+```ruby
+if config.get('tests').first.include? 'windows'
+  upload_module_to_bucket
+  @instance_names_ips.each { |k, v| ... WinRMRunner ... }
+end
+```
+
+This is a substring match against an arbitrary test name. It:
+
+1. Misroutes any test whose name happens to contain the substring
+   `windows` (e.g. `cis_rhel-8_firewalld_windowserver_2`).
+2. Only inspects the first test, so a mixed-OS run silently
+   mishandles every test after the first.
+3. Couples the runner's OS dispatch to test-name spelling.
+4. Duplicates logic already owned by `Provision::OsData`. The
+   provisioner already classifies the run via
+   `Linux.use_for?` / `Windows.use_for?` (`lib/cem_acpt/provision/terraform.rb:184-188`).
+
+This work is the implementation half of
+[RFC 0005](../docs/rfcs/0005-os-dispatch-replace-windows-heuristic.md).
+
+## Functional behavior
+
+Add a single classification helper to `Provision::OsData`, and have
+the runner consume it.
+
+### `Provision::OsData.os_family_for(test_name)`
+
+A new module-level method on `CemAcpt::Provision::OsData`:
+
+```ruby
+# @param test_name [String]
+# @return [Symbol] :linux or :windows
+# @raise [CemAcpt::Provision::OsData::UnknownOsFamilyError] if the
+#   test_name does not match any known Linux or Windows OS / version.
+def self.os_family_for(test_name)
+  return :windows if CemAcpt::Provision::Windows.use_for?(test_name)
+  return :linux if CemAcpt::Provision::Linux.use_for?(test_name)
+
+  raise UnknownOsFamilyError, ...
+end
+```
+
+`UnknownOsFamilyError < StandardError` is defined inside `OsData` and
+its message names the test_name plus the valid OS/version sets — same
+information that `Provision::Terraform#new_backend` raises today, so
+preflight failures are at least as informative as today's
+provisioner-time failures.
+
+`Provision::Terraform#new_backend` will be refactored to delegate to
+`os_family_for` so the two callers cannot drift. The error class
+raised there changes from `ArgumentError` to
+`OsData::UnknownOsFamilyError`. No callers of `new_backend` rescue
+`ArgumentError` specifically (verified by grep), so this is a
+behavior-preserving narrowing.
+
+### Runner change
+
+`TestRunner::Runner#run` replaces the `if … include? 'windows'`
+block with:
+
+```ruby
+windows_tests, linux_tests = config.get('tests').partition do |t|
+  CemAcpt::Provision::OsData.os_family_for(t) == :windows
+end
+
+unless windows_tests.empty?
+  raise 'Mixed Windows and Linux tests in one run are not supported' \
+    unless linux_tests.empty?
+
+  logger.info('CemAcpt') { 'Running on windows nodes...' }
+  upload_module_to_bucket
+  @instance_names_ips.each do |k, v|
+    login_info = CemAcpt::Utils.get_windows_login_info(k, v)
+    win_node = CemAcpt::Utils::WinRMRunner::WinNode.new(
+      login_info, @run_data[:win_remote_module_name],
+    )
+    win_node.run
+  end
+end
+```
+
+Two behavior consequences:
+
+- A test name that doesn't match either Linux or Windows now fails
+  fast at preflight (via `os_family_for`) instead of later in
+  `Provision::Terraform#new_backend`. RFC 0005 calls this out as
+  desired.
+- A mixed-OS `tests:` list now raises a clear error instead of
+  silently treating tests after the first as Linux. This is the
+  desired behavior.
+
+## Input / output contract
+
+### `OsData.os_family_for`
+
+| Input `test_name`                          | Output                          |
+|--------------------------------------------|---------------------------------|
+| `'cis_windows-2022_…'`                     | `:windows`                      |
+| `'cis_rhel-8_firewalld_server_2'`          | `:linux`                        |
+| `'cis_rhel-8_firewalld_windowserver_2'`    | `:linux` (substring trap fixed) |
+| `'cis_freebsd-14_…'` (unknown OS)          | raises `UnknownOsFamilyError`   |
+| `'malformed name with no version'`         | raises `UnknownOsFamilyError`   |
+
+The method does no I/O and is pure with respect to `Linux.valid_names`,
+`Linux.valid_versions`, `Windows.valid_names`, `Windows.valid_versions`.
+
+### Runner
+
+| `tests:` list                                | Behavior                                                |
+|----------------------------------------------|---------------------------------------------------------|
+| All Linux test names                         | Skip Windows branch, run as today.                      |
+| All Windows test names                       | Take Windows branch, upload module + WinRM each instance.|
+| Mixed Linux + Windows                        | Raise `'Mixed Windows and Linux tests in one run are not supported'` from `#run`; `rescue StandardError` records it as a result and `clean_up` runs as today. |
+| Any test name not matching any known OS      | Raises `OsData::UnknownOsFamilyError`; same rescue path.|
+
+## Constraints / invariants
+
+- The dispatch decision in `TestRunner::Runner` and
+  `Provision::Terraform` MUST come from the same source of truth
+  (`OsData.os_family_for`).
+- `OsData.os_family_for` MUST NOT do substring matching against the
+  test name; it goes through `use_for?`, which already anchors with
+  the `^prefix_osname-version` regex.
+- The runner MUST classify every test name in the list, not just the
+  first.
+- Both new and pre-existing failure modes route through the runner's
+  existing `rescue StandardError` and `ensure clean_up`, so resource
+  cleanup is unchanged.
+
+## Error handling
+
+- `OsData::UnknownOsFamilyError < StandardError` — raised by
+  `os_family_for` when neither `Linux.use_for?` nor `Windows.use_for?`
+  matches. Message format:
+
+  ```
+  Cannot determine OS family for test name: <test_name>.
+  Known OSes: linux=[...], windows=[...].
+  Known versions: linux=[...], windows=[...].
+  ```
+
+- `Provision::Terraform#new_backend` is refactored to:
+
+  ```ruby
+  case CemAcpt::Provision::OsData.os_family_for(test_name)
+  when :linux
+    CemAcpt::Provision::Linux.new(@config, @provision_data)
+  when :windows
+    CemAcpt::Provision::Windows.new(@config, @provision_data)
+  end
+  ```
+
+  An unknown test name will surface
+  `OsData::UnknownOsFamilyError` instead of `ArgumentError`. No
+  call sites in `lib/`, `exe/`, or `spec/` rescue `ArgumentError`
+  from this method, so this is a safe narrowing.
+
+- Mixed-OS run — runner raises a `RuntimeError` (plain
+  `raise '…'`) with a message that names the constraint. It is
+  caught by the existing `rescue StandardError => e` in `#run`, so
+  resource cleanup runs and the error is reported via the results
+  queue.
+
+## Non-goals
+
+- **Per-test OS dispatch** in a single `cem_acpt` invocation (i.e.
+  actually supporting a mixed list). RFC 0005 explicitly defers this
+  to a follow-up; we are only closing the obvious correctness gap.
+- Renaming or moving `Provision::Linux` / `Provision::Windows` /
+  `OsData`, or restructuring the provisioner.
+- Touching `Utils::Puppet::ModulePackageBuilder` (which uses
+  `metadata['name'].include?('windows')` for a different purpose:
+  module packaging on the local machine, not test routing).
+- Touching `spec/cem_acpt/test_runner_spec.rb`'s
+  `module_name.include?('windows')` (test fixture matcher, not
+  production logic).
+
+## Tests
+
+### New file: `spec/cem_acpt/provision/terraform/os_data_spec.rb`
+
+`describe CemAcpt::Provision::OsData` covering `.os_family_for`:
+
+1. Returns `:linux` for a representative Linux test name
+   (`'cis_rhel-8_firewalld_server_2'`).
+2. Returns `:windows` for a representative Windows test name
+   (`'cis_windows-2022_firewall_server_2'`).
+3. Returns `:linux`, not `:windows`, for the substring-trap case
+   (`'cis_rhel-8_firewalld_windowserver_2'`).
+4. Raises `UnknownOsFamilyError` for an unrecognized OS
+   (`'cis_freebsd-14_…'`).
+5. Raises `UnknownOsFamilyError` for a name that doesn't match the
+   `^\w+_(\w+)-(\d+).*` regex at all.
+
+The spec doesn't need a Config or run_data — `os_family_for` is a
+pure module method.
+
+### Update: `spec/cem_acpt/test_runner_spec.rb`
+
+Add a context that constructs a Runner with a mixed-OS `tests:`
+list and asserts the run surfaces the mixed-OS error. The cleanest
+way to test this without spinning up the full provisioning chain is
+to call the partition logic via the same path `#run` uses — which
+means we let the existing `pre_provision_test_nodes` /
+`provision_test_nodes` / `provisioner_output` stubs from the
+"successfully runs a test" test fire, then assert that
+`@results.to_a.last` is the mixed-OS error.
+
+Concretely, add inside the existing `'with a Runner object'`
+context:
+
+```ruby
+it 'records an error when tests mixes Windows and Linux' do
+  mixed_config = CemAcpt::Config::CemAcpt.new(
+    opts: { 'tests' => ['cis_windows-2022_firewall_server_2',
+                        'cis_rhel-8_firewalld_server_2'] },
+    load_user_config: false,
+  )
+  runner = CemAcpt::TestRunner::Runner.new(mixed_config)
+  allow(runner).to receive(:pre_provision_test_nodes).and_return(true)
+  allow(runner).to receive(:provision_test_nodes).and_return(true)
+  allow(runner).to receive(:provisioner_output).and_return(instance_names_ips)
+  allow(runner).to receive(:clean_up).and_return(true)
+  allow(runner).to receive(:process_test_results).and_return(true)
+  results = runner.run
+  expect(results.last).to be_a(StandardError)
+  expect(results.last.message).to match(/Mixed Windows and Linux/)
+end
+```
+
+This relies on `Runner#run`'s `rescue StandardError => e; @results << e`
+behavior, which already exists.
+
+## Documentation
+
+- `docs/ARCHITECTURE.md` §4 — replace the `if tests.first.include?('windows')`
+  bullet in the lifecycle diagram with text that describes
+  `OsData.os_family_for`-driven partition + the mixed-OS guard.
+- `docs/ARCHITECTURE.md` §13 — replace the
+  "After Terraform reports back IPs, the runner branches on
+  `tests.first.include?('windows')`" sentence with the new dispatch
+  description.
+- `docs/rfcs/0005-os-dispatch-replace-windows-heuristic.md` — flip
+  status from `Proposed` to `Implemented` and add an
+  "Implementation" note linking the commit / PR.
+
+## Acceptance criteria
+
+- [ ] `Provision::OsData.os_family_for` exists with `:linux` /
+      `:windows` return values and raises `UnknownOsFamilyError` for
+      unknown names.
+- [ ] `lib/cem_acpt/test_runner.rb` no longer references
+      `tests.first.include?` (or any other substring-on-test-name
+      heuristic) for OS dispatch.
+- [ ] `Provision::Terraform#new_backend` consumes
+      `OsData.os_family_for` rather than calling
+      `Linux.use_for?` / `Windows.use_for?` directly.
+- [ ] RSpec coverage for `os_family_for` (5 cases above) passes.
+- [ ] RSpec coverage for the runner's mixed-OS error passes.
+- [ ] `docs/ARCHITECTURE.md` §4 and §13 updated.
+- [ ] RFC 0005 status flipped to `Implemented`.
+- [ ] `bundle exec rake spec` passes.
+- [ ] `rubocop` is clean on touched files.