feat(oblt-aw,docs-aw): event-scoped orchestrators reduce check noise

[fr4nc1sc0-r4m0n]

Summary

• Introduce event-scoped client templates and orchestrators (oblt-aw-event-*, docs-aw-event-*) so co-triggered routes share one aw-prelude dashboard read per GitHub event family instead of per-route prelude chains.
• Extend aw-prelude.yml with batch proceed-by-workflow evaluation (evaluate_workflow_gates.py); move dashboard and event predicates to orchestrator jobs; route workflows (oblt-aw-*, docs-aw-*) focus on agent logic only.
• Replace per-route distribution triggers with five obs and four docs event-scoped client entrypoints; remove aw-route-prelude / aw-event-context split in favor of unified prelude.

Architecture

flowchart TB
  subgraph Consumer["Consumer repo"]
    EVT["GitHub event"]
    C["trigger-*-aw-<event>.yml"]
    EVT --> C
  end
  subgraph ControlPlane["elastic/oblt-aw"]
    ORCH["*-aw-event-* orchestrator"]
    PRE["aw-prelude"]
    R["*-aw-* route"]
    C --> ORCH
    ORCH --> PRE
    ORCH -->|if: proceed + event| R
  end

Loading

Test plan

• python3 scripts/validate_aw_workflow_prelude.py
• pytest tests/test_evaluate_workflow_gates.py tests/test_build_target_operations.py tests/test_validate_aw_workflow_prelude.py
• pre-commit actionlint on changed workflows
• Merge and run distribute-client-workflow to roll out event-scoped client templates to consumer repos
• Update Backstage workflow_ref from per-route triggers to event-scoped triggers
• Verify a consumer PR shows one orchestrator check per event family (not one skipped check per route)

Related issue: https://github.com/elastic/observability-robots/issues/3614

[Copilot]

Pull request overview

This PR refactors the agentic workflow control plane to an event-scoped orchestration model, reducing “skipped check” noise by running the dashboard prelude once per GitHub event family and fanning out per-route proceed flags to route reusables.

Changes:

• Added event-scoped orchestrator reusables (oblt-aw-event-*, docs-aw-event-*) and updated client templates to call orchestrators instead of per-route reusables.
• Extended aw-prelude.yml to compute a proceed-by-workflow map via a new scripts/evaluate_workflow_gates.py helper.
• Updated route reusables (oblt-aw-*, docs-aw-*) to accept shared-proceed and related shared inputs, and refreshed documentation/tests accordingly.

Reviewed changes

