feat(compile): runtime prompt loading via {{#runtime-import}} markers (#625)

* feat(compile): runtime prompt loading via {{#runtime-import}} markers

Adopts gh-aw's {{#runtime-import path}} marker model and the inlined-imports front-matter toggle. Agent prompt bodies (and the Stage-2 threat-analysis prompt) are now loaded at pipeline runtime by default; body edits no longer require ado-aw compile.

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

* feat(compile): introduce System phase so ado-script installs before user runtimes

ADO's NodeTool@0 prepends to PATH, so when both AdoScriptExtension (gate+import bundle, requires Node 20.x) and NodeExtension (user-pinned version) emit NodeTool@0 into the same Agent job, the LAST install wins on PATH. Previously AdoScript ran in the Tool phase, AFTER Runtime — so its hardcoded 20.x silently overrode the user's pinned version.

Introduces a new ExtensionPhase::System variant that sorts before Runtime. AdoScript moves to System: its NodeTool@0 install runs first, the resolver step uses it during a brief 20.x window, then the user's NodeExtension's NodeTool@0 runs and the user's version wins on PATH for everything after.

Adds test_node_runtime_install_orders_after_ado_script_so_user_version_wins pinning this ordering. Updates extension-count tests for the new phase. Refreshes ExtensionPhase docs and the collect_extensions ordering policy.

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

* fix(compile): guard runtime-import marker paths against whitespace and ##vso injection

Addresses three findings from the 2026-05-19 Rust PR review on #625:

1. Reject whitespace in agent source paths at compile time when
   inlined-imports is false. The runtime resolver
   (scripts/ado-script/src/import/index.ts) matches marker bodies with
   [^\s}]+, so a space silently truncated the path and produced either
   a misleading runtime `file not found` or, for optional markers, an
   unexpanded marker visible to the LLM. Mirrors the existing
   resolve_imports_inline guard.

2. Aggregate all import errors instead of reporting only the first.
   Previously hadError ??= captured one failure and silently swallowed
   subsequent ones. Now every missing/unreadable required marker emits
   its own ##vso[task.logissue type=error] line before exit(1).

3. Sanitize rawPath in ##vso error output. Strips `]`, CR, and LF
   from path strings embedded in diagnostic lines so an unusual
   path can no longer break the ##vso command framing.

Tests:
* tests/compiler_tests.rs::test_runtime_imports_default_rejects_source_path_with_whitespace
* scripts/ado-script/src/import/__tests__/error-reporting.test.ts (2 cases)

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

* fix(compile): block path-traversal in runtime-import resolver and guard fixture helper

Two follow-up findings from the 2026-05-19 review on #625:

1. Reject `..` path components in both resolvers.

   `resolve_imports_inline` (compile-time, inlined-imports: true) and
   `import.js` (runtime, inlined-imports: false) both accepted
   `../`-style paths without restriction. A malicious markdown body
   on an untrusted PR branch could therefore embed host files (e.g.
   `{{#runtime-import ../../../../etc/passwd}}`) into the compiled
   YAML or, at runtime, into the agent prompt. The new guard rejects
   any path whose `/` or `\\`-split segments include `..`,
   regardless of whether the path is absolute or relative. Literal
   `..` characters inside a filename (e.g. `name..md`) are still
   allowed because they are not segments.

2. `compile_fixture_with_inlined_imports` now refuses fixtures that
   already declare `inlined-imports:`.

   The helper used to inject `inlined-imports: true` by raw string
   substitution before the closing `---`. If a future fixture
   hard-coded `inlined-imports: false`, the rewritten front matter
   would have two `inlined-imports:` keys; serde_yaml silently uses
   the last one so the test would still pass, but the duplicate-key
   fixture is confusing and the helper would silently flip the
   author's intent. The guard panics with an actionable message.

Tests:
* src/compile/extensions/ado_script.rs: 5 new unit tests covering
  relative/embedded/absolute/backslash `..` rejection and the literal
  `name..md` allow case.
* scripts/ado-script/src/import/__tests__/path-traversal.test.ts:
  4 new vitest cases.

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

* refactor(compile): drop unused ADO_AW_IMPORT_BASE env var

`import.js` consults `ADO_AW_IMPORT_BASE` only when resolving a
relative marker path (`isAbsolute(rawPath) ? rawPath : resolve(base,
rawPath)`). In the pipeline the only marker `import.js` ever sees is
the compiler-generated top-level body marker, which embeds an absolute
`$(Build.SourcesDirectory)/...` path. The resolver is also single-pass
by design, so author-written nested relative markers inside the inlined
body are never re-expanded at runtime. The env var was therefore dead
code at runtime.

Changes:
- Remove the `env:` block from `resolver_step()` in
  `src/compile/extensions/ado_script.rs` (and update its unit test to
  assert the variable is absent).
- Drop the `process.env.ADO_AW_IMPORT_BASE ??` fallback in
  `scripts/ado-script/src/import/index.ts`; `import.js` now always
  uses `dirname(argv[2])` for relative-path resolution (irrelevant in
  pipeline use, useful for local invocations).
- Replace the `ADO_AW_IMPORT_BASE`-override vitest with a
  `dirname(target)` default-base test that pins the fallback for
  standalone callers.
- Update `docs/ado-script.md` and `docs/runtime-imports.md` to drop
  the env-var contract and explain why the runtime never sees a
  relative marker.

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

* fix(compile): correct threat-prompt doc claim and gate required_hosts on actual download

Two findings from the latest PR review:

1. docs/template-markers.md falsely claimed that the
   `{{ threat_analysis_prompt }}` marker is emitted as a
   `{{#runtime-import ...}}` when `inlined-imports: false`. The
   threat-analysis prompt is tooling-shipped (compiled into the
   `ado-aw` binary via `include_str!`) and unconditionally inlined at
   step 11 of `compile_shared`. The marker is for the agent body, not
   the threat prompt. Rewrote the paragraph to reflect this and to
   cross-reference the rationale in `src/compile/common.rs`.

2. `AdoScriptExtension::required_hosts()` always requested
   `github.com`, even when `inlined-imports: true` AND no filters were
   configured (so neither `setup_steps()` nor `prepare_steps()` emits
   the NodeTool@0 + curl pair, and github.com is therefore unreachable
   from the pipeline). For a security-sensitive project, the
   allowlist should match the actual network reach of the compiled
   pipeline. Now returns `vec![]` unless `has_gate()` or
   `runtime_imports_active()`. Added three unit tests covering all
   three branches (no-consumer, gate-active, imports-active).

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

* fix(compile): reject absolute paths in compile-time runtime-import resolver

Three findings from the latest PR review:

1. **Security**: `resolve_imports_inline` accepted absolute paths
   without restriction. When `inlined-imports: true`, an untrusted PR
   branch could embed arbitrary host files into the compiled YAML via
   `{{#runtime-import /home/runner/.ssh/id_rsa}}`,
   `{{#runtime-import C:\Users\runner\secret.txt}}`, or
   `{{#runtime-import \\server\share\file}}`. The PR description
   already called out the `..`-traversal threat for "untrusted PR
   branches" — the same threat applies here. Compile-time resolution
   now requires a **relative** path rooted under `base_dir` (the
   source `.md` file's parent directory, which is inside the repo and
   therefore part of the same trust domain). `std::path::Path::is_absolute`
   is platform-dependent, so the guard also explicitly checks
   `/`-prefixed and `\\`-prefixed shapes.

   `import.js` (runtime resolver) keeps its absolute-path support
   unchanged — the agent VM is a lower-risk environment and the
   pipeline-generated body marker is always absolute.

2. **Cleanup**: `AdoScriptExtension::has_gate()` and `setup_steps()`
   both called `lower_pr_filters()` / `lower_pipeline_filters()`,
   doing the same lowering twice. Factored into a single
   `lowered_checks()` helper that both call sites reuse.

3. **Comment**: `sanitizeForVsoMessage` in `import.js` now explains
   why `[` is intentionally NOT stripped (without a closing `]` and a
   fresh `##vso` prefix it cannot open a new logging command).

Tests:
* `rejects_absolute_posix_path_at_compile_time`,
  `rejects_absolute_windows_drive_path_at_compile_time`,
  `rejects_unc_path_at_compile_time` in
  `src/compile/extensions/ado_script.rs`.
* `supports_relative_and_absolute_paths` test removed (no longer
  reachable behaviour); replaced with `supports_relative_path_resolution`.
* `docs/runtime-imports.md` updated to document the new restriction
  and call out the security rationale.

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

* fix(compile): reject `}` in runtime-import paths to match the runtime regex

`import.js`'s marker regex `[^\s}]+` excludes `}` from the path capture
so the regex terminates cleanly at the closing `}}`. The compile-time
resolver (`resolve_imports_inline`) terminated only at `}}` and would
therefore silently accept a path like `foo}bar.md` that the runtime
resolver would either truncate or leave unexpanded — a real
compile-vs-runtime divergence.

Reject `}` in paths up front at compile time so the failure mode is one
clear compile error rather than two different runtime behaviours
depending on `inlined-imports`. Added a comment to `import.js`'s
regex documenting that the compile-time side enforces the same
restriction.

Test: `rejects_path_containing_closing_brace` in
`src/compile/extensions/ado_script.rs`.

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

* fix(compile): make absolute-path check platform-independent for runtime-import

`Path::is_absolute` is platform-dependent — on Linux it doesn't recognize

Windows drive-letter paths like `C:\Users\...` as absolute, so

`rejects_absolute_windows_drive_path_at_compile_time` failed on Linux CI

with `file not found` instead of the expected absolute-path rejection.

Added an explicit drive-letter detector that matches `[A-Za-z]:[/\\]`

via pure string inspection, so the guard fires on every host where

`ado-aw compile` may run regardless of the local platform's path

semantics.

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

* fix(compile): reject absolute paths in runtime resolver and pass --base from pipeline

The compile-time `resolve_imports_inline` already rejected absolute
paths, but `import.js` allowed them at runtime with a misleading
"Mirrors `resolve_imports_inline`" comment. Although the documented
single-pass design currently prevents author-written nested markers
from reaching `import.js`, the asymmetry was a defence-in-depth gap:

  - the resolver explicitly says it handles "arbitrary author-written
    markers in the agent body";
  - if the design ever shifts to multi-pass, an author marker like
    `{{#runtime-import /tmp/awf-tools/staging/mcpg-config.json}}` could
    silently embed credentials into the agent's system prompt;
  - the runtime and compile-time paths should enforce the same policy
    so reviewers don't have to mentally track which guards apply where.

Changes:

* `scripts/ado-script/src/import/index.ts`
  - Add `--base <path>` CLI arg (replaces the implicit `dirname(target)`
    fallback for pipeline use; the fallback remains for standalone
    invocation).
  - Reject absolute paths the same way Rust does: POSIX `/foo`,
    Windows drive-letter `C:\foo`/`C:/foo` (detected via a
    platform-independent character scan because `path.isAbsolute` is
    OS-dependent on this), and UNC `\\server\share`.

* `src/compile/common.rs`
  - Emit a trigger-repo-relative marker (stripping
    `$(Build.SourcesDirectory)/` from the resolved source path) so the
    new absolute-path reject in `import.js` doesn't fire on the
    compiler-generated body marker. The relative-form marker is the
    only form `import.js` ever needs to resolve at runtime.

* `src/compile/extensions/ado_script.rs`
  - Resolver step passes `--base "$(Build.SourcesDirectory)"` so the
    relative marker resolves against the trigger-repo checkout root.

Tests:

* New vitest cases for the three absolute-path shapes (POSIX,
  drive-letter, UNC) and for `--base` resolution.
* Replaced the "uses absolute snippet paths as-is" test with a
  rejection assertion.
* Unit test updated to assert the resolver step now includes
  `--base "$(Build.SourcesDirectory)"`.

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

* fix(compile): reject `}` in runtime-import source path and fix stale extension refs

Two findings from the latest review:

1. **Bug**: `agent_marker_path` in `compile_shared` was only guarded
   against whitespace, not `}`. An agent file at `agents/fo}o.md`
   (valid on Linux/macOS/NTFS) would emit a malformed marker that the
   runtime regex `[^\s}]+` truncates at the `}` and then fails to
   match because the next two chars aren't `}}`. The marker would
   survive as literal text in the agent's prompt with no error
   surfaced. Added an explicit `}` check that mirrors the same guard
   in `resolve_imports_inline`, with a clear error suggesting either
   renaming the path or setting `inlined-imports: true`.

2. **Stale refs**: `TriggerFiltersExtension` and
   `src/compile/extensions/trigger_filters.rs` were referenced in:

   - `src/compile/pr_filters.rs` (3 comments)
   - `.github/workflows/ado-script.yml` (path triggers)
   - `tests/bash_lint_tests.rs` (annotation comment)
   - `scripts/ado-script/README.md` (Bundles + Layout + See also)
   - `site/src/content/docs/reference/filter-ir.mdx` (Integration
     Points section + Gate Step Injection)

   All updated to point at `AdoScriptExtension` /
   `src/compile/extensions/ado_script.rs` (the consolidated extension
   introduced earlier in this PR). The site doc was also extended to
   note the additional `prepare_steps()` hook the extension owns for
   the runtime-import resolver.

Tests:
* `test_runtime_imports_default_rejects_source_path_with_closing_brace`
  in `tests/compiler_tests.rs` — exercises a source path with `}`
  and asserts the compiler errors with the new guard.

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

---------

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

Author: jamesadevine

.github/workflows/ado-script.yml

@@ -5,7 +5,7 @@ on:
     paths:
       - "scripts/ado-script/**"
       - "src/compile/filter_ir.rs"
-      - "src/compile/extensions/trigger_filters.rs"
+      - "src/compile/extensions/ado_script.rs"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/ado-script.yml"
@@ -19,7 +19,7 @@ on:
     paths:
       - "scripts/ado-script/**"
       - "src/compile/filter_ir.rs"
-      - "src/compile/extensions/trigger_filters.rs"
+      - "src/compile/extensions/ado_script.rs"
       - "Cargo.toml"
       - "Cargo.lock"
       - ".github/workflows/ado-script.yml"
@@ -69,13 +69,13 @@ jobs:
         working-directory: scripts/ado-script
         run: npm run typecheck
 
-      - name: Build bundle (gate.js)
+      - name: Build bundles
         working-directory: scripts/ado-script
         run: npm run build
 
-      - name: Smoke-test bundle
+      - name: Smoke-test bundles
         working-directory: scripts/ado-script
-        run: npx vitest run -c vitest.config.smoke.ts
+        run: npm run test:smoke
 
       - name: E2E gate test
         run: cargo test --test gate_e2e -- --ignored --nocapture

AGENTS.md

@@ -62,7 +62,7 @@ Every compiled pipeline runs as three sequential jobs:
 │   │   │   ├── ado_aw_marker.rs # Always-on metadata marker extension (emits # ado-aw-metadata JSON)
 │   │   │   ├── github.rs # Always-on GitHub MCP extension
 │   │   │   ├── safe_outputs.rs # Always-on SafeOutputs MCP extension
-│   │   │   ├── trigger_filters.rs # Trigger filter extension (gate evaluator delivery)
+│   │   │   ├── ado_script.rs # Always-on ado-script extension (gate evaluator + runtime-import resolver, per-job downloads)
 │   │   │   └── tests.rs  # Extension integration tests
 │   │   ├── codemods/     # Front-matter codemods (one file per transformation)
 │   │   │   ├── mod.rs    # Codemod struct, CODEMODS registry, runner
@@ -159,7 +159,9 @@ Every compiled pipeline runs as three sequential jobs:
 │   ├── update-ado-agentic-workflow.md # Guide for modifying an existing agentic pipeline
 │   └── debug-ado-agentic-workflow.md  # Guide for troubleshooting a failing agentic pipeline
 ├── scripts/              # Supporting scripts shipped as release artifacts
-│   ├── ado-script/       # TypeScript workspace for bundled gate.js (and future bundles)
+│   ├── ado-script/       # TypeScript workspace for bundled gate.js, import.js, and future bundles
+│   │   └── src/
+│   │       └── import/   # Runtime prompt resolver bundle
 │   └── gate.js           # Bundled gate evaluator (built from scripts/ado-script/, see docs/ado-script.md)
 ├── tests/                # Integration tests and fixtures
 ├── docs/                 # Per-concept reference documentation (see index below)
@@ -172,7 +174,7 @@ Every compiled pipeline runs as three sequential jobs:
 - **Language**: Rust (2024 edition) - Note: Rust 2024 edition exists and is the edition used by this project
 - **CLI Framework**: clap v4 with derive macros
 - **Error Handling**: anyhow for ergonomic error propagation
-- **Bundled scripts**: TypeScript + ncc (`scripts/ado-script/`) — compiled gate evaluator and future internal helpers; see [`docs/ado-script.md`](docs/ado-script.md).
+- **Bundled scripts**: TypeScript + ncc (`scripts/ado-script/`) — compiled gate evaluator, runtime import resolver, and future internal helpers; see [`docs/ado-script.md`](docs/ado-script.md).
 - **Async Runtime**: tokio with full features
 - **YAML Parsing**: serde_yaml
 - **MCP Server**: rmcp with server and transport-io features
@@ -196,6 +198,8 @@ index to jump to the right page.
 
 - [`docs/front-matter.md`](docs/front-matter.md) — full agent file format
   (markdown body + YAML front matter grammar) with every supported field.
+- [`docs/runtime-imports.md`](docs/runtime-imports.md) — runtime prompt import
+  markers, path resolution, and `inlined-imports:` behavior.
 - [`docs/schedule-syntax.md`](docs/schedule-syntax.md) — fuzzy schedule time
   syntax (`daily around 14:00`, `weekly on monday`, timezones, scattering).
 - [`docs/engine.md`](docs/engine.md) — `engine:` configuration (model,
@@ -242,7 +246,7 @@ index to jump to the right page.
   adding codemods.
 - [`docs/ado-script.md`](docs/ado-script.md) — `ado-script` workspace
   (`scripts/ado-script/`): the bundled TypeScript runtime helpers (today:
-  `gate.js`), schemars-driven type codegen, and the A2 design decision.
+  `gate.js` and `import.js`), schemars-driven type codegen, and the A2 design decision.
 - [`docs/local-development.md`](docs/local-development.md) — local development
   setup notes.
 

docs/ado-script.md

@@ -3,8 +3,9 @@
 `ado-script` is the umbrella name for the TypeScript workspace at
 [`scripts/ado-script/`](../scripts/ado-script/). It produces small,
 ncc-bundled Node programs that the **compiler injects into every emitted
-pipeline** as runtime helpers. The first (and currently only) bundle is
-`gate.js`, the trigger-filter gate evaluator.
+pipeline** as runtime helpers. Today it produces `gate.js`, the
+trigger-filter gate evaluator, and `import.js`, the runtime prompt
+resolver described in [`runtime-imports.md`](runtime-imports.md).
 
 > **Internal-only.** `ado-script` is not a user-facing front-matter
 > feature. Authors never write an `ado-script:` block in their agent
@@ -33,6 +34,35 @@ discriminated union. There is no `eval`, no `Function`, no `vm` — a
 compromised compiler cannot use the spec to run arbitrary code on the
 pipeline runner.
 
+## What `import.js` does
+
+`import.js` is a single-shot Node program. It reads the prompt file path
+from `argv[2]` and resolves `{{#runtime-import path}}` markers in place.
+The compiler runs it as a post-prepare-prompt step when
+[`inlined-imports: false`](front-matter.md#inlined-imports). See
+[`runtime-imports.md`](runtime-imports.md) for the author-facing marker
+syntax.
+
+### Env-var contract
+
+`import.js` takes no environment variables. Relative-path markers
+resolve against `dirname(argv[2])`; in pipeline use this is irrelevant
+because the compiler always embeds an absolute marker path and
+`import.js` is single-pass (nested markers inside the inlined body are
+not re-expanded).
+
+The bundle lives at `dist/import/index.js` and ships in the same
+`ado-script.zip` release asset as `gate.js`, so pipelines download it
+through the same Setup-job asset flow. `import.js` uses only the Node
+standard library, so the ncc bundle is small (~1.5 KB) and carries no
+SDK dependency.
+
+The Stage-2 threat-analysis prompt is **not** runtime-imported.
+`src/data/threat-analysis.md` is `include_str!`'d into the `ado-aw`
+binary and inlined into the emitted YAML at compile time, matching
+gh-aw's pattern (their `threat_detection.md` ships with the setup
+action and is read directly from disk — no marker, no resolver).
+
 ## End-to-end data flow
 
 ```
@@ -147,14 +177,19 @@ scripts/ado-script/
 │   │   ├── env-facts.ts         # Pipeline-variable readers + ENV_BY_FACT + BRANCH_FACTS + ref-prefix stripping
 │   │   ├── policy.ts            # PolicyTracker state machine
 │   │   └── vso-logger.ts        # ##vso[…] emitters with property/message escaping; complete() is idempotent
-│   └── gate/                    # gate.js entry point + per-concern modules
-│       ├── index.ts             # main(): decode → preflight → bypass → facts → eval → emit
-│       ├── bypass.ts            # build-reason auto-pass
-│       ├── facts.ts             # fact acquisition (env + REST)
-│       ├── predicates.ts        # 11 predicate evaluators + validatePredicateTree + glob ReDoS hardening
-│       └── selfcancel.ts        # best-effort build cancellation
+│   ├── gate/                    # gate.js entry point + per-concern modules
+│   │   ├── index.ts             # main(): decode → preflight → bypass → facts → eval → emit
+│   │   ├── bypass.ts            # build-reason auto-pass
+│   │   ├── facts.ts             # fact acquisition (env + REST)
+│   │   ├── predicates.ts        # 11 predicate evaluators + validatePredicateTree + glob ReDoS hardening
+│   │   └── selfcancel.ts        # best-effort build cancellation
+│   └── import/                  # import.js entry point + runtime prompt resolver
+│       ├── index.ts             # main(): expand runtime-import markers in place
+│       └── __tests__/           # marker, path-resolution, and single-pass coverage
 ├── test/                        # End-to-end smoke tests
-└── dist/gate/index.js           # ncc bundle output (gitignored)
+└── dist/                        # ncc bundle output (gitignored)
+    ├── gate/index.js
+    └── import/index.js
 ```
 
 The release workflow (`.github/workflows/release.yml`) runs
@@ -195,11 +230,18 @@ The Rust subcommand that emits the schema is intentionally hidden:
 cargo run -- export-gate-schema --output schema/gate-spec.schema.json
 ```
 
-## How the gate bundle is wired into emitted pipelines
+## How the bundles are wired into emitted pipelines
+
+`AdoScriptExtension`
+(`src/compile/extensions/ado_script.rs`) is the always-on single
+extension that owns all `ado-script` wiring. It has two independent
+features, each emitted **into the job that actually consumes the
+bundle**:
 
-`TriggerFiltersExtension`
-(`src/compile/extensions/trigger_filters.rs`) injects three Setup-job
-steps when any `filters:` block is active:
+### Setup job (gate evaluator)
+
+When `filters:` lowers to non-empty checks, `setup_steps()` returns
+three step strings into the Setup job:
 
 1. **`NodeTool@0`** — installs Node 20.x LTS, capped at
    `timeoutInMinutes: 5`.
@@ -209,9 +251,42 @@ steps when any `filters:` block is active:
    `unzip -o /tmp/ado-aw-scripts/ado-script.zip -d /tmp/ado-aw-scripts/`.
    Also capped at `timeoutInMinutes: 5`.
 3. **`bash: node '/tmp/ado-aw-scripts/ado-script/dist/gate/index.js'`** —
-   runs the gate with `GATE_SPEC` and the env-var contract above.
-
-The IR-to-bash codegen that produces these steps is
+   runs the gate with `GATE_SPEC` and the env-var contract documented
+   above.
+
+### Agent job (runtime-import resolver)
+
+When `inlined-imports: false` (the default), `prepare_steps()` returns
+the same install + download pair plus the resolver invocation, into
+the Agent job's existing `{{ prepare_steps }}` block:
+
+1. **`NodeTool@0`** — same shape as above.
+2. **`curl` download + verify + extract** — same artefact, same
+   verification.
+3. **`bash: node '/tmp/ado-aw-scripts/ado-script/dist/import/index.js'`** —
+   expands `{{#runtime-import …}}` markers in
+   `/tmp/awf-tools/agent-prompt.md` in place. See
+   [`runtime-imports.md`](runtime-imports.md) for marker syntax.
+
+### Per-job download (NOT a duplication bug)
+
+ADO jobs use **isolated VMs** — `/tmp` is not shared between jobs.
+The `ado-script.zip` bundle therefore has to be downloaded once per
+job that consumes it. When both features are active (a pipeline with
+both `filters:` and `inlined-imports: false`), install + download
+steps appear in **both** Setup and Agent. That's correct architecture
+given ADO's topology, not waste.
+
+### What gets emitted, by case
+
+| `filters:` | `inlined-imports` | Setup-job steps | Agent-job extra steps |
+|---|---|---|---|
+| inactive   | `true`  | (none)                              | (none)                              |
+| inactive   | `false` | (no Setup job)                      | install + download + resolver       |
+| active     | `true`  | install + download + gate           | (none)                              |
+| active     | `false` | install + download + gate           | install + download + resolver       |
+
+The IR-to-bash codegen that produces the gate step is
 `compile_gate_step_external` in `src/compile/filter_ir.rs`.
 
 ## Modifying `ado-script`

docs/filter-ir.md

@@ -350,24 +350,30 @@ The bash shim exports only the ADO macros needed by the spec's facts:
 
 ## Integration Points
 
-### TriggerFiltersExtension
+### AdoScriptExtension
 
-When Tier 2/3 filters are configured, the `TriggerFiltersExtension`
-(`src/compile/extensions/trigger_filters.rs`) activates via
-`collect_extensions()`. It implements `CompilerExtension` and controls:
+When `filters:` is configured (and lowers to non-empty checks), the
+always-on `AdoScriptExtension`
+(`src/compile/extensions/ado_script.rs`) emits the gate-side steps via
+the `setup_steps()` trait hook. The extension also owns the unrelated
+runtime-import resolver — see [`runtime-imports.md`](runtime-imports.md).
+
+For the gate path it controls:
 
 1. **Node install step** — emits a `NodeTool@0` step pinned to Node 20.x
-   LTS so `gate.js` has a runtime
+   LTS so `gate.js` has a runtime.
 2. **Download step** — fetches `ado-script.zip` from the ado-aw release
    artifacts, verifies its SHA256 checksum via `checksums.txt`, then
-   extracts `gate.js` to `/tmp/ado-aw-scripts/ado-script/dist/gate/index.js`
+   extracts `gate.js` to `/tmp/ado-aw-scripts/ado-script/dist/gate/index.js`.
 3. **Gate step** — calls `compile_gate_step_external()` to generate a step
-   that runs `node /tmp/ado-aw-scripts/ado-script/dist/gate/index.js` (no inline heredoc)
+   that runs `node /tmp/ado-aw-scripts/ado-script/dist/gate/index.js` (no inline heredoc).
 4. **Validation** — runs `validate_pr_filters()` / `validate_pipeline_filters()`
-   during compilation via the `validate()` trait method
+   during compilation via the `validate()` trait method.
 
-The extension uses the `setup_steps()` trait method (not `prepare_steps()`)
-because the gate must run in the **Setup job** (before the Agent job).
+The gate-side steps use `setup_steps()` (not `prepare_steps()`)
+because the gate must run in the **Setup job**, before the Agent job.
+Runtime-import resolver steps for the agent body use `prepare_steps()` and
+land in the Agent job — see [`runtime-imports.md`](runtime-imports.md).
 
 ### Tier 1 Inline Path
 
@@ -379,7 +385,7 @@ no Node evaluator and no download step.
 ### Gate Step Injection
 
 Gate steps are injected into the Setup job by `generate_setup_job()` in
-`common.rs`. When the `TriggerFiltersExtension` is active, its
+`common.rs`. When the `AdoScriptExtension` is active, its
 `setup_steps()` are collected and injected first (download + gate). When
 only Tier 1 filters are present, the inline gate step is injected directly.
 

docs/front-matter.md

@@ -234,6 +234,27 @@ becomes a `repos:` entry, with `checkout: false` added for entries
 that weren't listed under `checkout:`. Mixing the legacy fields with
 an existing `repos:` block is rejected; pick one shape.
 
+## Inlined Imports
+
+The `inlined-imports:` field controls when `{{#runtime-import ...}}`
+markers in the markdown body are resolved. It defaults to `false`.
+See [`runtime-imports.md`](runtime-imports.md) for the full marker
+syntax, path resolution rules, and runtime behavior.
+
+When `inlined-imports: false`, the compiler leaves runtime-import
+markers to be resolved on the pipeline runner. This is the default
+behavior, and it means prompt-body edits do not require recompiling the
+generated YAML.
+
+When `inlined-imports: true`, the compiler resolves all runtime-import
+markers at compile time, including the implicit top-level marker that
+normally reloads the body itself. The emitted YAML contains the fully
+expanded prompt body, so the pipeline file is self-contained.
+
+The trade-off is that the generated YAML is larger, and prompt-body
+edits require `ado-aw compile` plus committing the updated pipeline
+file.
+
 ## Filter Validation
 
 The compiler validates filter configurations at compile time and will emit

docs/runtime-imports.md

@@ -0,0 +1,88 @@
+# Runtime Imports
+
+_Part of the [ado-aw documentation](../AGENTS.md)._
+
+Runtime imports let agent prompts pull in snippet files with gh-aw-compatible
+`{{#runtime-import ...}}` markers. They are available in the markdown body and
+are controlled by the [`inlined-imports:` field](front-matter.md#inlined-imports).
+The runtime bundle that expands them is documented in [`ado-script.md`](ado-script.md).
+
+## Marker syntax
+
+Use `{{#runtime-import path}}` for a required import. If the target file is
+missing, resolution fails.
+
+```markdown
+## Repository policy
+{{#runtime-import docs/policy.md}}
+```
+
+Use `{{#runtime-import? path}}` for an optional import. If the target file is
+missing, the marker is replaced with an empty string.
+
+```markdown
+## Local notes
+{{#runtime-import? docs/local-notes.md}}
+```
+
+## Where markers can appear
+
+Authors can place runtime-import markers anywhere in the agent markdown body.
+When `inlined-imports: false` (the default), the compiler also injects an
+implicit top-level runtime-import marker that reloads the body itself at
+pipeline runtime instead of embedding it into the generated YAML. When
+`inlined-imports: true`, that implicit body marker is resolved at compile time
+along with any author-written markers.
+
+## Path resolution
+
+- **Author-written markers** must use **relative paths** rooted at the agent
+  `.md` file's directory. Absolute paths and `..` segments are rejected. This
+  protects the compile host (`ado-aw compile`, which may run on a CI agent
+  carrying privileged material like SSH keys and service-connection tokens)
+  from untrusted PR branches embedding host files into the compiled YAML —
+  e.g. `{{#runtime-import /home/runner/.ssh/id_rsa}}` or
+  `{{#runtime-import ../../../../etc/passwd}}` are both compile-time errors.
+- **Compiler-generated marker for the agent body** uses an absolute path
+  (`$(Build.SourcesDirectory)/…`) built from the trigger-repo checkout root,
+  so the runtime resolver never has to resolve a relative path. The
+  compile-time restriction does not apply here because the path is
+  tooling-generated, not author-supplied.
+
+## Single-pass behavior
+
+Runtime imports are expanded in a single pass. Imported snippets are inserted
+verbatim, and any nested `{{#runtime-import ...}}` or
+`{{#runtime-import? ...}}` markers inside those snippets are **not** expanded.
+This matches gh-aw's runtime-import behavior.
+
+## Resolver ordering
+
+The runtime-import resolver runs first. Any extension supplements that are
+appended later with `cat >>` — including SafeOutputs guidance, GitHub MCP
+guidance, runtime guidance, and cache-memory guidance — are added after import
+resolution and are left untouched.
+
+## Failure modes
+
+| Marker kind | Missing file behavior |
+|---|---|
+| `{{#runtime-import path}}` | Resolver exits with status 1 and the pipeline fails. |
+| `{{#runtime-import? path}}` | Marker is silently replaced with an empty string. |
+
+When `inlined-imports: true`, the same required/optional rules are applied at
+compile time instead of on the pipeline runner.
+
+## Implementation notes
+
+- **Runtime**: `dist/import/index.js` is ncc-bundled into `ado-script.zip`.
+  The always-on `AdoScriptExtension`'s `prepare_steps()` injects three
+  steps into the Agent job's existing `{{ prepare_steps }}` block:
+  `NodeTool@0` install, the `ado-script.zip` download/verify/extract,
+  and the `node import.js` resolver invocation. All three run on the
+  same VM as the agent — ADO jobs are VM-isolated, so the bundle must
+  be downloaded inside whichever job consumes it.
+- **Compile time**: `resolve_imports_inline()` in
+  `src/compile/extensions/ado_script.rs` performs the inline expansion
+  when `inlined-imports: true`.
+