Skip to content

[ADR-0007] Collapse per-role Class-1 stubs into agent-ingress.yml (pilot) #506

Closed
Closed
[ADR-0007] Collapse per-role Class-1 stubs into agent-ingress.yml (pilot)#506
Labels
dev-leadFor dev-lead agent pickup

Description

@don-petry
don-petry
opened on Oct 1, 2026

Implements ADR-0007 for this repo: collapse the 5 event-driven Class-1 agentic caller stubs into a single .github/workflows/agent-ingress.yml.

This repo is the decided pilot for the collapse (epic combsmith/.github-private#1723, story combsmith/.github-private#1729).

Collapse package — source of truth, already merged to main in .github-private:
docs/initiatives/agent-ingress-collapse-markets.md

It contains the exact agent-ingress.yml content (§3), the if: predicate provenance per job (§3a), the enumerated eligible set with justified carve-outs (§2), the old→new required-check name mapping and rollback for both half-landed states (§8), and the run-count baseline (§1).

⛔ Do not start yet — one prerequisite is open

The §4 job-level concurrency: ruling must be ACCEPTED first. The rendered ingress in §3 uses job-level concurrency: blocks, which ADR-0007's enumerated schema does not list. The Solution Architect ruled that the enumeration is exhaustive (an allowlist), so this requires its own ADR rather than an interpretation:

Until ADR-0010 is accepted, §3's content may change. Starting now risks building against a schema reading that does not survive.

Do this (once ADR-0010 is accepted)

  1. ADD .github/workflows/agent-ingress.yml with the exact content in §3 of the package.
  2. DELETE the 5 per-role stubs: dev-lead.yml, pr-auto-review.yml, pr-review.yml, pr-review-mention.yml, ci-failure-analyst.yml.
  3. Both changes in ONE commit / ONE PR (§8b) — a half-landed state is the risk this story is shaped to avoid.

Before you merge (§8a gate)

  • Re-read the branch ruleset and confirm none of the 5 roles is a required check. As of 2026-09-29 none is (§6). If one has become required, apply the atomic ruleset rename in §8d in the same PR.
  • Run the if:-as-event-filter linter ([Phase 2] Make caller_stub_freeze and validate-caller-inputs ingress-aware (job-scoped freeze + if:-as-event-filter check) .github-private#1725) over agent-ingress.yml — every job if: must be a pure event filter (§3a).
  • Confirm ADR-0010 is accepted, and that §3's concurrency blocks satisfy its collision rule: each group carries the role-name prefix and does not match any group declared by that role's pinned reusable. dev-lead centralizes concurrency inside its reusable, so this is a live case, not hypothetical.
  • Keep the 6 carve-out stubs (§2b) and both required-gate stubs (§2c) untouched.

Evidence required before this issue may close

  • One observed post-collapse run per collapsed role, linked here ([Phase 3] Collapse the first repo's Class-1 event-driven stubs into agent-ingress.yml and rename the required checks .github-private#1729 AC7). Static validator green proves the file parses and the pins resolve — it does not prove a role still fires, which is what the epic's success metric demands.
  • A fleet-monitor run in which each collapsed role classifies ALIGNED by job block, not MISSING (#1729 AC11c). This depends on the canonical agent-ingress.yml template being published under petry-projects/.github standards/workflows/ and the STUB_REGISTRY rows being activated — both prepared in §9a/§9b but not yet applied.

Known follow-ups — do NOT bundle into this PR (§5)

  • pr-review.yml pins @pr-review/stable, a deprecated bare-tier channel (a pin-contract failure independent of staleness). Repoint to pr-review/v<MAJOR>-stable once published; do not pin the immutable release directly, which bypasses staged promotion.
  • ci-failure-analyst.yml pins a bare SHA and therefore receives no promotions. Repoint to a moving ci-failure-analyst/v<MAJOR>-stable channel.

Both are preserved as-is in §3 for behaviour parity in the pilot and flagged inline with # DEFECTIVE PIN.

Maintainer update (2026-10-07) — read before continuing on PR #513

Do exactly these, in this order. Everything else on the PR is settled.

  1. Resolve the merge conflict by MERGING main (git merge origin/main, not a rebase; a depth-1 checkout cannot rebase this branch). main changed .github/workflows/ci-failure-analyst.yml (a Dependabot pin bump, e390f85) while this PR deletes it. Resolve by DELETING that stub.
  2. Carry the Dependabot bump into the ingress. In agent-ingress.yml, set the ci-failure-analyst job's uses: to ...ci-failure-analyst-reusable.yml@b58510275dd1cbbd13c0733c15265d51fd63b992 (what main now pins), keeping the # DEFECTIVE PIN — bare SHA, see §5 note. Both pinned reusables declare no concurrency, so the ADR-0010 collision rule is unaffected. Make no other change to the ingress content. It is byte-identical to the ratified §3 in petry-projects/.github-private (merged in #2039), and the collapse must be behavior-equivalent to the deleted stubs.
  3. Do NOT change any job if: or concurrency block, including the ci-failure-analyst self-exclusion and the no-PR check-run handling. Verified: the analyst's check run is named analyze, so the original guard never matched; this is pre-existing, tracked in Follow-ups from #2004 / PR #2051 and the markets ingress pilot (verifier region check, phantom Fixed replies, dispatch cancellation, dry-run slot) .github-private#2068. Decline those review threads.
  4. Accept these test/workflow fixes (they are valid): in .github/scripts/tests/agent-ingress-workflow.bats replace bare $(yq ...) assignments with run yq ... plus $status assertions (an empty result must not pass a negative-only assertion) and printf '%s\n'; tighten the pr-review-mention-workflow.bats if: assertion so the && linking the subscription group to the Bot-sender guard is actually checked; add agent-ingress.yml to the paths lists in shell-tests.yml. Because these edit tests already on this branch, the commit MUST carry a Test-Change-Justification: trailer (the #2013 test-tamper guard refused to push the previous attempt, so the work was stranded locally).
  5. PR body: replace the bare Closes #506 with Refs #506 and Refs petry-projects/.github-private#1729, and add the §8a evidence: the ruleset read at PR time (requires exactly CodeQL, SonarCloud, agent-shield / AgentShield, dependency-audit / Detect ecosystems, none of the five collapsing roles); the six §2b carve-out files unchanged; and the real output of scripts/validate-ingress-if.sh and scripts/validate-caller-inputs.sh (fetch from petry-projects/.github-private main) run on this PR's agent-ingress.yml. Do not claim they passed without running them.
  6. pr-review / review is the renamed, NON-required check (package §6); it is not a merge blocker unless it fails for a real reason in this PR.

Maintainer update 2 (2026-10-09 22:30Z) — REVERT commit e4544ef

Commit e4544ef ("restore per-run grouping for check_suite and workflow_run", made while handling CodeAnt's PR-risk summary) is wrong and must be reverted. It puts the pr-auto-review job's concurrency: back to its pre-ADR shape: a github.run_id fallback and an expression for cancel-in-progress. ADR-0010 (accepted, combsmith/.github-private#2036) FORBIDS both: no run_id, and cancel-in-progress must be a literal boolean. It also fails this PR's own bats (.github/scripts) and pr-auto-review / check-and-dispatch checks.

Do exactly this:

  1. Revert e4544ef so agent-ingress.yml is again identical to the ratified package §3 (petry-projects/.github-private docs/initiatives/agent-ingress-collapse-markets.md) except the single ci-failure-analyst uses: SHA (@b58510275dd1cbbd13c0733c15265d51fd63b992). The pr-auto-review group is pr-auto-review-ready-check-${{ ...pr-N or sha-<head_sha> }} with literal cancel-in-progress: true. Do not change any concurrency: block or if: again.
  2. Disposition CodeAnt's PR-risk summary comment (IC_kwDORntvTc8AAAABZizhfA) as invalid, with this reasoning: its concern is the head-SHA grouping for check_suite/workflow_run and the shared pr-review-enumerate slot, which is the ratified ADR-0010 / package §4b design. The deleted stub's run_id fallback is forbidden by ADR-0010. A reviewer-bot summary is NOT a change request. Do not edit the workflow to satisfy it.
  3. Do the same for any bot summary (CodeRabbit, CodeAnt, cubic) that raises the concurrency groups, the ci-failure-analyst if: guard, or no-PR handling: those are all decided and tracked in Follow-ups from #2004 / PR #2051 and the markets ingress pilot (verifier region check, phantom Fixed replies, dispatch cancellation, dry-run slot) .github-private#2068. Disposition invalid/out-of-scope; never edit the ingress for them.

Activity

  1. don-petry
    added
    dev-leadFor dev-lead agent pickup
    on Oct 4, 2026

  2. don-petry commented on Oct 4, 2026

    @don-petry
    don-petry
    on Oct 4, 2026
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #506 — [ADR-0007] Collapse per-role Class-1 stubs into agent-ingress.yml (pilot)

    Prerequisite check

    Scope

    Add .github/workflows/agent-ingress.yml with the exact package §3 content and delete the 5 per-role stubs, both in one commit (§8b).

    Implementation Checklist

    • ADD .github/workflows/agent-ingress.yml (verbatim package §3)
    • DELETE dev-lead.yml, pr-auto-review.yml, pr-review.yml, pr-review-mention.yml, ci-failure-analyst.yml
    • Leave untouched: the 6 carve-out stubs (§2b) and the 2 required-gate stubs (§2c)
    • Retarget .github/scripts/tests/pr-review-mention-workflow.bats. It currently asserts against the deleted pr-review-mention.yml. The same [Fleet Monitor] petry-projects/markets — .github/workflows/pr-review-mention.yml #307 guards (Bot-sender skip, v2-stable pin, triggers, pull-requests: write) will now be asserted against the pr-review-mention job in agent-ingress.yml.

    Tests to Write

    • New .github/scripts/tests/agent-ingress-workflow.bats, checking:
      • the ingress exists, is valid YAML and has permissions: {}
      • it has exactly the 5 role jobs, each a thin caller with a uses: pin and an if:
      • the 5 legacy stubs are gone and the carve-out/gate stubs are still present
      • each role's pin is preserved
      • the job-level concurrency groups have a role prefix and a literal cancel-in-progress
      • the pr-review fallback is enumerate, not batch
    • Retargeted pr-review-mention-workflow.bats (see above)
    • Run the #1725 validate-ingress-if.sh and validate-caller-inputs.sh guards over agent-ingress.yml

    Test Command

    bats .github/scripts/tests/*.bats plus bash .dev-lead/scripts/dev-lead-lint.sh

    Out of scope (§5 follow-ups, not bundled)

    • The pr-review/stable bare-tier pin
    • The ci-failure-analyst bare-SHA pin

  3. don-petry commented on Oct 4, 2026

    @don-petry
    don-petry
    on Oct 4, 2026
    ContributorAuthor

    Dev-Lead: Progress (in progress — not yet durable)

    Provisional. Nothing is pushed yet. The automation posts the authoritative completion record, with the PR number and head SHA, after the push. Treat the notes below as intent, not delivered results.

    Plan execution (intended)

    • Added .github/workflows/agent-ingress.yml. It is a verbatim copy of package §3, post-#2038 re-render, and I diffed it to confirm the bytes are identical.
    • Deleted dev-lead.yml, pr-auto-review.yml, pr-review.yml, pr-review-mention.yml and ci-failure-analyst.yml in the same change.
    • Retargeted .github/scripts/tests/pr-review-mention-workflow.bats to the ingress pr-review-mention job. The [Fleet Monitor] petry-projects/markets — .github/workflows/pr-review-mention.yml #307 guards are kept and tightened slightly.
    • Added .github/scripts/tests/agent-ingress-workflow.bats. It checks the collapse shape, pin parity, the trigger union, that the carve-outs are still present, and the ADR-0010 concurrency bounds, including that pr-review falls back to enumerate and not batch.

    §8a gate, run locally (provisional)

    • Ruleset on main requires CodeQL, SonarCloud, agent-shield / AgentShield and dependency-audit / Detect ecosystems. None of the 5 roles is required, so §8d does not apply.
    • ADR-0010 is accepted (.github-private#2036).
    • validate-ingress-if.sh was run against the frozen rulings TSV. Output: OK — … pure event-filter if: and bounded concurrency.
    • validate-caller-inputs.sh was run with each reusable fetched at its exact pinned ref. It reports no forwarded-input violation and no concurrency-group collision for any of the 5 jobs. That includes dev-lead, which declares no caller group.

    Notes

    • sonar-project.properties: still has S7637 resourceKey entries for the deleted dev-lead.yml and pr-auto-review.yml, plus an entry for pr-review-mention.yml. They match nothing now, so they do no harm. The ingress carries an inline NOSONAR(githubactions:S7637) marker on each channel-pinned uses:. I left this file alone to keep the PR to the §8b scope. Prune the entries in a follow-up.
    • Carve-out drift in §2b: the package classifies dependabot-rebase.yml as a pull_request_target role. The live file actually triggers on push, schedule and workflow_dispatch. It is still ineligible for the ingress and stays untouched, but the package's stated reason for the carve-out is stale.
    • Behavior changes: per package §4b, these are expected with ADR-0010.
      • pr-auto-review non-PR events now share one slot per head SHA.
      • pr-review sweeps with no PR now share the pr-review-enumerate slot, so a later sweep cancels an earlier one.
    • Not bundled, per §5: the pr-review/stable and bare-SHA ci-failure-analyst pins are preserved and marked # DEFECTIVE PIN.
    • Still needed before this issue closes:
      • one observed post-merge run per collapsed role (#1729 AC7);
      • a fleet-monitor ALIGNED run (AC11c), which depends on publishing the canonical template (§9b) and activating the STUB_REGISTRY rows (§9a).

  4. don-petry commented on Oct 4, 2026

    @don-petry
    don-petry
    on Oct 4, 2026
    ContributorAuthor

    Dev-Lead: Implementation Complete — PR #513

    The implementation for issue #506 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.

    Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.

  5. don-petry
    added 4 commits that reference this issue on Oct 7, 2026

    fix(reviews): carry main's Dependabot pin bump into ci-failure-analys…

    6165036

    feat: implement issue #506 — [ADR-0007] Collapse per-role Class-1 stu…

    c69c9a9

    fix(reviews): carry main's Dependabot pin bump into ci-failure-analys…

    5844610

    feat: implement issue #506 — [ADR-0007] Collapse per-role Class-1 stu…

    5fe86cb

  6. don-petry commented on Oct 10, 2026

    @don-petry
    don-petry
    on Oct 10, 2026
    ContributorAuthor

    AC7 progress: first live runs of the collapsed ingress (observed 2026-10-10, within minutes of the merge of #513)

    agent-ingress.yml is live on main (merged file is byte-identical to the one validated before merge). 29 Agent Ingress runs occurred in the first minutes (events: issue_comment, pull_request_review, repository_dispatch, check_run, check_suite). "Run succeeded" is not enough evidence on its own, since a skipped job also counts, so this counts only jobs that actually executed (conclusion success or failure), per role:

    Role Observed to execute? First executed job
    dev-lead Yes (11 success, 1 failure) run 38012779766, dev-lead / dispatch, event issue_comment
    pr-auto-review Yes (9 success) run 38012785893, pr-auto-review / check-and-dispatch, event pull_request_review
    pr-review Yes (1 success) run 38012646038, pr-review / review, event check_suite
    pr-review-mention Not yet (29 runs, all skipped, as expected: needs an @donpetry-bot mention or a review request) none
    ci-failure-analyst Not yet (29 runs, all skipped, as expected: needs a failing check run) none

    The one failure is dev-lead / dispatch at step "Run rebase" (run 38012532951, event issue_comment, on the #517 sync PR): the dev-lead rebase path through the shared reusable, not something the collapse introduced.

    AC7 is therefore 3 of 5. Still to observe: pr-review-mention (any owner @donpetry-bot mention on a markets PR) and ci-failure-analyst (any failing check run on a markets PR). Observing those two closes AC7. Skip/execute counts also give the AC10 kind-(a) skip data once there is more traffic.

  7. don-petry commented on Oct 10, 2026

    @don-petry
    don-petry
    on Oct 10, 2026 – with Claude
    ContributorAuthor

    AC7: observed execution per collapsed role on agent-ingress.yml (final: 4 of 5 executed, 1 accepted unobserved)

    Only jobs that executed (conclusion success/failure) count. A role whose inner job was skipped does not.

    Role Status Run (event)
    dev-lead ✅ executed dev-lead / dispatch (issue_comment, 2026-10-10 01:16Z)
    pr-auto-review ✅ executed pr-auto-review / check-and-dispatch (workflow_run, 01:16Z)
    pr-review ✅ executed pr-review / review (check_suite, 01:18Z)
    pr-review-mention ✅ executed pr-review-mention / handle-mention (pull_request: review_requested for donpetry-bot on #517, 09:54Z)
    ci-failure-analyst ⚪ not observed; accepted when the pilot was finalized The only check_run events it gets are third-party check failures. GitHub Actions' own check runs deliver none (combsmith/.github-private#2235). No third-party check failed on markets from 2026-10-10T01:16Z to 2026-10-14T02:45Z, so it billed 0 jobs. Its trigger and self-exclusion guard (#523, 9310b6e) are verified by .github/scripts/tests/agent-ingress-workflow.bats.

    Counts for the first 59 ingress runs (01:16Z to 07:04Z), by caller job:

    • dev-lead executed 21 times.
    • pr-auto-review executed 17 times.
    • pr-review executed 3 times.
    • pr-review-mention routed 19 times; its inner handle-mention skipped each time, because none of those comments mentioned the bot.

    Final, 2026-10-14. The maintainer finalized the pilot on this evidence (combsmith/.github-private#1729). The first live ci-failure-analyst run on markets depends on #2235 (a workflow_run trigger) shipping through ci-failure-analyst/v1-stable.

    Generated by Claude Code

  8. don-petry commented on Oct 12, 2026

    @don-petry
    don-petry
    on Oct 12, 2026 – with Claude
    ContributorAuthor

    Drift monitoring now covers this repo's collapsed ingress. Fleet Monitor classifies all five roles in .github/workflows/agent-ingress.yml (main at 9310b6e, after #523) as ALIGNED with the canonical template petry-projects/.github standards/workflows/agent-ingress.yml (452ea69). Run: https://github.com/petry-projects/.github-private/actions/runs/38193525415. The full evidence is on combsmith/.github-private#1729.

    Remediation is pointed at that template. It will therefore preserve this repo's current blocks, including the ci-failure-analyst/v1-stable pin and the corrected self-exclusion guard from #523, and will not revert them. Any future change to a job block here must land in the template in the same window.

    AC7 is still 4/5. ci-failure-analyst has not executed since #523, because no check run has failed on this repo yet.

    Generated by Claude Code

  9. don-petry commented on Oct 14, 2026

    @don-petry
    don-petry
    on Oct 14, 2026 – with Claude
    ContributorAuthor

    The pilot is finalized. All acceptance criteria are met, except ci-failure-analyst's live run, which the maintainer accepted unobserved (see the final AC7 evidence above). The full verdict and the measured cost are on combsmith/.github-private#1729 (closed). Closing this companion issue.

    Generated by Claude Code

  10. don-petry
    closed this as completedon Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickup

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions