refactor(marker): emit ado-aw marker via prepare_steps, not setup_steps

The always-on `ado-aw-marker` extension was emitting its metadata
step via `setup_steps`, which forced `generate_setup_job` to spin
up a dedicated `- job: Setup` block in every compiled pipeline.
Minimal agentic pipelines with no user `setup:` declarations, no
PR/pipeline filters, and no other Setup-contributing extensions were
paying for a whole extra pool agent + agent boot just to emit a
single-line metadata comment.

Move the marker emission to `prepare_steps` so the step lands
inside the always-present Agent job's `{{ prepare_steps }}` block.
No extra job, no extra pool time — the marker is still parsed by
`parse_marker_step` the same way (scans for the
`# ado-aw-metadata:` line anywhere in the YAML).

The change requires extending the `CompilerExtension::prepare_steps`
signature to accept `&CompileContext` — the marker needs
`input_path`, `ado_context`, and `front_matter.target` to
build its JSON. All five existing `prepare_steps` implementors
(cache_memory, lean, python, node, dotnet) gain an unused
`_ctx: &CompileContext` parameter. The macro dispatcher and
`generate_prepare_steps` propagate ctx through.

Tests:

* All five existing `prepare_steps` unit tests in `extensions/tests.rs`
  updated to construct a `CompileContext` via the existing `ctx_from`
  helper.
* All seven `generate_prepare_steps` tests in `common.rs` updated to
  pass a `CompileContext::for_test(&fm)`.
* All seven marker-emit unit tests in `ado_aw_marker.rs` updated to
  call `prepare_steps(&ctx)` (now returns `Vec<String>` directly,
  no `Result` wrapper).
* New regression test `test_marker_does_not_create_setup_job_for_minimal_pipeline`
  asserts a minimal compiled pipeline contains the marker line but
  no `- job: Setup` block — guards against future re-introduction
  of the unnecessary Setup job.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

src/compile/common.rs

