From c9a908ff3de6388325bbae6348565974ffd52a52 Mon Sep 17 00:00:00 2001
From: "anthony.wen" <awen01@gmail.com>
Date: Sat, 14 Mar 2026 20:11:06 -0400
Subject: [PATCH] Document ATVM missing-config fail-fast rule

Record the operator preference to stop immediately when a requested ATVM config file is missing. Update the ATVM guide, local agent instructions, and run learnings to avoid searching for or substituting alternate config files without explicit direction.
---
 atvm/AGENTS.md                | 2 ++
 atvm/atvm-automation-guide.md | 4 +++-
 atvm/atvm-automation-runs.md  | 9 +++++++++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/atvm/AGENTS.md b/atvm/AGENTS.md
index 1dfe79c..3f7e68c 100644
--- a/atvm/AGENTS.md
+++ b/atvm/AGENTS.md
@@ -157,6 +157,8 @@ Re-create blacklist:
 - Prefer distro-scoped filtering (for example `--containsVm redhat9`) when possible.
 - Do not reference `cypress.atvm-config.ts` by default.
 - Unless the operator explicitly asks for another config, use ATVM config files with `gold` in the filename (for example `cypress.atvm-config-gold.ts`).
+- If the operator-specified ATVM config file is missing, fail fast and report the missing filename.
+- Do not search for alternate config files or silently substitute another config unless the operator explicitly asks for that.
 
 ## Update Policy (Both Tracks)
 After each run:
diff --git a/atvm/atvm-automation-guide.md b/atvm/atvm-automation-guide.md
index 150ac05..9c4912f 100644
--- a/atvm/atvm-automation-guide.md
+++ b/atvm/atvm-automation-guide.md
@@ -49,6 +49,8 @@ Typical sequence:
 - Additional numbered config variants map to corresponding Gold Disks.
 - Do not default to `cypress.atvm-config.ts`.
 - Unless the operator explicitly requests another config, use a config file with `gold` in the filename.
+- If the operator-specified config file is missing, stop immediately and report the missing file.
+- Do not search for substitute ATVM config files and do not switch to another config unless the operator explicitly instructs it.
 
 ## Available Templates
 - `cmc-e2e`
@@ -63,7 +65,7 @@ Typical sequence:
 ## Command Pattern
 ```bash
 python3 cmc-templates.py --template <template> --config_file_path ./<config-file> [template options...]; \
-python3 ./run-sorry-cypress.py --config_file <config-file> --build_name <hyphenated-description-no-spaces>
+python3 ./run-sorry-cypress.py --config_file <config-file> --build_name <hyphenated-description-no-spaces> [--categorize]
 ```
 
 ## Examples Reference
diff --git a/atvm/atvm-automation-runs.md b/atvm/atvm-automation-runs.md
index e367676..4fa338b 100644
--- a/atvm/atvm-automation-runs.md
+++ b/atvm/atvm-automation-runs.md
@@ -126,3 +126,12 @@ This file stores run-specific examples only when a run produced a new learning r
   - Format failed machine lines as `machine-name - FAIL - <failure description>`.
   - Prefer the longer same-line description when it adds useful operator-facing context.
   - Keep `Notes` for broader context, anomalies, and extra follow-up detail beyond the machine-specific failure description.
+
+## Run Learning: 2026-03-14 (Missing requested ATVM config must fail fast)
+- Observed requirement:
+  - If the operator asks for a specific ATVM config file and that file is missing on the automation VM, looking for other config files or substituting a different one creates the wrong next step.
+  - The operator wants to decide what to do after a missing-config failure.
+- Action for future runs:
+  - If the requested config file is missing, stop immediately and report the missing filename.
+  - Do not search the automation VM for alternate config files.
+  - Do not switch to another config unless the operator explicitly instructs it.