Approved: one agent-ingress stub per repo — webhooks are not the lever (ADR-0007)

[don-petry]

Status: approved. The decision is recorded as ADR-0007 (accepted) in
#1710. This Discussion is open for the deeper review — the ADR
is append-only, so anything that changes direction here becomes ADR-0008 superseding 0007,
not an edit.

The question

Could an org- or repo-level webhook invoke our persona / agent workflows directly across
the fleet, replacing the per-repo thin caller stubs (ADR-0001)? Specifically: can we trigger
agents more easily across all repos from one place; are all our action types webhookable; and
do authN / authZ / secrets work the same way as they do inside a workflow?

The decided approach

Collapse each consumer repo's per-role caller stubs into one
.github/workflows/agent-ingress.yml. Do not stand up an off-GitHub webhook receiver at the
current fleet size (8 consumer repos per scripts/lib/consumer-manifest.json, 9–13 pinned
refs each).

The reframe that decided it: a stub is doing three separable jobs — ingress (subscribe to
the event), enrollment (this repo opted in), and the ring pin (ADR-0002). A webhook
replaces only the first, and the first is the cheapest to fix without one.

Answers to the three questions

1. Can webhooks trigger agents more easily across all repos? Not by themselves — a
webhook is not an executor. An org webhook delivers JSON to an endpoint we would have to
host; it cannot start a workflow. It can only call back into GitHub via
repository_dispatch, or run the agent on compute we own. And we already run hub-and-spoke:
persona-mention.yml → repository_dispatch → persona-runner.yml serves all nine personas
from one runtime (Bridge A, docs/agentic-interaction-model.md §5). The centralization is
already in hand. What is not consolidated is the ingress file — and consolidating a
doorbell needs no receiver.

2. Are all our action types webhookable? No — roughly 40% at best. From the CI-verified
§4 classification table (35 agentic rows):

Class	Rows	Webhookable
1 — event-driven	15 (14 real subscriptions; initiative-planner.yml is workflow_dispatch-only)	yes
2 — backstop timer	3	fast path yes, timer half no
3 — cadence-origin	17	no — no webhook exists for "it is Monday"

Gaps beyond the count: pull_request_target (dependabot-automerge, add-to-project) is an
Actions-only construct — a receiver sees plain pull_request and inherits full secret
access on fork PRs, which Actions currently withholds; check_suite:requested/rerequested
is GitHub Apps only, not org webhooks; required checks (holdout-guard,
duplicate-decl-gate, test-deletion-guard) must stay in-repo because a hub run posts no
check on the target PR unless we synthesize commit statuses; and workflow_call is not an
event at all, so the reusable tier is unaffected either way.

3. Do authN / authZ / secrets work the same? No — four deltas.

1. No GITHUB_TOKEN. Today it is per-run, repo-scoped, auto-expiring, and shaped by the
   job's permissions: block. A GitHub App installation token is genuinely better scoped
   than a PAT and would fix the fine-grained-PAT single-owner limit §5 already flags for
   cross-org — but the read/write split in persona-runner-reusable.yml (the agent holds
   github.token and physically cannot post; the workflow holds the PAT and posts) is
   enforced by the runtime today and would have to be hand-rebuilt.
2. Org Actions secrets are unreachable from a receiver. secrets: inherit has no
   analogue; CLAUDE_CODE_OAUTH_TOKEN, GH_PAT_DON_PETRY, GOOGLE_API_KEY would need a
   second store and a second rotation path. Keep execution in Actions and this delta is zero.
3. The recursion brake disappears. §5's rule — events authored by GITHUB_TOKEN trigger
   nothing — is a free loop-guard. A receiver has none: every comment it posts is a live
   event it receives back. After docs/postmortems/2026-06-pr-860-runaway.md (1,481
   acknowledgements in 4.5 hours), the marker guard would go from belt-and-braces to sole
   defense.
4. Identity churn. Personas post as don-petry (runtime.identity.credential, checked
   by verify-persona-identity.sh); donpetry-bot is deliberately a separate review-only
   account. An App changes the actor on every comment, approval and push, and
   approval-by-actor is already load-bearing under the last-push rule. That is its own
   change, not a rider on an ingress change.

What ADR-0007 actually binds

• One ingress per repo — the only entrypoint for event-driven (Class 1) roles; its on:
  block is the union of the collapsed roles' triggers.
• A job-level if: may act as an event filter and only as an event filter —
  github.event_name, github.event.action, payload fields as a pure predicate. Anything
  reaching for repo state is logic and belongs in the reusable. One job per role is required,
  not stylistic: each role needs its own permissions: block and its own channel pin, and a
  single dispatching job would have to grant the union of every role's permissions.
• The ADR-0002 ring pin moves one tier down, it does not disappear — per-role channel
  tags become per-job pins in the ingress.
• Carve-outs: pull_request_target roles keep their own stub; Class 2/3 timers keep
  theirs; non-agentic CI and gate workflows are out of scope.