Copilot reviewed 60 out of 60 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_validate_aw_workflow_prelude.py	Updates validation expectations for route workflows (shared-proceed contract; exclude orchestrators).
tests/test_evaluate_workflow_gates.py	Adds unit tests for multi-workflow gate evaluation helper.
tests/test_build_target_operations.py	Updates distribution/build tests for new event-scoped trigger template naming.
scripts/validate_aw_workflow_prelude.py	Changes CI validation from “routes must call prelude” to “routes must declare shared-proceed”; keeps registry coherence checks.
scripts/evaluate_workflow_gates.py	New script to compute proceed flags for multiple workflows in one call.
README.md	Updates quick start to describe event-scoped client + orchestrator model.
docs/workflows/oblt-aw-client-template.md	Documents the new event-scoped client model and template index.
docs/workflows/docs-aw-pr-ai-menu.md	Updates docs PR AI menu workflow documentation for orchestrator-based routing.
docs/workflows/docs-aw-client-template.md	Documents event-scoped client model for Docs workflows and migration notes.
docs/workflows/docs-aw-ai-menu.md	Updates docs issue AI menu workflow documentation for orchestrator-based routing.
docs/workflows/aw-prelude.md	Updates the prelude contract: control-plane-workflows input and proceed-by-workflow output.
docs/onboarding/adopting-agentic-workflows.md	Updates onboarding guidance to reflect route contracts + orchestrator responsibilities.
AGENTS.md	Updates conventions to reflect route vs orchestrator responsibilities and shared-proceed contract.
.github/workflows/oblt-aw-security-triage.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-security-fixer.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-security-detector.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-triage.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-fixer.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-detector.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-mention-in-issue.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-issue-triage.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-issue-fixer.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-event-status.yml	Adds status-family orchestrator that calls prelude once and routes to the status route.
.github/workflows/oblt-aw-event-schedule.yml	Adds schedule/workflow_dispatch-family orchestrator with shared prelude and route fanout.
.github/workflows/oblt-aw-event-pull-request.yml	Adds pull_request-family orchestrator with shared prelude and route fanout.
.github/workflows/oblt-aw-event-issues.yml	Adds issues/workflow_dispatch-family orchestrator with shared prelude and route fanout.
.github/workflows/oblt-aw-event-issue-comment.yml	Adds issue_comment-family orchestrator with shared prelude and route fanout.
.github/workflows/oblt-aw-estc-pr-buildkite-detective.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-duplicate-issue-detector.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-dependency-review.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-automerge.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-autodoc.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/oblt-aw-agent-suggestions.yml	Converts route reusable to accept shared inputs instead of running prelude internally.
.github/workflows/docs-aw-pr-ai-menu.yml	Converts docs route reusable to accept shared inputs and gate jobs on inputs.shared-proceed.
.github/workflows/docs-aw-pr-ai-menu-collect.yml	Converts docs collect route reusable to accept shared inputs and gate job on inputs.shared-proceed.
.github/workflows/docs-aw-event-workflow-run.yml	Adds docs workflow_run-family orchestrator with shared prelude and route fanout.
.github/workflows/docs-aw-event-pull-request.yml	Adds docs pull_request-family orchestrator with shared prelude and route fanout.
.github/workflows/docs-aw-event-issues.yml	Adds docs issues/workflow_dispatch-family orchestrator with shared prelude and route fanout.
.github/workflows/docs-aw-event-issue-comment.yml	Adds docs issue_comment-family orchestrator with shared prelude and route fanout.
.github/workflows/docs-aw-ai-menu.yml	Converts docs route reusable to accept shared inputs and gate jobs on inputs.shared-proceed.
.github/workflows/aw-prelude.yml	Changes prelude to accept control-plane-workflows and output proceed-by-workflow using the new Python helper.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-status.yml	Updates obs status client template to call the status orchestrator.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-security-fixer.yml	Removes per-route obs security-fixer client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-security-detector.yml	Removes per-route obs security-detector client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-schedule.yml	Updates obs schedule client template to call the schedule orchestrator and adds workflow_dispatch.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-triage.yml	Removes per-route obs RNA triage client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-fixer.yml	Removes per-route obs RNA fixer client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-detector.yml	Removes per-route obs RNA detector client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-pull-request.yml	Updates obs pull_request client template to call the pull_request orchestrator.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issues.yml	Updates obs issues client template to call the issues orchestrator and adds workflow_dispatch.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issue-triage.yml	Removes per-route obs issue-triage client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issue-fixer.yml	Removes per-route obs issue-fixer client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issue-comment.yml	Updates obs issue_comment client template to call the issue_comment orchestrator.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-duplicate-issue-detector.yml	Removes per-route obs duplicate-detector client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-dependency-review.yml	Removes per-route obs dependency-review client template (replaced by event-scoped templates).
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-agent-suggestions.yml	Removes per-route obs agent-suggestions client template (replaced by event-scoped templates).
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-workflow-run.yml	Updates docs workflow_run client template to call the workflow_run orchestrator.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-pull-request.yml	Updates docs pull_request client template to call the pull_request orchestrator.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-issues.yml	Updates docs issues client template to call the issues orchestrator.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-issue-comment.yml	Adds docs issue_comment client template to call the issue_comment orchestrator.

Comments suppressed due to low confidence (1)

.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-workflow-run.yml:28

• This client workflow now calls the orchestrator for every workflow_run completion (including failures/cancels). Previously it avoided running on non-successful collects; keeping that guard prevents unnecessary orchestrator/prelude work and reduces check noise on failed collect runs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fr4nc1sc0-r4m0n]

@copilot fix the precommit checks

[Copilot]

@copilot fix the precommit checks

Fixed the failing pre-commit check by applying the ruff-format update in scripts/evaluate_workflow_gates.py (commit ab71bf2). I also re-ran pre-commit locally and it now passes.