Skip to content

docs: consolidate documentation drift fixes from auditor backlog #1189

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamesadevine merged 1 commit into from
Jun 24, 2026
Merged

docs: consolidate documentation drift fixes from auditor backlog #1189

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 19 additions & 11 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,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
│ │ │ ├── ado_script.rs # Always-on ado-script extension (gate evaluator + runtime-import resolver + exec-context-pr precompute, per-job downloads)
│ │ │ ├── ado_script.rs # Always-on ado-script extension (gate evaluator + runtime-import resolver + execution-context precomputes, per-job downloads)
│ │ │ ├── exec_context/ # Always-on execution-context extension (issue #860)
│ │ │ │ ├── mod.rs # ExecContextExtension; CompilerExtension impl; contributor fan-out
│ │ │ │ ├── contributor.rs # Internal ContextContributor trait + Contributor enum
Expand Down Expand Up @@ -223,12 +223,19 @@ 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, import.js, exec-context-pr.js, exec-context-pr-synth.js
│ └── ado-script/ # TypeScript workspace for bundled gate/import helpers plus execution-context bundles
│ └── src/
│ ├── gate/ # Gate evaluator source (bundled to gate.js)
│ ├── import/ # Runtime prompt resolver source (bundled to import.js)
│ ├── exec-context-pr/ # PR-context precompute source (bundled to exec-context-pr.js)
│ ├── exec-context-pr-synth/ # Synthetic-PR resolver source (bundled to exec-context-pr-synth.js)
│ ├── exec-context-manual/ # Manual-run context source (bundled to exec-context-manual.js)
│ ├── exec-context-pipeline/ # Pipeline-completion context source (bundled to exec-context-pipeline.js)
│ ├── exec-context-ci-push/ # CI/push context source (bundled to exec-context-ci-push.js)
│ ├── exec-context-workitem/ # Linked work-item context source (bundled to exec-context-workitem.js)
│ ├── exec-context-schedule/ # Scheduled-run context source (bundled to exec-context-schedule.js)
│ ├── exec-context-pr-checks/ # PR validation checks context source (bundled to exec-context-pr-checks.js)
│ ├── exec-context-repo/ # Repository identity context source (bundled to exec-context-repo.js)
│ └── shared/ # Shared modules across bundles (auth, ado-client, env-facts, types.gen.ts)
├── tests/ # Integration tests and fixtures
├── docs/ # Per-concept reference documentation (see index below)
Expand All @@ -241,7 +248,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, runtime import resolver, PR-context precompute, and synthetic-PR resolver; see [`docs/ado-script.md`](docs/ado-script.md).
- **Bundled scripts**: TypeScript + ncc (`scripts/ado-script/`) — compiled gate evaluator, runtime import resolver, and execution-context precompute 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
Expand Down Expand Up @@ -281,11 +288,9 @@ index to jump to the right page.
- [`docs/targets.md`](docs/targets.md) — target platforms: `standalone`,
`1es`, `job`, and `stage`.
- [`docs/execution-context.md`](docs/execution-context.md) — built-in
`aw-context/` precompute (issue #860): PR target-branch fetch +
merge-base resolution, `base.sha`/`head.sha` artefacts, prompt
fragment with pre-filled ADO MCP identifiers, auto-extension of the
agent's bash allow-list with read-only git commands; configured via
the `execution-context:` front-matter block.
`aw-context/` precompute contributors for PR, manual, pipeline,
CI/push, work-item, scheduled, PR-check, and repository context;
configured via the `execution-context:` front-matter block.
- [`docs/safe-outputs.md`](docs/safe-outputs.md) — full reference for every
safe-output tool agents can use to propose actions (PRs, work items, wiki
pages, comments, etc.) plus their per-agent configuration.
Expand All @@ -310,7 +315,9 @@ index to jump to the right page.
- [`docs/ir.md`](docs/ir.md) — typed Azure DevOps pipeline IR (`Pipeline`, jobs/stages/steps, output refs, graph pass, lowering, target builders, and the public JSON summary consumed by agent-facing tooling).
- [`docs/cli.md`](docs/cli.md) — `ado-aw` CLI commands (`init`, `compile`,
`check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`,
`remove`, `list`, `status`, `run`, `audit`; `configure` is a deprecated hidden alias).
`remove`, `list`, `status`, `run`, `audit`, `mcp-author`, `trace`,
`inspect`, `graph`, `whatif`, `lint`, `catalog`; `configure` is a
deprecated hidden alias and `export-gate-schema` is a hidden build-time tool).
- [`docs/audit.md`](docs/audit.md) — `ado-aw audit`: accepted build-id / URL
forms, artifact layout, cache behavior, rejection tracing, and `AuditData`
report shape.
Expand All @@ -335,8 +342,9 @@ index to jump to the right page.
rewrite on breaking-change updates, contributor workflow for
adding codemods.
- [`docs/ado-script.md`](docs/ado-script.md) — `ado-script` workspace
(`scripts/ado-script/`): the bundled TypeScript runtime helpers (today:
`gate.js`, `import.js`, `exec-context-pr.js`, `exec-context-pr-synth.js`), schemars-driven type codegen, and the A2 design decision.
(`scripts/ado-script/`): the bundled TypeScript runtime helpers
(`gate.js`, `import.js`, and the execution-context `exec-context-*.js`
bundles), schemars-driven type codegen, and the A2 design decision.
- [`docs/local-development.md`](docs/local-development.md) — local development
setup notes.