• ADR-0001 is extended, not superseded — it fixed the stub↔reusable boundary and is
  silent on ingress. That silence was the actual finding.

Costs we accepted with our eyes open

• Per-repo blast radius becomes total. One bad edit to agent-ingress.yml disables every
  event-driven agent in that repo, where today a broken dev-lead.yml leaves pr-review
  alive. caller_stub_freeze.sh becomes correspondingly load-bearing.
• Per-repo, per-role staging is lost — a repo with the ingress reaches every role routed
  by it. Same trade ADR-0006 made for personas, made knowingly a second time.
• Run attribution coarsens. The fleet monitor and health scans sample by run_workflow;
  collapsing many workflow names into one reproduces the attribution problem ADR-0006 fact 3
  names for personas. Job names must carry the role, and monitors keying on workflow name
  must retarget to job level in the same change.
• paths: filters move down a tier (dependency-advisory.yml), so union subscription
  starts more runs with mostly-skipped jobs — free in minutes, not in log legibility.
• Branch-protection check names change and must be renamed in the same change as the
  first collapse, or protection blocks merges on a check that no longer exists.

Not foreclosed

The ADR states the reopening triggers for the webhook option: the fleet outgrowing a stub
fanout (roughly, when the eight-file edit is itself the bottleneck), a need for events Actions
cannot subscribe to inline, or cross-org routing that fine-grained PATs cannot span. Reopening
means a new ADR, because it moves the boundary this one just set.

---

Delivery scope (refined 2026-09-08)

Note on the ideation pass. The discussion: [created] bridge fired
feature-ideation.yml on this Discussion, but the ideate job failed before the BMAD
Analyst ran — Install Python jsonschema could not open
.feature-ideation-tooling/scripts/feature-ideation-requirements.txt at the pinned
refs/tags/v1 sparse checkout (run
34182110246).
This is pre-existing — every scheduled feature-ideation run has failed since
2026-08-14. There is therefore no ideation input to fold in, and the scope below is
architect-authored, not ideation-derived. The broken ideation tooling is tracked
separately and is not in this initiative's scope.

Scope of this initiative — S1: make the ingress collapsible, then pilot it once

This initiative delivers the enabling work plus a single-repo pilot. Fleet-wide rollout
across all 8 consumer repos is deliberately a separate, later initiative gated on the
pilot's evidence.

1. Canonical agent-ingress.yml template + router shape. Author the template under the
   standards path the other org templates use, with one job per role, each carrying its own
   permissions: block and its own ADR-0002 channel pin. No repo adopts it in this story.
2. if:-as-event-filter checker. ADR-0007 loosens ADR-0001 in exactly one place, so
   that loosening gets an automated check: a job-level if: in a caller stub may reference
   only github.event_name, github.event.action, and event-payload fields used as a pure
   predicate. Anything reaching for repo state fails the check. Pure-logic + bats per
   ADR-0004.
