From 3b28f877efa145b2f2f9200a0033633f43d95c63 Mon Sep 17 00:00:00 2001
From: "anthony.wen" <awen01@gmail.com>
Date: Fri, 27 Mar 2026 12:30:31 -0400
Subject: [PATCH] Refine explicit-VM blacklist handling for ATVM runs

---
 atvm/AGENTS.md                        | 2 ++
 atvm/docs/automation/guide.md         | 4 +++-
 atvm/docs/automation/run-learnings.md | 8 ++++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/atvm/AGENTS.md b/atvm/AGENTS.md
index 89030fc..a0fb782 100644
--- a/atvm/AGENTS.md
+++ b/atvm/AGENTS.md
@@ -52,6 +52,8 @@ This file defines how to operate and maintain the ATVM workspace in `/home/aw/co
 - Default plugin: `--use_specified_plugin iscsi`
 - Always include `--ignore_force_shutdown` unless explicitly told not to.
 - Default config family: `gold`
+- Do not auto-add the maintained `--exclude_partial_match` blacklist when the operator explicitly targets named VMs with `--specify_vms`.
+- Even for explicit `--specify_vms` requests, first check whether any requested VM is on the maintained blacklist and stop if it is.
 
 ## Required Operating Rules
 - Never run setup without operator-provided `--expected-ip` and `--expected-hostname`.
diff --git a/atvm/docs/automation/guide.md b/atvm/docs/automation/guide.md
index 69a3acf..ac788a3 100644
--- a/atvm/docs/automation/guide.md
+++ b/atvm/docs/automation/guide.md
@@ -125,7 +125,9 @@ python3 ./run-sorry-cypress.py --config_file <config-file> --build_name <hyphena
   - `--vm_platforms vmware|ovirt|openshift|proxmox`
 
 ## Blacklisted Machines
-Always exclude these machines from ATVM automation runs by adding them to `--exclude_partial_match`.
+Always exclude these machines from broad-scope ATVM automation runs by adding them to `--exclude_partial_match`.
+If the operator explicitly targets one or more named VMs with `--specify_vms`, do not add the maintained `--exclude_partial_match` list unless the operator also explicitly asks for it.
+Even for explicit `--specify_vms` requests, first check whether any requested VM is on the maintained blacklist and stop instead of launching the run if one is included.
 
 Permanently blacklisted because CMC cannot compile:
 - `atvm6-centos6.0`
diff --git a/atvm/docs/automation/run-learnings.md b/atvm/docs/automation/run-learnings.md
index 886b570..da073fc 100644
--- a/atvm/docs/automation/run-learnings.md
+++ b/atvm/docs/automation/run-learnings.md
@@ -266,3 +266,11 @@ This file stores run-specific examples only when a run produced a new learning r
 - Action for future runs:
   - Treat `approve` as approval to run and start the watcher.
   - Treat `approve without watcher` as approval to run without starting the watcher.
+
+## Run Learning: 2026-03-27 (Do not auto-add blacklist excludes for explicitly specified VMs)
+- Observed requirement:
+  - When the operator explicitly specifies the VM or VM list to run, they do not want the maintained `--exclude_partial_match` blacklist added automatically.
+- Action for future runs:
+  - Keep the maintained `--exclude_partial_match` list for broad selectors such as `--containsVm` or `--randomize`.
+  - When the operator uses `--specify_vms`, do not auto-add the blacklist unless they explicitly request it.
+  - Even when the operator uses `--specify_vms`, first check whether any requested VM is on the maintained blacklist and stop instead of launching it if one is included.