diff --git a/AGENTS.md b/AGENTS.md index 41667fac..94145ee4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -268,6 +268,7 @@ fail-closed and only pauses when the agent actually proposed a reviewed output. │ ├── approval-summary/ # Safe-outputs summary renderer (bundled to approval-summary.js; end-of-Agent-job summary tab) │ ├── github-app-token/ # GitHub App token minter (bundled to github-app-token.js; mints installation token in Agent + Detection when engine.github-app-token is set) │ ├── executor-e2e/ # Stage 3 safe-output E2E test harness (not a bundle; runs deterministic scenarios against a real ADO project and files a GitHub issue on failure) +│ ├── trigger-e2e/ # Trigger-condition E2E harness (not a bundle; TypeScript port of filter_ir.rs spec construction used to queue real ADO builds exercising every gate predicate; includes a drift guard that deep-compares the hand-authored FACT_META mirror against the committed fact-catalog.gen.json) │ ├── prepare-pr-base/ # create-pull-request base-ref preparer (bundled to prepare-pr-base.js; fetches/deepens target branch so mcp.rs finds a diff base on shallow-default pools — issue #1413; emitted in BOTH the Agent job and the SafeOutputs job before the executor's worktree add — issue #1453) │ └── shared/ # Shared modules across bundles (auth, ado-client, env-facts, types.gen.ts) ├── tests/ # Integration tests and fixtures @@ -353,7 +354,7 @@ index to jump to the right page. `check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`, `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). + deprecated hidden alias; `export-gate-schema` and `export-fact-catalog` are hidden build-time tools). - [`docs/agency-plugin.md`](docs/agency-plugin.md) — the Agency / Claude Code plugin (`agency/plugins/ado-aw/`): canonical layout, six skills, `mcp-author` wiring, the self-contained root marketplace catalogs, `init --agency` diff --git a/docs/ado-script.md b/docs/ado-script.md index 10a7dd81..ee2f2537 100644 --- a/docs/ado-script.md +++ b/docs/ado-script.md @@ -617,6 +617,17 @@ The Rust subcommand that emits the schema is intentionally hidden: cargo run -- export-gate-schema --output schema/gate-spec.schema.json ``` +A second hidden command exports the fact catalog JSON (kind/failure_policy/dependencies +for every gate `Fact`), used as a drift guard for the `FACT_META` mirror in +`scripts/ado-script/src/trigger-e2e/gate-spec.ts`: + +```sh +cargo run -- export-fact-catalog --output schema/fact-catalog.gen.json +``` + +`npm run codegen` runs both export stages. See [`docs/cli.md`](cli.md#hidden-build-time-tools) +for the full option reference of both hidden commands. + ## How the bundles are wired into emitted pipelines `AdoScriptExtension` diff --git a/docs/cli.md b/docs/cli.md index 4bc2dbe7..696e335a 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -187,6 +187,10 @@ These commands are not shown in `--help` but are available for contributors work - `--output, -o ` - Write the schema to a file instead of stdout. Parent directories are created automatically. - See [`docs/ado-script.md`](ado-script.md) for how this command fits into the ado-script build workflow (`cargo run -- export-gate-schema --output schema/gate-spec.schema.json`). +- `export-fact-catalog` - Export the fact catalog JSON (kind/failure_policy/dependencies for every gate `Fact`). Used as a drift guard for the hand-maintained `FACT_META` mirror in `scripts/ado-script/src/trigger-e2e/gate-spec.ts` — `npm run codegen` regenerates `fact-catalog.gen.json` from this command, and the `gate-spec.test.ts` drift test deep-compares the two. + - `--output, -o ` - Write the catalog to a file instead of stdout. Parent directories are created automatically. + - Example: `cargo run -- export-fact-catalog --output schema/fact-catalog.gen.json` + ## Pipeline IR Reference The compiler builds typed Azure DevOps pipeline IR and lowers it through one YAML emitter. The canonical Setup → Agent → Detection → SafeOutputs → Teardown shape, plus the optional always-running Conclusion job when `safe-outputs:` is configured, lives in `agentic_pipeline.rs` (shared by every target); target-specific builders (`standalone_ir.rs`, `onees_ir.rs`, `job_ir.rs`, and `stage_ir.rs`) own only the per-target envelope (pipeline shape, template parameters, 1ES wrapping).