From 893fe35524b6f682466b3374d1fbeb44ba99937c Mon Sep 17 00:00:00 2001
From: "anthony.wen" <awen01@gmail.com>
Date: Tue, 14 Apr 2026 15:37:53 -0400
Subject: [PATCH] Clarify ATVM systemOS command defaults

---
 atvm/AGENTS.md                        | 3 ++-
 atvm/docs/automation/guide.md         | 8 +++++---
 atvm/docs/automation/run-learnings.md | 9 +++++++++
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/atvm/AGENTS.md b/atvm/AGENTS.md
index 417455a..9f21cad 100644
--- a/atvm/AGENTS.md
+++ b/atvm/AGENTS.md
@@ -49,11 +49,12 @@ This file defines how to operate and maintain the ATVM workspace in `/home/aw/co
 - Controller credential source: `/home/aw/code/cds/.env.credentials.local` via `ATVM_CONTROLLER_USER` and `ATVM_CONTROLLER_PASSWORD`
 - Detailed test artifact root on controller: `/root/cdc-e2e-cyp-12.17.4/cypress/cmcReporter`
 - Default Mattermost status destination config: `/home/aw/code/cds/.env.credentials.local`
-- Default plugin: `--use_specified_plugin iscsi`
+- Default plugin-bearing template plugin: `--use_specified_plugin iscsi`
 - Always include `--ignore_force_shutdown` unless explicitly told not to.
 - Always include `--test_partition` unless explicitly told not to.
 - For `cmc-migrateops-compute-migration` to VMware, default to `--vm_platforms vmware` and `--set_static_ip_dest` unless explicitly told otherwise.
 - Default config family: `gold`
+- Treat `cmc-systemOS` as not using plugin or integration-type arguments. Do not auto-add `--use_specified_plugin`, `--integration_type`, or watcher integration/plugin metadata for that template.
 - 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.
 
diff --git a/atvm/docs/automation/guide.md b/atvm/docs/automation/guide.md
index 48ff72a..bccbd26 100644
--- a/atvm/docs/automation/guide.md
+++ b/atvm/docs/automation/guide.md
@@ -32,7 +32,8 @@ Run ATVM CMC automation tests on the designated automation VM without unintended
 - For multiple VMs in same distro, use distro-scoped filtering (`--containsVm`) instead of long explicit VM lists.
 - Always include `--ignore_force_shutdown` on `cmc-templates.py` commands unless the operator explicitly asks not to.
 - Always include `--test_partition` on `cmc-templates.py` commands unless the operator explicitly asks not to.
-- Default to `--use_specified_plugin iscsi` unless the operator explicitly requests a different plugin.
+- Default plugin-bearing templates to `--use_specified_plugin iscsi` unless the operator explicitly requests a different plugin.
+- Do not add plugin or integration-type arguments to `cmc-systemOS`; that template should be planned without `--use_specified_plugin`, without `--integration_type`, and without watcher integration/plugin metadata.
 - For `cmc-migrateops-compute-migration` to VMware, default to `--vm_platforms vmware` and `--set_static_ip_dest` unless the operator explicitly says otherwise.
 - For `cmc-reboot`, treat `--use_specified_plugin both` as an exception case that requires an extra confirmation.
 - When `cmc-reboot` is planned with `--use_specified_plugin both`, warn that FC+iSCSI together may hit a "chicken before the egg" timing problem where iSCSI disks are not attached before mTDI / CMC services start.
@@ -137,7 +138,7 @@ Completed-run verification sequence:
 
 ## Command Pattern
 ```bash
-python3 cmc-templates.py --template <template> --ignore_force_shutdown --test_partition --config_file_path ./<config-file> --use_specified_plugin iscsi [template options or explicit plugin override...]; \
+python3 cmc-templates.py --template <template> --ignore_force_shutdown --test_partition --config_file_path ./<config-file> [template-specific plugin/integration options when that template actually uses them...]; \
 python3 ./run-sorry-cypress.py --config_file <config-file> --build_name <hyphenated-description-no-spaces> [--categorize]
 ```
 
@@ -225,7 +226,8 @@ When asked for one VM or a VM set:
 - default to a config filename containing `gold` unless the operator explicitly says otherwise,
 - always include `--ignore_force_shutdown` on the template-generation command unless the operator explicitly overrides that default,
 - always include `--test_partition` on the template-generation command unless the operator explicitly overrides that default,
-- default to `--use_specified_plugin iscsi` unless the operator explicitly requests another plugin or the template does not use plugin selection,
+- default plugin-bearing templates to `--use_specified_plugin iscsi` unless the operator explicitly requests another plugin or the template does not use plugin selection,
+- treat `cmc-systemOS` as a template that does not use plugin selection or integration-type selection, so omit `--use_specified_plugin`, omit `--integration_type`, and omit watcher integration/plugin metadata for that template,
 - use a descriptive `--build_name` without Gold Disk IDs.
 
 ## Update Rule
diff --git a/atvm/docs/automation/run-learnings.md b/atvm/docs/automation/run-learnings.md
index bd4d879..2f62527 100644
--- a/atvm/docs/automation/run-learnings.md
+++ b/atvm/docs/automation/run-learnings.md
@@ -526,3 +526,12 @@ This file stores run-specific examples only when a run produced a new learning r
   - When extracting `TEST FLOW:` from a generated spec, include common steps plus only the runtime-gated plugin branch selected for that run.
   - Use watcher metadata such as the approved integration/plugin path to decide whether to include FC steps, iSCSI steps, or both.
   - Do not count every plugin-gated branch in the generated spec just because the text is present.
+
+## Run Learning: 2026-04-14 (`cmc-systemOS` should not carry plugin or integration arguments)
+- Observed operator requirement:
+  - `cmc-systemOS` runs should not be planned with `--use_specified_plugin`, `--integration_type`, or watcher integration/plugin metadata.
+  - Treating `cmc-systemOS` like a plugin-bearing template adds incorrect command arguments and misleading status metadata.
+- Action for future runs:
+  - Plan `cmc-systemOS` template commands without plugin-selection or integration-type arguments.
+  - When watcher-backed execution is used for `cmc-systemOS`, omit watcher integration/plugin metadata too.
+  - Keep plugin defaults scoped to templates that actually use plugin selection.