Expand Down
14 changes: 8 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,9 +271,10 @@ the service connections. Approve the permissions and the pipeline is ready.
| `teardown` | list | — | Separate job after safe outputs |
| `network` | object | — | Additional allowed/blocked hosts |
| `inlined-imports` | boolean | `false` | When `true`, resolves all `{{#runtime-import …}}` markers at compile time; the generated YAML is self-contained but prompt-body edits require recompilation. See [runtime-imports.md](docs/runtime-imports.md). |
| `env` | map | — | Workflow-level environment variables (reserved, not yet implemented) |
| `execution-context` | object | — | Configuration for the always-on execution-context plugin (PR context precompute). See [execution-context.md](docs/execution-context.md). |
| `env` | map | `{}` | Workflow-level environment variables (accepted by parser, not yet forwarded to compiled pipeline output) |
| `execution-context` | object | — | Configuration for the always-on execution-context plugin (`aw-context/` contributors). See [execution-context.md](docs/execution-context.md). |
| `supply-chain` | object | — | Internal feed/registry mirror settings for compiler/runtime artifacts. See [supply-chain.md](docs/supply-chain.md). |
| `ado-aw-debug` | object | — | Debug-only knobs for local/dogfood diagnostics. See [ado-aw-debug.md](docs/ado-aw-debug.md). |

### Markdown Body