3. Teach validate-caller-inputs about multi-ref forwarding. The [#1052 A] CI guard: forwarded caller inputs ⊆ declared inputs at the pinned @ref (+ #1034 regression) #1253 check assumes one
   stub forwards to one pinned reusable; the ingress forwards to several. Extend it to
   validate every uses:/with: pair in one file against its own pinned ref's declared
   workflow_call.inputs.
4. Retarget caller_stub_freeze.sh to the ingress path. One file, one byte-identity
   baseline. The freeze becomes more load-bearing under ADR-0007, not less.
5. Retarget fleet_stub_drift.sh and template_stub_drift.sh. Both key on per-role stub
   paths today; they must classify ALIGNED / DRIFTED / MISSING against the single ingress
   path without losing per-role visibility in the report.
6. Move run attribution from workflow name to job name. fleet_monitor.sh,
   pr_review_health.sh and the health scans sample by run_workflow; collapsing many
   workflow names into one reproduces the attribution problem ADR-0006 fact 3 names for
   personas. Job names must carry the role and the monitors must key on them.
7. Pilot: collapse petry-projects/.github-private behind one ingress. The dogfood repo
   only. Includes the branch-protection required-check renames, which must land in the same
   change or protection blocks merges on a check name that no longer exists. Excludes
   pull_request_target roles and Class 2/3 timers per the ADR carve-outs.
8. Update the §4 interaction-model table and the interaction contracts. The CI-verified
   table in docs/agentic-interaction-model.md and interaction-contracts/*.yml must move
   in the same PR as the pilot collapse, or validate-interaction-model fails.

Initiative success metric

Primary: in the pilot repo, the count of Class 1 agentic caller-stub files drops from its
current value to 1, and every collapsed role demonstrably fires on its subscribed event
at least once after the collapse — evidence is one linked run per collapsed role, recorded
on the pilot story before it closes. A collapse that reduces file count but silently stops a
role from firing is a failure, not a partial success.

Secondary: zero net change in required-check outcomes on the pilot repo's next 10 merged
PRs (no check lost, no check newly blocking).

Cost cap

≤ 60 agent runs and ≤ USD 40 of engine spend across the whole initiative. The pilot is
one repo; if the pilot alone exceeds half that budget, stop and re-scope rather than
continuing to the fleet-rollout initiative.

Prerequisites (known, not open questions)

• ADR-0007 must be merged — docs(adr): ADR-0007 — one agent-ingress stub per repo, not one stub per role #1710. Every story below cites
  it as the governing decision, so it is a hard blocked_by for story 1.
• Branch-protection edits on the pilot repo need admin rights; the required-check rename in
  story 7 cannot be done by an agent alone and needs a human step.

Open questions — advisory, do NOT bake into acceptance criteria

These are genuinely unresolved. Per the planner's rubric they belong here, not inside an AC,
and they are non-blocking — the S1 scope above is buildable without answering them.

1. One ingress file, or a small number grouped by permission profile? ADR-0007 says one.
   The cost is total per-repo blast radius, which is the cost I am least comfortable with.
   Story 7's pilot is the evidence that should settle it — if the answer changes, that is
   ADR-0008 superseding 0007, not an edit.
2. Do per-job ADR-0002 pins preserve ring promotion in practice, or recreate the
   channel-skew defect (feat: implement issue #1031 — fix(#844): plumb LSP_PILOT_ENABLED env + decouple capture from LSP wiring so the pilot A/B runs in CI #1034 / epic fix(ci): prevent channel-skew workflow breakage — guard forwarded inputs vs pinned refs + codify the pinning rules (post-#1034) #1052) with more pinned surfaces per file? Story 3 is
   where this would first show up.
3. How do the required-check renames sequence across 8 repos without a merge freeze?
   Out of S1 scope by construction — this is the fleet-rollout initiative's problem, and
   story 7 should record what the single-repo rename actually cost as input to it.

Explicitly out of scope

• Fleet-wide rollout beyond the pilot repo (separate initiative, gated on the metric above).
• Any off-GitHub webhook receiver. ADR-0007 states the reopening triggers; reopening means a
  new ADR, not a story here.
• Fixing feature-ideation.yml's broken tooling checkout — real, tracked separately.
• Migrating agent identity to a GitHub App. Named in the ADR as its own change precisely so
  it does not ride along on an ingress change.

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #1723 — Implement ADR-0007: collapse per-role caller stubs into one agent-ingress.yml per repo

6 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Author the agent-ingress.yml canonical structure and freeze the if:-as-event-filter boundary #1724 (M) — [Phase 1] Author the agent-ingress.yml canonical structure and freeze the if:-as-event-filter boundary
• [Phase 2] Make caller_stub_freeze and validate-caller-inputs ingress-aware (job-scoped freeze + if:-as-event-filter check) #1725 (M) — [Phase 2] Make caller_stub_freeze and validate-caller-inputs ingress-aware (job-scoped freeze + if:-as-event-filter check)
• [Phase 2] Retarget fleet drift/remediate tooling to per-job extraction (never resurrect a collapsed stub) #1726 (L) — [Phase 2] Retarget fleet drift/remediate tooling to per-job extraction (never resurrect a collapsed stub)
• [Phase 2] Retarget run attribution to job/role level so the collapse doesn't blind the fleet monitor #1727 (M) — [Phase 2] Retarget run attribution to job/role level so the collapse doesn't blind the fleet monitor
• [Phase 2] Teach the interaction-model section 4 table and validate-interaction-model about a multi-role ingress file #1728 (M) — [Phase 2] Teach the interaction-model section 4 table and validate-interaction-model about a multi-role ingress file
• [Phase 3] Collapse the first repo's Class-1 event-driven stubs into agent-ingress.yml and rename the required checks #1729 (M) — [Phase 3] Collapse the first repo's Class-1 event-driven stubs into agent-ingress.yml and rename the required checks

Open questions for review:

• ADR-0007 binds 'exactly one agent-ingress.yml per repo', but the ADR author flags total per-repo blast radius as the cost they are least comfortable with and names an honest alternative: a SMALL number of ingress files grouped by permission profile rather than exactly one. Confirm before Story 1 freezes the template whether to go with exactly-one or grouped-by-permission-profile (the latter would supersede via ADR-0008).
• Which repo is the FIRST collapse target? .github-private is where the tooling lives but has only ~2-3 eligible thin-caller stubs (most of its Class-1 workflows carry org-private logic and don't collapse); a leaf consumer (per consumer-manifest.json) is a fuller demonstration but its collapse is a cross-repo PR dev-lead cannot author from .github-private. Confirm the target for Story 6.
• Sequencing of the required-check renames across the 8 consumer repos without a merge freeze (ADR deeper-review item 4). This epic covers only the FIRST repo's collapse + rename; the fan-out order and freeze-avoidance strategy for the remaining repos is a follow-on that needs a decision before fan-out.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #1723 to hand it to initiative-driver for auto-implementation.