@@ -2221,12 +2221,13 @@ pub fn generate_teardown_job(
 pub fn generate_prepare_steps(
     prepare_steps: &[serde_yaml::Value],
     extensions: &[super::extensions::Extension],
+    ctx: &CompileContext,
 ) -> Result<String> {
     let mut parts = Vec::new();
 
     // Extension prepare steps and prompt supplements (runtimes + first-party tools)
     for ext in extensions {
-        for step in ext.prepare_steps() {
+        for step in ext.prepare_steps(ctx) {
             parts.push(step);
         }
         if let Some(prompt) = ext.prompt_supplement() {
@@ -3048,7 +3049,7 @@ pub async fn compile_shared(
         .is_some_and(|cm| cm.is_enabled());
     let parameters = build_parameters(&front_matter.parameters, has_memory);
     let parameters_yaml = generate_parameters(&parameters)?;
-    let prepare_steps = generate_prepare_steps(&front_matter.steps, extensions)?;
+    let prepare_steps = generate_prepare_steps(&front_matter.steps, extensions, ctx)?;
     let finalize_steps = generate_finalize_steps(&front_matter.post_steps);
     let pr_expression = pr_filters.and_then(|f| f.expression.as_deref());
     let pipeline_expression = pipeline_filters.and_then(|f| f.expression.as_deref());
@@ -6008,7 +6009,8 @@ safe-outputs:
             "---\nname: test\ndescription: test\ntools:\n  cache-memory: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         assert!(
             !result.is_empty(),
             "memory steps must be emitted when cache-memory enabled"
@@ -6023,7 +6025,8 @@ safe-outputs:
     fn test_generate_prepare_steps_without_memory_and_no_steps_has_safeoutputs_prompt() {
         let fm = minimal_front_matter();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         // SafeOutputs always contributes a prompt supplement
         assert!(
             result.contains("Safe Outputs"),
@@ -6037,7 +6040,8 @@ safe-outputs:
             "---\nname: test\ndescription: test\ntools:\n  cache-memory: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         assert!(
             result.contains("DownloadPipelineArtifact"),
             "memory steps must include the artifact download task"
@@ -6052,9 +6056,10 @@ safe-outputs:
     fn test_generate_prepare_steps_without_memory_with_user_steps() {
         let fm = minimal_front_matter();
         let exts = crate::compile::extensions::collect_extensions(&fm);
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
         let step: serde_yaml::Value =
             serde_yaml::from_str("bash: echo hello\ndisplayName: greet").unwrap();
-        let result = generate_prepare_steps(&[step], &exts).unwrap();
+        let result = generate_prepare_steps(&[step], &exts, &ctx).unwrap();
         assert!(!result.is_empty(), "user steps should be present");
         assert!(
             !result.contains("agent_memory"),
@@ -6068,9 +6073,10 @@ safe-outputs:
             "---\nname: test\ndescription: test\ntools:\n  cache-memory: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
         let step: serde_yaml::Value =
             serde_yaml::from_str("bash: echo hello\ndisplayName: greet").unwrap();
-        let result = generate_prepare_steps(&[step], &exts).unwrap();
+        let result = generate_prepare_steps(&[step], &exts, &ctx).unwrap();
         assert!(
             result.contains("agent_memory"),
             "memory reference must be present"
@@ -6087,7 +6093,8 @@ safe-outputs:
             "---\nname: test\ndescription: test\nruntimes:\n  lean: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         assert!(result.contains("elan-init.sh"), "should include elan installer");
         assert!(result.contains("Lean 4"), "should include Lean prompt");
         assert!(result.contains("--default-toolchain stable"), "should default to stable");
@@ -6100,7 +6107,8 @@ safe-outputs:
             "---\nname: test\ndescription: test\nruntimes:\n  lean:\n    toolchain: \"leanprover/lean4:v4.29.1\"\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         assert!(
             result.contains("--default-toolchain leanprover/lean4:v4.29.1"),
             "should use specified toolchain"
@@ -6113,7 +6121,8 @@ safe-outputs:
             "---\nname: test\ndescription: test\nruntimes:\n  lean: true\ntools:\n  cache-memory: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
-        let result = generate_prepare_steps(&[], &exts).unwrap();
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
+        let result = generate_prepare_steps(&[], &exts, &ctx).unwrap();
         assert!(result.contains("agent_memory"), "memory steps present");
         assert!(result.contains("elan-init.sh"), "lean install present");
         assert!(result.contains("Lean 4"), "lean prompt present");
@@ -6125,6 +6134,7 @@ safe-outputs:
     fn test_generate_awf_mounts_no_extensions() {
         let fm = minimal_front_matter();
         let exts = crate::compile::extensions::collect_extensions(&fm);
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
         let result = generate_awf_mounts(&exts);
         assert_eq!(result, "\\", "no mounts should produce bare continuation");
     }
@@ -6135,6 +6145,7 @@ safe-outputs:
             "---\nname: test\ndescription: test\nruntimes:\n  lean: true\n---\n",
         ).unwrap();
         let exts = crate::compile::extensions::collect_extensions(&fm);
+        let ctx = crate::compile::extensions::CompileContext::for_test(&fm);
         let result = generate_awf_mounts(&exts);
         assert!(result.contains("--mount"), "should contain --mount flag");
         assert!(result.contains(".elan"), "should reference .elan directory");

src/compile/extensions/ado_aw_marker.rs

@@ -17,7 +17,6 @@
 //! older parsers, mirroring gh-aw's `# gh-aw-metadata: {...}` shape.
 
 use super::{CompileContext, CompilerExtension, ExtensionPhase};
-use anyhow::Result;
 
 // ─── ado-aw marker (always-on, internal) ─────────────────────────────
 
@@ -43,13 +42,22 @@ impl CompilerExtension for AdoAwMarkerExtension {
         ExtensionPhase::Tool
     }
 
-    fn setup_steps(&self, ctx: &CompileContext) -> Result<Vec<String>> {
+    fn prepare_steps(&self, ctx: &CompileContext) -> Vec<String> {
+        // Inject the marker step into the Agent job's prepare phase
+        // (NOT a separate Setup job). Setup-job injection would force
+        // every compiled pipeline to spin up an extra agent pool job
+        // just to emit a metadata comment — wasteful for pipelines
+        // that have no other reason to need a Setup job. prepare_steps
+        // lands inside the always-present Agent job's
+        // `{{ prepare_steps }}` block, so it costs zero extra
+        // jobs/agents/pool time.
+        //
         // In unit-test contexts that build a CompileContext without an
         // input_path (e.g. CompileContext::for_test), skip the marker.
         // Production paths always populate input_path via
         // CompileContext::new.
         let Some(input_path) = ctx.input_path else {
-            return Ok(vec![]);
+            return vec![];
         };
 
         let source = super::super::common::normalize_source_path(input_path);
@@ -129,7 +137,7 @@ impl CompilerExtension for AdoAwMarkerExtension {
             target = target,
         );
 
-        Ok(vec![step])
+        vec![step]
     }
 }
 
@@ -155,7 +163,7 @@ mod tests {
     fn returns_no_step_when_input_path_absent() {
         let fm = parse_fm("name: t\ndescription: x\n");
         let ctx = CompileContext::for_test(&fm);
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert!(steps.is_empty(), "expected no marker when input_path is None");
     }
 
@@ -173,7 +181,7 @@ mod tests {
             compile_dir: None,
             input_path: Some(input_path),
         };
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert_eq!(steps.len(), 1);
         let step = &steps[0];
         assert!(step.contains("displayName: \"ado-aw\""), "step missing displayName:\n{step}");
@@ -206,7 +214,7 @@ mod tests {
             compile_dir: None,
             input_path: Some(input_path),
         };
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert_eq!(steps.len(), 1);
         let step = &steps[0];
         // ADO identifiers are case-insensitive; lowercase to make
@@ -245,7 +253,7 @@ mod tests {
                 compile_dir: None,
                 input_path: Some(input_path),
             };
-            let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+            let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
             assert_eq!(steps.len(), 1, "target={raw_target}");
             assert!(
                 steps[0].contains(&format!("\"target\":\"{expected}\"")),
@@ -279,7 +287,7 @@ mod tests {
             compile_dir: None,
             input_path: Some(input_path),
         };
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert_eq!(steps.len(), 1);
         let step = &steps[0];
         assert!(
@@ -316,7 +324,7 @@ mod tests {
             compile_dir: None,
             input_path: Some(input_path),
         };
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert_eq!(steps.len(), 1);
         let step = &steps[0];
 
@@ -365,7 +373,7 @@ mod tests {
             compile_dir: None,
             input_path: Some(input_path),
         };
-        let steps = AdoAwMarkerExtension.setup_steps(&ctx).unwrap();
+        let steps = AdoAwMarkerExtension.prepare_steps(&ctx);
         assert_eq!(steps.len(), 1);
 
         // Parse the marker step back via the canonical discovery parser

src/compile/extensions/mod.rs

@@ -288,7 +288,11 @@ pub trait CompilerExtension {
     /// Pipeline steps (YAML strings) to run before the agent.
     ///
     /// Each element is a complete YAML step (e.g., `- bash: |...`).
-    fn prepare_steps(&self) -> Vec<String> {
+    /// These are injected into the Agent job's `{{ prepare_steps }}`
+    /// block — no new job/stage is created, so always-on extensions
+    /// (like `ado-aw-marker`) can emit metadata steps with zero impact
+    /// on pipeline structure.
+    fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
         vec![]
     }
 
@@ -561,8 +565,8 @@ macro_rules! extension_enum {
             fn prompt_supplement(&self) -> Option<String> {
                 match self { $( $Enum::$Variant(e) => e.prompt_supplement(), )+ }
             }
-            fn prepare_steps(&self) -> Vec<String> {
-                match self { $( $Enum::$Variant(e) => e.prepare_steps(), )+ }
+            fn prepare_steps(&self, ctx: &CompileContext) -> Vec<String> {
+                match self { $( $Enum::$Variant(e) => e.prepare_steps(ctx), )+ }
             }
             fn setup_steps(&self, ctx: &CompileContext) -> Result<Vec<String>> {
                 match self { $( $Enum::$Variant(e) => e.setup_steps(ctx), )+ }

src/compile/extensions/tests.rs

@@ -207,7 +207,9 @@ fn test_lean_prompt_supplement() {
 #[test]
 fn test_lean_prepare_steps() {
     let ext = LeanExtension::new(LeanRuntimeConfig::Enabled(true));
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 1);
     assert!(steps[0].contains("elan-init.sh"));
 }
@@ -324,7 +326,9 @@ fn test_ado_validate_duplicate_mcp_warning() {
 #[test]
 fn test_cache_memory_prepare_steps() {
     let ext = CacheMemoryExtension::new(CacheMemoryToolConfig::Enabled(true));
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 1);
     assert!(steps[0].contains("DownloadPipelineArtifact"));
 }
@@ -401,7 +405,9 @@ fn test_python_prepare_steps() {
     let ext = crate::runtimes::python::PythonExtension::new(
         crate::runtimes::python::PythonRuntimeConfig::Enabled(true),
     );
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 1, "no auth step without feed-url/config");
     assert!(steps[0].contains("UsePythonVersion@0"));
 }
@@ -413,7 +419,9 @@ fn test_python_prepare_steps_with_feed_url() {
     ).unwrap();
     let python = fm.runtimes.as_ref().unwrap().python.as_ref().unwrap();
     let ext = crate::runtimes::python::PythonExtension::new(python.clone());
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 2);
     assert!(steps[0].contains("UsePythonVersion@0"));
     assert!(steps[1].contains("PipAuthenticate@1"));
@@ -543,7 +551,9 @@ fn test_node_prepare_steps() {
     let ext = crate::runtimes::node::NodeExtension::new(
         crate::runtimes::node::NodeRuntimeConfig::Enabled(true),
     );
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 1, "no auth steps without feed-url/config");
     assert!(steps[0].contains("NodeTool@0"));
 }
@@ -555,7 +565,9 @@ fn test_node_prepare_steps_with_feed_url() {
     ).unwrap();
     let node = fm.runtimes.as_ref().unwrap().node.as_ref().unwrap();
     let ext = crate::runtimes::node::NodeExtension::new(node.clone());
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 3);
     assert!(steps[0].contains("NodeTool@0"));
     assert!(steps[1].contains("Ensure .npmrc"));
@@ -708,7 +720,9 @@ fn test_dotnet_prepare_steps() {
     let ext = crate::runtimes::dotnet::DotnetExtension::new(
         crate::runtimes::dotnet::DotnetRuntimeConfig::Enabled(true),
     );
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 1, "no auth steps without feed-url/config");
     assert!(steps[0].contains("UseDotNet@2"));
     assert!(steps[0].contains("packageType: 'sdk'"));
@@ -721,7 +735,9 @@ fn test_dotnet_prepare_steps_with_feed_url() {
     ).unwrap();
     let dotnet = fm.runtimes.as_ref().unwrap().dotnet.as_ref().unwrap();
     let ext = crate::runtimes::dotnet::DotnetExtension::new(dotnet.clone());
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert_eq!(steps.len(), 3);
     assert!(steps[0].contains("UseDotNet@2"));
     assert!(steps[1].contains("Ensure nuget.config"));
@@ -735,7 +751,9 @@ fn test_dotnet_prepare_steps_with_config_only() {
     ).unwrap();
     let dotnet = fm.runtimes.as_ref().unwrap().dotnet.as_ref().unwrap();
     let ext = crate::runtimes::dotnet::DotnetExtension::new(dotnet.clone());
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     // config: alone trusts the user-checked-in nuget.config — no shim,
     // just the auth step.
     assert_eq!(steps.len(), 2);
@@ -796,7 +814,9 @@ fn test_dotnet_global_json_sentinel_emits_use_global_json() {
     let dotnet = fm.runtimes.as_ref().unwrap().dotnet.as_ref().unwrap();
     assert!(dotnet.use_global_json());
     let ext = crate::runtimes::dotnet::DotnetExtension::new(dotnet.clone());
-    let steps = ext.prepare_steps();
+    let fm = minimal_front_matter();
+    let ctx = ctx_from(&fm);
+    let steps = ext.prepare_steps(&ctx);
     assert!(steps[0].contains("useGlobalJson: true"));
     assert!(!steps[0].contains("version:"), "explicit version must be omitted in global.json mode");
     assert!(steps[0].contains("from global.json"));

src/runtimes/dotnet/extension.rs

@@ -62,7 +62,7 @@ in the repository.\n"
         )
     }
 
-    fn prepare_steps(&self) -> Vec<String> {
+    fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
         let mut steps = vec![generate_dotnet_install(&self.config)];
         // Emit ensure-nuget.config + NuGetAuthenticate when an internal feed
         // is configured. When only `config:` is set, the user-checked-in

src/runtimes/lean/extension.rs

@@ -52,7 +52,7 @@ the toolchain. Lean files use the `.lean` extension.\n"
         )
     }
 
-    fn prepare_steps(&self) -> Vec<String> {
+    fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
         vec![generate_lean_install(&self.config)]
     }
 

src/runtimes/node/extension.rs

@@ -54,7 +54,7 @@ Node.js is installed and available. Use `node` to run scripts, \
         )
     }
 
-    fn prepare_steps(&self) -> Vec<String> {
+    fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
         let mut steps = vec![generate_node_install(&self.config)];
         // Emit ensure-npmrc + npmAuthenticate only when an internal feed is configured
         if self.config.feed_url().is_some() || self.config.config().is_some() {

src/runtimes/python/extension.rs

@@ -55,7 +55,7 @@ management, install it first with `pip install uv`.\n"
         )
     }
 
-    fn prepare_steps(&self) -> Vec<String> {
+    fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
         let mut steps = vec![generate_python_install(&self.config)];
         // Emit PipAuthenticate only when feed-url is set (config alone is not
         // sufficient — PipAuthenticate needs a feed to authenticate against)