Expand Down Expand Up @@ -440,7 +441,7 @@ actions, and the executor processes them after threat analysis.
| `reply-to-pr-comment` | Replies to an existing PR review comment thread |
| `resolve-pr-thread` | Resolves or updates the status of a PR review thread |
| `submit-pr-review` | Submits a review vote on a pull request |
| `update-pr` | Updates pull request metadata (reviewers, labels, auto-complete, etc.) |
| `update-pr` | Updates pull request metadata (reviewers, labels, auto-complete, vote, update-description) |
| `link-work-items` | Links two ADO work items together |
| `queue-build` | Queues a pipeline build by definition ID |
| `create-git-tag` | Creates a git tag on a repository ref |
Expand Down Expand Up @@ -611,7 +612,8 @@ index to jump to the right page.
- [`docs/targets.md`](docs/targets.md) — target platforms: `standalone`, `1es`,
`job`, and `stage`.
- [`docs/execution-context.md`](docs/execution-context.md) — built-in
`aw-context/` precompute configuration (PR context staging + merge-base facts).
`aw-context/` precompute contributors for PR, manual, pipeline, CI/push,
work-item, scheduled, PR-check, and repository context.
- [`docs/safe-outputs.md`](docs/safe-outputs.md) — full reference for every
safe-output tool plus their per-agent configuration.
- [`docs/safe-output-permissions.md`](docs/safe-output-permissions.md) —
Expand Down Expand Up @@ -640,8 +642,8 @@ index to jump to the right page.
- [`docs/codemods.md`](docs/codemods.md) — front-matter codemod framework
(detection-based source rewrites on breaking-change updates).
- [`docs/ado-script.md`](docs/ado-script.md) — `scripts/ado-script/` workspace
(bundled TypeScript runtime helpers: `gate.js`, `import.js`,
`exec-context-pr.js`, `exec-context-pr-synth.js`).
(bundled TypeScript runtime helpers: `gate.js`, `import.js`, and the
execution-context `exec-context-*.js` bundles).
- [`docs/extending.md`](docs/extending.md) — adding new CLI commands, compile
targets, front-matter fields, typed IR extensions, safe-output tools,
first-class tools, and runtimes.
Expand Down
75 changes: 59 additions & 16 deletions docs/ado-script.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
`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. Today it produces four bundles:
pipeline** as runtime helpers. Today it produces eleven bundles:

- `gate.js` — trigger-filter gate evaluator (Setup job).
- `import.js` — runtime prompt resolver described in
Expand All @@ -26,6 +26,25 @@ pipeline** as runtime helpers. Today it produces four bundles:
`aw-context/pipeline/upstream-*` files plus a `## Pipeline-completion
context` prompt fragment (Agent job; see
[`execution-context.md`](execution-context.md)).
- `exec-context-ci-push.js` — CI/push precompute that stages "since
last green build" diff context under `aw-context/ci-push/` (Agent
job; see [`execution-context.md`](execution-context.md)).
- `exec-context-workitem.js` — PR-linked work-item precompute that
stages linked work-item metadata and descriptions under
`aw-context/workitem/` (Agent job; see
[`execution-context.md`](execution-context.md)).
- `exec-context-schedule.js` — Scheduled-run precompute that stages
"since last successful scheduled run" context under
`aw-context/schedule/` (Agent job; see
[`execution-context.md`](execution-context.md)).
- `exec-context-pr-checks.js` — PR Build Validation checks precompute
that stages succeeded/failing check results under
`aw-context/pr/checks/` (Agent job; see
[`execution-context.md`](execution-context.md)).
- `exec-context-repo.js` — Repository identity precompute that stages
branch, SHA, last release tag, and commits-since-tag facts under
`aw-context/repo/` (Agent job; see
[`execution-context.md`](execution-context.md)).

> **Internal-only.** `ado-script` is not a user-facing front-matter
> feature. Authors never write an `ado-script:` block in their agent
Expand Down Expand Up @@ -72,10 +91,9 @@ because the compiler always embeds an absolute marker path and
not re-expanded).

The bundle lives at `import.js` and ships in the same
`ado-script.zip` release asset as `gate.js`, `exec-context-pr.js`,
`exec-context-pr-synth.js`, `exec-context-manual.js`, and
`exec-context-pipeline.js`, so pipelines download it through the
same Agent-job asset flow.
`ado-script.zip` release asset as `gate.js` and the ten
`exec-context-*.js` bundles listed in the workspace layout, so
pipelines download it through the same Agent-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.

Expand Down Expand Up @@ -381,25 +399,50 @@ scripts/ado-script/
│ ├── exec-context-manual/ # exec-context-manual.js entry point + manual-context precompute
│ │ ├── index.ts # main(): collect PARAM_* env vars → JSON snapshot → prompt fragment
│ │ └── __tests__/ # unit tests for success / failure / sanitisation paths
│ └── exec-context-pipeline/ # exec-context-pipeline.js entry point + pipeline-completion precompute
│ ├── index.ts # main(): validate TriggeredBy ids → fetch upstream Build via REST → stage + prompt
│ └── __tests__/ # unit tests for validate / success / failure / sanitisation paths
│ ├── exec-context-pipeline/ # exec-context-pipeline.js entry point + pipeline-completion precompute
│ │ ├── index.ts # main(): validate TriggeredBy ids → fetch upstream Build via REST → stage + prompt
│ │ └── __tests__/ # unit tests for validate / success / failure / sanitisation paths
│ ├── exec-context-ci-push/ # exec-context-ci-push.js entry point + CI/push diff context
│ │ ├── index.ts # main(): find last green build → stage changed files / commits → prompt
│ │ └── __tests__/ # unit tests for success / fallback / sanitisation paths
│ ├── exec-context-workitem/ # exec-context-workitem.js entry point + PR-linked work-item context
│ │ ├── index.ts # main(): fetch linked WIs → stage metadata + descriptions → prompt
│ │ └── __tests__/ # unit tests for fetch / truncation / sanitisation paths
│ ├── exec-context-schedule/ # exec-context-schedule.js entry point + scheduled-run diff context
│ │ ├── index.ts # main(): find prior scheduled success → stage changed files / commits → prompt
│ │ └── __tests__/ # unit tests for success / no-baseline / sanitisation paths
│ ├── exec-context-pr-checks/ # exec-context-pr-checks.js entry point + PR validation checks context
│ │ ├── index.ts # main(): fetch policy/build checks → stage failing/succeeded JSON → prompt
│ │ └── __tests__/ # unit tests for checks filtering / sanitisation paths
│ └── exec-context-repo/ # exec-context-repo.js entry point + repository identity context
│ ├── index.ts # main(): stage branch/SHA/tag/commits-since-tag facts → prompt
│ └── __tests__/ # unit tests for identity / tag fallback / sanitisation paths
├── test/ # End-to-end smoke tests (gate, import, exec-context-pr)
├── gate.js # ncc bundle output (gitignored)
├── import.js # ncc bundle output (gitignored)
├── exec-context-pr.js # ncc bundle output (gitignored)
├── exec-context-pr-synth.js # ncc bundle output (gitignored)
├── exec-context-manual.js # ncc bundle output (gitignored)
└── exec-context-pipeline.js # ncc bundle output (gitignored)
├── exec-context-pipeline.js # ncc bundle output (gitignored)
├── exec-context-ci-push.js # ncc bundle output (gitignored)
├── exec-context-workitem.js # ncc bundle output (gitignored)
├── exec-context-schedule.js # ncc bundle output (gitignored)
├── exec-context-pr-checks.js # ncc bundle output (gitignored)
└── exec-context-repo.js # ncc bundle output (gitignored)
```

The release workflow (`.github/workflows/release.yml`) runs
`npm ci && npm run build`, then zips `scripts/ado-script/gate.js`,
`scripts/ado-script/import.js`,
`scripts/ado-script/exec-context-pr.js`,
`scripts/ado-script/exec-context-pr-synth.js`,
`scripts/ado-script/exec-context-manual.js`, and
`scripts/ado-script/exec-context-pipeline.js` into the
`scripts/ado-script/exec-context-manual.js`,
`scripts/ado-script/exec-context-pipeline.js`,
`scripts/ado-script/exec-context-ci-push.js`,
`scripts/ado-script/exec-context-workitem.js`,
`scripts/ado-script/exec-context-schedule.js`,
`scripts/ado-script/exec-context-pr-checks.js`, and
`scripts/ado-script/exec-context-repo.js` into the
`ado-script.zip` release asset. Pipelines download that asset at
runtime by URL pinned to the compiler's `CARGO_PKG_VERSION`, verify
its SHA-256 against the `checksums.txt` asset, then extract.
Expand Down Expand Up @@ -500,10 +543,10 @@ The rows below assume the synthetic-PR resolver is **not** active
|---|---|---|---|
| no gate | none | (none) | (none) |
| no gate | `inlined-imports: false` only | (no Setup job) | install + download + resolver |
| no gate | `on.pr` execution-context only | (no Setup job) | install + download + exec-context-pr |
| no gate | both | (no Setup job) | install + download + resolver + exec-context-pr |
| no gate | execution-context contributor(s) only | (no Setup job) | install + download + exec-context bundle(s) |
| no gate | resolver + execution-context | (no Setup job) | install + download + resolver + exec-context bundle(s) |
| gate | none | install + download + gate | (none) |
| gate | any combination of resolver / exec-pr | install + download + gate | install + download + (resolver?) + (exec-context-pr?) |
| gate | any combination of resolver / exec-context | install + download + gate | install + download + (resolver?) + (exec-context bundle(s)?) |

When the synthetic-PR resolver **is** active
(`pr_trigger_for_synth = Some(_)`, i.e. `synthetic_pr_active()` is
Expand Down Expand Up @@ -582,8 +625,8 @@ npm ci # one-time
npm run codegen # regenerate types.gen.ts (compiles ado-aw first)
npm test # vitest unit tests
npm run typecheck # strict tsc --noEmit
npm run build # ncc-bundle to gate.js
npm run test:smoke # build + smoke test the bundle end-to-end
npm run build # ncc-bundle all ado-script JS helpers
npm run test:smoke # build + smoke test the bundles end-to-end
```

The Rust-side E2E gate test compiles a real agent, extracts the
Expand Down
Loading